Imported from weidwonder/agentic-principle (agentic-principle/SKILL.md). Install upstream with npx skills add weidwonder/agentic-principle --skill agentic-principle. Copyright stays with the author.

Agentic 设计与编排原则

把一个业务意图，转成一份经过用户确认的 Agentic 方案：场景选型、Agent 与工具边界、提示词、运行时契约、上下文与并发预算、信息传递链路，并据此实现或评审已有实现。

非目标：不替代具体业务功能的编码实现；不为"看起来更智能"而把可程序化的流程 Agent 化；不审查 Skill 本身的写法质量（交 skill-principle）。

本文件：§四条入口 → §工作流（步骤 0→4，其中步骤 2.5 是 D1–D13 逐维检查）→ §基础原则 → §各场景必确认项 → §约束 → §失败处理 → §按需引用 → §验证清单（清单本体在 references/delivery/verification.md）。

四条入口

评审时先抛开现有实现独立设计，是为了避免被既有实现锚定，错过场景选型层面的问题。评审的审计模式判定、逐维评估、证据状态与矛盾检查都在 references/modes/review-mode.md，新建场景不必读。

增量入口有退回条件：新增能力若要求改编排模式、提高并发或上下文上限、或让某个 Agent 的职责跨到第 3 个不相干领域，退回「新建」走完整流程。判定细则见 references/modes/incremental.md §一。不确定时按新建走——增量入口省的是重复论证，不是省该做的判断。

排障入口不做全面体检：它针对一次具体异常找根因，产出是「归因 + 处置 + 回归用例」，不是评审报告。若根因指向某个维度压根没做，说明这不是偶发故障而是架构缺陷——升级为「评审」或「新建」，不要就地打补丁。判定细则见 references/modes/debug-mode.md §一。

接手既有设计文档时：先看文档 frontmatter 的 skillVersion。与本 skill 当前版本（见 frontmatter metadata.version）不一致时，按小节标题名定位，不要按编号——模板的章节编号会随版本变化，编号对齐会写错位置。差异较大时告知用户，并询问是否按新模板补齐缺失小节。

工作流

步骤 0 — 理解意图与边界

产出：产品/功能愿景一句话、用户是谁、成功标准、明确的不做什么。 信息不足时提问，不要用假设填空。

步骤 1 — 场景分类

先抛开当前实现，按下表自上而下判定，第一个命中的即是答案：

相邻场景最容易判错，用下表切边界：

命中「完全程序过程」即退出本 skill，转常规程序开发。

混合是常态：程序不能覆盖 100% 场景时，不要强行全程序，拆成「程序做确定部分 + Agent 做语义部分」——外层编排确定、个别步骤交给 Agent 处理歧义，是生产系统最常见的真实形态。

步骤 2 — 设计

按 §基础原则 + §各场景必确认项 形成设计草案。此阶段只在会话内形成草案，不落盘、不写实现代码。

完成判据：草案已能填满 references/delivery/design-doc-template.md §二 骨架的这几节——场景分类结论、角色与职责、Agent 设计、信息传递链路、上下文、注意力与并发预算。逐维检查产出的各张清单在步骤 2.5 后回填。填不满的部分即是待确认项，带进步骤 3。

步骤 2.5 — 逐维检查（强制，由你执行）

这是检查动作，不是提问动作。按下表逐维执行：先判适用条件，不适用的标 N/A 并写明理由，适用的逐个对象核对红线，触线项当场给处置。

评审入口下本步骤走两遍，对象不同：这里检查的是你自己刚做的独立设计（产出缺口清单与处置），references/modes/review-mode.md §三 再用同一张表检查现有实现（产出 pass/partial/fail/unknown/N/A；D13 另有专属的 not-adopted，且不用 partial，见 references/runtime/retrospective.md §八）。两份产出都保留，差异写进设计文档的「与现有实现的差异」一节。

执行纪律（对每个适用维度一律成立）：

1. 逐个对象，不允许抽样。D1/D2/D3/D8/D13 逐个 Agent，D4 逐个工具/MCP，D5 逐个 Agent 且逐个工具，D10 逐条 handoff，D11 逐个节点，D12 逐个环节核对切片覆盖（调试模式开关本身按机制看，通常只有一处实现）。D6/D7/D9 按机制看——loop、预算、熔断通常全系统只有一处实现，按对象分批只会让多个子代理重复读同一段代码。
2. 实际扫描，不用推测替代。要读现有的 Skill、提示词、文档、样例数据、代码，会花时间和 token，不要省略。
3. 规模分流：对象数超过 6 个时，分批派并行子代理执行扫描，每个子代理回报结构化清单，你只做汇总与跨对象的一致性判断。子代理数受已确认的并发上限约束。不这样做，扫描会因上下文压力退化成抽样——而抽样正是这一步禁止的。
4. 每维产出一张清单，格式统一：对象 → 命中哪条红线 → 证据 → 处置 → 是否需用户确认。全部带进步骤 3。
5. 处置若改变 Agent 数量、职责边界、模型档位或工具授权 → 必须列入步骤 3 交用户确认；纯放置层级的调整直接体现在草案里即可。
6. 冲突时完备性优先：D2 的减负处置不得删除 D1 认定为必需的规则，改用下沉（挪进 Skill / 文件留索引）或拆分职责实现。D4 的落盘处置不得变成"不给了"，改检索方式。

D1 信息完备性的展开（此维度无独立 reference，动作写在这里）：

1. 列出方案中每一个 Agent 节点。
2. 对每个节点，核对它在运行时能拿到的信息（系统提示词 + 首轮 User Prompt + 可读取的 Skill/文件 + 上游传来的数据）是否足以支撑它要做的每一项业务判断。
3. 逐条追问：这个判断依据哪条规则？规则写在哪？Agent 读得到吗？边界情况（空输入、格式不符、多义、超出枚举范围）有没有对应规则？
4. 另查一遍有没有用启发式规则顶替真实业务规则（判据见 §程序化与启发式的边界）。这类顶替在缺口清单里要单列，因为它比"缺规则"更隐蔽——表面上有规则，实际是编的。

产出：缺口清单（哪个 Agent、缺哪条规则、影响哪个判断）。缺口带进步骤 3 交用户补充，不得由你虚构业务规则填补。

步骤 3 — 用户核对

双轨制：

1. 结构化提问：把关键决策点逐批向用户确认，每批不超过 4 项，优先使用宿主提供的结构化选项提问能力。完整提问批次见 references/delivery/design-doc-template.md §一（权威版本）；各场景的额外差异项见 §各场景必确认项。步骤 2.5 各维度的清单在此一并交用户。
2. 设计文档终审：确认后写出设计文档，含流程图，交用户终审。
   • 路径：目标项目 docs/specs/YYYY-MM-DD-<short-desc>.md，并同步更新 docs/index.md。
   • 模板与流程图写法见 references/delivery/design-doc-template.md。

用户明确签字确认后才进入步骤 4。除非用户明确要求跳过核对——跳过时须把全部关键假设写入设计文档的「确认记录」一节，并一句话告知用户"已按以下假设推进"。

步骤 4 — 实现或比对

• 无实现：按项目既定的分工派发实现。若项目约定由外部编码代理执行，你负责任务书、验收与合并，不亲自编码。实现完成后按 §验证清单 亲自验证，不采信代理的自述。每个 Agent 按 references/prompt/agent-construction.md §四 实跑测试；多节点场景另按 references/delivery/testing.md 建步骤级用例逐步骤跑通。步骤 2.5 中触线的维度，其处置都要有对应的实跑验证：审批闸门实跑不通过路径确认 fail-closed，最大返回用例实测 token 数，loop 上限实跑撞线确认真的停得住，有副作用的重试实跑重复投递确认幂等。
• 有实现：按 references/modes/review-mode.md 执行评审序列——判定审计模式 → 按 D1–D13 逐维评估并给证据状态 → 矛盾检查 → 回填设计文档的「与现有实现的差异」一节。该文件同时给出每类问题的证据要求与不得径自改动实现的边界。

基础原则

复杂度阶梯

从最简方案起步，只有在可证明改善结果时才升级复杂度。每升一级都要多付延迟、成本与不确定性：

1. 单次 LLM 调用 + 好的提示词
2. ＋检索／in-context 示例
3. ＋工具调用（单 Agentic）
4. ＋程序编排（Agentic 工作流）
5. ＋动态拆解与子代理（父子 Agentic）

与步骤 1 的场景分类互为表里：分类表给出场景的上限，这条阶梯要求你在该上限内取最低可行档。

同一条阶梯适用于单个能力：不要因为"Agent 通常都有"就配上记忆、RAG、规划模块、子代理或某个框架。每一项都要能说出它解决了哪个具体问题。

提示词质量（适用于系统、用户、工具描述、工具返回全部提示词）

优先级从高到低：

1. 不遗漏信息、不提供错误信息（最重要）
2. 尽可能低冗余
3. 尽可能结构化
4. 无错别字

程序化与启发式的边界

能程序化的过程尽量程序化——但"能程序化"指的是规则确定的过程：格式转换、字段映射、数值计算、状态机流转、权限判定、计数与硬上限。这类逻辑放进程序，比放进提示词更可靠、更便宜、更可测。

靠关键词、正则、阈值去猜语义意图的启发式规则不算程序化。那是把语义判断伪装成程序：它在样例上看着能跑，遇到没见过的表述就无声地判错，而且错得理直气壮——下游拿不到任何"我不确定"的信号。

因此：

• 默认不引入启发式规则。 需要语义判断的地方就交给 Agent 判断。
• 确需引入的，必须先给出覆盖率论证：这条规则至少能覆盖 75% 的真实场景，并说明剩余部分怎么兜底（转 Agent 判断 / 转人工 / 显式报"无法判定"）。
• 覆盖率论证与规则本身都要在步骤 3 取得用户确认，连同覆盖率数字与未覆盖部分的兜底一起写进设计文档。
• 覆盖率说不清、举不出反例集的，说明这就该由 Agent 做语义判断，不要硬写规则。

启发式用于「缩小搜索范围」可以，用于「下判定」不行。 用正则先筛出可疑位置再逐个读，是合理的加速；用正则直接判定"这个实现没有做恢复"，是错误的。前者的假阳性只浪费一点时间，后者的假阴性直接写进结论。这条同样约束本 skill 自带的扫描脚本——见 scripts/scan_agent.py 的使用纪律。

程序若不能覆盖 100% 场景，拆成「Agent + 程序协作」，而不是靠加启发式规则硬把覆盖率补到 100%。

Agent 构建

• Agent 必须设置系统提示词，言简意赅、极度精简且不遗漏重要方面。
• 六要素，缺一不可：角色 → 核心职责 → 处理流程 → 质量标准 → 输出格式 → 边界情况。各要素详略按场景灵活定义，但不得整项缺失。
• 增益提示块：从 references/prompt/system-prompt-blocks.md 摘取适用块，追加到系统提示词尾部。其中「开工前自检」块必选；其余按该文件的适用条件矩阵，只摘条件命中的块。
• 透明性：Agent 的关键决策过程要对使用者可见（显式的计划步骤、选择理由），不要做成黑盒。
• 六要素模板、写作细则、角色设定、SOP 入提示词的条件、上下文分层与注意力五抓手、模型档位选择、工具最小能力集，全部见 references/prompt/agent-construction.md。
• 工具与 MCP 的设计规范（描述写法、防呆、隐式规则显式化、封装形态选择）见 references/tools/tool-design.md。

各场景必确认项

完整提问批次见 references/delivery/design-doc-template.md §一。本节只列各场景额外的差异项。

通用（所有场景）

提问的具体问题只在 references/delivery/design-doc-template.md §一 维护。下表是维度 → 批次的映射，用来核对没有漏问（按批次标题定位，不要按编号——编号会随模板版本变化）：

三条不可省略：上下文上限与并发上限要问到实数，不接受"够用就行"；单 Agent Chat 场景跳过「工具返回体量」「运行时边界与恢复」两批；「授权与安全边界」批不跳过，只问其中第 3、4 项（不可信输入来源、输出侧具名检查与判定码）——用户输入本身就是不可信来源，输出侧检查照样要有；每个适用维度都要有对应批次被问过，标 N/A 的维度在设计文档写明理由即可，不必提问。

单 Agent Chat 应用

无额外项。经验与内容尽可能集成进系统提示词（无外部工具可依赖）。

单 Agentic 应用

1. 工具、MCP 清单——通常给完成任务的最小集合。
2. Skill 范围（如有）——同样取最小范围。
3. 系统提示词内容对齐——必须取得用户确认。建议在系统提示词所在代码/文档中记录最近一次确认日期；若时间过久且相关业务逻辑已更新，需再次与用户确认其可用性。

父子 Agentic 应用

按 D10 逐项走 references/multi-agent/multi-agent.md，其中这几项必须由用户拍板：

1. 子 Agent 系统提示词是父 Agent 实时构建、固定单一，还是固定若干个按需分配？由用户决定并说明其顾虑。
2. 子 Agent 数量上限是多少？是否超过 LLM 并发上限？拆分粒度与并发数各是多少？
3. 每个子 Agent 的模型档位逐个确认（此场景不设默认档位）。
4. 子 Agent 产出的信任处理：父 Agent 采纳前是否做筛查、子 Agent 读了哪些不可信来源。
5. 对子 Agent 再走一遍「单 Agentic 应用」的 3 项确认。

Agentic 工作流

先选编排模式，再谈具体步骤：

选中 Orchestrator-Workers 意味着该工作流内部嵌套了父子 Agentic，需同时走完 §父子 Agentic 应用 的确认项。Parallelization 与 Orchestrator-Workers 的分界线与步骤 1 相同：子任务是否预定义。

其余确认项：

1. 整体输入、输出的格式与形态。产出较长或由多步骤共同填充时，先定产物模板与分区表（见 references/delivery/long-artifact.md），再排步骤——这是本场景的默认编排姿势。
2. SOP 详细设计 + 流程图确认：按工作先后次序描述，每一步标明由程序还是 Agent 执行；Agent 节点的工作流程、分支条件；并行部分如何并行。这个过程必须用业务语言与用户沟通。
3. 信息连续性：确认程序与 Agent 之间每一步的沟通方式（文件 / 结构体 / Prompt），确保传递准确、无遗漏、无冗余。注意：工具通常不作为流程环节，它是 Agent 可选用的操作。

完全程序过程

无需语义判断即可完成 → 转程序开发模式，不继续本 skill。

约束

带 [Dn] 标记的约束对应步骤 2.5 的同名维度，细则见维度矩阵表最后一列；无标记的是流程纪律，不依附任何维度。所有约束一律生效，标记只用于反查细则。

排障入口例外：它不走步骤 0→4，因此本节中以设计流程为前提的约束——要求走步骤 2.5 逐维、要求产出设计文档与索引、要求步骤 3 签字的那几条——对它不适用；它按 references/modes/debug-mode.md §七 的收口四件事结账。其余约束照常生效，§绝对禁止 一律生效，不分入口。排障同样要补回归用例、同样不得用启发式下判定、同样不得让 P0 被其他维度的优点抵消。

1. 除非用户明确要求跳过核对，否则步骤 3 未取得确认不得进入实现；跳过时须把关键假设写入设计文档的「确认记录」一节并告知用户。
2. 评审已有实现时，先独立出设计再比对，不得被现有实现锚定。
3. [D1–D13]（新建 / 增量 / 评审入口）步骤 2.5 的每个维度都要有结论：适用的给清单，不适用的标 N/A 并写明理由。不允许跳过不写——沉默不等于 N/A。
4. [D2] 不把 references/prompt/system-prompt-blocks.md 整块复制进系统提示词——只摘条件命中的块。
5. 设计文档写入 docs/specs/YYYY-MM-DD-<short-desc>.md 并同步 docs/index.md（若项目另有文档治理规则，以项目规则为准）。
6. 场景判定命中「完全程序过程」时如实告知用户，不为了用上 Agent 而 Agent 化。
7. [D1/D2] 注意力减负不得删除 Agent 做判断必需的规则；下沉层级与拆分职责是首选手段。删除真正冗余的内容（重复、模型已知的常识、与本 Agent 职责无关的段落）不受此限。
8. [D2] 评审场景发现的注意力问题，须先与用户确认成立，再提改进建议；不得直接改动现有实现。
9. [D3] 命中长产物判据的交付物，模板由程序预建、完整性由程序校验，不以 Agent 自评替代程序校验（自检仍是好习惯，只是不能当验收依据）。
10. [D11] 多节点场景不得只做端到端测试；每个步骤都要有可单独运行的用例。评测 Agent 未经人工标注样本校准，不得作为验收依据。
11. [D5] 每个工具/动作都要标自主级别；high-impact-automation 必须有确定性代码实现的具名审批闸门，提示词里的"执行前请先确认"不算闸门。
12. 走增量入口时，平台缺口清单必须逐条对照并处置（补 / 登记为风险 / 记未踩中），不得以"平台一直这样"默认继承。
13. [D4] 直接进入模型上下文的工具/MCP 都要按最坏情况估算最大返回；估算或实测 > 10k token 而无兜底的，不得在未告知用户的情况下交付——用户明确接受该风险的，记入设计文档「确认记录」后可放行。
14. [D1] 引入任何启发式规则都要有覆盖率论证并取得用户确认；覆盖率低于 75% 或说不清的，改由 Agent 做语义判断。
15. [D5/D7/D8] 一个 P0 级缺陷不得被其他维度的优点抵消。 无论整体评价多好，触到 §绝对禁止 或 D5/D7/D8 红线的项都要单独列在结论最前面，不做加权平均、不写"总体良好但……"。
16. 排障时拿不到对话记录，第一动作是把记录补上并复现，不是继续猜。细则见 references/modes/debug-mode.md §二。
17. [D12] 每个 Agentic 应用都要有可开启的调试模式：开启后每个环节留完整输入与输出切片，关闭时仍留骨架（step 标识、时间、体量、状态码），且能只回放某一个环节。改代码才能观察不算做到；有副作用的环节回放必须干跑或沙箱。
18. [D13] 任务执行期间用户无法插话的 Agent 应当有可开启的复盘反馈：任务终止时与上下文压缩时各在对话副本上追加一段固定的复盘提问，收四类外部偏误。没有它不判缺陷（评审记 not-adopted 并问用户要不要补），但它的产出只是线索——不得当结论采信或写成 finding、不得据以改提示词、不得写回主任务对话或进父 Agent 上下文、不得写入持久记忆、不得让复盘失败阻断主任务。

绝对禁止

• 绝对禁止将真实凭证、密钥、客户数据写入设计文档或提示词示例——一律使用占位符。设计文档会进入 docs/ 并可能入库，提示词会分发给多个 Agent。
• 绝对禁止设计不设数量上限的子 Agent 派发，或上限高于已确认的 LLM 并发额度。
• 绝对禁止以合理推测填补业务规则缺口：未经用户确认的业务规则（判定标准、阈值、枚举、优先级）不得写入 Agent 提示词或 Skill。编一套关键词表或阈值顶替真实业务规则，是这条禁令最常见的犯法形态。 取默认值推进设计决策不受此限（用户答"你定就行"时照常推进），但必须标注为假设并记入「确认记录」。
• 绝对禁止把不可信内容拼接进系统指令位置（系统提示词、工具描述、SOP 段落、评测 rubric）。
• 绝对禁止让检索结果在未按身份/租户过滤的情况下进入模型上下文，或让过滤条件来自模型传入的参数——违反即构成跨租户数据泄露，且输出侧过滤兜不住。
• 绝对禁止对超长返回做静默截断：砍掉尾部而不告知总量与获取剩余部分的方式，会让 Agent 把半截数据当全量用，且下游无从察觉。
• 绝对禁止安全检查或审批闸门 fail-open：检查逻辑异常、闸门服务不可用时，一律视为未通过，抑制输出走兜底，不得放行。
• 绝对禁止把模型自述当作动作已完成的证据：声称"已提交""已发送""已修复"必须由环境状态或工具返回证实。
• 绝对禁止让自建 loop 的终止只取决于模型自己说"我做完了"，且不设任何步数、时间或成本上限。
• 绝对禁止在没读过对话记录的情况下靠改提示词给异常止血——它掩盖根因、无法证伪，并让下一次同样的异常更难查。

失败处理

维度专属的症状与处置（产出被截断、上下文被工具打满、Agent 原地打转、重复扣款、越权检索、定位不到是哪一步坏了、增量撞上平台缺口……）写在各维度 reference 末尾的「常见症状」一节，随该维度一起加载（模板与清单类文件没有这一节）——按 §按需引用 的条件读到哪个维度，就带上它的症状表。

按需引用

构件类（设计或评审对应构件时读）：

• references/prompt/agent-construction.md：写系统提示词、定上下文分层与注意力方案、选模型档位、定工具授权、做交付前实跑测试。含六要素模板、写作细则、注意力五抓手、最小能力集、自主级别标注格式。
• references/prompt/system-prompt-blocks.md：写或改 Agent 系统提示词时读。含增益提示块全文与适用条件矩阵。
• references/tools/tool-design.md：设计工具/MCP/Skill 封装时读。含封装形态选择、描述规范、防呆设计、隐式规则显式化、启发式规则的覆盖率论证写法。
• references/tools/tool-output.md：D4 估工具返回体量时读，实现落盘兜底、写极端返回用例时也读。含估算换算、两条处置路径、落盘返回契约、常见超长源清单。
• references/multi-agent/multi-agent.md：D10，方案含 2 个以上 Agent 时读。含必要性判据与单 Agent 基线、拓扑与上下文共享、handoff 契约、评审者独立性、共享写入并发控制、并发与任务拆分。
• references/runtime/agent-loop.md：D6，自建 agent loop / harness 时读。含终止条件、四类上限、可恢复与可取消、异步系统的幂等与乱序。
• references/runtime/reliability.md：D7，有副作用动作或外部依赖时读。含错误四分类、退避、无进展检测、熔断、幂等键、部分状态回滚与对账。
• references/runtime/memory.md：D8，有持久记忆、RAG 或跨会话状态时读。含五类状态分离、写入判据、来源与时效、租户过滤、更正与删除。
• references/runtime/cost-and-cache.md：D9，上规模或有预算约束时读。含分项计量、各级预算、延迟分位、prompt cache 友好布局、上下文压缩保真契约。
• references/runtime/observability.md：D12，设计调试模式与切片、排障取证据、给 D11 造夹具时读。含开关四契约、每环节切片字段、单环节回放判据、脱敏与留存、与各维度的接缝。
• references/runtime/retrospective.md：D13，方案里有「任务执行期间用户无法插话」的 Agent 时读；评审判这一维、或想用复盘产出定位问题时也读。含适用条件、机制形态（副本分支 + 两个触发点）、复盘提问模板全文、四类分界、异常处置、红线清单、not-adopted 的判法。
• references/safety/safety.md：D5，定不可信输入与输出检查时读。含自主级别四档、闸门写法、信任分级表、判定码起步清单、fail-closed。

交付类：

• references/delivery/design-doc-template.md：进入步骤 3 时读。含完整提问批次（权威版本）、设计文档骨架、流程图写法。
• references/delivery/long-artifact.md：D3 命中长产物判据时，或实现阶段搭产物模板时读。含三步做法、分区划法、完整示例。
• references/delivery/testing.md：D11 与步骤 4 时读。含三层测试体系、步骤级用例写法、评测 Agent 与 rubric 构建、批量评测与门禁。
• references/delivery/verification.md：进入步骤 4 时必读。交付前的逐项确认清单，分设计期（逐维）、实现与验证期、交付期三段。

模式类：

• references/modes/review-mode.md：入口判定为「评审已有实现」时读。含审计模式判定、逐维评估与证据状态、矛盾检查、证据要求表、边界。
• references/modes/incremental.md：入口判定为「增量」时读。含入口判定与退回信号、继承声明、只 spec 增量、平台缺口清单。
• references/modes/debug-mode.md：入口判定为「排障」时读，实现验证或评审中撞见实际异常时也读。含对话记录的获取清单、骨架时间线降噪法、第一偏离点三分类、四层归因表（harness / 供应商 / 外部程序 / 设计）、收口与回归用例。

工具：

• scripts/scan_agent.py：评审陌生代码仓库时的可选加速器，产出线索与证据缺口。只产线索不产结论，输出不得直接写进评审报告，必须人工读过原码才能升格为 finding。用法：python3 <skill根目录>/scripts/scan_agent.py <目标路径> --format markdown，仅需 Python 3 标准库，无需安装。纪律见 references/modes/review-mode.md §八。其行为用例见同目录 test_scan_agent.py——改动扫描规则后必须重跑。

验证清单

交付前逐项确认，完整清单见 references/delivery/verification.md：设计期按 D1–D13 逐维核对（每维要么有清单、要么标 N/A 写明理由），实现期核对实跑证据（Agent 实跑、步骤级用例、极端返回、安全用例、运行时用例、越权检索、切片与回放实跑），交付期核对文档、skillVersion、索引与用户签字。

这份清单是必读的——它是"做到了没有"的唯一判据，不因为交付时间紧就跳过。

案例

三个骨架，说明一次完整走法长什么样。案例中的项目与数字均为示例。

案例 1 — 新建·中等规模：用户说"帮我做一个合同审阅功能，上传合同后出一份风险报告"。

步骤 1 判为 Agentic 工作流：审阅维度（合规、财务、法务）在设计期就能穷举，不需要运行时探查——与父子 Agentic 的分界线正在于此；编排模式选 Parallelization（三视角并行）。步骤 2 出草案。

步骤 2.5 十三维逐个过，一个都不留空：D1 扫描三个审阅 Agent，无缺口（评判标准来自用户提供的风控清单）；D2 三个 Agent 均未触线；D3 命中（报告约 15 页、结构固定）→ 定分区表，程序建模板、三区各填各区、程序校验占位符；D4 命中（合同解析工具对 200 页 PDF 返回约 18k token）→ 该平台改不了 loop，走工具侧分页 + 落盘；D5 标出"报告发送给客户"是 high-impact-automation → 闸门定为"法务复核 / 发送前 / 不通过则退回并通知"，实现位置 pipeline/gate_send.py；D6 标 N/A（用现成工作流引擎），但仍按 agent-loop §一 查了引擎默认的单节点超时与重试次数，确认 200 页 PDF 解析不会撞上；D7 适用——发送报告有副作用，幂等键按 reliability §五 的「业务实体 + 操作类型 + 请求批次」取"合同号 + 发送 + 报告版本"——三段缺一不可，少了操作类型，同一份报告的"发送"与"归档"就会撞键，网关超时先查投递状态再决定补发，重复发送登记进对账表；D8 标 N/A（无持久记忆与检索）；D9 标 N/A（内部低频使用）；D10 适用——三视角并行，与单 Agent 基线对比后确认省了约 2/3 墙钟时间，handoff 契约含验收标准与原始条款引用；D11 发现只有端到端测试 → 每个节点补夹具；D12 适用——调试模式定为请求头打标开启、生产默认关但骨架恒开，三个审阅 Agent 与合同解析工具各留输入输出切片，回放入口对"发送报告"这一步默认干跑，切片留存 30 天且写入时脱敏合同方名称；D13 适用——三个审阅 Agent 全程无人参与对话，各自在自己的对话副本上做任务终止时的复盘，预发默认开、生产按采样开，产出挂在同一次运行下当线索用，不直接写进报告。

步骤 3 问了 12 批（场景与边界、能力边界、授权与安全边界、资源上限、工具返回体量、运行时边界与恢复、多 Agent 协作、提示词对齐、注意力与分层、测试与评测、可观测与回放、复盘反馈）——每个适用维度都对上了一批；「信息缺口确认」因 D1 无缺口、「启发式规则」因方案中无此类规则，均在文档里记「已扫描、无」而非留空——记下来才说明查过。上下文与并发上限问到了实数（8 并发、200k 窗口）。用户改了一处：财务视角合并进合规——Agent 数量变了就要回炉（执行纪律第 5 条），于是复核了受影响的三项：分区表从三区改两区、D10 的基线对比重算（两路并行省约 1/2 而非 2/3）、D2 按新的两个 Agent 重核一遍。步骤 4 派实现，回来后亲自跑：闸门的不通过路径、200 页 PDF 的实测返回（落盘后 1.2k token）、重复投递确认只发一次、每个节点的边界输入。

案例 2 — 评审已上线系统：用户说"评审一下我们的客服 Agent"。

先不看代码，走 0→3 得出独立设计（否则会被现有结构锚定）——这一遍的步骤 2.5 逐维检查针对的是你自己的设计，产出的是缺口清单（例如：你的设计里退款必须过闸门、检索必须按租户过滤）。之后才是第二遍：对现有实现逐维给证据状态。两份并排，差异就是「与现有实现的差异」一节的内容。

拿到仓库 + 提示词 + 部分测试，但没有生产环境 → 判为实现评审，报告开头声明，所有运行时断言不外推。逐维给证据状态：D5 fail（refund.create 可直接调用，服务端无二次校验，提示词里写着"退款前请确认"——那不是闸门）；D7 fail（超时重试且幂等键用 uuid4() 现生成）；D8 unknown（拿不到检索层代码，无法确认租户过滤在哪一层，结论里写明"提供 retriever.py 即可定性"）；D2 partial（系统提示词 12k 字符，触线——但走两段式，先带证据问用户是否认为是问题，用户答"刻意合并以省一次调用"，记为已知权衡）；D13 标 N/A（客服 Agent 与用户直接对话，偏误当场就能被纠正）；其余 pass 或 N/A。矛盾检查抓出一条：设计文档写"最多 20 轮"，代码里 MAX_TURNS = 200 且该常量未被引用。结论把 D5、D7 两条 P0 置顶，不写"总体良好但……"，并给出最小下一步：补一份 retriever.py 就能把 D8 从 unknown 定性。

案例 3 — 排障·线上异常：用户说"我们的运维 Agent 最近老是不调那个查配置的工具，直接就开始瞎猜"。

不走步骤 0→4，走排障入口。先要一次具体失败运行的对话记录——用户只有应用日志，日志里写着"工具调用 0 次"，这只是"我们以为发生了什么"，于是先请他们在 LLM 调用出入口把完整 request/response 落盘（含 tools 与 stop_reason），复现一次拿到真记录，同时把"没有 transcript"按 P0 登记为 D12 缺失——不是这一次排障的临时装置，而是本该在设计期就有的调试模式，收口时按 references/runtime/observability.md 补齐开关与切片。

降噪成骨架（thinking 与工具返回只留名字和体量），28 轮一屏扫完。正序读，第 3 轮就是第一偏离点：Agent 说"我无法查看当前配置"——不是从最后那句瞎猜的结论倒着查。按三分类判为输入偏离（它判错了，但换谁都会判错），于是去看第 3 轮实际发出的 request——不是配置文件、不是提示词模板：tools 清单里根本没有那个工具。归因层落在 harness，根因是工具注册在某个条件分支下被跳过，与提示词无关。

收口四件事：归因写明轮次与证据；映射回 D2（工具清单与最小集），按 references/prompt/agent-construction.md 处置；补一条回归用例，断言该场景下 request 的 tools 含该工具；如实说明本次只看了这一条链路，另一类偶发超时仍是 unknown。全程没有改过一个字的提示词——若一开始就去"优化提示词让它记得调工具"，异常大概率会被盖住，而工具依然没被注册。