Back to Details

documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Skill

文档编写规范

Version: 1.0 Source: Documentation Standards
Non-negotiable documentation standards. Documentation ships with code, not after it.
版本: 1.0 来源: 文档编写标准
不可妥协的文档编写标准：文档需随代码一同交付，而非滞后于代码。

Core Principles

核心原则

  1. Documentation Ships with Code — Every feature includes updated documentation
  2. Single Source of Truth — 
    /Documentation
    folder is THE reference
  3. Agent Continuity — Documentation enables agents to understand context
  4. Living Documents — Keep documentation current, not stale
  1. 文档随代码交付 — 每个功能都需包含更新后的文档
  2. 单一可信源 — 
    /Documentation
    文件夹是唯一参考依据
  3. Agent 上下文连续性 — 文档需能让Agent理解上下文
  4. 活文档 — 保持文档的时效性，避免过时

The Documentation Feedback Loop

文档反馈循环

Agent reads /Documentation → Understands context → Does work → Updates /Documentation → Next agent reads
When you update 
/Documentation
, you're helping the next agent (including future you) understand the project.
Agent reads /Documentation → Understands context → Does work → Updates /Documentation → Next agent reads
当你更新
/Documentation
时，你是在帮助下一个Agent（包括未来的你自己）理解项目。

Semantic Versioning (SemVer)

语义化版本控制（SemVer）

Format

格式

MAJOR.MINOR.PATCH
TypeWhen to BumpExamples
MAJORBreaking change to behavior, inputs, outputs, or structureAPI contract changes, removed features, renamed files
MINORNew user-visible capability or workflowNew feature, new endpoint, new command
PATCHBug fixes, small improvements, no new capabilityFix typo, improve performance, formatting
MAJOR.MINOR.PATCH
类型何时升级示例
MAJOR（主版本）行为、输入、输出或结构发生破坏性变更API合约变更、功能移除、文件重命名
MINOR（次版本）添加用户可见的新功能或工作流新功能、新接口、新命令
PATCH（修订版本）bug修复、小幅改进，无新功能修复拼写错误、提升性能、格式调整

Release Naming Convention

版本命名规范

vX.Y.Z — [Program] / [Module]: [Feature]
ComponentTypeDescription
ProgramNounMajor domain (e.g., Kitchen, Garden)
ModuleNoun-phraseCapability area (e.g., Planning, Tasks)
FeatureVerb/Noun-phraseSpecific action (e.g., Create meal plan)
Examples:
  • 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
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 Tags (Machine-Friendly)

范围标签（机器友好型）

scope: program.module.feature
Examples:
  • scope: kitchen.planning.generate-shopping-list
  • scope: garden.tasks.track-watering-routine
scope: program.module.feature
示例:
  • scope: kitchen.planning.generate-shopping-list
  • scope: garden.tasks.track-watering-routine

Compatibility Rules

兼容性规则

MAJOR bump when ANY of these change in a breaking way:
  • File/folder paths or naming conventions
  • Required inputs or workflow order
  • Output contract (required sections, templates)
MINOR bump when:
  • New workflow outcome added
  • Module gains end-to-end feature
  • Docs gain new non-breaking sections
PATCH bump when:
  • Bug fixes, formatting, typos
  • Performance improvements without contract change
当以下任何一项发生破坏性变更时，升级MAJOR版本：
  • 文件/文件夹路径或命名规范
  • 必需的输入或工作流顺序
  • 输出合约（必填章节、模板）
升级MINOR版本的场景：
  • 添加新的工作流成果
  • 模块获得端到端功能
  • 文档添加非破坏性的新章节
升级PATCH版本的场景：
  • bug修复、格式调整、拼写错误修正
  • 无合约变更的性能提升

Folder Structure

文件夹结构

/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
/Documentation/
  project-roadmap.md       # 动态规划 + 进度跟踪
  architecture.md          # 系统设计概述
  changelog.md             # 版本历史（遵循Keep a Changelog格式）
  features/
    [program-name]/
      [module-name]/
        _[module-name].md  # 模块说明文档（下划线使其排序靠前）
        feature-name-1.md  # 功能规格说明
        feature-name-2.md  # 功能规格说明

Key Files

关键文件

FilePurpose
project-roadmap.md
Strategic roadmap (v0.1 → v1.0), milestones
architecture.md
System design, data flow, key components
changelog.md
Version history (Keep a Changelog format)
_*.md
(module)		Module overview, features list, dependencies
*.md
(feature)		User story, acceptance criteria, tech notes
文件用途
project-roadmap.md
战略路线图（从v0.1到v1.0）、里程碑跟踪
architecture.md
系统设计、数据流、核心组件
changelog.md
版本历史（遵循Keep a Changelog格式）
_*.md
（模块文件）		模块概述、功能列表、依赖关系
*.md
（功能文件）		用户故事、验收标准、技术说明

Root README

根目录README文档

The README is a bridge, not a brochure. Its job is to take someone from "what is this?" to "I have it running and understand how to use it." If a reader follows the README top to bottom and can't get the project working, the README failed — not the reader.
README是一座桥梁，而非宣传册。它的职责是引导读者从“这是什么？”过渡到“我已经能运行它并理解如何使用它”。如果读者按README从头到尾操作却无法让项目运行，那就是README的失败——而非读者的问题。

Two Audiences, One Document

两类读者，一份文档

  • "Just run it" readers — Want a working state in 5 minutes. They'll read Title, Quick Start, and Setup.
  • "Understand it" readers — Want to know why things work. They still want Quick Start first — understanding is easier once you've seen the thing running.
The section order below serves both. Skim readers exit early with a working result. Deep readers continue into structure and configuration.
  • “只想运行它”的读者 — 希望在5分钟内让项目正常运行。他们会阅读标题、快速开始和设置部分。
  • “想深入理解”的读者 — 想知道项目的工作原理。他们仍希望先看快速开始部分——在看到项目运行后，理解会更容易。
以下章节顺序同时服务于两类读者。浅读的读者可以在完成前几节就获得可用结果。深度阅读的读者可以继续了解结构和配置。

Section Order

章节顺序

#SectionPurpose
1Title + One-Liner"Is this relevant to me?" in 10 seconds
2Quick StartFirst success in ≤5 minutes
3What This Does / Doesn'tSet correct expectations
4PrerequisitesHonest dependency list
5SetupFull environment setup with validation
6UsageCore workflows with real examples
7Project StructureWhere things live and why
8ConfigurationWhat's customizable and how
9TroubleshootingCommon failures + fixes
10ContributingHow to help, where to start
Why this order: Sections 1–2 are engagement gates (fail here and the reader leaves). Sections 3–5 are foundation (skip these and the reader gets lost later). Sections 6–8 are reference (dip in and out as needed). Sections 9–10 are safety nets (when things go wrong or someone wants to contribute).
序号章节用途
1标题 + 一句话描述10秒内让读者判断“这与我相关吗？”
2快速开始确保读者在≤5分钟内获得首次成功体验
3项目能做/不能做什么建立正确的预期
4前置要求明确列出依赖项
5环境设置完整的环境设置步骤及验证方法
6使用方法核心工作流及实际示例
7项目结构文件位置及设计原因
8配置说明可自定义项及配置方法
9故障排查常见问题及解决方法
10贡献指南如何参与贡献、入门路径
为什么是这个顺序： 第1-2节是读者留存的关键（此处失败会导致读者离开）。第3-5节是基础（跳过这些会导致读者后续困惑）。第6-8节是参考资料（按需查阅）。第9-10节是保障（当出现问题或读者想贡献时）。

Key Principles

核心原则

  1. Success Horizons — Every instruction ends with what the reader should see. 
    npm run db:migrate
    alone is incomplete. Add: You should see: 
    Migrations complete. 12 tables created.
  2. Honest Prerequisites — List exact versions with check commands. Hidden requirements become support tickets.
  3. Concrete Over Abstract — Use the project's actual names and paths, not 
    {placeholder}
    patterns.
  4. Jargon Translation — If a term would make someone stop and Google, translate it immediately.
  5. Failure Modes — Document common failures inline (
    > **If you see [error]:** [cause]. Fix: [what to do]
    ), catch the rest in Troubleshooting.
  6. Scannable Structure — Headers, code blocks, tables, short paragraphs. Never walls of text.
Full guide: 
references/readme-guide.md
— Section-by-section details with Good/Bad examples and anti-patterns Template: 
assets/readme-template.md
— Copy-paste starter with all 10 sections
  1. 明确的成功标志 — 每个步骤都需说明读者应看到的结果。仅写
    npm run db:migrate
    是不完整的，应补充：你应该看到：
    Migrations complete. 12 tables created.
  2. 透明的前置要求 — 列出精确的版本及检查命令。隐藏的依赖项会转化为支持工单。
  3. 具体而非抽象 — 使用项目的实际名称和路径，而非
    {placeholder}
    这类占位符。
  4. 术语解释 — 如果某个术语会让读者停下来谷歌搜索，立即给出解释。
  5. 故障模式说明 — 内联记录常见故障（
    > **如果出现[错误]:** [原因]。解决方法：[具体操作]
    ），其余故障汇总到故障排查章节。
  6. 易扫描的结构 — 使用标题、代码块、表格、短段落。绝不使用大段无格式文本。
完整指南: 
references/readme-guide.md
— 包含各章节细节、正反示例及反模式 模板: 
assets/readme-template.md
— 包含全部10个章节的可复制起始模板

Feature Specifications

功能规格说明

Required Elements

必填要素

Every feature file MUST include:
  1. One-line description
  2. Module reference and status
  3. User story (As a / I want / So that)
  4. Overview and basic scenario
  5. Acceptance criteria (testable checkboxes)
  6. Data model (if applicable)
  7. Technical notes with Standards Checklist
  8. Open questions
  9. Related features
Use the template at 
assets/feature-template.md
. Every feature file must include: one-line description, module reference + status, user story (As/Want/So), overview with basic scenario, testable acceptance criteria, data model (if applicable), technical notes with standards checklist, open questions, and related features.
每个功能文件必须包含：
  1. 一句话描述
  2. 模块引用及状态
  3. 用户故事（As a / I want / So that 格式）
  4. 概述及基础场景
  5. 验收标准（可测试的复选框）
  6. 数据模型（如适用）
  7. 技术说明及标准检查清单
  8. 待解决问题
  9. 相关功能
使用
assets/feature-template.md
中的模板。每个功能文件必须包含：一句话描述、模块引用+状态、用户故事（As/Want/So格式）、含基础场景的概述、可测试的验收标准、数据模型（如适用）、带标准检查清单的技术说明、待解决问题及相关功能。

Module Explainers

模块说明文档

Use the template at 
assets/module-template.md
. Each module explainer includes: one-line description, program reference + status count, overview, feature table (with status + links), dependencies, and architecture notes.
使用
assets/module-template.md
中的模板。每个模块说明文档包含：一句话描述、主程序引用+状态统计、概述、功能表格（含状态及链接）、依赖关系及架构说明。

Changelog Format

变更日志格式

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

Change Types

变更类型

TypeDescription
AddedNew features
ChangedChanges in existing functionality
DeprecatedSoon-to-be removed features
RemovedNow removed features
FixedBug fixes
SecurityVulnerability fixes
类型描述
Added（新增）新功能
Changed（变更）现有功能的变更
Deprecated（弃用）即将移除的功能
Removed（移除）已移除的功能
Fixed（修复）bug修复
Security（安全）漏洞修复

Status Formats

状态格式

ContextFormatValues
project-roadmap.md
Emoji⏳ Planned, 🔄 In Progress, ✅ Complete, 🚫 Blocked
Feature/Module filesTextPlanned, In Progress, Complete
Open questionsTextOpen, Resolved
Rationale: Emoji in roadmap for visual scanning. Text in feature files for AI parsing.
上下文格式可选值
project-roadmap.md
表情符号⏳ 规划中, 🔄 进行中, ✅ 已完成, 🚫 受阻
功能/模块文件文本Planned, In Progress, Complete
待解决问题文本Open, Resolved
设计理由： 路线图中使用表情符号便于快速视觉扫描；功能文件中使用文本便于AI解析。

Documentation Checklist

文档检查清单

Before considering documentation complete:
在确认文档完成前，请检查以下内容：

Feature Files

功能文件

  • One-line description present
  • Status is current and accurate
  • User story follows As/Want/So format
  • Acceptance criteria are testable checkboxes
  • Standards checklist is complete
  • Open questions addressed or documented
  • 包含一句话描述
  • 状态是最新且准确的
  • 用户故事遵循As/Want/So格式
  • 验收标准是可测试的复选框
  • 标准检查清单已完成
  • 待解决问题已记录或解决

Module Explainers

模块说明文档

  • Feature table is current
  • Status counts are accurate
  • Dependencies listed
  • 功能表格是最新的
  • 状态统计准确
  • 已列出依赖关系

Project-Level

项目级文档

  • Roadmap reflects current state
  • Changelog updated for release
  • Architecture doc current
  • 路线图反映当前状态
  • 变更日志已针对版本更新
  • 架构文档是最新的

References

参考资料

  • references/semver-guide.md
    — Complete semantic versioning guide
  • references/changelog-format.md
    — Keep a Changelog format
  • references/feature-spec-guide.md
    — Feature specification writing guide
  • references/readme-guide.md
    — Root README writing guide
  • references/semver-guide.md
    — 完整的语义化版本控制指南
  • references/changelog-format.md
    — Keep a Changelog格式说明
  • references/feature-spec-guide.md
    — 功能规格说明编写指南
  • references/readme-guide.md
    — 根目录README编写指南

Assets

资源模板

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

Scripts

脚本工具

  • scripts/validate_docs.py
    — Validate documentation structure
  • scripts/generate_feature.py
    — Generate feature file from template
  • scripts/validate_docs.py
    — 验证文档结构
  • scripts/generate_feature.py
    — 从模板生成功能文件