# Claude Code Auto-Pipeline
[](https://docs.anthropic.com/en/docs/claude-code)
[](.claude/agents/)
[](#工具支持)
**AI 编码工具生成代码的速度很快 —— 但发布 bug 的速度更快。**
这个 pipeline 在“想法”和“生产环境”之间增加了结构化的质量门禁，让你每次部署时不再心惊胆战。
一条命令。13 个阶段 (0–12)。设计审查、安全、测试，以及最后的代码审查和提交门禁 —— 全部自动处理。阶段提示词遵循结构化的 CONSTRAINTS→CONTEXT→TASK→FORMAT→VERIFY。
```
/auto-pipeline "add user authentication with JWT"
# 或直接运行 engine：
bash run-pipeline.sh "add user authentication with JWT"
```
兼容 **Claude Code, Cursor, Cline, Windsurf, GitHub Copilot 和 Aider**。
## 为什么会有这个项目
你肯定遇到过这种情况：Claude 写了 200 行代码，你点击了“全部接受”，10 分钟后某些功能就出错了。没有测试，没有安全检查，也没人问过“这到底跟现有的代码匹不匹配？”
这个 pipeline 解决了这个问题。每一个功能在发布哪怕一行代码之前，都要经过**飞行前检查、对抗性审查、漂移检测和完整的 QA 套件**。它能发现你在代码审查中才会注意到的问题——只不过是在你 commit *之前*发现的。
**它的作用：**
- 在发布任何内容之前，对设计进行对抗性审查，并扫描 OWASP 问题
- 将 Phase 9 与你项目**真实的测试退出代码**挂钩——这是模型无法伪造的信号
- 审查实际的 git diff (Phase 12)，仅在 `APPROVE` 时提交，在此之前最多进行两次自动修复
- 为每个子进程限定工具范围，从而减少 50–78% 的单阶段 bootstrap (实测)
- 适用于任何代码库——放入 `.claude/` 文件夹即可运行
## 存在的问题
AI 编码工具非常强大，但也很冲动。告诉它“给我的应用加上登录功能”，它就会立刻开始写代码——不收集需求，不进行设计审查，也不做安全检查。结果呢？虚构的架构、被遗漏的边缘情况、范围蔓延，以及悄悄混入生产环境的漏洞。
## 解决方案
这个 pipeline 让 AI 遵循高级工程团队会使用的相同流程：
1. **理解**你真正想要的是什么
2. **设计**一个有真实文档支持的解决方案
3. **评判**该设计，从三个不同的角度——在写哪怕一行代码之前
4. **规划**提前计划好每一次文件改动，并提供确切的 before/after diff
5. **验证**计划与设计相符（没有遗漏，也没有增加）
6. **构建**严格按照计划，逐步执行
7. **检查**结果——类型、测试、文档和安全性
每个阶段都会生成具有可读性的 artifact。每一个设计决策都会引用来源。每一个被指出的评审问题都会附带修复方案。实现从任务到代码的完全可追溯性。
| 功能 | 优势 |
|---------|---------|
| **4 种模式** | `yolo` (极速), `fast`, `standard` (平衡, 默认), `paranoid` (彻底) |
| **Pre-Check 阶段** | 在从零开始构建之前，先寻找现有的代码/库 |
| **平衡的模型路由** | Opus 用于设计、对抗性审查和代码审查；Sonnet 用于其他所有环节——从不使用 Haiku |
| **测试退出代码门禁** | Phase 9 基于你真实测试套件的退出代码进行拦截，而不是听信模型的一面之词 |
| **提交代码审查** | Phase 12 审查真实的 diff 并在 `APPROVE` 时提交，带有次数受限的自动修复循环 |
| **单阶段工具范围限定** | 仅加载每个阶段所需的工具——每个子进程的 bootstrap 缩小 50–78% |
| **自动恢复** | 在暂停之前进行设计修订、漂移修复、构建重试和代码审查修复 |
| **工具无关** | 适用于 Claude Code, Cursor, Windsurf, Copilot, Cline, Aider |
## 快速开始
### 1. 复制到你的项目
```
git clone https://github.com/TheAstrelo/Claude-Pipeline.git
cp -r Claude-Pipeline/.claude/ /path/to/your/project/
```
### 2. 启动你的 AI 工具
```
# Claude Code
npx @anthropic-ai/claude-code@latest
# 或者在 Cursor、Cline、Windsurf、Copilot 或 Aider 中打开
```
### 3. 运行 pipeline
```
# 快速 prototyping — 跳过 adversarial、drift 和 QA；直接构建
/auto-pipeline --profile=yolo "add a logout button"
# Balanced（默认）— 完整 pipeline
/auto-pipeline "implement user dashboard"
# 完全监督 — 出现任何问题即暂停
/auto-pipeline --profile=paranoid "payment integration"
# 仅跳过 QA 阶段，保留 adversarial + drift + security
/auto-pipeline --profile=fast "add dashboard widget"
```
## 参数
这些是引擎 (`run-pipeline.sh`，以及转发给它的 `/auto-pipeline` 包装器) 实际会解析的参数：
| 参数 | 描述 |
|------|-------------|
| `--profile=yolo\|fast\|standard\|paranoid` | 选择一个模式 (默认: `standard`) |
| `--mode=auto\|dev` | `auto` (非交互式) 或 `dev` (在每个生成 artifact 的阶段后暂停) |
| `--skip-arm` | 跳过 Phase 1 (需求) |
| `--skip-ar` | 跳过 Phase 3 (对抗性审查) |
| `--skip-pmatch` | 跳过 Phase 5 (漂移检测) |
| `--model-strong=MODEL` | 用于 Phase 2, 3, 12 的模型 (默认: `claude-opus-4-8`) |
| `--model-fast=MODEL` | 用于所有其他阶段的模型 (默认: `claude-sonnet-5`) |
| `--max-budget-usd=N` | 单阶段花费上限 (默认: `4.00`) |
| `--max-run-budget-usd=N` | 整体运行花费上限 (默认: `15.00`) |
没有 `--yolo`/`--fast`/`--paranoid` 这种简写形式——请使用 `--profile=`。
### 示例
```
# Balanced pipeline
/auto-pipeline "add user authentication"
# 跳过 adversarial review，保留其他所有内容
/auto-pipeline --skip-ar "add dashboard widget"
# 明确限制开销并选择 models
bash run-pipeline.sh --max-run-budget-usd=8 --model-fast=claude-sonnet-5 "add dashboard widget"
# 在交互式 dev 模式下的 Standalone runner（在阶段之间暂停）
bash run-pipeline.sh --mode=dev --profile=paranoid "handle payments"
```
## 模板
使用预先配置好的模板，跳过繁琐的需求收集过程：
| 模板 | 适用场景 |
|----------|----------|
| `api-endpoint` | 带有验证的 REST API endpoint |
| `auth-flow` | JWT/OAuth 身份验证 |
| `crud-page` | 完整的 CRUD 界面 (列表、创建、编辑、删除) |
| `webhook` | 带有签名验证的 Webhook 处理程序 |
```
/auto-pipeline --template=api-endpoint "users GET /api/users"
/auto-pipeline --template=auth-flow "jwt with refresh tokens"
/auto-pipeline --template=crud-page "products with name, price, category"
/auto-pipeline --template=webhook "stripe payment_intent.succeeded"
```
## Pipeline 命令
### 核心 Pipeline
| 命令 | 描述 |
|---------|-------------|
| `/auto-pipeline
` | 运行包含所有参数的完整 pipeline |
| `/pipeline-undo` | 回滚上一次 pipeline 运行 |
| `/pipeline-history` | 显示过往运行记录及花费 |
| `/pipeline-estimate ` | 运行前预览花费 |
| `/pipeline-scan` | 主动问题检测 |
### 单个阶段
| 命令 | 阶段 | 作用 |
|---------|-------|-------------|
| `/pre-check ` | 0 | 搜索现有的解决方案 |
| `/arm ` | 1 | 需求明确化 |
| `/design` | 2 | 技术设计 |
| `/ar` | 3 | 对抗性审查 |
| `/plan` | 4 | 实施规划 |
| `/pmatch` | 5 | 漂移检测 |
| `/build` | 6 | 执行计划 |
| `/denoise` | 7 | 移除调试 artifact |
| `/qf` | 8 | 质量契合度检查 |
| `/qb` | 9 | 质量行为检查 |
| `/qd` | 10 | 质量文档检查 |
| `/security-review` | 11 | 安全审计 |
## 智能建议
### 失败时
获取带有可点击文件引用、切实可行的修复建议：
```
✗ add auth endpoint · $0.12
FAILED: Phase 3 (Adversarial) — HIGH severity issue
Suggested fixes:
1. Add input validation for email field
└─ src/api/auth.ts:24
2. Use parameterized SQL query
└─ src/api/auth.ts:31
└─ Before: WHERE email = '${email}'
└─ After: WHERE email = $1, [email]
Run /auto-pipeline --fix to auto-apply these suggestions
```
### 成功时
根据已构建的内容提供感知上下文的后续步骤：
```
✓ add user dashboard · $0.19
Created:
src/pages/dashboard.tsx
src/api/dashboard/stats.ts
Suggested next steps:
1. Run tests → /auto-pipeline --test
2. Create PR → /auto-pipeline --pr
3. Add E2E test → /auto-pipeline "add cypress test for dashboard"
```
### 主动扫描
在问题变成麻烦之前发现它们：
```
/pipeline-scan
```
```
Found 3 opportunities:
⚠ Missing tests
└─ src/api/users.ts has no corresponding test file
└─ Suggestion: /auto-pipeline "add tests for users API"
⚠ Security
└─ npm audit found 2 moderate vulnerabilities
└─ Suggestion: /auto-pipeline "fix npm audit vulnerabilities"
⚠ Documentation
└─ src/api/auth.ts missing JSDoc on 5 exports
└─ Suggestion: /auto-pipeline "add jsdoc to auth module"
Run suggested pipelines? [1/2/3/all/none]
```
## 13 个阶段
```
Task Description
│
▼
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Phase 0 │───▶│ Phase 1 │───▶│ Phase 2 │
│ Pre-Check │ │ Requirements│ │ Design │
│ [HARD] │ │ [SOFT] │ │ [SOFT] │
└─────────────┘ └──────────────┘ └──────────────┘
│
┌──────────────────────────────────────┘
▼
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Phase 3 │───▶│ Phase 4 │───▶│ Phase 5 │
│ Adversarial│ │ Planning │ │ Drift Check │
│ [HARD] │ │ [SOFT] │ │ [SOFT] │
└─────────────┘ └──────────────┘ └──────────────┘
│
┌──────────────────────────────────────┘
▼
┌─────────────┐ ┌──────────────────────────────────┐
│ Phase 6 │───▶│ Phases 7-10 │
│ Build │ │ 7: Denoise 8: Quality Fit │
│ [NONE] │ │ 9: Behavior 10: Docs │
└─────────────┘ └──────────────────────────────────┘
│
▼
┌──────────────┐ ┌────────────────────┐
│ Phase 11 │───▶│ Phase 12 │
│ Security │ │ Commit Code-Review│
│ [HARD] │ │ [HARD] ─ commit │
└──────────────┘ └────────────────────┘
│
▼
APPROVE → commit · else auto-heal ×2 → human
```
| 阶段 | 作用 | 为什么重要 |
|-------|-------------|----------------|
| **0. Pre-Check** | 在你的代码库中搜索现有的代码和库 | 防止重复造轮子 |
| **1. Requirements** | 从你的任务中提取可测试的成功标准 | 将模糊的想法转化为具体的规范 |
| **2. Design** | 创建引用真实文档的架构决策 | 决策是可追溯的，而非虚构的 |
| **3. Adversarial Review** | 三位“批评者”对设计进行压力测试 | 在写代码之前，抓住安全漏洞和边缘情况 |
| **4. Planning** | 为每一次文件改动生成确切的 BEFORE/AFTER 代码 | 确保每一次改动都是确定性的 |
| **5. Drift Detection** | 验证计划是否涵盖了所有的设计需求 | 确保没有任何遗漏或增加 |
| **6. Build** | 按计划逐步执行并进行验证 | 拒绝毫无规划的胡乱代码堆砌 |
| **7. Denoise** | 移除 console.log、debugger 和被注释掉的代码 | 保持生产环境代码整洁 |
| **8. Quality Fit** | 类型检查、linting 和约定合规性检查 | 确保代码符合项目规范 |
| **9. Quality Behavior** | 运行构建 + 测试，验证行为 | 确保代码确实按设计运行 |
| **10. Quality Docs** | 检查 Swagger/JSDoc 覆盖率 | 保持 API 文档最新 |
| **11. Security** | OWASP 扫描：注入、XSS、身份验证绕过、密钥泄露 | 在合并前抓住漏洞 |
| **12. Commit Code-Review** | 根据任务简报审查真实的 git diff；在 `APPROVE` 时提交，否则自动修复 (≤2 次) 然后请求人工介入 | 最后一道防线——没有未审查的代码会被提交 |
## 模式
| 模式 | 跳过的内容 | 门禁模式 | 适用场景 |
|---------|-------------------|-----------|-------------|
| **yolo** | 3, 5, 7-10 | soft | 原型设计、实验测试 |
| **fast** | 7-10 | standard | 功能开发、中等风险 |
| **standard** | 无 | mixed | 日常开发 (默认) |
| **paranoid** | 无 | hard | 生产环境、支付、身份验证 |
```
/auto-pipeline --profile=yolo "quick prototype"
/auto-pipeline --profile=fast "add dashboard widget"
/auto-pipeline --profile=paranoid "handle payments"
```
## 历史记录与撤销
### 查看历史记录
```
/pipeline-history
```
```
Pipeline History (last 10 runs)
# Status Task Cost Duration
─────────────────────────────────────────────────────────────
1 ✓ add user authentication $3.41 6m 22s
2 ✓ fix login bug $2.68 4m 10s
3 ✗ implement payment flow $2.15 3m 30s
└─ Failed: Phase 11 (Security)
Summary:
Total runs: 12 Success: 10 (83%) Failed: 2 (17%)
Total cost: $38.90
```
### 撤销上次运行
```
/pipeline-undo
```
回滚到 pipeline 进行更改之前创建的 git 检查点。
## 成本效益
### 模型路由 (平衡)
采用两种模型，从不使用 Haiku，也从不使用 `max` effort。Opus 负责高强度推理和最后一道防线的审查工作；Sonnet 负责其他所有环节。
| 阶段 | 模型 | Effort |
|--------|-------|--------|
| 2 Design, 3 Adversarial | `claude-opus-4-8` | high |
| 12 Commit Code-Review | `claude-opus-4-8` | xhigh (如果 CLI 有限制，则限制为 high) |
| 0 Pre-Check, 11 Security | `claude-sonnet-5` | high |
| 4, 5, 6, 9 | `claude-sonnet-5` | medium |
| 1, 7, 8, 10 | `claude-sonnet-5` | low |
使用 `--model-strong=` / `--model-fast=` 进行覆盖。每个子进程也仅加载其所在阶段的工具 (`--tools`) 并在密封环境下运行 (`--strict-mcp-config`)，从而将单阶段 bootstrap 减少了 50–78%。
### 成本
根据演示任务 (`add a GET /api/version endpoint`) 的实测结果，一次完整的 13 阶段运行成本约为 **$3–6**：三个 Opus 阶段 (Design, Adversarial, Code-Review) 每个花费约 $0.8–1.7，占据了大头；Sonnet 阶段每个花费约 $0.13–0.26。一次带有 `--skip-ar` 且没有进行代码审查修复的运行最终花费为 **$3.06**；一次触发了 `REQUEST_CHANGES` 并自动修复一次的运行花费为 **$3.83** (额外花费的约 $1 买到的是一次修复过程 + 第二次 Opus 审查，从而避免了对人工介入的中断)。
单次花费受 `--max-budget-usd` (单阶段，默认 $4) 限制，整体运行花费受 `--max-run-budget-usd` (整个运行过程，默认 $15) 限制。每个阶段都会 `--output-format json`，因此单阶段的 `total_cost_usd` 会被记录在 `.claude/history.json` 中——运行一次，即可获取你自己任务的真实数据。
## 文件结构
```
Claude-Pipeline/
├── run-pipeline.sh # THE engine (13 phases, gates, commit)
├── .claude/
│ ├── commands/ # 22 slash commands
│ │ ├── auto-pipeline.md # Thin wrapper that runs run-pipeline.sh
│ │ ├── plan-review.md # Plan → review (dispatches to agents)
│ │ ├── design.md · ar.md · pmatch.md · security-review.md # per-phase helpers
│ │ └── pipeline-scan.md # Proactive scanning (code-scanner agent)
│ ├── agents/ # 15 agents — reachable from a live slash command
│ │ ├── architect.md · atomic-planner.md · adversarial-coordinator.md
│ │ ├── security-auditor.md · code-scanner.md · builder.md · denoiser.md …
│ ├── lib/ # Reference docs (error patterns, next steps, context)
│ ├── templates/ # Pattern references (api-endpoint, auth-flow, crud-page, webhook)
│ ├── hooks/ # protect-files.sh + auto-format.sh (Claude Code, via settings.json);
│ │ │ # detect-project.sh + notify.sh (run-pipeline.sh startup/exit)
│ ├── history.json # Run history (per-run costUSD)
│ └── artifacts/ # Per-session output ({session}/*.md + .raw/.err/.verdict)
│
├── targets/ # Other tool ports (cursor, cline, windsurf, copilot, aider, codex)
├── demo/ # Demo kit (starter Express project + red acceptance test)
└── pipeline-viz/ # Real-time pixel-art visualization
```
## 自定义
### 规则
在 `.claude/rules/` 中添加项目特定的规范：
```
# .claude/rules/api.md
- Use Hono instead of Express
- Return { data, error } shape
```
### Hooks
**Claude Code hooks** (配置在 `.claude/settings.json` 中，由测试框架强制执行)：
```
# protect-files.sh — PreToolUse(Edit|Write)：阻止对 .env、.git/、
# package-lock.json、amplify.yml 和 .claude/settings.json 的编辑。
# 失败时 CLOSED（解析失败时拒绝），并使用 node，而不是 jq。
# auto-format.sh — PostToolUse(Edit|Write)：格式化刚刚写入的文件。
```
**引擎生命周期 hooks** (配置在 `run-pipeline.sh` 中)：
```
# detect-project.sh — 在启动时运行：检测 stack（framework、language、
# test/build/lint 命令、search dirs），将
# project-config.json 写入 session artifacts，如果
# 未找到 test 命令则进行填充，并在每个 phase prompt 的开头
# 添加一行“匹配此 stack”的说明。
# notify.sh — 通过 EXIT trap 在每次退出时触发（成功、HARD-gate 停止、预算削减、
# 错误）：桌面通知 + 终端响铃，
# 跨平台（macOS / Linux / Windows toast + beep）。
```
## 工具支持
这个 pipeline 是**工具无关**的。将 `.claude/` 文件夹放入任何项目中，即可与以下工具配合使用：
| 工具 | 状态 | 备注 |
|------|--------|-------|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | 完全支持 | 原生斜杠命令 |
| [Cursor](https://cursor.sh) | 完全支持 | 通过 rules 和 agents |
| [Windsurf](https://codeium.com/windsurf) | 完全支持 | 通过 rules 和 agents |
| [GitHub Copilot](https://github.com/features/copilot) | 完全支持 | 通过 instructions |
| [Cline](https://github.com/cline/cline) | 完全支持 | 通过 custom instructions |
| [Aider](https://aider.chat) | 完全支持 | 通过 conventions |
## 实时可视化
`pipeline-viz/` 文件夹包含一个**实时像素艺术可视化工具**，它将你的 pipeline 进度展示为一个动画的等距视角办公室，里面还有坐在办公桌前工作的 agents。
```
cd pipeline-viz && npm install && npm start
```
## 环境要求
- 一款 AI 编码工具 (Claude Code, Cursor, Cline, Windsurf, Copilot, Codex 或 Aider)
- Node.js (用于 QA 阶段中的构建/类型检查步骤)
- 一个包含 `CLAUDE.md` 文件的项目
## 贡献
欢迎各种形式的贡献——提交 issue 或 PR 皆可。无论是新的 agent、bug 修复，还是更好的文档，我们都深表感激。
## 许可证
MIT —— 详见 [`LICENSE`](LICENSE)。随意使用它、改造它、发布它。