qa-understand

name	qa-understand
description	测试意图理解与提炼。将任意信息源转化为可测试的理解，写入 story，供 qa-functional-test 和 qa-case-review 使用。 调度层设计：按需加载对应适配器，不预加载所有内容。 内置适配器：文本（PRD/需求/口述）、代码（文件/目录/片段，支持 N 个代码仓库）。 多源时顺序执行各适配器（文本适配器完成后依次执行各代码适配器），完成后加载综合层产出统一交接块。 由 qalore 调用，不独立触发。
practices_min_version	2026-06-12-v11

qa-understand：测试意图理解与提炼

前置说明

变量	来源	fallback
{practices_path}	qalore 注入	自动恢复：读 ~/.claude/qalore-config.json 重建 context
{story_path}	qalore 注入	自动恢复：读 ~/.claude/qalore-config.json 重建 context
{确认项目名}	qalore 注入	暂停，向用户重新确认

不得用猜测值继续执行。

---

三驱动认知框架

在加载任何适配器之前建立的认知姿态，全程有效。与适配器各自的领域思考哲学共同构成完整认知体系：三驱动回答「为什么读、何时停、如何识别边界」，适配器回答「如何从这种信息源中提取可测试行为」。

假设优先 读任何信息源前，先用一句话假设这个模块「做什么、谁触发、影响什么」。 读是在验证和修正假设，不是从零积累信息。 停止读的条件：假设中所有已知的系统交互都有了来源证据。 读的认知目标：以测试为目的——完整理解功能行为（为验证类测试提供基础），同时识别潜在风险点（为异常类测试提供方向）。两者都不能偏废。

模型驱动：每读一段，问——这证实还是推翻了假设的哪个部分？

证据驱动：每条论断必须有来源。任何「我认为是这样的」都是待验证假设，不是断言。

边界驱动：每个系统交互都有两端。遇到边界时判断另一端是否已知：

• 已知 → 记录边界关系 [模块::组件/功能点]
• 未知且对理解当前模块行为关键 → 主动寻找另一端（具体追踪深度由各适配器声明）
• 未知且不关键 → 写入待确认项，标注「链路断点」

产出断言前 产出断言前，问一个问题：我的模型里有没有悬空的端点？ （描述了某行为但没有来源；或看到了外部调用但不知道另一端） 有悬空端点 → 补读或标注待确认；没有 → 可以产出。

---

渐进式阅读策略

适用于任何大型信息源，与信息类型无关。

第一阶段：导航（建地图，成本极低） 用最低代价扫描信息结构，建立「这里有什么、在哪里」的地图。不做深度理解，只做位置定位。

第二阶段：切片精读（按问题，成本按需） 每次精读操作针对地图中的一个语义单元，回答假设中的一个开放问题。语义单元 = 该信息源中最小自包含逻辑块，由各适配器声明。

Agent 使用任何可用手段完成导航（搜索、目录遍历、语义检索、文件扫描…），本框架不限定工具。

渐进式阅读策略控制「同一个文件内如何读」（导航→切片精读），各适配器的「信息范围层级」章节控制「哪些文件允许读、按什么顺序读」——两者正交。示例：层级 1 允许读智能体管理 BL 文件 → 先用导航阶段扫描其 6 个功能点节头 → 后对含"创建者"字样的节做切片精读（而非全量 Read）。

---

适配器注册表

按需加载对应适配器，不预加载所有内容。

适配器基础路径： ~/.claude/skills/qalore/capability/qa-understand/adapters/

信息源类型	触发信号	适配器文件	写入目标
需求文档 / PRD / 口述 / URL	用户提供文档或需求描述，或描述含「沉淀/提炼/分析/记录/更新业务逻辑」	adapters/text.md	{模块名}-功能-业务逻辑.md
代码文件 / 目录 / 片段（单个或多个仓库）	用户提供代码路径或片段，或描述含「读代码/阅读代码/代码逻辑/更新代码逻辑」	adapters/code.md（每个仓库运行一次）	{模块名}-功能-代码逻辑.md
（可扩展）	—	—	—

加载规则：

每个模块处理开始前，先在 context 写入当前模式标记（覆盖上一个模块的旧标记）：

• 单源（仅文本或仅单个代码仓库） → 写入 【qa-understand-mode: single】；Read 对应适配器文件，按其协议独立执行
• 多源（文本 + 代码，或多个代码仓库） → 写入 【qa-understand-mode: multi】；顺序执行（不并发）：
  1. 若有文本源：Read 并执行 text.md
  2. 若有代码仓库 1..N：依次 Read 并执行 code.md（每次执行前写入 【code-source: {仓库名}】，code.md 读取此标记在多源模式下标注断言来源）
  3. 所有适配器完成后，Read adapters/synthesis.md 产出统一交接块
  • assert_seq 续接：每个适配器完成 ID 分配后立即更新 index.json 的 assert_seq，下一个适配器直接从 index.json 读取续接起点，不依赖 context 标记传递
• 未注册类型 → 告知用户不支持，提供扩展路径：注册表新增行 + 新建适配器文件

---

执行前确认

遵循 handbook.md「执行前确认规范」章节。本 capability 的计划摘要格式：

【测试意图理解执行计划】
项目：{确认项目名}
模块：{模块名}
信息源：
  · 文本（{来源描述}，操作：{新建/patch}）          ← 文本源时
  · 代码（{仓库名}，{路径}，depth={N}，操作：{新建/patch}）← 每个代码源单独列一行
综合层：{多源时：是 / 单源时：否}
外部依赖断点（有则列出，无则省略）：
  · {依赖名称}（位置：{代码路径}）—— 能否提供代码或配置？
规范版本：{practices version}

---

统一交接块格式（所有适配器的输出契约）

无论单源或多源，最终向 qa-functional-test 和 qa-case-review 输出统一格式。格式定义、字段声明、置信度标注规则见 {practices_path}/tech-stacks/functional/story-formats.md「统一交接块格式」章节。

多模块任务：按模块逐个处理，每个模块完成后立即输出该模块的交接块，不等全部模块完成后再统一输出。