architect-loop阶段技能库深度剖析:从codebase-design到integrate的8个技能分工设计

原创2026-11-13 14:56:45204 阅读

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):

  1. 单一词汇表:8 个技能全部使用同一套术语,用词漂移本身就是"缺陷";
  2. 分层调用规则:只有编排器可以调用阶段技能,阶段技能之间互不调用,各自干完活就返回编排器;
  3. 权限隔离:阶段技能不提交代码、不碰追踪器、不直接编辑产品代码——发布与合并永远是编排器的动作。

💡 一句话理解:编排器是项目经理,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):

  1. 消费 change-context digest,把 README、架构文档、术语表更新到"实际交付了什么"的状态,退役行为直接删掉,文档提交单独成 commit;
  2. 逐个合并剩余绿灯 job 分支,每次合并后跑 postflight;
  3. 合并冲突只在发货时解决,解决后必须重跑全套收尾验证(validator + 全部 RUN 项);
  4. 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 个技能的源码(每个文件都不长)是最好的入门方式:

结语

architect-loop 的 8 个阶段技能库给出的启示是:AI 编码工厂的竞争力不在单点提示词有多长,而在职责切分有多干净——统一词汇定边界、冻结检查封死作弊、全新上下文防自欺、确定性脚本做裁判。想深入某一环的实现细节,直接打开对应 skills/<name>/SKILL.md,每篇都是百行以内的"岗位说明书"。

登录后查看全文
architect-loop