Build Project Docs

构建项目文档体系 (build-project-docs)

为项目创建完整的分层式 LLM 友好文档。支持两种模式：已有项目梳理文档、新项目从 PRD 驱动开发。

核心理念

LLM上下文窗口有限，文档必须分层：

• .claude/CLAUDE.md = 主索引（项目地图，始终加载到上下文）
• .claude/docs/{模块}/README.md = 模块级文档（按需加载）
• *.claude/docs/{模块}/.md** = 深度参考文档（API详情、数据模型、坑点）
• .claude/docs/{模块}/CHANGELOG.md = 模块变更历史（调试和回滚参考）

---

模式检测

开始前先判断当前模式：

文档模式（已有项目，有源代码）

项目已有代码，需要梳理生成文档。

全新（无 .claude/docs/）→ 按顺序执行文档模式全部8个阶段。

增量（.claude/docs/ 已存在）→ 1. 先检查 `.claude/docs/_progress.md`——如果存在，说明上次会话中断，读取它确定：

• 阶段状态：哪些阶段已完成、哪个阶段进行中、哪些待执行
• 模块进度：阶段4/5/7中哪些模块已完成、哪些待处理
• 直接跳到第一个未完成的阶段继续，不重复已完成的阶段

2. 如果 _progress.md 不存在，阅读现有 .claude/CLAUDE.md 和所有 .claude/docs/ 文件 3. 运行阶段1获取当前状态 4. 对比：新模块→加入，文件数变化→更新，缺失→创建，过期→更新 5. 跳过已完成且准确的阶段 6. 阶段7和阶段8 特殊处理：即使 _progress.md 标记为已完成，如果源码比文档更新（find -newer 检测），仍需重新运行

新项目模式（PRD驱动）

用户提到 PRD、需求文档、新项目规划、开发规范，且项目为空或新建 → 执行新项目模式5个阶段。

用户提到 PRD + 项目已有代码 → 先用文档模式梳理现有代码，再用新项目模式的阶段1-3做增量功能的需求拆解。

---

文档模式（8个阶段）

为已有项目梳理代码、生成分层文档。

执行前必须阅读对应阶段的 reference 文件。

---

新项目模式（5个阶段）

从 PRD 出发，生成架构设计、需求拆解、开发规范、模块文档。

开发规范参考：

• Java 代码规范
• Spring Boot 脚手架规范

执行前必须阅读对应阶段的 reference 文件。

---

关键规则

上下文管理（最重要！）

处理多模块时，禁止一次性处理所有模块。必须： 1. 逐模块串行处理（从小到大） 2. 每完成一个模块 → 更新 _progress.md → 不再引用该模块源码 3. 处理 3+ 个大模块后 → 主动提示用户开新会话继续

进度追踪（_progress.md）

_progress.md 是全局进度文件，两种模式通用：

• 每完成一个阶段或一个模块 → 立即更新 _progress.md
• 新会话读取后可直接跳到断点继续
• 全部完成后删除

文档完整性

• ❌ 只写 README 不写 api 子文件就算"完成"
• ✅ 只要模块对外暴露了 API（Controller / @Tool / gRPC / Handler 等），就必须按业务域拆分 api-{域}.md
• ✅ 每个业务模块必须有 data-model.md + pitfalls.md（文档模式）或 data-model.md + dev-checklist.md（新项目模式）
• ✅ README 是索引，api-*.md 才是详情，README 中必须链接到所有子文件

文件大小

• .claude/CLAUDE.md：150行以内
• 模块 README.md：200行以内
• 超过250行必须拆分子文件

核心原则

详见 principles.md

---

开始执行

根据模式检测结果，进入对应的阶段流程。每个阶段先展示结果给用户确认，再继续下一阶段。

build-project-docs

为项目构建分层式 LLM 友好文档体系，让 AI Agent 高效理解和操作你的代码库。

核心理念

LLM 上下文窗口有限，文档必须分层加载：

.claude/
├── CLAUDE.md                   主索引（项目地图，始终加载）≤150行
└── docs/
    └── {模块}/
        ├── README.md           模块概览（按需加载）≤200行
        ├── api-{域}.md         API 详情
        ├── data-model.md       数据模型
        ├── pitfalls.md         坑点陷阱（文档模式）
        ├── dev-checklist.md    开发清单（新项目模式）
        └── CHANGELOG.md        变更历史

两种模式

文档模式（已有项目）

扫描已有代码，生成完整文档体系。8 个阶段：

支持增量更新——中断后新会话自动从断点继续。

新项目模式（PRD 驱动）

从需求文档出发，生成架构设计和开发规范。5 个阶段：

内置 Java 代码规范和 Spring Boot 脚手架规范参考。

使用方式

# 已有项目：在项目根目录执行
/build-project-docs

# 新项目：提供 PRD 文件
/build-project-docs 这是我的 PRD：...

自动检测模式：有源代码 → 文档模式，空项目+PRD → 新项目模式。

特性

• 断点续传 — _progress.md 追踪进度，会话中断后自动恢复
• 逐模块处理 — 避免上下文溢出，串行处理大项目
• 增量更新 — 检测源码变更，只更新过期文档
• 交叉验证 — 最终阶段检查文档一致性和链接完整性

依赖

• git（用于变更日志分析）

License

MIT

阶段1：项目探查

系统性扫描项目结构：

1. 构建系统

读取根构建文件（pom.xml / package.json / Cargo.toml / go.mod 等）：

• 识别所有模块/包及其关系
• 提取技术栈版本
• 记录构建命令和配置

2. 模块清单

对每个模块：

• 统计源文件数量
• 列出包/目录结构
• 识别入口点（Application类、main函数）
• 找到控制器/路由（公共API表面）
• 找到服务/业务逻辑层
• 找到数据访问层
• 检查配置文件

3. 依赖图

映射模块间依赖：

• 共享/基础模块（被所有人依赖）
• 业务模块（领域特定）
• 打包/部署模块

4. 现有文档

检查已有的文档、README、注释。

5. 输出格式

探查完成后，必须以下表格式输出结果给用户确认，确认后再进入阶段2：

# 项目探查结果

| # | 模块 | 源文件数 | 入口/API | 依赖 | 备注 |
|---|------|---------|----------|------|------|
| 1 | common | 45 | 无 | - | 工具类/异常体系 |
| 2 | dao | 62 | 无 | common | 115个Mapper |
| 3 | oss-server | 38 | 6个Controller | common, dao | 业务模块 |
| ... | | | | | |

技术栈: Java 17 / Spring Boot 3.x / Maven
构建命令: mvn clean package -DskipTests
模块总数: {N}

等用户确认后再继续。 如果用户指出遗漏或分类错误，先修正再进入下一阶段。

阶段2：架构分类

将每个模块归入以下层级：

分类结果决定后续阶段的执行顺序和文档详细程度。

阶段3：编写 .claude/CLAUDE.md（主索引）

输出路径：.claude/CLAUDE.md（所有文档统一放在 .claude/ 目录下）。

必须包含的章节

# {项目名}

## 概述
{1-2句：这个项目做什么，谁在用}

## 构建
{运行时要求、版本约束、构建命令}

## 测试环境
{API地址、认证头、测试凭据}

## 项目结构
{ASCII树展示所有模块，每个带一行描述}

## 模块索引
{按层级分组的表格：基础层 → 业务层 → 打包层}
{每行：模块 | 描述 | 文件数 | 文档链接}

## 核心架构
{核心调用链/数据流的ASCII图}

## 模块依赖关系
{哪些模块依赖哪些}

## 环境配置
{配置如何组织、有哪些环境}

## 重要坑点
{5-10个跨模块的已知问题}

## 模块变更日志
{说明 .claude/docs/{模块}/CHANGELOG.md 机制，排查问题时优先阅读}

## 文档索引
{链接到所有 .claude/docs/ 文件的索引表，标记完成状态}
{注意：CLAUDE.md 和 docs/ 都在 .claude/ 下，链接用相对路径 docs/{模块}/xxx.md}

关键规则

• 控制在 150行以内（始终加载到上下文）
• 每个模块必须出现（不能有盲区）
• 链接到详细文档，不要内联详情
• 标记文档完成状态（已完成/待补充）

写入进度

CLAUDE.md 写完后，创建或更新 .claude/docs/_progress.md：

# 执行进度

## 阶段状态
- 阶段1: ✅ 已完成
- 阶段2: ✅ 已完成
- 阶段3: ✅ 已完成
- 阶段4: ⏳ 待执行
- 阶段5: ⏳ 待执行
- 阶段6: ⏳ 待执行
- 阶段7: ⏳ 待执行
- 阶段8: ⏳ 待执行

这是 _progress.md 的初始创建点，后续阶段在此基础上追加模块级进度。

阶段4：编写基础模块文档

为每个共享/基础模块创建 .claude/docs/{模块}/README.md。

逐模块处理：从阶段2分类为基础层/数据层的模块清单中，逐个读取源码、写入文档，处理完一个再处理下一个。

工具/通用模块

• 统一响应格式（成功/错误/分页模式）
• 异常体系和错误码
• 所有API封装类（方法索引和调用模式）
• 关键工具类（仅记录行为不明显的）
• 常量和枚举索引
• 安全/认证机制
• 外部服务集成点

数据访问模块

• Mapper/Repository 按业务域分组索引
• 核心 PO/Entity 模型（仅关键字段）
• 表关系图
• 分页模式
• AOP/拦截器

共享业务模块（如审批、审计）

• API 端点
• Service 接口方法
• 其他模块如何集成（注解、调用模式）
• 全模块必须使用的共享DTO

验证

每写完一个基础模块文档后，立即验证并更新进度：

# 确认文件已写入
ls -la .claude/docs/{模块}/

# 确认 README 内容不为空且行数合理
wc -l .claude/docs/{模块}/README.md

写完一个模块后，立即更新 `_progress.md`：

## 阶段4 基础模块
- common: ✅ README
- dao: ✅ README
- base: ⏳ 待处理

全部基础模块完成后： 1. 在 _progress.md 中将阶段4标记为 ✅ 已完成 2. 检查清单：

• [ ] 阶段2中分类为基础层/数据层的每个模块都有 .claude/docs/{模块}/README.md
• [ ] 每个 README 行数 ≤ 200 行（超过则拆分子文件）
• [ ] 共享模式只在基础模块文档中写一次（业务模块通过链接引用）

阶段5：编写业务模块文档

每个业务模块的文档要求

必须创建：README.md

docs/{模块}/README.md 包含：

• 模块概述和依赖
• 对外 API 索引（含路径/方法/工具名）
• 关键服务流程（仅非平凡的）
• 数据模型引用（尽量链接到基础层文档）
• 模块特定配置
• 本模块已知坑点

必须创建：按 API 分组拆分的子文件

只要模块对外暴露了 API（不论形式），就必须为每个 API 分组创建独立的 api-{域}.md 文件。

API 的形式包括但不限于：

• REST Controller（Spring MVC / Express / Gin 等）
• MCP Server 的 @Tool 方法
• gRPC Service 定义
• GraphQL Resolver
• WebSocket Handler
• CLI 命令入口

按业务域拆分，每个域一个文件：

• docs/{模块}/api-{域}.md — 该域下所有 API 的详细文档（路径/方法签名、参数、返回值、调用示例）
• docs/{模块}/data-model.md — 模块核心数据模型（DTO/VO/PO/Tool参数 及其关系）
• docs/{模块}/pitfalls.md — 已知坑点和注意事项

README.md 的作用是索引，api-.md 才是详情。README 中必须有「详细文档」章节链接到所有 api-.md。

判断标准

写完 README 后，必须执行以下检查：

该模块对外暴露了 API 吗？（Controller / @Tool / gRPC Service / Handler / ...）
→ 没有：只写 README（如纯工具库模块）
→ 有：按业务域拆分 api-{域}.md + data-model.md + pitfalls.md

---

单模块执行流程

1. 读取当前模块的所有源文件（Controller/Tool/Service/DTO 等）
2. 写 README.md（模块概览 + API 索引表）
3. 判断：该模块对外暴露了 API 吗？
   → 没有（纯工具库/纯模型模块）：跳到步骤 6
   → 有：继续步骤 4-5
4. 按业务域拆分，每个域写一个 api-{域}.md + 写 data-model.md + 写 pitfalls.md
5. 验证所有文件已写入（ls 检查）
6. 更新 _progress.md：将该模块从 ⏳ 改为 ✅，补充文件清单
7. 进入下一个模块，回到步骤1
8. 处理 3+ 个大模块后，主动提示用户：
   「建议开新会话继续，运行 /build-project-docs 会自动读取 _progress.md 进入增量模式」

进度文件 .claude/docs/_progress.md

阶段5开始时，将阶段5标记为 🔄 进行中，并在已有进度基础上追加模块级进度：

## 阶段5 业务模块
- oss: ✅ README + api-bucket + api-cluster + api-region + api-user + api-ec + api-schedule + data-model + pitfalls (7域/124个API)
- mcp-obs: ✅ README + api-tools + data-model + pitfalls (1域/15个Tool)
- hdfs-server: ⏳ 待处理
- hdfs-service: ⏳ 待处理

每完成一个模块，将该模块从 ⏳ 改为 ✅ 并补充文件清单。全部完成后将阶段5标记为 ✅ 已完成。

执行顺序（从小到大）

1. 先统计所有业务模块的 API 数量（端点数 / Tool 数 / 方法数） 2. 按数量从少到多排序 3. 逐个处理，每完成一个模块必须写入 _progress.md 4. 处理 3+ 个大模块后，主动提示用户开新会话继续（_progress.md 保证进度不丢）

禁止事项

• ❌ 同时读取多个模块的源码
• ❌ 跳过写 _progress.md 直接处理下一个模块
• ❌ 处理大量模块后不提示用户（应建议开新会话继续）
• ❌ *只写 README 不写 api-.md 子文件就算"完成"**
• ❌ 把所有 API 详情全塞进 README 里

完成标志

阶段5完成的判定标准：

• 每个对外暴露 API 的模块都有对应的 api-*.md 文件
• 每个业务模块都有 data-model.md + pitfalls.md
• 每个 README.md 都有「详细文档」章节链接到所有子文件
• _progress.md 中所有业务模块标记为 ✅，阶段5标记为 ✅ 已完成

注意：_progress.md 在阶段8验证全部通过后才删除，阶段5完成时不要删。

阶段6：编写配置层文档

如有独立配置模块，创建 docs/{模块}/README.md 包含：

• 环境列表和区分方式
• 配置文件命名规则
• 关键配置项说明

完成后在 _progress.md 中将阶段6标记为 ✅ 已完成。如果项目没有独立配置模块，也标记为 ✅ 已完成（无独立配置模块）。

阶段7：生成变更日志

为每个已文档化的模块（包括基础模块和业务模块）生成 docs/{模块}/CHANGELOG.md。静态文档描述"是什么"，CHANGELOG 描述"最近改了什么"。

基础模块（如 common、dao）的变更往往影响所有业务模块，CHANGELOG 对排查跨模块 bug 尤为重要。

7.1 识别需要生成 CHANGELOG 的模块

# 列出有 docs 但没有 CHANGELOG 的模块
for dir in .claude/docs/*/; do
  module=$(basename "$dir")
  [ ! -f "$dir/CHANGELOG.md" ] && echo "$module"
done

# 列出有 CHANGELOG 但可能有新提交的模块
for f in .claude/docs/*/CHANGELOG.md; do
  module=$(basename $(dirname "$f"))
  echo "$module"
done

7.2 提取 Git 历史

# 获取最近10个涉及该模块的提交
git log --oneline -10 -- {模块目录}/

# 对每个提交，获取变更文件和统计
git show --stat {commit-hash} -- {模块目录}/

# 获取实际 diff 来理解改了什么
git show {commit-hash} -- {模块目录}/

# 检查同一提交是否也修改了公共模块（跨模块影响）
git show --stat {commit-hash} -- {公共模块目录}/

7.3 去重检查

如果 CHANGELOG.md 已存在，先提取已记录的 commit hash，跳过已有条目：

grep -oP '(?<=\*\*提交\*\*: |Commit\*\*: )[a-f0-9, ]+' .claude/docs/{模块}/CHANGELOG.md

7.4 分析每个提交

对每个提交确定：

1. 类型: feat / fix / refactor / perf / chore

• 关键词："修复"→fix，"增加/新增/支持"→feat，"优化"→perf，"调整"→refactor

2. 变更文件：列出每个文件的 +/- 行数

• 必须包含实际文件名和变更行数（从 git show --stat 获取）
• 禁止使用占位符如"（需通过 git show 查看）"

3. 影响分析：

• 哪些 API 端点受影响？
• 是否有新参数、字段或方法？
• 跨模块变更（公共模块在同一提交中被修改）？
• 数据库变更（新列、修改查询）？
• 配置变更？

4. 风险评估：

• LOW：仅本模块、装饰性/日志变更
• MEDIUM：API参数变更、业务逻辑变更
• HIGH：跨模块变更、数据模型变更、核心流程变更

7.5 条目格式

## [{日期}] {提交消息}

**类型**: {feat|fix|refactor|perf|chore}
**提交**: {短hash}
**风险**: {LOW|MEDIUM|HIGH}

### 变更文件
| 文件 | 变更 | 说明 |
|------|------|------|
| {类名.java} | +5/-2 | {改了什么以及为什么} |

### 影响范围
- **API**: {受影响的端点、新参数}
- **跨模块**: {公共模块是否也变更了}
- **数据模型**: {PO/Mapper 是否变更}
- **配置**: {配置是否变更}

### 回滚指南（仅 HIGH 风险）
- 回滚: `git revert {hash}`
- 检查文件: {列表}
- 副作用: {什么可能被影响}

7.6 写入规则

• 新条目追加到顶部（最新在最上面）
• 如果文件不存在，创建时加头部：

# Changelog - {模块名}

> 模块变更历史。最新变更在最上方。
> 排查问题时优先阅读本文件。

---

7.7 重要规则

• 具体描述文件变更 — "修改了Controller" 没用，"BucketResourceController.changeBasePro() 新增 replicationPipeline 参数" 有用
• 每个提交必须运行 git show --stat — 禁止文件表为空或使用占位符
• 总是标注跨模块影响 — 如果公共模块在同一提交中被修改，这是关键信息
• HIGH 风险必须包含回滚指南
• 合并相关提交 — 如果多个提交明显是同一功能，合并为一条记录
• 写入前去重 — 检查已有 CHANGELOG 的 hash 避免重复条目

7.8 进度追踪

阶段7开始时将其标记为 🔄 进行中，并在 _progress.md 中追加：

## 阶段7 变更日志
- common: ✅ CHANGELOG (3条)
- dao: ✅ CHANGELOG (2条)
- oss-server: ⏳ 待处理

每写完一个模块的 CHANGELOG，将该模块从 ⏳ 改为 ✅。全部完成后将阶段7标记为 ✅ 已完成。

阶段8：交叉引用验证与自检

全部文档和变更日志写完后，进行最终验证。

文档完整性

1. .claude/CLAUDE.md 中每个模块的文件数和描述是否正确 2. 每个 .claude/docs/ 文件是否在 .claude/CLAUDE.md 文档索引中有链接 3. 基础层文档被业务模块文档引用（而非重复） 4. 无孤儿信息 — 每个事实只存在于一个地方 5. 坑点放在最具体的适用位置

CHANGELOG 质量

6. 每个已文档化的模块（含基础模块）都有 CHANGELOG 7. 每个 CHANGELOG 条目都有完整的文件列表（无占位符） 8. HIGH 风险条目都有回滚指南

验证命令

# 检查 CHANGELOG 覆盖度
ls .claude/docs/*/CHANGELOG.md 2>/dev/null

# 检查占位符
grep -rn "需通过\|查看详细\|TBD" .claude/docs/*/CHANGELOG.md

# 检查每个 README 是否链接了所有子文件
for module in $(ls .claude/docs/); do
  for f in $(ls .claude/docs/$module/*.md 2>/dev/null | xargs -I{} basename {}); do
    if [ "$f" != "README.md" ] && [ "$f" != "CHANGELOG.md" ]; then
      grep -q "$f" .claude/docs/$module/README.md || echo "MISSING: $module/README.md -> $f"
    fi
  done
done

# 检查 .claude/CLAUDE.md 是否链接了所有模块
for module in $(ls .claude/docs/); do
  grep -q "docs/$module/" .claude/CLAUDE.md || echo "NOT LINKED: $module"
done

# 检查有 API 的模块是否都有 api-*.md 子文件
for module in $(ls .claude/docs/); do
  dir=".claude/docs/$module"
  # 跳过没有 README 的目录
  [ ! -f "$dir/README.md" ] && continue
  # 检查 README 中是否提到了 API（Controller/@Tool/gRPC/Handler 等）
  if grep -qiE "Controller|@Tool|gRPC|Handler|Resolver|端点|endpoint|API" "$dir/README.md"; then
    # 有 API 的模块必须有 api-*.md
    api_count=$(ls "$dir"/api-*.md 2>/dev/null | wc -l)
    if [ "$api_count" -eq 0 ]; then
      echo "MISSING API DOCS: $module has APIs but no api-*.md files"
    fi
    # 有 API 的模块必须有 data-model.md 和 pitfalls.md
    [ ! -f "$dir/data-model.md" ] && echo "MISSING: $module/data-model.md"
    [ ! -f "$dir/pitfalls.md" ] && echo "MISSING: $module/pitfalls.md"
  fi
done

如果验证发现问题，必须修复后再报告。常见修复：

• MISSING API DOCS → 回到阶段5为该模块补写 api-*.md
• MISSING: data-model.md / pitfalls.md → 补写对应文件
• NOT LINKED → 在 .claude/CLAUDE.md 中补充链接

完成收尾

全部验证通过后： 1. 在 _progress.md 中将阶段8标记为 ✅ 已完成 2. 删除 `_progress.md`（临时文件，全部完成后不再需要） 3. 输出最终进度报告给用户

核心原则

该记录什么

• 模块边界和依赖关系（"地图"）
• API 表面（端点、方法签名）
• 数据模型及其关系
• 非显而易见的行为（坑点、陷阱、类型转换bug）
• 调用模式（模块间如何通信）
• 配置结构和环境差异
• 近期变更和影响范围（CHANGELOG）

不该记录什么

• 看代码就能明白的实现细节
• 标准框架行为（Spring Boot自动配置等）
• 单个函数逻辑（除非是关键共享工具）
• 临时状态或进行中的工作
• 一周后就会过时的东西

一次记录，处处引用

• 共享模式放在基础模块文档中
• 业务模块文档链接到基础文档：[参见 common/README](../common/README.md)
• 同一信息不要在两个地方重复
• 如果发现自己写了相同的东西两次，提取到最通用的适用位置

文件大小指南

• .claude/CLAUDE.md：150行以内（始终加载）
• 模块 README.md：200行以内（单一聚焦）
• 如果 README 超过250行，拆分为子文件

阶段1：PRD 解析

输入

用户提供的 PRD 文档，形式可能是：

• 直接粘贴的文本
• 文件路径（.md / .docx / .pdf）
• 口头描述的需求

解析目标

从 PRD 中提取以下结构化信息：

1. 项目概述

• 项目名称
• 一句话描述
• 目标用户
• 核心价值

2. 功能模块

对每个功能模块提取：

• 模块名称
• 模块职责（一句话）
• 核心用例（用户能做什么）
• 对外接口（API / 页面 / 定时任务 / MQ）

3. 数据模型

• 核心实体（名称 + 关键字段）
• 实体间关系（一对多、多对多）
• 关键约束（唯一性、必填、枚举值）

4. 非功能需求

• 性能要求（QPS、响应时间）
• 安全要求（认证、鉴权、数据脱敏）
• 集成点（外部系统、第三方 API）
• 部署要求（容器化、多环境）

5. 优先级

• P0：MVP 必须有
• P1：第一版完成后尽快补
• P2：后续迭代

输出格式

解析完成后，必须以结构化表格输出给用户确认：

# PRD 解析结果

## 项目概述
| 项目名 | 描述 | 目标用户 |
|--------|------|---------|
| xxx | xxx | xxx |

## 功能模块
| # | 模块 | 职责 | 核心API | 优先级 |
|---|------|------|---------|--------|
| 1 | 用户管理 | 注册/登录/权限 | 5个接口 | P0 |
| 2 | 工作空间 | 项目空间CRUD | 8个接口 | P0 |

## 核心实体
| 实体 | 关键字段 | 关系 |
|------|---------|------|
| User | id, name, email, role | 1:N → WorkspaceMember |
| Workspace | id, name, code | 1:N → WorkspaceMember |

## 非功能需求
- 认证方式：JWT / SSO
- 部署：Docker + K8s
- 监控：OpenTelemetry

等用户确认后再继续。 如果 PRD 信息不完整，列出缺失项让用户补充。

阶段2：架构设计

基于阶段1的 PRD 解析结果，按脚手架规范设计项目结构。

执行前必须阅读：springboot-scaffold.md

2.1 判断项目类型

2.2 生成项目结构

单模块项目

按脚手架规范的标准包结构生成：

project-name/
├── doc/sql/init.sql
├── src/main/java/com/example/{project}/
│   ├── controller/
│   ├── service/impl/
│   ├── dao/
│   ├── domain/
│   ├── vo/
│   ├── config/
│   ├── exception/
│   ├── constants/
│   ├── utils/
│   └── {Project}Application.java
├── src/main/resources/
│   ├── application.yml
│   ├── application-dev.yml
│   ├── application-prod.yml
│   ├── logback-spring.xml
│   └── mapper/
├── bin/start.sh, stop.sh
├── pom.xml
├── README.md
└── .gitignore

多模块项目

project-name/
├── project-common/          # 基础层：工具类、异常、常量
├── project-dao/             # 数据层：Mapper、实体
├── project-service/         # 业务层：Service 接口 + 实现
├── project-web/             # 接入层：Controller、配置、启动类
├── doc/sql/
├── bin/
└── pom.xml                  # 父 POM

2.3 模块划分

基于阶段1的功能模块列表，确定每个功能模块放在哪一层：

| 功能模块 | 所在层 | 包路径 |
|---------|--------|--------|
| 用户管理 | service + web | controller/user, service/user |
| 工作空间 | service + web | controller/workspace, service/workspace |
| 公共工具 | common | utils, exception, constants |

2.4 输出

生成项目结构树 + 模块划分表，展示给用户确认后进入下一阶段。

阶段3：需求拆解

基于阶段1的 PRD 解析 + 阶段2的架构设计，将需求拆解为可执行的开发任务。

3.1 拆解维度

每个功能模块拆解为：

数据层任务

• 建表 SQL（doc/sql/）
• 实体类（domain/）
• Mapper 接口 + XML（dao/ + mapper/）

业务层任务

• Service 接口定义
• Service 实现（含业务逻辑、事务、异常处理）
• DTO / Request / Response 定义（vo/）

接入层任务

• Controller（路由、参数校验、Swagger 注解）
• 权限配置（如需）

基础设施任务

• 配置类（config/）
• 异常体系（exception/ + ErrorCode）
• 全局处理器（GlobalExceptionHandler）
• 工具类（utils/）

3.2 输出格式

# 开发任务清单

## 基础设施（所有功能的前置依赖）

| # | 任务 | 文件 | 优先级 | 预估 |
|---|------|------|--------|------|
| 0.1 | 项目脚手架搭建 | pom.xml, Application, 配置文件 | P0 | - |
| 0.2 | 统一响应 RestResult | vo/RestResult.java | P0 | - |
| 0.3 | 异常体系 | exception/BizException + ErrorCode | P0 | - |
| 0.4 | 全局异常处理器 | exception/GlobalExceptionHandler | P0 | - |
| 0.5 | Swagger 配置 | config/OpenApiConfig | P0 | - |
| 0.6 | MyBatis-Plus 配置 | config/MybatisConfig | P0 | - |
| 0.7 | 数据库初始化脚本 | doc/sql/init.sql | P0 | - |

## 模块1：{模块名}

| # | 任务 | 文件 | 依赖 | 优先级 |
|---|------|------|------|--------|
| 1.1 | 建表 SQL | doc/sql/V1.0.0__init.sql | 0.7 | P0 |
| 1.2 | 实体类 | domain/Workspace.java | 1.1 | P0 |
| 1.3 | Mapper | dao/WorkspaceDao.java + mapper/WorkspaceMapper.xml | 1.2 | P0 |
| 1.4 | DTO 定义 | vo/CreateWorkspaceRequest.java 等 | - | P0 |
| 1.5 | Service 接口 | service/WorkspaceService.java | 1.3, 1.4 | P0 |
| 1.6 | Service 实现 | service/impl/WorkspaceServiceImpl.java | 1.5 | P0 |
| 1.7 | Controller | controller/WorkspaceController.java | 1.6 | P0 |
| 1.8 | 单元测试 | test/WorkspaceServiceTest.java | 1.6 | P1 |

## 模块2：...

3.3 规则

• 基础设施任务排最前（所有模块依赖）
• 模块内按 数据层 → 业务层 → 接入层 顺序
• 标注任务间依赖关系
• P0 任务构成 MVP，P1/P2 后续迭代
• 任务粒度：一个任务 = 一个可独立提交的工作单元

输出后等用户确认，确认后进入阶段4。

阶段4：生成 CLAUDE.md 开发指南

基于前3个阶段的结果，生成 .claude/CLAUDE.md 作为 AI 编程的项目级开发指南。

执行前必须阅读：

• java-code.md — Java 代码规范
• springboot-scaffold.md — 脚手架规范

4.1 CLAUDE.md 结构

# {项目名}

## 概述
{一句话描述，来自阶段1}

## 技术栈
- Java {版本} / Spring Boot {版本}
- MyBatis-Plus / MySQL
- Redis（如有）
- OpenTelemetry 可观测性

## 构建与运行
{来自脚手架规范的构建命令和启动方式}

## 项目结构
{来自阶段2的项目结构树}

## 包结构与依赖方向
{来自脚手架规范第三章}
controller -> service -> dao -> domain

## 开发规范摘要

### 命名规范
- 包名：全小写，com.example.{project}.{module}
- 类名：UpperCamelCase，DTO/VO/Request/Response 后缀
- 方法名：lowerCamelCase，get/list/create/update/delete 前缀
- 常量：UPPER_SNAKE_CASE，禁止魔法值
{从 java-code.md 提取关键条目，不超过 20 行}

### Controller 规范
- URL 全小写，单词用 `-` 分隔
- @RestController + @RequestMapping("/api/v1/{resource}")
- @RequestBody 搭配 @Valid
- 返回 RestResult<T>，禁止返回 null
- 每个方法必须有 @Operation(summary)

### Service 规范
- @Transactional(rollbackFor = Exception.class)
- 双层 catch：BizException 原样抛 + Exception 包装
- 方法体不超过 80 行

### 数据库规范
- 表名 t_ 前缀，字段小写下划线
- 必须有 id/create_time/update_time/is_deleted
- 禁止 SELECT *，禁止无 WHERE 的 UPDATE/DELETE

### 异常处理
- BizException + ErrorCode 枚举
- Controller 不写 try-catch，走 GlobalExceptionHandler
- 错误码按模块分段：通用 1xxxxx，模块A 2xxxxx ...

### 日志规范
- @Slf4j + 占位符，禁止字符串拼接
- error 必须带异常对象：log.error("msg", e)
- 外部调用前后各一条日志（含耗时）

## 模块索引
{来自阶段1的功能模块表，链接到 .claude/docs/ 下的详细文档}

## 开发任务
{来自阶段3的任务清单摘要，链接到完整任务文档}

## 文档索引
{链接到所有 .claude/docs/ 文件}

4.2 关键规则

• 150 行以内（始终加载到上下文）
• 规范摘要只放最关键的条目，详细规范链接到 standards/ 文件
• 项目特定信息（模块、API、数据模型）链接到 docs/ 子文件
• 必须包含构建命令、包结构、依赖方向（AI 写代码最常参考）

4.3 同时生成 .claude/docs/_task-list.md

将阶段3的完整任务清单写入 .claude/docs/_task-list.md，作为开发进度追踪文件。

CLAUDE.md 中链接到此文件：[开发任务清单](docs/_task-list.md)

4.4 写入进度

完成后创建 .claude/docs/_progress.md：

# 执行进度

## 阶段状态
- 阶段1 PRD解析: ✅ 已完成
- 阶段2 架构设计: ✅ 已完成
- 阶段3 需求拆解: ✅ 已完成
- 阶段4 开发指南: ✅ 已完成
- 阶段5 模块文档: ⏳ 待执行

阶段5：生成模块开发文档

为每个功能模块生成详细的开发文档，放在 .claude/docs/{模块}/ 下。

5.1 每个模块必须生成的文件

README.md — 模块概览

# {模块名}

## 概述
{模块职责，一句话}

## API 列表
| 方法 | 路径 | 说明 | 请求体 | 响应 |
|------|------|------|--------|------|
| POST | /api/v1/workspace/create | 创建工作空间 | CreateWorkspaceRequest | RestResult<Integer> |
| GET | /api/v1/workspace/{code} | 查询详情 | - | RestResult<WorkspaceDto> |

## 依赖
- 依赖模块：common（工具类、异常）
- 外部依赖：MySQL, Redis

## 详细文档
- [API 详情](api-{域}.md)
- [数据模型](data-model.md)
- [开发清单](dev-checklist.md)

api-{域}.md — API 详细设计

对每个 API 端点：

## POST /api/v1/workspace/create

### 说明
创建新工作空间

### 请求体 CreateWorkspaceRequest

| 字段 | 类型 | 必填 | 校验 | 说明 |
|------|------|------|------|------|
| name | String | 是 | @NotBlank @Size(max=64) | 工作空间名称 |
| workspaceCode | String | 是 | @NotBlank @Pattern | 编码，唯一 |
| product | String | 是 | @NotNull | 产品标识 |
| members | List<MemberRoleDto> | 是 | @NotEmpty @Valid | 成员列表 |

### 响应
RestResult<Integer> — 返回新建的工作空间 ID

### 业务逻辑
1. 校验 workspaceCode 唯一性
2. 创建工作空间记录
3. 批量添加成员
4. 返回 ID

### 错误码
| 错误码 | 说明 |
|--------|------|
| 200001 | 项目不存在 |
| 200002 | 编码已存在 |

data-model.md — 数据模型

# 数据模型

## t_workspace 工作空间表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT UNSIGNED | 主键 |
| name | VARCHAR(64) | 名称 |
| code | VARCHAR(64) | 编码，唯一 |
| ... | | |

## 实体关系
workspace 1:N workspace_member N:1 user

## 索引
- uk_code (code) — 唯一索引
- idx_name (name) — 普通索引

dev-checklist.md — 开发清单

从阶段3任务清单中提取该模块的任务，加上代码规范提醒：

# {模块} 开发清单

## 待开发
- [ ] 建表 SQL
- [ ] 实体类 Workspace.java（@Data @TableName("t_workspace")）
- [ ] Mapper 接口 WorkspaceDao.java（@Repository extends BaseMapper）
- [ ] DTO：CreateWorkspaceRequest（@Valid 校验注解）
- [ ] Service 接口 + 实现（@Transactional(rollbackFor=Exception.class)）
- [ ] Controller（@RestController @Tag @Operation）
- [ ] 单元测试

## 规范提醒
- Controller 不写 try-catch，走全局异常处理器
- Service 用双层 catch 模式（BizException + Exception）
- DTO 字段用包装类型，不设默认值
- Mapper 参数加 @Param
- 禁止 SELECT *

5.2 执行流程

1. 按模块优先级顺序，逐模块处理
2. 每个模块：写 README → api-*.md → data-model.md → dev-checklist.md
3. 写完一个模块 → 更新 _progress.md
4. 全部完成 → 更新 CLAUDE.md 的文档索引 → 删除 _progress.md

5.3 完成标志

• 每个功能模块都有 README + api-*.md + data-model.md + dev-checklist.md
• CLAUDE.md 的文档索引链接到所有文件
• _progress.md 已删除

5.4 最终输出

完成后汇报：

| 模块 | 文档 | API数 | 备注 |
|------|------|-------|------|
| .claude/CLAUDE.md | 已完成 | - | 开发指南 |
| docs/workspace/ | 已完成 | 8 | README + api + data-model + checklist |
| docs/user/ | 已完成 | 5 | README + api + data-model + checklist |
| docs/_task-list.md | 已完成 | - | 完整开发任务清单 |

Java 代码规范

本规范用于指导 AI 代码生成和人工开发，涵盖命名、OOP、集合、并发、异常、日志、SQL、注解等全维度约束。

---

一、命名规范

二、 xxx

Spring Boot 项目脚手架规范

新建 Spring Boot 项目时的标准模板,包含目录结构、打包配置、文档要求、中间件集成和可观测性接入。

搭配 java-code.md一起使用。

---

一、项目整体目录结构

二、xxxx