documentation

文档技能

版本： 1.0 来源： 文档标准

不容妥协的文档标准。文档应与代码一同交付，而不是事后补上。

问题

AI Agent 会把文档视为可选项——代码写好了，但变更日志、功能规格和模块文档却被跳过，或是事后才生成。每次会话都假设下一次会话会“直接看代码”，但没有文档，会话之间的上下文就会消失。这些标准确保每项变更都附带文档，让 Agent 和人类能够接续上一次会话的工作。

使用方式

• 构建者： 开始开发功能前，阅读 ## Builder Checklist。将文档工作与代码一并规划，而不是事后补上。
• 重构者： 使用 ## Enforced Rules 查找文档缺漏。阅读叙述性章节，了解格式和结构指南。
• 两者： 叙述性章节是权威标准。检查清单和规则表是对相同内容的精简呈现。

---

核心原则

1. 文档与代码一同交付 — 每项功能都包含更新后的文档
2. 单一事实来源 — /Documentation 文件夹是唯一参考来源
3. Agent 连续性 — 文档帮助 Agent 理解上下文
4. 持续更新的文档 — 保持文档最新，避免过时

---

文档反馈循环

Agent reads /Documentation → Understands context → Does work → Updates /Documentation → Next agent reads

更新 /Documentation 时，你是在帮助下一个 Agent（包括未来的自己）理解项目。

---

语义化版本控制（SemVer）

格式

MAJOR.MINOR.PATCH

类型	何时递增	示例
MAJOR	对行为、输入、输出或结构进行不兼容变更	API 合约变更、移除功能、重命名文件
MINOR	新增用户可见的功能或工作流	新功能、新端点、新命令
PATCH	缺陷修复、小幅改进，不增加新功能	修正拼写错误、提升性能、调整格式

版本命名规范

vX.Y.Z — [Program] / [Module]: [Feature]

组成部分	类型	描述
Program	名词	主要领域（例如，Kitchen、Garden）
Module	名词短语	功能领域（例如，Planning、Tasks）
Feature	动词／名词短语	具体操作（例如，Create meal plan）

示例：

• v0.2.0 — Kitchen / Planning: Create weekly meal plan
• v0.3.0 — Garden / Tasks: Track watering routine
• v0.4.1 — Kitchen / Planning: Fix missing quantities

范围标签（便于机器处理）

scope: program.module.feature

示例：

• scope: kitchen.planning.generate-shopping-list
• scope: garden.tasks.track-watering-routine

兼容性规则

出现以下任一项不兼容变更时，递增 MAJOR：

• 文件／文件夹路径或命名规范
• 必需输入或工作流顺序
• 输出合约（必需章节、模板）

以下情况递增 MINOR：

• 新增工作流结果
• 模块获得端到端功能
• 文档新增不具破坏性的章节

以下情况递增 PATCH：

• 缺陷修复、格式调整、拼写错误
• 不改变合约的性能改进

---

文件夹结构

/Documentation/
  project-roadmap.md       # Living plan + progress tracking
  architecture.md          # System design overview
  changelog.md             # Version history (Keep a Changelog)
  features/
    [program-name]/
      [module-name]/
        _[module-name].md  # Module explainer (underscore sorts first)
        feature-name-1.md  # Feature specification
        feature-name-2.md  # Feature specification

关键文件

文件	用途
project-roadmap.md	战略路线图（v0.1 → v1.0）、里程碑
architecture.md	系统设计、数据流、关键组件
changelog.md	版本历史（Keep a Changelog 格式）
_*.md (module)	模块概览、功能列表、依赖项
*.md (feature)	用户故事、验收标准、技术说明

---

根目录 README

README 是一座桥梁，而不是宣传册。它的作用是帮助读者从“这是什么？”走到“我已经让它运行起来，并且知道如何使用它”。如果读者从头到尾读完 README 仍无法让项目正常运行，失败的是 README，而不是读者。

两类读者，一份文档

• “直接运行”型读者——希望在 5 分钟内得到可用结果。他们会阅读标题、快速开始和安装设置。
• “理解原理”型读者——希望了解事情为何能正常运行。他们仍然希望先看快速开始——先看到实际运行的效果，更容易理解。

下方的章节顺序兼顾这两类读者。略读的读者可以提前离开，并已获得可用结果。深入阅读的读者则可以继续了解结构和配置。

章节顺序

#	章节	目的
1	标题 + 一句话介绍	在 10 秒内回答“这和我有关吗？”
2	快速开始	在 ≤5 分钟内首次成功运行
3	功能与非功能说明	建立正确的预期
4	先决条件	如实列出依赖项
5	安装设置	完整设置环境并进行验证
6	用法	通过实际示例介绍核心工作流
7	项目结构	说明各部分的位置及原因
8	配置	说明可自定义的内容及方法
9	故障排除	常见故障及修复方法
10	贡献	如何提供帮助，以及从何处着手

**为何采用此顺序：**第 1–2 节是吸引读者继续阅读的关键（在这里受挫，读者就会离开）。第 3–5 节是基础（跳过这些内容，读者之后就会迷失方向）。第 6–8 节是参考内容（按需查阅）。第 9–10 节是安全网（用于处理故障或帮助想要贡献的人）。

核心原则

1. 成功标志——每条说明都应以读者应该看到的结果结束。单独写 npm run db:migrate 并不完整。请补充：你应该看到：Migrations complete. 12 tables created.
2. 如实列出先决条件——列出确切的版本，并提供检查命令。隐藏的要求会变成支持工单。
3. 具体优于抽象——使用项目中的实际名称和路径，而不是 {placeholder} 模式。
4. 解释术语——如果某个术语会让读者停下来搜索，就立即解释。
5. 故障情况——在文中说明常见故障（> **如果看到 [error]：** [原因]。修复方法：[操作步骤]），其余情况放到“故障排除”部分。
6. 便于浏览的结构——使用标题、代码块、表格和简短段落，绝不堆砌大段文字。

完整指南： references/readme-guide.md——逐节说明，附有优劣示例和反模式 模板： assets/readme-template.md——包含全部 10 个章节，可直接复制使用

---

功能规格

必需内容

每个功能文件都必须包含：

1. 一句话描述
2. 模块引用和状态
3. 用户故事（作为 / 我想要 / 以便）
4. 概述和基本场景
5. 验收标准（可测试的复选框）
6. 数据模型（如适用）
7. 附带标准检查清单的技术说明
8. 待解决问题
9. 相关功能

使用 assets/feature-template.md 中的模板。每个功能文件都必须包含：一句话描述、模块引用 + 状态、用户故事（作为 / 想要 / 以便）、带有基本场景的概述、可测试的验收标准、数据模型（如适用）、附带标准检查清单的技术说明、待解决问题和相关功能。

---

模块说明

使用 assets/module-template.md 中的模板。每份模块说明都包含：一句话描述、程序引用 + 状态数量、概述、功能表（含状态 + 链接）、依赖项和架构说明。

---

更新日志格式

遵循 Keep a Changelog 格式。使用 assets/changelog-template.md 中的模板。

变更类型

类型	说明
Added	新增功能
Changed	对现有功能的更改
Deprecated	即将移除的功能
Removed	已移除的功能
Fixed	Bug 修复
Security	漏洞修复

---

状态格式

上下文	格式	值
project-roadmap.md	表情符号	⏳ Planned，🔄 In Progress，✅ Complete，🚫 Blocked
功能/模块文件	文本	Planned，In Progress，Complete
待解决问题	文本	Open，Resolved

**理由：**路线图中使用表情符号，便于快速浏览。功能文件中使用文本，便于 AI 解析。

---

构建者检查清单

在编写受此技能规范约束的代码之前，请根据这些约束检查你的计划。构建者在开始工作前阅读本节；重构者则使用「强制规则」表和完整说明。

在将文档视为完成之前：

功能文件

• 包含一行描述
• 状态为最新且准确
• 用户故事遵循 As/Want/So 格式
• 验收标准为可测试的复选框
• 标准检查清单已完成
• 已处理或记录待解决问题

模块说明文档

• 功能表为最新
• 状态计数准确
• 已列出依赖项

项目级别

• 路线图反映当前状态
• 已更新发布版本的变更日志
• 架构文档为最新

---

强制规则

目前尚未通过确定性检查工具强制执行文档标准。添加文档检查器后，请在此处以及检查器的 RULE_SKILLS 注册表中登记规则。

规则 ID	严重程度	检查内容
—	—	暂无自动化规则——所有检查均通过上方的「构建者检查清单」手动完成

---

参考资料

• references/semver-guide.md — 完整的语义化版本控制指南
• references/changelog-format.md — Keep a Changelog 格式
• references/feature-spec-guide.md — 功能规范编写指南
• references/readme-guide.md — 根 README 编写指南

资源文件

• assets/feature-template.md — 功能文件模板
• assets/module-template.md — 模块说明文档模板
• assets/changelog-template.md — 变更日志模板
• assets/readme-template.md — README 模板

脚本

• scripts/validate_docs.py — 验证文档结构
• scripts/generate_feature.py — 根据模板生成功能文件