大概三周前我们团队还在用最原始的方式折腾Claude Code谁需要谁复制一套系统提示词主仓库里躺着三四屏互相矛盾的旧约定提交记录东一条西一条代码风格连机器人自己都认不出来。后来我把整个开发方式推倒重来用类似“工程化”的思路给AI Agent做了套地面规则也就是题目里说的CC开发框架。这系列文章我会按阶段拆着写这篇是第一篇核心只有一件事把Claude Code从个人手里的全能助手变成团队内部一个可以分工、可约束、可交接的协作单元。这套玩法不是某个实验室里的炫技成果就是给正经业务线上用的。我们现在三个业务模块的迭代已经跑在这套框架上高峰期一天会有几十个任务被多个Agent并发处理。如果你也遇到过“Prompt越写越长但效果越来越飘”“多个Agent互相覆盖文件”“评审卡在某个Agent手里半天没人管”这类问题这篇应该能给你一些能直接抄回去的思路。1. 为什么需要团队级CC开发框架1.1 个人脚本逻辑的尽头单独一个人用Claude Code写点脚本或原型其实不需要什么框架。你开个会话让它写个函数、改个bug、补个测试它做得又快又好。问题出在“人变多、项目变复杂”的那一刻。我们前期阶段团队里五六个人同时在同一个仓库里接任务每个人都按自己的习惯给Claude Code下达指令有人要求它直接改动文件有人只让它输出diff有人把整个项目背景塞进上下文有人连需求文档都不舍得贴。结果就是三个非常典型的症状。第一某A和某B让Agent做的改动互相冲突最后合代码的时候仓库一团乱。第二同一个功能被不同人重复生成浪费了大量时间和令牌。第三Agent的行为完全不可预期因为每个会话的上下文、指令风格、规则优先级完全不同。你说这是Claude Code的问题吗其实不是工具没有变变的是使用方式。个人玩法里所有的“隐性默契”都不存在必须把团队约定变成显式的、可读取的规则。这段经历让我意识到所谓团队级AI Agent开发真正要管的不是某个Agent聪明不聪明而是它在一堆人、一堆任务之间怎么被编排、被约束、被复用。这跟一个人写代码要上版本管理、要做code review是一样的逻辑只不过管理对象从“程序员”换成了“AI Agent”。1.2 团队化要解决的四件事我给自己列了四个必须解决的问题不解决就谈不上团队级。第一是上下文隔离。每个Agent任务需要的背景应该尽量少而精准而不是把整个仓库和所有历史对话都塞给它。上下文一旦膨胀不光是花钱多关键是它会把注意力放到无关紧要的角落生成质量肉眼可见地下降。第二是角色边界。不能让一个Agent既负责规划又负责写代码又负责评审。表面上看全能是好事实际上会让任务粒度失控出了问题也不知道该找谁。角色模糊导致的另一个问题是上下文互相污染同一个会话里干了好几件事日志一塌糊涂。第三是任务交接。Agent和Agent之间必须有一张明确的任务卡说清楚谁做的、要做什么、做到什么程度算完成、下一步交给谁。没有这个所有协作都会退化成“人肉搬砖”。第四是可回溯。每一轮改动要能对应到具体任务、具体Agent、具体规则版本。否则一旦线上出问题你根本不知道是哪个环节的锅。这四个问题本质上是把传统研发管理里的分工、SOP、版本控制思路迁移到AI Agent上。Claude Code本身给了很强的代码理解和生成能力但能力越强越需要护栏。CC开发框架说白了就是给能力加护栏的那套东西。2. 框架的骨架目录、配置与上下文边界2.1 一个干净的仓库结构设计框架的第一步不是写配置而是先把整个仓库结构搭出来目的只有一个让每个Agent都清楚自己该在哪干活、去哪找材料、产出放哪里。我们用的结构如下team-cc-framework/ ├── config/ │ ├── base.toml # 全局基础配置 │ ├── agents/ # 每个Agent的角色定义 │ ├── workflows/ # 任务流转状态机定义 │ └── rulesets/ # 共享的编码规范与业务规则 ├── agents/ │ ├── planner.agent.toml │ ├── coder.agent.toml │ └── reviewer.agent.toml ├── workflows/ │ ├── requirement-to-merge.yaml │ ├── bugfix.yaml │ └── release.yaml ├── shared/ │ ├── api-contracts/ # 接口契约 │ ├── prompts/ # 跨角色复用的提示语片段 │ └── task-templates/ # 任务卡模板 └── logs/ └── run-history.jsonl # 每次任务运行的审计日志仓库结构本身没有太神秘的东西但它传递了一个信息Agent不是散养的它有固定的归属地和工具位置。以前我们总在对话里反复交代“你去看一下某某目录下的文档”现在Agent启动时直接按配置指向对应目录省掉了大量重复描述。我特别想强调一下 logs 目录。这个目录一开始很多人觉得没用后来发现它是排查问题的救命稻草。每个任务跑完把任务ID、Agent角色、读取了哪些文件、改动了哪些文件、评审结论是什么全部以JSON行格式追加进去。出问题的时候看一眼历史就知道是哪次改动引入的不用靠记忆和猜。2.2 用配置文件给Agent“上户口”有了目录骨架第二步是把每个Agent的身份和行为边界写进配置文件。我们把这种操作叫“上户口”意思是每个Agent必须有一个明确的档案记录它的职责、能力、权限和交接对象。下面是我们 planner 角色的配置删减了敏感信息但结构基本完整name: planner description: 负责需求分析与任务拆解不直接改代码 context_limit: 8000 model: default permissions: read_repo: true write_files: false run_commands: false capabilities: - repo_scan - requirement_parse - task_decomposition - api_query handoff: default_next: coder on_risk: human_review这里每个字段都有实际含义。context_limit 控制给这个Agent的上下文输入上限我们设成8000足够它读完一张任务卡和几个关键文件又不会让它陷入整个仓库的噪声里。permissions 里的 write_files 明确设为 false目的就是阻止规划类Agent越过边界直接改代码规则一定要写在配置文件里不能指望靠对话“叮嘱”它。这类配置化的好处是可以纳入版本管理。谁改了planner角色定义改动记录在git历史里一清二楚。我们后期调整过好几轮角色边界比如给coder开放了“新增测试文件”的权限就是因为线上反馈很多代码改完缺测试所以把写测试从reviewer的提示语转移到了coder的权限里。这个调整只改了一行配置但效果比让所有人在对话里喊十遍“记得补测试”都管用。2.3 上下文边界怎么定上下文管理大概是整个框架里最容易被忽视、影响却最大的设计。很多人以为给Agent越多上下文它就越聪明实际上我用下来的体感完全相反一旦上下文超过某个阈值它反而会在无关信息上浪费注意力甚至开始编造不存在的依赖关系。我的经验是提前给每个Agent画一个“信息圈”。planner只需要需求文档、任务模板、历史任务摘要coder只需要任务卡、相关模块代码、接口契约reviewer只需要变更diff、规则集、测试报告。除此之外的信息一律不默认加载。这听起来可能有点反直觉但你可以想一下人类团队后端开发者的日常并不需要不停阅读市场部PPTAgent也一样术业有专攻。我一般把context_limit分档设置。纯分类或抽取类任务给4000到6000让Agent做一些轻量分析代码生成和修改给8000到12000保证它能读完核心文件涉及多模块联动的大任务不超过20000再多我就强制拆任务。这套分档来自于我们自己的压测记录不同档位下生成代码的编译通过率差异很明显后面会专门用一节讲参数实测。3. 角色体系与任务编排3.1 三个核心角色框架第一版只设了三个角色planner、coder、reviewer。三个角色对应人类团队里的三种职能目的是让流程清晰、权责明确。planner的职责是对需求进行解析拆成可执行的任务卡识别风险然后把任务交给coder。它不写实现代码它的产出是一张结构和验收标准都清晰的任务卡。因为它的产出不是代码所以即使它犯糊涂也不会污染代码库最多就是任务卡写得不合理review阶段一眼就能看出来。coder是实际动手的角色负责根据任务卡实现功能、修bug、补测试。它的核心要求是“言行一致”说改哪几个文件就改哪几个文件不得顺手改动无关代码。我们在coder配置里加了一条强制规则凡是没有在任务卡里列出的文件一律不允许改动。这条规则看着简单但解决了一大半的“Agent乱改代码”问题。reviewer做的是守门工作。它拿到coder的diff之后先对照规则集做静态检查再跑测试最后检查任务验收标准是否满足。reviewer拥有三个角色里唯一的“拒绝”权限它可以带着拒绝理由把任务打回给coder。这相当于把code review从人的身上解放了一部分让高频的小改动也可以有自动化的质量闸门。你可能会问这么机械的三角色分工和Claude Code本身的Agent能力相比是不是退化了我的回答是这恰恰是团队化最稳妥的起步方式。全能型Agent在单独任务里很好用但在多人协作场景里全能等于不可控。先把角色收敛到三个让每个人都清楚自己该做什么后面再按需增加角色比如测试Agent、文档Agent就会非常顺。3.2 任务卡片与状态机角色定义好了接下来是它们之间怎么配合。我们不靠在对话里来回喊话而是靠一张统一格式的“任务卡”。任务卡是流程里所有Agent交换信息的载体相当于人类团队的工单。卡片的模板大致如下task_id: T-1024 title: 接入订单查询接口到订单详情页 owner_agent: coder dependency: T-1001 goal: 订单详情页调用订单查询接口并展示最新状态 acceptance_criteria: - 接口返回200且字段映射正确 - 异常时展示统一错误提示 - 新增接口契约测试 timebox: 30min context_files: - src/pages/orderDetail.js - src/api/order.js handoff: next: reviewer字段不需要多但每一个都要有意义。dependency字段是很多团队会漏掉的它表达的是“这个任务依赖哪个前置任务的产出”。如果缺了这个两个Agent很容易重复实现同一个依赖或者在一个还没完成的功能上继续叠加改动那后面的错误会非常难排查。状态机方面我们设计得很轻任务只允许在 init → planned → in_progress → review → merged → closed 这几个状态里流转另外还有一个 rejected 状态表示被打回。每个状态变更都会记录到logs目录里作为审计追踪。这套状态机是整个CC开发框架执行层的核心骨架所有工作流都围着它转。有人会觉得状态机是不是太重了我自己也一度犹豫过。但后来实际跑下来发现状态机不是给Agent看的是给人做监控和管理用的。有了状态才能知道当前哪些任务在排队、哪些在评审、哪些卡住了。没有这个团队就像黑灯舞厅大家都很忙但不知道谁跟谁在跳舞。4. 实战从需求到合入的一个完整闭环4.1 需求拆成任务卡纸上谈兵没什么意思我用一个我们实际走过的需求来串一遍流程。假设产品提了一个需求给订单详情页增加服务状态展示。这个需求本身非常简单但在没有框架的时候它也照样闹出过毛病——有人会让Agent把整个详情页重写了有人会让Agent去改接口返回结构最后接口文档和数据展示互相打架。有了框架之后planner会先做几件事。第一扫描仓库结构定位订单详情页相关文件。第二读取接口契约看看现有的查询接口有哪些字段。第三检查历史任务确认有没有人已经做过类似改动。做完这些它生成上面那张任务卡把owner设置为coder依赖关联到已有的接口改造任务。这里有一个关键设计planner不会把原始需求原文直接传给coder而是只传递解析后的任务卡。为什么要这样因为产品经理的需求描述往往含混有很多背景和潜台词传给coder的信息越原始Agent越容易糊涂。planner的作用就类似于翻译架构师把模糊的自然语言需求变成结构化、可验收的工程任务。4.2 执行与评审的衔接coder拿到任务卡后先读取卡片里列出的context_files再读取共享规则集里的编码规范然后在local分支上开始工作。执行过程里它随时对照acceptance_criteria每完成一个验收点就自己先过一遍。如果遇到任务卡信息不足的情况它不会自己乱猜而是把任务状态调整为 in_progress 但标记为 blocked并回传给planner补充信息。这一点是我们在规则集里明确规定的防止Agent强行脑补需求。写完代码后coder生成一份变更摘要内容包括改动文件清单、关键逻辑说明、自测结果。然后把手牌交给reviewer。reviewer拿到diff后并不是简单看代码美不美观它要做的是三件事对照规则集检查代码风格和边界跑一次相关测试核对diff里的改动是否全部落在任务卡允许的文件范围内。如果reviewer发现问题它会进入 rejected 状态并附上具体的拒绝原因和修改建议打回给coder。coder根据建议修改后再提起来。这个循环在配置里设了一个最大轮数我们设的是2轮。超过2轮还没通过任务自动升级到人工处理避免两个Agent原地死循环烧钱又耗时间。4.3 回滚机制评审通过后任务并不会立刻自动合并到主干。我们设计了半自动合入reviewer通过后生成合并请求真正的merge由人或者CI脚本触发。这个“人为扳机”非常值得保留因为它保留了最后一道安全阀同时也符合大多数研发团队的流程习惯。如果合并后发现线上问题框架里还有一记绝招叫“任务级回滚”。因为每个任务卡都会记录改动文件的清单回滚时不需要把整个分支推回去只需要调用该任务对应的反向变更就能精准撤销这次任务带来的代码改动。这个能力在传统Git操作里要做不少手动工作但我们因为每次改动都有明确的任务边界回滚成本变得极低。这个完整闭环走下来我要强调一句流程存在的意义不是增加阻力而是为了减少不确定性。没有流程的时候每一步都可能出问题有了流程之后每一步的结果都可预期人只需要在极少数的异常节点介入。5. 团队级落地常见坑与排查实录5.1 共享规范的版本化团队级框架跑了一段时间后最容易出现的问题不是技术而是“规范腐化”。今天有人给规则集加了一条风格约定明天有人觉得没用又删了后天又有新成员不知道加过这回事。到最后规则集变得比老太太的裹脚布还长但真正执行的没有几条。我的解法很简单把共享规则集纳入版本管理并且把版本号写进任务卡。每个Agent执行任务时必须读取指定版本的规则集不允许“读最新版”。这样每次改动的依据都可追溯。规则集的修改要走一个小评审流程不能哪个人自己顺手加一条就提交。我见过最离谱的事情是好几个角色Agent同时读取一个正在被修改的规则文件结果有人读到一半的内容生成结果时好时坏。后来统一改成“读取快照”也就是把规则集按版本固化成只读文件Agent只读取固化后的版本这场混乱才算结束。5.2 高频问题的排查速查表这几个月跑下来遇到的问题五花八门但高频问题基本可以归纳成下面这张表。我建议新团队直接把这表打印出来贴墙上省得踩同样的坑。现象根因解决办法上下文爆掉生成质量下降角色权限太宽加载了多余文件收紧capabilities按信息圈加载多个Agent重复实现同一功能任务卡缺少dependency字段planner先扫描历史任务和已有实现代码风格一会儿一套规则集版本不固定任务卡绑定ruleset版本Agent读快照评审任务没人接任务卡没有指定next reviewer在handoff里设置默认reviewerAgent反复修改但总不过审验收标准模糊或轮数上限缺失精化acceptance_criteria设最大轮数Agent改了任务卡范围外的文件权限配置过宽或规则没写死在配置和规则集双层面禁止范围外改动输出日志找不到对应任务没记录task_id所有Agent日志必须带task_id这些问题的共性是它们都不是Claude Code本身的问题而是框架在设计时没有把约束和记录做足。工具用得越深框架的约束力越重要。每次排查问题的过程也是对框架本身做一次加固的过程。5.3 参数实测与调优心得最后说说参数这块最容易被当成玄学。我直接给结论基于我们自己的实验数据。context_limit是最敏感的参数。我们把同一份代码生成任务分别用4000、8000、12000、20000的上下文上限跑编译通过率分别是78%、91%、87%、69%。为什么12000反而比8000低因为任务本身只需要6000的上下文塞多了之后Agent会去“参考”那些跟任务无关的模块结果反而跑偏。所以不要盲目给大上下文给够就行。另一个参数是generation temperature。在我们的代码生成场景里temperature调低到0.2左右代码风格更稳定命名也更保守很适合团队协作里的“执行角色”。但planner做需求拆解时我们会调高到0.6让它有一定发散性。同一个模型配合不同的参数给不同角色效果差别非常明显。还有一个容易忽略的是最小输出长度或者叫“强制输出框架”。比如让reviewer必须按“结论证据建议”三段格式输出它就会更倾向于做出结构化判断而不是含糊地说“看起来可以”。这种输出约束可以在不调任何参数的情况下显著提升评审质量。6. 下一步扩展方向CC开发框架目前已经支撑了我们两条核心业务线的日常迭代但我也清楚它还有不少可以继续往下钻的地方。第一个方向是把更多角色加进来比如专门负责写测试的测试Agent、专门维护文档的文档Agent、专门做数据摸查和分析的数据Agent。角色越多框架的编排能力要求越高任务卡和状态机需要再细化。第二个方向是接入更完整的CI/CD管线。现在我们的人为合入扳机还比较粗后续可以让reviewer的通过结果直接对接CI产物实现自动构建、自动部署到预发环境人工只在最后确认发布。第三个方向是把这套配置经验沉淀成模板让新项目在初始化时直接生成一份基础框架而不是每次从零开始手工搭。我们已经试着做了个简单脚手架目前看起来效果不错后续如果稳定了可以单独写一篇分享。第四个方向是引入更多维度的指标比如任务平均流转时长、评审打回率、上下文成本这些指标可以用来反哺框架调优。没有指标的框架优化就是瞎猜有了指标每次改配置都能拿数据说话。这些方向我不会一下子全做AI Agent开发最怕的就是贪多嚼不烂。先把基础框架打牢再一个一个加厚才是团队这条路走得稳的关键。我个人比较深的体会是Claude Code这类工具的实力其实已经超出大多数团队的使用方式了瓶颈从来不在模型而在协作设计的粗糙程度。CC开发框架不是什么灵丹妙药它就是一套让人和多个Agent之间能有序配合的共识。只要这套共识还在持续迭代后面加多少角色、接多少系统我心里都不慌。
