为代码库编写新手友好文档：README、架构说明…

当需要为代码库编写或改进文档（README、架构文档、代码注释、API 文档）时，用结构化模板和最佳实践让新开发者快速理解并参与项目。

适用场景

解决思路

1. 遵循新手友好文档的核心原则：先讲“为什么”再讲实现细节；采用渐进式披露，从简单到复杂分层呈现信息；提供上下文，解释代码存在的原因而非仅功能；为每个概念配具体示例；假设读者无先验知识，定义术语并避免行话；使用图表、流程图和文件树等可视化辅助；帮助用户在 5 分钟内获得可运行的快速成果。
2. 编写 README 时按以下结构：项目名称、What This Does（1-2 句白话说明）、Quick Start（5 分钟内跑起来）、Project Structure（带说明的可视化文件树）、Key Concepts（核心概念）、Common Tasks（常见操作的分步指南）、Troubleshooting（常见问题与解决方案）。
3. README 最佳实践：开头突出项目价值主张；提供经过实际测试可用的安装步骤；给出项目结构的可视化概览；高级主题链接到更深入的文档；根 README 聚焦于快速上手。
4. 编写架构文档时按以下结构：Architecture Overview、System Design（高层图与说明）、Directory Structure（每个目录用途的详细拆解）、Data Flow（数据如何在系统中流动）、Key Design Decisions（为何做这些架构选择）、Module Dependencies（各部分如何交互）、Extension Points（在哪里以及如何添加新功能）。
5. 架构文档最佳实践：用图表展示系统组件与关系；解释架构决策背后的“为什么”；同时记录正常路径和错误处理；标明模块之间的边界；包含带注释的可视化文件树结构。
6. 编写代码注释时使用以下注解模式：函数/方法文档用 JSDoc 风格，包含 Why this exists 说明、@param 参数说明、@returns 返回值、@example 示例；复杂逻辑注释解释边界情况与业务逻辑，例如区分 API 返回 null（已删除用户）与空字符串（未完成引导）的不同处理。
7. 代码注释最佳实践：解释“为什么”而非“做什么”；记录边界情况与业务逻辑；为复杂函数添加示例；解释不自解释的参数；标注任何陷阱或反直觉行为。
8. 编写 API 文档时按以下结构：Endpoint Name、What It Does（白话说明用途）、Endpoint（如 `POST /api/v1/resource`）、Authentication（所需认证及提供方式）、Request Format（JSON schema 或示例请求）、Response Format（JSON schema 或示例响应）、Example Usage（curl/代码的具体示例）、Common Errors（错误码及含义）、Related Endpoints（相关操作链接）。
9. API 文档最佳实践：提供可运行的 curl 示例；同时展示成功与错误响应；清晰说明认证方式；记录速率限制与约束；包含常见问题的排查说明。
10. 文档工作流第 1 步——分析代码库：识别入口点（主文件、index 文件、应用初始化）；梳理依赖关系（模块之间如何关联）；找出核心概念（用户需要理解的关键抽象）；定位配置（环境设置、配置文件）；审查现有文档（在已有基础上补充，不要重复）。
11. 文档工作流第 2 步——选择文档类型：新项目或缺 README → 先写 README；复杂架构或多模块 → 写架构文档；令人困惑的代码段 → 添加行内代码注释；HTTP/API 端点 → 写 API 文档；需要多种类型 → 按 README → Architecture → API → Comments 的顺序处理。
12. 文档工作流第 3 步——生成文档：以 `assets/templates/` 中的模板为起点（`assets/templates/README.template.md`、`assets/templates/ARCHITECTURE.template.md`、`assets/templates/API.template.md`）；填入项目特定信息替换占位符；添加项目中的真实代码示例；加入文件树、图表、流程图等可视化辅助；测试安装步骤确保可用；链接相关文档。
13. 文档工作流第 4 步——以清晰度审查：以初学者视角阅读，确认无# 项目上下文也能理解；检查完整性，找出解释中的缺口；验证代码示例确实可运行；测试说明步骤，确认他人能照着完成；改进结构，让信息易于查找。
14. 使用模板时：从 `assets/templates/` 读取合适模板；针对具体项目定制，替换占位符为实际信息；按需添加项目特定章节；使用代码库中的真实代码作为示例；删除不适用的章节。
15. 需要高级文档模式时参考 `references/documentation_guidelines.md`（风格指南与最佳实践）和 `references/visual_aids_guide.md`（如何创建有效图表与文件树），适用于复杂企业级代码库、多利益相关方需求、需要高级文档模式或大型项目文档标准化的场景。
16. 创建文件树结构帮助新用户理解项目组织，例如标注 `src/`（源代码）、`components/`（可复用 UI 组件）、`pages/`（页面级路由组件）、`services/`（业务逻辑与 API 调用）、`utils/`（辅助函数）、`types/`（TypeScript 类型定义）、`public/`（静态资源）、`tests/`（镜像 src 结构的测试文件）、`package.json`（依赖与脚本）。
17. 解释复杂数据流时使用带编号的步骤与图示，例如：用户提交表单 → 验证 → API 调用 → 数据库 → 响应，并标注每一步对应的文件（如 `components/UserForm.tsx`、`services/validation.ts`、`services/api.ts`、PostgreSQL 数据库）。
18. 记录设计决策时捕捉架构选择背后的“为什么”，包含 Decision（决策内容）、Context（背景）、Reasoning（理由）、Trade-offs（权衡），例如说明为何用 Redux 而非 Context API：组件数量多导致 Context 不必要重渲染、Redux DevTools 便于调试、团队已有经验，代价是更多样板代码与更陡的学习曲线。
19. 输出文档时遵循：根据目标受众调整复杂度（初学者/中级/高级）；使用一致的 Markdown 格式与标题层级；测试所有代码片段与命令；在文档之间建立导航链接；保持可维护性，便于随代码变更更新；标注最后更新日期与版本。

适用边界 · 注意事项

• 不适用于非代码库文档场景（如产品需求文档、用户手册、营销材料）。
• 当项目极其简单、无需面向新开发者时，不必套用完整模板与工作流。
• 没有代码库访问权限或无法运行/测试示例时，不应声称示例已验证。