context-infra 检查与复盘infra.guiming.net · 全内容自包含呈现 · 生成于 2026-07-21 16:28 UTC

设计文档协议：怎么填、填到什么算完（术·语义层，draft）

Z3 全文↑ Z2 条目

术-语义层 · 术层 skill 全文

← 返回术层 skill 索引 · 返回方法论区

本页是 <code>rules/skills/drafts/workflow_design_doc_protocol.md</code> 的逐字投影（仅隐私清洗，零改写）。

时点提示：本页是仓内文件 rules/skills/drafts/workflow_design_doc_protocol.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。

设计文档协议：怎么填、填到什么算完（术·语义层，draft）

元数据

目标（一句话）

design_doc 工具能生成一个三层骨架，但骨架里每个核心字段都是 <...> 占位。光有工具没有协议，结果就是骨架生成了、没人填——T631 那份 106 行设计文档里 20 个核心字段（问题是什么、目标态、约束、架构、决策、交付物）全是空占位，因为没有东西告诉 agent 怎么填、填到什么算完。这个协议补的就是这一层：什么时候用、三层各自填什么才算填实、用什么机械判据确认填完了。

边界（不做什么）

何时用 design_doc

不是每个任务都要三层设计文档。触发条件（任一成立就值得写）：

反过来，单文件小改、机械替换、一条命令能验的任务不需要三层设计文档，写了反而是过度工程。

三层怎么填（对齐双锚点）

工具生成的骨架有三层 + Final Boundary。每层的填法和「填实」的样子：

Layer 1 功能设计 = Requirement Anchor（收紧目标语义，防目标发散）。 五格都要落地，且每一格回答的是「需求」不是「实现」：

Layer 2 实现设计 = Unit Anchor（收紧行为边界，防行为发散）。 架构图给组件流向；职责表每个组件写清「负责什么 / 不负责什么 / 路径接口」（「不负责什么」是边界，别省）；决策表是这层的承重点——每个关键决策写「决策点 / 本轮选择 / 选择理由 / 不选什么及原因」，「不选什么」就是行为边界的显式收紧；反过度工程化三问按工具模板里的问题逐个真回答，不是占位。

Layer 3 代码改动清单。 ADDED / MODIFIED / REMOVED 各给真实路径 + 原因；对比表写 before/after。设计阶段还没动代码时，路径要具体到计划文件（tools/x/y.py），不写 <路径>；没有 REMOVED 就写「无」，不留占位。

Final Boundary。 状态三选一（DONE / PARTIAL / BLOCKED）+ 已覆盖 / 未覆盖 / 延后 / 证据边界。这是诚实边界，不留空、不全声称。

意义面怎么填（M1-M5 填法）Beta

本节只指导 design_doc 骨架里的 ## §意义面，不是把需求原文换个说法，也不是提前写设计方案。意义面回答的是：这个设计记录为什么存在、补的是哪类 LLM/系统根局限、它如何承接总领意义并约束后续设计。

填到根局限级：每条意义要指向问题的窟窿或根局限，例如「fresh agent 拿不到完整上下文」「执行者不能自评够没够」「确定性记录不该占模型注意力预算」。不要把用户需求原文改写成「完成某需求」「支持某功能」放进 M1/M2；那会被 DC6 regulator 当作回显需求或空泛意义。

引需求锚，不复制需求原文：需求面已经承接 requirement_doc 指针和本次涉及需求索引，意义面只引用 req_id / requirement_doc 锚。不要把逐字需求复制进意义面，避免同一信息出现第二个真源。

承接总领意义必须具体可查：顶部表格的「承接总领意义」行必须含 CROSS_DOMAIN_MEANING.md 字样，并指向 adhoc_jobs/context_infra_base_tooling_buildout_20260615/requirements/meaning/CROSS_DOMAIN_MEANING.md 的具体条目。当前 DC6 壳允许的编号合法集是 1-13 与 A/B/C；filled 状态下，该行没有 CROSS_DOMAIN_MEANING.md 或没有合法编号都会 FLAG。

M1 本域核心意义：一句话写清这个设计文档 / 这个域为什么存在，必须能区别于相邻域。例如 DDP 的 M1 不是「记录设计需求」，而是「给 fresh agent 重建完整上下文的权威载体」。

M2 补哪类根局限：写它补的是哪类根局限或第一层必要条件，可以用 (a)/(b)/(c)/(d) 这类根局限短码，但必须解释补什么缺口。M2 是正向补口，不是任务目标清单。

M3 总领意义锚：列出承接的 CROSS_DOMAIN_MEANING.md 条目编号，例如 #1、#4、#7、#8、#10 或新意义 A/B/C。M3 要和顶部指针一致；顶部指针给确定性壳定位，M3 给读者和 regulator 理解。

M4 防哪种不良行为：写这条意义在反向防什么，例如 reward hacking、回显需求、自证完成、上下文断裂、设计和意义各写各的发散。M4 与 M2 正交：M2 写补什么，M4 写防什么。

M5 意义到落地对应：写意义如何落到确定层槽位、外部 oracle、状态门、Forbidden Read 或消费链。DC6 regulator 会看 M5 是否真的对应 M2 标的局限，而不是泛泛写「提升质量」。

当前 checker 对齐：tools/design_doc/check_completeness.py 的 DC6 壳只在检测到三面骨架时启用；它检查三面存在、每面 face_status、设计/执行标签、意义面 CROSS_DOMAIN_MEANING.md 指针和 M1-M5 标题。face_status 当前可通过的值只有 unwritten 与 filled。协议语义上的 draft 表示草稿中间态，但在当前壳扩容前不要把 draft 写进 face_status，否则会被 DC6_FACE_STATUS_INVALID FLAG。

三面异步写入纪律 Beta

三面是 §需求面、§意义面、§设计面。异步写入不是「随便留空」，而是把不同时间 / 不同模型写入的面分开，让每一面有自己的状态、锚和完成门。

  1. 分面写：一次只改一个面。需求面更新 requirement_doc 指针和涉及需求索引；意义面只写 M1-M5；设计面才写 Layer 1/2/3 与 Final Boundary。异步性可以用 git diff 区块隔离验证：本轮只动哪一面，应能在 diff 里看出来。
  2. 后写引先写：意义面引用需求面锚，不复制需求原文；设计面后写时，Layer 1 的 core_need 要能回链到意义面 M1/M2，而不是独立漂移成另一套目标。
  3. 写意义面 Forbidden Read 设计草稿：复用 v0.4 DESIGNER-CONTRACT.md 的 Forbidden Read 语义。写意义面的 agent 只读需求面指针、CROSS_DOMAIN_MEANING.md 条目和本任务授权输入，不读 §设计面 草稿，防止先看设计再倒推意义。
  4. face_status 当前落地值：unwritten 表示本面尚未写，可合法保留 <...> 占位；filled 表示本面声明已填实，DC1 会检查该面残留占位，DC6 会检查意义面结构与指针。draft 作为协议语义保留给未来壳扩容；当前不要写入 face_status。
  5. DC1 状态门：T963 后 DC1 不再是全文无占位，而是状态门：有三面状态时，只对 filled 面报 DC1_PLACEHOLDER；unwritten 面留 <...> 合法。没有三面骨架的旧文档仍走旧式占位检查。
  6. 完成信号外置：三面都填了也不靠作者自报。完成仍要跑 design_doc 的 check_completeness，由 DC1/DC2/DC5/DC6 的确定性壳和 DC3/DC4/DC5/DC6 的 regulator 共同给外部误差信号。

复杂设计前的准备：六要素 Designer Packet 草稿（UP-63）

三层骨架假设权威源边界已经想清楚——但一个设计任务如果牵涉 ≥2 个 Authority Target（哪个文件是权威源、要往哪几处写），或者本身就是跨文件传播，直接上手填 Layer 1/2/3 容易把还没想清楚的边界写死。这一节补的是三层骨架之前的准备动作。

何时起草：满足"何时用 design_doc"的触发条件之外，再加一条——本任务识别出 ≥2 个 Authority Target，或本任务的决定会牵连其它文件的行为/契约。只满足这条不满足"何时用 design_doc"本身的，不需要走三层骨架，草稿完就地关闭。

六节结构（历史模板见 adhoc_jobs/design_doc_protocol_loop_codex_20260501/prompts/designer_prompt_reconstruction.md，本节是按当前仓库规模的精简版，不是原样照搬）：

  1. Prompt Atoms：把用户原话拆成可追溯的原子，每条标 requirement/decision/constraint/question/instruction 五种之一。
  2. Baseline Constraints：写之前必须遵守的既有约束——已有字段名、路径约定、结构协议、语义不变式，每条注明来源文件或来源理由。
  3. Concept Modules：每个概念给「用户需求 → 需求本质 → 设计 → 边界」四段（与 UP-73/DDP-13 的四段结构一致，不是重造）。
  4. Authority Targets：target-id / canonical-for / candidate-file / reason / touched-by 五列表——哪个文件是这个概念的权威源，改了它之后哪些文件要跟着检查（touched-by 具体纪律见下一节）。
  5. Pending Decisions：没有阻塞项写「无阻塞待裁决项」；有阻塞项列 decision-id / issue / options / why blocked / affected-write-blocks。
  6. Write Blocks：block-id / target / content / must-include-tokens / blocked-by——具体要写哪块内容到哪个文件，写完这节才开始真正填三层骨架。

这份草稿是什么、不是什么：它是丢弃型中间产物（放在临时位置，不进 git 权威区），帮设计者把边界想清楚；写完六节之后，Concept Modules 喂 Layer 1/2，Authority Targets 喂 Layer 2 决策表和下一节的传播纪律，草稿本身不当作交付物保留、不算入 Final Boundary 的"已覆盖"证据。

已知陷阱 T5（Designer Packet 变成新权威层）：把六节草稿当成比三层骨架更权威的东西，后续设计变更去改草稿而不改正式骨架——草稿只在写之前用一次，写完就过期，权威永远在 design_docs/ 正式文件。

Authority Targets 的传播纪律：touched-by / canonical-for（DDP-14）

用户原话点名了这件事该谁管："因为这涉及到 touched by 权威源等地方的写入，这是 process doc 在拿到设计文档后，由 design doc protocol 负责执行的写入任务。"——Authority Targets 表里已经有 canonical-for 和 touched-by 两列，但光填表不传播，等于没做这件事。

触发：Layer 2 决策表任何一条决策的影响范围超出本设计文档本身（会改变别的文件的行为、契约或读取路径）时触发。

怎么做（复用 bestpractice_architecture_doc_design.md §2.3 的三层协议，按引用不复制实现）：

  1. canonical-for：这个决策涉及的概念，权威源是哪个文件——一个概念只能有一个权威源。
  2. touched-by：改了权威源之后，哪些文件的契约块需要跟着检查/更新——具体到文件路径，不写"相关文件"这种空泛话。
  3. 契约块：在每个 touched-by 文件里留一段 → <概念名> 格式的契约块，写清楚"本层对该概念的义务/限制"+ 指向权威源的链接，不复制权威源的完整定义。

Final Boundary 新增一项：touched-by 列表里的文件是否都已经完成传播（契约块已写/已核对），不是"Authority Targets 表填了 touched-by 列就算完工"。未传播完的 touched-by 项在 Final Boundary 里必须显式标"延后"，不能沉默略过。

边界（不做什么）：本节不重建历史 6-Phase Protocol 的 Designer/Checker/Decomposer/Writer/Propagator/Reviewer 五角色分工——那是 design_doc_protocol_loop_codex_20260501 / designdoc_protocol_round1_claude_code_20260501 的实验性 Round，已被本仓库当前更轻量的 design_docs/ + tools/ddp/ 模型取代，不再复活。本节只吸收 touched-by 传播的判据和契约块格式，不吸收那套角色分离的运行时机制。

多轮迭代时的 Bad Behavior 审查 + fresh-agent 可消费性（UP-67 / DDP-16）

用户原话："每轮记录 Bad Behavior 风险：reward hacking、局部最优、自证完成、fresh-agent consumability、是否需要推翻重建。命中风险时必须影响下一步反应。"DDP-16 进一步把 fresh-agent consumability 从风险检查项升格为正向验收目标。

触发：DDP 域自己做多轮迭代式协议/skill 重建工作时（同一个设计对象跨多个 session/round 反复修改，例如一次改动同时牵涉三份以上文件、或分多轮逐步定稿的场景），在每个轮次边界跑一次 Bad Behavior 审查。单轮次、单文件的小改不触发。

怎么审查：不新造分类法，按名引用 rules/skills/workflow_controller_loop/references/BAD_BEHAVIOR_GUIDE.md（12 方向、36 条具体表现、审查输出 schema 该文件已定义）。DDP 场景重点覆盖：

命中任何条目，按 BAD_BEHAVIOR_GUIDE 的 reaction 集合（keep/rerun/rollback/discard/rethink/redesign_test/await_user/block）之一处理，不能只记录不改变决策（BB-31）。

fresh-agent 可消费性（正向验收项，不只是风险提示）：一份要交给另一个 agent（含 Codex）执行的设计文档，Final Boundary 里必须有一条独立判断——一个没有先验上下文的新 agent，仅凭这份文档能不能真的把活干出来。这条判断不能由撰写者自己勾选："能" / "不确定"两种情况里，"不确定"或命中 fresh-agent consumability 风险时，验收门控必须补一份独立 fresh-agent E2E 通过证据（真的派一个不知情的 agent 拿文档去执行，看它是否卡在缺上下文），不能用撰写者的自我评估替代。

已知陷阱 T6（fresh-agent 检查被自报替代）：撰写者在 Final Boundary 写"fresh-agent 可消费：是"但从没有真的找一个无先验 agent 试过——这条判断和 DC3/DC4 一样必须过第二方（regulator 或真实 fresh-agent 试跑），不能自报作数。

当前边界：本节暂不新增 DCx 编号机械化检测——check_completeness.py 的 DC5 已用于 unit 职责隔离，DC6 已由 T963（意义面/三面异步互补设计，commit e4c7028ae）落地为意义面填实检查。Bad Behavior 审查和 fresh-agent 可消费性目前仍只是 Final Boundary 清单项 + 按名引用的判据，不与 DC6 合并：DC6 管意义面是否填实、是否回链设计面；Bad Behavior / fresh-agent 清单项管设计产物是否可消费、是否需要独立 E2E。二者语义不同，保留为独立 Final Boundary 清单项；机械化检测器留给未来独立检测器或后续 DC 编号。

设计来源记录纪律（provenance，SGQ-14）Beta

用户原话点名了这件事的目的："对于设计文档中的所有设计方案，我认为必须明确记录『设计的来源』——即为什么要这样设计。如果在设计时参考了一些业界比较优秀的实现方案，必须将这些参考来源记录下来，并在设计文档中作为一个独立的部分呈现。目的是后续调整或重构时，依然能够追溯到之前成功设计的依据，从而进行更综合的评估和考虑。"——骨架 §2.3b「设计来源与参考(provenance)」就是这个"独立的部分"的落点；本节给它的填写纪律。

这一节管什么、不管什么（与 Layer 2 决策表的关系）：决策表（§2.3）管"选了什么、为什么选它、放弃了什么"——它是决策的横切面；provenance 表（§2.3b）管"这个选择的依据从哪来"——它是依据的溯源面。两者正交、不重复：决策表的"为什么"是本轮的权衡逻辑（在当前约束下为何这个选择更优），provenance 的"来源"是这个逻辑站得住的外部/历史支点（业界某实现这样做过、内部某先例验证过、或纯第一性推导）。不要把决策表的理由复制进 provenance，也不要把来源锚塞进决策表撑宽表格。

何时必填：设计面进入 filled 状态时，每个进了决策表的关键设计决策都要在 §2.3b 有对应的一条来源。触发不限于"借鉴了业界方案"——三种情形都要写：

填实判据（反例导向）：每条来源必须可回溯到具体锚——一个能点开的 URL、一个仓内文件路径、或需求真源的具体块号。反例（判为空泛，应 FLAG）：泛泛写"参考了业界最佳实践""借鉴了成熟方案"而没有具体是哪个实现、哪篇文档、哪个项目。这类无锚描述在重构时等于没记，因为后人无法据此回到"之前成功设计的依据"。"采纳了什么"要写清从参考里具体吸收了哪部分（不是整个照搬时尤其要写明边界）；"与参考的差异"要写清有意偏离的地方及原因（直接照搬则写"直接采纳"），这一列是防止把参考当圣经、丢失本地约束适配的关键。

重构时的消费方式（用户原话的目的落地）：当后续 session 要调整或重构某个设计时，先读 §2.3b——它回答"当初为什么这样设计、依据是什么、和参考差在哪"。有了来源锚，重构者能做三件决策表本身给不了的判断：(1) 回到原始参考看它是否已演进（业界实现是否有更新版本、内部先例是否已被推翻）；(2) 判断当初的"与参考的差异"是否仍然成立（本地约束是否变了）；(3) 在"更综合的评估"里把原始依据和新证据一起权衡，而不是在真空里重做决策。这就是把"独立部分呈现"从一个格式要求变成一个可消费的追溯接口。

与确定层的当前关系：§2.3b 落在设计面，因此自动继承 DC1 状态门语义——设计面 unwritten 时表内 <...> 占位合法（异步留白）；设计面声明 filled 后，空 provenance 表的占位会被 DC1 逐格 FLAG（给 field:line），与其它设计面字段完全一致。本轮不新增 DCx 编号做"来源锚可解析性"的语义校验（来源类型是否合法四选一、参考锚 URL/路径是否真能解析、是否泛泛无锚），那属于 regulator 语义判断或未来独立检测器的范围，记录为深水区。当前 provenance 的"填实 vs 空泛"判断，与 DC3 回显需求判断同源，靠 regulator 或第二方，不靠撰写者自报。

已知陷阱 T7（provenance 退化成空泛口号）：把 §2.3b 填成"参考业界最佳实践"这类无锚句子——确定层查不出（不是 <...> 占位了），但重构时追溯断链，等于没记。这条和 T2（回显需求）同构，靠 DC3 同级的 regulator 判，或在 Final Boundary 里由第二方复核每条来源是否真有可点开的锚。

完成判据（可机械查，是这个协议的硬核）

一份设计文档「填完了」要全过下面，缺一不算完。确定性壳负责结构、占位、状态和指针；regulator 负责空泛、决策回链、职责隔离与意义质量：

收口调用：设计文档填完跑 python3 tools/design_doc/check_completeness.py <设计文档路径> --regulator --regulator-tier codex:high：DC1/DC2/DC5/DC6 的壳面给确定性 verdict（残留占位、空格、缺状态/标签/指针、非法编号 → FLAG，给字段:行号），DC3/DC4/DC5/DC6 的 regulator 喂文档判空泛、决策回链、职责隔离与意义质量。完成判断不让写文档的 agent 自己勾，过检测器或第二方。

Final Boundary 补充项（触发时生效，不是每份文档都要）：touched-by 传播是否完成（见「Authority Targets 的传播纪律」节，未传播完须显式标延后）；fresh-agent 可消费性判断是否给出且非撰写者自报（见「多轮迭代时的 Bad Behavior 审查」节，命中风险须补独立 E2E 证据）。这两项不占用 DCx 编号，是 DC1-DC6 之外的独立清单项，只在各自触发条件成立时才是必填。

方法论建议（可按情况调整）

已知陷阱（来自真实案例）

输出规格

跨域根与联系

← 返回术层 skill 索引 · 返回方法论区