documentation-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation Guide Enforcement Skill

文档规范强制执行技能

Ensures all documentation is consistent, current, and complete. Used by the doc-master agent.

确保所有文档的一致性、时效性和完整性。供doc-master agent使用。

Keep a Changelog Format

Keep a Changelog 格式

All CHANGELOG entries MUST follow Keep a Changelog format.

所有CHANGELOG条目必须遵循Keep a Changelog格式。

Categories (in this order)

分类（按以下顺序）

Added — new features
Changed — changes to existing functionality
Deprecated — soon-to-be removed features
Removed — removed features
Fixed — bug fixes
Security — vulnerability fixes

Added — 新增功能
Changed — 现有功能变更
Deprecated — 即将移除的功能
Removed — 已移除的功能
Fixed — Bug修复
Security — 漏洞修复

Structure

结构

markdown

undefined

markdown

undefined

Changelog

[Unreleased]

Added

New authentication module (#123)

新的认证模块 (#123)

Fixed

Token expiry off-by-one error (#124)

Token过期差一错误 (#124)

[1.2.0] - 2026-02-15

Added

Batch processing support (#100)


The `[Unreleased]` section MUST always exist at the top for accumulating changes.

---

批量处理支持 (#100)


`[Unreleased]`部分**必须**始终位于顶部，用于累积待发布变更。

---

README Required Sections

README 必填章节

Every README.md MUST contain these sections in order:

Overview — 1-2 sentence project description
Installation — How to install/set up
Usage / Quick Start — Minimal working example
Commands Table — Available commands with descriptions
Configuration — Config files, env vars, options
Contributing — How to contribute, link to CONTRIBUTING.md

每个README.md必须按顺序包含以下章节：

概述 — 1-2句话的项目描述
安装 — 安装/设置方法
使用/快速开始 — 最简可用示例
命令表格 — 可用命令及说明
配置 — 配置文件、环境变量、选项
贡献指南 — 贡献方式，链接至CONTRIBUTING.md

Docstring Format: Google Style

文档字符串格式：Google风格

All public functions MUST have Google-style docstrings.

python

def process_data(
    data: List[Dict],
    *,
    validate: bool = True,
) -> ProcessResult:
    """Process input data with optional validation.

    Args:
        data: Input records as list of dicts with 'id' and 'content' keys.
        validate: Whether to validate input before processing.

    Returns:
        ProcessResult with metrics and processed items.

    Raises:
        ValueError: If data is empty or missing required keys.
    """

Include

Args

Returns

, and

Raises

for every public function. Omit sections only if truly not applicable (e.g., no exceptions raised).

所有公共函数必须使用Google风格的文档字符串。

python

def process_data(
    data: List[Dict],
    *,
    validate: bool = True,
) -> ProcessResult:
    """Process input data with optional validation.

    Args:
        data: Input records as list of dicts with 'id' and 'content' keys.
        validate: Whether to validate input before processing.

    Returns:
        ProcessResult with metrics and processed items.

    Raises:
        ValueError: If data is empty or missing required keys.
    """

每个公共函数都需包含

Args

、

Returns

和

Raises

部分。仅当完全不适用时可省略（例如无异常抛出）。

HARD GATE: Sync Rules

硬性要求：同步规则

Documentation MUST stay in sync with code at all times.

FORBIDDEN:

Updating code without updating corresponding docs
Hardcoded component counts (e.g., "17 agents") — use dynamic discovery or verify against filesystem
Undocumented public APIs — every public function needs a docstring
Stale cross-references — links to files/sections that no longer exist
CHANGELOG entries without issue/PR numbers
Version dates that do not match actual release dates

REQUIRED:

CHANGELOG entry for every user-visible change
Version date updated when changes are made
Component counts verified against filesystem before committing
Cross-references validated (all linked files exist)
README updated when commands or configuration change
Docstrings updated when function signatures change

文档必须始终与代码保持同步。

禁止行为：

更新代码但不更新对应文档
硬编码组件数量（例如“17个agents”）—— 使用动态发现或根据文件系统验证
未文档化的公共API——每个公共函数都需要文档字符串
过时的交叉引用——指向已不存在的文件/章节的链接
无问题/PR编号的CHANGELOG条目
版本日期与实际发布日期不符

要求行为：

每个用户可见的变更都要有CHANGELOG条目
变更时更新版本日期
提交前根据文件系统验证组件数量
验证交叉引用（所有链接文件均存在）
命令或配置变更时更新README
函数签名变更时更新文档字符串

When to Update Which Docs

何时更新对应文档

Change Type	README	CHANGELOG	Docstrings	ADR
API change	Yes	Yes	Yes	Maybe
New feature	Yes	Yes	Yes	Maybe
Bug fix	No	Yes	No	No
Refactor (no behavior change)	No	No	Maybe	Maybe
Architecture decision	No	No	No	Yes
Config change	Yes	Yes	No	No
Deprecation	Yes	Yes	Yes	Maybe

变更类型	README	CHANGELOG	文档字符串	ADR
API变更	是	是	是	可能
新功能	是	是	是	可能
Bug修复	否	是	否	否
重构（无行为变更）	否	否	可能	可能
架构决策	否	否	否	是
配置变更	是	是	否	否
弃用	是	是	是	可能

ADR Template

ADR模板

For major architectural decisions, create an ADR (Architecture Decision Record).

markdown

undefined

对于重大架构决策，需创建ADR（架构决策记录）。

markdown

undefined

ADR-NNN: [Title]

ADR-NNN: [标题]

Date: YYYY-MM-DD Status: Proposed | Accepted | Deprecated | Superseded by ADR-NNN

日期：YYYY-MM-DD 状态：提议 | 已接受 | 已弃用 | 被ADR-NNN取代

Context

背景

What is the issue or decision we need to make?

我们需要解决的问题或做出的决策是什么？

Decision

决策

What did we decide and why?

我们做出了什么决定，原因是什么？

Consequences

影响

What are the positive and negative outcomes?

有哪些正面和负面结果？

Alternatives Considered

备选方案评估

What other options were evaluated and why were they rejected?


Store ADRs in `docs/adr/` directory, numbered sequentially.

---

还考虑了哪些其他选项，为什么被否决？


将ADR存储在`docs/adr/`目录中，按顺序编号。

---

Anti-Patterns

反模式

BAD: Hardcoded counts

错误示例：硬编码数量

markdown

This project has 17 agents and 40 skills.

These numbers drift immediately. Verify against filesystem or use dynamic discovery.

markdown

本项目有17个agents和40个skills。

这些数字会立即失效。需根据文件系统验证或使用动态发现。

GOOD: Verified counts

正确示例：已验证数量

bash

undefined

bash

undefined

Count before documenting

记录前先统计

ls plugins/autonomous-dev/agents/.md | wc -l ls plugins/autonomous-dev/skills//SKILL.md | wc -l

undefined

ls plugins/autonomous-dev/agents/.md | wc -l ls plugins/autonomous-dev/skills//SKILL.md | wc -l

undefined

BAD: Stale cross-references

错误示例：过时的交叉引用

markdown

See [architecture guide](docs/ARCHITECTURE.md) for details.

docs/ARCHITECTURE.md

was renamed to

docs/ARCHITECTURE-OVERVIEW.md

, this link is broken.

markdown

详情请参阅[架构指南](docs/ARCHITECTURE.md)。

如果

docs/ARCHITECTURE.md

已重命名为

docs/ARCHITECTURE-OVERVIEW.md

，此链接将失效。

GOOD: Validated references

正确示例：已验证的引用

Check all links exist before committing documentation changes.

提交文档变更前检查所有链接是否存在。

BAD: Missing CHANGELOG entry

错误示例：缺失CHANGELOG条目

Shipping a user-visible feature with no CHANGELOG entry. Users cannot discover what changed.

发布用户可见的功能但无CHANGELOG条目。用户无法了解变更内容。

GOOD: CHANGELOG-first workflow

正确示例：CHANGELOG优先工作流

Write the CHANGELOG entry before or during implementation, not as an afterthought.

在实现之前或期间编写CHANGELOG条目，而非事后补充。

Cross-References

交叉引用

project-alignment: PROJECT.md as source of truth
git-github: Commit message and PR conventions
code-review: Documentation checklist item (#8)

project-alignment: PROJECT.md为事实来源
git-github: 提交信息和PR约定
code-review: 文档检查清单项（#8）