📦 第 1 步:项目级claude

# 假设你的项目根目录是 /home/user/projects/order-service
cd /home/user/projects/order-service

# 1.1 创建 .claude 目录
mkdir -p .claude/commands .claude/hooks

# 1.2 复制本工具箱的 automation 文件
cp /path/to/spring-cloud-workflow/automation/.claude/commands/req-full.md .claude/commands/
cp /path/to/spring-cloud-workflow/automation/.claude/hooks/*.py .claude/hooks/
cp /path/to/spring-cloud-workflow/automation/.claude/spring-templates/*.md .claude/spring-templates/
cp /path/to/spring-cloud-workflow/automation/.claude/settings.json .claude/

# 1.3 给 hook 加执行权限
chmod +x .claude/hooks/*.py
  

验证:

ls -la .claude/
# 应该看到 commands/ hooks/ settings.json 三个东西
  

⚙️ 第 2 步:调整配置(2 分钟)

2.1 编辑 `settings.json`

把 $CLAUDE_PROJECT_DIR 替换成你的项目绝对路径(环境变量有些 CC 版本不展开):

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "python /home/user/projects/order-service/.claude/hooks/stage-tracker.py"
      }]
    }],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "python /home/user/projects/order-service/.claude/hooks/coverage-check.py"
        }]
      }
    ]
  }
}
  

2.2 检查 `CLAUDE.md` 是否存在

/req-full 依赖 CLAUDE.md 里的项目配置(技术栈、命名规范、Git 规范)。如果没有,先跑 /init 生成。

🧪 第 3 步:测试 hooks(1 分钟)

3.1 测试 hook 1:阶段跟踪器

# 手动测试(应该无输出说明 OK)
echo '{"user_prompt":"我要做需求", "session_id":"test"}' | \
  python .claude/hooks/stage-tracker.py

# 应该看到:
{"continue": true, "hookSpecificOutput": {"additionalContext": "当前阶段: None/8, 需求: None"}}
  

3.2 测试 hook 2:文档验证器

# 创建一个空 01-requirement.md,看会报什么
mkdir -p /tmp/test
echo '{}' > /tmp/test/01-requirement.md
echo '{"tool_name":"Write","tool_input":{"file_path":"/tmp/test/01-requirement.md","content":"# 标题\n需求编号: REQ-001\n"}}' | \
  python .claude/hooks/doc-validator.py

# 应该看到
⚠️ [01-requirement] 模板不完整,缺失字段:
   - 需求编号
   - 创建日期
   - 需求方
   - 负责人
   - ## 1. 背景
   - ## 2. 需求描述
   - ## 3. 验收标准
   - ## 4. 不做什么
   - ## 5. 风险与依赖

{"continue": true, "hookSpecificOutput": {"additionalContext": "模板标识：01-需求文档，缺失项：[需求编号、创建日期、需求方、负责人、## 1. 背景、## 2. 需求描述、## 3. 验收标准、## 4. 不做什么、## 5. 风险与依赖]，文档完整性：不完整"}}
  

3.3 测试 hook 3:覆盖率检查

# 这个需要先有 JaCoCo 报告
# 跑完 mvn test 后跑:
echo '{"tool_name":"Bash","tool_input":{"command":"mvn test"},"tool_output":"BUILD SUCCESS"}' | \
  python .claude/hooks/coverage-check.py

# 应该看到
📊 覆盖率检查结果: PASS
   总包数: 4, 失败: 0
✅ 覆盖率达标,可以进入下一阶段
{
  "status": "PASS",
  "results": [
    {
      "package": "com.example.my_demo.controller",
      "line_pct": 68.2,
      "branch_pct": 50.0,
      "line_covered": 15,
      "line_total": 22
    },
    {
      "package": "com.example.my_demo.service.impl",
      "line_pct": 100.0,
      "branch_pct": 90.0,
      "line_covered": 32,
      "line_total": 32
    },
    {
      "package": "com.example.my_demo.exception",
      "line_pct": 82.6,
      "branch_pct": 100,
      "line_covered": 19,
      "line_total": 23
    },
    {
      "package": "com.example.my_demo.repository.impl",
      "line_pct": 89.7,
      "branch_pct": 90.0,
      "line_covered": 52,
      "line_total": 58
    }
  ],
  "failed": [],
  "summary": "总包数: 4, 失败: 0"
}
  

3.4 在 CC 里实测

cd /home/user/projects/order-service
claude
  

在 CC 里:

> /help
# 应该看到 /req-full

> /req-full 测试一下
# 应该启动流程(因为没有 PROJECT_PLAN.md,会提示先创建)
  

🚀 第 4 步:第一次实战(1 分钟 + 跑流程)

4.1 准备 PROJECT_PLAN.md

在项目根目录创建:

# 项目计划

### 进行中
(空)

### 待启动
(空)

### 已完成
(空)
  

4.2 启动 CC 并跑需求

claude

> /req-full REQ-2026-001 满100减20的促销功能

4.3 观察自动化效果

你应该看到:

CC: 🚀 启动 8 阶段流程,需求 REQ-2026-001
    [阶段 0/8] 需求接入
    Q1: 减 20 是"满 100 才减"还是累计?
    ...
[Hook 1] 🔄 状态推进: 阶段 ? → 阶段 0
  

每回答 1 个问题,CC 推进一点。

当 CC 写 01-requirement.md 时:

[Hook 2] ✅ [01-requirement] 模板完整

阶段 0 完成后 CC 会停下等你确认需求 ⏸️。

总计 4 次确认(需求 / Worktree / Review / 收尾),其他全自动。

🐛 故障排查

Hook 不触发?

# 1. 检查 Python 路径
which python
# 应该是 /usr/bin/python 或类似

# 2. 检查 hook 权限
ls -la .claude/hooks/
# 应该 -rwxr-xr-x

# 3. 检查 settings.json 语法
python -m json.tool .claude/settings.json
# 应该正常输出格式化 JSON

# 4. 看 CC 日志
claude --debug 2>&1 | grep -i hook
  

状态推进不对?

# 查看状态文件
cat /tmp/req-state.json

# 手动重置
rm /tmp/req-state.json
  

覆盖率检查不准?

JaCoCo 报告路径: target/site/jacoco/jacoco.csv
多模块项目:每个模块都有 target/site/jacoco/jacoco.csv
默认配置已支持(glob 递归找)

🎨 自定义(可选)

修改检查点

settings.json 里的 automation.checkpointStages 决定哪几个阶段需要人工确认:

"checkpointStages": [0, 3, 6, 7]
// 0 需求澄清  3 Worktree  6 Review  7 收尾
// 改 [0, 6] = 只在需求和 Review 停下,其他全自动
  

修改覆盖率目标

coverage-check.py 里的 COVERAGE_TARGETS:

COVERAGE_TARGETS = {
    "service": {"line": 80, "branch": 70},  # 改这里
    "controller": {"line": 60, "branch": 0},
    ...
}
  

禁用某个 hook

注释掉 settings.json 里对应的 hook 数组即可。

✅ 安装完成

你现在可以:

1 句话启动 8 阶段流程
中间只在 4 个节点拍板
所有阶段都自动留痕
覆盖率不达标自动提醒

下一步:试着跑 /req-full 一个真实的小需求(预估 < 4h),感受自动化效果。

文章信息

本文作者：zhangxue
本文链接：https://lucksnow1989.github.io/article/21.机器学习/4.AI工程/automation/docs/01-快速安装.html
版权声明：本文为本人原创文章，遵循 CC 4.0 BY-NC-SA版权协议，转载请附上原文出处链接和本声明。