Claude Code 生产级工作流

project-root/
  .claude/
    templates/PLAN.template.md
    rules/                       # 代码规范/错误码/安全红线
    repo_map.md                  # 关键目录/入口/数据流
  CLAUDE_CODE_LOG/
    20250827_083000__add-auth-mw/   # 时间戳__任务-kebab
      PLAN.md
      PROMPT_USED.md
      0001.patch
      RUN_LOG.md
      COMMIT_SHA.txt
      EVAL_REPORT.md

# Task Title
Auth middleware for API v2
## 0. Metadata
- Timestamp: 2025-08-27 08:30
- Branch: feature/auth-mw-20250827-0830
- Issue: #123
## 1) Tool Conventions（工具约定）
- 使用 Claude Code / Cursor（Claude）
- **只输出 unified diff（patch）**
- **仅允许修改**：server/middleware/auth.ts, server/routes/*.ts, tests/auth.test.ts
## 2) Language Conventions（语言/栈）
- Node 20 + TypeScript strict
- ESLint/Prettier 强制，显式类型
## 3) Project Context（项目）
- 目录/数据流见 .claude/repo_map.md
- 禁改：infra/, migrations/, .env*
- 依赖：jsonwebtoken@^9
## 4) Persona（人设）
- 资深后端+测试工程师：先最小可行，再补测试与文档
## 5) Component Scope（组件）
- API v2 中间件层；契约：Authorization: Bearer <JWT>
## 6) Task & DoD（任务与验收）
- 校验 JWT，注入 req.user；区分 401/403
- **DoD**：
  - `npm test` 全绿
  - `GET /v2/ping` 返回 200
  - 改动行数 < 300 且只在白名单文件中
## 7) Query / Action（执行指令）
- 如不确定，先提出 ≤3 条澄清问题
- 然后输出 **unified diff**（新增文件含 `--- /dev/null`）
- 最后附 ≤120 字变更摘要
## Risks & Rollback
- 风险：路由顺序导致中间件未生效
- 回滚：revert 当前补丁；接口不变
## Evaluation（验证）
- 运行：`npm i && npm test`
- 记录：输出写入 `RUN_LOG.md`
## Debrief（执行后填写）
- 成功/失败；原因分类；下一轮假设与修正

读取 ./CLAUDE_CODE_LOG/20250827_083000__add-auth-mw/PLAN.md
严格按"白名单/DoD/步骤"执行：
1) 如不确定，先给 ≤3 条澄清问题；
2) 然后只输出 unified diff 补丁；
3) 附 ≤120 字变更摘要。

# 1) 开轮
TS=$(date +"%Y%m%d_%H%M%S"); TASK=add-auth-mw
ROUND="CLAUDE_CODE_LOG/${TS}__${TASK}"
mkdir -p "$ROUND" && git checkout -b "feature/${TASK}-${TS}"
# 2) 生成 PLAN 草稿
cp .claude/templates/PLAN.template.md "$ROUND/PLAN.md"
echo -e "\n\nBranch: feature/${TASK}-${TS}\nTimestamp: ${TS}" >> "$ROUND/PLAN.md"
# 3) 让 Claude 输出补丁 → 粘贴保存为：
cat > "$ROUND/0001.patch"
# 4) 应用与验证留痕
git rev-parse HEAD > "$ROUND/COMMIT_SHA.txt"
git apply "$ROUND/0001.patch" --3way
npm i && npm test | tee "$ROUND/RUN_LOG.md"
# 5) 提交或归档
git add -A && git commit -m "cc: ${TASK} @ ${TS}"

读取 PLAN.md
若不确定，提出 ≤3 个澄清点
仅在白名单文件内最小化实现，输出 unified diff

目标：不改变对外行为，仅改善内部结构
保留所有导出 API 与测试不变
分步给 diff（先小再大），每步都能独立通过测试

先给"复现单测"的最小 patch（红）
再给修复 patch（绿）
两段 diff 分开发送

仅对 README/脚本做有限改动
给出本地验证命令，产出写入 RUN_LOG.md

git apply --check CLAUDE_CODE_LOG/**/0001.patch
npm test / pytest -q / go test ./...

# 任务标题（≤60字）
## 1. 任务目标 / DoD（必须可验证）
- 验收命令：
  - `npm i && npm test`
  - `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/v2/ping == 200`
- 改动边界：
  - 仅允许：<列出文件或通配>
  - 禁止：infra/, migrations/, .env*
  - 单轮改动 ≤300 行（超限先停下并提问）
## 2. 执行步骤（最小可行）
1) <最小实现点>
2) <接入/注册位置>
3) <补单测或脚本>
4) 本地跑测并记录日志
## 3. 注意事项
- **只输出 unified diff（patch）**；新增文件用 `--- /dev/null`
- 保持导出 API 不变（若变更需明示）
- ESLint/Prettier；TS 显式类型
## 4. 补充信息
- 依赖：<name@ver>
- 契约：<协议/头/错误码>
## 5. 风险与回滚
- 风险：<潜在失效点>
- 回滚：revert 当前补丁，接口不变
## 6. 执行约定（给 Claude）
- 如不确定，先给 ≤3 条澄清问题
- 然后输出补丁 + ≤120 字摘要
## 7. 本轮总结（执行后填写）
- 成功/失败：
- 失败原因分类：
- 下一轮修正计划：