代码库上板Skill：一键读懂陌生代码库，自动生成 ARCHITECTURE.md
- 它是什么：一个专门用来"上板"（onboarding）的 AI 技能，系统化探索陌生代码库，最终在仓库根目录产出一份结构完整的
ARCHITECTURE.md。 - 解决什么痛点：接手新项目、贡献开源仓库、隔了半年回头看自己代码时，最耗时的不是写代码，而是"搞清楚它是怎么运转的"。
- 产出什么：一份包含技术栈表、Mermaid 组件图、关键抽象、模式与约定、开发工作流命令、入口点清单、目录结构注释的架构文档。
- 安全边界清晰：技能只被允许使用
Read、Grep、Glob以及find、wc、ls这类只读命令，写入权限仅用于生成文档，不改动业务代码。 - 怎么用：在仓库根目录执行
/onboard，无需任何参数，它探索的就是当前工作目录。
该技能叫什么？如何下载安装 AI 技能提升开发效率？
中文名：代码库上板 英文名：onboard 技能 ID：11941
这个技能的名称很形象——"上板"即 onboarding 的意译，指新人或新接手者"登上"一个项目的甲板，先摸清船的结构再动手干活。它要解决的问题非常具体：当你面对一个完全陌生的代码库时，如何用最短时间建立一张准确的"地图"。
传统做法是翻 README、点开几十个目录、在 IDE 里跳转定义，靠人脑拼图；而这个技能把这件事变成一条可复用的流水线——从仓库结构扫描，到技术栈识别、入口点定位、组件关系映射，最后把结论沉淀成一份可长期维护的 ARCHITECTURE.md。
「一键安装」的思路与步骤
AI 技能的安装方式通常与其所依托的平台强绑定，本技能的详情中并未给出具体的命令行安装指令，因此这里给出通用的操作路径，具体命令与入口请以官方说明为准：
第一步：确认安装前提
- 你使用的 AI 编码助手 / 客户端需要支持"技能（Skill）"这一扩展机制，并能识别技能的
name、description等元信息。 - 你的工作环境需要能访问该技能所属的技能市场或插件仓库。
- 建议在本地已克隆好的仓库中使用，因为技能需要读取真实文件系统。
第二步：通过技能 ID 或名称检索安装
在技能市场 / 插件市场中，以技能 ID 11941 或名称 onboard / 代码库上板 进行检索，找到条目后按平台提示完成启用。从技能配置可以看到几个值得注意的字段，它们决定了它的运行方式：
agent: Explore与context: fork：说明它运行在一个独立的"探索型"子智能体上下文中，探索过程不会挤占你的主对话上下文空间。disable-model-invocation: true：说明它不会被模型自动触发，需要你显式调用——这也意味着不会在你没打算用的时候突然跑起来。allowed-tools白名单：Read、Grep、Glob、Bash(find *)、Bash(wc *)、Bash(ls *)、Write，权限收敛得非常克制。
第三步：验证是否生效
在任意一个已有代码的仓库根目录中调用 /onboard。如果技能生效，你会看到它开始按顺序执行"扫描顶层结构 → 读取配置文件 → 定位入口点"等动作，而不是简单地丢给你一段泛泛的总结。执行结束后，仓库根目录应出现 ARCHITECTURE.md 文件，且其中没有留下占位文本——这是技能自带质量清单中的一条硬性要求。
如果没有任何反应，优先检查两件事：当前目录是否是仓库根目录；技能是否处于启用状态。具体排错方式以官方说明为准。
该技能的主要功能和特点
- 系统化的七步探索工作流：调查仓库结构 → 识别技术栈 → 查找入口点 → 映射架构 → 梳理目录模式与约定 → 文档化开发工作流 → 编写
ARCHITECTURE.md。不是"随便看看"，而是有明确阶段和产出物的流程。 - 配置文件驱动的技术栈识别：它按优先级依次检查
package.json、Cargo.toml、go.mod、pyproject.toml、flake.nix、Makefile/Justfile、docker-compose.yml/Dockerfile、.github/workflows/*.yml、tsconfig.json、.tool-versions/.mise.toml等，从中提取语言、框架、包管理器、测试框架、格式化与代码检查工具。 - 自动绘制 Mermaid 组件图：把入口点、路由/处理器、服务层、数据访问层、数据库、外部 API 之间的关系画成图，且要求"根据实际发现的架构调整"，而不是套模板。
- 自动提取"隐性约定"：错误处理方式、API 请求/响应形状、测试文件命名与夹具习惯、状态管理方式、配置注入路径——这些恰恰是新人最容易踩坑、却最少被写进 README 的内容。
- 开发工作流命令有据可查：构建、测试、本地运行、部署的命令，要求从
Makefile/Justfile/package.json的scripts中核实后写入，避免编造命令。 - 自带质量检查清单：从"新人在 30 秒内能理解项目做什么"到"至少 3 个模式与约定被文档化并附示例"“入口点列出文件路径”“无占位文本剩余”，形成闭环。
- 和普通"AI 对话总结"的差异：普通对话助手往往只读 README 就下结论；本技能要求实际读取配置文件、读 2–3 个入口点源码、抽样阅读测试文件，并输出结构化、可提交入库的文档。
如何使用该技能？
第 1 步：进入目标仓库根目录
cd /path/to/your/repo
技能探索的是"当前工作目录"，所以位置很关键。
第 2 步：发起调用
/onboard
无需参数。这是一个"零输入"技能——它不问你项目是做什么的，而是自己去查。
第 3 步：观察它的探索动作
正常情况下你会依次看到：ls -la 列顶层结构、find . -maxdepth 3 -type d 输出目录树（排除 .git、node_modules、target、dist、.next 等干扰项）、按扩展名统计文件数量以判断主要语言、统计仓库文件总量。这些数字会直接进入文档的"仓库规模"上下文。
第 4 步：查看它生成的技术栈判断
技能会读取实际存在的配置文件。例如在一个 Node 项目里，它会读 package.json 的 dependencies 与 scripts；在 Rust 项目里读 Cargo.toml 的 [[bin]] 段；在 Nix 项目里读 flake.nix。你可以借此校验它是否"看对了"——如果判断偏了，通常说明仓库里有多个技术栈混用，需要你补一句说明。
第 5 步：检查组件图与数据流
打开生成的 ARCHITECTURE.md，重点看 Mermaid 图是否符合你的认知。图中通常形如：入口点 → 路由器/处理器 → 服务层 → 数据访问 → 数据库，以及服务层到外部 API 的分支。如果图里漏掉关键模块，说明该模块的组织方式不常规，值得你自己再确认一遍。
第 6 步：核对开发工作流命令
格外仔细地核对"构建 / 测试 / 本地运行"三节里的命令，是否与 Makefile、Justfile 或 package.json 的 scripts 完全一致。这是文档里最容易被后续使用者直接复制执行的部分。
第 7 步：把文档提交进仓库
ARCHITECTURE.md 由技能写在仓库根目录，你可以直接 commit，作为团队资产长期维护。文档顶部带有"由代码库探索自动生成 / 最后更新日期"的说明，方便后续判断新鲜度。
典型输出结构（节选）：
## 概述
[2-3句话：项目做什么、为谁服务、核心技术]
## 技术栈
| 层 | 技术 |
| 语言 | TypeScript 5.x |
| 框架 | Next.js 14 |
...
## 入口点
| 入口点 | 目的 | 文件 |
| 主 | 应用启动 | `src/main.ts` |
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| onboard（代码库上板） | 面向"接手者"的架构文档生成技能 | 七步探索工作流、技术栈识别、Mermaid 组件图、模式与约定固化、开发工作流提取、质量检查清单 | 需在支持 Skill 的平台启用（以官方说明为准），调用只需 /onboard 一条指令 |
新项目上板、开源仓库贡献、长期后回归、团队新人引导 | 优势：产出结构化可入库文档，权限白名单克制，只读为主；不足：一次面向单个仓库，文档质量依赖仓库配置文件的规范程度 |
| 人工阅读 README + 逐目录浏览 | 最传统的上板方式 | 靠人脑拼图，边看边记 | 零门槛 | 小仓库、结构简单的项目 | 优势：理解最深、能发现文档之外的"气味"；不足：耗时最长，结论留在个人脑子里，无法沉淀复用 |
| 通用 AI 对话助手直接提问 | 让模型"讲讲这个仓库" | 概览式总结、随机抽样解释 | 低，对话即可 | 快速获得模糊印象 | 优势：随时可用、交互灵活；不足：容易只读 README 就下结论，缺少系统性步骤，不产出可提交的结构化文档，也不保证覆盖入口点与约定 |
| 自动化 API 文档生成器（如 Doxygen / Sphinx / TypeDoc 等） | 从源码注释生成参考手册 | 提取函数、类、模块签名与注释 | 需配置与接入构建流程 | 已有良好注释的库、对外 API 文档 | 优势：精度高、可随代码自动更新；不足：回答的是"每个函数是什么"，而非"系统如何运转"，对数据流、约定、工作流几乎不覆盖 |
可以看到，这几类方案并非互相取代：注释文档工具回答"细节"，AI 对话回答"印象"，而 onboard 回答的是"地图"——三者可以叠加使用。
该技能的典型应用场景与实际体验情况
场景一：新员工入职第一天
角色：刚加入团队的开发工程师。痛点：拿到仓库地址后不知道从哪下手，问同事又怕打扰。使用方式：克隆仓库后在根目录执行 /onboard，半小时内拿到一份带组件图和构建命令的文档，边读边对照代码。实际体验：上手难度几乎为零——不需要写 prompt、不需要给参数。效果取决于仓库本身的规范程度：配置文件齐全（有 package.json、Makefile、CI 配置）的项目，产出质量明显更高。注意：它给的是"骨架"，业务语义仍需向人确认。
场景二：给开源项目提第一个 PR
角色：开源贡献者。痛点：想修一个 bug，但不知道代码该改在哪个模块，怕 PR 被拒。使用方式：/onboard 生成文档后，直接看"模式与约定"和"测试约定"两节，照着既有风格写测试、按既有方式处理错误。实际体验：这一节的价值往往高于组件图——它把"这个项目习惯怎么做"显性化了。注意事项：文档是快照，PR 前建议重新跑一次，或至少核对一下相关目录结构有没有变。
场景三：接手一个"前同事离职后无人维护"的仓库
角色：被临时指派的维护者。痛点：没有文档、没有交接、代码能跑但没人敢改。使用方式：先跑 /onboard 摸清技术栈和入口点，再顺着数据流逐个模块读。实际体验：这类仓库常见多语言混用（比如前端在根目录、后端在 server/），此时技能的技术栈判断可能出现偏移，需要人工校正后重跑或手工补充。这也是最需要"注意事项"提醒的场景。
场景四：给新成员做引导材料
角色：团队负责人 / Tech Lead。痛点：每次新人来都要口头讲一遍架构，内容还不一致。使用方式：把生成的 ARCHITECTURE.md 提交到仓库，作为固定引导材料；结构变化时重跑更新。实际体验：这是长期收益最高的用法——把一次性的"讲解"变成可版本化的团队资产。注意团队需建立"架构变了就重跑"的习惯，否则文档会腐烂。
该技能能为用户带来的价值
- 把"读代码"从玄学变成流程：七步工作流让上板有明确的阶段与产出物，不再依赖个人经验或运气。
- 显著压缩首次理解成本：过去需要半天到一天才能拼出的仓库全景，现在以一份结构完整的文档呈现，且开篇就要求"新人在 30 秒内能理解项目做什么"。
- 沉淀为可复用资产：产出物是仓库根目录下的 Markdown 文件，可以进版本库、可以在 Code Review 中被讨论、可以随代码演进重新生成，而不是留在某个人的脑海里。
- 降低新人打扰成本：团队里"这个项目怎么跑起来"的高频问题，答案直接写在文档的"开发工作流"一节，且命令有据可查。
- 风险可控：权限白名单之下，它只能读取文件和执行
find、wc、ls这类只读命令，写入仅用于生成文档，不会在你不知情的情况下改动业务代码。 - 长期价值在于"约定显性化"：错误处理方式、测试约定、配置注入路径这些隐性知识，一旦被写下来，就能减少大量"风格不一致"的返工。
常见问题 FAQ
Q1：这个技能怎么安装？在哪里能用？
A：它是一个 AI 技能，需要通过支持 Skill 机制的平台检索并启用，技能 ID 为 11941，名称是 onboard / 代码库上板。具体安装命令、入口位置以官方说明为准。启用后即可在仓库根目录用 /onboard 调用。
Q2：使用它收费吗？
A：技能详情中未包含任何定价信息，是否收费取决于你所使用的平台与订阅方案，请以官方说明为准。
Q3：它会不会改我的代码？
A：不会改业务代码。从技能配置看，它被允许使用的工具是 Read、Grep、Glob，以及 Bash(find *)、Bash(wc *)、Bash(ls *) 这三个只读类命令，写权限（Write）用于产出 ARCHITECTURE.md。
Q4：什么项目适合用？小项目是不是没必要？
A：适合任何"你需要快速搞懂它"的仓库，尤其是接手开源项目、加入新团队、长期未接触后回归的场景。很小的仓库收益会打折扣——但如果你打算把它作为团队引导材料，即使小项目也值得生成一份。
Q5：它和直接问 AI「讲讲这个仓库」有什么区别？
A：区别在系统性。直接提问往往只读 README 就给结论；而该技能要求实际扫描目录、读取配置文件、阅读 2–3 个入口点源码、抽样阅读测试文件，并按规定结构输出，最后还过一遍质量检查清单（如"至少 3 个模式与约定被文档化并附示例"“无占位文本剩余”）。它产出的是可以提交进仓库的文档，而不是一段聊天记录。