onboarding

用途

该技能用于爬取代码仓库，并在仓库根目录生成 ONBOARDING.md 文档，帮助新贡献者在不依赖创建者解释的情况下理解代码库。它适用于代码编写速度快于文档更新的快速迭代项目，例如通过 AI 辅助开发、快速原型或团队交付速度快于文档编写速度的场景。该技能从代码本身重建心智模型。

该技能始终从头重新生成文档，不读取或对比之前的版本。如果 ONBOARDING.md 已存在，它会被覆盖。

主要能力

• 运行内置的清单脚本（scripts/inventory.mjs）获取仓库的结构化地图，无需读取每个文件。
• 解析 JSON 输出，获取项目名称、语言、框架、包管理器、测试框架、目录结构、入口点、可用脚本、现有文档文件、测试基础设施、基础设施和外部依赖、monorepo 结构等信息。
• 根据清单指引，读取理解代码库所需的关键文件。
• 将清单数据和关键文件内容综合为六个部分，写入仓库根目录的 ONBOARDING.md。

使用方式

阶段 1：收集清单

运行内置的清单脚本：

node scripts/inventory.mjs --root .

解析 JSON 输出。如果脚本失败或返回错误字段，向用户报告问题并停止，不要尝试从不完整的数据编写 ONBOARDING.md。

阶段 2：读取关键文件

根据清单指引，使用原生文件读取工具（而非 shell 命令）读取理解代码库所必需的文件。在没有依赖关系的文件之间并行批量读取。只读取编写六个部分所需的具体细节的文件。不同仓库需要读取的文件数量不同。

优先级顺序：

1. README.md（如果存在）——用于了解项目目的和设置说明。
2. 主要入口点——清单中 entryPoints 列出的文件。
3. 路由/控制器文件——查找 routes/、app/controllers/、src/routes/、src/api/ 或类似目录。
4. 揭示架构和外部依赖的配置文件——docker-compose.yml、.env.example、.env.sample、数据库配置、next.config.*、vite.config.* 等。只读取 .env.example 或 .env.sample 模板，绝不读取 .env 本身。只提取变量名，绝不提取值。
5. AGENTS.md 或 CLAUDE.md（如果存在）——用于了解已记录的项目约定和模式。
6. 已发现的文档——清单的文档列表包含每个文件的标题（第一个标题）。使用这些标题决定哪些文档相关，无需先读取它们。只读取标题表明直接相关的文档的完整内容。

不要推测性地读取文件。每次读取文件都应由清单输出证明其合理性，并可追溯到需要它的部分。

阶段 3：编写 ONBOARDING.md

将清单数据和关键文件内容综合为以下定义的部分，写入仓库根目录。

标题：使用 # {Project Name} Onboarding Guide 作为文档标题。从清单中获取项目名称。不要使用文件名作为标题。

写作风格

文档应读起来像一位知识渊博的队友在喝咖啡时解释项目，而不是生成的文档。

语气和语调：

• 使用第二人称（“你”）——直接与新贡献者对话。
• 使用主动语态和现在时：“路由器将请求分派给处理器”，而不是“请求被路由器分派给处理器”。
• 直接表达。以重要内容开头，而不是以铺垫开头：“运行 bun dev 启动服务器”，而不是“为了启动开发服务器，你需要运行以下命令”。
• 匹配代码库的正式程度。

清晰度：

• 每个句子都应教会读者一些东西或告诉他们该做什么。
• 优先具体而非抽象。
• 引入术语时立即在上下文中定义。
• 使用最准确的最简单词汇。

应避免的内容：

• 填充和清嗓子：“需要注意的是”、“如上所述”、“在本节中我们将”。
• 模糊总结：“此模块处理……的各个方面”。
• 陈述事实时的模糊词：“这本质上充当”、“这基本上是”。
• 最高级和营销语言：“健壮”、“强大”、“全面”、“无缝”。
• 关于文档本身的元评论：“本文档旨在……”。

格式要求：

• 对所有文件名、路径、命令、函数/类名、环境变量和技术术语使用反引号。
• 每个部分使用 markdown 标题（##）。
• 在指定处使用 ASCII 图表和 markdown 表格。
• 谨慎使用粗体强调。
• 保持段落简短——2-4 句。
• 在每个 ## 部分之间插入水平规则（---）。
• 代码块宽度约束：最多 80 列。

文档结构

第 1 部分：这是什么？

回答：这个项目做什么，面向谁，解决什么问题？从 README.md、清单描述和入口点中获取信息。如果无法从代码中明确确定项目目的，请如实说明。保持 1-3 段。

第 2 部分：如何使用？

回答：站在消费方角度使用这个项目是什么样子？根据谁消费项目来命名此部分：

• 终端用户产品——标题：“用户体验”。
• 开发者工具——标题：“开发者体验”。
• 两者兼有——标题：“用户和开发者体验”。

保持 1-3 段或每个受众一个简短流程。如果存在全面的用户或开发者文档，链接到它们并用一句话总结关键工作流。不要重复现有文档。仅对没有消费受众的代码库跳过此部分。

第 3 部分：如何组织？

回答：架构是什么，关键模块有哪些，它们如何连接，系统外部依赖什么？

系统架构——两种图表：

• 架构图——组件、它们如何连接以及使用什么协议或传输。从用户界面开始，中间是内部管道，底部是数据存储和外部服务。
• 用户交互流程——用户在产品中经历的逻辑旅程。

对于简单系统，架构图已足够。对于多界面产品，两者都包括。使用垂直堆叠保持图表在 80 列以内。

内部结构——包括显示高层布局的 ASCII 目录树，用简短注释标注目录。当存在职责明确的模块时，用表格呈现。描述模块如何连接。

外部依赖和集成——呈现系统与自身代码库外部通信的所有内容。查找信号：docker-compose.yml、环境变量引用、客户端库导入语句、清单检测到的框架。用表格呈现。如果没有检测到外部依赖，说明：“此项目似乎是自包含的，没有外部服务依赖。”

第 4 部分：关键概念和抽象

回答：要讨论这个代码库，需要理解哪些词汇和模式？

此部分涵盖：

• 领域术语——项目特定词汇：实体名称、API 资源名称、数据库表、配置概念以及新读者不会立即认识的术语。
• 架构抽象——代码库中塑造……（原文在此处截断）

核心原则

• 为人类优先写作——清晰散文，新开发者可以阅读和理解。
• 展示，而不仅仅是讲述——使用 ASCII 图表展示架构和流程，使用 markdown 表格展示结构化信息，对所有文件路径、命令和代码引用使用反引号格式。
• 六个部分，每个都有其价值——每个部分回答新贡献者在第一小时内会问的问题。没有推测性部分。对于没有消费受众的纯基础设施，可以跳过第 2 部分，产生五个部分。
• 陈述你能观察到的，而不是你必须推断的——不要编造设计理由或评估脆弱性。如果代码没有揭示为什么做出某个决定，不要猜测。
• 绝不包含密钥——入职文档会提交到仓库。绝不包含 API 密钥、令牌、密码、带凭据的连接字符串或任何其他秘密值。引用环境变量名称（STRIPE_SECRET_KEY），绝不引用其值。如果 .env 文件包含实际密钥，只提取变量名。
• 链接，不要重复——当现有文档很好地涵盖某个主题时，内联链接到它，而不是重新解释。

适用场景

• 快速迭代的代码库，代码编写速度快于文档更新。
• 通过 AI 辅助开发、快速原型或团队交付速度快于文档编写速度的项目。
• 需要帮助新贡献者理解代码库的场景。

限制

• 该技能始终从头重新生成文档，不读取或对比之前的版本。如果 ONBOARDING.md 已存在，它会被覆盖。
• 如果清单脚本失败或返回错误字段，技能会报告问题并停止，不会从不完整的数据编写文档。
• 绝不包含密钥。
• 不编造设计理由或评估脆弱性。
• 原文在第 4 部分“架构抽象”处截断，该部分内容不完整。