name: docs-codebase description: 技术写作模式，适用于README文件、API文档、架构决策记录（ADRs）、变更日志、贡献指南、代码注释和文档即代码工作流。涵盖文档结构、风格指南、Markdown最佳实践和文档测试。

技术文档

为清晰、可维护的技术文档提供即用型模式。

现代最佳实践（2026年1月）: 文档即代码、所有权+审查节奏、文档质量保证关卡（链接/风格/拼写）、AI辅助起草+审查、OpenAPI 3.2.0（其中流式模式重要）、以及用于AI搜索的生成式引擎优化（GEO）。

快速参考

文档类型	模板	使用时机
项目README	readme-template.md	新项目、入职
架构决策	adr-template.md	技术决策
API参考	api-docs-template.md	REST/GraphQL APIs
变更日志	changelog-template.md	版本历史
贡献指南	contributing-template.md	开源、团队

工作流

确定文档类型和受众。
在代码库中查找现有模式；遵循本地约定。
从assets/中最接近的模板开始并适配。
为关键文档（运行手册、入职、API参考）添加所有权+审查节奏。
在合并前运行文档质量保证（链接、格式、拼写、示例）。

决策树

用户需求: [文档任务]
    ├─ 新项目？ → **README.md**
    ├─ 技术决策？ → **ADR**
    ├─ 构建API？ → **OpenAPI规范** + api-docs-template
    ├─ 新版本？ → **CHANGELOG.md**
    ├─ 团队协作？ → **CONTRIBUTING.md**
    ├─ 记录代码？ → **Docstrings** (JSDoc, Python)
    └─ 构建文档站点？ → **MkDocs** (Python) 或 **Docusaurus** (JS)

跨平台AI文档

AGENTS.md 标准

优先将AGENTS.md作为跨工具的单一事实来源。如果特定工具需要不同的文件名（例如：Claude Code使用CLAUDE.md），仅当您希望跨工具内容相同时通过符号链接保持对齐。

# 如果`CLAUDE.md`不存在且您希望内容相同：
ln -s AGENTS.md CLAUDE.md

做 / 避免

做

为关键文档分配所有者和审查节奏
添加CI检查链接、风格和过时性
倾向于小型、任务导向的文档而非大型维基页面
使用保持变更日志格式和语义版本控制

避免

没有所有者的文档（保证会腐坏）
过时的运行手册（在事件中危险）
复制/粘贴文档与代码脱节

资源

资源	用途
references/readme-best-practices.md	README结构、徽章
references/adr-writing-guide.md	ADR生命周期、示例
references/changelog-best-practices.md	保持变更日志格式
references/api-documentation-standards.md	REST、GraphQL、gRPC文档
references/code-commenting-guide.md	Docstrings、内联注释
references/contributing-guide-standards.md	CONTRIBUTING.md结构
references/docs-as-code-setup.md	MkDocs、Docusaurus、CI/CD
references/writing-best-practices.md	清晰沟通
references/markdown-style-guide.md	Markdown格式
references/documentation-testing.md	Vale、markdownlint、cspell
references/ai-documentation-tools.md	Mintlify、DocuWriter、GEO
references/production-gotchas-guide.md	记录平台问题

模板

类别	模板
架构	adr-template.md
API参考	api-docs-template.md
项目管理	readme-template.md, changelog-template.md, contributing-template.md
文档即代码	docs-structure-template.md, ownership-model.md

技能	用途
qa-docs-coverage	文档覆盖审计
dev-api-design	REST API模式
git-workflow	常规提交
docs-ai-prd	PRD模板

文档代码库 docs-codebase