Skip to content

Latest commit

 

History

History
147 lines (106 loc) · 13.9 KB

README.md

File metadata and controls

147 lines (106 loc) · 13.9 KB

cooperation-skill

多 agent 协作框架 —— 最强的模型只做设计、出卡和收官,实现交给执行细致的模型自主完成,你主要跟 Conductor(指挥)对话,由它向各角色派工、派卡记账、做逐卡门禁与初审,里程碑末再由另一个模型把整体实际跑起来验收;人类只裁决真正该由人定的事,最后拿到一份修完之后的交付报告。

这不是"让几个 AI 一起干活"的泛泛建议,而是一套从真实翻车里长出来的约束:每一条规则背后都有一次具体的代价。框架本身可以照抄,但真正值钱的是 anti-patterns.md 里那些"为什么必须这么规定"。

它解决什么问题

失败 这里的对策
最强的模型把上下文花在派卡、记账、复跑命令、催进度上 内容链路与控制链路分开:Conductor 派卡、对着封闭清单逐卡过门禁、记账,不碰卡面、不做裁决;Architect 只在里程碑两头和被唤起时出场
人要分别跟好几个 agent 说话,意图在转述中走样 Conductor 做 Owner 的主要对话入口:控制类的事直接办,内容类的事附 Owner 原话派给 Architect;汇报用大白话,但不丢"未实测""推断"这类限定词
中间的 Conductor 能力不差,却只能当跑脚本的机器;逐卡也没人读代码 Conductor 初审档:门禁结论照旧只认清单,另附不阻塞的初审意见(疑似缺陷、改进、存疑)和具体的肯定,实现方逐条选"现在改 / 挂账 / 不采纳";按采纳率校准
卡面写成实现说明书,实现方只能照抄出卡人的盲区 薄卡:目标、少量有区分力的完成判据、本卡特有约束、已知未知,一屏以内;判据由实现方读过代码后细化
每个决定都停工等裁决,而裁决结果和实现方的首选方案 5/5 一致 按回退成本分三区:绿区直接做,黄区提案并继续,只有会外溢或不可逆的才停
实现方发现了更好的契约,直接就改了 红区穷举且一律停;已被消费的契约、安全边界、既有测试不在放权范围内
review 停不下来,一张小卡审了 7 轮,体量做到预算 2.3 倍 一次给全 + 只退回有依据的 + 轮次封顶 + 越线信号;验收强度由"面对谁"决定,不由"多重要"决定
人类被一串单卡通知淹没,或者拿到一份还带着一堆该修没修的问题的交付 里程碑收官:Reviewer 把整体跑起来验收 → Architect 评估归类 → 有依据且修法清楚的自己迭代掉 → 只把产品方向、主观体验、已批准契约这类事留给 Owner,写成选择题
换了个弱一点的模型,整套放权规则就压不住了 执行者档位:正文按强模型写,弱模型叠加保守档附录,把黄区并回红区、卡面写全、逐卡审核
两个 agent 共享工作区,一次 git checkout 抹掉对方未提交的活 按 A/B/C 实际拓扑定纪律;A 切分支前确认现场,C 每个运行使用独立分支
Multica 拒绝记录交付分支,提示起始提交不再可达 每轮冻结 run_start,沿宿主分配追加提交;交付前检查身份与祖先关系

角色

Owner(人类)         产品方向、主观体验、已批准的契约、花钱的事
                     └─ 主要跟 Conductor 对话,零内容搬运;读里程碑交付报告并裁决其中留给 Owner 的事项

Architect            设计文档与 ADR、按里程碑批量出卡、裁决、退回定性、收官评估、签发交付报告
                     └─ 专属:契约制定权 · 裁决权 │ 按需唤起,不常驻每张卡

Implementer          细化完成判据、自主实现、交付;黄区提案并继续,红区停下
                     └─ 专属:红区以外的实现自主权

Conductor(指挥,可选)  Owner 的主要对话入口:听意图、向各角色派工、用大白话汇报;派卡、卡级门禁并合入集成分支、记账、汇编报告的事实部分
                     └─ 换说法不换实质;门禁只认封闭清单;无契约权、裁决权、主干合入权

Reviewer(可选)      里程碑末把整体实际跑起来验收;对抗档/取证档逐卡验收;合入主干
                     └─ 有验收权与主干合入权,无契约修改权
每张卡:  派卡 → 细化判据 → 实现 ⇄ 提案/裁决 → 交付 → 卡级门禁 → 合入集成分支
里程碑:  设计/ADR → 批量出卡 →〔逐卡循环〕→ 里程碑验收 → 收官评估 ⇄ 自迭代 → 合入主干 → Owner 报告

两个角色都可选:没有 Conductor 时派卡记账归 Architect、卡级门禁归 Reviewer;没有 Reviewer 时验收与主干合入归 Architect;只有两个 agent 就是双 agent 原形。

模型怎么配:设计能力最强的做 Architect;执行细致的做 Implementer;严谨且最好与 Implementer 异源的做 Reviewer;Conductor 是你主要对话的对象,要说话清楚、不丢限定词,至少要能可靠地跑命令、比对输出(基础档);能读懂代码、说得出具体理由的,开初审档,让它对每张交付提改进意见——它仍然不做内容决定。

核心机制

机制 一句话
两条链路 设计 → 卡面 → 实现 → 验收是内容链路,不放转述者;谁在做什么、下一步该谁动是控制链路,交给 Conductor
初审 Conductor 初审档的逐卡读码:每卡至多三条不阻塞的意见加具体肯定。放开"说",不放开"判"
三层检查 卡级门禁(每张卡,机械清单)→ 里程碑验收(整体实际运行)→ 收官评估(结构与归类)。常规卡的实测推迟到里程碑末,所以里程碑要切小;对抗档与取证档仍逐卡验收
薄卡 目标 + 完成判据骨架 + 本卡特有约束 + 已知未知。运行信息归派卡消息,常驻规则归协议,都不进卡面
三区 判据是回退成本:只动本卡代码 = 绿区直接做;封在本卡内 = 黄区提案并继续;会外溢或不可逆 = 红区停
L1 / L2 / L3 L1 分"停"和"提案"两种;L2 缺陷继续做、随交付提出;L3 改进在范围内直接采用
Owner 裁决规则 默认不留。只有产品方向、主观体验、已批准的契约、代价落在 Owner 身上的取舍、花钱/对外/不可逆、僵局这六类才留,且写成带推荐的选择题
里程碑收官 合并后的主干上统一评估;有依据且修法清楚的出补卡自迭代,最多两轮;再出交付报告
交付报告 做了什么、怎么实现、效果如何、自己修掉了什么、遗留缺陷、后续建议、需要你裁决。Architect 签发,Conductor 汇编事实
档位 Implementer:标准档给强模型,保守档给较弱模型,收紧的规则都在一份附录里。Conductor:基础档只跑清单,初审档加逐卡初审
止损 一次给全、只退回有依据的、轮次封顶、三个越线信号;同样约束收官自迭代
验收强度分档 判据是**"谁会攻击这段代码"**。只处理自家输入 = 常规档;处理外部/不可信输入 = 对抗档
信道 A/B 使用串行单文件信道;只有 A 的共享 index 可作 staging 回执。C 使用独立消息文件、唯一 ID 和显式 ack,按确定 SHA 读取

文件地图

文件 内容 读者
SKILL.md agent 入口:文件路由、新项目部署流程、日常路由 agent
protocol.md 共同协议:角色与两条链路、档位、生命周期、止损、强度分档、信道规则、工作区形态、L1-L3、三区、Owner 裁决规则、里程碑收官与交付报告、工程规约 全员必读
architect.md 批量出薄卡、出卡自查、裁决、按需审核、退回定性、收官评估与交付报告 Architect
conductor.md 与 Owner 对话和派工、派卡、卡级门禁、初审(初审档)、跟踪分流、三本账、里程碑收口与报告汇编 Conductor;未部署时由 Architect 执行
implementer.md 领卡、细化完成判据、三区内自主实现、三节交付报告、退回处理 Implementer
reviewer.md 验收测试(按强度分档)、退回分流、合入收口序列、漏检回流 Reviewer;未部署时由 Architect 执行
profiles/guarded.md 保守档附录:给较弱 Implementer 的收紧规则 用保守档时
anti-patterns.md 反模式池 —— 本仓最有价值的部分,每条带源案例 全员
templates/ 信道骨架、任务卡、Owner 交付报告、三份启动提示词 部署与日常
references/local-worktrees.md 本地并行 worktree、Multica 起点保护、收发消息、评审与收口、迁移 C / 托管运行
scripts/worktree_guard.py inspect / start / check,Python 3 标准库,无需安装依赖 开工与交付时

README.md(本文件)面向人类,帮你判断要不要用;SKILL.md 面向 agent,是它的操作入口。两者刻意不重复——单一事实源是这套框架自己的规矩之一。

安装

作为 Claude Code / Codex CLI 的 skill:

git clone https://github.com/ppw1014/cooperation-skill.git ~/Projects/cooperation-skill
ln -s ~/Projects/cooperation-skill ~/.claude/skills/cooperation-skill
ln -s ~/Projects/cooperation-skill ~/.codex/skills/cooperation-skill

用软链接指向同一份而不是各拷一份,是为了避免多处副本各自漂移——顺带一提,"覆盖前先确认目标路径是不是已有别人的内容" 也是这套东西教出来的教训之一。

只想读方法论: 直接看 protocol.md 和 anti-patterns.md,不装也能用。

在新项目部署

关键认知:其他 agent 读不到你的 skill 目录——它们只读项目仓库和自己的启动提示词。所以部署 = 把协作基础设施实例化进目标项目的仓库;本仓是母本 + 部署器。

  1. 定角色、模型与档位 —— 按 agent 数量决定是否部署 Reviewer 与 Conductor,未部署的由 Architect 兼;每个 Implementer 登记标准档或保守档;
  2. 定配置 —— 信道路径、分支约定、项目门禁命令表(protocol §8 的坑位)、backlog / 挂账 / 待 Owner 裁决清单 / 交付报告的位置;
  3. 定工作区形态与管理者 —— A/B/C 和 manual/multica 分开确定,以实际路径与宿主分配为证据;
  4. 实例化 —— 将协议、角色手册与反模式部署到项目;C 额外部署参考文档、guard、独立消息模板与工作区配置,保留相对链接并填入项目实际路径;
  5. 出启动提示词 —— 按 templates/*-bootstrap.md 填空交给 Owner,只指路径不复制内容;
  6. 写信道首条部署宣告 → 设计文档定稿 → 批量出第一个里程碑的卡。

完整步骤见 SKILL.md。

工作区形态 A / B / C

A:共享目录 B:独立 clone C:本地并行 worktree
Git 状态 工作文件、index、HEAD 共享 对象库与工作区各自独立 对象库/普通分支引用共享,工作文件/index/HEAD 独立
可见性 未提交消息可见 commit + push 后按远端 SHA 读 commit 后按本地 SHA 读,无需 push
消息 串行追加,共享 index 回执 串行追加,显式已读 独立文件、唯一 ID、显式 ack
集成 先确认共享现场 核对远端交付 SHA 每级集成人串行合入确定 SHA

探测比较同一机器上各方的 toplevel/git-dir/common-dir,不能把“读不到未提交消息”直接判成 B。Multica 托管任务还必须保留平台分配的分支和每轮起点;即使只改提交说明,amend 起点也会导致交付提交不再包含它。

每轮第一条 Git 写操作前执行 python3 scripts/worktree_guard.py start --run-id <本轮唯一ID>,交付消息提交后执行 check --run-id <同一ID>。记录按 worktree/运行隔离,重复 start 不覆盖;检查失败保留现场。详细配置、路径与边界见 工作流。

本地验证:python3 -B -m unittest discover -s tests -v。测试使用自动清理的临时 Git 仓库;通过不代表已验证 Multica 的实际记录与回收流程。

出处与成色

源自三个真实项目的协作实践与复盘,项目名已匿名化为项目 A / 项目 B / 项目 C:

  • 项目 A 贡献了主体协议(v1.5)与出卡侧、实现侧、验收侧的绝大部分反模式;
  • 项目 B 贡献了交叉 review 的止损规则与验收强度分档——代价是一张本地文档检查脚本的卡走了 7 轮 review、体量做到预算 2.3 倍;
  • 项目 C 是第一个跑三方部署(Architect 与 Reviewer 异源)的项目,贡献了形态 A 下的写入点纪律与提交 pathspec 纪律,以及门槛落点、区分性输入、接口消费方三条出卡检查——全部来自一张高风险卡的预审实战(现已并入 Architect 的出卡自查)。

成色说明:anti-patterns.md 里带「源案例」的条目来自实战。当前流程(Architect 按需唤起 + Conductor 卡级门禁 + Reviewer 里程碑验收 + 三区 + 收官自迭代 + 执行者档位)是基于模型能力提升做出的调整,尚未经实战校准。它放弃了开发期预审、逐卡审核和常规卡的逐卡实测,代价与回退办法记在 anti-patterns.md「流程变更说明」;不放心时把 Implementer 登记为保守档,就回到了逐卡审核的旧流程。用的时候请按这个区别对待——这套框架自己的规矩就是:没验证过的断言不能当事实用。

反馈回流

新项目撞出的教训先落项目实例文档,再回流本母本——母本是跨项目资产,实例是项目现场。两处都改时先实例后母本,防漂移。

许可

MIT © 2026 lc.jin

随便用,包括商用;保留版权声明即可。如果这套东西帮你省掉了几轮返工,欢迎把你撞出的新反模式提回来。