Qa From Trd

qa-from-trd

> 框架不可变铁律（复用自 AGENTS.md 第 7 条） > 本 SKILL.md 及其 scripts/ 等框架文件在"使用本 skill"过程中只读。 > 发现 bug 必须立刻停下，向用户报告，由用户决定是否开新会话修。

本 skill 不在主菜单出现，有两个模式：

• script：由 nexus qadoc 命令触发，Python 交互选项目并生成脚本版 Markdown。
• agent：由隐藏 intent qadocs 触发，宿主 Agent 对话选项目，Python 只生成 qa_case_ir.json 交接包，再由宿主 Agent 生成正式 QA 文档。

核心设计

通过 4 层来源推导 QA 参考信息，但正文只展开高价值重点 Case；常规冒烟、参数校验、普通错误码覆盖降级为清单。若没有额外重点 Case，文档必须明确说明“本期无额外重点建议”。

1. Layer 1 显性 Case：每个接口的必填校验、格式、分页、错误码、响应外壳
2. Layer 2 规则反推 Case：根据 TRD 关键词（分表、缓存、JSON 解析、排序等）触发模板 case
3. Layer 3 链路依赖 Case：从伪代码/时序图抽 dependency_chain，推导前置步骤影响最终字段的 case
4. Layer 4 隐性风险 Case：结合项目规范（AIWeave docs）扫描命名漂移、只读边界、缓存安全等

script 模式 Markdown 目录保持简洁：

1. 接口与依赖
2. 建议重点验证

失败不阻塞

生成失败时返回 exit 3 并在 summary 里提示，不阻塞 TRD → Plan 主链路。

Agent 模式流程（隐藏 qadocs）

触发词：用户输入 qadocs、生成 QA 测试设计、生成 QA 测试文档。不要把它展示到 nexus 1–6 主菜单。

1. 运行 scripts/discover_diagnose_targets.py 的非交互发现能力，按 signals.has_trd=true 过滤候选；用对话让用户选 bucket 和项目。禁止调用 qadoc.py 的 _ask_bucket / _pick_project，它们只服务终端脚本模式。
2. 选定项目后，可调用隐藏 CLI 交接包：nexus qadocs --project-dir 。它只会生成 qa_case_ir.json 并打印 PRD/TRD/IR/输出路径 JSON，不调用模型。
3. Read references/qadocs-agent-prompt.md、PRD、TRD、qa_case_ir.json；可选读取 aiweave_context.json 或业务项目 docs/INDEX.md。
4. 先构建 PRD ↔ TRD ↔ Docs ↔ Case 的内部映射，再覆盖写入 -QA-doc.agent.md。每次 qadocs 运行都必须覆盖旧 Agent 版 Markdown，禁止追加、合并或保留旧内容。
5. 按 prompt 的质量门禁自检，覆盖写入 qa_doc_agent_review.json。
6. 回写 context：

``bash python3 skills/qa-from-trd/scripts/_core/update_context.py \ --context \ --qa-md -QA-doc.agent.md \ --qa-ir /qa_case_ir.json \ --agent-mode ``

Agent 模式必须保留脚本版产物不覆盖。若已存在 -QA-doc.md，只覆盖 -QA-doc.agent.md 与 qa_doc_agent_review.json。

Agent 版正文应面向 QA 执行，默认结构为：

1. 接口契约速查
2. QA 重点摘要
3. 核心 Case
4. 补充信息（仅有内容时保留）

不要输出独立的“范围与证据源”大章或“PRD / TRD / Docs 对齐摘要”大章；证据应下沉到接口契约、QA 重点摘要和核心 Case。接口契约速查必须保留 Method + Path、关键入参、关键出参、错误码、依赖和关联核心 Case。

核心 Case 是 Agent 模式的主要价值：必须说明“为什么是核心 Case”，并显式写证据标签（如 PRD + TRD + Docs + 自动化价值）。优先保留 PRD + TRD 同时命中的 Case；纯 TRD 技术 Case 可以保留，但必须标注“TRD 专属技术 Case”并说明数据一致性、事务、幂等或链路风险。边界、异常、并发、缓存、事务类内容只有被判定为核心时才放入核心 Case，否则放入补充信息或省略。补充信息没有实际内容时整章不输出。

Agent 模式必须做精准度自检：核心 Case 预期必须唯一；测试步骤不得先触发其它错误码从而遮蔽目标断言；TRD 未证明的唯一约束、数据级幂等、锁超时安全性或补偿机制必须标为“设计风险 / 待确认项”，不能伪装成已确定 Case。IR 中的表头污染字段、无分页接口的分页 Case、与“不写缓存”冲突的 HIT-after-MISS Case 必须拒绝。

缓存安全规则

• 不设计"写后即读缓存"的验证 case（违反项目缓存铁律）
• Redis BYPASS / HIT / MISS 三路必须覆盖
• TTL 过期后行为必须有 case

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.