From bgp-docs
Analyze existing codebase and generate a two-layer project wiki under docs/wiki/ (project overview + domain docs), covering domain models, business flows, architecture, and dependencies. Use when the user asks to document a project, create a project wiki, analyze codebase structure, or mentions terms like "项目 wiki", "项目文档", "整理文档", "项目说明", "代码分析", "架构梳理", "onboarding 文档".
How this skill is triggered — by the user, by Claude, or both
Slash command
/bgp-docs:bgp-document-wikiThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
从现有代码库生成两层项目文档:**项目层**(非业务的项目级内容)+ **领域层**(业务内容按域拆分)。
从现有代码库生成两层项目文档:项目层(非业务的项目级内容)+ 领域层(业务内容按域拆分)。
配套使用:bgp-document-iteration skill 用于记录每次 feature 分支的迭代改动,与本 skill 形成套件——本 skill 维护项目现状(随代码演进),bgp-document-iteration 记录变更历史(不可变时间线)。
本 skill 使用 Claude Code 工具名(Glob、Grep、Read、Bash、Agent)。跨平台映射见 references/tool-mapping.md。
如果目标仓库属于以下情况之一,本 skill 不适用——应直接告知用户,不要硬生成空洞文档:
判断方式:Glob 统计非依赖源文件数量 → 读 README 前 50 行判断性质 → 命中任一条件则输出:
当前仓库看起来是 [类型],不适合生成两层项目文档。建议改为:[根据类型给建议]。如仍需生成,请告知。
等用户确认后再继续;否则跳过本 skill。
先读后写,宁缺毋滥。
待补充,不要凭经验或示例脑补Java 11+、./gradlew build)仅为格式示例,不是默认值——必须替换为实际值Java 17 (来源: pom.xml <java.version>)统一的"待补充"格式(显式可见,便于人工找到并补上):
> ⚠️ 待补充(需人工确认):<此处提示期望内容或推不出的原因>
每条业务事实只在一个地方有权威描述,其他地方通过链接引用,防止 drift。
实体归属:每个实体归属且仅归属一个域。
paths → 归那个域userId 字段描述写 引用 [User](../user/README.md#user)流程归属:
| 流程类型 | 归属域 |
|---|---|
| 同步调用链(A → B) | 发起方 A(入口 Controller 所在域) |
| 事件驱动(B 发事件,A 消费) | 消费方 A(业务动作发生处) |
| 纯编排(Saga / 工作流) | 编排所在域 |
共享基础设施(shared-lib、util、通用 types 等):不作为业务域,不进 domains/;在 01-architecture.md 的"目录结构"节一句话说明即可。
所有跨域链接统一指向 ../<other-domain>/README.md#<anchor>,不写 domain-model.md 或 flows.md——这样该域从单文件切到拆分模式时,引用方文档不用改。
[User](../user/README.md#user)[PaymentService.charge](../payment/README.md#charge)拆分模式下:<domain>/README.md 的"核心实体"和"主要流程"节保留跳转段(标题锚点 + 一句话 + 指向 domain-model.md / flows.md 的链接),让跨域链接始终有效。
docs/wiki/
├── README.md # 项目层入口:项目背景 + 技术栈 + 核心功能 + 域索引
├── 01-architecture.md # 架构模式 + 系统架构图 + 目录结构 + 领域划分 + 跨域 ER
├── 02-milestones.md # 里程碑(历史 + 未来)
├── 03-dependencies.md # 外部依赖
├── 04-deployment.md # 部署说明
├── 05-development.md # 开发指南
└── domains/ # 领域层(业务内容)
├── README.md # 领域清单
└── <domain>/
├── README.md # 领域概览 + 对外接口 + (单文件模式下含实体、流程)
├── domain-model.md # 本域所有实体(拆分模式)
└── flows.md # 本域所有流程(拆分模式)
# API ≥ 20 时可拆出 api.md(可选)
拆分触发条件(任一命中,单文件 → 拆 README + domain-model + flows):
每次调用 skill 前先 Glob 检查 docs/wiki/README.md:
文档由两层组成:
| 层 | 边界 | skill 行为 |
|---|---|---|
| 代码层(auto 区) | HTML 注释 <!-- auto:xxx -->...<!-- /auto:xxx --> 包裹的块 | 每次跑整块替换为从代码重新算出的内容 |
| 人工层 | auto 标记外的所有内容:prose、业务背景、设计说明、例外情况、填过的"待补充"等 | 永不改写,原样透传 |
规则只有一条:代码事实放 auto 区;为什么/例外/背景放 auto 区外的人工小节。详细标记清单见 references/output-templates.md 的 "auto 标记约定" 一节。
同一个"规则"在文档里要拆成两段:
auto:entity:<Name> 或 auto:flow:<Name> 内部,从校验/调度/状态机代码提取这样下次代码加了新校验,skill 在 auto 区自动补上;人工写的"为什么 30 分钟"、"大客户特批"不会被覆盖。
auto:domains-table(行级既有权威)01-architecture.md 的领域划分表虽然标着 auto,但语义与普通 auto 块不同——它是"混合区":
这条规则让"用户手动调整过的划分"和"用户加在行内的备注(如 [人工改名:xxx → yyy])"都被保留,而 skill 仍能把新代码追加上来。
auto:domain-index / auto:domains-listing这两个块展示的域名 / 职责列表是 auto:domains-table 的投影。增量模式下按以下规则重算:
auto:domains-table 的既有行(含人工改过的名字)./domains/<x>/)。用户改域名但未改目录时会造成链接和文本不一致——skill 不自动修复(物理 mv 风险高),由用户手动处理(见 README "域重命名指南")检查构建文件:
pom.xml / build.gradle → Java / Springpackage.json → Node.js / 前端requirements.txt / pyproject.toml → Pythongo.mod → GoCargo.toml → Rustapps/ / packages/ / services/ / pnpm-workspace.yaml → Monorepo识别后加载 references/language-hints.md 对应语言小节。
一次读取,同时提取:
内部保存依赖列表,Step 6 直接引用。
优先读取:README.md、CONTRIBUTING.md、CHANGELOG.md、Dockerfile、docker-compose.yml、CI 配置(.github/workflows/*、.gitlab-ci.yml)、Makefile、.env.example、openapi.yaml。
项目背景(从以下来源,推不出写"待补充"):
| 要素 | 数据源(按优先级) |
|---|---|
| 业务背景 | README.md 引言/Overview/About 节、package.json description |
| 目标用户 | README.md 的"Who is this for" / 权限配置角色 |
| 核心价值 | README.md 的 Features / Why / Highlights 节 |
⚠️ 项目背景是 AI 最容易幻觉的部分——读不到就写"待补充",不要从项目名脑补。
技术栈分类(从 1.2 依赖清单 + 配置文件):
| 类别 | 典型依赖信号 |
|---|---|
| 后端框架 | Spring Boot / NestJS / FastAPI / Gin / Actix |
| 前端框架 | React / Vue / Next.js / Nuxt |
| 数据存储 | MySQL / PostgreSQL / MongoDB / Redis / Elasticsearch |
| 消息队列 | Kafka / RabbitMQ / RocketMQ / Pulsar |
| DevOps | Docker / GitHub Actions / GitLab CI |
| 监控 | Prometheus / Grafana / Sentry / DataDog |
输出精简版,详细版本留给 03-dependencies.md。找不到的类别省略,不写"无"。详细信号见 language-hints.md 的"架构组件识别"。
里程碑数据:
git tag --sort=-creatordate | head -20
git log --tags --simplify-by-decoration --pretty='format:%h %D %ad %s' --date=short | head -30
# CHANGELOG.md 全文(如有)
数据源策略:
02-milestones.md 仍生成,但"历史里程碑"整块写待补充分叉点:
Read docs/wiki/01-architecture.md 的 auto:domains-table 块作为归属依据,不执行下面的 2.1 / 2.2。只对代码里未命中任何既有 path 的孤儿路径做最小推断,输出一组"待归属"行(由 Step 7.5 追加到表尾)。2.3 单领域判断也不重跑——既有表已定性按项目类型选择启发式(详见 language-hints.md 的"领域识别"小节)。核心思路:
com.xxx.<domain>.* 中的 <domain> 段通常是业务域modules/<domain>/ 或 <domain>/{controller,service} 结构apps/<name> 或 services/<name> 是一个域*Controller / *Service 命名前缀聚类(OrderController + OrderService → order 域)过滤非业务目录:config / common / util / infrastructure / gateway / shared——归入 shared 基础设施(不作业务域)。
把推断结果写入 01-architecture.md 的 auto:domains-table 块,表格包含:域名 / paths / 归属本域的核心实体 / 一句话职责。
如果推断结果只有 1 个业务域,提示用户:
本项目识别为单领域,两层结构过重。建议直接写一份单页 README,或确认后我会为你生成扁平的
docs/wiki/目录(README + domain-model + flows)。继续请回复"继续"。
用户要求继续则用退化结构(docs/wiki/ 下直接 README.md + domain-model.md + flows.md);否则跳过本 skill。
按项目类型选择查找策略,详见 language-hints.md 的"实体定位"小节。
识别主键/外键、一对多/多对多、继承、组合。优先使用框架注解(@OneToMany、gorm 标签、Prisma schema 等)作为事实来源。
先筛选核心实体(大项目可能 100+ 实体,全量详述会压垮 context)。
纳入条件(满足任一):
@OneToMany / @ManyToOne / @ManyToMany 等关系的主表或从表出现 ≥ 2 次@Entity 主表数量上限:每域核心实体 ≤ 10 个。超出时用末尾表格罗列。
按域归属(见全局原则-归属规则):
domain-model.md 写详情(或单文件模式下写 README.md)筛选不到实体时(如无 ORM 的 CLI 项目):转而分析主要数据结构(DTO、Value Object、Response 类型),章节改名为"核心数据结构"。
对每个核心实体记录:
降级规则:如果核心字段都无法从代码确定,不要强行详述——降级到末尾的"次要实体表格"。
输出格式(含 Mermaid ER 图)见 output-templates.md 的领域层模板。
按项目类型定位,详见 language-hints.md 的"业务入口"小节。涵盖:REST API、GraphQL、消息队列消费、定时任务、事件处理、gRPC。
纳入条件(满足任一):
数量上限:每域主要流程 ≤ 5 个。超出时其余端点用表格罗列:| 端点 | 方法 | 入口 Controller | 简述 |。
按域归属(见全局原则-归属规则):
flows.md,画完整序列图跨域序列图约定:其他域参与者标注为 ServiceName<br/>[<domain> 域];关键步骤文字加链接到被调用域。链接统一用 ../<other-domain>/README.md#<anchor>(见全局原则-跨域链接)。
对核心实体(Order、Task、Workflow 等)检查状态字段 + 状态转换逻辑:
OrderStatus.java、*State.java)squirrel-foundation、XState、自实现 switch-case)markAs*、transitionTo*)找到则画 stateDiagram-v2,标注来源文件。
使用 Mermaid sequenceDiagram 或 stateDiagram-v2。
聚合各域流程为用户视角的核心功能清单:
数据源(按优先级):
POST /api/orders → "下单")OrderCreated → "触发订单创建通知")@Scheduled → "每日账单结算")写作原则:
[推断][下单](./domains/order/README.md#下单流程)数量控制:全量 ≤ 20 个。超出时留高频 / 高价值的 20 个,其余以"完整端点见各域 README"收尾。
使用 Glob 扫描,深度按语言自适应——目标是看到业务关键目录(controller/、service/、entity/、handler/、router/ 等):
如果按推荐深度看不到业务关键词(controller/service/handler/router/model/entity),加深 2 层;仍看不到则从 src/ 或项目根整体扫。
忽略目录:node_modules、target、build、dist、.git、vendor、__pycache__、.pytest_cache、.tox、.venv、*.egg-info、.next、.nuxt、.gradle、out、bin、obj、coverage、.idea、.vscode。
⚠️ 不要把
env/加入忽略列表——只忽略.venv/、.env/(点开头)。
从目录命名 + 包结构 + 关键注解推断:
在 01-architecture.md 的"架构模式"节后新增"系统架构图"节,用 Mermaid flowchart 画部署拓扑。
画什么(自上而下分组):
package.json、README 提及、子目录推断)@SpringBootApplication / main 入口数 / docker-compose.yml services 决定几个连线原则(从代码能看出的):
推不出的处理:
[待补充]Frontend 节点图后补充"组件清单"表,列每个节点的证据:
| 组件 | 实际证据 | 备注 |
|---|---|---|
| MySQL | spring.datasource.url in application.yml + mysql-connector-j 依赖 | |
| Nginx | 待补充 | 未在代码库发现,通常是部署层 |
详细识别规则见 language-hints.md 的"架构组件识别"小节。
在 01-architecture.md 写两个 auto 块:
auto:domains-table — 领域划分表。增量模式下此表是特殊区块(既有行不动,只追加"待归属"行),具体规则见 Step 2 和 Step 7.5auto:er-diagram — 跨域 ER 主图(Mermaid erDiagram),只画涉及跨域引用的实体关系。域内实体细节留给各域 domain-model.md目的:让读 01-architecture.md 的人一眼看到目录、域、跨域实体关系三件事。不画全量 ER(全量在各域内画),避免这张图随实体增加而失控。
直接使用 Step 1.2 已提取的依赖列表。monorepo 的子模块构建文件如 Step 1 未扫描,再补读。
参考类别,按项目实际取舍:
CLI / 纯库 / 纯前端项目的"数据存储"、"消息队列"等类别可直接省略,避免空表格。
从配置文件和代码查找:第三方 API、云服务、支付网关、短信/邮件服务。每项标注配置 key 前缀和调用文件位置。
| 章节 | 数据来源 | 找不到时 |
|---|---|---|
| 项目简介 - 类型/技术栈/版本 | 构建文件 | 从代码推断,标 [推断] |
| 项目简介 - 业务背景 | README、package.json description | 整块写"待补充",不要脑补 |
| 技术栈总览 | 依赖清单分类 | 找不到的类别省略 |
| 核心功能列表 | 各域 Controller 端点(Step 4.5) | 命名歧义标 [推断];都推不出写"待补充" |
| 核心领域模型 | 实体类代码 + 注解 | 字段级:略过无法确认的字段;实体级:无法确认则降级到"次要实体"表 |
| 业务流程 | Controller + Service 调用链 | 只画能追踪的部分,标 [部分流程未覆盖] |
| 项目结构 | 目录扫描 | 客观陈述 |
| 系统架构图 | Dockerfile / compose / 依赖 / 配置 | 推不出的节点不画;推不出的连线虚线 + [待补充] |
| 里程碑 - 历史 | git tag + CHANGELOG | 两者都无时整块写"待补充" |
| 里程碑 - 未来 | — | 整块写"待补充(需人工规划)" |
| 外部依赖 | 构建 + 配置文件 | 无则不列 |
| 部署 - 环境要求 | 构建文件、Dockerfile、compose、CI | 未声明组件写 待补充 |
| 部署 - 启动步骤 | README、Makefile、scripts、CMD、CI | 找不到写 待补充(未发现启动脚本) |
| 部署 - 配置说明 | application-example.yml、.env.example、配置类 | 不要编造配置项 |
| 开发指南 | CONTRIBUTING、lint 配置、git hooks、CODEOWNERS | 找不到整节写 待补充 |
拆分触发(见输出路径规范):任一条件命中(实体 ≥ 4、流程 ≥ 3、预估 > 400 行)即拆。
为什么设阈值:小域拆成 3 个空文件比一个简洁 README 更难读;大域塞进一个文件又让人滚屏找不到。阈值让文档密度自适应。
下表定义 Step 1-6 产出去哪个文件。首次和增量模式都用这个分发表;两种模式的差异在 7.4 / 7.5 的写入方式。
项目层 docs/wiki/(6 个文件,直接放根目录):
| 文件 | 内容 | 来源 |
|---|---|---|
README.md | 项目简介(背景/技术栈/目标用户)+ 核心功能 + 域索引 | Step 1 + 4.5 |
01-architecture.md | 架构模式 + 系统架构图 + 目录结构 + 领域划分 + 跨域 ER | Step 5 |
02-milestones.md | 历史里程碑 + 未来规划 | Step 1.4 |
03-dependencies.md | 依赖表格、第三方服务 | Step 6 |
04-deployment.md | 环境、配置、启动 | 7.1 |
05-development.md | 本地开发、代码规范、提交规范、FAQ | 7.1 |
领域层 docs/wiki/domains/:
| 文件 | 内容 |
|---|---|
domains/README.md | 领域清单(表格:域名 / 职责 / 核心实体 / 文档链接) |
domains/<X>/README.md(单文件) | 概览 + 对外接口 + 实体 + 流程 |
domains/<X>/README.md(拆分) | 概览 + 对外接口 + 实现位置 + 跳转段到 domain-model.md / flows.md |
domains/<X>/domain-model.md(拆分) | 本域所有实体 |
domains/<X>/flows.md(拆分) | 本域所有流程 + 状态机 |
domains/<X>/api.md(可选,API ≥ 20) | 完整 API 清单 |
章节间互链:
docs/wiki/README.md 目录链接到同级其他文件 + ./domains/README.mddomains/<x>/ 下文件头部加:回到:[领域清单](../README.md) · [项目总览](../../README.md)../<other-domain>/README.md#xxx(见全局原则-跨域链接)mkdir -p docs/wiki
mkdir -p docs/wiki/domains
# 对每个域:
mkdir -p docs/wiki/domains/<domain>
按 references/output-templates.md 的骨架逐文件 Write,所有模板里的 <!-- auto:xxx -->...<!-- /auto:xxx --> 标记原样保留——它们是下次增量跑的定位锚点。
单领域退化(Step 2.3 用户确认后):docs/wiki/ 下直接 README.md + domain-model.md + flows.md,不创建 domains/。
docs/wiki/ 已存在时)对每个既有目标文件执行以下合并流程(新增的文件按 7.4 首次模式写):
<!-- auto:([^\s>]+) -->([\s\S]*?)<!-- /auto:\1 --> 抽出 id 和现有内容。[^\s>]+ 允许中文 ID(如 auto:flow:创建订单流程)Edit——代码没变时不必写入,既减少 diff 噪音,也让 Step 8.6 的 mtime 检查有意义Edit 把旧块整体替换为新块(保留开闭标记本身)<!-- 代码中未发现此项 -->,不删标记、不碰周围 proseauto:domains-table → 不执行本步骤,按下方"新领域"小节处理domains/<x>/README.md;拆分模式 = domains/<x>/domain-model.md)README.md;拆分 = flows.md)03-dependencies.md 对应小节docs/wiki/README.md 的 auto:features 块内Step 2 识别到的"待归属"路径(不在既有 auto:domains-table 任何 path 下):
auto:domains-table 块内追加一行 | 待归属 | <path> | - | 建议归属:<域>(AI 推断) |docs/wiki/domains/<new>/ 目录——等用户确认归属后下次重跑 skill 再建auto:domains-table 其余处理规则(既有行不重排、不删)同执行模式节的说明。
04-deployment.md 和 05-development.md 整体是人工层(大部分是团队规范 prose),未加 auto 标记。增量模式下这两个文件完全不动。首次模式按模板生成"待补充"占位,由用户填写后永久保留。
给用户一段简短摘要:
01-architecture.md 的 auto:domains-table 块")生成后执行自检。前两项必须实际执行工具调用验证,不能仅目测。
防止 AI 为了格式好看而编造行号 / 文件路径。
domains/<x>/ 文档中随机抽 5 条 来源: xxx.java:45 形式的引用docs/wiki/ 下 6 个项目层文件都存在(README、architecture、milestones、dependencies、deployment、development)docs/wiki/domains/README.md + 每个 docs/wiki/domains/<X>/README.md 存在docs/wiki/ 下 README.md + domain-model.md + flows.md 存在docs/wiki/README.md 的目录链接指向的文件都存在../<other-domain>/README.md#xxx)随机抽 3 条:目标文件存在且锚点存在README.md(不是 domain-model.md / flows.md)output-templates.md 中的示例值被当作项目事实写入仅在本次执行走增量路径时跑:
auto:domains-table 既有行数 ≥ 上次读取时的行数(只增不减,增量只发生在"待归属"行)04-deployment.md 和 05-development.md 未被修改(mtime 未变 或 内容 diff 为空)信息不完整时从代码推断,但标 [推断]:
Agent + subagent_type=Explore)——开放问题,如 "Where are entity classes?" / "How is auth implemented?"Grep):@Entity、@RestController、@TransactionalGlob):**/*Controller.java、**/entity/*.java按非依赖源文件数分档:
| 规模 | 策略 |
|---|---|
| < 100 文件 | 常规流程 |
| 100-500 文件 | 采样分析 + 严格核心筛选(Step 3.3 / 4.2 的上限) |
| 500-2000 文件 | 并行派发子 agent 分模块分析 |
| > 2000 文件 | 并行 + 分批写入(见下"context 管理") |
并行派发(Claude Code 用 Agent;无并行能力则见下):
子任务 1: 用户模块(entity/User*, service/User*, controller/User*)
子任务 2: 订单模块(entity/Order*, service/Order*, controller/Order*)
子任务 3: 支付模块(entity/Payment*, service/Payment*, client/*Pay*)
每子任务输出结构化结果(实体片段 + 流程片段),主 agent 汇总去重。
无并行时的 context 管理:
Monorepo 处理详见 language-hints.md 的 "Monorepo / 多模块项目" 小节。
npx claudepluginhub pangjiawei19/agent-skills --plugin bgp-docsFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.