在需要完整理解现有代码库并输出带历史上下文的现状研究文档时…

需要跨代码库、thoughts 历史和外部资料回答研究问题，并生成只描述现状的自包含研究文档时使用。

适用场景

解决思路

1. 初始设置：当命令被调用时，先回复：`I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.`，然后等待用户提供研究问题。
2. 只做现状文档：不要建议改进或变更，除非用户明确要求；不要做根因分析，除非用户明确要求；不要提出未来增强，除非用户明确要求；不要批评实现或识别问题；不要推荐重构、优化或架构变更；只描述存在什么、在哪里存在、如何工作以及组件如何交互；创建现有系统的技术地图/文档。
3. 收到研究问题后，先读取任何直接提到的文件：如果用户提到特定文件（tickets、docs、JSON），先完整读取；使用 Read tool 且不要带 limit/offset 参数以读取整个文件；在启动子任务前，在主上下文中亲自读取这些文件；确保在分解研究前拥有完整上下文。
4. 分析并分解研究问题：把用户查询拆成可组合的研究领域；花时间 ultrathink 用户可能寻找的底层模式、连接和架构影响；识别要调查的具体组件、模式或概念；使用 TodoWrite 创建研究计划来跟踪所有子任务；考虑哪些目录、文件或架构模式相关。
5. 启动并行子代理任务进行全面研究：创建多个 Task agents 并发研究不同方面；对于代码库研究，使用 **scout** agent 进行全面代码库探索（结合定位、分析和模式查找）；提醒所有 agents 是文档员，不是批评者，要描述存在的内容，不提出改进或识别问题；对于 thoughts 目录，使用 **thoughts-locator** agent 发现关于主题存在哪些文档；使用 **thoughts-analyzer** agent 从特定文档中提取关键见解（只限最相关的文档）；对于网络研究（仅在用户明确要求时），使用 **web-search-researcher** agent 获取外部文档和资源；如果使用 web-research agents，指示它们随发现返回链接，并在最终报告中包含这些链接；对于 Linear tickets（如果相关），使用 **linear-ticket-reader** agent 获取特定 ticket 的完整详情；使用 **linear-searcher** agent 查找相关 tickets 或历史上下文；智能使用这些 agents：先用 locator agents 找到存在的内容；然后对最有希望的发现使用 analyzer agents 记录它们如何工作；在不同搜索内容时并行运行多个 agents；每个 agent 知道自己的职责，只告诉它你在找什么；不要写关于 HOW to search 的详细提示，agents 已经知道；提醒 agents 它们在文档化，不是评估或改进。
6. 等待所有子代理完成并综合发现：等待所有 sub-agent tasks 完成后再继续；编译所有 sub-agent 结果（代码库和 thoughts 发现）；优先以实时代码库发现为主要事实来源；把 thoughts/ 发现作为补充历史上下文；连接不同组件之间的发现；包含具体文件路径和行号供参考；验证所有 thoughts/ 路径正确（例如个人文件用 thoughts/allison/ 而不是 thoughts/shared/）；突出模式、连接和架构决策；用具体证据回答用户的具体问题。
7. 收集研究文档的元数据：运行 `hack/spec_metadata.sh` 脚本生成所有相关元数据；文件名格式：`thoughts/shared/research/YYYY-MM-DD-ENG-XXXX-description.md`；格式中 YYYY-MM-DD 是今天日期，ENG-XXXX 是 ticket 编号（无 ticket 则省略），description 是研究主题的简短 kebab-case 描述；示例：有 ticket 时 `2025-01-08-ENG-1478-parent-child-tracking.md`，无 ticket 时 `2025-01-08-authentication-flow.md`。
8. 生成研究文档：确保目录存在：`mkdir -p thoughts/shared/research`；使用第 4 步收集的元数据（原文写 step 4，实际第 5 步）；用 YAML frontmatter 后接内容的结构组织文档。
9. 研究文档 YAML frontmatter 结构： --- date: [当前日期和时间，带 ISO 格式时区] researcher: [来自 thoughts status 的研究者名称] git_commit: [当前 commit hash] branch: [当前分支名] repository: [仓库名] topic: "[用户的问题/主题]" tags: [research, codebase, relevant-component-names] status: complete last_updated: [当前日期，YYYY-MM-DD 格式] last_updated_by: [研究者名称] ---
10. 研究文档内容结构： # 研究：[用户的问题/主题] **日期**：[第 4 步中的当前日期和时间，带时区] **研究者**：[来自 thoughts status 的研究者名称] **Git 提交**：[第 4 步中的当前 commit hash] **分支**：[第 4 步中的当前分支名] **仓库**：[仓库名] ## 研究问题 [原始用户查询] ## 摘要 [高层级现状文档，通过描述存在什么来回答用户问题] ## 详细发现 ### [组件/领域 1] - 存在内容的描述 ([file.ext:line](link)) - 它如何连接到其他组件 - 当前实现细节（不做评价） ### [组件/领域 2] ... ## 代码引用 - `path/to/file.py:123` - 那里有什么的描述 - `another/file.ts:45-67` - 代码块的描述 ## 架构文档 [代码库中发现的当前模式、约定和设计实现] ## 历史上下文（来自 thoughts/） [来自 thoughts/ 目录的相关见解和引用] - `thoughts/shared/something.md` - 关于 X 的历史决策 - `thoughts/local/notes.md` - 过去对 Y 的探索 注意：路径排除 "searchable/"，即使是在那里找到的 ## 相关研究 [指向 thoughts/shared/research/ 中其他研究文档的链接] ## 待解决问题 [任何需要进一步调查的领域]
11. 添加 GitHub permalinks（如果适用）：检查是否在 main 分支或 commit 已推送：运行 `git branch --show-current` 和 `git status`；如果在 main/master 或已推送，生成 GitHub permalinks：运行 `gh repo view --json owner,name` 获取仓库信息；创建 permalinks：`https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`；在文档中把本地文件引用替换为 permalinks。
12. 呈现发现：向用户呈现简洁的发现摘要；包含关键文件引用以便导航；询问他们是否有后续问题或需要澄清。
13. 处理后续问题：如果用户有后续问题，追加到同一研究文档；更新 frontmatter 字段 `last_updated` 和 `last_updated_by` 以反映更新；在 frontmatter 中添加 `last_updated_note: "Added follow-up research for [brief description]"`；添加新章节：`## Follow-up Research [timestamp]`；根据需要启动新的 sub-agents 进行额外调查；继续更新文档并同步。
14. 始终使用并行 Task agents 以最大化效率并最小化上下文使用。
15. 始终运行新鲜的代码库研究——绝不只依赖现有研究文档。
16. thoughts/ 目录提供历史上下文以补充实时发现。
17. 专注于找到具体文件路径和行号供开发者参考。
18. 研究文档应自包含，包含所有必要上下文。
19. 每个 sub-agent prompt 应具体且专注于只读文档操作。
20. 记录跨组件连接和系统如何交互。
21. 包含时间上下文（研究进行的时间）。
22. 尽可能链接到 GitHub 以提供永久引用。
23. 保持主 agent 专注于综合，而不是深度文件阅读。
24. 让 sub-agents 记录存在的示例和使用模式。
25. 探索整个 thoughts/ 目录，而不仅仅是 research 子目录。
26. CRITICAL：你和所有 sub-agents 是文档员，不是评估者。
27. REMEMBER：记录 what IS，而不是 what SHOULD BE。
28. NO RECOMMENDATIONS：只描述代码库的当前状态。
29. 文件阅读：在启动 sub-tasks 前，始终完整读取提到的文件（无 limit/offset）。
30. 关键顺序：始终在启动 sub-tasks 前先读取提到的文件（第 1 步）。
31. 关键顺序：始终等待所有 sub-agents 完成后再综合（第 4 步）。
32. 关键顺序：始终在写文档前收集元数据（第 5 步在 第 6 步之前）。
33. 关键顺序：绝不用占位符值写研究文档。
34. 路径处理：thoughts/searchable/ 目录包含用于搜索的硬链接。
35. 路径处理：始终通过仅移除 "searchable/" 来记录路径——保留所有其他子目录。
36. 路径处理示例：`thoughts/searchable/allison/old_stuff/notes.md` → `thoughts/allison/old_stuff/notes.md`
37. 路径处理示例：`thoughts/searchable/shared/prs/123.md` → `thoughts/shared/prs/123.md`
38. 路径处理示例：`thoughts/searchable/global/shared/templates.md` → `thoughts/global/shared/templates.md`
39. 路径处理：绝不把 allison/ 改成 shared/ 或反之——保留精确目录结构。
40. 路径处理：这确保路径对编辑和导航正确。
41. Frontmatter 一致性：始终在研究文档开头包含 frontmatter。
42. Frontmatter 一致性：在所有研究文档中保持 frontmatter 字段一致。
43. Frontmatter 一致性：添加后续研究时更新 frontmatter。
44. Frontmatter 一致性：多词字段名使用 snake_case（例如 `last_updated`、`git_commit`）。
45. Frontmatter 一致性：标签应与研究主题和研究的组件相关。

适用边界 · 注意事项

• 当目标不是记录现状，而是评估实现、识别问题、做根因分析、提出改进/重构/优化/架构变更或未来增强时；除非用户明确要求，否则不要按此技能执行。
• 当项目缺少 thoughts/ 历史目录、Task/子代理机制、scout/thoughts-locator/thoughts-analyzer/web-search-researcher/linear-*-reader 等专用 agents 或 `hack/spec_metadata.sh` 时，不应套用完整流程。
• 当用户没有明确要求外部网络研究时，不要使用 web-search-researcher 做外部资料检索。