ADR 001: 采用标准模板体系管理项目文档

ADR 001: 采用标准模板体系管理项目文档

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

Status

Accepted

Context

项目文档长期以自由格式的 Markdown 编写，不同作者产出的 API 文档、函数文档与架构决策文档结构差异巨大，导致：

• 检索困难：同样的信息在多个文档中以不同格式出现；
• 维护成本高：代码变更后，文档更新缺少统一入口；
• 新人上手慢：没有固定的阅读路径。

Decision

我们采用 claude-howto 提供的 Documentation 插件（见 07-plugins/documentation/README.md）作为统一方案：

• API 端点使用 api-endpoint.md 模板；
• 函数与方法使用 function-docs.md 模板；
• 架构决策使用 adr-template.md 模板；
• 文档生成由 /generate-api-docs 等命令驱动， 并由 api-documenter、code-commentator、example-generator 三个子代理分工完成。

Consequences

Positive

• 文档结构统一，检索与审查成本显著下降；
• 文档贴近代码，生成与更新有明确流程；
• 子代理分工使文档质量有专人保障。

Negative

• 存量文档需要迁移到新模板，初期有一定改造量；
• 团队需要学习模板约定与命令用法。

Neutral

• 模板约定本身也需要持续演进，需定期评审。

Alternatives Considered

Alternative 1：仅制定书面规范，不使用插件

通过 wiki 页面约定文档格式。 原因：缺少工具约束，规范容易被忽略，无法强制执行。

Alternative 2：购买商业文档平台

原因：成本较高，且与现有 Git 工作流集成度不足。

References

• ADR 002: 文档生成命令与 CI 的集成方式（Related ADR）
• 插件文档：07-plugins/documentation/README.md

## 在 claude-howto 的 Documentation 插件中落地 ADR 工作流 ADR 模板不是孤立存在的，它是 Documentation 插件完整能力链的一环。该插件的核心结构（见 [07-plugins/documentation/README.md](https://link.gitcode.com/i/e53b52ec0dbef9535adcb1aba67e840b)）包括： - **Slash 命令**：`/generate-api-docs` 生成 API 文档、`/generate-readme` 创建或更新 README、`/sync-docs` 同步文档与代码、`/validate-docs` 校验文档； - **子代理（Subagents）**：`api-documenter` 负责端点文档与请求/响应模式，`code-commentator` 负责 JSDoc/内联注释改进，`example-generator` 负责入门指南与常见用例示例； - **模板**：`api-endpoint.md`、`function-docs.md`、`adr-template.md`； - **MCP 服务器**：GitHub 集成用于文档同步。 从 [agents/api-documenter.md](https://link.gitcode.com/i/eb9317dbcae5e7784ce296a442fa98be) 的 frontmatter 可以看到，子代理通过 `tools: Read, Write, Grep` 声明其工具权限，`description` 字段明确职责边界，这正是 Claude Code 插件体系中"**职责单一、权限最小**"的设计体现。代码注释类任务则由 [code-commentator](https://link.gitcode.com/i/f1951979b6ce4149469473ed7305b5c6) 承担（额外具备 `Edit` 权限），示例与教程类任务交给 [example-generator](https://link.gitcode.com/i/8987faef4602987170c86329765dd77d)。 插件的典型使用流程如下（以生成 API 文档为例，来自 [README](https://link.gitcode.com/i/e53b52ec0dbef9535adcb1aba67e840b) 的 Example Workflow）：

User: /generate-api-docs

Claude:

1. Scans all API endpoints in /src/api/
2. Delegates to api-documenter subagent
3. Extracts function signatures and JSDoc
4. Organizes by module/endpoint
5. Uses api-endpoint.md template
6. Generates comprehensive markdown docs
7. Includes curl, JavaScript, and Python examples

Result: ✅ API documentation generated 📄 Files created:

• docs/api/users.md
• docs/api/auth.md
• docs/api/products.md 📊 Coverage: 23/23 endpoints documented

安装插件只需一条命令： ```bash /plugin install documentation

环境要求为Claude Code 2.1+，GitHub 访问为可选（用于文档同步）；若启用 GitHub 同步，需配置令牌：

export GITHUB_TOKEN="your_github_token"

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto