doc-driven-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Document-Driven Development Guide

文档驱动开发指南

Core Principle: Documentation first, code follows, tests verify, documentation closes. All features must follow the documentation-driven development cycle.

This skill ensures proper documentation workflow, preventing common mistakes like code without Story updates or incomplete feature tracking.

Project Documentation Structure:

Stories:
```
stories/
```
(version-based feature tracking)
Design Docs:
```
docs/design/
```
(architecture and decisions)
API Docs:
```
docs/
```
(user-facing documentation)
Changelog:
```
CHANGELOG.md
```
(session-based updates)
Roadmap:
```
ROADMAP.md
```
(version planning)

Related Skills:

```
solana-sdk-zig
```
: Rust source references and test compatibility
```
zig-0.15
```
: Zig API usage
```
zig-memory
```
: Memory management patterns

核心原则：文档先行，代码随后，测试验证，文档收尾。所有功能必须遵循文档驱动的开发周期。

该Skill可确保规范的文档工作流，避免出现代码已更新但Story未同步、功能跟踪不完整等常见问题。

项目文档结构:

Stories:
```
stories/
```
（基于版本的功能跟踪）
设计文档:
```
docs/design/
```
（架构与决策记录）
API文档:
```
docs/
```
（面向用户的文档）
更新日志:
```
CHANGELOG.md
```
（基于开发会话的更新记录）
路线图:
```
ROADMAP.md
```
（版本规划）

相关Skills:

```
solana-sdk-zig
```
：Rust源码参考与测试兼容性
```
zig-0.15
```
：Zig API使用
```
zig-memory
```
：内存管理模式

References

参考资料

Detailed templates and examples:

Document	Path	Content
CHANGELOG Template	`references/changelog-template.md`	Session entry format, version release format

详细模板与示例:

文档	路径	内容
CHANGELOG模板	`references/changelog-template.md`	开发会话记录格式、版本发布格式

Development Cycle (Required)

开发周期（强制要求）

Every feature/change MUST follow this workflow:

┌─────────────────────────────────────────────────────────────────┐
│  1. Documentation Preparation                                    │
│     ├── Update/create design docs (docs/design/)                │
│     ├── Update ROADMAP.md (if new feature)                      │
│     └── Create/Update Story file (stories/)                     │
├─────────────────────────────────────────────────────────────────┤
│  2. Coding Phase                                                 │
│     ├── Implement feature code                                   │
│     ├── Add code comments with Rust source references           │
│     ├── Sync update docs/ (REQUIRED!)                           │
│     └── Update Story checkboxes as features complete            │
├─────────────────────────────────────────────────────────────────┤
│  3. Testing Phase                                                │
│     ├── Unit tests (zig test src/xxx.zig)                       │
│     ├── Integration tests (zig build test)                      │
│     └── All tests MUST pass before proceeding                   │
├─────────────────────────────────────────────────────────────────┤
│  4. Documentation Finalization                                   │
│     ├── Update CHANGELOG.md with session entry                  │
│     ├── Update Story status (⏳ → ✅) if ALL complete           │
│     └── Update README.md (if user-visible changes)              │
└─────────────────────────────────────────────────────────────────┘

每个功能/变更必须遵循以下工作流:

┌─────────────────────────────────────────────────────────────────┐
│  1. 文档准备阶段                                                │
│     ├── 更新/创建设计文档（docs/design/）                │
│     ├── 更新ROADMAP.md（若为新功能）                      │
│     └── 创建/更新Story文件（stories/）                     │
├─────────────────────────────────────────────────────────────────┤
│  2. 编码阶段                                                 │
│     ├── 实现功能代码                                   │
│     ├── 添加带有Rust源码参考的代码注释           │
│     ├── 同步更新docs/（强制要求！）                           │
│     └── 随着功能完成更新Story复选框            │
├─────────────────────────────────────────────────────────────────┤
│  3. 测试阶段                                                │
│     ├── 单元测试（zig test src/xxx.zig）                       │
│     ├── 集成测试（zig build test）                      │
│     └── 所有测试必须通过后才能继续                   │
├─────────────────────────────────────────────────────────────────┤
│  4. 文档收尾阶段                                   │
│     ├── 在CHANGELOG.md中添加开发会话记录                  │
│     ├── 更新Story状态（⏳ → ✅）当所有任务完成时           │
│     └── 更新README.md（若有面向用户的变更）              │
└─────────────────────────────────────────────────────────────────┘

Story File Format

Story文件格式

Directory Structure

目录结构

stories/
├── v0.1.0-core-types.md
├── v0.2.0-serialization.md
├── v0.29.0-program-sdk-completion.md
├── v1.0.0-sdk-restructure.md
├── v2.0.0-spl-token.md
└── v2.2.0-stake-program.md

stories/
├── v0.1.0-core-types.md
├── v0.2.0-serialization.md
├── v0.29.0-program-sdk-completion.md
├── v1.0.0-sdk-restructure.md
├── v2.0.0-spl-token.md
└── v2.2.0-stake-program.md

Story Template

Story模板

markdown

undefined

markdown

undefined

Story: vX.Y.Z Feature Name

Story: vX.Y.Z 功能名称

Brief description (one sentence)

简短描述（一句话）

Goals

目标

Goal 1
Goal 2

目标1
目标2

Acceptance Criteria

验收标准

module_name.zig

Integration

集成

Completion Status

完成状态

Start date: YYYY-MM-DD
Completion date: YYYY-MM-DD
Status: ⏳ In Progress / ✅ Completed

undefined

开始日期: YYYY-MM-DD
完成日期: YYYY-MM-DD
状态: ⏳ 进行中 / ✅ 已完成

undefined

Status Markers

状态标记

Marker	Location	Meaning	When to Use
`⏳`	ROADMAP, stories, docs	Pending/In Progress	Feature started but not complete
`🔨`	ROADMAP, stories	Currently Working	Active development this session
`✅`	ROADMAP, stories	Completed	ALL checkboxes are `[x]`
`[ ]`	stories, docs	Unchecked task	Task not yet done
`[x]`	stories, docs	Completed task	Task finished and verified
`TODO`	Code comments	To implement	Future work
`FIXME`	Code comments	To fix	Known issue
`XXX`	Code comments	Attention needed	Needs review

标记	位置	含义	使用场景
`⏳`	ROADMAP、stories、docs	待处理/进行中	功能已启动但未完成
`🔨`	ROADMAP、stories	当前开发中	本次会话正在开发的功能
`✅`	ROADMAP、stories	已完成	所有复选框均为 `[x]`
`[ ]`	stories、docs	未完成任务	任务尚未开始
`[x]`	stories、docs	已完成任务	任务已完成并验证
`TODO`	代码注释	待实现	未来需完成的工作
`FIXME`	代码注释	待修复	已知问题
`XXX`	代码注释	需要关注	需要评审

Story Sync Rules (Critical)

Story同步规则（关键）

Timing	Required Action
Start new version	Create Story file, list ALL acceptance criteria
Complete single feature	Change `[ ]` to `[x]` for that feature
Complete entire version	ONLY update status to ✅ when ALL `[ ]` are `[x]`
Add new feature	Add acceptance criteria to Story
Before version release	Ensure all `[ ]` are `[x]`

时机	要求操作
启动新版本	创建Story文件，列出所有验收标准
完成单个功能	将该功能的 `[ ]` 改为 `[x]`
完成整个版本	仅当所有 `[ ]` 变为 `[x]` 时，才将状态更新为✅
添加新功能	在Story中添加验收标准
版本发布前	确保所有 `[ ]` 均已变为 `[x]`

Common Mistakes

常见错误示例

markdown

undefined

markdown

undefined

❌ WRONG - Marking complete with unchecked items

❌ 错误 - 仍有未勾选项却标记为完成

Completion Status

完成状态

Status: ✅ Completed

状态: ✅ 已完成

Acceptance Criteria

验收标准

Feature 1
Feature 2 ← Still unchecked!

功能1
功能2 ← 仍未勾选！

✅ CORRECT - All items checked before marking complete

✅ 正确 - 所有项勾选后再标记完成

Completion Status

完成状态

Status: ✅ Completed

状态: ✅ 已完成

Acceptance Criteria

验收标准

Feature 1
Feature 2

undefined

功能1
功能2

undefined

Validation Commands

验证命令

bash

undefined

bash

undefined

Check uncompleted tasks in stories/

检查stories/中未完成的任务

grep -rn "[ ]" stories/

Check story status markers

检查Story状态标记

grep -rn "Status:" stories/

Check ROADMAP status

检查ROADMAP状态

grep -n "⏳|✅" ROADMAP.md

Full scan (one command)

全面扫描（单命令）

Verify Story-ROADMAP consistency

验证Story与ROADMAP的一致性

echo "=== ROADMAP ===" && grep -n "✅|⏳" ROADMAP.md echo "=== Stories ===" && grep -rn "Status:" stories/

undefined

echo "=== ROADMAP ===" && grep -n "✅|⏳" ROADMAP.md echo "=== Stories ===" && grep -rn "Status:" stories/

undefined

Completion Criteria

完成标准

A version can ONLY be marked as "completed" when ALL conditions are met:

Criterion	Verification
Core functionality 100%	All `[ ]` are `[x]` in Story
All tests passing	`zig build test` shows 0 failures
No memory leaks	Testing allocator reports no leaks
Documentation synced	CHANGELOG updated, Story status correct
Issues documented	Any deferred items noted

版本仅当满足以下所有条件时，才可标记为“已完成”:

标准	验证方式
核心功能100%完成	Story中所有 `[ ]` 均变为 `[x]`
所有测试通过	`zig build test` 显示0失败
无内存泄漏	测试分配器报告无泄漏
文档已同步	CHANGELOG已更新，Story状态正确
问题已记录	所有延期项均已标注

Refactoring Rules

重构规则

When doing architecture changes, follow this strict order:

Phase 1: Refactor Existing Code
    ├── Move/reorganize file structure
    ├── Update import paths and dependencies
    ├── Run tests: zig build test
    └── Ensure all existing tests 100% pass
    └── Commit: "refactor: reorganize project structure"

Phase 2: Verify Refactoring Complete
    ├── Compilation passes, no errors
    ├── All original tests pass
    ├── Functionality unchanged from before
    └── DO NOT proceed until 100% verified

Phase 3: Add New Features (ONLY after Phase 2)
    ├── Add new modules/files
    ├── Implement new features
    ├── Add tests for new features
    └── Commit: "feat: add new feature"

进行架构变更时，必须遵循以下严格顺序:

阶段1：重构现有代码
    ├── 移动/重组文件结构
    ├── 更新导入路径与依赖
    ├── 运行测试: zig build test
    └── 确保所有现有测试100%通过
    └── 提交: "refactor: reorganize project structure"

阶段2：验证重构完成
    ├── 编译通过，无错误
    ├── 所有原有测试通过
    ├── 功能与重构前一致
    └── 未100%验证完成前不得继续

阶段3：添加新功能（仅在阶段2完成后）
    ├── 添加新模块/文件
    ├── 实现新功能
    ├── 为新功能添加测试
    └── 提交: "feat: add new feature"

Prohibited Refactoring Behaviors

禁止的重构行为

Behavior	Status
Mix refactoring + new features in one commit	❌ PROHIBITED
Start new features before refactoring tests pass	❌ PROHIBITED
Skip test verification between phases	❌ PROHIBITED
Combine Phase 1 and Phase 3 in same commit	❌ PROHIBITED

行为	状态
单次提交中混合重构与新功能	❌ 禁止
重构测试通过前启动新功能	❌ 禁止
跳过阶段间的测试验证	❌ 禁止
阶段1与阶段3合并到同一提交	❌ 禁止

CHANGELOG Format

CHANGELOG格式

See:
references/changelog-template.md
for complete templates.

参考: 完整模板请查看
references/changelog-template.md
。

Session Entry (Daily Work)

开发会话记录（日常工作）

markdown

undefined

markdown

undefined

Session YYYY-MM-DD-NNN

Date: YYYY-MM-DD Goal: Brief description of session goal

日期: YYYY-MM-DD 目标: 会话目标简短描述

Completed Work

已完成工作

Implemented feature X
Fixed bug in Y
Added tests for Z

实现功能X
修复Y中的bug
为Z添加测试

Test Results

测试结果

Unit tests: 305 tests passed
Integration tests: 53 vectors verified

单元测试: 305个测试通过
集成测试: 53个用例验证通过

Next Steps

下一步计划

Task for next session

undefined

下一会话任务

undefined

Version Release Entry

版本发布记录

markdown

undefined

markdown

undefined

[vX.Y.Z] - YYYY-MM-DD

Added

新增

New feature 1
New feature 2

新功能1
新功能2

Changed

变更

Modified behavior 1

修改行为1

Fixed

修复

Bug fix 1

undefined

Bug修复1

undefined

Test Requirements

测试要求

All code changes MUST pass tests before commit:

bash

undefined

所有代码变更必须通过测试后才能提交:

bash

undefined

Run full test suite

运行完整测试套件

./solana-zig/zig build test --summary all

Or run SDK tests

或运行SDK测试

cd sdk && ../solana-zig/zig build test --summary all

undefined

cd sdk && ../solana-zig/zig build test --summary all

undefined

On Test Failure

测试失败时的处理

Situation	Action
Test fails	Fix immediately, do NOT commit
Cannot fix quickly	Revert changes, investigate
Need help	Ask before committing broken code

Critical:

zig build test

must 100% pass before

git commit

场景	操作
测试失败	立即修复，禁止提交
无法快速修复	回滚变更，排查问题
需要协助	提交有问题的代码前先咨询他人

关键要求:

zig build test

必须100%通过才能执行

git commit

。

Common Error Scenarios

常见错误场景

Error	Cause	Fix
Story says ✅ but has `[ ]`	Premature completion	Uncheck ✅, complete remaining items
ROADMAP and Story disagree	Sync issue	Run validation commands, align status
Code complete, Story unchanged	Forgot to update	Update Story checkboxes immediately
Tests fail after "complete"	Incomplete verification	Never mark complete without test pass

错误	原因	修复方案
Story显示✅但仍有 `[ ]`	过早标记完成	取消✅标记，完成剩余项
ROADMAP与Story状态不一致	同步问题	运行验证命令，统一状态
代码已完成但Story未更新	忘记更新Story	立即更新Story复选框
标记“完成”后测试失败	验证不完整	未通过测试绝不标记完成

Verification Checklist

验证清单

Before marking any version complete:

```
grep -rn "\[ \]" stories/vX.Y.Z-*.md
```
returns nothing
```
zig build test
```
shows 100% pass
CHANGELOG.md has session entry
Story status updated (⏳ → ✅)
ROADMAP.md version marked ✅

标记任何版本为完成前，请检查:

```
grep -rn "\[ \]" stories/vX.Y.Z-*.md
```
无返回结果
```
zig build test
```
显示100%通过
CHANGELOG.md已添加会话记录
Story状态已更新（⏳ → ✅）
ROADMAP.md中版本已标记为✅

Prohibited Actions

禁止行为

❌ Code complete but Story not updated
❌ Story marked ✅ but code not implemented
❌ Skip Story and develop directly
❌ Release version with
[ ]
remaining
❌ Mark Story ✅ when partial features complete
❌ Commit code that fails tests
❌ Mix refactoring and new features in one commit

❌ 代码已完成但Story未更新
❌ Story标记为✅但代码未实现
❌ 跳过Story直接开发
❌ 仍有
[ ]
项时发布版本
❌ 仅完成部分功能就标记Story为✅
❌ 提交测试失败的代码
❌ 单次提交中混合重构与新功能