AI代码开发协作治理实践

一、概述

当 AI coding agent 从“单次代码补全”变成“持续参与项目开发”后，真正的难点不再只是 Prompt 怎么写，而是协作和治理：

大任务如何拆分给多个 Agent。
如何避免不同 Agent 互相覆盖工作。
如何做 code review 和 handoff。
如何控制规则膨胀、上下文污染和安全风险。
如何用指标判断规则是否真的提升效率。

本文合并多 Agent 协作、代码评审和规则治理实践，适合作为团队落地 AI 代码开发规范的第二篇博客。

二、多 Agent 协作模型

多 Agent 协作把一个大任务拆给多个专门 Agent：调研 Agent 读代码，计划 Agent 写方案，实现 Agent 改文件，测试 Agent 跑验证，review Agent 找风险。相比单 Agent 长上下文工作，多 Agent 的优势是上下文隔离、并行探索和角色清晰；代价是协调成本和结果合并复杂度。

graph TD
    U["User / Maintainer"] --> C["Coordinator Agent"]
    C --> R["Research Agent"]
    C --> P["Planning Agent"]
    C --> I["Implementation Agent"]
    C --> T["Test Agent"]
    C --> V["Review Agent"]
    R --> C
    P --> C
    I --> C
    T --> C
    V --> C
    C --> U

角色	主要职责	输出
Coordinator	拆任务、控制范围、合并结论	总结、最终决策
Research Agent	只读调研代码和资料	文件地图、风险点
Planning Agent	写方案和任务清单	plan、task list
Implementation Agent	按任务改代码	patch、变更说明
Test Agent	执行验证、复现问题	命令输出、失败原因
Review Agent	查 bug、回归、安全、遗漏测试	findings、建议

三、何时使用多 Agent

适合	不适合
大型重构、跨模块功能、迁移项目	单文件小改
需要并行调研多个子系统	需求还不清晰且需要和用户频繁确认
需要独立 code review 或安全审查	修改风险极低
长文档或大代码库分析	结果必须实时共享同一上下文

任务拆分时，每个子任务必须明确目标、允许范围、禁止事项、输入、输出和验证方式。

示例：

你是 Review Agent。只做代码审查，不修改文件。
关注 bug、回归、安全、缺失测试。
输出按严重程度排序，必须带文件路径和行号。
如果没有发现问题，明确说明剩余风险。

四、并行与串行判断

flowchart TD
    A["Task"] --> B{"是否共享同一文件?"}
    B -->|是| C["串行执行"]
    B -->|否| D{"是否需要前置结论?"}
    D -->|是| C
    D -->|否| E["并行执行"]

可并行	应串行
文档调研、测试验证、不同模块只读分析	同一文件修改
前后端独立原型探索	数据库 schema 先于 API
多方案比较	需要统一设计决策

Coordinator 必须负责最终合并，不能让多个 Agent 同时编辑同一文件后直接交付。

五、Code Review Agent 规范

review Agent 不应复述改动内容，而应优先报告问题。

优先级	关注点
P0	数据丢失、安全漏洞、生产不可用
P1	主要流程回归、接口不兼容、测试失败
P2	边界条件、性能、并发、缺失验证
P3	可维护性、命名、局部风格

推荐输出：

Findings:
- [P1] 文件:行 - 问题描述，为什么会失败，建议修复方向。

Open questions:
- ...

Test gaps:
- ...

最终交付前，Coordinator 需要确认：

检查	说明
需求覆盖	对照 spec/issue 确认无遗漏
变更边界	是否只改了任务相关文件
测试验证	是否运行了必要命令，失败是否说明
Review 收口	P0/P1/P2 是否处理或明确接受
文档同步	API、README、迁移说明是否更新

六、Handoff 与上下文压缩

多 Agent 的关键是交接质量。每次 handoff 应包含：

当前目标。
已完成工作。
修改过的文件。
尚未验证的风险。
下一步明确动作。

避免把完整长日志直接交给下游 Agent。应提炼为“事实 + 证据路径 + 待办”。

七、规则治理对象

AI 代码开发规范不是写得越多越好。规则、Skills、Memories、Spec 工件都会进入 Agent 的决策链；如果它们过长、冲突、过期或不可验证，反而会降低 Agent 的执行质量。

对象	示例	风险
仓库指令	`AGENTS.md`、`CLAUDE.md`	过长、过期、冲突
IDE Rules	`.cursor/rules`、`.clinerules`	工具私有、重复加载
Memories	Cascade/Claude auto memory	记录错误事实、泄露敏感信息
Skills	`SKILL.md` + scripts	恶意脚本、误触发
Specs	`spec.md`、`plan.md`、`tasks.md`	需求漂移、任务未回写

八、常见反模式

反模式	表现	后果	治理方式
万能大规则	一个文件几千行	关键约束被稀释	主文件保留索引，细节拆分
口号式规则	“写优雅代码”	不可执行	改成命令、路径、检查项
互相冲突	A 要用 Jest，B 要用 Vitest	Agent 随机选择	明确优先级，删除旧规则
过期命令	测试命令已失效	验证失败或跳过测试	每次依赖升级后更新
规则复制	README、架构文档全量复制	上下文浪费	链接原文，只摘执行要点
自动记忆失控	记住临时 debug 结论	后续持续误导	定期审查和删除
Skill 误触发	任何任务都加载复杂流程	低效、打断简单任务	收窄 description

九、规则最小化原则

graph TD
    A["候选规则"] --> B{"是否跨任务反复出现?"}
    B -->|否| C["放在本次 Prompt"]
    B -->|是| D{"是否稳定长期有效?"}
    D -->|否| E["放在 spec / issue"]
    D -->|是| F{"是否可验证?"}
    F -->|否| G["改写为具体动作"]
    F -->|是| H["写入规则文件"]

一条规则进入仓库前，应能回答：

触发条件是什么？
Agent 应采取什么动作？
如何验证它遵守了？
如果与其他规则冲突，谁优先？

十、效果度量

指标	观察方式
首次通过率	Agent 修改后测试一次通过比例
Review 命中率	review 中重复指出同类问题的次数
规则遵守率	抽查 PR 是否按规则运行命令/更新文档
上下文成本	规则文件大小和加载数量
返工率	因误解需求或架构导致的重做次数
安全事件	secret 泄露、权限绕过、危险命令

不要只看“生成速度”。AI coding agent 的真正效率取决于通过 review 和测试的总周期。

十一、安全治理

AI 规则和 Skills 可能影响实际文件和命令执行，应设置安全边界：

风险	控制
secret 泄露	禁止读取/打印 `.env`、key、token；日志脱敏
供应链攻击	只安装可信 Skills/插件，审查脚本
危险命令	明确禁止 destructive command，要求确认
权限扩大	不让 Agent 自动修改 CI secret、IAM、生产配置
数据合规	禁止把客户数据上传到外部服务

十二、推荐治理结构

AGENTS.md
docs/agent/
  architecture.md
  testing.md
  security.md
  review-checklist.md
.cursor/rules/
  architecture.mdc
  testing.mdc
.github/instructions/
  review.instructions.md

AGENTS.md 只保留最常用规则和索引。长细节通过相对链接引用，具体工具规则只写触发条件和适配格式。

十三、审查清单

检查项	通过标准
文件大小	主规则文件短小，细节拆分
指令清晰	每条规则有动词和对象
冲突处理	同类规则只有一个权威来源
命令有效	install/test/lint 命令可运行
敏感信息	无 secret、账号、客户数据
可追溯	重要规则能链接到决策或事故来源

参考资料：

相关文档：

AI代码开发规范方法论

← 返回笔墨札记