onboarding

生成入门文档

扫描代码仓库，并在仓库根目录生成 ONBOARDING.md，帮助新贡献者了解代码库，无需创建者亲自讲解。

软件项目普遍存在入门问题，但在快速变化的代码库中，这个问题尤为突出：代码的编写速度超过了文档的更新速度——无论是借助 AI 辅助开发、快速原型开发，还是团队的交付速度本来就快于文档编写速度。本技能会根据代码本身还原代码库的心智模型。

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

核心原则

1. 优先为人编写——使用清晰易懂的文字，让新开发者能够阅读和理解。提升 Agent 实用性是优质人类写作的副作用，而不是独立目标。
2. 展示，而不只是讲述——使用 ASCII 图展示架构和流程，使用 Markdown 表格呈现结构化信息，并使用反引号标注所有文件路径、命令和代码引用。
3. 六个各有价值的章节——每个章节都要回答新贡献者在入职第一小时会提出的问题。不得添加推测性章节。如果项目纯属基础设施，且没有使用方，可以跳过第 2 节，最终生成五个章节。
4. 陈述可观察到的事实，不要推断——不要捏造设计理由或评估脆弱性。如果代码没有揭示某项决策的原因，就不要猜测。
5. 绝不包含机密——入门文档会提交到代码仓库。绝不能包含 API 密钥、令牌、密码、带凭据的连接字符串或任何其他机密值。仅引用环境变量的名称（如 STRIPE_SECRET_KEY），绝不引用其值。如果 .env 文件包含实际机密，只提取变量名。
6. 提供链接，不要重复——如果现有文档已充分介绍某个主题，请在文中添加链接，而不是重新解释。

执行流程

阶段 1：收集清单

运行随附的清单脚本（scripts/inventory.mjs），在不读取每个文件的情况下获取代码仓库的结构概览：

node scripts/inventory.mjs --root .

解析 JSON 输出。输出包含以下信息：

• 项目名称、语言、框架、包管理器、测试框架
• 目录结构（顶层目录，以及源码目录下一级的目录）
• 各检测到的生态系统的入口点
• 可用脚本和命令
• 现有文档文件（含用于初步判断的首个标题）
• 测试基础设施
• 基础设施和外部依赖项（环境变量文件、Docker 服务、检测到的集成）
• Monorepo 结构（如适用）

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

阶段 2：阅读关键文件

根据清单，阅读有助于理解代码库的关键文件。使用原生文件读取工具（而非 shell 命令）。

阅读内容及原因：

如果文件之间不存在依赖关系，请分批并行阅读。例如，可在同一轮中一起阅读 README.md、入口文件和 AGENTS.md/CLAUDE.md，因为这些文件的内容彼此无关。

只阅读编写六个部分所需的具体、详细内容。清单已提供项目结构、语言、框架、脚本和入口文件路径——不要为了再次确认清单中已有的信息而重读文件。不同仓库需要阅读的文件数量各不相同；小型 CLI 工具可能只需阅读 4 个文件，复杂的单体仓库可能需要阅读 20 个文件。根据各部分的需求决定阅读内容，不要按任意数量阅读。

优先级顺序：

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 本身——只能读取 .env.example 或 .env.sample 模板。只提取变量名，绝不提取变量值。
5. AGENTS.md 或 CLAUDE.md（如果存在）——了解项目中已记录的约定和模式。
6. 已发现的文档——清单的 docs 列表包含每个文件的标题（第一个标题）。先根据标题判断哪些文档与五个部分直接相关，再决定是否阅读。仅阅读标题表明与内容直接相关的文档。除非重点提示特别要求，否则跳过带日期的头脑风暴/计划文件。

不要推测性地阅读文件。每次文件读取都必须有清单输出作为依据，并且能对应到所需的某个部分。

第 3 阶段：编写 ONBOARDING.md

将清单数据和关键文件内容整理到下方定义的各个部分中。将文件写入仓库根目录。

标题：使用 # {Project Name} Onboarding Guide 作为文档标题。根据清单确定项目名称。不要使用文件名作为标题。

写作风格——文档读起来应该像一位熟悉项目的队友和你喝咖啡时介绍项目，而不是像自动生成的文档。

语气和风格：

• 使用第二人称（“你”），直接与新贡献者交流
• 使用主动语态和现在时：“路由器将请求分发给处理程序”，而不是“请求由路由器分发给处理程序”
• 直截了当。先说重点，不要先铺垫：“运行 bun dev 启动服务”，而不是“为了启动开发服务，你需要运行以下命令”
• 贴合代码库的正式程度。随性的原型可以采用轻松的行文；企业系统则使用更严谨的措辞。参考 README 和现有文档的语气。

清晰度：

• 每句话都应该让读者学到东西或告诉他们该做什么。删掉没有这两种作用的句子。
• 优先使用具体表述，而非抽象表述：“src/services/billing.ts 会从客户的卡中扣款”，而不是“计费模块负责处理与付款相关的业务逻辑”
• 引入术语时，立即结合上下文进行定义。不要让读者滚动页面去查术语表。
• 使用准确且最简单的词。“使用”而不是“利用”，“启动”而不是“初始化”，“发送”而不是“传输”。

避免以下内容：

• 填充语和铺垫语：“需要注意的是”“如上所述”“本节将介绍”
• 含糊的概述：“此模块处理各个方面……”——具体说明它做什么
• 陈述事实时使用模棱两可的词：“这基本上充当……”“这本质上是……”——如果你知道它做什么，就直截了当地说
• 最高级和营销用语：“健壮”“强大”“全面”“无缝”
• 对文档本身的元评论：“本文档旨在……”——直接说明内容

格式要求——全文保持一致：

• 所有文件名（package.json）、路径（src/routes/）、命令（bun test）、函数名/类名、环境变量和技术术语都使用反引号
• 每个章节使用 Markdown 标题（##）
• 在指定位置使用 ASCII 图表和 Markdown 表格
• 少量使用粗体强调
• 段落保持简短，每段 2–4 句

章节分隔符——在每个 ## 章节之间插入水平分隔线（---）。这类文档内容密集，使用明显的视觉分隔线有助于快速浏览。

代码块宽度限制：最多 80 列。 Markdown 代码块会以 white-space: pre 方式渲染，不会自动换行，因此过长的行会导致读者在 GitHub、平板电脑和窄视口上横向滚动。以下规则适用于所有 ``` 围栏中的内容：

• ASCII 架构图：将方框垂直排列，不要横向排列。每行最多放置 2 个方框，每个方框标签不得超过 20 个字符。这样图表宽度可控制在约 60 个字符以内。
• 流程图：文件路径和注释合计不得超过 80 个字符。如果描述过长，请移到下一行或缩短描述。
• 目录树：行内 # 注释不得超过 30 个字符。优先使用简短的职责说明（“编辑器插件”），而不是罗列所有内容（“标记、热力图、建议、协作光标等”）。

第 1 节：这是什么？

回答：这个项目有什么作用？面向谁？解决了什么问题？

参考 README.md、清单描述（例如 package.json 描述字段），以及入口文件所体现的应用用途。

如果无法从代码中明确判断项目用途，请直言：“本文档未说明此项目的用途。根据代码结构，它似乎是……”

请控制在 1–3 个段落内。

第 2 节：如何使用

回答：从使用者的角度来看，这个项目是什么样的？

在能够分析架构之前，贡献者需要了解项目从外部来看做什么。本节衔接“这是什么”（第 1 节）和“它是如何构建的”（第 3 节）。与本文档其他部分一样，本节面向新加入团队的开发者。目标是展示产品在使用者视角下的样貌，让后续章节中的架构和代码流程更容易理解。

根据项目的使用者类型，在输出中为本节命名：

• 面向终端用户的产品（Web 应用、移动应用、消费级工具）——标题：“用户体验”。描述用户能看到的内容和主要工作流（例如“注册、创建项目、邀请协作者、查看实时更新”）。参考路由、入口文件和 README。
• 开发者工具（SDK、库、开发者 CLI、框架）——标题：“开发者体验”。描述开发者如何使用该工具：安装、展示主要 API 接口的最小用法示例，以及最常见的 2–3 个命令或模式。这不同于第 6 节（开发者指南），后者介绍如何为此代码库做贡献；本节介绍如何使用此代码库产出的内容。
• 两者兼有（同时提供面向用户的产品和开发者 API/SDK 的平台）——标题：“用户与开发者体验”。涵盖两种视角，先介绍终端用户体验，再介绍面向开发者的部分。

每种受众的内容控制在 1–3 个段落，或采用简短流程说明。如果已有完整的用户或开发者文档，请链接到文档，并用一句话概述关键工作流。不要重复现有文档。

仅在没有使用者的代码库中跳过本节（纯基础设施、无需直接交互的内部部署工具）。

第 3 节：项目是如何组织的？

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

本节涵盖内部结构和系统边界——也就是应用会与自身之外的哪些对象交互。

系统架构——有两种图示可以帮助新贡献者了解项目，是否使用其中一种或两种，取决于系统的复杂程度：

1. 架构图——展示组件、组件之间的连接方式，以及使用的协议或传输方式。开发者可以通过它了解代码位于何处，以及各部分如何交互。在线条上标注交互类型（HTTP、WebSocket、桥接、队列等）。从上到下依次排列面向用户的界面、中间的内部基础设施，以及底部的数据存储和外部服务。

2. 用户交互流程——展示用户使用产品时的逻辑路径。它关注的不是基础设施，而是从用户视角出发会发生什么——操作步骤的顺序，以及系统如何响应。

何时使用其中一种或两种：

• 对于简单的系统（单个 Web 应用、CLI 工具、简单的 API），架构图已经能说明用户使用过程——一张图就够了。请求在各组件中的路径就是用户流程。
• 对于有多个使用界面的产品（原生应用 + Web + API），或包含多种不同用户类型的系统，请同时提供两张图。架构图展示各部分如何连接，帮助开发者理解系统；用户交互流程展示产品在这些部分之间的逻辑体验。这是观察同一系统的不同视角。

使用垂直排列，使图示宽度不超过 80 列。

架构图示例：

       User / Browser
            |
            |  HTTP / WebSocket
            v
+------------------+    bridge    +------------------+
| Browser Client   |<----------->| Native macOS App |
| (Vite bundle)    |             | (Swift/WKWebView)|
+--------+---------+             +--------+---------+
         |                                |
         |  WebSocket                     |  bridge
         v                               v
+------------------------------------------+
|            Express Server                |
|  routes -> services -> models            |
+--------------------+---------------------+
                     |
                     |  SQL / Yjs sync
                     v
              +--------------+
              | SQLite + Yjs |
              +--------------+

用户交互流程示例（同一系统，不同视角）：

User opens app
  |
  v
Writes/edits document
  (Milkdown editor)
  |
  v
Changes sync in real-time
  (Yjs CRDT)
  |                \
  v                 v
Document persists   Other connected
  to SQLite         clients see edits
  |
  v
User shares doc
  -> generates link
  |
  v
Recipient opens
  in browser client

对于简单项目（单一用途的库、CLI 工具），如果目录树已经能说明整体情况，则两种图示都可以省略。

内部结构——提供一个 ASCII 目录树，展示项目的高层布局：

project-name/
  src/
    routes/       # HTTP route handlers
    services/     # Business logic
    models/       # Data layer
  tests/          # Test suite
  config/         # Environment and app configuration

为目录添加简短注释，说明其用途。仅包含重要目录——省略构建产物、配置文件和样板内容。

如果存在职责明确、彼此有区别的模块或组件，请用表格列出：

| Module | Responsibility |
|--------|---------------|
| `src/routes/` | HTTP request handling and routing |
| `src/services/` | Core business logic |
| `src/models/` | Database models and queries |

说明模块之间如何连接——谁调用谁，以及数据如何在它们之间流动。

外部依赖和集成——列出系统在自身代码库之外交互的一切对象。这通常是新贡献者尝试运行项目时遇到的最大障碍。可以从以下线索中查找：

• docker-compose.yml（数据库、缓存、消息队列）
• 配置文件或 .env.example 中的环境变量引用
• 客户端库的导入语句（数据库驱动、API SDK、云存储）
• 项目清单检测到的框架（例如，Prisma 表明项目使用了数据库）

如果有多个依赖，请用表格列出：

| Dependency | What it's used for | Configured via |
|-----------|-------------------|---------------|
| PostgreSQL | Primary data store | `DATABASE_URL` |
| Redis | Session cache and job queue | `REDIS_URL` |
| Stripe API | Payment processing | `STRIPE_SECRET_KEY` |
| S3 | File uploads | `AWS_*` env vars |

如果未检测到外部依赖，请明确说明：“该项目似乎是自包含的，没有外部服务依赖。”

第 4 节：关键概念和抽象

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

本节涵盖两方面：

领域术语——项目特有的词汇：实体名称、API 资源名称、数据库表、配置概念，以及新读者不容易立即理解的行话。

架构抽象——塑造代码组织方式，以及贡献者应如何考虑进行更改的代码库结构模式。这对于原作者可能并未有意识地选择这些模式的代码库尤其重要——这些模式可能由 AI 引入，或从模板中采用，却没有文档说明。

值得列出的架构抽象示例：

• “业务逻辑位于服务层（src/services/），而不是路由处理程序中”
• “每个受保护的路由都会先经过 src/middleware/auth.ts 中间件进行身份验证”
• “数据库访问采用仓储模式——每个模型都有对应的仓储类”
• “后台任务定义在 src/jobs/ 中，并通过 Redis 支持的队列进行分派”

将领域术语和抽象放在同一张表格中：

| Concept | What it means in this codebase |
|---------|-------------------------------|
| `Widget` | The primary entity users create and manage |
| `Pipeline` | A sequence of processing steps applied to incoming data |
| Service layer | Business logic in `src/services/`, not handlers |
| Middleware chain | Requests flow through `src/middleware/` first |

目标为 5-15 个条目。只纳入会让新读者困惑的概念，或代表不明显架构决策的概念。略过普遍理解的术语。

第 5 节：主要流程

回答：当这个应用的主要功能实际运行时，会发生什么？

针对每种不同的界面或用户类型，追踪一条流程。“界面”指进入系统的路径存在实质差异——例如原生应用、Web UI、API 调用方或 CLI 用户。每条流程都应揭示前面流程尚未涵盖的架构部分。当下一条流程大多只是再次经过已展示的文件时，就停止。

对于简单的库或 CLI，一条流程即可。对于带有 Web UI 和 API 的全栈应用，需要两条。对于同时提供原生、Web 和 Agent 界面的产品，则需要三条。流程数量应由架构决定，而不是任意设定。

为最重要的流程添加 ASCII 流程图：

User Request
  |
  v
src/routes/widgets.ts
  validates input, extracts params
  |
  v
src/services/widget.ts
  applies business rules, calls DB
  |
  v
src/models/widget.ts
  persists to PostgreSQL
  |
  v
Response (201 Created)

在每个步骤中引用具体的文件路径。文件路径和注释应少于 80 个字符——如有需要，将注释放在下一行（如上所示）。

如果第一张图已经说明了结构模式，其他流程可以改用编号列表，无需绘制完整流程图。

第 6 节：开发者指南

回答：如何设置项目、运行项目并进行常见修改？

涵盖以下方面：

1. 设置 —— 先决条件、安装步骤、环境配置。参考 README 和清单中的脚本。命令请放在代码块中：

   bun install
   cp .env.example .env
   bun dev
   

2. 运行和测试 —— 如何启动开发服务器、运行测试、执行 lint。使用清单中检测到的脚本。

3. 常见修改模式 —— 说明进行 2-3 种最常见类型的修改时应从哪里入手。例如：

   • “要添加新的 API 端点，请在 src/routes/ 中创建路由处理器，并在 src/routes/index.ts 中注册”
   • “要添加新的数据库模型，请在 src/models/ 中创建文件，然后运行 bun migrate”

4. 关键入门文件（适用于复杂项目）—— 使用表格将代码库中的不同区域映射到具体的入口文件，并简要说明“为何从这里入手”。这能为新贡献者提供一份具体的阅读清单，而不是让他们面对庞大的目录树无从下手。例如：

   | Area | File | Why |
   |------|------|-----|
   | Editor core | `src/editor/index.ts` | All editor wiring |
   | Data model | `src/formats/marks.ts` | The annotation system everything builds on |
   | Server entry | `server/index.ts` | Express app setup and route mounting |
   

   如果项目的源文件少于约 10 个，且目录树本身已足以作为阅读清单，则跳过此项。

5. 实用提示（适用于复杂项目）—— 如果代码库中有特别庞大、复杂或存在不易察觉陷阱的部分，请将它们整理成简短的贡献者提示。这些提示能体现对项目实际情况的了解，帮助新贡献者避免踩坑。例如：

   • “编辑器模块约有 450KB。大多数行为都通过 src/editor/plugins/ 中的插件接入 —— 修改编辑器之前，请先了解插件架构。”
   • “协作子系统包含许多保护逻辑和 epoch 检查。阅读测试名称，了解维护了哪些不变量。”

   对于规模小到可以轻松掌握的简单项目，请跳过此项。

行内文档链接

编写每个章节时，请检查清单的 docs 列表中是否有与章节内容直接相关的文件。如有，请在文中添加链接：

身份验证使用基于令牌的中间件 —— 完整模式请参阅 docs/solutions/auth-pattern.md。

不要单独创建参考资料或延伸阅读章节。如果某个章节没有相关文档，就让该章节独立呈现，不要提及缺少相关文档。

阶段 4：质量检查

写入文件前，请确认：

• 每个部分都直接回答对应问题，没有冗余或填充内容
• 文档中没有任何机密、API 密钥、令牌、密码或凭证值
• 没有虚构的设计理由（“我们选择 X 是因为……”）
• 没有脆弱性或风险评估
• 文档中引用的文件路径都对应清单中的真实文件
• 所有文件名、路径、命令、代码引用和技术术语都使用反引号格式
• 文档标题采用“# {Project Name} Onboarding Guide”格式，而不是文件名
• 对于多界面项目，包含系统级架构图（简单的库或 CLI 可跳过）
• 所有代码块内容（图表、目录树、流程跟踪）都不超过 80 列
• 架构和／或主要流程部分包含 ASCII 图表
• 每种不同的界面或用户类型各有一个流程（数量由架构决定，不随意指定）
• 架构部分说明外部依赖和集成（或明确说明不存在）
• 使用表格说明模块职责、领域术语／抽象和外部依赖
• Markdown 样式始终保持一致（标题、粗体、代码块、表格）
• 仅在直接相关处内联链接现有文档
• 写作直接具体，不含填充内容、模糊措辞或关于文档本身的元评论
• 语气与代码库相符（小型项目可轻松随意，企业项目则精准严谨）
• 包含“How It’s Used”部分，标题根据受众调整为“用户体验”“开发者体验”或两者；纯基础设施且没有使用者时才可跳过
• 架构图包含带标签的边（协议／传输方式）；如果系统有多个界面或用户类型，还需包含用户交互流程图

将文件写入仓库根目录，命名为 ONBOARDING.md。

阶段 5：呈现结果

写入文件后，告知用户已生成 ONBOARDING.md。如果平台提供阻塞式提问工具，请使用该工具提供后续选项（Claude Code 中使用 AskUserQuestion，Codex 中使用 request_user_input，Gemini 中使用 ask_user）。否则，在聊天中列出编号选项。

选项：

1. 打开文件进行审核
2. 分享到 Proof
3. 完成

根据用户选择：

• 打开审核 -> 使用当前平台的文件打开或编辑器机制打开 ONBOARDING.md
• 分享到 Proof -> 上传文档：

  CONTENT=$(cat ONBOARDING.md)
  TITLE="Onboarding: <project name from inventory>"
  RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
  PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
  

  如果成功，显示 View & collaborate in Proof: <PROOF_URL>，然后返回选项
• 完成 -> 不执行其他操作