feature-discovery

功能探索

功能探索会追踪现有功能、模块或行为的运作方式，并在聊天中给出附有证据引用的报告：让另一位工程师了解它是什么、如何运作、在哪里使用，以及还有哪些不确定之处。

输入

输入可以是结构化的——Projects Affected: 加上一个 What: 区块——也可以是自由形式；请推断涉及的项目和主题。仅在会阻碍进展时才提问澄清；如果用户不在，则说明假设并尽力继续。

规则

• 不添加任何署名。 任何输出中都不得添加或保留共同作者、AI 或工具署名。
• 只读，仅限聊天。 探索期间不得编辑代码、配置、文档、原生记忆、ADR、提示词、问题或生成的产物——GLOSSARY.md 和产物编辑须等到步骤 7 获批后再进行。绝不创建 docs/discovery/ 文件；除非用户指定，否则不要读取旧版探索文件——这些文件可能已过时。不得执行 git fetch、git pull、安装、迁移或破坏性命令。
• 非变更式验证。 默认进行静态检查。只有确认项目或测试命令不会更改文件或本地／外部状态后，才执行这些命令。否则应报告未运行的检查，而不是声称检查通过。仅凭干净的 git status，无法证明忽略的文件或数据库未发生变化。
• 以当前代码为准。 证据顺序：优先当前代码、测试和配置；其次为 ADR。代码用于确认已实现的行为；ADR 和已批准的需求用于记录预期行为。两者冲突时都要引用；实现不匹配不等于规则已获批准修改。由模拟、夹具或桩数据提供的路径不属于已实现行为；应明确说明。区分证据与推断，绝不编造理由。警示信号：为了匹配一个可能的错误而改写业务规则。
• Git 历史须获准后才能查看。 探索期间绝不查看；可在报告中提出扫描建议（步骤 7）。
• 追踪行为，而不只是符号。 通过带引用的链接或明确指出缺口，串联入口点、相关条件、状态变更、调用方和下游影响。标出相似路径之间复用的衔接点。警示信号：罗列符号，却没有使用位置或用户可见的影响。
• 范围保持精简。 将宽泛的输入拆分；指出首个切片和延后处理的切片。回答范围内的问题或在验证后报告证据缺口，即可停止；超出当前上下文的未完成工作需要拆分范围或交接。警示信号：未明确转向就偏离到产品探索或实验设计。
• 报告呈现后即停止。 建议下一项技能，但绝不调用它，也不在收到新请求前开始实施。仍可通过讨论厘清的未知事项应作为待决事项留给 /feature-prompt 或 /grill-with-field；无法通过讨论厘清的事项（“需要感受／看到效果”）应转交给 /handoff + /prototype（已安装时；否则直白说明不确定性）。若目标或开放问题仍模糊，应建议使用 /wayfinder，而不是 /feature-prompt；无法拨开迷雾就无法编写适用于 PR 的提示词。
• 每次阶段转换时输出 Stage / Found / Next / Needs user——每个字段各占一行。阶段：已解析、已追踪代码、已验证、报告。
• 子 Agent：对独立工作自动派发本地工作流——绝不使用云端 Agent；派发时宣布工作流数量，并在每个工作流完成时报告。返回摘要，而非逐字记录；综合分析留在主会话中。

工作流

1. 解析并定位

列出要回答的问题。使用仓库名称、元数据或 README，将项目代码对应到 Git 根目录和软件包边界。记录已检查的修订版本／工作树状态以及开始时的 git status；保留现有更改。无法映射的项目应明确列为缺口，同时继续范围内的工作。

确定 <artifacts-root>：如果存在 *.code-workspace 文件，则使用其所在目录；否则使用上下文对应的根目录（仓库根目录中的 GLOSSARY-MAP.md；旧版 CONTEXT-MAP.md）；再否则使用仓库根目录。

2. 追踪当前代码

先搜索精确术语，再搜索别名、路由、组件、配置键、环境变量、表、作业、标志和测试；先用 rg，查找代码库证据时优先使用 CLI，再使用 MCP。对于不明确的依赖项，只读检查可用的源代码或上游官方源。需要下载或安装才能获取的源代码属于已报告的缺口，并应建议后续跟进。

3. 阅读 ADR

在 <artifacts-root> 和映射的项目中，查找与主题相关的 ADR（位于 docs/adr/、docs/decisions/，或由 GLOSSARY.md、代码注释引用）。记录每个 ADR 的状态（已接受、已取代、提议中），以及当前代码是否与之相符。若未找到 → 说明查找过的位置。

4. 有界阅读问题，或者完全不读

阅读用户指定的问题，或能够解决实质性缺口的问题；如果用户未要求查看问题，且本地证据已能回答问题，则标记为无需审查跟踪系统；不要请求批准进行广泛扫描。阅读每个有界问题及其评论；使用精确术语或可靠标签进行有界搜索。将每次查询限定在其映射的仓库／跟踪系统中（默认使用 gh issue view <n> --comments；工作区跟踪系统映射优先）。如果实质性缺口需要无界扫描，请说明成本并事先征求同意。若扫描遭拒、不可用或未获回复 → 跳过该扫描，说明限制，并继续可进行的有界工作。

5. 跟踪候选上下文术语

将发现的领域术语与 GLOSSARY.md 进行比较——优先查看 <artifacts-root> 中的文件，否则查看附近的项目文档——并标记缺失、过时、已重命名、多义或含义模糊的术语。只有存在候选术语时，才加载 references/context-terms.md，了解其筛选、呈现和审批要求。如果没有候选术语，用一行说明即可。

6. 验证两次

第 1 轮：根据所用的代码、测试、配置和上下文，逐项交叉核对答案。第 2 轮：使用别名和反向查找，寻找可能相互矛盾的路径。断定代码未使用之前，请检查相关的间接注册、路由、监听器、标志、导入路径别名和动态构造的名称（模板字符串 URL、拼接的键）；仅在生成文件或构建输出（dist/、build/、生成的客户端）中找到的匹配项不能作为源代码证据；没有匹配项只能说明在已搜索范围内未找到。根据已实现和预期的行为验证术语；标记归属、测试和证据方面的缺口。逐一处理每个问题：有证据支持的已回答、注明缺失证据的未解决，或明确延期到本次范围之外。

7. 提交报告并停止

如果第 2 步留下了一个关于原因或时间的问题，第 8 节结尾应提出查看历史记录：说明问题、已追踪的文件，以及最近 2 个月的时间范围。只有收到新的明确同意后才进行扫描；扫描仅限只读（git log、git show、git blame；如需查找更早的证据，可扩展为有针对性的查询），并以简短补充说明作答，同时指出已追踪文件上是否有重复的修复提交。

对于报告后的 GLOSSARY.md 或其他文档更新：列出每个目标路径、拟议文本及理由；等待明确批准，然后按照 references/context-terms.md 中的 Applying approved updates 执行（谨慎处理：未收到回复 → 不做编辑；候选术语保留在报告中）。

输出

使用下方编号结构，每节不超过 3 个项目符号；目标约 550 字，不得遗漏答案或注意事项。Quick trace 适用于简单的单项目答案，不存在实质性分支、上下文候选项或冲突的情况——而不只是问题提到了一个符号。请在开头声明使用 Quick trace，并采用第 1–3、5 和 9 节（第 5 节写一行），其他部分标为 N/A。在第 1–3 节中纳入用户要求的用法和理由。否则使用完整报告；不得缩略多项目发现。

各节按顺序排列：1 摘要 · 2 功能 · 3 工作原理 · 4 使用位置 · 5 ADR · 6 需求背景／上下文 · 7 候选 GLOSSARY.md 术语 · 8 风险、差距和建议的后续检查 · 9 已执行的验证 · 10 建议的后续技能（可选，1–3 项）。完整报告请加载 references/report-template.md；Quick trace 使用符合条件的上述章节，无需加载完整模板。

证据格式。 引用 文件:行号，或文件名加符号及其作用。跨项目报告中，路径须标明 PROJECT-CODE，问题须标明所属仓库／跟踪系统，不得只写 #123；提交记录须包含仓库、短哈希和日期。区分已检查的源代码、已检查的测试、已执行的检查、运行时观察、ADR 文本和推断。源代码中的默认值不能证明部署配置。仅引用实际运行命令所得的关键输出；对于未执行的检查，须说明跳过了哪些检查；对于否定性结论，须说明搜索范围。

完成标准

• 第 1–9 节中的每项事实性陈述均按证据格式附有引用
• 每个用户提出的问题都有基于证据的回答、明确指出的证据缺口，或明确的范围暂缓说明
• 已比较开始和结束时的 git status；保留现有更改；已执行的命令符合非变更规则（获准的第 7 步更新除外）
• 用户接受第 8 节中的提议之前，不得运行任何 Git 历史命令
• 完整报告须按编号顺序编写（第 10 节可选）；符合条件的 Quick trace 须包含第 1–3、5 和 9 节
• 若包含第 7 节，结尾须给出四选一的审批请求，或说明没有候选项
• 报告完成后停止会话——不得调用技能，也不得开始实施