DSH DIY 全仓文档写作与协作标准 (Spec Coding Guide)

August 16, 2026 · View on GitHub

在使用 Spec Coding 作为新一代 AI-Native 开发范式下，代码不再是第一真实来源（Truth），Markdown 规范文档才是主程序的内核代码只是根据 Spec 翻译的产物。

为了防止多轮对话后模型产生记忆漂移，或交接给不同模型后环境脏乱，特制定以下文档规范。

一、 结构严密，没有散兵游勇

任何一个新的功能项目，其专属目录下必定要有且只有以下 4 份骨干 Spec 文档：

  1. 1_REQUIREMENTS.md（我需要它做什么）
  2. 2_ARCHITECTURE.md（在什么技术约束内去做）
  3. 3_TASKS.md（分解了多少步骤，做到了哪里）
  4. 4_VERIFICATION.md（怎么证明代码是对的 / 验收测试指标）

二、 文档的“无情”重构原则（保持洁净）

为了对抗冗杂度并节约上下文 Token，维护文档时请保持：

  1. 不要留存历史修订痕迹：文档只需描述现态 (Current State)。如果你把 V1 改成了 V2，直接删掉 V1 的文字。不需要类似于“（已废弃）这里最初是用 WebView 的...”的注释。历史让 Git 记录，不污染 Spec。
  2. 拒绝流水帐：结构化、大纲化、子弹块化。
  3. 消除术语歧义 (Glossary Sync)：名词必须强对应，不允许前文写“控制器”，后文写“Orchestrator”。

三、 对 Agent（AI 助手）的约束铁律

  1. 谋定后动：当人类发来“我想要一个 XYZ 功能”时。Agent 绝对不能直接上手贴代码。Agent 的第一步，必然是去修改相关的 REQUIREMENTS 或 ARCHITECTURE 文档，追加 TASKS 的动作树。
  2. 反馈闭环：每当一个 .cs / .js / .rs 代码文件的确切实现写定且走通，立刻切去修改 3_TASKS.md 大纲并打钩 [x]。

四、人在环的协作阶段

每个可交付变更必须在 3_TASKS.md 中按以下顺序拆分为独立任务；阶段之间由人类明确决定是否继续，以便切换负责的 Agent 或模型。

  1. 规划（Plan）：规划 Agent 对齐四份 Spec，产出范围、实施顺序、风险、验证证据和回退方案。此阶段不得改动产品代码、构建脚本或发布配置。
  2. 人工批准（Approve）：人类审阅规划并明确授权开始执行。未批准的规划不得被执行 Agent 自动推进。
  3. 执行（Execute）：执行 Agent 只处理已批准的、边界明确的单个任务，运行该任务规定的自动检查；每完成一个实现任务立即更新其状态。
  4. 验收（Verify）：验收 Agent 根据 4_VERIFICATION.md 独立检查实现、构建产物和证据，记录通过项、失败项与未覆盖风险。验收通过后仍须由人类决定是否发布。

规划和验收宜分配给能力更强的模型；执行阶段可分配给普通模型。模型选择权和每个阶段的继续权始终属于人类。

Spec Document == Database State。 必须确保它随时同步、清晰与高度整洁。