参考文档编写最佳实践

这是「GSD 全景代码解析」专题的第 37 篇。在本系列中，我们将逐层拆解 Get Shit Done (GSD) 这一 56K+ stars 的 Meta-Prompting 框架，从命令系统到工作流编排，从 Agent 设计到上下文工程，带你一览上下文驱动开发的工程全貌。

---

一、参考文档的定位和价值

在前面的文章中，我们已经深入解析了 GSD 的参考文档体系——从 checkpoints.md 到 thinking-models-reasoning.md，从流程规范到认知策略。这些文档是 GSD 上下文工程的核心载体，但文档本身的质量往往比文档的内容更能决定系统的成败。

1.1 参考文档在 GSD 中的定位

在 GSD 的架构中，参考文档不是"补充说明"，而是一等公民——它们与代码、配置、工作流具有同等的重要性：

flowchart TD
    subgraph "GSD 核心资产"
        C[代码 Code] --> S[系统 System]
        W[工作流 Workflows] --> S
        A[Agent 定义] --> S
        R[参考文档 References] --> S
    end
    
    R --> C
    R --> W
    R --> A

参考文档的独特价值在于：

• 可解释性：Agent 的决策依据可以被人类审查和理解
• 可迁移性：知识从特定 Agent 中抽离，可被多个 Agent 复用
• 可演化性：不修改代码即可调整系统行为
• 可审计性：变更历史清晰可追溯

1.2 为什么参考文档质量至关重要

低质量的参考文档会产生级联失效：

文档问题	直接后果	级联影响
信息过时	Agent 遵循错误规范	产出物质量下降，调试成本激增
结构混乱	Agent 无法快速定位信息	上下文窗口被无效信息占用
描述模糊	Agent 产生歧义理解	同一规则在不同 Agent 中执行不一致
过度详细	关键信息被噪声淹没	Context Rot 加速，推理质量下降
缺少版本	新旧规范混用	系统行为不可预测

核心原则：参考文档的编写质量，直接决定了 GSD 系统整体输出的上限。

---

二、高质量参考文档的特征

2.1 清晰的结构

清晰的结构是高质量参考文档的首要特征。Agent（以及人类读者）需要在最短时间内定位所需信息。

结构清晰度的评估标准：

• [x] 文档有明确的层级结构（H1 → H2 → H3）
• [x] 每个章节有独立的职责，避免内容重叠
• [x] 使用目录（TOC）或索引帮助快速导航
• [x] 关键信息前置，细节后置（倒金字塔结构）
• [x] 使用表格、列表、代码块等视觉元素分隔不同类型的信息

GSD 推荐的文档结构模板：

# 文档标题

## 概述（Why & What）
- 文档目的
- 适用范围
- 关键术语定义

## 核心规范（How）
### 规范一：XXX
- 定义
- 执行步骤
- 示例
- 例外情况

### 规范二：XXX
...

## 附录
- 版本历史
- 相关文档链接
- 常见问题

2.2 准确的信息

准确性是参考文档的生命线。在 GSD 中，参考文档被 Agent 视为"权威来源"，任何错误都会被忠实执行。

确保准确性的措施：

措施	实施方式	频率
代码同步检查	文档中的 API、路径、配置项与代码库比对	每次代码变更后
事实核查	技术参数、版本号、限制条件与官方文档交叉验证	文档发布前
示例可运行	所有代码示例在目标环境中实际执行验证	每次更新后
多人审查	至少一名技术专家审阅	每次重大更新

2.3 适度的详细程度

参考文档的详细程度需要精确控制——太简略会导致歧义，太详尽会触发 Context Rot。

详细程度的决策框架：

flowchart TD
    A[确定信息类型] --> B{是否为关键决策依据?}
    B -->|是| C[详细描述
包含约束条件和边界情况]
    B -->|否| D{是否为常见操作?}
    D -->|是| E[简要描述
引用外部文档]
    D -->|否| F{是否为背景知识?}
    F -->|是| G[提供摘要
附深入阅读链接]
    F -->|否| H[移除或移至附录]

GSD 的上下文预算意识：

GSD 的 context-budget.md 为每份参考文档分配了明确的 Token 预算。编写者需要在这个预算内完成信息传递：

文档类型	建议预算	策略
核心流程规范	2K-4K tokens	完整但精炼
配置参考	1K-2K tokens	关键项详细，其余索引化
最佳实践指南	1.5K-3K tokens	原则 + 代表性示例
背景知识	0.5K-1K tokens	摘要 + 外部链接

2.4 可验证的内容

每一份参考文档都应该包含可验证的断言，让读者（人类或 AI）能够确认文档内容与实际情况的一致性。

可验证性的实践：

• 规范必须有检查点："所有函数必须有文档字符串" → 配套 scripts/check_docstrings.py
• 阈值必须有度量："测试覆盖率不低于 80%" → 配套 pytest --cov 命令
• 流程必须有产出物："代码审查必须通过 Checklist" → 配套 review-checklist.md

---

三、知识组织策略

3.1 分类体系

GSD 的参考文档采用三层分类体系，确保知识的有序组织和快速检索：

flowchart LR
    subgraph "第一层：按职能域"
        D1[流程规范
Process]
        D2[能力配置
Capability]
        D3[质量标准
Quality]
        D4[认知策略
Cognition]
    end
    
    subgraph "第二层：按读者角色"
        R1[Planner]
        R2[Executor]
        R3[Verifier]
        R4[Debugger]
    end
    
    subgraph "第三层：按使用场景"
        S1[新项目启动]
        S2[日常开发]
        S3[代码审查]
        S4[故障排查]
    end
    
    D1 --> R1
    D1 --> S1
    R2 --> S2
    D3 --> R3
    D3 --> S3
    D4 --> R4
    D4 --> S4

分类体系设计原则：

• [x] 单一职责：一份文档只回答一类问题
• [x] 正交性：不同维度的分类相互独立，避免交叉重复
• [x] 可扩展性：新增文档能够自然归入现有分类，不破坏结构
• [x] 可发现性：从任意文档都能导航到相关文档

3.2 依赖关系

参考文档之间存在依赖关系，需要显式管理以避免"文档碎片化"。

依赖关系的类型：

类型	说明	示例
包含（Includes）	A 文档完整包含 B 文档的内容	planning-config.md 包含 checkpoints.md 的检查点定义
引用（References）	A 文档提及 B 文档，但不依赖其内容	execution.md 引用 model-profiles.md 的模型选择建议
扩展（Extends）	A 文档在 B 文档基础上增加特定场景的规则	verification-overrides.md 扩展 verification.md 的默认策略
冲突（Overrides）	A 文档明确覆盖 B 文档的某条规则	项目级 .gsd/verification-overrides.md 覆盖全局规则

依赖关系管理工具：

# 文档元数据示例（可嵌入文档 frontmatter 或单独维护）
document:
  id: verification-overrides
  version: "2.1.0"
  
  dependencies:
    - id: verification
      version: ">=1.5.0"
      relationship: extends
    
    - id: model-profiles
      version: ">=3.0.0"
      relationship: references
  
  conflicts:
    - id: legacy-verification
      version: "<1.0.0"
      reason: 旧版验证规则与新覆盖机制不兼容

3.3 版本管理

参考文档的版本管理策略需要与代码版本管理解耦但关联。

版本号规范（Semantic Versioning for Docs）：

版本变化	触发条件	兼容性要求
Major (X.0.0)	删除规范、修改行为定义、变更核心术语	下游必须审查适配
Minor (x.Y.0)	新增规范、扩展适用场景、增加示例	向后兼容
Patch (x.y.Z)	修正错误、优化表述、更新链接	完全兼容

版本管理实践：

flowchart TD
    subgraph "文档版本生命周期"
        D1[草稿 Draft] --> D2[评审 Review]
        D2 --> D3[发布 Published]
        D3 --> D4[维护 Maintained]
        D4 --> D5[弃用 Deprecated]
        D5 --> D6[归档 Archived]
    end
    
    subgraph "状态标记"
        S1[draft: 仅内部可见]
        S2[review: 待审批]
        S3[published: 正式生效]
        S4[deprecated: 不再更新，建议迁移]
        S5[archived: 仅历史参考]
    end

版本锁定机制：

项目可以通过 .planning/gsd-config.yaml 锁定参考文档版本：

reference_docs:
  checkpoints:
    version: "2.3.1"
    auto_update: patch   # 允许自动更新 patch 版本
  
  model_profiles:
    version: "3.0.0"
    auto_update: none    # 完全锁定，手动更新

---

四、更新机制

4.1 何时更新

参考文档的更新应该由事件驱动，而非时间驱动：

触发事件	更新类型	紧急程度
代码行为变更（API、配置项、默认值）	同步更新	高（阻塞发布）
发现文档错误（事实错误、过时链接）	修正更新	高（24小时内）
新场景支持（新增语言、框架、工具）	扩展更新	中（下个迭代）
用户反馈（常见问题、理解困难点）	优化更新	低（按需排期）
架构演进（设计原则调整）	重构更新	中（需评审）

4.2 谁负责更新

参考文档的维护责任应该明确到人（或到角色）：

文档类型	主要维护者	审查者	审批者
流程规范类	Tech Lead / Architect	相关 Agent 开发者	项目负责人
能力配置类	MLOps / 平台工程师	模型评估团队	技术委员会
质量标准类	QA Lead / 测试架构师	开发团队代表	质量负责人
认知策略类	AI Researcher / Prompt Engineer	产品团队	技术负责人

4.3 更新流程

GSD 推荐采用轻量级变更流程，平衡效率与质量：

flowchart LR
    A[识别变更需求] --> B{变更类型?}
    B -->|Patch: 修正错误| C[直接提交
无需审批]
    B -->|Minor: 新增内容| D[PR 审查
1人批准]
    B -->|Major: 重构/删除| E[变更提案
RFC 评审]
    
    C --> F[更新版本号]
    D --> F
    E --> F
    F --> G[更新变更日志]
    G --> H[通知相关团队]
    H --> I[同步到 Agent 上下文]

变更日志（Changelog）模板：

## [2.1.0] - 2026-04-20

### Added
- 新增 "Python 类型注解" 检查点（CP-CODE-12）
- 补充异步函数错误处理模式示例

### Changed
- 将 "单元测试覆盖率" 阈值从 70% 提升至 80%
- 更新 `model-profiles.md` 中 Claude 3.5 的上下文窗口限制

### Deprecated
- 标记 "Legacy Gate 格式" 为弃用，将在 3.0.0 移除

### Fixed
- 修正 `execution.md` 中 Docker 构建命令的路径错误
- 更新失效的外部文档链接

---

五、文档一致性检查

5.1 自动化检查

自动化检查是保障文档一致性的第一道防线：

检查项	工具/方法	检查内容
链接有效性	markdown-link-check	所有内部/外部链接可访问
代码示例可运行	pytest / node / 容器化执行	文档中的代码片段无语法错误
术语一致性	自定义 linter（基于术语表）	关键术语使用统一表述
格式规范	markdownlint	标题层级、列表缩进、代码块标记
版本同步	自定义脚本（比对代码与文档）	文档中引用的版本号与实际一致
Token 预算	自定义脚本	文档长度未超出分配的上下文预算

GSD 文档检查流水线示例：

# .github/workflows/docs-check.yml
name: Reference Docs Check

on:
  push:
    paths:
      - 'references/**'
      - '.planning/**'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Markdown Lint
        run: npx markdownlint-cli references/**/*.md
      
      - name: Link Check
        run: npx markdown-link-check references/**/*.md
      
      - name: Terminology Check
        run: python scripts/check_terminology.py references/
      
      - name: Code Example Validation
        run: python scripts/validate_code_examples.py references/
      
      - name: Context Budget Check
        run: python scripts/check_context_budget.py references/

5.2 人工审查

自动化检查无法替代人工审查，特别是在以下方面：

• 语义准确性：代码能运行，但是否实现了文档描述的行为？
• 逻辑一致性：文档 A 和文档 B 的规则是否存在隐性冲突？
• 可读性评估：新加入的团队成员能否理解文档？
• 场景覆盖：是否遗漏了重要的边界情况？

人工审查 Checklist：

• [ ] 文档目的在开头清晰陈述
• [ ] 所有断言都有证据或示例支撑
• [ ] 示例覆盖正常路径和异常路径
• [ ] 与其他文档的交叉引用准确
• [ ] 术语使用与全局术语表一致
• [ ] 变更日志完整记录了本次修改
• [ ] 版本号按照 SemVer 规范正确递增
• [ ] 无拼写错误和语法问题
• [ ] 文档长度在上下文预算范围内
• [ ] 废弃内容有明确的迁移指引

5.3 与代码的同步

参考文档与代码的同步是最易出问题的环节。GSD 推荐以下策略：

策略一：单点真相（Single Source of Truth）

将可自动生成的内容从文档中剥离，改为从代码生成：

# scripts/generate_api_reference.py
# 从代码注释自动生成 API 参考文档

import ast
from pathlib import Path

def generate_api_docs(source_dir: Path, output_file: Path):
    """扫描源代码，提取 docstring 生成 API 参考。"""
    docs = []
    for py_file in source_dir.rglob("*.py"):
        tree = ast.parse(py_file.read_text())
        for node in ast.walk(tree):
            if isinstance(node, (ast.FunctionDef, ast.ClassDef)):
                docstring = ast.get_docstring(node)
                if docstring:
                    docs.append({
                        "name": node.name,
                        "type": "function" if isinstance(node, ast.FunctionDef) else "class",
                        "docstring": docstring,
                        "file": str(py_file.relative_to(source_dir))
                    })
    
    # 生成 markdown 输出
    output_file.write_text(render_api_reference(docs))

策略二：代码即文档（Docs as Code）

将参考文档纳入版本控制，与代码一起进行 Code Review：

project/
├── src/                    # 源代码
├── tests/                  # 测试代码
├── references/             # 参考文档（与代码同仓库）
│   ├── checkpoints.md
│   ├── gates.md
│   └── model-profiles.md
├── .planning/              # 项目级覆盖配置
│   └── gsd-config.yaml
└── scripts/                # 文档生成和检查脚本
    ├── generate_refs.py
    └── check_consistency.py

策略三：契约测试（Contract Testing）

为参考文档中的关键断言编写测试，确保文档与代码的一致性：

# tests/test_reference_contracts.py

import yaml
import pytest
from pathlib import Path

def test_checkpoints_have_implementation():
    """验证 checkpoints.md 中定义的检查点都有对应的实现。"""
    checkpoints_doc = Path("references/checkpoints.md").read_text()
    checkpoint_ids = extract_checkpoint_ids(checkpoints_doc)
    
    for cp_id in checkpoint_ids:
        impl_file = Path(f"src/checkpoints/{cp_id.lower()}.py")
        assert impl_file.exists(), f"检查点 {cp_id} 缺少实现文件"

def test_model_profiles_match_actual():
    """验证 model-profiles.md 中的模型配置与实际可用模型一致。"""
    profiles_doc = Path("references/model-profiles.md").read_text()
    doc_models = extract_model_ids(profiles_doc)
    
    actual_models = get_available_models()  # 从 API 获取
    
    assert set(doc_models) == set(actual_models), \
        f"文档模型与可用模型不一致: {set(doc_models) ^ set(actual_models)}"

---

六、参考文档编写最佳实践清单

基于前面的讨论，以下是 GSD 参考文档编写的完整最佳实践清单：

结构设计

• [x] 采用标准模板：每份文档遵循统一的结构模板（概述 → 核心规范 → 附录）
• [x] 层级不超过三级：H1 → H2 → H3，避免过深的嵌套影响可读性
• [x] 目录导航：长文档（>2KB）必须提供目录或索引
• [x] 信息前置：关键结论和决策依据放在章节开头，细节和示例后置

内容质量

• [x] 单一职责：一份文档只解决一类问题，避免"万能文档"
• [x] 可验证断言：每条规范都有对应的检查点或测试可以验证
• [x] 示例驱动：抽象规则必须配合具体示例，示例覆盖正常和异常路径
• [x] 术语统一：关键术语在文档开头定义，全文保持一致使用
• [x] 上下文预算：文档长度控制在分配的 Token 预算内，超出时拆分为多份文档

组织管理

• [x] 三层分类：按职能域 → 读者角色 → 使用场景组织文档
• [x] 显式依赖：在文档元数据中声明依赖关系和版本要求
• [x] 版本管理：采用 SemVer 规范，变更必须记录变更日志
• [x] 生命周期状态：每份文档标记当前状态（草稿 / 发布 / 维护 / 弃用 / 归档）

更新维护

• [x] 事件驱动：文档更新由代码变更、用户反馈等事件触发，而非固定周期
• [x] 责任明确：每份文档有明确的主维护者和审查者
• [x] 分级审批：Patch 级直接提交，Minor 级 PR 审查，Major 级 RFC 评审
• [x] 变更通知：重大变更主动通知相关团队和 Agent 维护者

一致性保障

• [x] 自动化检查：集成链接检查、代码验证、术语一致性、格式规范等自动化检查
• [x] 人工审查：所有变更至少经过一人审查，重大变更需多角色参与
• [x] 代码同步：优先使用代码生成文档，文档与代码同仓库管理
• [x] 契约测试：为关键文档断言编写测试，确保文档与实现的一致性

可访问性

• [x] 读者导向：根据目标读者（Planner / Executor / Verifier）调整详细程度和术语深度
• [x] 交叉引用：相关文档之间建立链接，支持导航和关联阅读
• [x] 快速定位：使用锚点、关键词索引帮助读者快速定位特定信息
• [x] 多格式支持：核心文档同时维护 Markdown（人类阅读）和结构化数据（Agent 消费）两种格式

---

七、小结

本文系统总结了 GSD 参考文档的编写最佳实践：

1. 定位与价值：参考文档是 GSD 的一等公民，其质量直接决定系统输出的上限
2. 高质量特征：清晰的结构、准确的信息、适度的详细程度、可验证的内容
3. 知识组织：三层分类体系、显式依赖管理、SemVer 版本策略
4. 更新机制：事件驱动、责任明确、分级审批的轻量级变更流程
5. 一致性保障：自动化检查 + 人工审查 + 代码同步的三层防护体系

参考文档的编写不是一次性工作，而是持续演化的知识工程。在 GSD 的实践中，最好的参考文档往往是那些经历了多次迭代、被多个 Agent 实际验证、并根据反馈不断优化的文档。

核心洞察：优秀的参考文档不是"写出来"的，而是"用出来"的——只有在实际执行中不断打磨，文档才能真正成为 Agent 和人类之间的可靠契约。

---

下一篇预告： 第 38 篇《SDK 架构总览》——全面解析 GSD SDK 的整体架构设计、核心模块划分、接口定义规范以及开发者集成指南，带你从使用者视角转向开发者视角，深入理解 GSD 的可扩展性设计。