古法程序员复杂任务 Spec 写作：多 Agent 编排 + Skill 三层架构 + Gate 四态¶

📊 Level ⭐⭐⭐⭐⭐ | 15.9KB

核心定位¶

古法程序员（公众号 cc-codex实践）Harness Engineering 系列中篇——回答"业务侧的 spec 到底要写些什么"。核心命题：当任务复杂到需要多角色协作、跨多阶段、保证每步可追溯，spec 就不再是"一段提示词"，而是一套有结构的工程资产。

三件套：工作流编排 + skill 组织 + 知识库建连。

一、多 Agent：一个编排者 + 一队专职执行者¶

分工¶

编排者（入口 Agent）：只做编排和收口——判断阶段、门禁、派发、是否继续。不亲自写业务代码
执行者（7 角色）：需求分析师 / 架构师 / 各端实现者 / 代码评审者 / 测试工程师 / 联调工程师 / 效率工程师

派发纪律（血泪教训）¶

角色绑定规则约束：错派角色 = 绕过该角色该过的关卡（作者亲历：UI 实现错派架构师 → 视觉对齐问题复发）
先按阶段选角色，再用"改动文件路径 → 角色"映射表校验写入范围
跨端改动禁止一个 Agent 包办：必须架构师出统一契约 → 各端实现者隔离写入范围并行

并行配额¶

同主线最多 5 个子 Agent（常态 4 + 1 备用）
派发时声明：交付什么 / 什么格式 / 写到哪 / 验收条件
完成后先核验产物再关闭释放名额——否则就是失控的并发进程

二、入口文件（CLAUDE.md / AGENTS.md）写作¶

第一原则：薄入口¶

入口只放启动索引和硬边界，不放具体步骤。具体步骤 → skill，硬规则 → rules，角色契约 → agents，背景决策 → docs。入口本身只是一张地图。

入口 Agent 契约（写死）¶

编排者和收口者，不是执行者
只判断阶段/门禁/交接/派发
小型机械修订/索引更新/跑校验可自做，其余默认派子 Agent
不直接改生产代码，不绕过门禁、评审、校验
非致命问题先记录 owner/route/证据/下一步继续，不要停下来问
只有致命错误或门禁明确卡住才允许停

模板投影（反模式提醒）¶

入口真正的权威源是模板文件，CLAUDE.md / AGENTS.md 是从模板投影出来的。直接改投影文件 = 下次同步被覆盖。多 Agent 协作里很容易踩。

三、rules / docs / skills 三类目录¶

职责切分¶

目录	答什么	内容
skills	怎么做	具体步骤和流程
rules	必须遵守什么	硬约束、检查清单
docs	为什么是现在这样	架构、背景、长期决策记录

核心好处：同一条知识只有一个权威位置。

一个 skill 的标准结构¶

某个 skill/
├── SKILL.md        # 薄入口：路由 + 职责 + 边界 + 输出契约
├── references/     # 按需加载的长内容
└── scripts/        # 确定性脚本（仅 script-backed skill）

测试样例 → 平行的 evals 目录（按 skill 名一一对应，不放 skill 内）。

SKILL.md 固定骨架¶

frontmatter（name / 用于路由的 description「含适用/不适用/典型触发语」 / 层级 / 风险等级 / 是否人工复核）+ 职责边界 + 适用与不适用 + 工作方式（含"什么时候去读哪个 reference"）+ 按需加载 references 清单 + 输出与验证。

核心纪律：SKILL.md 要薄。它是路由卡不是知识库。

skill 怎么引用 rule / docs / 知识库¶

references（skill 自有长内容）：按需点名加载，平时不占上下文
rule（硬约束）：不在 skill 正文抄，靠路径和角色自动挂——目录级规则按路径加载，角色绑定规则随角色加载，最硬的几条启动就常驻
docs（长期知识）：每条 docs 知识都必须有明确消费方（某 skill/rule/角色引用它）——没有消费方 = 孤儿知识

新 docs 知识入系统时，必须顺手补上谁会用它。

script 硬要求¶

优先标准库 + POSIX shell，少引外部依赖
写状态文件原子写入，并发加锁
命令包装器只调配置里声明过的入口
完整日志落盘，主会话只回传摘要
新脚本必须配测试，改流程脚本要跑回归
脚本是用来兜住确定性的，自己不可靠就失去意义

四、Skill 三层架构¶

三层职责（严格不重叠）¶

编排层（orchestrator）：通常 1 个，维护状态机、派发控制权，不干具体活
阶段层（phase）：对应交付链路每段（需求/设计/开发/评审/测试/发布），管输入输出和门禁
原子层（atom）：单一确定能力，只做一件事，不编排别的 skill，不发明命令

阶段层关键设计：gate 四态¶

Gate	含义	处置
pass	通过	进下一阶段
blocked	卡住	附负责人和回退路径
not_required	本阶段对该模块不适用	放行（例：纯后端模块 UI 还原阶段）
risk_accepted	有问题但显式接受	留痕继续

核心纪律：没有证据时，宁可卡住也不要假装完成。

节点清单：单一事实来源¶

每个节点声明：属于哪一层 / 怎么执行（脚本 vs 模型推进）/ 路由描述（含"适用/不适用/典型触发语"）/ 输入输出 / 可用工具 / 风险等级 / 是否人工复核。

节点间三种 edge¶

Edge	含义	驱动方
handoff	阶段间流转	编排者驱动
dynamic_load	子 Agent 新上下文动态加载能力	用什么加载什么，不全塞进去
semantic	证据依赖	例："发现候选"只产候选地图，定点证据必须下游证据 skill 收敛，不能看到候选就当结论

为什么要分层¶

变化频率和失败模式不同： - 编排逻辑很少变（一变就全局） - 阶段契约中等频率变（改一段输入输出） - 原子能力最常变（每次只动一个点）

混在一起没法只改一层而不担心其他层崩。分层后每个能力独立路由、独立测、独立改，不会悄悄拖动其他部分。

下一篇预告¶

测试三件套： 1. 对照：同题配 skill vs 不配 skill 跑两遍，比差在哪（避免把通用规则的功劳算到 skill 头上） 2. 存档：模型每次真实回答存为文件、提交进代码库，跑完能复查而非跑完就忘 3. 不用大模型打分：裁判自己也不稳（今天给 8 分明天给 6 分），用写死的、对错一目了然的检查项来判

一句话总结¶

复杂任务的 spec 核心是三件资产：工作流怎么编排、skill 怎么组织、知识库怎么建连。把这三件分别说清楚，比写一段更长的提示词管用得多。

与 wiki 既有内容关系¶

Claude Code Dynamic Workflows 多Agent编排（696 行 9 source）：jiagoux/thariq 视角（6 模式/3 失败/10 场景）↔ 古法程序员视角（spec 写作/skill 三层/gate 四态/edge 三种）。互补不重复
高德 Spec as AI OS：反熵增架构（274 行）：都强调 spec 结构化；高德更宏观（OS 级反熵增），古法程序员更落地（文件目录/skill 分层/edge 种类）
Harness Engineering（290 行 5 source）：理论 + 5 制品 + 3 阵营；古法程序员的"skill 三层 + edge 三种 + gate 四态" = Harness 概念的工程实现映射

深度分析¶

Spec 从"提示词"到"工程资产"的范式转换：古法程序员的核心洞察在于，当任务复杂度超过单个 Agent 的能力边界时，spec 的性质发生根本变化——它不再是"更好的提示词"，而是包含编排逻辑（谁做什么）、skill 目录（怎么做的知识）和知识图谱（用什么做）的三维工程资产。这与 Harness Engineering 的"5 制品"理论完全对应，但提供了更落地的文件组织方案。

Gate 四态是编排鲁棒性的关键：pass/blocked/not_required/risk_accepted 四种 gate 状态的设计，解决了多 Agent 编排中最常见的问题——某个 Agent 失败后，整个 pipeline 是卡死还是优雅降级？blocked 态允许人工介入，risk_accepted 态允许跳过非关键检查点。这比简单的 try/catch 模式更适合生产环境。

Skill 三层架构的工程智慧：编排层 skill（全局调度）→ 阶段层 skill（单步执行）→ 原子 skill（可复用工具）的三层结构，本质上是软件工程中"模块化"思想在 AI Agent 领域的映射。它解决了两个关键问题：(1) skill 复用——原子 skill 可以跨多个阶段层 skill 调用；(2) 测试隔离——每层可以独立测试。

"不用大模型打分"的 eval 哲学：测试三件套中最有价值的洞察是"裁判自己也不稳"——LLM 评分的随机性（今天 8 分明天 6 分）使得自动化 eval 不可靠。用写死的检查项替代 LLM 评分，虽然覆盖面窄，但结果确定可复现。这是工程实践中"可复现性 > 覆盖面"原则的体现。

Edge 三种类型的语义价值：handoff（Agent 间交接）、dynamic_load（运行时加载）、semantic（语义级连接）三种 edge 类型，比简单的"数据传递"抽象层次更高。特别是 semantic edge——它允许 Agent 间通过语义相似度而非硬编码接口连接，是松耦合编排的关键创新。

实践启示¶

用"三件套"结构组织复杂任务 spec：不要写一个巨大的 prompt——拆分为 (1) 工作流编排文件（定义 Agent 分工和 gate 条件）、(2) skill 目录（按三层结构组织）、(3) 知识库（规则+文档+示例）。每个文件独立可测试。
为每个关键步骤定义 gate 状态：不要假设所有步骤都会成功——为每个步骤明确 gate 条件（pass/blocked/risk_accepted），并定义 blocked 态的升级路径（人工介入 or 自动重试）。
投资原子 skill 的复用性：在三层 skill 架构中，原子 skill 的复用价值最高。优先将通用能力（文件读写、API 调用、格式转换）封装为原子 skill，而不是在每个阶段层 skill 中重复实现。
eval 用确定性检查项替代 LLM 评分：对于自动化测试，优先使用写死的、对错一目了然的检查项（文件是否存在、格式是否正确、关键字段是否出现），而不是让 LLM 打分。LLM 评分只用于人工 review 环节。
CLAUDE.md 作为薄入口 + 模板投影：不要把所有规则写进 CLAUDE.md——保持它为"薄入口"（指向 rules/docs/skills 目录），用模板投影机制将详细规则注入到具体任务上下文中。这避免了 context window 浪费。