用途
Pre-Work Research 用于在开始实现之前进行调研，帮助开发者先理解代码库与文档的全貌，再动手修改。其核心原则是“Measure twice, cut once”（量两次，切一次）。技能要求在开始时声明：“I'm researching the codebase and documentation before implementing.”（我正在实现之前调研代码库和文档。）
何时需要调研
技能给出了不同情境下的调研需求：
- 不熟悉的代码区域：需要调研
- 新库或 API：需要调研
- 复杂集成：需要调研
- 性能敏感代码：需要调研
- 安全敏感代码：需要调研
- 简单、孤立的改动：最少调研
调研协议
技能定义了六个步骤：
Step 1：理解需求 在调研实现之前，阅读完整的 issue 描述、审查所有验收标准、记录提到的任何约束、识别未知项。
Step 2：研究仓库文档 通过命令查看项目概览、架构/设计文档、贡献指南和 API 文档，例如：
# Project overview
cat README.md
# Architecture/design docs
ls -la docs/
find . -name "*.md" -path "./docs/*"
# Contributing guidelines
cat CONTRIBUTING.md
# API documentation
cat docs/api*.md
cat docs/architecture*.md
需要寻找：架构决策、使用的设计模式、编码约定、测试要求、部署注意事项。
Step 3：研究现有代码库 查找相似实现、理解模式、检查可用工具。示例命令包括：
# Find similar features
grep -r "similar keyword" src/
# Find related tests
grep -r "similar keyword" **/*.test.*
# Find imports of relevant modules
grep -r "import.*ModuleName" src/
理解模式时，查看 2-3 个相似功能的示例。例如添加 API 端点时：
grep -r "router\." src/routes/
cat src/routes/[existing-endpoint].ts
添加服务时：
ls -la src/services/
cat src/services/[existing-service].ts
检查工具：
ls -la src/utils/
cat src/utils/[relevant-util].ts
grep -r "export function" src/utils/
Step 4：研究外部资源 使用外部 API 或库时，查阅官方文档、API 参考和社区资源。命令示例：
pnpm info [package-name]
然后访问文档 URL，搜索“[library-name] documentation”、“[library-name] getting started”、“[library-name] [specific feature]”。对于外部 API，需关注：认证要求、速率限制、错误处理、响应格式、版本管理。社区资源包括 GitHub issues、Stack Overflow、博客文章。
Step 5：记录发现 创建调研摘要，格式如下：
## Pre-Work Research: Issue #[NUMBER]
### Requirements Understanding
- [Key requirement 1]
- [Key requirement 2]
### Codebase Patterns
- Pattern for [X]: See `src/example/pattern.ts`
- Utilities available: `src/utils/helper.ts`
- Test pattern: See `src/example/example.test.ts`
### External Dependencies
- [Library]: [Key findings]
- [API]: [Authentication method, rate limits]
### Approach
Based on research, the approach is:
1. [Step 1]
2. [Step 2]
3. [Step 3]
### Risks/Considerations
- [Risk 1]
- [Consideration 1]
Step 6：更新 Issue（如有重要发现） 如果调研揭示了重要上下文，使用命令更新 issue：
gh issue comment [ISSUE_NUMBER] --body "## Pre-Implementation Research
### Approach
[Summary of planned approach]
### Considerations
- [Important finding 1]
- [Important finding 2]
### Questions (if any)
- [Question needing clarification]
"
按任务规模决定调研深度
- 琐碎任务（拼写错误、配置）：无需调研
- 小任务（单文件）：快速模式检查
- 中等任务（功能）：完整协议
- 大任务（系统）：扩展调研
快速模式检查（5 分钟）：
grep -r "pattern" src/ | head -5
cat src/similar/example.ts | head -50
完整协议（15-30 分钟）：完成上述步骤 1-6。
扩展调研（1 小时以上）：阅读所有相关文档、追踪现有实现、必要时创建概念验证、记录架构考量。
需要关注的内容
在文档中关注：架构图（理解系统结构）、编码标准（匹配现有风格）、决策记录（理解为何如此实现）、API 契约（保持兼容性）。
在代码库中关注：相似功能（遵循既有模式）、测试模式（编写一致的测试）、错误处理（一致地处理错误）、日志模式（适当地记录日志）。
在外部资源中关注：官方示例（使用推荐模式）、常见陷阱（避免已知问题）、性能提示（适当优化）、安全指南（安全实现）。
调研输出
调研后，应当了解：相似功能如何实现、应遵循什么模式、有哪些可用工具、测试方法应是什么、任何风险或特殊注意事项。
检查清单
开始实现之前：
- Issue 需求已理解
- 仓库文档已检查
- 相似代码模式已找到
- 相关工具已识别
- 外部资源已调研（如适用）
- 方案已记录
- Issue 已更新（如有重要发现）
集成
该技能被以下技能调用：
- issue-driven-development - Step 5
该技能为以下技能提供信息：
- tdd-full-coverage - 如何编写测试
- strict-typing - 使用什么类型模式
- inline-documentation - 文档模式