Prd To Trd

prd-to-trd

> 适用范围扩展 · 对话追问式编辑也走本 skill 约束 > 本 skill 不仅负责"PRD → TRD 生成"，还通过文档头 guard block + lint_trd.py 对后续一切编辑强制执行同一套 HARD-GATE。 > 具体来说：若某次对话里用户说「把这份 TRD 的 X 改一下 / 优化 Y / 评估 Z 可行性」，而该文件头部含 ` 锚点，则 AI 必须： > 1. 在动笔前 Read 本 SKILL.md，把下方完整 HARD-GATE 清单加载进上下文； > 2. 按本 skill 的硬约束执行编辑（不是按对话偏好自由发挥）； > 3. 编辑完运行 python3 scripts/linttrd.py ，blocking 不过不得声明完成。 > 4. **若本次来源是 trdreviewrequired / reviewer 报告修复 / TRD → Plan 门禁修复，linttrd.py 通过不是终点**：必须继续走 auto_converge.py 或重新派 prd-to-trd-reviewer 并把报告回流，由状态机判定下一步。禁止输出“建议你本地下步再派 reviewer / 或跑 auto_converge”后停住。 > 这是 [AGENTS.md`](../../AGENTS.md) 第 9 条"nexus-harness 工作模式"在 TRD 维护场景下的落地。

> 框架不可变铁律（复用自 [AGENTS.md](../../AGENTS.md) 第 7 条，所有 skill 一致） > 本 SKILL.md 及其 scripts/ / templates/ / tests/ 等框架文件在"使用本 skill"过程中只读。 > 即便发现 bug / 参数漏传 / 模板缺漏 / 质检误判，也必须立刻停下当前工作流， > 向用户报告问题原文，由用户决定是否开新会话以"维护 nexus-harness 框架"为唯一目标修复。 > 唯一豁免：用户在当前会话明确声明"现在就是来改这个 skill 的"。 > 违反此条 = 边用边改，框架即刻失去"可分发给其他用户使用"的基本属性。

> 职责边界（必读） > 本 skill 只做一件事：把一份已经定稿可用的 PRD 转成一份结构完整的 TRD，并用「硬质检修复 + reviewer 复核 + 用户可选继续自动修」把 TRD 推到可交付或可人工接手。 > 不做：代码层面的实现细节落地（交 tdd-loop）、基于代码改动的 TRD 增量更新（交 finish-project / 类似 skill）、PRD 本身的修订。 > 输入是「PRD + 可选 KB + 可选约束」，输出是「TRD + 质检报告」。仅此而已。

把一份 PRD 转成结构完整的 TRD：

/
├── .md            ← 输入 PRD
└── -技术方案.md   ← 建议的 TRD 路径（脚本算给你作建议，用户可改）

TRD 必含章节：数据结构设计 / 核心流程（时序）/ 缓存设计 / 数据库设计 / CRUD SQL 示例；可选：PRD-TRD 对齐矩阵。

---

不可绕过的硬约束

> 零号铁律 · 禁止调用 legacy prdtotrd MCP > 在 nexus-harness CLI 模式（即 NEXUS_HOME 已设置）下，AI tool 清单里若出现任何名字含 prdtotrd / prd-trd / prd-trd-mcp 的 MCP，禁止调用。它们是本 skill 脚本的过期前身，不识别 NEXUS_KNOWLEDGE_ROOT / NEXUS_STATE_ROOT，会让本仓库所有 CLI 模式契约失效（legacy MCP 会直接让用户输 __NONE__，并且看不见 ~/.nexus-harness/knowledge/ 下的 KB）。 > 唯一允许的入口是本 skill 提供的脚本：python3 $NEXUS_HOME/skills/prd-to-trd/scripts/trd_wizard.py（或 _core.trd_wizard 模块）。 > 该铁律由 nexus_harness/mcp_guard.py 在启动器侧探测并向用户 stderr 告警，同时在项目级 CLAUDE.md banner 注入硬约束规则。看到 banner 里列出的待屏蔽 MCP 名字直接拒绝调用即可。

> 零号铁律 · 1:1 平移基线 > 本 skill 的脚本行为 1:1 复刻自 prdtotrd MCP（trdwizard / generatetrdfromprd / qualitychecktrd / trdpostreview_wizard 等 7 个工具）。任何与 MCP 行为不一致的改动必须基于真跑测证据，记入 backlog 后再做，不在使用过程中临场重构。

> 零号铁律 · 禁止暴露内部实现 > 禁止向用户输出："1:1 平移自 prdtotrd MCP / 状态机内部结构 / __NONE__ token / _compose_trd 是 1500 行硬模板 / 与其它 skill 的差异"等元信息。 > 用户只关心两件事：(a) 你接下来要他做的选择是什么 (b) 当前进展到哪一步。其余一律不说。

> AIWeave 入口探测铁律（v0.x 整合后新增 · 仅 Go 项目；已直接接入 trd_wizard 状态机） > 用户给完 project_path / prd_path 后，trd_wizard 会自动调用 aiweave-bridge/scripts/detect.py 判 maturity，主 Agent 无需手动 bash detect。返回的新 stage 与处理方式如下： > - non_go → 静默走老 TRD 流程（KB 已封存，docsincrementplan 留空）。 > - aiweave_choice_t0 → 状态机自动停下问用户：「立即自动执行 bootstrap / 跳过 AIWeave」。Agent 把 1/2 透传到 aiweave_choice 即可（脚本会按 maturity 翻译成 bootstrap_later / skip_aiweave）。 > - 用户回复 1（bootstrap_later）后 trdwizard 进入 三段式 bootstrap： > ① 进程内调 bootstrap.py cp vendor templates → /docs/ + .claude/skills/（秒级） > ② 进程内调 fill_docs.py 做机械邮戳：{ProjectName} / {YYYY-MM-DD} / {project_module}（秒级） > ③ 返回 action="dispatch_aiweave_snapshot" / stage="aiweave_snapshot_required" 派发指令包（默认 snapshot_inputs.stage="all"），主 Agent 必须用 Task 同步阻塞派 1 个独立上下文子 Agent（subagent_type="aiweave-snapshot"，未注册时 fallback generalPurpose）以 task_prompt_template 为 prompt 一次性写完全部 19 篇 docs（按 vendor/aiweave/docs-spec 读真实业务代码后填 docs/，精度到函数签名 / DDL 字段 / 缓存 Hash 字段映射 / 路由表中间件链；耗时 30-90min 一气呵成）。子 Agent Task 返回后跑 1 次 lint_aiweave_invariants.py --check-docs-quality + 1 次 docs-build-reviewer 复核；blocking → 通知子 Agent 定点修复，最多 2 轮，再失败 askuser。禁止把 1 个子 Agent 拆成 B1-B6 六个独立 subagent 串行——历史验证那是慢 2-3 倍的反模式。 > ④ 子 Agent 完成时写 /.aiweave_snapshot.json checkpoint 并打印 [snapshot] done → ...。主 Agent 把 aiweave_snapshot_done=true 回传 trdwizard；wizard 会重新验真 checkpoint（ok==true ∧ docs/ 存在 ∧ 声明文件真实存在，不再盲信 aiweave_snapshot_done），通过后重新 detect，进入 T1/T2 的 docs 基础上下文准备与范围切片流程。 > 铁律：snapshot 必须真子 Agent 派发；主 Agent 禁止"我来扮演 snapshot"自填 docs/，禁止 Bash 跑 filldocs 当替代——filldocs 只做机械邮戳，没有读代码 + 业务判断能力。 > 可恢复保障：dispatch 时 trdwizard 已把 aiweave_snapshot_status=pending + aiweave_snapshot_project_path / aiweave_snapshot_prd_path 落盘到 context.json。snapshot 首选同步阻塞静默等待；但即便被宿主后台化、会话中断或主 Agent 上下文被打断，流程不会丢失——用户回入口输入「继续」/「下一步」，discover_workspace_stage.py / what_next.py 会识别 stage=aiweave_snapshot_required，自动验证 checkpoint 并带 aiweave_snapshot_done=true 回流 trd_wizard。因此严禁向用户输出「你可以先去做别的事情」这类暗示流程会自行恢复的措辞，但可以告知"如被打断，回入口输入继续即可接回"。 > - aiweave_choice_t1 → docs/ 缺部分篇章，问「补齐 / 带缺口前进」；同样回 1/2 → fill_missing_later / skip_missing。 > - aiweave_options → 核心选择题阶段，状态机会先 silent 调用 compile_context.py 准备 AIWeave docs 基础上下文；等 prd_slice + dependency_contracts 确认后，再用当前项目范围调用 generate_options.py 生成 A/B/C 选择题。Agent 把用户回复（如 q1=A, q2=B, q3=C 或单字母 A B C）原样作为 aiweave_options_answers（list 或字符串）回传，脚本会自动算出 docs_increment_plan 并继续 Stage 4。 > - 状态机执行阶段会自动追加一步 append_docs_increment_plan 把 ## docs/ 增量计划 写到 TRD 末尾，并把 aiweave_status / aiweave_context_path / docs_increment_plan 透传给 update_project_context.py 写入 context.json。 > 若用户在 wizard 启动时已确认要旁路 AIWeave（极端例外），可一次性传 no_aiweave=true。 > KB 体系（knowledge_base_dirs）已随 AIWeave 整合同步封存，collect_knowledge_base_dirs 阶段在脚本层静默以空 list 继续，主 Agent 无需任何操作。

> 零号铁律 · presentation-only（最高优先级） > 脚本返回的 dict 中，只有 presentation 下的字段是给用户看的。其它所有字段（stage / action / required_field / interaction_contract / agent_instruction / plan_preview / steps / quality_report / quality_report_before_fix / quality_report_after_fix / warning_issues / failed_issues / next_actions / trd_path / ai_context / prd_content 等）全部是 AI 内部用的，禁止主动展示给用户。 > 唯一例外：用户主动追问"详细信息 / 完整报告 / 那 N 个 warning 是什么"时，可按需挑相关字段摘要展示——但不许把 JSON 整坨甩出来。

执行时必须遵守以下铁律，违反任意一条立刻停下：

1. 【交互铁律】 只要脚本返回 action="ask_user" / action="ask_user_ai_compose"，必须停下并等待用户下一条明确回复。禁止在同一轮里继续调用脚本自动推进。
2. 【禁止代答】 严禁替用户做选择或填默认值（project_path / prd_path / cache_requirement / database_requirement / engineering_constraints / output_path / confirmed / quality_choice / fix_choice / user_feedback）。只有用户在最新消息中明确表达，才能把对应参数传进去。
3. 【project_path 必填，禁止从 PRD 推断】 TRD 必须基于"具体项目"产出（接口风格、鉴权、表规范、缓存 key 都来自项目）。绝不用 PRD 所在目录、pwd、git root 等任何方式推断 project_path，必须显式问用户。仅当上游已显式传入 project_path 时跳过。trd_dir 只决定 TRD 输出目录，不代表业务项目根目录。
4. 【output_path 必填，但展示推断作建议】 脚本在 collect_output_path 阶段会算出建议路径并放入 presentation.question。用户回「是 / yes / ok / 确认」即采纳建议；回路径即用新路径。绝不在用户没回复前自行 output_path=。
5. 【confirm_plan 用人话摘要，禁止甩 JSON】 脚本在 confirm_plan 阶段返 presentation.question（包含一段中文摘要：项目 / PRD / AI 知识库 / 缓存 / 数据库 / 工程约束 / TRD 落盘路径，每行一项）。只展示这段中文摘要。plan_preview 字段是机读结构，绝不给用户看。
6. 【execute 门禁 + 静默推进】 仅当 trd_wizard.py 返回 action="execute" 后才按 steps 顺序自动调用工具。给用户只展示 presentation.next_action_for_user 那一句中文进度。绝不给用户复述脚本名、steps 数组、tool / params 字段。【参数原样透传】 调 generate_trd_from_prd / update_project_context / auto_converge 时必须原样使用对应 steps[].params，禁止手搓 JSON 漏传或改写 user_doc_type / http_method_policy / prd_slice / dependency_contracts / engineering_constraints；漏 user_doc_type 会按关键词误判文档类型，脚本会直接报错拒绝生成。
7. 【骨架先落盘 + 分段补肉】 generate_trd_from_prd 返回 skeleton_markdown 后必须立即 write_markdown_file 落盘，再按 section_fill_plan[*].write_units 逐块补齐。接口设计、数据结构、流程、页面、状态机、权限、缓存、导入/批处理等大章节必须按 H3 / 单接口 / 单表 / 单矩阵 / 单流程粒度写；小章节可按 H2 整节写。禁止启动后台 Agent 一次性生成完整 TRD；禁止整篇重写；补肉失败时只能继续缩小到当前小块内的表格/段落，不能升级为整篇 Write。

7.5. 【正文生成阶段禁止子 Agent】 从 generate_trd_from_prd 返回到 TRD 正文补齐完成之前，禁止使用任何子 Agent / Task / Local Agent / general-purpose Agent 生成、补齐、改写 TRD 正文。正文只能由当前主 Agent 按 section_fill_plan 分批写入。只有进入 auto_converge 且返回 dispatch_reviewer / redispatch_reviewer 时，才允许派发 prd-to-trd-reviewer 子 Agent。

1. 【auto_converge 主入口 · 有限收敛 · 质量+速度】 TRD 落盘后默认调 auto_converge.py。收敛策略：硬质检 → 有 blocking/major 则自动修复 → 第 1 次派独立 reviewer 子 Agent 全量复核 → 修后再检时由状态机内联 run_review.py 快速规则集复检（不再派子 Agent，秒～分钟级）→ 若仍有 blocking/major 且 round 。AI 自己也禁止凭空编造路径示例安抚用户。
2. 【AI 出题铁律 · cache/db/engineering · AIWeave 加固版 v2】 当脚本返回 action="ask_user_ai_compose"，禁止任何通用问题模板。出题前必须按下列顺序消化输入（AIWeave 字段优先于 PRD）：

• (a) 若 ai_context.aiweave 存在（项目 aiweave_status ∈ {T1,T2}）：先逐条看完 ai_context.aiweave.topic_doc_hints[*].digest（已内联 docs/*.md 顶部 15 行现状摘要）与 ai_context.aiweave.aiweave_context_summary（docs 篇章索引 + BUILD_STATUS 计数）；这两个字段是事实主源。digest 不够时再用 Read 打开对应 path 看完整文件。
• (b) 然后再读 ai_context.prd_content，把 PRD 视为『相对 docs/ 的增量需求』；结合 ai_context.project_path 与 collected_context。
• (c) 【最高法则 · docs 已定义维度一律 AI 自决，禁止扔回用户】 以下维度凡 docs 里已有约定，AI 必须按 docs 自动落 TRD，禁止包装成「选择题 / 风格确认 / 冲突拍板」问用户：
• 命名前缀：路由前缀 / Cache Key 前缀 / MQ Topic 前缀 / 表名字段命名
• 实例 / 连接选择：Redis 实例 / DB 连接 / MQ 集群（除非 docs 明确写多实例分流）
• 错误码段（ErrNo 范围）/ 中间件链 / 响应外壳（envelope）
• 已有 service 方法签名 / module 名 / 已有表 DDL / 已有索引策略
• PRD 写法与 docs 规范冲突时（如 PRD 写 aqlog:、docs 规定 goweb:），直接按 docs 归一化写进 TRD（goweb:aqlog:...），TRD 对应章节加一行『按 docs 命名规范归一化为 X』即可。
• (d) ai_context.aiweave.docs_increment_plan 已经定下的方向（如『新增独立 Redis Key』）只允许沿着方向继续细化（新 Key 的 Hash 字段映射 / TTL / 回源策略），禁止重新拷问『要不要缓存 / 新建还是复用 / Key 用哪种风格』这类已确定方向。
• (e) presentation.expected_question_count 是上限不是下限。当 digest + summary + docsincrementplan 已经覆盖全部决策时，允许返回 0 条追问——但此时仍必须向用户展示「AI 自决摘要」（按 docs 自动确定的各项结论逐条列出），最后一行写「如无异议，请回复「确认」继续」；收到「确认」后把摘要内容作为 required_field 的值回填给 wizard。禁止在 0 条追问时直接调 wizard 跳过用户交互——interaction_contract.must_wait_user_reply=True 在 0 条追问时同样适用。凑数提问 = 违反本铁律，本轮提问作废重写。
• (f) 真要提问时：编号清晰发给用户（标题 + 1. / 2. / 3. 之间空一行），每题必须是 docs 未覆盖且 PRD 也无法单方面拍板的真增量项；收齐答案后回填到 required_field。
• (g) 分歧有界收敛 · 永不把用户逼进死胡同（interaction_contract.bounded_divergence_convergence，缓存/数据库/工程/接口评审通用）：当用户回的不是「确认」、而是改进意见/反对/补充时，无论该意见是否本身有问题，禁止反复细抠把流程卡死：① 先把用户意图原样记进 required_field（绝不丢话）；② 若与 docs/代码证据冲突，只点一次 + 给带依据的修正版；③ 最多再澄清一轮（max_clarify_rounds_on_pushback=1），之后以用户最新回复为准、写进字段并继续下一阶段，未敲定点标『待详设/联调确认』风险项、不阻塞；④ 每次追问/澄清结尾必须给明确前进出口（如『回复「确认」继续；或「就按我说的记下，细节后面再定」我直接记录并往下走』）。
• 禁止把 ai_context（含 aiweave 子树）任何字段展示给用户。

1. 【输出克制】 给用户的每条回复只包含两段：(a) 脚本 presentation 字段里要用户做的事；(b) 必要时一句简短上下文。不要附流程图、原理说明、脚本名、JSON dump、"我接下来要执行 generate / write / post_review" 等。「克制」不等于缩短 presentation.question：action="ask_user" 时须逐字完整转发 presentation.question（含多行、编号列表、` nexus kb clone / nexus kb cp ` 等命令行），禁止删掉中间行只留首尾。

1. 【参考项目代码 · 由 v2 路径原生驱动】

TRD 的接口路径、出参 envelope（code/message/data 等）、表结构、伪代码风格必须参考 project_path 下的真实项目代码，禁止凭空发明。 v2 生成路径由 context_pack 扫描真实项目并把 route_samples / envelope / db_naming / cache_key_samples 注入 ai_instruction.reference_samples，AI 必须直接采用这些真实样本落笔，不许自创通用样板。同时质检层继续兜底：

• GENERIC_API_PATH：接口全部 /api//... 且项目实际路由不是这种风格 → fail
• RESPONSE_ENVELOPE / RESPONSE_ENVELOPE_CONSISTENCY：出参键与项目响应外壳不一致 → fail

AI 在调用本 skill 时必须把 project_path 传准（这是 context_pack 能抓到真实路由/外壳的前提）。质检报错时不许找借口跳过，只能走 ai_repair_trd 路径按清单定点修复。

17.5. 【禁止野路子自检 · 最终状态判定唯一入口】（最高优先级，MVP 实测暴露） 禁止 AI 用 python3 -c "..."、临时写一段 inline Python、读 quality_check 内部模块再自己拼一份"简化版报告"等任何方式替代 auto_converge / quality_check.py 做最终状态判定。 典型翻车：AI 写了 python3 -c "import json,sys; ..." 发现 "Total failed: 0 / Total checks: 0" 就宣布"通过"——其实根本没跑真质检，是假绿灯。 判定最终状态只有两个合法入口：

• auto_converge.py（带状态机，会自动派 reviewer）；
• quality_check.py（底层硬检，仅用于快速排查单点问题）。

修完任何一批 reviewer issues 或 blocking fail 之后，必须以上述脚本完整 JSON 输出里的 summary.blocking_fail / summary.fail 为准；若来源是 reviewer / trd_review_required，还必须完成 reviewer 复检回流。禁止只挑几条 gate 自测然后宣布通过；禁止在日志里写"修复完成"而没有脚本 JSON 证据；禁止在 lint 通过后停下并让用户“下一步自己再跑 reviewer/auto_converge”。 违反此条 = 等同宣布完成前偷瞄 § 铁律 #18，本次产出作废。

1. 【用户面谈阶段铁律 · auto_converge 收敛后】

auto_converge 自动收敛完成（硬质检 + 独立 reviewer 双闸门均过）后，第一次面对用户时呈上：TRD 路径 + reviewer summary + 一句「有修改意见吗？」。用户回复：

• 「无 / 通过 / ok」→ 直接 done。
• 具体意见 → auto_converge 自己分析是否触发结构性大改（删章节 / 改目录 / 重排结构 / 合并或拆分章节 / 整体重写 等），
• 非结构性意见 → 返回 ai_repair_trd 指令包（structural_guard.mode=structure_locked，严禁删标题/改顺序）。
• 结构性意见 → 返回 ask_user 让用户明文输入「我了解风险，强制结构改动」后才允许改（structural_guard.mode=structural_allowed）。

禁止 AI 自作主张跳过二次确认动结构；禁止 AI 对用户"轻描淡写"把意见私自降级为非结构性再偷偷改。

1. 【禁止偷瞄已有 TRD / 旁路文件】（防作弊铁律）

本 skill 的 TRD 必须完全由 generate_trd.py 基于 prd_path + project_path + knowledge_base_dirs + 用户给的约束生成，不允许任何旁路输入。具体禁令： (a) 禁止 AI 在调用脚本前后 Read / Grep / Glob PRD 同目录、.Agent/、docs/、项目根下任何 *技术方案*.md / *-trd*.md / *-design*.md / TRD*.md 等"看起来像旧 TRD"的文件。 (b) 禁止把 output_path 指向的文件如已存在则先读一遍"参考结构"再覆盖——必须直接覆盖。 (c) 禁止在用户对话中主动提"我看到旁边有一份历史 TRD，要不要参考"。如果用户自己明确说"参考这份历史 TRD"，那也得让用户把路径作为 knowledge_base_dirs 之一传进来，走正规通道，不许走 Read 偷读。 (d) 上游 project-start 传 output_path 进来时，AI 也禁止预先 Read 该路径下的旧文件。 违反此条 = 5 维基线对比作弊，整次产出作废。

1. 【AI 落笔铁律 · v2】（最高优先级，对应 §11 v2 重构）

v2 模式下，generate_trd_from_prd 默认返回 {action: "ai_compose_trd", skeleton, context_pack, skeleton_markdown, section_fill_plan}。上层 AI 必须先落盘 skeleton_markdown，再按 section_fill_plan 分批补齐 TRD，每节都必须严格遵守 4 项输出契约：

• section_fill_plan 类型是 list[dict]，不是 dict。每元素含 batch（int）、sections（兼容字段）、write_units（本批只允许写的最小内容块）、rule（str）。禁止写 section_fill_plan.get(...)（会报 AttributeError: 'list' object has no attribute 'get'）。正确遍历：for plan_batch in section_fill_plan: for unit in plan_batch.get("write_units", []): ...，仅当旧数据没有 write_units 时才回退遍历 sections。需要人工核对结构时：

echo '' | python skills/prd-to-trd/scripts/summarize_v2_generate_trd.py (a) 必含要点不漏：section.must_include_points 列表中的每一条必须在该节正文中明确覆盖，不许跳过、不许"以下省略"、不许糊弄。 (b) 必含图表必嵌：section.must_include_diagrams 列出的图表（mermaid.sequenceDiagram / mermaid.flowchart / mermaid.erDiagram / mermaid.stateDiagram / plantuml.usecase 等）必须用对应语法以 `mermaid 或 `plantuml 代码块嵌入正文，不许用文字"流程图描述"代替。 图表文本语言规范：mermaid / plantuml 图中的节点名、边描述、状态名等大段描述必须用中文（节点里的动作、校验、流转说明一律中文）。只有简单情况可用英文单词或通用缩写（白名单示例：API / DB / Redis / MySQL / ES / MQ / HTTP / JSON / SQL / TTL / UID / ID / OK / NG / UI / RPC / gRPC / CDN / OSS / K8s / QPS / RT）。禁止用英文短语描述业务语义（如 check user login status 必须写成 校验用户登录态；update cache with new data 必须写成 写入最新数据到缓存）。 (c) 引用样本必用：section.reference_samples 给出的真实路由 / envelope keys / 表名 / Redis Key 必须直接采用——接口路径用 route_prefix_dominant 而非 /api/...、出参 envelope 用 global_constraints.envelope_keys 而非默认 code/message/data、表名按 db_naming.style 命名。编造路径或外壳 = 整次产出作废。 (d) 禁止内容必避：section.forbidden 列出的词、前缀、章节名严禁出现；skeleton.banned_sections 列出的章节整章不许写。 (e) doc_type 不许串：写 2C-Backend 不许写"页面与权限"；写 2B-Frontend 不许写"DDL"。看到 banned_sections 自检。 (f) 每次只补齐当前批次的 write_units。大章节拆小块：接口设计按 §5.0 / §5.1 / 单接口 H3 写，页面-接口映射按矩阵和字段核对表写，数据结构按单表/实体写，流程按单流程写，权限/状态机/缓存/导入按单矩阵或单 Key/步骤写；正文生成阶段禁止任何子 Agent / Task / Local Agent / general-purpose Agent，禁止后台生成整篇 TRD；补齐完成后进入 auto_converge 有限收敛。 违反此条 = v2 输出契约破坏，整次产出作废。

1. 【文档独立可读铁律】（最高优先级）

TRD 必须让读者脱离源代码即可完整理解设计，禁止任何形式的"节选 / 示意 / 详见代码"。具体要求： (a) 关键内容禁止节选：数据结构定义（struct / DDL / 字段清单）、核心业务流程、SQL 示例、错误码表、状态机枚举，必须全量写出。禁止出现 // ... 省略其他字段、// 参考 xxx.go、详见代码实现、...（其余略）、// TODO 补充 等节选/占位标记。读者看到文档就能直接理解，不需要跳去查代码。 (b) 接口四要素必须完整：TRD 中每一个接口小节必须同时包含以下四项，缺一即作废重写：

1. 接口路径（Path）：HTTP Method + 完整 URL 路径（method 遵循 collect_http_method_policy 决策）
2. 入参（Request）：字段名 / 类型 / 是否必填 / 含义 / 示例值（通常用表格或 JSON）
3. 出参（Response）：完整 envelope（按 global_constraints.envelope_keys）+ data 内部每个字段的类型与含义（不允许写 data: {...省略}）
4. 错误码（Error Code）：该接口可能返回的全部业务错误码 + 触发条件 + 面向用户的提示文案

质检层以 `APIFOUR

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xurb-nexus
• Source: xurb-nexus/nexus-harness
• License: Apache-2.0
• Homepage: https://xurb-nexus.github.io/nexus-harness/

Install and usage instructions live in the source repository linked above.