把"读不完的项目"转化为"读得完、改得动、回得来"的技术文档树。
核心理念:主代理只做协调与整合,具体阅读交给并行子代理;每条产出都同时写到分层文档和迭代变更日志,绝不让发现散落在对话里。
适合:
不适合(请用其他 skill):
触发短语示例:
任何项目都按四层来沉淀,不要塞进一个文件:
Layer 1 功能目录 顶层目录(01-* ~ NN-*)按"业务/技术职责"分组
Layer 2 总体设计模块 每个模块的 README.md —— 边界 / 架构图 / 子能力清单 / 关键决策
Layer 3 能力设计 每个模块下的 0X-能力名.md —— 责任范围 / 入口 / 数据流 / 配置 / 已知限制 / 测试
Layer 4 迭代变更摘要 CHANGELOG.md —— 每次产出/修订的摘要 + 非显然发现 + 跨模块溢出为什么是这四层 —— 任何技术文档至少回答四个问题:整体长什么样(L2)、具体怎么做的(L3)、为什么要这么做(L2 关键决策)、最近发生了什么(L4)。L1 只是分类承载。
| 角色 | 职责 | 工具 |
|---|---|---|
| 主代理(协调者) | 侦察、骨架、分配、整合、横向矩阵、收尾 | Bash/Glob/Read/Write/Edit/TodoWrite/Agent |
| 子代理(深耕者) | 各自负责一个模块,深读源码,产出该模块全部文档,回报非显然发现 | general-purpose,可读可写 |
关键纪律:
general-purpose 类型(可写文件);Explore/Plan 类型不能写。10 份独立模块文档之上,主代理必须做一次"全局视角聚合":
没有横向矩阵的摸底 = 把"读不完"换成"读不出问题"。这个聚合是 skill 的核心价值,不可省略。
path/file.ext:line 格式 — 让读者一键跳转。打招呼 + 一句话确认你理解了任务:
"我会按照「主代理 + N 并行子代理 + 四层文档 + 横向矩阵」工作流来沉淀整个项目。先做侦察,再分配代理,最后整合。"
按存在性优先读取(并行 Bash):
CLAUDE.md(项目级 agent 指令)— 必读README.md / AGENTS.mddocs/architecture.md / 系统需求企划书*.mdpackage.json / go.mod / pyproject.toml / Cargo.toml(技术栈)docker-compose*.yml(服务拓扑).env.example(配置面)不要逐字读完,只看到能定位"项目是什么、用了什么、有几个 app"即可。
通过 ToolSearch 加载本 skill 必需的工具(如果尚未加载):
TodoWrite — 跟踪进度Glob / WebFetch / WebSearch# 顶层结构
ls -la <project_root>
ls <apps_or_packages_root>
# 服务/应用列表
find . -maxdepth 3 -name "package.json" -not -path "*/node_modules/*"
find . -maxdepth 3 -name "go.mod" -o -name "pyproject.toml"
# 后端关键路径(按语言适配)
ls <backend>/internal/handler /service /repository /model /middleware
ls <backend>/migrations | tail -20
# 前端
ls <frontend>/app /src
# 文档与基础设施
ls docs/ .github/ ops/ nginx/ scripts/ 2>/dev/null目标: 在不超过 8 个并行 Bash 调用内,得到:
经验法则:3 ≤ 模块数 ≤ 12(并行子代理硬上限通常是 10)。
按以下信号分模块:
packages/* 作为独立模块或并入设计系统模块典型拆分模板(全栈 web 应用,10 模块):
01-backend-auth-users 鉴权 / 用户 / 权限
02-backend-content 核心业务实体 1(如内容管理)
03-backend-domain-X 核心业务实体 2(如媒体/订单等)
04-backend-system-misc AI / 搜索 / 监控 / 杂项 + 中间件
05-frontend-public 面向终端用户的前端
06-frontend-admin 管理后台
07-service-extra 辅助 service(AI / worker / job)
08-database-migrations DB schema + migration history
09-design-and-shared 设计系统 + shared packages
10-infra-devops Docker / Nginx / CI / scripts调整规则:
在派遣代理前,必须给用户看一张拆分表(模块编号 / 名称 / 关注面 / 输入路径)。这是"绝不偏差"的关键 — 用户可纠正模块边界。
mkdir -p docs/output/{01-mod-name,02-mod-name,...,NN-mod-name}输出根目录默认 docs/output/。如果项目已有 docs/ 目录,强烈建议新建 output/ 子目录避免污染既有 docs。
# <项目名> · 技术摸底沉淀 · 迭代变更日志
> 本文件以摘要形式记录 `docs/output/` 中每一次文档沉淀的迭代变更。
> 每条记录包含:**触发事件 · 影响范围 · 文档增量 · 关键发现 · 跨模块溢出**。
>
> 版本基线:<YYYY-MM-DD> / branch <branch> / migrations 至 <NNN> / <其他基线信号>。
---
## 目录结构约定
(贴出 docs/output 树)
## 迭代记录
### Iteration 0 · <YYYY-MM-DD> · 骨架初始化
**触发事件:** 用户要求 ...
**影响范围:** docs/output/ 整树。
**文档增量:** 创建 N 个模块目录、CHANGELOG.md、README.md 占位。
**关键发现:**(此时只有侦察事实)
**下一步:** Wave 1 — 并行 N 个子代理沉淀各模块。只写"骨架已立、Wave 1 后填充"。禁止此时写架构图与横向矩阵 — 信息不全的聚合是负价值。
每个子代理 prompt 由 共同部分 + 模块特定部分 拼成。下面这块完整可拷贝,只需替换 <...> 占位:
你是 <项目名> 项目「<模块名>」模块的技术摸底文档作者。
# 项目背景
- <项目一句话定位>
- 技术栈: <一行罗列>
- 工作目录(绝对路径): <ABSOLUTE_PATH>
- 输出语言: <中文 / 英文 / 跟随项目>
- 输出根目录: docs/output/<NN-module-slug>/
# 模块范围(必读)
<列出本模块的所有源码文件 / 目录,使用相对路径>
(如果有跨模块的小段重叠,在这里明确"重点描述 / 仅引用 / 不要重复")
# 任务输出(全部写到 docs/output/<NN-module-slug>/)
1. **README.md** —— 总体设计
必含章节: 模块定位 / 边界与职责 / 架构图(ASCII) / 子模块清单(指向各能力文档) /
横向依赖(被谁调/调谁) / 关键决策记录 / 技术栈与库版本 / 已知问题清单 / 扩展点
2. **01-<capability>.md** —— <能力 1>
3. **02-<capability>.md** —— <能力 2>
... (按模块特性列 4-9 份)
# 每个能力文档必含
- 责任范围
- 关键代码入口(file_path:line_start-line_end + 函数名)
- 数据流(请求 → middleware → handler → service → repo → DB,具体到方法名)
- 涉及的 DB 表 / 字段 / 索引(若涉及)
- 配置 / 环境变量 / Redis key / 第三方依赖
- 与其他模块耦合
- 已知限制 / 待改进
- 测试覆盖说明(列出对应 *_test 文件覆盖了什么)
# 要求
- markdown 用 # / ## / ### 干净分级
- 文件引用格式: `path/to/file.ext:42-58`
- 不写 emoji(除非引自源码)
- 每个文档 200-500 行(完整性 > 简洁;模块巨大时 README 可超 500)
- 不要执行 git/pnpm/docker/curl 等副作用命令
- 不要写到 docs/output/<NN-module-slug>/ 之外
- Glob/Grep/Read 大胆并行,加速侦察
- "看似存在但实际未实现"的能力(空 handler / 死代码 / 配置未生效)必须显式标注
- 不确定的地方就描述你观察到的事实,不要瞎猜
# 报告
完成后用 200-300 字回复:
1) 写了哪些文件 / 对应能力
2) 1-3 条**非显然**发现(架构怪味、隐性 bug、技术债、命名漂移、半实现功能)
3) 你看到的、本模块**未覆盖但本应覆盖**的部分(应该归到哪个其他模块)run_in_background: true — 让代理后台跑,主代理不阻塞general-purpose 类型 — 不要用 Explore(只读)isolation 不要设 worktree — 必须落盘到当前工作目录<task-notification> 通知### Iteration 1.NN · <YYYY-MM-DD> · <模块名>(模块 NN 完成)
**触发事件:** 子代理 #N 完成 `docs/output/<NN-mod-slug>/`。
**影响范围:** 模块 NN 共 X 个文档,合计 ~YYYY 行。
**文档增量:**
- `README.md`(NNN 行) —— <一句话概括>
- `01-xxx.md`(NNN 行) —— <一句话概括>
... (逐文一行)
**关键发现(非显然):**
1. **<发现标题>** —— <一句话事实> + <一句话影响>
2. **<发现标题>** —— ...
3. **<发现标题>** —— ...
**跨模块溢出:**
- <溢出项> → 应被 **<NN-other-module>** 收录
- ...1 · 文档分层(图示四层)
2 · 模块导航(分类表格,每行:编号/模块/关注面/文档量)
3 · 全局架构速览(ASCII 拓扑图 + 数据/服务总线说明)
4 · 横向矩阵
4.1 P0/P1 问题表(去重 — 跨模块同一问题只列一次)
4.2 跨模块耦合"对子"表
5 · 阅读路径建议(角色化 — 新人/加功能/排查事故/安全审计)
6 · 沉淀方法论(本次产出怎么做的,留作团队后续参考)
7 · 后续维护建议(PR 触发对子提示 / 新增能力同步 README + CHANGELOG / 季度巡检)逐个读 10 个 CHANGELOG iteration 段的"关键发现",按下表归类:
| 优先级 | 判定 |
|---|---|
| P0 | 生产已经/即将出错;数据丢失/泄露/越权风险;用户操作完全失效 |
| P1 | 影响重大功能可用性;违反项目铁律(CLAUDE.md);命名/规范偏差导致后续维护困难 |
| P2(可选) | 性能瓶颈;非关键路径技术债;清理/简化机会 |
P2 在文档量大时可省略 — 只保留 P0/P1 让读者聚焦。
把每个模块"溢出建议"中"X 改时必须同步 Y"型陈述聚到一张表:
| 触发改动 | 必须同步 | 文件锚点 |
|---|---|---|
| <docs/output/path-to-anchor> |
判定标准:真正的强耦合才入表(改 A 不同步 B 会立刻坏掉的)。一般依赖、文档参考不入。
### Iteration 2 · <YYYY-MM-DD> · Wave 2 整合
**触发事件:** N 个子代理全部沉淀完成,主代理整合 + 顶层 README + 横向矩阵。
**影响范围:** 顶层 README.md 全文重写。
**文档增量:**
- §1 文档分层
- §2 模块导航
- §3 全局架构速览(ASCII)
- §4.1 P0/P1 问题表(N 条)
- §4.2 跨模块耦合"对子"表(N 组)
- §5 阅读路径建议
- §6 沉淀方法论
- §7 后续维护建议
**数据沉淀总量:** N 个模块 / NN 份 markdown / NNNNN 行。
**关键产出洞察:**(主代理对全局的总结性观察 — 1-3 条)
**下一步(Wave 3):** 校核覆盖盲区,确认手册级文档完整。针对项目元素,逐项确认每个都映射到了某个模块:
# 后端 handler 全集
ls <backend>/internal/handler/*.go | grep -v _test
# DTO 全集
ls <backend>/internal/dto/
# Repo / Service / Model 全集
ls <backend>/internal/{repository,service,model}/
# Migrations 全集
ls <backend>/migrations/ | wc -l
# Frontend 页面 / 路由全集
find <frontend>/app -maxdepth 3 -type d
find <frontend>/src/pages -maxdepth 2 -type d
# 共享包
ls packages/把数量与文档中的覆盖做对照。任何元素没被任何模块文档提到 = 盲区。
### Iteration 3 · <YYYY-MM-DD> · Wave 3 覆盖盲区校核(收尾)
**触发事件:** 主代理对 N 模块沉淀做交叉审计,确认无重大盲区。
**审计结果:**
| 维度 | 数量 | 覆盖状态 |
| --- | --- | --- |
| <类别> | NN | <说明覆盖到哪些模块,或"全部交叉引用">|
| ... | ... | ... |
**未独立成章但已交叉引用的边缘内容:**
- <项> —— <理由>(如:体量小,合并入 X 模块更合理)
**最终交付指标:**
- 文件数:N 份
- 行数:NNNNN 行
- P0/P1:N + N 条
- 跨模块耦合:N 组
**结束条件已满足:** 项目从「四层渐进结构」完整拆解、交叉审计、横向矩阵聚合,沉淀完成。全部满足才能宣告完成:
README.md 并包含 §1.1 中要求的所有章节README.md 含横向矩阵(P0/P1 + 对子表)CHANGELOG.md 有 Iter 0 / 每模块 1.0X / Iter 2 / Iter 3 共 N+3 段# 模块 NN · <模块名>
> <一句话定位:这个模块在系统中扮演什么角色>
## 1 · 模块定位
<2-3 段:边界、职责范围、不做什么>
## 2 · 架构图
\```
<ASCII 图:本模块内部组件 + 与其他模块的交互入口>
\```
## 3 · 子能力清单
| # | 能力 | 文档 | 主要入口 |
| --- | --- | --- | --- |
| 01 | <名> | [01-xxx.md](./01-xxx.md) | `path/file.ext` |
| ... | ... | ... | ... |
## 4 · 横向依赖
- **被以下模块调用:** <NN-X / NN-Y>
- **调用以下模块:** <NN-Z>
- **共享 secret / 资源:** <列出>
## 5 · 关键决策记录(ADR-style)
### 5.1 <决策标题>
- **背景:** ...
- **决策:** ...
- **代价:** ...
(每条决策一节;通常 3-7 条;**不要复述代码,只记录"为什么这么选"**)
## 6 · 技术栈与库版本
| 类别 | 选择 | 版本 |
| --- | --- | --- |
| <语言/框架/库> | <选择> | <版本> |
## 7 · 已知问题清单
| 优先级 | 问题 | 影响 | 建议 |
| --- | --- | --- | --- |
| P0 | ... | ... | ... |
| P1 | ... | ... | ... |
## 8 · 扩展点
- <未来增强的明确切入点,代码侧注释或 TODO>
## 9 · 与其他模块的交叉引用
- 本模块 X 由 [NN-Y/0Z-aaa.md] 详细描述,这里仅引用
- 跨模块耦合"对子":见顶层 [README.md §4.2](../README.md#42-跨模块耦合对子表)# 能力 NN.0X · <能力名>
> <一句话:这个能力解决什么问题>
## 1 · 责任范围
- **In scope:** ...
- **Out of scope:** ...(明确边界)
## 2 · 关键代码入口
| 层 | 文件 | 关键函数 / 行号 |
| --- | --- | --- |
| Handler | `path/x_handler.go:42-78` | `HandleXxx` |
| Service | `path/x_service.go:120-180` | `XxxService.DoIt` |
| Repo | `path/x_repo.go:15-60` | `XxxRepo.FindByX` |
| Model | `path/x.go:1-30` | `Xxx` |
## 3 · 数据流
\```
请求 → middleware A → handler.HandleXxx
→ service.DoIt
→ repo.FindByX → DB query
→ 第三方调用 / Redis / 其他模块
→ 响应序列化
\```
## 4 · 数据模型 / 表关联
| 表 / 集合 | 关键字段 | 索引 / 约束 | 关联 |
| --- | --- | --- | --- |
| <table> | ... | ... | ... |
## 5 · 配置与依赖
- 环境变量: `XXX_YYY`(默认 ...)
- Redis key: `prefix:{user_id}`(TTL ...)
- 第三方: <服务名 + 接口>
## 6 · 已知限制 / 待改进
- <事实型描述,不要鸡汤>
## 7 · 测试覆盖
| 文件 | 覆盖范围 |
| --- | --- |
| `xxx_test.go` | 单元: A / B / C;集成: 无 |
(如果完全无测试,**显式写"测试覆盖率 0"**,不要含糊。)
## 8 · 与其他模块耦合
- 改 X 时同步 Y:见顶层 [README.md §4.2](../../README.md#42-)| 优先级 | 模块 | 问题 | 一句话影响 |
| --- | --- | --- | --- |
| P0 | <NN-mod> | <短标题> | <一句话:用户/数据/钱受影响的方式> |
| P1 | <NN-mod> | <短标题> | <一句话:可用性/规范/维护性受影响的方式> || 触发改动 | 必须同步 | 文件锚点 |
| --- | --- | --- |
| <改 X 路由> | <改 nginx 配置 / DB schema / 前端 hook> | [NN-mod/0X-xxx.md](./NN-mod/0X-xxx.md) |每份产出完成后,机械性检查(子代理已自查 + 主代理抽查):
path:line 形式的代码引用README.md主代理一键自查命令(改 N 与路径):
cd <project_root>/docs/output && \
for d in 0*-*; do
echo "=== $d ===";
count=$(ls "$d"/*.md 2>/dev/null | wc -l);
total=$(wc -l "$d"/*.md 2>/dev/null | tail -1 | awk '{print $1}');
echo "files=$count lines=$total";
donepath:line。以下是已验证有效或经过推理认为有效的提升点。按优先级排列,P0/P1 强烈建议默认启用。
子代理 prompt 公共部分有 80% 内容相同。把这部分抽成一个 "context pack" 字符串变量,模块特定部分作为 overlay。减少 prompt 编写错误,加快批量派遣。
实现方式:在 Phase 1 侦察完成后,主代理自己组装 <CONTEXT_PACK> 文本块(项目定位 + 工作目录 + 输出语言 + 通用纪律),Wave 1 每个 prompt 顶部插入这块。
不同代理对同一概念可能用不同词(鉴权/认证/auth/login;文章/帖子/post/article)。在 Phase 1 主代理读 CLAUDE.md / README 时萃取一份 5-15 行的术语表,放入 Context Pack。直接消除文档术语漂移。
要求每个能力文档必须有一个章节列举"看似存在但实际未通的能力"。原版做法是依赖代理自觉;改进后变成模板必填项,避免遗漏死路。
模板片段:
## X · 半实现 / 死路清单
| 能力名 | 表象 | 实际 | 证据 |
| --- | --- | --- | --- |
| <如 SCHEDULED 状态> | DB 字段存在 / API 接受 | 无 worker 推进 | grep 结果 + path:line |让子代理回报用结构化格式而非自由文本,主代理可机械合并到 CHANGELOG / P0/P1 表。
模板片段(在子代理 prompt 末尾加):
# 报告(必须用此 YAML 格式)
\```yaml
files_written:
- path: docs/output/01-mod/README.md
lines: 291
summary: <一句话>
findings:
- title: <发现 1 标题>
severity: P0|P1|P2|info
evidence: path/file.ext:line
impact: <一句话>
overflow:
- to_module: 03-other-mod
reason: <一句话>
\```主代理把 YAML 解析后追加到 CHANGELOG,无需手工提炼。
原版做法
1 一波派 10 个 documenter。改进做法:Wave 0: 1 个 surveyor 代理 —— 全项目侦察 + 模块拆分方案 + 每模块 prompt 清单
Wave 1: N 个 documenter 代理 —— 按 Wave 0 方案派遣
Wave 2: 1 个 integrator 代理 —— 整合(P0/P1 + 对子表) + 写顶层 README
Wave 3: 1 个 auditor 代理 —— 覆盖盲区检查收益:主代理几乎不写文档,只做调度与决策。主代理上下文消耗大幅降低。
每份产出后,主代理 grep 一下文件,要求 path/file.ext:line 格式至少 N 处出现:
# 抽查某文档 path:line 引用密度
grep -E '[a-z_/]+\.[a-z]+:[0-9]+' docs/output/01-mod/01-xxx.md | wc -l
# 阈值:能力文档 ≥ 8,README ≥ 5低于阈值 = 内容空洞,要求子代理重做。
代理超时 / 报错 / 偏离时:
派遣 Wave 1 时,把 N 个模块同时加到 TodoWrite 列表(每个一条),代理回报后逐条标 completed。让用户看到"剩 X 个未完成"。
每个模块文档的"与其他模块耦合"章节,链接的目标必须存在。简单脚本:
# 收集所有模块内 markdown 链接,验证目标文件存在
for f in docs/output/**/*.md; do
grep -oE '\]\(\.\./[^)]+\)' "$f" | sed 's/](\(.*\))/\1/' | while read link; do
test -f "docs/output/$(realpath --relative-to=docs/output "$(dirname "$f")/$link" 2>/dev/null)" || echo "broken: $f -> $link";
done;
done如果模块涉及多种语言(Go + Python + TypeScript),给子代理列出每种语言的关键约定(项目 lint 规则、命名规则)。避免代理用语言 A 的视角描述语言 B 的代码。
跨模块耦合"对子",目前只在顶层 README §4.2。改进:在 源 与 目标 模块的能力文档底部都加一条"⇄ 改本能力时同步 X",这样改任一侧都能看到。
Iter 0 时把 commit hash 写入 CHANGELOG 头:git rev-parse HEAD。后续如果代码继续推进,要么:
避免文档与代码事实脱钩而无人察觉。
对每份能力文档的"测试覆盖"章节,主代理在 Wave 3 抽样运行:
go test -cover ./internal/handler/... | grep -E 'coverage|FAIL'
pytest --cov=app/<module> tests/把实际覆盖率数据回填文档。让"测试覆盖说明"从主观变客观。
横向矩阵 §4.2 对子表数据足够时,可生成 Mermaid 依赖图:
放在顶层 README §3 末尾,辅助阅读。
本 skill 默认假设 monorepo + 多语言 + 全栈。适配其他类型时:
用户说:"对我项目进行完整的模块梳理和技术沉淀"
主代理执行(精简流程):
mkdir -p docs/output/{01-NN}/,写 CHANGELOG Iter 0 + 占位 README。general-purpose 代理(run_in_background: true),用 §5.1 模板。全程典型耗时:30-50 分钟挂钟时间(子代理并行),主代理实际工作时间 10-15 分钟。
本 skill 不做 以下事(请用其他 skill 或直接做):
主代理只有同时满足以下 6 条才能宣告完成:
docs/output/ 树完整 — N 个模块目录,每个有 README + ≥4 能力文档README.md 含 §1-§7 全部章节,横向矩阵无空表CHANGELOG.md 含 Iter 0 / 1.0X×N / 2 / 3 完整序列任何一条不满足 = 没完成,不要谎报。
调用本 skill 后,用户可以得到:
docs/output/01-NN-mod/{README.md,0X-cap.md}这就是"项目摸底沉淀技能"的全部承诺。
最后一条手记:这个 skill 的最大价值不是任何单份文档,而是"主代理 + N 子代理 + 横向矩阵"这个工作流模式 — 它让"读不完的项目"从"找时间慢慢看"变成"30 分钟内拿到地图"。
加载评论中...