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 — 追踪关系与约束

• 至少追踪一条与修改相关的入口 → 核心逻辑 → 下游依赖或持久化路径。
• 只读取与任务相关的注册点、配置、权限、中间件、数据模型、迁移和测试。