bmad-document-project

BMAD 文档项目

现有项目入口。 如果项目已有代码，规划技能就需要基于实际情况，而不是猜测技术栈或约定。此技能会系统地以只读方式扫描代码库，并生成 project-documentation.md，作为当前状态的权威快照，供所有下游 BMAD 规划技能加载。

不会编写、修改或执行任何代码。 允许使用的工具有 Read、Glob、Grep、Write（仅用于输出文档）和 TodoWrite（用于跟踪扫描进度）。

---

输出

bmad-output/project-documentation.md
（或用户配置的输出文件夹——请遵循该设置）

如果 bmad-output/project-context.md 存在，则加载它；合并其中已有的约束，而不是从头重新发现。

---

三种意图

如果意图不明确，请询问用户；绝不要在不告知用户的情况下重新生成现有文档。

创建 — 初次扫描

使用 TodoWrite 跟踪以下六个扫描阶段。完成所有阶段后，再编写最终文档。

阶段 1 — 仓库骨架

Glob: **/* (depth ≤ 3, exclude node_modules, .git, dist, build, __pycache__, .venv)
Glob: *.md, *.txt, *.rst at root and docs/

记录：目录树结构、是否存在 monorepo 标记（packages/、apps/、libs/）、顶层配置文件、文档根目录。

阶段 2 — 技术栈和工具链

读取以下存在的文件（文件缺失时不要报错）：

文件	提取内容
package.json / package-lock.json	运行时和开发依赖、脚本
pyproject.toml / requirements*.txt / Pipfile	Python 技术栈
go.mod	Go 模块和依赖
Cargo.toml	Rust crate
pom.xml / build.gradle	JVM 技术栈
Gemfile	Ruby 技术栈
composer.json	PHP 技术栈
*.csproj / *.sln	.NET 技术栈
Dockerfile / docker-compose*.yml	容器策略
.github/workflows/*.yml / *.gitlab-ci.yml / Jenkinsfile	CI/CD 流程
*.tf / *.bicep / *.yaml（位于 infra/ 中）	IaC / 云服务提供商

记录：主要语言、框架、主要库、运行时版本固定信息、测试框架（注明——不要运行）、构建工具、包管理器。

阶段 3 — 入口点和关键流程

Grep: "main\|entrypoint\|app\.listen\|createServer\|handler\|router\|routes"
Grep: "export default\|module\.exports\|@app\.route\|@Controller\|@RestController"

读取发现的顶层入口文件（最多 5–8 个；略读即可，无需通读）。

记录：应用的启动方式、主要路由层、身份验证/中间件链（仅名称）、发现的后台工作进程或队列。

阶段 4 — 模块 / 领域结构

读取 src/、app/、lib/ 或同等目录下一级的目录名称及 index.* / __init__.* 文件。

Glob: src/**/index.{ts,js,py,go,rb}
Glob: app/**/__init__.py

记录：模块名称及推断出的职责、层级边界（控制器 / 服务 / 仓库 / 模型 / 工具）、共享实用工具。

阶段 5 — 约定和模式

每层抽查 3–5 个代表性文件（如果能从文件名/路径深度判断，优先选择近期修改的文件）：

Grep: "class \|interface \|type \|enum " — naming style
Grep: "async \|await \|Promise\|goroutine\|concurrent" — concurrency pattern
Grep: "import \|require\|from " — module resolution style
Grep: "console\.log\|logger\.\|log\." — logging approach
Grep: "\.env\|process\.env\|os\.environ\|config\." — config/secrets pattern

记录：命名约定（文件、类、函数的大小写风格）、错误处理风格、日志记录方式、配置/密钥管理方式、测试文件位置约定（仅名称——不要执行）。

阶段 6 — 集成点

Grep: "http[s]\?://\|fetch(\|axios\.\|requests\.\|http\.Get\|RestTemplate"
Grep: "database\|db\.\|pool\.\|prisma\.\|mongoose\.\|sqlx\.\|gorm\."
Grep: "redis\|kafka\|rabbitmq\|sqs\|pubsub\|queue\|event"
Grep: "s3\.\|storage\.\|blob\.\|bucket"

记录：调用的外部 HTTP API（域名/服务名称，不含密钥）、数据库类型和 ORM/驱动、消息队列或事件总线、对象存储、第三方服务（支付、电子邮件、身份验证提供商——仅名称）。

编写文档

填写 ${CLAUDE_PLUGIN_ROOT}/skills/bmad-document-project/templates/project-documentation.template.md → bmad-output/project-documentation.md。

使用 Write 工具。对于没有依据的部分，保留 `` 注释，不要编造内容。准确性优先于完整性。

---

更新 — 重新扫描变更区域

1. 阅读现有的 project-documentation.md。
2. 询问用户哪些区域发生了变化（新增模块？新增依赖？重构？）。
3. 仅针对这些区域重新执行上面的相关阶段。
4. 通过精确改写变更部分来谨慎编辑文档。
5. 在文档末尾附加一条注明日期的更新说明。

如果只改动了部分内容，不要从头重新生成整份文档。

验证 — 检查完整性

阅读现有的 project-documentation.md 并确认：

• 六个扫描领域都有内容（不是空白，也不是所有内容都为“未检测到”）
• 技术栈部分列出了主要语言、框架和重要依赖项
• 入口点部分至少列出了一个引导或启动文件
• 模块结构列出了可识别的领域名称
• 约定部分涵盖命名风格和错误处理
• 集成点列出了外部依赖项（或明确说明“无”）
• 没有虚构的文件路径（用 Glob 交叉检查一两个路径）

报告一份通过/未通过清单。提供填补缺漏的帮助，而不是悄悄编辑。

---

范围边界

此技能为只读，唯一例外是其单个输出文档。它：

• 不会修改任何源文件。
• 不会运行测试、构建脚本、代码检查工具或覆盖率工具。
• 不会生成应用代码、迁移文件或测试固件。
• 不会实现功能或审查差异。

如果扫描发现值得修复的问题，请将其记录为文档中的规划备注，不要直接修复。

---

交接

编写好 project-documentation.md 后，它将成为以下工作的棕地输入：

• bmad-init — 根据检测到的技术栈和约束，填充 project-context.md。
• bmad-prd — 为现有功能和集成约束提供事实依据。
• bmad-architecture — 将其作为演进的基线架构，而不是从头设计。
• bmad-tech-spec（Quick Flow）— 为聚焦的规格说明提供具体起点。

文档就绪后，说明建议的下一步。

---

角色说明

此分析角色与 BMAD Method 中的 Mary（业务分析师）相契合——先了解现状，再提出改进建议。该文档是她的实地笔记：准确、有据可查、不带臆测。

---

---

属于 BMAD Planning & Orchestrator 插件的一部分——这是一个用于 BMAD Method 的 Claude Code 驱动工具，由 BMAD Code Organization 开发（https://github.com/bmad-code-org/BMAD-METHOD）。贯彻 bmad-document-project 的理念。所有方法论相关致谢均归 BMAD Code Organization 所有。