大模型驱动的自动化编码任务：设计方案与落地实践

目录

• 1. 问题定义与目标
• 2. 核心理念：从 Copilot 到 Autonomous Coder
• 3. 总体架构设计
• 4. 关键能力模块详设
  • 4.1 任务理解与拆解（Task Decomposer）
  • 4.2 上下文工程（Context Engine）
  • 4.3 代码生成与编辑（Code Editor）
  • 4.4 执行与验证（Verify Loop）
  • 4.5 自修复闭环（Self-Healing）
  • 4.6 状态与断点（State & Resume）
• 5. 全流程时序图
• 6. 工具与技术选型
• 7. 可落地实践步骤（4 周 MVP）
• 8. 评估体系与度量指标
• 9. 风险与反模式
• 10. 附录：Prompt 与配置样例

---

1. 问题定义与目标

1.1 什么叫"自动化编码任务"

不是"代码补全"，而是端到端完成下面这种任务：

给定一个 Jira 工单或一段自然语言需求，模型 自主 完成：理解 → 拆解 → 改代码 → 跑测试 → 自修复 → 提 PR，全程无人逐步干预。

1.2 目标分层

等级	能力	典型场景	人介入度
L0 辅助	代码补全 / 单文件改写	IDE 内 inline 建议	每步介入
L1 单步代理	改一个函数 + 跑一次测试	修一个小 bug	任务级介入
L2 多步代理	改多个文件 + 自修复循环	加一个 API 字段	启动 + 验收
L3 任务级自治	完整 PR（含测试）	中小型 feature	只看最终 PR
L4 多任务并行	多 Worktree 并行夜跑	批量重构 / 适配	早上看汇总

本方案目标：稳定达到 L3，部分场景达到 L4。

1.3 衡量"成功"的硬指标

• 一次性通过率（First-Pass Rate）≥ 60%：模型首次产出 PR 即可合入
• 自修复成功率 ≥ 80%：失败后 5 轮内能自愈
• 平均完成时长 ≤ 30 分钟 / 中小型任务
• Token 成本 ≤ 0.5 元 / 任务（按当前主流模型）

---

2. 核心理念：从 Copilot 到 Autonomous Coder

2.1 三条第一性原理

1. Harness 优于 Model
   换模型只能提升几个点；优化上下文 + 工具 + 反馈循环，可提升 10+ 个百分点。重投入应该放在工程而不是换模型。

2. 反馈闭环优于一次生成
   “生成 → 执行 → 看错误 → 再生成"的循环，胜过"一次生成 1000 行”。让模型像人一样 小步快跑、依赖编译器/测试反馈。

3. 结构化输入优于自由文本
   把"模糊需求"变成"Spec + Plan"再喂给模型，幻觉率断崖式下降。任何自动化都从 结构化任务定义 开始。

2.2 心智模型：把模型当成"实习工程师"

实习生能完成任务的前提：

• 有清晰的需求文档（→ Spec）
• 有项目说明书（→ CLAUDE.md / 项目记忆）
• 有完整的开发环境（→ 沙箱 + worktree）
• 有自检手段（→ lint / test / 编译器）
• 卡住时知道找谁（→ 升级到人或更强模型）

自动化编码 = 把这五件事工程化、协议化、可复用。

---

3. 总体架构设计

3.1 三层架构

3.2 数据流总览

核心数据契约（每一步都是结构化产物）：

阶段	产物	形态
理解	spec.yaml	需求 + 验收 + 约束
拆解	plan.json	任务 DAG
实现	patch.diff	git diff
验证	verify.json	测试/lint/编译结果
评审	review.md	多维评分

---

4. 关键能力模块详设

4.1 任务理解与拆解（Task Decomposer）

4.1.1 目标

把"加一个按门店筛选导出"变成机器可执行的步骤清单。

4.1.2 流程

4.1.3 关键设计

• 原子任务粒度：单任务 token 预算 ≤ 20k、改动文件 ≤ 5 个，超过自动拆分
• 每个任务自带验收钩子（acceptance: ["unit:xx.spec.ts"]），保证"做完=可验证"
• 依赖关系 DAG：标注 parallelizable: true 的任务可并行
• 使用顶级规划模型（Opus 级 / DeepSeek-R1）；执行用性价比模型（Sonnet 级 / Qwen-Coder）

4.1.4 Plan 数据结构

{
  "spec_id": "TASK-001",
  "tasks": [
    {
      "id": "T1",
      "desc": "扩展 export API 增加 shopId 参数",
      "files": ["api/order/export.ts"],
      "depends_on": [],
      "parallelizable": true,
      "acceptance": ["unit:export.shopId.spec.ts"],
      "token_budget": 8000,
      "risk": "low"
    }
  ],
  "rollback_plan": "回滚到上一个 tag"
}

---

4.2 上下文工程（Context Engine）

这是自动化编码效果的天花板。 喂错上下文，再强的模型也写错代码。

4.2.1 四级上下文

4.2.2 关键技术点

① 代码 RAG（检索相关代码）

• 向量库：Milvus / Qdrant
• embedding 模型：bge-code / Qwen3-Embedding
• 切分策略：按 AST 函数级 切分，不按行数（避免切碎语义单元）
• 检索结果：Top-K 相关函数 + 调用链

② 上下文压缩

• 总 token 超阈值时，自动做"摘要 + 关键锚点保留"
• 关键锚点格式：file_path:line 让模型可精确回跳

③ 项目级长期记忆

• CLAUDE.md：项目一句话简介、架构图、领域术语、编码规范、禁止事项
• AGENTS.md：Agent 协作规范
• 这两个文件 强制约束 60 行以内，每次都注入

4.2.3 上下文构造伪代码

def build_context(task):
    return {
        "system": load_project_memory("CLAUDE.md"),
        "task": task.spec + task.acceptance,
        "code_snippets": rag_search(task.desc, top_k=10),
        "runtime": last_error_log or "",
        "budget": 20000  # token 上限
    }

---

4.3 代码生成与编辑（Code Editor）

4.3.1 输出形态：必须用 diff/patch，而不是整文件重写

主流做法：让模型输出 search-replace block，由 Harness 应用补丁：

function exportOrder(req, shopId) {

4.3.2 多文件编辑策略

• 单文件多块：一次返回多个 search-replace block
• 多文件改动：Harness 串行应用，每次应用后立即语法校验
• 冲突检测：同时改同一文件由 Harness 串行化（避免并发污染）

4.3.3 隔离执行环境

• git worktree：每任务独立工作区，互不污染
• docker 沙箱：禁网 / 白名单网，限 CPU/内存/时长
• Secrets：通过 Vault sidecar 注入，绝不进上下文

---

4.4 执行与验证（Verify Loop）

没有验证的代码生成是耍流氓。 这是"自动化"区别于"自动补全"的核心。

4.4.1 验证金字塔

自下而上、快的先跑：

1. 语法/编译（最快、最常失败）
2. lint + typecheck（秒级）
3. 单元测试（针对 diff 涉及函数）
4. 集成测试（API 契约）
5. E2E（最慢、对应 AC）

任何一层失败立即返回错误给模型，不浪费跑后面的层。

4.4.2 测试自动生成（AC → 测试）

每条 AC 必须有 test_hook，例如：

acceptance:
  - given: 用户选择门店A
    when: 点击导出
    then: 文件仅含门店A订单
    test_hook: e2e/order-export.spec.ts::filter_by_shop

Test Agent 根据 given/when/then 自动生成 Playwright 脚本，强制做到：

AC 总数 == 已覆盖测试数，否则 PR 阻断。

4.4.3 验证结果结构化

{
  "stages": {
    "compile": {"pass": true, "duration_ms": 1200},
    "lint":    {"pass": false, "errors": [{"file":"a.ts","line":42,"msg":"unused"}]},
    "unit":    {"pass": false, "failed": ["test_a"]},
    "e2e":     {"skipped": true}
  },
  "next_action": "fix_lint_then_unit"
}

模型拿到这个 JSON 就知道下一步怎么做。

---

4.5 自修复闭环（Self-Healing）

4.5.1 流程

4.5.2 关键策略

失败类型	修复策略	示例
语法错误	直接喂错误信息	Unexpected token at line 42
类型错误	喂类型签名 + 错误位置	Type 'string' not assignable to 'number'
单测失败	喂用例输入 + 期望 vs 实际	expected 5 got 4
Flaky 失败	重试 3 次取多数	网络抖动等
环境错误	切镜像 / 重建沙箱	依赖装不上

4.5.3 防止"死循环"

• N 轮上限（默认 5 轮）：超过停在最近绿色快照，通知人
• 进步检测：若连续 2 轮错误数没下降 → 立即升级（换模型/通知人）
• token 预算：单任务累计 token 超限即停

---

4.6 状态与断点（State & Resume）

4.6.1 为什么必须做状态持久化

夜跑 8 小时、并行 N 任务、网络抖动、机器重启…… 没有断点续跑就没有真正的自动化。

4.6.2 设计

每步快照内容：

{
  "task_id": "T1",
  "step": 7,
  "phase": "verify",
  "input": "...",
  "output": "...",
  "tool_calls": [...],
  "token_used": 1234,
  "timestamp": "2026-05-13T10:00:00Z"
}

支持 人工接管 → 再交还 AI 的混合模式。

---

5. 全流程时序图

---

6. 工具与技术选型

6.1 MVP 最小栈（10 件套）

6.2 模型选型矩阵

角色	推荐模型	替代	理由
Planner	Opus / GPT-5 / DeepSeek-R1	Claude 3.7 Sonnet Thinking	强推理
Coder	Sonnet / Qwen3-Coder / Composer	DeepSeek-V3	性价比+长上下文
Critic	同 Planner	-	评审需推理
Embedding	bge-code / Qwen3-Embedding	text-embedding-3	代码语义

6.3 工具清单（按必要性）

优先级	工具	用途
P0	git worktree	任务隔离
P0	docker / nsjail	沙箱执行
P0	lint + test runner	反馈源
P0	向量库（代码 RAG）	上下文
P0	gitlab/github MCP	PR 操作
P0	langfuse	trace/回放
P1	jira/feishu MCP	任务接入
P1	semgrep + trivy	安全扫描
P2	playwright	E2E
P2	computer-use	真实环境操作

---

7. 可落地实践步骤

7.1 实施路线图

7.2 详细步骤

一、地基（必做）

搭建沙箱

• 写一个 Dockerfile，预装项目所有依赖
• 准备 git worktree 脚本：scripts/new-worktree.sh task-id
• 验证：在沙箱内能 git clone + npm install + npm test 跑通

写项目记忆

• 创建 .ai/CLAUDE.md，包含：
  • 项目一句话简介 + 架构图
  • 领域术语表（5-10 个核心概念）
  • 编码规范（命名/目录/测试要求）
  • 禁止事项（如不得引入某依赖）
  • 常用脚本（build/test/lint）
• 强制 60 行以内，每次都注入

选模型 + 接 API

• 至少接 1 个 Planner 模型 + 1 个 Coder 模型
• 准备 token 记账工具（langfuse 或自研）

二、单任务闭环（核心）

实现 Spec + Plan

• 写一个 CLI：auto-code "修复登录页验证码不显示"
• 内部流程：
  1. 调 Planner 生成 spec.yaml
  2. 调 RAG 找相关文件
  3. 生成 plan.json（哪怕只有 1 个 task）

实现 Code + Apply

• 让 Coder 输出 search-replace block
• 写一个 patch applier（用 git apply 或自研解析器）
• 应用到 worktree

跑通端到端

• 找一个真实的小 bug（5 分钟人能修完的那种）
• 全程让 AI 跑通：理解 → 改代码 → 跑测试 → 输出 diff
• 不强求第一次就通过，目标是流程跑通

三、让它"真的可用"

自修复闭环

• 实现 verify.json 结构化输出
• 失败时把错误塞回 Coder 上下文
• 限 5 轮，超出挂起
• 度量：一次性通过率、自修复成功率

测试生成

• 让 Test Agent 根据 AC 自动写单测
• 强制：AC 数 = 测试数，否则 PR 阻断

State Store

• 用 SQLite 存每步快照
• 实现 auto-code resume <task-id>

四、放大规模

：PR 自动化

• 接 gitlab/github MCP
• AI 自动推 PR，PR 描述含：Spec ID / 改动文件 / 测试证据 / 回滚步骤

多任务并行

• 一次输入多个任务 → 多 worktree 并行
• 任务调度器（简单的线程池就行）

度量看板

• 接入 langfuse 或自研，看板含：
  • 一次性通过率
  • 平均 token 成本
  • 自修复成功率
  • 失败 Top-N 原因

7.3 任务选择策略

适合做自动化的任务：

• ✅ 改字段名 / 加参数
• ✅ 写单元测试
• ✅ 修明确的 bug（有复现步骤）
• ✅ 升级依赖 + 适配
• ✅ 国际化文案补全
• ✅ API 文档生成

不适合的：

• ❌ 架构级重构
• ❌ 性能优化（涉及业务判断）
• ❌ 安全相关代码
• ❌ 复杂业务逻辑设计

7.4 0→1 检查清单

落地前问自己 10 个问题：

• 有 CLAUDE.md 项目记忆吗？
• 有干净的沙箱（docker + worktree）吗？
• 测试命令 30 秒内能跑完吗？（否则反馈循环太慢）
• 有结构化的 verify 输出吗？
• 自修复轮数有上限吗？
• token 预算有上限吗？
• 失败有人工接管入口吗？
• 每一步有快照可恢复吗？
• 有 trace 平台能回放吗？
• 第一批任务选的是"绿区"吗？

---

8. 评估体系与度量指标

8.1 四类核心指标

8.2 推荐目标值（团队级，3 个月后）

指标	MVP（第 1 月）	进阶（第 3 月）
一次性通过率	≥ 30%	≥ 60%
自修复成功率	≥ 50%	≥ 80%
Token/任务	≤ 2 元	≤ 0.5 元
平均完成时长	≤ 60 min	≤ 30 min
缺陷逃逸率	与基线持平	下降 ≥ 20%

8.3 失败任务复盘机制

失败 Top-5 任务复盘，找根因：

• 上下文不够？→ 改进 RAG
• 任务太大？→ 改进拆解
• 测试不稳定？→ 修测试
• 模型能力不够？→ 升级模型 / 加 Critic

---

9. 风险与反模式

9.1 技术风险

风险	对策
幻觉写出不存在 API	强 RAG + Critic 二次审
上下文超长丢信息	压缩 + 锚点 + 任务拆细
自修复死循环	N 轮上限 + 进步检测
成本失控	每任务 token 预算 + 告警
测试不稳定误判	重试 3 次取多数
改坏现有代码	worktree 隔离 + PR 评审

9.2 反模式（必须避免）

9.3 边界（坚决不让 AI 做）

• 生产环境 DDL 执行（写脚本可以，执行人工）
• 权限/支付/金融核心逻辑（建议可以，决策权人）
• 安全应急响应（仅辅助 RCA）
• 直接 SSH 生产服务器

---

10. 附录：Prompt 与配置样例

10.1 Planner Prompt 骨架

你是 Planner Agent。请把下面的需求拆解成可执行的最小任务图。

【需求】
{spec}

【项目约定】
{CLAUDE.md 摘要}

【影响面】
{impact.json}

【输出格式】严格 JSON，包含 tasks[] / depends_on / acceptance / rollback_plan。
【约束】
1. 单任务 token ≤ 20k，改动文件 ≤ 5；
2. 每个任务必须有 acceptance 测试钩子；
3. 标注 parallelizable 字段。

10.2 Coder Prompt 骨架

你是 Coder Agent。在 worktree 内完成下面任务。

【任务】
{task.json}

【项目约定】
{CLAUDE.md}

【相关代码片段】
{rag_top_k}

【上一轮错误（如有）】
{last_error}

【输出格式】严格使用 search-replace block，不要输出整文件。
【规则】
1. 仅改 task.files 列出的文件；
2. 不引入新依赖（如必须，先在输出顶部说明）；
3. 改完后简要说明改动逻辑（≤ 100 字）。

10.3 项目配置 auto-code.yaml

model:
  planner: claude-opus-4
  coder: qwen3-coder-480b
  critic: claude-sonnet-4
budget:
  token_per_task: 20000
  max_heal_rounds: 5
  timeout_min_per_task: 30
sandbox:
  image: registry.internal/auto-code:latest
  cpu: 2
  memory_gb: 4
  network: whitelist
rag:
  vector_db: qdrant
  embedding: bge-code-v1
  top_k: 10
verify:
  lint: "npm run lint"
  test: "npm test -- --bail"
  e2e: "npx playwright test"
permissions:
  default: L2  # 沙箱可写
  allow_pr: true
  allow_merge: false
trace:
  endpoint: https://langfuse.internal

10.4 .ai/CLAUDE.md 模板（60 行内）

# 项目：订单中心

## 一句话
负责订单全生命周期，对接支付/库存/履约。

## 架构
- 前端：React 18 + Vite
- 后端：Node.js 20 + NestJS + PostgreSQL
- 部署：k8s + 行云

## 领域术语
- SKU：库存单元
- SPU：商品单元
- 履约单：订单的子结算单元

## 编码规范
- TS strict 模式，禁 any
- API 必须 OpenAPI 文档
- 单测覆盖率 ≥ 80%
- commit message: type(scope): desc

## 禁止事项
- 不引入 moment（用 dayjs）
- 不直接写 SQL（用 TypeORM）
- 不修改 migration 历史文件

## 常用命令
- build: `npm run build`
- test:  `npm test`
- lint:  `npm run lint`
- e2e:   `npm run e2e`

## API 契约
docs/openapi/order.yaml

---

自动化编码 = 结构化任务输入 + 工程化反馈闭环 + 隔离化执行环境 + 可恢复的状态机。

模型只是其中一环；Harness 才是把"AI 助手"变成"AI 同事"的关键工程投入。