auto-claude-build

用途

Auto-Claude 是一个自主构建系统（autonomous build system）。根据资料，它适用于以下场景：运行构建、理解 Agent 工作流、管理并行执行，以及排查构建问题。其目标是将一个规格（Spec）持续转化为经过 QA 验证的代码改动。

主要能力

构建流水线

系统架构为：Spec → 规划 Agent（Planner Agent）→ 编码 Agent（Coder Agent）→ QA 审查器（QA Reviewer）→ QA 修复器（QA Fixer）→ 完成。各阶段产物依次为 impl_plan.json、代码改动、QA 报告、修复后的代码。

Agent 角色

Planner：创建基于子任务的实现计划，使用 Claude，思考 token 为 5000。
Coder：实现子任务，可派生子 Agent，使用 Claude，无思考 token。
QA Reviewer：验证验收标准，使用 Claude，思考 token 为 10000。
QA Fixer：修复 QA 报告的问题，使用 Claude，无思考 token。

所有 Agent 使用 Claude Agent SDK，在 core/client.py 中配置。示例代码：

from core.client import create_client

client = create_client( project_dir=project_dir, spec_dir=spec_dir, model="claude-opus-4-5-20251101", agent_type="coder", # or "planner", "qa_reviewer", "qa_fixer" max_thinking_tokens=None # or 5000, 10000, 16000 )

安全层

Sandbox：操作系统级 bash 隔离
Filesystem Permissions：限制在项目目录内
Command Allowlist：仅允许已批准命令（见 security.py）

可用工具

Read、Write、Edit：文件操作（所有 Agent）
Glob、Grep：文件搜索（所有 Agent）
Bash：Shell 命令（白名单内，所有 Agent）
Context7：文档查询（所有 Agent）
Linear：项目管理（所有 Agent，若启用）
Graphiti：记忆系统（所有 Agent，若启用）
Electron/Puppeteer：浏览器测试（仅 QA）

并行执行

Coder Agent 可派生子 Agent 进行并行工作，例如：主 Coder Agent 下挂前端子 Agent、后端子 Agent 与测试子 Agent。配置最多 12 个 Agent 终端，每个在隔离上下文中运行，结果自动合并。

Git Worktree 策略

每个 Spec 对应一个分支，所有工作在隔离 worktree 中进行，不自动推送，由用户控制合并时机。结构为：main（你的分支）下创建 auto-claude/{spec-name} 隔离 worktree。

使用方式

运行构建

基本构建命令：

cd apps/backend source .venv/bin/activate

Run build for spec

python run.py --spec 001

With iteration limit (for testing)

python run.py --spec 001 --max-iterations 5

构建选项：

--spec SPEC：要构建的 Spec（编号或完整名称）
--max-iterations N：限制构建迭代次数
--skip-qa：跳过自动 QA 验证
--qa：仅运行 QA 验证

构建流程

初始化：创建用于隔离的 git worktree、加载 Spec 与实现计划、设置安全沙箱。
规划阶段：Planner Agent 分析 Spec、创建子任务拆分、分配依赖。
实现阶段：Coder Agent 实现子任务、可派生子 Agent 并行工作、实时更新进度。
QA 阶段：QA Reviewer 验证每个验收标准、生成 QA 报告；若有问题，QA Fixer 应用修复；循环直至通过（最多 50 次迭代）。

监控构建

实时进度：

Watch build progress

tail -f .auto-claude/specs/001-feature/build-progress.txt

Check implementation plan status

cat .auto-claude/specs/001-feature/implementation_plan.json | jq '.subtasks[] | {id, title, status}'

交互控制：构建期间按一次 Ctrl+C 可暂停并添加指令，按两次立即退出。也可使用文件式控制：

Pause after current session

touch .auto-claude/specs/001-feature/PAUSE

Add instructions

echo "Focus on the login flow" > .auto-claude/specs/001-feature/HUMAN_INPUT.md

Resume

rm .auto-claude/specs/001-feature/PAUSE

构建产物

目录结构包含：spec.md（规格）、implementation_plan.json（含状态的子任务计划）、build-progress.txt（实时进度日志）、qa_report.md（QA 验证结果）、QA_FIX_REQUEST.md（若被拒绝，需修复的问题）、graphiti/（记忆数据，若启用）、worktree/（Git worktree 信息）。

实现计划中的子任务状态可为 pending、in_progress、complete、blocked，并记录 started_at、completed_at。

QA 验证

QA Reviewer 逐条验证验收标准（示例）：

QA Report

Acceptance Criteria

[x] User can log in with email → PASS
[x] Error shown for invalid credentials → PASS
[ ] Session persists across page refresh → FAIL: Session not being saved

Issues Found

Session cookie not being set correctly in AuthProvider

QA Fixer 会自动读取 QA_FIX_REQUEST.md、分析根因、实施修复、触发重新验证。QA 循环为：QA Reviewer → 有无问题？无则完成；有则进入 QA Fixer → 重新验证（最多 50 轮）。

适用场景与限制

排查构建问题

构建卡住时可查看进度日志、搜索错误、移除 PAUSE 后强制重启：

Check what's happening

tail -100 .auto-claude/specs/001-feature/build-progress.txt

Check for errors

grep -i error .auto-claude/specs/001-feature/build-progress.txt

Force restart

rm .auto-claude/specs/001-feature/PAUSE python run.py --spec 001

Agent 恢复：Coder 具有恢复提示（coder_recovery.md），在子任务多次失败时激活。也可手动介入，通过 HUMAN_INPUT.md 添加人工输入。

常见问题与对应处理：

Timeout errors：在 .env 中增大 API_TIMEOUT_MS
Memory errors：减少 max_thinking_tokens
Tool failures：检查安全白名单
Git conflicts：运行 --review 并手动解决

高级配置

模型覆盖：

Use different model

AUTO_BUILD_MODEL=claude-sonnet-4-5-20250929 python run.py --spec 001

扩展思考配置：ultrathink 16000 tokens（规格创建）、high 10000 tokens（QA 审查）、medium 5000 tokens（规划）、None 禁用（编码）。

调试模式：

DEBUG=true DEBUG_LEVEL=3 python run.py --spec 001

限制

资料未提供具体的收费、价格、平台支持范围、性能指标或效果承诺信息。除上述明确列出的能力与配置外，未提及的功能与步骤暂未提供。

技能介绍

用途