Auto-Agent — 长程任务工程化框架

> Planner-Generator-Evaluator 三代理架构 + Sprint Contract 协商 + 对抗性评估。

> 核心原则：复杂任务的问题不是 AI 不够聪明，而是上下文污染和自我评估偏差。

何时使用

自动触发：

• 预计修改 3 个以上文件
• 设计新模块、新系统、新架构
• 大型重构或重写
• 用户说"复杂功能""大任务""长程""重构"

不触发：

• 单文件修复、小改动、查询类问题
• 简单的 bug 修复（1-2 文件）
• 代码审查、文档更新

快速开始

首次进入框架时，在项目根目录创建：

mkdir -p .auto-agent

需要 5 个核心文件：

项目/.auto-agent/
├── tasks.json             # 任务清单（单一事实来源）
├── progress.md            # 进度日志 + 决策记录
├── handoff.md             # 会话间交接工件
├── sprint-contract.md     # 当前任务 Generator-Evaluator 契约
└── review-checklist.md    # 项目特定的审查标准

可选辅助目录：

├── scripts/               # 自动化执行脚本（无人值守模式）
│   ├── run-task.ps1        #   执行单个任务
│   └── run-agent.ps1       #   持续执行多个任务
└── templates/              # 项目特定的代码模板
    └── system-template.txt #   新模块的起手式骨架

核心机制

1. Sprint Contract（冲刺契约）

每个任务开始前，必须先协商契约并写入 sprint-contract.md。

契约必须包含：

1. 目标 — 这个任务要完成什么（一句话）
2. 验收标准 — 可验证的通过条件，必须是可测试的（"功能正常"不是验收标准）
3. 涉及文件 — 预计修改/新建的完整文件路径列表
4. 完成定义 — 什么状态下可以标记 passes: true
5. 测试方式 — 如何验证：编译检查 / 运行测试 / 手动验证 / 自动化测试

示例：

目标: 实现用户登录 API 调用及 Token 持久化
验收标准:
  1. 输入用户名密码后，2 秒内 POST 请求发送到 /api/login
  2. 成功后 token 加密存储到本地，UI 切换到主页
  3. 失败后弹窗显示服务端返回的错误信息
  4. 网络超时 10 秒后显示"网络异常，请重试"
涉及文件:
  - src/services/ApiClient.ts
  - src/systems/LoginSystem.ts
  - src/ui/LoginPanel.tsx
测试方式: 编译检查 + 手动验证登录流程 + 模拟网络超时

2. 三角色分工

为什么必须分离：

• 同一个模型写代码 + 审代码 = 自我评估偏差（对自己的错误视而不见）
• Evaluator 只读代码文件 + Sprint Contract，不看 progress.md 中的实现说明
• Evaluator 必须刻意挑剔——原文："tuning a standalone evaluator to be skeptical is far more tractable than making a generator critical of its own work"

3. 任务分解规则

• 每个原子任务 1-3 个文件
• 依赖关系在 tasks.json 的 dependencies 字段记录
• 每个任务必填：acceptance_criteria、steps、critical_files
• estimated_complexity：low / medium / high，决定 Evaluator 严格程度

4. 评估评分矩阵

任一维度低于 hard threshold → 退回 Generator 修复 → 进入下一轮迭代。

典型迭代 2-4 轮，超过 3 轮仍未通过 → 升级为 blocked。

5. 复杂度分级策略

五阶段开发流程

Plan → Explore → Implement → Test → Review
 ↑                                    │
 └────────── 未通过，退回重来 ─────────┘

Phase 1: Plan

角色：Planner

1. 分析需求 → 拆解为原子任务 → 写入 tasks.json
2. 起草 Sprint Contract → 写入 sprint-contract.md
3. 识别任务依赖 → 填入 dependencies
4. 更新 progress.md 记录决策

Phase 2: Explore

角色：Planner

1. 读取现有相关代码，理解架构模式
2. 识别可复用的模块、接口、工具函数
3. 确认不重复造轮子
4. 记录发现到 progress.md

Phase 3: Implement

角色：Generator

1. 按 tasks.json 的 steps 顺序实现
2. 遵循项目现有架构模式，优先复用
3. 完成子任务后自评估 — 对照契约检查
4. 更新 progress.md
5. 每个任务单独 git commit

Phase 4: Test

角色：Generator

1. 编译检查（必须通过）
2. 功能路径测试（主流程 + 边界情况）
3. 修复自评估发现的问题

Phase 5: Review

角色：Evaluator

Evaluator 必须首先声明：

> "切换为 Evaluator 角色。以下是仅基于代码文件和 Sprint Contract 的独立评估，未受 Generator 实现思路影响。"

1. 对照 Sprint Contract 逐条验收
2. 四维度评分（功能正确性 / 架构合规 / 代码质量 / 复用性）
3. 任一维度低于 hard threshold → 记录详细原因 + 修复建议 → 退回
4. 全部通过 → tasks.json 中 passes: true，status: completed

上下文管理

新会话恢复协议

按序读取恢复上下文：

1. tasks.json → 当前所有任务状态
2. progress.md → 最新进度和决策记录
3. handoff.md（如存在）→ 上次会话交接状态
4. 当前任务涉及的代码文件

阻塞处理

连续 3 轮迭代未通过 → status: blocked：

• progress.md 中记录完整阻塞原因
• 输出以下格式的阻塞信息并停止：

🚫 任务阻塞 - 需要人工介入
当前任务: TASK-001 - 任务标题
阻塞原因: [具体原因]
已完成: [已完成内容]
解除后: [具体步骤]

• 禁止谎报通过、禁止将 passes 设为 true

tasks.json 格式

{
  "id": "TASK-001",
  "title": "简短标题",
  "description": "详细描述",
  "status": "planned | in_progress | completed | blocked",
  "phase": "Plan | Explore | Implement | Test | Review",
  "passes": false,
  "acceptance_criteria": ["可验证标准1", "可验证标准2"],
  "steps": ["具体步骤1", "具体步骤2"],
  "dependencies": ["TASK-000"],
  "critical_files": ["path/to/file1.cs", "path/to/file2.cs"],
  "estimated_complexity": "low | medium | high",
  "iteration": 0,
  "created_at": "YYYY-MM-DD",
  "updated_at": "YYYY-MM-DD"
}

安全规则

自动化级别：

• Level 1（推荐）：人工选择任务，AI 执行，人工验收
• Level 2：AI 自动选任务，执行前人工确认
• Level 3：完全自动 + 定期人工检查（需 --dangerously-skip-permissions）
• Level 4：完全无人值守（不推荐，仅成熟项目可用）

安装到你的项目

# 通过 SkillHub（推荐，国内加速）
# 在 Claude Code 中说："安装 auto-agent 技能"

# 通过 npx skills（国际）
npx skills add <your-org>/auto-agent -g -y

# 手动安装
mkdir -p ~/.claude/skills/auto-agent
# 复制 SKILL.md 到上述目录

项目专属配置（代码模板、审查清单）放在项目 .auto-agent/ 下。