| name | context-detective |
| description | Ground codebase work in task-relevant repository evidence. Use before planning or changing unfamiliar, multi-file, or high-risk behavior when dependencies, conventions, reuse opportunities, integration points, or blast radius are uncertain. Skip precise low-risk edits. Report unresolved uncertainty instead of guessing.
|
Context Detective — 上下文侦探
在计划或修改代码前，建立“足够且相关”的事实基础。优先明确结果、约束和完成标准，允许模型自行选择当前环境可用的搜索与读取工具。
适用场景
- 任务涉及陌生模块、多文件协作或隐含依赖
- 需要新增文件、依赖、数据结构、公共 API 或集成点
- 错误来源、调用关系、现有惯例或影响范围尚不清楚
不适用
- 用户给出了精确文件、精确修改和明确验证方式，且风险很低
- 拼写、文案、格式或其他不改变行为的局部修改
- 本轮已经完成探索，且任务范围和关键假设没有变化
调查深度
按“不确定性 × 影响范围 × 不可逆性”决定深度，不按文件数量机械分类。
| 深度 | 使用条件 | 最低要求 |
|---|
| 跳过 | 精确、低风险、无未知依赖 | 直接执行并做局部验证 |
| 聚焦 | 单模块 Bug 或局部行为变更 | 读取目标实现、直接关系和相关测试 |
| 标准 | 新功能或多文件修改 | 再确认类似实现、集成点和项目约束 |
| 深入 | 数据、认证、安全、公共 API、跨模块或架构变更 | 追踪关键契约、失败路径和完整影响面 |
工作流
1. Scope — 锁定任务切片
- 从用户给出的文件、符号、错误、测试、日志或 diff 开始，不先扫描整个仓库。
- 明确期望行为、不可改变的边界和完成标准；只调查可能改变方案的未知信息。
- 修改任务先检查工作区状态，区分用户已有改动与本次任务范围。
- 遵守已加载的仓库规则；涉及子目录时，确认是否存在更近的作用域规则。
2. Retrieve — 获取候选证据
- 先做路径、符号、错误文本和引用的精确搜索；术语模糊或仓库较大时，再使用可用的语义检索。
- 将语义结果视为候选，读取实际源码、配置或文档后才能作为事实。
- 优先读取最相关的少量文件；多个读取彼此独立且平台支持时可以并行。
- 搜索同职责、同层级或相似行为的实现，复用其模式，不复制其偶然细节。
3. Trace — 追踪关系与约束
- 至少追踪一条与修改相关的入口 → 核心逻辑 → 下游依赖或持久化路径。
- 只读取与任务相关的注册点、配置、权限、中间件、数据模型、迁移和测试。
- 识别可复用组件、外部契约、失败路径以及可能受影响的调用者。
- 不把常见框架惯例当作项目事实；以仓库中的实际实现为准。
4. Decide — 对齐方案
- 说明最可能修改或新增的资源、应复用的模式、必须遵守的约束和验证方式。
- 将结论区分为：Fact（已读取证据）、Inference（基于证据推断）、Unknown（仍缺信息）。
- Unknown 只有在会实质改变方案或造成高风险时才询问用户；否则明确假设并继续。
Evidence Gates
- 新建文件或组件前，确认不存在同职责实现，并找到命名与目录惯例。
- 引入或推荐依赖前，检查依赖声明、锁定文件和现有用法。
- 修改数据结构前，读取实际 Schema、模型和迁移机制。
- 修改 API、认证、权限或配置前，读取真实注册点与执行链。
- 修改行为前，确认相关调用者、测试或最小复现；无法验证时说明原因与替代检查。
- 涉及时效性强或仓库外事实时，使用当前可用的权威来源，不依赖记忆。
停止与输出
当以下问题都有可执行答案时停止探索：改哪里、复用什么、受哪些约束、如何验证、还剩哪些实质风险。若继续搜索只会补充背景而不会改变决策，也应停止。
- 实现任务：将探索结果用于后续工作，只向用户报告会改变方案、范围或风险的发现。
- 计划、审查或调研任务：输出简短
Context Brief，包含相关事实、影响面、复用/约束、验证方式和 Unknown。
- 除非用户明确要求，不生成完整项目百科、逐条工具日志或独立 Context Artifact。
- 引用证据时优先给出文件路径和符号；行号仅在有助于复核时提供。
Checklist
常见错误
| 错误 | 修正 |
|---|
| 为了“了解项目”读取所有依赖和目录 | 从任务线索开始，按风险向外扩展 |
| 写死某个平台的搜索工具名 | 描述所需能力，使用当前环境可用工具 |
| 将语义搜索结果直接当作事实 | 打开实际文件确认实现与上下文 |
| 强制每次输出完整调查报告 | 默认内部消化，只输出影响决策的信息 |
用 VERIFIED 掩盖未知信息 | 明确标注 Fact、Inference 和 Unknown |
