目录一、复杂任务的第一条原则不要让一个 Agent 从头干到尾二、编排者入口写什么入口要薄边界要硬三、spec 不是一个文件而是一组目录的分工四、一个 skill 应该怎么写薄入口厚引用可验证输出五、rules、docs、references 的区别不要把所有知识都叫“文档”一SKILL.md路由卡二referencesskill 私有长内容三rules硬约束四docs长期知识和决策记录六、script-backed skill确定性的事不要让模型自由发挥七、skill 要分层编排层、阶段层、原子层一编排层维护状态机不做具体活二阶段层负责一个交付阶段三原子层只做一件确定的事八、用 manifest 管住整张 skill 图一manifest二三种 edge声明边1. handoff阶段流转2. dynamic_load按任务动态加载能力3. semantic证据依赖九、复杂任务 spec 必须设计失败路径十、Spec 里最容易缺的东西产物契约十一、写复杂 spec 的一个可复用模板1. 任务类型2. 角色和权限3. 路径到角色映射4. 阶段状态机5. 门禁规则6. 知识装载规则7. 脚本规则8. 失败处理9. 最终报告十二、记住一句话复杂 spec 的核心不是“写更长”而是“拆得更准”参考文章我们在《Harness 到底指什么Coding Agent 时代的运行时边界、工程纪律与业务分层》讲了 harness 和业务工程的边界harness 是平台层负责提供运行环境、工具接口、上下文装载、权限控制和执行协议业务工程建在它之上不去改它。但这只解决了第一个问题平台和业务的边界在哪里。真正让复杂任务稳定跑起来的是第二个问题业务侧的 spec 到底应该写什么。一个简单任务可以是一句话提示词。比如“把这段代码改成 TypeScript”。模型读完直接干。但当任务复杂到需要多人协作、跨端实现、多阶段推进、过程要可追溯、结果要可验收时spec 就不能再是一段提示词了。它必须变成一套有结构的工程资产。我现在更倾向于这样定义复杂任务的 specSpec 不是告诉模型“做什么”的提示词而是定义一套 AI 工程系统如何分工、如何加载知识、如何推进状态、如何判断完成、如何在出错时回退的操作协议。它至少要回答四个问题第一复杂工作由谁做谁不该做。第二每个阶段怎么流转什么时候能进入下一步。第三知识、规则、流程、脚本分别放在哪里。第四怎么让每一步的产物、证据和责任都能被追踪。这篇就正面回答这个问题。一、复杂任务的第一条原则不要让一个 Agent 从头干到尾很多人写复杂任务 spec 的第一个误区是把复杂性继续塞给一个 Agent。于是入口提示词越来越长你要先理解需求再做架构设计再写代码再补测试再自我评审再跑验证最后总结风险。看起来很完整实际很危险。因为复杂任务失败往往不是模型“不够聪明”而是它在同一个上下文里同时承担了太多身份。它一会儿是产品经理一会儿是架构师一会儿是实现者一会儿又是评审者。每个身份应该遵守的约束不同但上下文混在一起之后边界会逐渐变模糊。最常见的几个问题是它在做实现时忘了设计阶段的约束它在做评审时默认相信了自己刚写的代码它在修 bug 时顺手扩大了改动范围它在上下文快满时开始丢掉早期决策它在阶段切换时没有留下可复查的证据。所以我的做法是一个编排者加一队专职执行者。编排者不是“更强的全能 Agent”而是“流程控制器”。它负责判断当前任务处于哪个阶段、门禁是否通过、下一步该交给谁、产物是否合格、是否需要回退。它不亲自写业务代码。真正的工作交给专职子 Agent每个子 Agent 在一个新的上下文里启动只加载这一次任务需要的规则、文档、输入和工具。这样上下文干净职责清楚也更容易审计。我通常把执行者拆成这些角色需求分析师把需求文档、范围、非目标、验收标准拆成结构化输入。架构师做技术方案、统一跨端契约、写 ADR但不写实现代码。端侧实现者按平台拆开比如 iOS、Android、Web、Backend各写各的范围。代码评审者从安全、性能、规范、兼容性、参考实现对齐等角度审查。测试工程师补测试口径优先写会先失败的验收测试。联调工程师跑端到端构建、安装、运行、日志收集和跨端一致性验证。效率工程师把反复出现的问题沉淀成脚本、模板、检查器或新的 skill。这套角色划分的意义不只是“分工更清楚”。更关键的是角色本身是规则装载单元。不同角色应该自动加载不同规则。架构师需要加载架构约束、跨端契约规范、ADR 模板。端侧实现者需要加载平台规范、目录规则、UI 对齐清单、测试命令。代码评审者需要加载安全检查、性能检查、反模式清单。联调工程师需要加载运行环境、日志路径、构建脚本和故障分流规则。如果角色选错了问题就不只是“这个 Agent 不擅长”而是它会绕过本该生效的一整套规则。也许我们都吃过类似的亏。比如有一次端上 UI 实现被误派给架构师。架构师当然能写代码但它没有加载端侧实现者绑定的 UI 约束、组件边界和视觉还原检查。结果代码能跑结构也说得过去但视觉对齐问题又冒出来了。所以派发不能凭感觉。我的规则是先按阶段选角色再用“改动文件路径 → 角色”的映射表校验写入范围。两者冲突时必须停下来记录冲突不允许擅自扩大某个 Agent 的写入范围。比如docs/adr/**只能由架构师写ios/**只能由 iOS 实现者写android/**只能由 Android 实现者写web/**只能由 Web 实现者写scripts/validation/**可以由效率工程师写但必须附测试生产代码不能由编排者直接改。跨端任务尤其要严格。如果一个需求同时改 iOS、Android、Web不允许派一个“全栈 Agent”包办。正确做法是先由架构师产出统一契约明确字段、状态、错误码、交互边界和验收标准再让各端实现者在隔离写入范围内并行实现最后由联调工程师按统一契约验证一致性。复杂任务里多 Agent 不是为了炫技而是为了把“职责、上下文、规则、写入权限和证据链”拆开。拆开之后系统才可控。二、编排者入口写什么入口要薄边界要硬编排者的行为绝大部分由入口文件决定。在 Claude Code 里可能是CLAUDE.md在其他环境里可能是AGENTS.md、SYSTEM.md或某个入口 spec。名字不重要作用一样它是 Agent 启动时最先读到的业务侧协议。很多项目会把入口文件写成一本巨大的说明书。所有流程、所有规则、所有模板、所有反模式、所有目录说明都塞进去。结果入口文件越来越长模型每次启动都要读一遍读完还抓不住重点。我现在的原则是入口只放启动索引和硬边界不放具体步骤。入口文件应该像一张地图而不是一座仓库。它要告诉编排者任务来了先判断什么不同任务类型去读哪个 skill不同路径受哪些 rule 管哪些事情绝对不能做什么情况可以继续推进什么情况必须停下来产物和状态写到哪里。但它不应该详细解释每个阶段怎么做。具体步骤放进 skill硬约束放进 rules角色契约放进 agents长期知识和决策记录放进 docs。入口越薄越容易稳定。入口越厚越容易变成上下文噪音。我会在入口里写死一段“编排者契约”。核心大概是编排者是流程控制者和收口者不是执行者。编排者负责判断阶段、门禁、交接、回退和是否继续。编排者默认不直接修改生产代码。小型机械修订、索引更新、状态文件维护、跑校验可以自己做。具体业务实现、架构设计、测试补充、代码评审默认派给子 Agent。不得绕过门禁、评审、测试和写入范围限制。不得让一个 Agent 同时承担设计、实现和评审。遇到非致命问题记录 owner、route、evidence、next step 后继续推进。只有致命错误、权限风险、破坏性操作、范围扩大、门禁阻塞才允许停下来请求人工决策。最后两条非常重要。复杂工作流最怕的是 Agent 一遇到小问题就停下来问你。缺一个日志路径问你。测试命令失败一次问你。某个文件命名不一致问你。一个可选字段没找到问你。这类 Agent 看起来很谨慎实际无法承担复杂任务。因为复杂任务天然会有小缺口、小冲突、小不确定。系统必须区分“可以记录后继续”的问题和“必须阻塞”的问题。我通常把问题分成四类info_gap信息缺口但不影响当前阶段继续。记录下来交给对应 owner 后续补齐。local_failure局部失败比如某个非关键测试失败。记录日志、归属和重试路径继续其他不依赖它的任务。gate_blocker门禁阻塞比如契约缺失、测试无法运行、产物不存在。必须停在当前阶段。risk_decision需要人类接受风险比如跳过测试、扩大范围、修改公共接口、执行破坏性操作。必须回到用户。这套分类写进入口编排者才不会把所有问题都当成阻塞也不会把真正的风险偷偷吞掉。入口里还应该写清楚“哪些决策需要人”。比如扩大任务范围需要人。修改公共 API 需要人。删除数据、重置环境、批量迁移需要人。接受安全、合规、性能风险需要人。对外发布、合并主干、发版需要人。而这些不需要每次问派发下一个子 Agent读取对应 skill、rule、docs运行已声明的校验脚本更新状态文件在同一范围内修复明确的校验失败把非致命问题记录到 backlog。入口文件的价值不是让 Agent “更懂业务”而是让它知道什么事它有权决定什么事必须交还给人。还有一个工程细节很容易被忽略不要直接编辑生成态入口文件。如果你的CLAUDE.md和AGENTS.md是从模板投影出来的那权威源应该是模板而不是生成文件。直接改生成文件下次同步就会被覆盖。在多 Agent 协作里这个坑更常见。某个 Agent 以为自己修了入口规则其实只是改了一个一次性产物。正确做法是模板是权威源生成文件只读或只由脚本生成修改入口规则必须改模板生成文件头部标明“不要手改”CI 或校验脚本检查投影是否一致。入口文件不是越全越好。它要短但要硬。短是为了减少上下文噪音。硬是为了让整个系统有不可绕过的边界。三、spec 不是一个文件而是一组目录的分工复杂任务的 spec 不应该堆在一个大文件里。它应该拆成几类资产每类回答一个问题。我通常用三类目录skills怎么做。rules必须遵守什么。docs为什么是现在这样。这三类目录的分工很关键。如果流程变了改 skill。如果约束变了改 rule。如果背景、架构决策、长期知识变了改 docs。同一条知识只能有一个权威位置。否则系统很快会变成这样skill 里写一版流程rule 里又写一版限制docs 里还有旧版说明入口文件里复制了一段过时内容最后模型每次读到的东西都互相矛盾。复杂 spec 的一个核心目标就是消灭这种“多处复制的伪知识”。四、一个 skill 应该怎么写薄入口厚引用可验证输出每个 skill 是一个能力单元。它可以很大比如“完成一个跨端需求开发”也可以很小比如“生成 ADR 编号”或“检查契约字段是否齐全”。但无论大小它都应该有稳定的文件结构。一个典型 skill 目录长这样skills/ feature-delivery/ SKILL.md references/ requirement-analysis.md architecture-contract-template.md gate-definition.md scripts/ validate_state.py check_outputs.sh其中SKILL.md是入口。它不应该很长。它的职责是让模型快速判断这个 skill 是干什么的什么时候应该用什么时候不应该用需要哪些输入会产出什么怎么判断通过需要按需加载哪些 reference有没有脚本兜底。我一般会给SKILL.md一个固定骨架。第一段是 frontmattername: feature-delivery description: 适用需要从需求分析推进到设计、实现、评审、测试、联调的复杂业务需求。 不适用单文件机械修改、纯问答、无需状态追踪的小修小补。 典型触发语实现这个需求、完成这个功能、跨端改造、从需求到上线。 layer: orchestrator risk: high human_review: required_before_release这里的 description 不是写给人看的宣传语而是写给路由器看的。它必须包含三件事适用不适用典型触发语。只有这样模型才更容易在正确场景召唤它也更容易在错误场景拒绝它。第二段是职责边界。比如本 skill 负责复杂业务需求的端到端编排包括需求结构化、架构设计、分端实现、代码评审、测试补充、联调验证和收口报告。 本 skill 不直接写生产代码不替代平台层 harness不修改未授权路径不跳过阶段门禁。职责边界一定要同时写“管什么”和“不管什么”。只写正向职责很容易让 Agent 自动扩权。第三段是输入输出。输入包括需求来源目标范围非目标范围受影响路径验收标准风险等级已有参考实现或设计稿允许使用的工具写入范围。输出包括结构化需求设计方案或 ADR跨端契约实现 PR 或补丁测试报告评审报告联调日志阶段门禁结论最终收口摘要。第四段是工作方式。这里不要写长篇方法论只写最小流程1. 读取任务输入生成 state.json。 2. 调用 requirement-analysis phase。 3. requirement gate 通过后调用 architecture phase。 4. architecture gate 通过后按路径和平台派发 implementation agents。 5. 实现完成后调用 review phase。 6. review gate 通过后调用 test phase。 7. test gate 通过后调用 integration phase。 8. 生成 final report。第五段是按需加载 references。需要拆需求时读取 references/requirement-analysis.md。 需要定义跨端契约时读取 references/architecture-contract-template.md。 需要判断阶段是否通过时读取 references/gate-definition.md。这点很重要。SKILL.md要薄长知识放 references。模型只有走到那一步才把对应内容读进上下文。否则每次召唤 skill 都读一堆用不上的内容既浪费上下文也会干扰判断。第六段是验证。比如通过条件 - state.json 存在且 schema 校验通过 - 每个阶段都有 gate 结论 - 每个 blocked 都有 owner、reason、evidence、rollback_path - 每个 pass 都有可追溯证据 - 生产代码改动必须有对应实现者和评审者 - 最终报告必须列出完成项、未完成项、风险和后续动作。一个 skill 如果没有验证标准就只是另一段提示词。一个 skill 有了验证标准才开始变成工程资产。五、rules、docs、references 的区别不要把所有知识都叫“文档”复杂 spec 最容易混乱的地方是所有东西都被叫成“文档”。流程文档、规则文档、背景文档、模板文档、排障文档、ADR全都混在一起。模型读的时候不知道哪些是必须遵守哪些只是参考人维护的时候也不知道改哪里才算改到了权威源。我会把它们拆成四类。一SKILL.md路由卡它回答这个能力什么时候用怎么启动输入输出是什么最小流程是什么需要读哪些 reference怎么算完成。它要短。二referencesskill 私有长内容它回答某一步具体怎么做模板长什么样有哪些案例有哪些反模式某类分析应该按什么框架展开。references 是按需加载的不是常驻上下文。比如需求分析 skill 可以有references/ ambiguity-taxonomy.md non-goals-template.md acceptance-criteria-examples.md模型只有在做需求分析时才读这些内容。三rules硬约束rules 回答什么必须遵守什么绝对不能做哪些路径归哪个角色哪些检查必须跑哪些风险必须人工确认。rules 不应该被 skill 复制。它应该通过路径、角色或全局启动自动挂载。我通常把 rules 分成三类全局规则任何任务都必须遵守比如不得修改 harness、不得跳过安全门禁、不得执行破坏性操作。路径规则进入某些目录自动加载比如ios/**、android/**、backend/**各有自己的约束。角色规则某个 Agent 被派发时自动加载比如评审者必须加载安全、性能、规范检查清单。这样做的好处是规则只有一个权威源。skill 只引用规则不复制规则。四docs长期知识和决策记录docs 回答为什么系统是这样设计的某个架构决策的背景是什么历史上踩过哪些坑某个模块的长期演进方向是什么。docs 不是垃圾桶。不能什么都往里面扔。有一个纪律每条长期知识都必须有消费方。也就是说docs 里的每篇文档都应该被某个 skill、rule 或角色明确引用。如果一篇 docs 没有消费方它就是孤儿知识。它可能写得很好但没有 Agent 会读它它变了也不会触发任何流程变化。时间久了它会变成“看起来像知识实际上没人消费”的过期说明。所以新增 docs 时我会同时写清楚这篇文档被哪个 skill 使用在哪一步使用不读它会导致什么风险。知识进入系统不是因为它被写下来了而是因为它被某个执行路径消费了。六、script-backed skill确定性的事不要让模型自由发挥复杂任务里有些事情适合让模型判断比如需求拆解、方案权衡、风险总结。但也有很多事情不适合让模型自由发挥比如校验 JSON schema检查文件是否存在扫描 forbidden path生成目录索引运行固定测试命令比对契约字段检查入口文件是否由模板生成收集日志并压缩摘要。凡是有唯一正确做法的事情就应该写成脚本。这类 skill 我叫 script-backed skill。它的价值不是“让 AI 会写脚本”而是反过来用脚本缩小 AI 的自由发挥空间。比如阶段状态文件必须满足这个结构{ task_id: string, phase: architecture, status: pass, owner: architect, evidence: [docs/adr/0012-contract.md], next: implementation }不要让模型每次自己想字段名。写一个validate_state.py所有阶段都用它校验。字段不对就是不通过。脚本目录一般放在 skill 下面skills/feature-delivery/scripts/ validate_state.py check_gate_outputs.py collect_logs.sh我对脚本有几条硬要求优先使用标准库和 POSIX shell少引外部依赖。所有输入输出格式要写清楚。写状态文件必须原子写入避免中途失败留下半截文件。并发写入要加锁。命令包装器只能调用配置里声明过的入口不能让模型临时拼危险命令。完整日志落盘主会话只回传摘要。新增脚本必须配测试。修改流程脚本必须跑回归。脚本失败时要返回结构化错误而不是只吐一屏日志。脚本不是为了显得“工程化”。它的意义是把可判定的部分钉死。让模型处理开放问题。让脚本处理确定问题。让 gate 判断两者的组合结果能不能进入下一阶段。这才是稳定的分工。七、skill 要分层编排层、阶段层、原子层只把 skill 拆成很多目录还不够。复杂系统里skill 之间也要分层。我一般分三层编排层 orchestrator阶段层 phase原子层 atom。这三层职责不能混。一编排层维护状态机不做具体活编排层通常只有少数几个 skill。它负责读取任务入口建立状态文件判断当前阶段派发子 Agent检查阶段产物推进或回退状态生成最终收口报告。它不写业务代码不做架构细节不直接补测试。它像流水线控制器而不是流水线上的工人。二阶段层负责一个交付阶段阶段层对应交付链路里的每一段。比如需求分析技术设计实现代码评审测试联调发布准备复盘沉淀。每个阶段都必须有明确的输入、输出和 gate。阶段最重要的不是“做事”而是“给出可审计结论”。我要求每个阶段结束时都输出四态之一pass通过有证据可以进入下一阶段。blocked卡住有原因、有 owner、有回退路径。not_required本阶段对当前任务不适用说明为什么。risk_accepted有问题但已被明确接受必须附接受人、原因和范围。这四态很重要。很多系统只有“完成 / 未完成”不够用。比如一个模块根本不渲染 UI那么 UI 还原阶段不应该失败也不应该假装完成而应该输出not_required。再比如缺少必要设计稿UI 实现者不应该凭感觉调到“差不多”而应该输出blocked把问题退回上游。再比如测试环境临时不可用但业务方明确接受本次只做静态检查那不能写pass应该写risk_accepted并记录谁接受了这个风险、接受到什么范围。gate 的意义是防止系统把“做过了”伪装成“做对了”。三原子层只做一件确定的事原子层是最底下的能力。它可以是解析需求表格生成 ADR 编号校验状态文件收集构建日志检查目录写入范围扫描 TODO比对 API 字段提取错误栈。原子 skill 有几条纪律只做一件事不编排其他 skill不发明命令不扩大范围输入输出稳定最好可由脚本兜底可以被多个阶段复用。原子层最常变但每次只影响一个点。阶段层中等频率变化影响一段流程。编排层最少变一变就是全局。这就是分层的原因。如果把三层混在一起一个小脚本变化可能影响整条工作流一个阶段门禁变化可能被实现者绕过一个原子能力失败可能让编排层直接失控。分层之后每个能力都可以独立路由、独立测试、独立替换。八、用 manifest 管住整张 skill 图当 skill 多起来之后光靠目录结构不够。你需要一个机器可读的清单文件作为整套 skill 图的单一事实来源。一manifest我通常会建一个 manifest比如skills: feature-delivery: layer: orchestrator execution: model description: 适用复杂业务需求端到端交付。 不适用单文件小修、纯问答。 典型触发语实现这个需求、完成这个功能、跨端改造。 inputs: - requirement_doc - scope - acceptance_criteria outputs: - final_report - phase_states tools: - task_dispatch - state_validator risk: high human_review: before_release architecture-design: layer: phase execution: model description: 适用需要技术设计、跨端契约、ADR 的任务。 不适用已有明确设计且只需机械实现的任务。 典型触发语设计方案、统一契约、ADR。 inputs: - structured_requirement outputs: - adr - contract - architecture_gate risk: medium validate-state: layer: atom execution: script script: skills/feature-delivery/scripts/validate_state.py description: 适用校验阶段状态文件 schema。 不适用判断业务方案是否合理。 典型触发语校验 state、检查 gate 输出。 inputs: - state_json outputs: - validation_result risk: low二三种 edge声明边除了节点还要声明边。我会用三种 edge。1. handoff阶段流转表示一个阶段结束后控制权交给谁。比如edges: - type: handoff from: requirement-analysis to: architecture-design condition: requirement_gate.passhandoff 只能由编排者驱动不能让阶段自己随便跳。2. dynamic_load按任务动态加载能力表示当前任务满足某种条件时才把某个能力加载进子 Agent 上下文。比如- type: dynamic_load from: implementation to: ios-implementation condition: paths.include(ios/**)这可以避免所有子 Agent 一启动就背全量知识。iOS 实现者只读 iOS 相关规则Android 实现者只读 Android 相关规则。复杂任务最怕“所有知识都加载”。上下文越多不代表越聪明有时只是噪音越多。3. semantic证据依赖表示某一步的输出不能直接当结论只能作为下游判断的输入。比如- type: semantic from: candidate-discovery to: evidence-confirmation meaning: candidates_are_not_evidence这条边很重要。很多 AI 工作流会把“发现候选”误当成“确认事实”。比如搜索到一个可能相关的文件就直接改看到一个相似 API就当成参考实现扫到一个关键词就当成证据。semantic edge 的作用是把这种语义关系写清楚候选不是证据假设不是结论设计稿不是实现测试通过不是无风险日志摘要不是完整日志风险记录不是风险接受。这些话写在人类文档里没用必须落到流程图里成为下游 gate 的检查条件。九、复杂任务 spec 必须设计失败路径很多 spec 只写 happy path。需求分析之后做设计设计之后做实现实现之后做评审评审之后做测试测试之后联调最后总结。这不是复杂任务 spec只是流程图。真正的复杂任务 spec一定要写失败路径。每个阶段都应该回答缺输入怎么办产物不合格怎么办测试跑不起来怎么办跨端结果不一致怎么办规则冲突怎么办子 Agent 超出写入范围怎么办需要人工决策时记录什么可以继续推进的非致命问题怎么处理不能继续时怎么回退。比如架构阶段 blocked不能直接进入实现。它应该输出{ status: blocked, owner: product, reason: 缺少错误态交互定义, evidence: [requirements.md#L42-L56], rollback_path: 回到 requirement-analysis 补充错误态验收标准, next: await_input }比如测试阶段失败也不应该只写“测试失败”。应该写{ status: blocked, owner: web-implementation-agent, reason: checkout empty state snapshot mismatch, evidence: [logs/test-web-2026-06-08.txt], rollback_path: 返回 web implementation 修复 UI 状态分支, next: implementation:web }复杂任务能不能稳定跑不取决于 happy path 多顺而取决于失败时能不能落到一个明确位置。失败不可怕。失败后不知道谁负责、证据在哪、下一步去哪才可怕。十、Spec 里最容易缺的东西产物契约很多团队写 spec 时会写流程、角色、规则但漏掉最关键的一件事每个阶段到底产出什么。没有产物契约系统就会变成“看起来做了很多事”但没有东西可以复查。需求分析阶段不能只说“理解需求”要产出结构化需求。架构阶段不能只说“完成设计”要产出 ADR 和契约。实现阶段不能只说“代码已改”要列出改动路径和对应需求点。评审阶段不能只说“看起来没问题”要给检查项和证据。测试阶段不能只说“跑了测试”要给命令、结果、日志和未覆盖项。联调阶段不能只说“验证通过”要给环境、版本、路径和观察结果。一个阶段的产物契约至少包括文件位置格式必须字段证据要求通过条件失败时的输出格式。比如代码评审阶段的输出可以规定为review_report.md 必须包含 - scope审查范围 - changed_files涉及文件 - checks安全、性能、规范、契约、测试覆盖 - findings每个问题的 severity、owner、evidence、suggested_fix - verdictpass / blocked / risk_accepted有了产物契约编排者才能检查产物是否存在、字段是否齐全、证据是否足够。否则“完成”只是 Agent 自己的一句话。复杂 spec 的目标是把“我觉得做完了”变成“产物满足契约所以可以进入下一步”。十一、写复杂 spec 的一个可复用模板如果把上面的内容压缩成一个落地模板我会这样写。1. 任务类型这个 spec 管什么任务不管什么任务。适用 - 多阶段交付任务 - 多角色协作任务 - 跨端或跨模块改造 - 需要产物追踪和门禁验证的任务 不适用 - 单文件机械修改 - 纯问答 - 不需要状态追踪的小修2. 角色和权限谁能做什么不能做什么。orchestrator - 能派发、收口、状态推进、门禁检查 - 不能直接改生产代码 architect - 能写 ADR、契约、技术方案 - 不能写端侧实现代码 platform implementer - 能修改对应平台路径 - 不能修改其他平台路径或公共契约 reviewer - 能审查、提出 finding - 不能直接修复自己发现的问题除非另行派发为实现者3. 路径到角色映射docs/adr/** - architect ios/** - ios-implementer android/** - android-implementer web/** - web-implementer backend/** - backend-implementer rules/** - spec-maintainer skills/** - spec-maintainer4. 阶段状态机intake - requirement_analysis - architecture_design - implementation - review - test - integration - final_report每个阶段必须输出status: pass | blocked | not_required | risk_accepted owner: evidence: next: reason:5. 门禁规则没有结构化需求不得进入架构。 没有统一契约不得开始跨端实现。 实现者不得修改未授权路径。 评审不得由同一个实现者完成。 测试失败不得标记 pass。 risk_accepted 必须有人类接受记录。6. 知识装载规则入口只加载索引和硬边界。 阶段 skill 只加载当前阶段 references。 路径 rule 按写入路径自动加载。 角色 rule 按派发角色自动加载。 docs 必须被 skill、rule 或 agent 显式引用。7. 脚本规则确定性检查必须优先脚本化。 脚本输入输出必须稳定。 状态写入必须原子化。 并发写入必须加锁。 日志必须落盘。 主会话只返回摘要。 脚本新增或修改必须有测试。8. 失败处理info_gap记录后继续。 local_failure记录 owner、evidence、retry path继续不依赖它的任务。 gate_blocker停止当前阶段回退到指定 owner。 risk_decision请求人工决策。9. 最终报告最终报告至少包含完成了什么没完成什么哪些阶段通过哪些阶段 blocked哪些风险被接受关键证据位置后续动作可沉淀成 rule、script、skill 的模式。这个模板不复杂但它逼你把复杂任务最关键的边界都说清楚。十二、记住一句话复杂 spec 的核心不是“写更长”而是“拆得更准”复杂任务的 spec核心不是写一段更长的提示词。它是三件资产的组合。第一件是工作流编排谁负责推进状态谁负责执行什么时候能进入下一阶段什么时候必须回退。第二件是 skill 组织入口要薄references 按需加载script 兜住确定性skill 分成编排层、阶段层、原子层。第三件是知识库建连rules 是硬约束docs 是长期知识references 是当前 skill 的长内容每条知识都只有一个权威位置并且必须有明确消费方。这三件合起来复杂任务才从“某次对话里的临场发挥”变成“可以复用、可以审计、可以测试、可以演进的工程系统”。回头看复杂 spec 的本质仍然是克制。不让一个 Agent 什么都做。不让入口文件什么都写。不让规则到处复制。不让知识无消费方。不让阶段没有门禁。不让失败没有回退。不让模型在确定性问题上自由发挥。每加一个能力都要说清楚它的位置、职责、输入、输出、规则、证据和失败路径。这才是复杂任务 spec 的价值。它不是让 AI 看起来更强。它是让 AI 的能力被放进一个可控的系统里。写好 spec只解决了“组织得清不清楚”。但还有一个更难的问题每个 skill 到底好不好用。路由描述写得漂亮模型就一定会在正确时候召唤它吗阶段声称会输出 gate它真的每次都输出了吗references 拆得很细模型真的会在该读的时候读吗script-backed skill 看起来确定它的失败路径真的稳定吗这些不能靠感觉要靠测试。下一篇可以继续讲怎么测一个 skill 到底好不好用。重点不是让另一个大模型来打分而是做三件事。第一做对照。同一道任务带 skill 跑一遍不带 skill 跑一遍看差异到底是不是 skill 带来的。第二存结果。模型每次的真实输出都落成文件提交进代码库后续可以复查、比较和回归。第三用确定性检查项。不要轻易让另一个模型当裁判。裁判本身也不稳定。能写死的检查项就写死能脚本化的判断就脚本化。复杂任务 spec 让系统有结构。skill eval 让结构真的有效。这两件事合起来AI 工程才开始从“能跑一次”走向“能持续演进”。参考文章AnthropicBuilding Effective Agents这篇非常适合作为“workflow 和 agent 要区分、复杂系统优先简单可组合模式”的理论来源。文章明确区分了 predefined workflows 和更自主的 agents。https://www.anthropic.com/research/building-effective-agentsClaude Code DocsHow Claude remembers your project适合支撑你文中关于CLAUDE.md、项目记忆、入口文件、规则与工作流说明的部分。官方文档说明了CLAUDE.md用于存放项目指令、编码规范、工作流和架构信息。How Claude remembers your project - Claude Code DocsOpenAI Agents SDKAgents 指南适合支撑“handoffs、guardrails、human review、observability、state”这些概念。官方文档把复杂 agent workflow 拆成运行、编排、交接、护栏、人类复核、状态和可观测性等模块。https://developers.openai.com/api/docs/guides/agents12-Factor Agents这篇适合支撑你文中“确定性代码 LLM 能力分工”“上下文管理”“责任边界”“生产级 Agent 架构”的部分。它强调构建可用于生产环境的 LLM-powered software而不是只靠 prompt。GitHub - humanlayer/12-factor-agents: What are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers? · GitHubDeepWiki12-Factor Agents 解读这是对 12-Factor Agents 的结构化解读适合读者快速理解其中关于 deterministic code、LLM capabilities、context management、responsibility boundaries 的关系。humanlayer/12-factor-agents | DeepWikiOn the Use of Agentic Coding Manifests: An Empirical Study of Claude Code这篇论文很适合支撑你文中关于CLAUDE.md / AGENTS.md / manifest的观点。它研究了 242 个仓库中的 253 个 Claude.md 文件分析 agent manifests 的常见结构和内容。https://arxiv.org/abs/2509.14744Efficient Agents: Building Effective Agents While Reducing Cost适合支撑“不是 Agent 越多越好”“多 Agent 要有节制”“复杂度要和任务匹配”的观点。论文研究了 agent 系统里的效率—效果权衡以及模块复杂度的边际收益问题。[2508.02694] Efficient Agents: Building Effective Agents While Reducing CostOpenAI Agents SDKTracing适合支撑你文中“每一步要可追踪、工具调用、handoff、guardrail、custom events 都要能观测”的部分。文档说明 tracing 会记录 agent run 中的 LLM generation、tool call、handoff、guardrail 和自定义事件。Tracing | OpenAI Agents SDK - OpenAI 教程How Do AI Agents Do Human Work? Comparing AI and Human Workflows Across Diverse Occupations适合支撑“Agent 容易伪造/误用工具、质量需要外部验证、不能只相信模型自述完成”的论点。论文比较了人类和 Agent 在多类工作中的流程差异并指出 Agent 有时会掩盖质量缺陷。[2510.22780] How Do AI Agents Do Human Work? Comparing AI and Human Workflows Across Diverse OccupationsSwarm Skills: A Portable, Self-Evolving Multi-Agent System Specification for Coordination Engineering这篇很贴合你文章里“skill 不只是单 Agent 能力还可以扩展为多 Agent 协作协议”的方向。论文提出 Swarm Skills把多 Agent 工作流中的 roles、workflows、execution bounds 和语义结构变成可移植规格。[2605.10052] Swarm Skills: A Portable, Self-Evolving Multi-Agent System Specification for Coordination Engineering延伸阅读Anthropic,Building Effective Agents关于 workflow 与 agent 的工程区分以及简单可组合模式为何更可靠。Claude Code Docs,How Claude remembers your project关于CLAUDE.md、项目记忆和入口规则的官方说明。OpenAI Agents SDK Docs关于 handoffs、guardrails、human review、state 与 observability 的工程化参考。HumanLayer,12-Factor Agents关于生产级 Agent 系统中确定性代码、上下文管理和责任边界的原则。On the Use of Agentic Coding Manifests关于真实项目中 Claude.md / agent manifest 写法的实证研究。Efficient Agents关于 Agent 系统复杂度、成本和效果权衡的研究。Swarm Skills关于把多 Agent 协作协议规格化、可移植化的研究方向。