---
sha256: f4379665d838d733c580b7e348fb7acdc218a3bd0d63042b7b0f7b1515433018
source: "https://mp.weixin.qq.com/s/Q_k2duvAIv7hm9y6VxH3mQ"
title: "复杂任务的 Spec 怎么写"
author: 古法程序员
publisher: cc-codex实践
date: 2026-05-25
type: article
ingested: 2026-06-18
review_value: 8
review_confidence: 8
review_recommendation: strong
review_stars: 4
series: "古法程序员 Harness Engineering 系列（中篇：Spec 写作）"
series_parts:
  prev: "Harness 到底指什么"
  next: "Harness 怎么扩展：skill、配置目录与 hook"
---

# 复杂任务的 Spec 怎么写

> 作者：古法程序员（cc-codex实践） · 发布：2026-05-25

上一篇把 harness 和业务工程的边界划清了：harness 是平台层，业务工程建在它之上，不去改它。这篇正面回答"业务侧的 spec 到底要写些什么"。

**核心命题**：一个简单任务写句话扔给模型就完事了，但当任务复杂到需要**多个角色协作、跨多个阶段、还要保证每步可追溯**，spec 就不再是"一段提示词"，而是一套**有结构的工程资产**。三件套：**工作流编排 + skill 组织 + 知识库建连**。

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

### 编排者 vs 执行者分工

复杂任务的第一个决定，是**别让一个 Agent 从头干到尾**。上下文会爆、职责会糊，一个 Agent 既做需求分析又写代码又做评审，到后面它自己都分不清现在是哪个身份、该守哪条规矩。

**编排者（入口 Agent）** 只做编排和收口：判断现在到哪个阶段、门禁过没过、该派给谁、要不要继续。**不亲自写业务代码**。

**执行者** 按职责分角色（古法程序员的实际项目矩阵）：
- **需求分析师**：把需求文档和范围拆成结构化输入
- **架构师**：做技术设计、定跨端统一契约、写 ADR，**不写实现代码**
- **各端实现者**：按平台分开，每端一个，只写自己那端
- **代码评审者**：安全、性能、规范、参考实现对齐多维度核验
- **测试工程师**：补测试口径、写先失败的验收测试
- **联调工程师**：跑端到端构建、安装、运行、日志、跨端一致性
- **效率工程师**：把反复出现的模式沉淀成可复用资产

### 派发纪律

**关键认知**：选错角色，不只是分工不对，更会**绕过这个角色绑定的规则约束**。比如各端实现者会自动加载对应平台的硬约束清单，而架构师不会。错派 = 该过的关卡全失效（作者亲历：把端上 UI 实现错派给架构师，视觉对齐问题复发）。

派发规则：
1. **先按阶段选角色**，再用"改动文件路径 → 角色"映射表校验写入范围
2. 两者冲突 → 停下来说清楚，**绝不擅自扩大某个 Agent 的写入范围**
3. **跨端改动禁止一个 Agent 包办**：必须先由架构师产出统一契约，再让各端实现者在隔离写入范围里并行

### 并行配额

- 同一条主线**最多挂 5 个子 Agent**，常态并行 4 个，第 5 个只留作备用
- 每个子 Agent 派出去时声明：**要交付什么产物、什么格式、写到哪、验收条件是什么**
- 完成后先核验产物在不在、合不合格，再关闭它释放名额
- 没有这套配额和产物核验，多 Agent 很快会变成**一群失控的并发进程**

## 二、编排者入口（CLAUDE.md / AGENTS.md）写什么

### 第一原则：薄入口

入口只放**启动索引和硬边界**，不放具体步骤。几千行的 CLAUDE.md 模型每次启动都要读一遍，既慢又抓不住重点。

正确的做法：让入口告诉模型"任务来了先判断类型、然后去读哪个文件"。具体步骤放进 skill，硬规则放进 rules，角色契约放进 agents，背景和决策记录放进 docs。**入口本身只是一张地图**。

### 入口 Agent 契约（写死）

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

最后两条尤其重要：复杂工作流最怕 Agent 一遇到小问题就停下来等你拍板，跑十分钟问你八次。把"什么情况记录后继续、什么情况才允许停"写进契约，它才能真正一口气跑完一条链路。

### 子 Agent 派发也是编排者的内部动作

不该每次都回来问"能不能派下一个"——**只有范围扩大、破坏性操作、风险接受、对外发布这些才回到你这里决策**。

### 反模式：直接编辑生成态的入口文件

入口真正的权威源是**一个模板文件**，CLAUDE.md 和 AGENTS.md 都是用工具从模板投影出来的。**直接改投影出来的文件，下次一同步就被覆盖了**。在多 Agent 协作里很容易踩。

## 三、rules / docs / skills 怎么组织

### 三类目录的职责切分

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

**核心好处**：同一条知识**只有一个权威位置**。流程变了改 skill，约束变了改 rule，要追溯某个设计为什么这么定就翻 docs，不会到处都是重复又互相矛盾的说明。

### 一个 skill 的文件结构

```
某个 skill/
├── SKILL.md          # 入口：路由 + 职责 + 边界 + 输出契约
├── references/       # 按需加载的长内容：方法论、模板、检查段
└── scripts/          # 确定性脚本（只有 script-backed skill 才有）
```

测试样例不放在 skill 目录里，而是放在一个**平行的 evals 目录下、按 skill 名一一对应**。

### SKILL.md 固定骨架

- **frontmatter**：name、用于路由的 description（必须含"适用 / 不适用 / 典型触发语"）、层级、风险等级、要不要人工复核
- **职责边界**：这个 skill 管什么
- **适用与不适用**：什么时候召唤、什么时候别召唤
- **工作方式**：最小流程，外加"什么时候该去读哪个 reference"
- **按需加载 references**：一张清单，把每个场景对应的 reference 文件列出来
- **输出与验证**：交付什么、怎么算通过

**关键**：SKILL.md 要薄。它是给模型快速判断"要不要用我、怎么用我"的路由卡，**不是知识库**。把平台细节、反模式、长模板全堆进去，等于每次召唤都让它读一篇论文，召唤判断反而被淹没。

### skill 怎么引用 rule、docs 和知识库

#### references —— skill 自己的长内容，**按需点名加载**

不把方法论和模板写进 SKILL.md，而是拆成 references 下的独立文件，在"工作方式"里写清"这一步去读哪个 reference"。**模型只在真正走到那一步时才把它读进上下文，平时不占**。

#### rule —— 不在 skill 正文里抄，**靠路径和角色自动挂**

两种挂法：
- **目录级规则**：每份规则声明它管哪些路径，Agent 一进入这个路径，规则就自动加载进来
- **角色绑定**：某个角色被派出去时，它该守的检查清单自动跟着加载

**最硬的那几条约束则不挂路径，启动就常驻**。

**好处**：规则的权威源只有一份，skill 和角色都是"引用"它，而不是各自抄一份。

#### docs —— 被消费的知识库，**引用关系必须显式**

docs 放长期知识和决策记录，skill 在需要背景时去读它。

**重要纪律**：docs 里的每条长期知识，都应该有一个**明确的消费方**（某个 skill、rule 或角色）引用它。**没有消费方的知识就是孤儿知识**——写下来没人读、改了没人知道、慢慢就和实际脱节。

**新增一条 docs 知识时，顺手补上谁会用它，这条知识才算真正进了系统，而不是堆在一个没人看的文件夹里**。

### 三者合起来是一张引用网

skill 正文薄、点名读自己的 references、被动挂上路径和角色绑定的 rule、主动去 docs 取背景，**而每条知识都只有一个权威位置**。

### script 怎么组织

scripts 目录放**确定性工具**：校验器、命令包装器、流程辅助脚本。它存在的意义，是**缩小 Agent 自由发挥的空间**。凡是有唯一正确做法的事，就别让模型每次现编，写成脚本钉死。

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

## 四、skill 怎么分层，为什么分层

### 三层架构（职责严格不重叠）

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

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

每个阶段结束不是简单的"做完了"，而是给一个**四态结论**：

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

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

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

把整张图落成一个清单文件，是所有 skill 的**单一事实来源**。每个节点声明固定字段：

- 属于哪一层
- 怎么执行（背后挂脚本还是靠模型推进）
- 用于路由的描述（**必须含"适用 / 不适用 / 典型触发语"**）
- 输入输出
- 可用工具
- 风险等级
- 要不要人工复核

### 节点间三种 edge

| Edge | 含义 | 驱动方 |
|---|---|---|
| **handoff** | 阶段之间的流转 | 编排者驱动 |
| **dynamic_load** | 按当前任务类型，在子 Agent 的新上下文里动态加载对应能力 | 用什么加载什么，不全塞进去 |
| **semantic** | 证据依赖 | 例："发现候选"这步只产候选地图，真正的定点证据必须由下游证据 skill 收敛，**不能看到候选就当结论** |

### 为什么要分层

因为这几件事的**变化频率和失败模式完全不同**：

- 编排逻辑**很少变**，一变就是全局的
- 阶段契约**中等频率变**，改的是某一段的输入输出
- 原子能力**最常变**，但每次只动一个点

**混在一起，你就没法只改一层而不担心其他层崩**。分层之后，每个能力都能被独立地路由、独立地测、独立地改，而不会悄悄拖动别的部分。

## 一句话总结

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

## 下一篇预告（古法程序员系列）

下一篇讲怎么测一个 skill 到底好不好用，三件事：
1. **怎么做对照**：同一道题，配 skill 跑一遍、不配再跑一遍，比两次输出差在哪
2. **怎么把结果存下来**：模型每次的真实回答都存成文件、提交进代码库，谁都能随时翻出来复查
3. **为什么不用大模型打分**：让 AI 当裁判听着省事，但裁判自己也不稳。宁可用一组写死的、对错一目了然的检查项来判

## 与 wiki 既有内容的关系

**与 [[entities/claude-code-dynamic-workflows-multi-agent-orchestration|Claude Code Dynamic Workflows 多Agent编排]]**（696 行 9 source）：
- jiagoux/thariq 侧重 Thariq 官方 6 模式、3 失败模式、10 实战场景
- 古法程序员侧重 **spec-as-code 实战** + **skill 三层架构** + **gate 四态** + **edge 三种** + **测试三件套**
- **互补**：dynamic-workflows 给"模式/失败/场景"，古法程序员给"工程资产/组织/分层/验证"

**与 [[entities/spec-as-aios-anti-entropy-architecture-gaode-ai-native-series-2|高德 Spec as AI OS：反熵增架构]]**：
- 都强调 spec 的结构化
- 高德视角更宏观（OS 级反熵增）
- 古法程序员视角更落地（具体文件目录/skill 三层/edge 三种）

**与 [[entities/harness-engineering|Harness Engineering]]**：
- 古法程序员 = 实战派 Harness 落地；harness-engineering 实体 = 理论 + 5 制品 + 3 阵营
- 古法程序员的 "skill 三层 + edge 三种 + gate 四态" 是 Harness 概念的**工程实现映射**