architect-loop阶段技能库深度剖析:从codebase-design到integrate的8个技能分工设计
architect-loop阶段技能库深度剖析:从codebase-design到integrate的8个技能分工设计
architect-loop 是一款面向 AI 编码 Agent 的"自主软件工厂"技能库:一个编排器(orchestrator)指挥多个上下文全新的子代理,把需求自动变成可交付的 PR。它的核心设计是——用 8 个各司其职的阶段技能(stage skills)替代一坨巨型提示词,从 codebase-design 的共享设计词汇,一路覆盖到 integrate 的收尾发货。本文带你逐一拆解这 8 个技能的分工与协作方式。
一、为什么是"8 个技能"而不是一个?
传统做法是把所有规则塞进一个超长提示词,结果往往是:上下文越长模型表现越差、职责混乱、无法复用。architect-loop 的做法是把一次完整交付拆成一条流水线,每个环节由一个小而专的技能承担,每个技能通常只有几十到一百来行。
这套拆分背后有三条设计约束(记录在 docs/spec/skill-library.md):
- 单一词汇表:8 个技能全部使用同一套术语,用词漂移本身就是"缺陷";
- 分层调用规则:只有编排器可以调用阶段技能,阶段技能之间互不调用,各自干完活就返回编排器;
- 权限隔离:阶段技能不提交代码、不碰追踪器、不直接编辑产品代码——发布与合并永远是编排器的动作。
💡 一句话理解:编排器是项目经理,8 个技能是 8 个只干自己那一行的工位。
二、8 个技能总览:一张表看懂分工
| 顺序 | 技能 | 一句话职责 | 执行者 |
|---|---|---|---|
| 0 | codebase-design | 全员共享的"设计语言"词汇表 | 所有技能的公共依赖 |
| 1 | to-spec | 把需求综合成规范文档 spec | strategist 子代理 |
| 2 | adversarial-review | 先攻击 spec,再修订并做拆解压力测试 | 全新 strategist 子代理 |
| 3 | to-issues | 把 spec 切成可并行的垂直切片 issue | 随阶段 2 调用 |
| 4 | frozen-checks | 给每个 issue 写好"冻结"验收检查 | 随阶段 2 调用 |
| 5 | tdd | builder 的红绿循环 TDD 作业手册 | 每个 builder 预加载 |
| 6 | final-review | 整次 run 的收尾冷读评审 | 全新 strategist 子代理 |
| 7 | integrate | 文档更新 + 合并 + PR 收尾 | 专用 builder 子代理 |
配套的校验器 tests/validate_skills.py 还会检查每个技能的行数预算、词汇一致性和交叉引用完整性——技能库的"卫生"本身也是被测试的。
三、逐个技能拆解
1. codebase-design:先统一"普通话"再开工
skills/codebase-design/SKILL.md 不写代码,它定义了一套必须逐字使用的术语表:
- 设计侧:module(模块)、interface(接口)、seam(接缝)、adapter(适配器)、depth(深度)、leverage(杠杆)、locality(局部性)——禁止用 component / service / API 之类同义词替代;
- 工厂侧:run、issue、slice、frozen check、strategist、builder、orchestrator、verdict、digest 等,每个词只有一行定义。
它还在教"深度模块"设计方法论:小接口藏大实现、用"删除测试"判断模块是否只是传声筒、接口即测试面。当一种接口设计说不准时,它还内置了 DESIGN-IT-TWICE.md 的"设计两次"模式:并行派出 3 个以上子代理各画一种截然不同的接口方案,再按深度、局部性、接缝位置横向对比后拍板。
分工价值:所有后续技能、builder、评审者都引用这份词汇表,从源头上杜绝"同一个词、三种理解"。
2. to-spec:只综合,不追问
skills/to-spec/SKILL.md 是 intake 阶段的第一笔:把对话、仓库证据和研究发现综合写成 docs/spec/<run>.md,遵循"synthesize, do not interview"(只综合、不追问)原则。
几个反直觉的规矩:
- spec 正文不许写具体文件路径和代码片段(容易过期),原型产出的决策片段(状态机、schema)是唯一例外;
- 遇到的每个悬而未决的问题不自己拍板,而是以
RULING NEEDED: 问题 | 选项 | 默认值一行格式交回编排器走计时裁决协议; - 固定模板:Goal、Non-goals、Assumptions、Implementation decisions、Validation strategy 等章节名是"承重墙",后续对抗评审和解压测试都靠章节名定位。
3. adversarial-review:先摧毁,再重建
skills/adversarial-review/SKILL.md 是全流程最"狠"的一环:派一个对计划毫无立场的全新 strategist,任务是先打破 spec:
- 阶段 1 攻击:查章节间矛盾、不可证伪的声明、没有仓库证据的假设、缺失的 Non-goals、超出目标范围的野心,每条发现都要给出
FALSIFIED(被证伪)或HOLDS(成立)的判决加证据; - 阶段 2 修订与拆解:只把被证伪项的修复折回 spec,然后调用
to-issues和frozen-checks产出 issue 草稿和检查草稿; - 阶段 3 拆解压力测试:把每条
RUN:检查项真的在当前代码树上跑一遍、解析每个路径指针、用git check-ignore检查新产物路径——光"读"不算数。
它的边界同样硬:可以改 spec 草稿、可以写草稿,但永不提交、永不碰 tracker、永不编辑产品代码。
4. to-issues:切"曳光弹"式垂直切片
skills/to-issues/SKILL.md 把加固后的 spec 变成一批可并行的 issue,核心手法有四:
- 结构先行:重构/预重构类 issue 排最前,并挂 blocked-by 边,先"让改动变简单,再做简单的改动";
- 曳光弹垂直切片:每个 issue 是一条窄但完整的端到端路径,可独立演示验证,绝不做"只切一层"的水平片;
- 最大化不相交并行面:同一波次派发的 issue 文件集零重叠,共享文件冲突视为"拆解失败",拆分或重排,禁止事后手工合并;
- 接口契约而非未来代码引用:生产者 issue 发布契约块(名称、参数、返回类型、行为),消费者只引用契约,不引用还没写出来的实现。
每个 issue 还自带 ≤30 行的 change-skeleton(文件、签名、数据流、不变量),是契约而非逐行指令。
5. frozen-checks:答案先冻结,再开工
skills/frozen-checks/SKILL.md 是全库最有辨识度的自创机制,直接封死"AI 改考题"的作弊路径:
- 每个 issue 一个检查文件,位于
docs/checks/<run>/<slice>.md,头部写明目的、spec 指针和"失败契约"(失败了改哪里); - 评分语法只有一种:
- RUN: 命令 -> exit:<n>加可选的match:"子串",由确定性脚本 skills/architect/check-runner.sh 执行,带类型化退出码; - 每条检查必须是单一、可证伪的事实,冻结前必须真跑一遍——"不会失败的检查不是检查";
- 冻结协议:所有检查文件在任何 builder 被派出之前就提交进 factory 分支,此后对 builder 和评审者只读;改动检查文件 = 自动 FAIL。
这解决的是 DESIGN.md 里点名的"goalpost drift"(验收标准在结果出现后被改,于是永远通过)。
6. tdd:builder 的红绿循环作业手册
skills/tdd/SKILL.md 预加载给每个 builder,规定了工厂版的 TDD 循环(RED → GREEN):
- 接缝是预先约好的:issue 和 spec 里已经写明了测试边界,builder 不需要也不应该去追问用户;
- 冻结检查不是你的测试:它在外部事后验证切片,你必须在约定接缝上写自己的测试并亲跑——"冻结检查全绿但没有自己的测试"不算完成;
- 反模式清单:与实现耦合的测试、同义反复的断言、"先写完所有测试再写实现"的水平切法;
- 循环铁律:先红后绿、每周期一个接缝一个测试、红灯期间禁止重构、只在系统边界 mock。
配套的 skills/tdd/tests.md 用"好测试 / 坏测试"对照示例,skills/tdd/mocking.md 给出 mock 边界指南。
7. final-review:全程唯一的"模型评审"
skills/final-review/SKILL.md 在所有 issue 关闭后由编排器显式派出一次,评审者冷读整个 run——"你什么都没写,这正是重点"。
评审顺序固定:spec → 全量 diff(git diff <pre-run-sha>..HEAD)→ 每个 issue 的接口契约块 → 编排器跑好的收尾测试输出。每条发现必须过三道闸:只报本次 diff 引入的缺陷、不确定就不报、先复现后上报。
它重点猎杀"并行隔离工作的专属缺陷":重复概念、命名漂移、生产者契约与消费者调用不一致、跨切片矛盾假设、spec 没要过的兼容垫片等。零发现则直接回 REVIEW: GREEN 短路进 integrate;有发现则写成 review spec + 修复 issue 草稿 + 检查草稿,交修复波次(fix wave)的新 builder 施工,它自己永不编辑代码。测试健康度诊断由 skills/final-review/TEST-STEWARDSHIP.md 承担。
8. integrate:文档先行,证据收尾
skills/integrate/SKILL.md 是流水线的最后一站,由专用 builder 子代理执行,且第一步不是合并代码,而是文档通读(docs pass):
- 消费 change-context digest,把 README、架构文档、术语表更新到"实际交付了什么"的状态,退役行为直接删掉,文档提交单独成 commit;
- 逐个合并剩余绿灯 job 分支,每次合并后跑 postflight;
- 合并冲突只在发货时解决,解决后必须重跑全套收尾验证(validator + 全部 RUN 项);
- GitHub 模式下准备带
Closes #<tracking-issue>的 PR;markdown 模式下产出合并说明与 finish record。
它同样"只能看证据说话":报告里每个声明都对应一条命令结果;digest 以 DRAFT 形式交回,是否发货由编排器裁决——它自己不能批准自己的工作。
四、协作全景:一次 run 里 8 个技能如何接力
结合 README.md 的 /architect 流程,整条链路是:
编排器 intake
→ to-spec 起草 spec
→ adversarial-review 攻击/修订,内嵌调用 to-issues + frozen-checks
→ 编排器发布 issue、冻结检查(git 提交,SHA 记录在案)
→ builder 波次并行施工(tdd 循环 + 自跑测试)
→ check-runner 确定性评分冻结检查
→ final-review 冷读全量 diff
→ 有发现:fix wave 修复;GREEN:直接收尾
→ integrate 文档先行 + 合并 + PR
贯穿全程的公共词汇由 codebase-design 提供,而 CONTEXT.md 则是面向人阅读的术语总表。
五、这套分工设计的 3 个精髓
1️⃣ 用"词汇契约"替代"流程监督" 与其要求每个代理"注意保持一致",不如在 codebase-design 里把术语锁死,并由 tests/validate_skills.py 的词汇 lint 自动兜底——用机器检查语言一致性。
2️⃣ 用"确定性 + 模型"双轨替代纯模型互评 机械的验收交给 check-runner(冻结、只读、类型化退出码),模型判断只保留 final-review 一道(且必须全新上下文、只读、先复现后上报)。DESIGN.md 引用的研究结论是:写代码的代理自评最不可信,全新上下文验证者显著优于自我批评。
3️⃣ 每个技能的"不可为清单"和"可为清单"一样长 to-spec 不建 issue、adversarial-review 不提交、final-review 不编辑、integrate 不裁决发货……能力的克制本身就是架构,它保证任何单一环节失控都不会造成越权副作用。
六、快速上手:安装与查看技能库
git clone https://gitcode.com/gh_mirrors/ar/architect-loop
cd architect-loop && ./install.sh # Windows: .\install.ps1
安装器会把 skills/ 整棵树复制到 Claude / Codex 的技能目录。装上之后,直接看 8 个技能的源码(每个文件都不长)是最好的入门方式:
- 词汇总表:skills/codebase-design/SKILL.md
- 阶段技能:skills/to-spec/SKILL.md、skills/adversarial-review/SKILL.md、skills/to-issues/SKILL.md、skills/frozen-checks/SKILL.md、skills/tdd/SKILL.md、skills/final-review/SKILL.md、skills/integrate/SKILL.md
- 设计动机与证据:DESIGN.md、docs/spec/skill-library.md
结语
architect-loop 的 8 个阶段技能库给出的启示是:AI 编码工厂的竞争力不在单点提示词有多长,而在职责切分有多干净——统一词汇定边界、冻结检查封死作弊、全新上下文防自欺、确定性脚本做裁判。想深入某一环的实现细节,直接打开对应 skills/<name>/SKILL.md,每篇都是百行以内的"岗位说明书"。