项目文档生成技能（project-documentation）：用 6 阶段分层法，把陌生代码库变成一套能读懂的文档体系
- 它是一套"方法论 + 模板"的文档生成技能，不是单点工具：按"理解 → 结构化 → 核心文档 → 函数 → 入门 → 维护"6 个阶段推进，而不是上来就让 AI 直接写 README。
- 产出是一整套
docs/目录：涵盖架构概览、代码演练、API 参考、安装配置、新手入门五类文档，层次分明。 - 强调"先探索、后动笔"：要求先读 git 历史、目录结构、测试用例与执行流，再开始组织内容，避免写出"看起来对、实际全是猜测"的文档。
- 内置文档优先级排序：README 与安装指令 → 架构图 → 入口点 → 核心模式 → 关键函数 → 边缘情况，保证时间有限时先写最有价值的部分。
- 适合遗留项目接手、新成员入职、开源项目补文档、技术交接等场景，把"读代码猜意图"的过程变成可复用的资产。
该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能基本信息
| 项目 | 内容 |
|---|---|
| 技能中文名 | 项目文档生成技能 |
| 技能英文名 | project-documentation |
| 技能ID | 11843 |
| 技能类型 | 代码库扫描与分层文档生成 |
它解决什么问题
接手一个陌生仓库时，开发者最常遇到的困难是：README 只有两行、注释散落各处、入口点埋在 src/ 深处、数据流要自己顺藤摸瓜。传统做法是花几天读代码再补文档，或者干脆不写、让知识停留在个人脑中。这个技能把"读懂代码 → 写成文档"这个高频动作标准化，用一套明确的分层结构和扫描清单，让 AI 按步骤产出可维护的文档体系。
"一键安装"的思路与步骤
它的安装本质是：把技能包挂载到支持 Skill 机制的 AI 编程环境里，让 AI 在对话中自动获得这套 6 阶段文档方法论和配套模板。具体步骤：
- 确认前提：使用环境需支持 AI 技能（Skill）机制，并对目标代码仓库具备读取权限；部分步骤（如分析 git 历史、输出目录树）需要能执行
git、tree等命令。若环境为纯对话式、不能执行命令，也可以手动把关键信息贴给 AI 代替。 - 按技能ID检索：在技能市场或技能管理面板中，用技能ID
11843或英文名project-documentation检索该技能。 - 一键安装 / 添加：点击安装或"添加到当前工作区"，技能会自动注册到当前会话的可用技能列表中。
- 验证是否生效：新建一个会话，对 AI 说"请用项目文档生成技能扫描当前仓库，先只输出文档计划和目录结构，不要写正文"。如果它返回的是 6 阶段流程 +
docs/分层结构（architecture / walkthroughs / api / setup / onboarding），说明技能已成功加载；如果只是泛泛回答"我可以帮你写文档"，则说明未生效，需要检查安装状态。 - 确认模板可用：技能内置了 README、架构、演练、API 参考、设置指南等模板，可先让它"列出可用的模板文件"，确认模板已随技能一并挂载。
说明：具体的安装命令、入口位置、是否需要账号或付费，随承载平台不同而不同，请以官方说明为准。本文只描述通用思路，不虚构具体命令。
该技能的主要功能和特点
- 6 阶段文档方法：理解 → 结构化 → 核心文档 → 函数 → 入门 → 维护，每个阶段都有明确动作，避免"想到哪写到哪"。
- 三层文档分层：高层（架构与设计原则，面向新人与利益相关者）、中层（流程、模式、交互，面向贡献者）、低层（函数、参数、返回值，面向维护者），不同读者看不同层，互不干扰。
- 代码库扫描清单：内置 13 项扫描动作，包括分析版本控制历史、识别项目类型与框架、文档化入口点、映射目录结构、列出依赖、识别关键模式、文档化配置文件等，逐项执行，不易遗漏。
- 测试驱动理解：明确要求阅读测试代码——测试揭示代码"预期如何工作"，失败的测试历史反映曾经修复过的问题，测试结构往往镜像代码架构，这是很多文档生成方案忽略的信息源。
- 函数文档强调"意图"：不只写"这个函数做了什么"，而是写清楚为什么这样做、业务假设是什么、有哪些设计权衡，并附使用示例。
- 内置五类模板：README 模板、架构概述模板、演练指南模板、API/函数参考模板、设置指南模板，输出格式统一，团队协作时风格一致。
- 入门导向写作规范：清晰语言、避免未解释的行话、代码片段佐证、命名一致、解释决策理由，专为"让新人自定步调学习"设计。
- 可维护性设计：文档与源码一起版本化、保持可搜索、从团队沟通渠道链接、随代码演进逐步改进，把文档当作长期资产而非一次性交付物。
- 明确的优先级顺序：README 与安装指令优先，其次是架构图、入口点、核心模式、关键函数，最后才处理边缘情况与陷阱——时间紧时也不会把精力浪费在低价值内容上。
和普通"让 AI 写段 README"的做法相比，它的差异在于：有流程、有分层、有清单、有模板、有优先级，产出的是结构化的文档体系，而不是一段美化过的说明文字。
如何使用该技能？
第 1 步：触发技能并限定范围
首次使用时，建议先限定范围，避免一次性扫全仓库导致输出过长。示例提示词：
请使用项目文档生成技能，扫描
src/目录（不含node_modules），先完成阶段 1"文档化前理解"，输出你观察到的框架类型、入口点、目录结构和关键模式，不要生成正文。
第 2 步：让技能执行扫描
技能会按清单推进：查看近期提交记录、贡献者分布、分支历史，分析目录树（它会使用类似 tree -L 3 -I node_modules 的层级限制思路），识别 main.* / index.* / app.* 等入口文件，检测 React、Express、FastAPI 等框架特征，并阅读测试推断预期行为。
第 3 步：确认分层文档规划
扫描完成后，让它输出文档规划表，确认三个文档层分别写什么、放在哪个目录。此时你可以干预，例如：“我们团队最缺的是新人上手材料，请把 onboarding/ 提到优先级第一位。”
第 4 步：按优先级生成核心文档
按技能默认顺序生成：README 与安装说明 → 架构概览与组件图 → 入口点文档 → 数据流与模式 → API/函数参考 → 边缘情况与陷阱。建议分批生成，每批完成后人工确认，避免整批返工。
第 5 步：函数级文档补充意图
对关键模块，要求按"描述原因而非仅描述内容"的原则补注释。示例提示词：
请为
src/services/payment.ts中的 5 个导出函数生成文档，说明业务假设、参数含义、返回值和典型调用示例，重点解释为什么这样设计，而不只是描述做了什么。
第 6 步：整理输出结构
最终产出按技能约定的目录组织：
docs/
├── README.md # 项目概述
├── architecture/ # overview.md、components.md、diagrams/
├── walkthroughs/ # entry-points.md、data-flow.md、patterns.md
├── api/ # endpoints.md、functions.md
├── setup/ # installation.md、configuration.md、troubleshooting.md
└── onboarding/ # quickstart.md、tutorials/、gotchas.md
第 7 步：对照扫描清单验收
让技能按 13 项扫描清单逐条自查：入口点是否已文档化、依赖是否已列出、关键模式是否已识别、README 是否已更新、架构概述与演练指南是否完备。清单里打不勾的项，就是还需要补的部分。
第 8 步：纳入版本化与维护
把 docs/ 与源码一起提交，在 PR 模板中加入"是否同步更新文档"的检查项，并定期让技能重扫一次，标记出与代码已经脱节的段落。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 项目文档生成技能（project-documentation） | 面向代码库的分层文档生成技能 | 6 阶段方法、三层文档结构、扫描清单、五类模板、函数意图文档 | 需支持 Skill 机制的环境，安装后对话触发；需仓库读权限 | 遗留项目接手、新人入职、技术交接、开源项目补文档 | 优势：流程与结构完整，产出可直接落盘成 docs/ 体系；不足：需要人工分批确认，超大仓库需限定扫描范围 |
| 通用 AI 对话助手（直接粘贴代码提问） | 通用问答 | 解释代码片段、生成说明文字 | 极低，打开即用 | 临时看懂某个函数、写一段说明 | 优势：零门槛；不足：无分层结构、无扫描流程、跨文件一致性差，容易写成"泛泛而谈" |
| Docusaurus / MkDocs 等静态站点生成器 | 文档站点框架 | 把 Markdown 组织成可搜索的文档网站、主题、导航 | 需初始化项目、配置导航与插件 | 对外文档站、产品手册 | 优势：呈现效果好、可搜索；不足：只解决"怎么展示"，不解决"内容从哪来"，仍需人写正文 |
| Sphinx + autodoc / JSDoc / TSDoc 等注释抽取工具 | 代码注释抽取 | 从源码注释自动生成 API 参考 | 需按规范写注释、配置构建流程 | 库/SDK 的 API 手册 | 优势：与代码强绑定、更新及时；不足：只覆盖低层 API，无法生成架构概览、演练指南与入门材料，注释质量依赖开发者自律 |
对比结论：静态站点生成器解决"展示"，注释抽取工具解决"低层 API 自动化"，通用 AI 解决"临时看懂一段代码"；而项目文档生成技能补的是中间的空白——从代码库中系统性提炼出架构、流程、模式与入门路径，并且给出了明确的分层和优先级。
该技能的典型应用场景与实际体验情况
场景一：新成员入职一家中型 SaaS 公司
痛点是新人前两周基本在"读代码 + 问同事"中度过，老员工被反复打断。使用方式是让技能先产出 onboarding/quickstart.md 与 walkthroughs/entry-points.md，再做一次 30 分钟的走查。实际体验：入口点文档对新人的帮助最直接，能明显缩短"找到第一行代码在哪"的时间；但如果项目缺少测试，需要人工补充说明，因为技能严重依赖测试来推断预期行为。
场景二：接手遗留项目或外包交接
痛点是代码没有文档、原作者已离职、业务逻辑藏在命名混乱的函数里。使用方式是先让它完成阶段 1 的探索，输出框架识别、目录映射、依赖列表和关键模式；再重点生成 architecture/overview.md 和 onboarding/gotchas.md。实际体验：gotchas.md（边缘情况与陷阱）是惊喜项，把"新手最容易踩的坑"显式写出来，比架构图更能减少事故；注意扫描范围要限定，否则大仓库输出会非常长。
场景三：开源项目补齐贡献者文档
痛点是 README 只有安装三行命令，外部贡献者不知道从哪改起。使用方式是生成 walkthroughs/patterns.md 与 api/functions.md，并在 README 中链接。实际体验：模式文档（“这个项目里重复出现哪些写法”）对 PR 质量提升明显，贡献者能照着既有模式写代码；建议生成后人工校对命名与示例，确保与真实代码一致。
场景四：技术交接与知识沉淀
痛点是核心模块只有一个人懂，团队存在单点风险。使用方式是针对核心模块做低层函数文档，重点写"为什么这样设计"的决策理由。实际体验：写"意图"比写"行为"费力，但半年后回看价值最高；建议把它纳入 PR 流程，而不是一次性运动式补文档。
上手难度与注意事项：整体上手难度低，关键是第一次使用时不要"一把梭"，而是按阶段确认；技能给出的内容是初稿，涉及业务假设的部分必须由熟悉业务的人复核。
该技能能为用户带来的价值
- 把"读代码"的时间变成"读文档"的时间：新人上手从"逐文件翻阅"变成"按分层文档自定步调学习"，减少对老员工的重复打扰。
- 降低文档写作的启动门槛：很多人不写文档，不是因为不想写，而是不知道从哪写起。技能给出的优先级顺序（README → 架构 → 入口点 → 模式 → 函数 → 陷阱）直接把"从哪开始"这个问题解决了。
- 提升文档质量的一致性：五类模板统一了结构，不同人、不同模块产出的文档风格接近，避免出现"每篇文档都像不同项目"的情况。
- 减少知识单点风险：把"只有一个人懂"的隐性知识，转化为可搜索、可版本化、可交接的显性资产。
- 可量化的收益方向：可观察的指标包括新人首次提交 PR 的时间、重复性提问数量、交接期间的故障率、文档覆盖率（对照 13 项扫描清单的完成度）。具体提升幅度取决于项目规模与团队执行力度，建议先在小范围试点再评估。
- 长期价值：文档与源码一起版本化、随代码演进逐步改进，让文档成为持续维护的资产，而不是一次性的"补作业"。
常见问题 FAQ
Q1：怎么安装这个技能？安装后怎么确认生效？
在支持 AI 技能机制的环境里，用技能ID 11843 或英文名 project-documentation 检索并一键安装，然后新建会话，让它"先只输出文档计划"，如果能返回 6 阶段流程和 docs/ 分层结构，就说明已生效。具体安装入口与命令随平台不同，以官方说明为准。
Q2：这个技能收费吗？
技能本身的定价由承载平台决定，请以官方说明为准。需要注意的是，运行过程会消耗 AI 模型的调用额度，超大仓库建议限定扫描范围以控制成本。
Q3：它适合谁用？小项目有必要吗？
最适合三类人：接手陌生代码库的开发者、负责新人入职的 Tech Lead、需要维护开源项目文档的维护者。小项目如果只有一两个文件，收益有限；但只要项目超过"一个人能记住全部逻辑"的规模，分层文档就开始产生价值。
Q4：它生成的文档可以直接发布吗？
建议当作高质量初稿。架构、模式、入口点这类可从代码推断的内容准确度较高；涉及业务背景、设计权衡、历史决策的部分，需要熟悉业务的人补充与复核，尤其是"为什么这样做"的内容。
Q5：和 Docusaurus、Sphinx 这类工具是什么关系？
不冲突，是互补关系。本技能负责"内容生产"——从代码库中提炼出架构、演练、API、入门等文档；Docusaurus、MkDocs 负责"内容展示"，把 Markdown 变成可搜索的文档站；Sphinx autodoc、JSDoc 负责"低层 API 自动抽取"。典型组合是：先用本技能生成结构化文档，再交给站点生成器发布。