| 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】；顺序执行（不并发）：
- 若有文本源：Read 并执行 text.md
- 若有代码仓库 1..N：依次 Read 并执行 code.md（每次执行前写入
【code-source: {仓库名}】，code.md 读取此标记在多源模式下标注断言来源）
- 所有适配器完成后，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「统一交接块格式」章节。
多模块任务：按模块逐个处理，每个模块完成后立即输出该模块的交接块，不等全部模块完成后再统一输出。
