Context Detective — 上下文侦探

在生成任何内容（需求、设计、计划、代码）之前，按 DNA → Trace → Align 三阶段收集上下文，产出经过验证的 Context Artifact。

用户请求只是冰山一角 (10%)，代码库才是水下的 90%。忽略水下部分会导致：

• 重复造轮子：重新实现已有的工具类
• 风格不一致：项目用 fetch 却引入 axios
• 隐性回归：破坏隐藏的依赖关系

适用场景

• 开始任何非平凡任务之前
• 创建新文件之前（先查重）
• 遇到不熟悉的领域术语时
• 编写需求、设计或计划之前

不适用

• 单行修改、拼写修正等平凡任务
• 当前对话中已执行过 Context Detective 且任务范围未变
• 用户明确指定了文件路径和修改内容的精确指令

深度控制

根据任务规模选择调查深度，避免分析瘫痪：

终止条件：如果 Phase 2 搜索超过 3 轮仍无新收获，停止并在 Artifact 中记录"信息不足，需人工确认"。

语言速查表

先识别项目语言，再按对应列查找关键文件和惯例：

操作步骤

Phase 1: DNA 分析 — 识别项目骨架

读取，不要猜测。先用 Glob 在项目根目录查找依赖文件，确定语言和技术栈，再按语言速查表定位关键文件。

1. 语言识别 — 用 Glob 查找根目录的依赖文件，确定项目语言
   • Glob("pom.xml") / Glob("go.mod") / Glob("package.json") / Glob("pyproject.toml")
   • 注意：可能是多语言项目（如 Java 后端 + JS 前端），需逐一识别
2. 依赖清单 — 用 Read 读取对应的依赖文件，确认安装了哪些库
   • 确认：用了哪些框架？版本号是什么？有无锁定文件？
3. 配置文件 — 用 Read 读取配置文件（参考语言速查表），识别约束和惯例
   • 确认：有哪些环境约束？路径别名？运行模式？
4. 目录结构 — 用 Glob 探索 2-3 层目录，识别架构模式
   • Java: Glob("src/main/java/**") | Go: Glob("cmd/**"), Glob("internal/**") | JS: Glob("src/**") | Python: Glob("app/**") 或 Glob("src/**")
   • 确认：分层方式？业务逻辑位置？共享模块在哪？

Phase 2: 语义追踪 — 追踪关系和模式

超越关键词匹配，追踪依赖关系。

1. 关键词扩展 — 对用户提到的概念，用 Grep 和 SemanticSearch 搜索同义词和关联术语
   • 用户说"订单管理" → 搜索 Order, 订单, Purchase, Cart, 交易
   • 用 Grep 做精确匹配，用 SemanticSearch 做语义发现
2. 依赖链追踪 — 对找到的核心实体，用 Grep 追踪引用：
   • 找 调用者（参考语言速查表的"入口/路由"行）
   • 找 被调用者（参考语言速查表的"数据层"行，以及外部 API、工具类）
   • 画出变更的爆炸半径（哪些文件会受影响）
3. 双胞胎功能 — 用 SemanticSearch 找一个已有的、模式相似的功能作为参照
   • 要建"文档评论"？先看"任务评论"怎么做的
   • 复制模式（命名、分层、错误处理），而非代码
   • 降级策略：如果找不到模式相似的功能：
     • 退而求其次：找同层级任意一个完整模块作为结构参照
     • 或在 Artifact 中记录："无可参照的已有功能，需从零设计模式"

Phase 3: 差距对齐 — 叠加需求到现实

1. 集成点审计 — 用 Read 读取实际内容：
   • 数据库：Schema / Migration / ORM 模型定义
   • 路由：API 注册文件 / 路由表（参考语言速查表的"入口/路由"行）
   • 配置：权限 / 中间件 / 菜单配置
2. 复用验证 — 创建任何新东西之前先用工具确认：
   • 用 Glob 搜索常见工具类目录（参考语言速查表的"常见工具类目录"行）
   • 用 Grep 确认："现有文件的命名惯例是什么？"
3. 约束识别 — 记录硬约束：
   • 认证模式、分页方式、错误处理惯例、日志模式
   • 测试框架、代码风格（Linter / Formatter 配置）、部署方式

产出模板

完成三个阶段后，产出以下结构化 Artifact（所有事实均须通过工具读取确认，非假设）：

# Context Artifact
> **Module**: [模块名]
> **Date**: YYYY-MM-DD
> **Status**: VERIFIED — 所有事实均通过工具读取确认

## 1. Project DNA
- **语言/版本**: [如 Java 17 / Go 1.22 / TypeScript 5.x / Python 3.12]
- **框架**: [如 Spring Boot 3.x / Gin / Next.js 14 / FastAPI]
- **构建工具**: [如 Maven / go build / pnpm / Poetry]
- **架构模式**: [如 Controller → Service → Repository]
- **数据库**: [如 PostgreSQL + Prisma / MySQL + MyBatis-Plus / MongoDB + Mongoose]
- **测试框架**: [如 JUnit 5 / go test + testify / Vitest / pytest]
- **关键库**: [列出核心依赖]

## 2. 相关现实
- **核心实体**: [实体名, 文件路径, 行号]
- **API 模式**: [端点结构方式]
- **类似功能**: [可作为参照的已有功能，含路径]
- **可复用组件**: [已存在的可复用 Service/组件/工具类/包]

## 3. 差距
- [ ] [需要创建的]
- [ ] [需要修改的]
- [ ] [需要扩展的]

## 4. 风险与约束（下游阶段必须遵守）
1. [硬约束，如：认证必须使用 xxx 方式]
2. [风格约束，如：错误处理必须遵循 xxx 模式]
3. [性能约束，如：接口响应时间 < 200ms]

## 5. 验证记录
| 工具 | 命令/参数 | 验证了什么 |
|------|-----------|-----------|
| Read | `[依赖文件]` | 确认框架版本 |
| Grep | `"[核心类/函数名]"` | 确认核心实体已存在 |
| Glob | `[目录模式]` | 确认文件结构 |
| SemanticSearch | "[语义查询]" | 发现相关实现 |

各语言验证记录示例：

QA 自检清单

产出 Artifact 后，切换到 Fact Checker 视角进行自检。任何一项不通过则必须补充调查。

DNA 检查

• 框架感知：是否确认了项目实际使用的框架？（而非假设）
• 依赖感知：是否在建议引入新库之前检查了依赖文件？
• 风格对齐：提议的方案是否与项目现有风格一致？

语义追踪检查

• 关系映射：是否找到了关联文件，而不仅是精确关键词匹配？
• 双胞胎功能：是否找到了可作为模式参照的已有功能？
• 爆炸半径：是否识别了变更可能影响的范围？

差距对齐检查

• 路径验证：所有文件路径均通过工具确认存在？
• 集成点验证：是否读取了 Schema / 路由 / 配置的实际内容？
• 查重验证：是否确认没有创建已存在的组件？

否决条件（出现以下任一情况需退回重做）

• "建议使用 X 库，但依赖文件中并没有 X"
• "假设 src/utils/api.ts 存在，但未验证"
• "创建了新组件，但同名组件已存在"
• "未读取 Schema/Migration 就提出了数据模型变更"

与其他技能的关系

本技能是语言无关的前置技能，产出的 Context Artifact 可直接输入到需求分析、设计和计划阶段。

当识别到项目语言后，联动对应的领域技能：

铁律

常见错误