搭建面向AI编程代理的软件工厂：原理与最小实现

“软件工厂”这个概念在传统软件工程里，指的是用标准化流程、复用资产和车间式分工来高效地生产软件。引入 AI 编程代理之后，这个概念被重新激活了。原因很直接：单个代理写代码再快，也只是把个人效率放大；只有把代理放进一套有约束的流水线，也就是一个面向 AI 编程代理的软件工厂，才能让多个代理并行处理不同模块，并把每个任务的输入、过程、结果都变成可审计、可回滚、可评估的工程资产。

这篇文章适合正在考虑引入 AI 编程代理的团队，也适合那些已经在用 AI 编码工具，但还是停留在“让 AI 写一段代码，人来改一改”阶段的技术负责人。文章会带你把一个最小软件工厂拆开，依次看清：代理和软件工厂之间是什么关系，需要统一哪些基础设施约定，怎么设计一条可复现的代理流水线，怎么写出一个最小可运行实现，以及如何验证、观测和排查问题。

1. 先想清楚：AI 编程代理和软件工厂之间是什么关系

1.1 从“AI 补全”到“代理式开发”，执行方式发生了变化

传统的 AI 编码工具，本质是“输入上下文，输出代码片段”。人类开发者负责定位问题、决定改哪个文件、组织代码结构、运行测试、提交合并。AI 在这里是一个补全器，它不拥有任务。

AI 编程代理不同。代理拿到一个目标之后，可以自己去读仓库文件、修改多个文件、运行命令、检查报错、调整方案，甚至创建 Pull Request。也就是说，人类从“逐行写代码”变成了“提需求、审结果、控风险”。

这两种方式的差异不只是工具进化，而是责任边界发生了变化。

这就带来一个新的问题：代理的自主性越强，对流程约束的要求就越高。没有约束的代理，会把一个局部改动扩展成整个仓库的重构；没有验证的代理，会自信地给出一个能编译但语义错误的方案。面向 AI 编程代理的软件工厂，核心目标就是把这些风险收进轨道里。

1.2 软件工厂在代理开发中承担什么职责

可以这样理解：软件工厂不是让你不再写代码，而是把“让代理写代码”这件事工程化。

真实项目里，代理最需要的并不是更聪明的提示词，而是以下几样东西：

• 明确的任务输入。代理需要知道改什么、不能改什么、怎样算完成。
• 受限的访问边界。代理应该只能操作它被允许操作的仓库、分支、环境和密钥。
• 可复用的项目模板。代理生成的新模块应该符合团队已经定下的目录、依赖和命名规范。
• 自动化的验证环境。代理提交的代码不能靠人肉检查，必须有 lint、测试、构建、扫描等流水线兜底。
• 可观测的记录。谁在什么时候让代理做了什么，消耗了多少成本，结果是什么，都必须有日志。

软件工厂本质上就是这五类能力的组合。它不是某个具体工具，而是一套围绕代理运行的工程系统。你可以用 GitHub Actions 加脚本搭一个很轻量的版本，也可以用任务队列、独立执行机和资产管理平台搭一个生产级版本。关键不在于工具多豪华，而在于每一步都有边界、校验和记录。

1.3 最小软件工厂的五层结构

在动手搭建之前，建议把系统拆成五个层次。后续的每一步实现，都能对到某一层。

这五层不需要一次全部做完。对于刚起步的团队，可以先做代码层和流水线层，再补接入层和观测层。重点是不要跳过流水线层，那是把代理产出从“个人实验”变成“团队资产”的分水岭。

2. 先统一仓库、访问权限和项目初始化规则

2.1 用分支保护把代理限制在专用轨道里

代理最危险的操作之一，就是直接向主分支写入代码。一个代理在局部改动里顺手格式化了整个文件、删掉了看起来没用的方法，这些差异如果直接进主分支，人工审查成本会非常高。

推荐做法是：每个代理任务永远只在一个独立分支上工作，主分支禁止直推，所有变更必须通过 Pull Request 合入。在 GitHub 上，分支保护规则可以明确禁止直接推送。

# 分支保护规则示意，代码托管平台不同则位置不同 - 分支名: main 保护规则: require_pull_request_reviews: true required_approving_review_count: 1 dismiss_stale_reviews: true enforce_admins: true require_status_checks: true

这些规则的含义是：任何进入 main 的代码都必须经过 PR，至少一个人类审查者批准，过期的审查需要重新触发，管理员也一样受限，并且必须通过状态检查。

注意：分支保护不是限制开发效率，而是给代理错误设置止损点。代理可以随便在功能分支上折腾，但合入主分支的必须是经过验证和审查的结果。

2.2 给代理的最小权限而不是最大权限

代理运行所需要的权限，往往比一个人类开发者要小。因为它不需要长期维护本地环境，不需要访问所有仓库，也不需要全局密钥。

如果通过 GitHub 的个人访问令牌（Personal Access Token）或者细粒度访问令牌接入，建议遵循最小权限原则。下面是一个常见的最小权限示例。

如果使用云开发环境，还要把网络访问边界、依赖源、数据库地址都限制在测试环境。代理不需要访问生产库，就不会出现“改错库”的问题。

2.3 用统一项目模板减少代理的“自由发挥”

代理在不熟悉的仓库里生成新模块时，最常见的差异是：有人用src/布局，有人用app/布局，有人包名带backend，有人带service。这些差异本身不致命，但会让审查者很难快速判断代码是否符合规范。

可以用项目模板把约定固化下来。例如使用 Cookiecutter 或 Copier 创建项目骨架：

{ "project_name": "order-service", "module_name": "order_service", "python_version": "3.11", "package_manager": "poetry", "include_ci": "yes", "include_tests": "yes" }

生成命令示意如下。

cookiecutter https://your-git.example.com/templates/service-template.git

执行后，模板会生成统一目录结构、配置文件和依赖清单。代理后续只需要在已有骨架上做增量开发，而不是每次重新发明项目结构。

统一模板带来的价值不只是规范，更关键的是“可预期”。代理拿到模板后，知道代码应该放在哪里、配置写在哪个文件、测试用什么框架启动。这样它的决策空间变小了，错误的可能性也随之变小。

2.4 需求规格模板：给代理一套可执行的任务输入

代理理解任务的能力，取决于任务文本是否清晰。直接把一句话“给我加一个订单导出功能”扔给代理，得到的结果往往无法直接使用。更好的方式是建立一个需求规格模板，让每个任务都被描述成机器可读的结构。

下面是一种简单的任务描述格式，建议每个代理任务都按这个结构提交。

task: id: ORD-3321 title: 订单导出功能 goal: 支持管理员按日期范围导出订单列表为 CSV scope: - 新增导出接口 /api/admin/orders/export - 新增后台导出按钮和下载入口 non_goals: - 不做异步任务队列 - 不做权限细分 constraints: - 只能在 order-service/src/ 下修改 - 禁止修改数据库表结构 - 必须兼容现有鉴权中间件 acceptance_criteria: - 导出文件包含订单号、金额、状态、创建时间 - 超过 1 万行时返回 413 - 新增测试文件 tests/test_export.py related_files: - order-service/src/controllers/order_controller.py - order-service/tests/ verify: - poetry run pytest order-service/tests/test_export.py

这段内容的价值在于：目标、范围、约束、验收标准、相关文件和验证命令都是显式的。代理不需要猜测“这算不算完成”，流水线也不需要用模糊的标准判断。

3. 设计一条可复现的 AI 代理流水线

3.1 任务启动与上下文注入

代理能不能高质量完成任务，很大程度取决于它拿到的上下文。如果只把需求文本丢给代理，它可能去读整个仓库，消耗大量 token，最后还是找错位置。

在任务启动阶段，建议把下面这些信息打包进代理的提示词或工具上下文：

• 仓库根路径和语言栈。
• 任务要求的变更范围。
• 相关文件的相对路径。
• 禁止修改的文件列表。
• 可用的验证命令。
• 提交信息的格式要求。

上下文注入可以使用流水线脚本自动完成。也就是说，当一个人创建了符合格式的 Issue 或 YAML 任务后，编排脚本自动把这些信息转换成一段结构化的执行指令。

这一步和传统的提示词工程不同。这里不是让 AI 编写更好的提示词，而是让流水线把组织层面的信息精确地送到代理面前，防止代理把时间花在无意义的探索上。

3.2 代理工作流：规划、实现、自测、提交

一个稳定的代理任务执行循环可以抽象为四个阶段：

1. 规划。代理读取任务规格和相关文件，输出执行计划，包括要改哪些文件、涉及哪些接口、是否影响现有测试。
2. 实现。代理在专用分支上产生代码变更。
3. 自测。代理运行定义好的验证命令，例如 lint、单元测试、构建。
4. 提交。测试通过后，代理创建提交、推送到远程分支，并创建 Pull Request。

如果实现阶段失败，代理可以进入“修复循环”，即读取错误日志、修改代码、重新运行测试。这里的最大风险是代理在错误方向上反复修复，因此建议设定重试上限。例如最多重试 5 次，超过后转人工处理。

这是一个用简单脚本表达的循环伪代码。

for attempt in range(max_attempts): plan = agent.plan(task, repo_context) changes = agent.implement(plan) results = agent.run(verify_commands) if results.all_passed: agent.commit_and_push(branch) agent.create_pull_request(task, plan, changes) break else: agent.fix(results.errors)

这里有个容易忽略的点：agent.run(verify_commands)必须在隔离环境里执行。最好每一次任务都从干净的工作区开始，避免本机缓存、环境变量和未提交变更对结果造成干扰。

3.3 创建 PR 后自动执行的校验

代理提交 PR 只是开始，真正的质量保证在 PR 之后的流水线里。CI 流水线至少应该包含以下步骤。

# 示意的工作流配置，可按实际平台调整 name: ai-agent-pipeline on: pull_request: types: [opened, synchronize, reopened] jobs: validate: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Set up environment run: make install - name: Static check run: make lint - name: Unit tests run: make test - name: Build run: make build - name: Security scan run: make security-scan

这四条检查规则各有作用：

• make lint检查代码风格和明显错误。
• make test跑单元测试，验证业务逻辑。
• make build验证整个项目可以构建成功。
• make security-scan扫描依赖漏洞和敏感信息。

需要强调的是，安全扫描不应该只扫描最终构建产物，还应该在 diff 阶段扫描是否有密钥、内网地址、数据库连接串被提交进去。这类敏感信息一旦进入主分支，清理成本会非常高。

3.4 用质量门禁拦截不合格变更

质量门禁是一组由系统强制执行的判定条件。只有通过全部门禁的 PR 才能被人工合并。下面是一个质量门禁配置示例。

quality_gates: - name: build command: make build required: true - name: unit_tests command: make test min_pass_rate: 100 - name: lint command: make lint required: true - name: security_scan command: make security-scan required: true - name: diff_size max_files_changed: 30 max_lines_added: 2000

每个门禁都有失败时的处理方式：

• 如果build失败，说明代理改动破坏了项目编译，只有代理修复或人工接手后才能继续。
• 如果unit_tests覆盖率或通过率不足，需要重新运行测试。
• 如果diff_size超过阈值，说明任务过宽或代理跑偏，需要人工检查代理是否修改了任务范围外的文件。

质量门禁的意义不是替代代码审查，而是把低层次的问题挡在人工审查之前。人工审查者只需要看业务逻辑、设计合理性和边界情况，不用浪费时间看格式问题。

4. 最小实现：在流水线里跑通一个代理任务

4.1 需要准备的环境

最小实现不需要复杂平台，可以用一台带有 Git 和编程语言运行时的机器完成。常见的依赖如下。

下面示例中的agent-cli是一个占位命令，实际使用时要替换成你选定的代理工具调用方式。不同工具的调用参数、输出格式和权限配置差异较大，落地前要先确认当前版本支持什么形式。

4.2 项目目录结构

建议按下面的目录组织软件工厂示例。

ai-software-factory/ ├── tasks/ │ └── ORD-3321.yaml ├── scripts/ │ ├── run_agent.sh │ ├── create_branch.sh │ └── verify.sh ├── templates/ │ └── task_template.yaml ├── .aiignore └── Makefile

• tasks/存放任务规格文件。
• scripts/存放编排脚本和辅助脚本。
• templates/存放任务模板。
• .aiignore告诉代理哪些文件不能读取或修改。
• Makefile统一暴露常用命令。

4.3 编写一个代理任务

在tasks/ORD-3321.yaml中写清楚目标和验收标准，这一步必须由人或上层系统完成。

task: id: ORD-3321 title: 增加订单导出接口 goal: 提供按日期范围导出订单的 JSON / CSV 接口 scope: - 修改 src/order/controllers.py - 新增 src/order/exporters.py non_goals: - 不修改数据库结构 - 不做异步导出 acceptance_criteria: - 接口返回 200 时 body 是 CSV - 参数缺少 start_date 时返回 400 - 所有新增函数都有单元测试 verify: - pytest tests/ -x -q

这个任务文件是整个流程的源头。代理的一切行为都应该以这个文件为基准，而不是猜测需求。

4.4 写一个最小编排脚本

下面用一个 Bash 脚本演示整体流程：创建分支、读取任务、调用代理、验证、提交。

#!/usr/bin/env bash set -euo pipefail TASK_FILE="$1" TASK_ID=$(basename "$TASK_FILE" .yaml) BRANCH="ai-agent/${TASK_ID}" git checkout -b "$BRANCH" agent-cli run \ --task "$TASK_FILE" \ --branch "$BRANCH" \ --repo-path . \ --retry 3 # 代理完成后统一验证 bash scripts/verify.sh git add . git commit -m "AI agent: ${TASK_ID} $(date +%Y-%m-%d)" git push origin "$BRANCH"

这个脚本虽然简单，但已经包含了软件工厂最核心的四个动作：

• 给代理隔离出一个分支。
• 从任务文件注入目标。
• 强制跑验证。
• 把结果提交到共享仓库。

verify.sh里则集中了所有检查命令。

#!/usr/bin/env bash set -euo pipefail make lint make test make build

在真实项目中，这一步还需要处理“验证失败时如何反馈给代理”。常见做法是让代理读取失败日志，修复后继续，直到重试次数耗尽。

4.5 运行过程和预期结果

运行任务时，输出大致会经历以下阶段。

[1/5] Creating branch ai-agent/ORD-3321 [2/5] Preparing task context from tasks/ORD-3321.yaml [3/5] Running agent with max_retries=3 [4/5] Verifying changes - lint: passed - test: passed - build: passed [5/5] Pushing branch and opening pull request

这说明代理完整地走完了一个最小闭环。之后需要到代码托管平台查看 PR 中的 diff，人工审查实际改动是否和任务目标一致。

注意：不要只验证脚本执行成功，还要同时验证代理是否改动了非目标文件、是否留下了临时文件、是否引入了未解释的依赖。这些都是代理跑偏的高频现象。

5. 参数与策略：决定代理输出质量的核心配置

5.1 模型选择和工作模式

不同代理工具的底层模型能力、可调用工具范围和权限模型都不一样。团队选型时，要关注几点：

• 是否支持多文件编辑。
• 是否支持读取仓库结构和相关文件检索。
• 是否能运行命令并读取输出。
• 是否能与代码托管平台的 PR 流程对接。
• 是否有清晰的审计日志。

建议新团队从多文件编辑模式开始，等任务模板、质量门禁和日志体系稳定后，再切到自主代理。

5.2 上下文策略：给代理精读路径而不是全文

代理能力再强，也会受到上下文窗口限制。无限度地把整个仓库塞给代理，反而会让它迷失在无关代码里。

推荐三层上下文策略：

1. 项目骨架。仓库目录结构、主要配置文件。
2. 任务相关文件。根据任务描述自动匹配的文件列表。
3. 动态检索。当代理需要了解某个函数定义时，再通过检索工具读取具体代码段。

.aiignore文件用于明确禁止代理读取或修改的内容。

# .aiignore 示例 node_modules/ dist/ build/ .vscode/ *.log .env

这样做既能减少 token 消耗，也能降低代理误改关键文件的概率。

5.3 生成参数：不是越大越好

调用大模型时有几个参数经常被忽略。

对于代码修改任务，建议把 temperature 设低一些，减少随机改写。不要使用太高的温度，否则代理可能反复重构代码，制造大量不必要的 diff。

5.4 并行度和成本控制

当多个代理同时工作时，可能出现两个问题：文件冲突和成本失控。

文件冲突一般通过分支隔离解决。每个任务一个分支，合入顺序由 PR 合并流程控制。合并时如果有冲突，交给 CI 检查或在人工审查阶段解决。

成本控制则需要设置预算和告警。代理调用的 token 消耗可以按任务记录，超过预设阈值时直接暂停任务。

并行不是越多越好。代理不擅长协调共享文件，并行数量过高会导致合并成本远高于收益。

6. 验证与观测：如何判断代理产出合格

6.1 自动检查：让机器先过滤一遍

代理提交的代码必须经过机器检查，这是软件工厂的基本底线。自动检查分为四层。

• 静态检查：代码格式、未使用变量、明显的风格问题。
• 单元测试：验证函数和类的行为符合预期。
• 构建检查：验证依赖完整、项目可编译。
• 安全扫描：检查密钥泄露、依赖漏洞、危险函数调用。

下面是常见的命令集合。

make lint make test make build make security-scan

这四层不通过，PR 就不应该进入人工审查。人工审查要解决的问题不是“是否缩进一致”，而是“这样设计是否合理”。

6.2 人工审查：关注语义而不是格式

流水线能验证代码能跑，但不能验证方向对不对。人工审查至少要关注三点。

• 是否解决了任务描述中的问题，还是只解决了表面现象。
• 是否引入了超出任务范围的改动。
• 是否考虑到边界条件，例如空列表、超大数据量、异常输入。

人工审查不应该重复流水线已经做过的工作。差别在于：机器检查的是“代码对不对”，人检查的是“代码是否该这么写”。

6.3 日志、审计和成本追踪

面向代理的软件工厂，需要记录的不只是代码变更，还有代理的完整行为链路。

一条典型的审计日志应该包括以下字段。

task_id agent_version model branch action file_path operation status token_cost timestamp

实际记录格式可以是 JSON：

{ "task_id": "ORD-3321", "agent_version": "cli-1.2.3", "model": "default-model", "branch": "ai-agent/ORD-3321", "action": "edit_file", "file_path": "src/order/controllers.py", "operation": "insert", "status": "success", "token_cost": 15230, "timestamp": "2025-01-01T10:00:00Z" }

有了日志之后，团队可以回答几类关键问题：某个任务花了多少钱，代理改了哪些文件，失败发生在哪一步，某个模型是否经常需要人工返工。没有这些数据，软件工厂就是黑盒。

6.4 一套可落地的验证矩阵

在项目上线前，可以把验证维度做成矩阵，保证每个任务都按同一套标准执行。

这张表格可以直接作为内部文档发布。团队每次让代理处理任务前，先按表格确认检查和验证环节都已配置到位。

7. 常见问题和排查路径

7.1 现象、原因、检查和处理对照表

代理流水线在真实环境中会遇到不少问题。下面整理了一份高频问题对照表。

这六类问题是新搭建软件工厂时最容易遇到的，强烈建议在流水线文档中保留这张表。

7.2 从现象倒推的排查顺序

遇到代理产出异常时，不要直接改代码，先按下面的顺序定位问题。

1. 先检查任务输入。任务描述里的目标、范围、约束是否足够明确。
2. 再检查分支和权限。代理是否真的操作了它应该操作的分支，Token 权限范围是否正确。
3. 检查代理日志。它读了哪些文件、改了哪些文件、执行了什么命令。
4. 检查验证环境。代理执行验证命令时是否使用了正确的依赖和配置。
5. 检查 CI 日志。是流水线脚本错误，还是代码本身不满足检查条件。
6. 最后检查人工审查环节。是否存在把格式问题当逻辑问题处理的情况。

这个顺序的价值在于，先排除流程问题，再进入代码问题，避免一开始就被代理解释带偏。

7.3 三个高频坑：看起来能跑，实际很危险

第一个坑是让代理直接访问真实环境。很多团队为了省事，让代理在本机执行命令，结果代理修改了本机的环境变量、依赖缓存或其他项目文件。推荐做法是让代理在容器或 CI 运行器上工作，任务结束后销毁环境。

第二个坑是只检查“编译通过”就合并。代理代码如果只通过编译，往往缺失大量边界处理。合并前必须跑单元测试和代码审查，编译通过不等于逻辑正确。

第三个坑是过度授权。有些团队直接把拥有组织管理员权限的 Token 配置给代理，一旦代理输出被恶意提示词诱导，影响范围会迅速扩大。推荐做法是每个任务使用独立身份或 Token，并且仅授权单仓库、单分支、限时访问。

第四个坑是忽略审计日志。代理跑完任务后，如果没有任何日志，后续问题无法回溯。推荐做法是至少保留任务 ID、模型名称、文件改动列表、测试结果、token 成本和操作时间。

8. 从最小原型到生产软件工厂：清单和扩展

8.1 学习环境如何快速搭起来

对于刚接触“面向 AI 编程代理的软件工厂”的团队，不推荐一开始就搭完整平台。建议先在一台开发机上实现最小闭环。

建议按下面的顺序操作：

• 创建一个示例仓库，包含一个可运行项目和基础测试。
• 建立任务模板，把目标、范围、验收标准固定下来。
• 写一个编排脚本，让代理自动创建分支、调用工具、运行测试、创建 PR。
• 在代码托管平台配置分支保护，要求 PR 必须通过检查。
• 跑一个最简单的任务，确认从 Issue 到 PR 的链路是通的。

这套流程不需要引入复杂系统，只需要一个 Git 仓库、一个代理 CLI、一套脚本和一台能运行测试的机器。对于验证软件工厂思路，这已经完全足够。

8.2 生产环境落地检查清单

从学习环境走向生产环境时，建议逐项确认下面的清单。

这些检查项不只是技术问题，同时也是管理规范。生产环境里，代理的自主能力越强，这些约束就越重要。

8.3 后续扩展方向

最小软件工厂跑通后，可以考虑按下面的方向逐步扩展。

• 多仓库支持。让同一个代理工厂可以管理多个服务仓库，任务队列按仓库路由。
• 异步任务队列。把代理任务放入消息队列，实现并发调度和失败重试。
• 代理评估体系。定期用一批固定任务测试不同模型和策略的产出质量，形成可量化的回归指标。
• 自动评审辅助。把静态扫描结果、测试覆盖率和变更影响面汇总到 PR 评论，减少人工审查的重复劳动。
• 领域知识注入。把团队内部规范、架构文档、历史决策记录作为检索知识库，让代理在动手前先理解组织约定。

每一步扩展都应该回到软件工厂的本质目标：让代理的输出变得更加可预期、可验证、可维护。技术栈可以换，模型可以升级，但这条主线不能丢。对新手团队来说，最有价值的练习不是研究更多提示词，而是先把一个任务从需求到合并的完整链路固定下来，然后不断观察和优化这条链路。