context-detective

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

• 调查范围与任务直接相关，而不是泛读仓库
• 关键结论来自已读取的源码、配置、测试或权威文档
• 已检查类似实现、直接关系和必要集成点
• 已区分 Fact、Inference 和 Unknown
• 已达到停止条件，并能说明验证方式

常见错误

错误	修正
为了“了解项目”读取所有依赖和目录	从任务线索开始，按风险向外扩展
写死某个平台的搜索工具名	描述所需能力，使用当前环境可用工具
将语义搜索结果直接当作事实	打开实际文件确认实现与上下文
强制每次输出完整调查报告	默认内部消化，只输出影响决策的信息
用 VERIFIED 掩盖未知信息	明确标注 Fact、Inference 和 Unknown