Back to Details

living-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Living Documentation

活文档

Spec guides generation. Code changes update spec.
规范指导生成，代码变更更新规范。

When Triggered

触发时机

  • Modifying code that implements behavior defined in 
    requirements.md
  • Changing architecture/interfaces described in 
    design.md
  • Discovering edge cases or patterns not yet documented
  • 修改实现了
    requirements.md
    中定义的行为的代码时
  • 变更
    design.md
    中描述的架构/接口时
  • 发现尚未记录的边缘情况或模式时

Lifecycle

生命周期

PhaseAuthorityAction
GenerateSpec → CodeFollow spec as contract
ModifyCode → SpecUpdate spec to reflect code
阶段主导方操作
生成阶段规范 → 代码遵循规范作为契约
修改阶段代码 → 规范更新规范以反映代码实际情况

Sync Protocol

同步流程

After completing code change:
  1. Identify Affected Specs
    • Check task's 
      _writes:
      manifest
    • Map to spec sections: which requirements/design does this touch?
  2. Update Spec Content
    • Remove obsolete descriptions
    • Document actual implementation approach
    • Add discovered edge cases as new ACs
    • Keep spec readable without code
  3. Add Traceability
    markdown
    <!-- impl: path/to/file.ts#FunctionName -->
  4. Commit Together
    • Spec changes in same commit as code changes
完成代码变更后：
  1. 识别受影响的规范
    • 检查任务的
      _writes:
      清单
    • 映射到规范章节：此变更涉及哪些需求/设计内容？
  2. 更新规范内容
    • 删除过时的描述
    • 记录实际的实现方案
    • 将发现的边缘情况作为新的验收标准（AC）添加
    • 保持规范无需查看代码即可理解
  3. 添加可追踪性
    markdown
    <!-- impl: path/to/file.ts#FunctionName -->
  4. 一同提交
    • 规范变更与代码变更提交到同一个提交记录中

What to Update

更新内容对照表

Code ChangeSpec Update
New function/moduleAdd to 
design.md#Components
Behavior changeUpdate ACs in 
requirements.md
Edge case handlingAdd AC with EARS format
Architecture decisionDocument rationale in 
design.md
Removed featureDelete from both specs
代码变更类型规范更新内容
新增函数/模块添加到
design.md#Components
中
行为变更更新
requirements.md
中的验收标准
边缘情况处理以EARS格式添加验收标准
架构决策在
design.md
中记录决策依据
移除功能从两个规范文件中删除对应内容

Quality Check

质量检查

  • Spec describes current reality, not original plan
  • No stale sections left
  • New reader understands system from spec alone
  • Traceability links added
  • 规范描述当前实际情况，而非最初计划
  • 无过时章节遗留
  • 新读者仅通过规范即可理解系统
  • 已添加可追踪性链接