Back to Details

docs-conventions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Conventions

文档规范

Conventions for organizing team documentation as markdown files in the repository. Designed so docs serve as shared context for both humans and AI agents.
本规范用于指导在代码仓库中以markdown文件形式组织团队文档，设计初衷是让文档既能为团队成员也能为AI Agent提供共享上下文。

Directory Structure

目录结构

docs/
  adr/        # Architecture Decision Records — immutable once accepted
  rfcs/       # Proposals under discussion — accepted, rejected, or superseded
  guides/     # How-to guides for the team
  systems/    # Technical documentation of current systems
  incidents/  # Postmortems and investigations
  audits/     # Inventories and point-in-time analysis
docs/
  adr/        # Architecture Decision Records — immutable once accepted
  rfcs/       # Proposals under discussion — accepted, rejected, or superseded
  guides/     # How-to guides for the team
  systems/    # Technical documentation of current systems
  incidents/  # Postmortems and investigations
  audits/     # Inventories and point-in-time analysis

Naming Rules

命名规则

DirectoryPatternExample
adr/
NNNN-title.md
(zero-padded)
0001-use-postgresql.md
rfcs/
NNN-title.md
(sequential)
001-e2e-testing-strategy.md
incidents/
YYYY-MM-DD-title.md
2026-03-26-webhook-failures.md
guides/
descriptive-name.md
playwright.md
systems/
descriptive-name.md
candidate-search.md
audits/
descriptive-name.md
unused-api-endpoints.md
All filenames in kebab-case. Never UPPER_CASE or camelCase.
目录命名规则示例
adr/
NNNN-title.md
(补零对齐)
0001-use-postgresql.md
rfcs/
NNN-title.md
(按顺序编号)
001-e2e-testing-strategy.md
incidents/
YYYY-MM-DD-title.md
2026-03-26-webhook-failures.md
guides/
描述性名称.md
playwright.md
systems/
描述性名称.md
candidate-search.md
audits/
描述性名称.md
unused-api-endpoints.md
所有文件名统一使用kebab-case格式，禁止使用大写下划线格式或camelCase格式。

When to Use Each Type

各类型文档适用场景

ADR (
docs/adr/
)

ADR (
docs/adr/
)

Architectural decisions that are final and accepted. Once written, ADRs are not modified — if a decision is reversed, a new ADR supersedes the old one.
Use for: technology choices, infrastructure decisions, pattern adoptions, breaking changes in conventions.
Template:
markdown
undefined
已最终确认并采纳的架构决策。ADR编写完成后不可修改——如果原有决策被推翻，需新增一份ADR替代旧版本。
适用场景：技术选型、基础设施决策、模式采纳、规范破坏性变更。
模板：
markdown
undefined

NNNN. Title

NNNN. Title

Date: YYYY-MM-DD Status: Accepted | Superseded by NNNN
Date: YYYY-MM-DD Status: Accepted | Superseded by NNNN

Context

Context

What is the issue that we're seeing that motivates this decision?
What is the issue that we're seeing that motivates this decision?

Decision

Decision

What is the change that we're proposing and/or doing?
What is the change that we're proposing and/or doing?

Consequences

Consequences

What becomes easier or more difficult to do because of this change?
undefined
What becomes easier or more difficult to do because of this change?
undefined

RFC (
docs/rfcs/
)

RFC (
docs/rfcs/
)

Proposals that need team discussion before implementation. RFCs have a lifecycle: draft → discussion → accepted/rejected.
Use for: new features requiring design, refactoring strategies, testing strategies, process changes.
Template:
markdown
undefined
需要在落地前经过团队讨论的提案。RFC有明确的生命周期：草稿 → 讨论中 → 已采纳/已拒绝。
适用场景：需要设计的新功能、重构策略、测试策略、流程变更。
模板：
markdown
undefined

NNN. Title

NNN. Title

Date: YYYY-MM-DD Status: Draft | In Discussion | Accepted | Rejected Author: name
Date: YYYY-MM-DD Status: Draft | In Discussion | Accepted | Rejected Author: name

Summary

Summary

One-paragraph description of the proposal.
One-paragraph description of the proposal.

Motivation

Motivation

Why are we doing this? What problem does it solve?
Why are we doing this? What problem does it solve?

Proposal

Proposal

Detailed description of the proposed change.
Detailed description of the proposed change.

Alternatives Considered

Alternatives Considered

What other approaches were evaluated and why were they rejected?
What other approaches were evaluated and why were they rejected?

Open Questions

Open Questions

Unresolved issues that need team input.
undefined
Unresolved issues that need team input.
undefined

Guide (
docs/guides/
)

指南 (
docs/guides/
)

Step-by-step instructions to accomplish a specific task. Written for the team, not for end users.
Use for: setup guides, tooling guides, deployment procedures, testing workflows.
用于完成特定任务的分步操作指南，面向团队内部成员编写，而非终端用户。
适用场景：配置指南、工具使用指南、部署流程、测试工作流。

System (
docs/systems/
)

系统文档 (
docs/systems/
)

Technical documentation of how a system currently works. Updated when the system changes.
Use for: architecture overviews, data flows, API contracts, integration documentation.
说明当前系统运行逻辑的技术文档，随系统迭代同步更新。
适用场景：架构概览、数据流说明、API契约、集成文档。

Incident (
docs/incidents/
)

事件记录 (
docs/incidents/
)

Record of what happened, why, and what was done. Written after an outage, data loss, or significant bug.
Use for: postmortems, incident investigations, root cause analysis.
Template:
markdown
undefined
记录故障发生过程、根因及处置方案的文档，在出现服务中断、数据丢失或严重bug后编写。
适用场景：事后复盘、事件调查、根因分析。
模板：
markdown
undefined

YYYY-MM-DD: Title

YYYY-MM-DD: Title

Severity: Critical | High | Medium | Low Status: Resolved | Mitigated | Monitoring Duration: start — end
Severity: Critical | High | Medium | Low Status: Resolved | Mitigated | Monitoring Duration: start — end

Summary

Summary

What happened in 2-3 sentences.
What happened in 2-3 sentences.

Impact

Impact

Who/what was affected and to what extent.
Who/what was affected and to what extent.

Timeline

Timeline

Chronological list of events.
Chronological list of events.

Root Cause

Root Cause

Why it happened.
Why it happened.

Resolution

Resolution

What was done to fix it.
What was done to fix it.

Action Items

Action Items

  • Preventive measures
undefined
  • Preventive measures
undefined

Audit (
docs/audits/
)

审计报告 (
docs/audits/
)

Point-in-time analysis or inventory. May become stale — always include the date in the content.
Use for: dead code analysis, unused endpoint inventories, dependency audits, performance investigations.
定点时间的分析或盘点内容，可能会过时——务必在内容中标注编写日期。
适用场景：死代码分析、未使用接口盘点、依赖审计、性能排查。

Sequential Number Assignment

序号分配规则

When creating a new ADR or RFC, check the highest existing number:
bash
ls docs/adr/ | sort -n | tail -1   # Next ADR number
ls docs/rfcs/ | sort -n | tail -1  # Next RFC number
创建新的ADR或RFC时，先查询现有最大编号：
bash
ls docs/adr/ | sort -n | tail -1   # Next ADR number
ls docs/rfcs/ | sort -n | tail -1  # Next RFC number

What Does NOT Belong in 
docs/

哪些内容不适合放在
docs/
目录下

  • Ephemeral tasks: use your issue tracker (GitHub Issues, Linear, Jira)
  • Code patterns/rules: use linter configs or agent rule files
  • Meeting notes or stakeholder updates: keep in your wiki/Notion
  • API reference auto-generated from code: use doc generators (Swagger, TypeDoc)
  • 临时任务：使用你的项目issue跟踪工具（GitHub Issues、Linear、Jira）
  • 代码模式/规则：使用linter配置文件或Agent规则文件
  • 会议记录或利益相关方更新：存放在你的知识库/Notion中
  • 从代码自动生成的API参考文档：使用文档生成工具（Swagger、TypeDoc）

Scaffolding a New Project

新项目初始化配置

To set up the 
docs/
structure in a new repo:
bash
mkdir -p docs/{adr,rfcs,guides,systems,incidents,audits}
touch docs/adr/.gitkeep
要在新仓库中搭建
docs/
目录结构，可执行以下命令：
bash
mkdir -p docs/{adr,rfcs,guides,systems,incidents,audits}
touch docs/adr/.gitkeep