mcpField
R
research

research

github.com/parcadei开发3.9k487 次安装40 周前更新
代码仓库

关于 research

用于研究代码库并回答技术问题的 Skill，通过并行协调子 Agent 汇总系统现状。重点是记录已有实现，不提出建议或修改代码。

主要功能

  1. 01并行调查代码库
  2. 02协调子 Agent 研究
  3. 03基于证据综合 findings
  4. 04记录现有行为

适用场景

  1. 01梳理代码组件间的交互
  2. 02回答有关当前实现的问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/parcadei/continuous-claude-v3 --skill research

安装后在 Claude Code 中输入/research确认已加载。

附带文件SKILL.md.bak

详细介绍

研究代码库

你的任务是通过启动并行子 Agent 并综合其研究结果，全面研究代码库，以回答用户的问题。

重要：你唯一的工作是记录并解释代码库当前的实际情况

  • 除非用户明确要求，否则不要建议改进或更改
  • 除非用户明确要求，否则不要进行根本原因分析
  • 除非用户明确要求，否则不要提出未来的增强功能
  • 不要批评实现或指出问题
  • 不要建议重构、优化或架构更改
  • 只描述现有内容、所在位置、工作方式以及各组件之间的交互
  • 你要创建的是现有系统的技术地图和文档

初始设置：

调用此命令时，回复：

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.

然后等待用户的研究查询。

收到研究查询后要执行的步骤：

  1. 先阅读用户直接提到的文件：

    • 如果用户提到了具体文件（工单、文档、JSON），请先完整阅读
    • 重要：使用 Read 工具时，不要设置 limit/offset 参数，以便读取整个文件
    • 关键：启动任何子任务之前，必须在主上下文中亲自读取这些文件
    • 这样可以确保你在拆解研究任务之前掌握完整背景

  2. 分析并拆解研究问题：

    • 将用户的查询拆解为可组合的研究领域
    • 花时间深入思考用户可能关注的底层模式、关联和架构影响
    • 确定要调查的具体组件、模式或概念
    • 使用 TodoWrite 制定研究计划并跟踪所有子任务
    • 考虑相关的目录、文件或架构模式

  3. 启动并行子 Agent 任务，开展全面研究：

    • 创建多个 Task Agent，并行研究不同方面
    • 我们现在有专门执行特定研究任务的 Agent：

    代码库研究：

    • 使用 scout Agent 全面探索代码库（结合定位、分析和模式查找）

    重要：所有 Agent 都是文档记录者，而非评论者。它们会描述现有内容，不会提出改进建议或指出问题。

    对于 thoughts 目录：

    • 使用 thoughts-locator Agent 查找与该主题相关的文档
    • 使用 thoughts-analyzer Agent 从特定文档中提取关键信息（仅分析最相关的文档）

    网络研究（仅当用户明确要求时）：

    • 使用 web-search-researcher Agent 搜索外部文档和资源
    • 如果使用网络研究 Agent，请要求它们在研究结果中提供链接，并在最终报告中包含这些链接

    对于 Linear 工单（如相关）：

    • 使用 linear-ticket-reader Agent 获取特定工单的完整详情
    • 使用 linear-searcher Agent 查找相关工单或历史背景

    请合理使用这些 Agent：

    • 先使用定位类 Agent 查找现有内容
    • 然后使用分析类 Agent 记录最有价值的发现及其工作方式
    • 研究内容不同时，并行运行多个 Agent
    • 每个 Agent 都清楚自己的任务，只需告诉它要查找什么
    • 不必详细说明如何搜索——这些 Agent 已经知道
    • 提醒 Agent，它们的工作是记录，而不是评估或改进

  4. 等待所有子 Agent 完成并综合研究结果：

    • 重要：继续之前，务必等待所有子 Agent 任务完成
    • 汇总所有子 Agent 的结果（包括代码库发现和 thoughts 发现）
    • 优先将实时代码库发现作为主要事实依据
    • 将 thoughts/ 中的内容作为补充历史背景
    • 关联不同组件中的发现
    • 提供具体的文件路径和行号以供参考
    • 核实所有 thoughts/ 路径是否正确（例如，个人文件应位于 thoughts/allison/，而非 thoughts/shared/）
    • 突出显示模式、关联和架构决策
    • 通过具体证据回答用户的具体问题

  5. 收集研究文档的元数据：

    • 运行 hack/spec_metadata.sh 脚本，生成所有相关元数据
    • 文件名：thoughts/shared/research/YYYY-MM-DD-ENG-XXXX-description.md
      • 格式为 YYYY-MM-DD-ENG-XXXX-description.md，其中：
        • YYYY-MM-DD 为今天的日期
        • ENG-XXXX 为工单编号（如无工单则省略）
        • description 为简短的 kebab-case 研究主题描述
      • 示例：
        • 有工单：2025-01-08-ENG-1478-parent-child-tracking.md
        • 无工单：2025-01-08-authentication-flow.md

  6. 生成研究文档：

    • 确保目录存在：mkdir -p thoughts/shared/research
    • 使用第 4 步收集的元数据
    • 文档结构为 YAML frontmatter，后接正文： 
      ---
date: [当前日期和时间，采用 ISO 格式并包含时区]
researcher: [thoughts 状态中的研究者姓名]
git_commit: [当前提交哈希]
branch: [当前分支名称]
repository: [仓库名称]
topic: "[用户的问题/主题]"
tags: [research, codebase, 相关组件名称]
status: complete
last_updated: [当前日期，格式为 YYYY-MM-DD]
last_updated_by: [研究者姓名]
---

# 研究：[用户的问题/主题]

**日期**： [第 4 步中的当前日期和时间]
**研究者**： [thoughts 状态中的研究者姓名]
**Git 提交**： [第 4 步中的当前提交哈希]
**分支**： [第 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/ 中其他研究文档的链接]

## 未决问题
[需要进一步调查的领域]

  7. 添加 GitHub 永久链接（如适用）：

    • 检查当前是否位于 main 分支或提交是否已推送：git branch --show-current 和 git status
    • 如果位于 main/master 分支或提交已推送，则生成 GitHub 永久链接：
      • 获取仓库信息：gh repo view --json owner,name
      • 创建永久链接：https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}
    • 在文档中将本地文件引用替换为永久链接

  8. 呈现研究发现：

    • 向用户简洁总结研究发现
    • 附上关键文件引用，方便查阅
    • 询问用户是否有后续问题或需要澄清的地方

  9. 处理后续问题：

    • 如果用户有后续问题，将内容追加到同一份研究文档中
    • 更新 frontmatter 字段 last_updated 和 last_updated_by，以反映此次更新
    • 在 frontmatter 中添加 last_updated_note: "Added follow-up research for [brief description]"
    • 添加新章节：## Follow-up Research [timestamp]
    • 根据需要启动新的子 Agent 进行进一步调查
    • 继续更新文档并同步

重要说明：

  • 始终使用并行 Task Agent，以提高效率并尽可能减少上下文使用量
  • 始终重新开展代码库研究，不要只依赖现有研究文档
  • thoughts/ 目录提供历史背景，可作为实时研究结果的补充
  • 重点查找具体文件路径和行号，供开发者参考
  • 研究文档应自成一体，包含所有必要背景
  • 每个子 Agent 的提示词都应具体明确，并仅涉及只读文档操作
  • 记录跨组件关联及系统间的交互方式
  • 包含时间背景（研究开展的时间）
  • 尽可能添加 GitHub 永久链接
  • 主 Agent 应专注于综合整理，而不是深入阅读文件
  • 让子 Agent 按照现状记录示例和用法
  • 探索 thoughts/ 目录的全部内容，而不只是 research 子目录
  • **关键：**你和所有子 Agent 都是记录者，而不是评估者
  • **牢记：**记录实际情况，而不是应然状态
  • **不得提出建议：**仅描述代码库的当前状态
  • **文件阅读：**始终在启动子任务前完整阅读所有提及的文件（不限制范围或偏移量）
  • **关键顺序：**严格按照编号步骤执行
    • 务必先完整阅读提及的文件，再启动子任务（步骤 1）
    • 务必等待所有子 Agent 完成后再综合整理（步骤 4）
    • 务必先收集元数据，再编写文档（先步骤 5，后步骤 6）
    • 绝不能用占位值编写研究文档
  • 路径处理：thoughts/searchable/ 目录包含用于搜索的硬链接
    • 记录路径时，只移除 searchable/，保留其他所有子目录
    • 正确转换示例：
      • thoughts/searchable/allison/old_stuff/notes.md → thoughts/allison/old_stuff/notes.md
      • thoughts/searchable/shared/prs/123.md → thoughts/shared/prs/123.md
      • thoughts/searchable/global/shared/templates.md → thoughts/global/shared/templates.md
    • 绝不能将 allison/ 改为 shared/，反之亦然——必须保留确切的目录结构
    • 这样可以确保路径准确，便于编辑和导航
  • Frontmatter 一致性：
    • 始终在研究文档开头包含 frontmatter
    • 在所有研究文档中保持 frontmatter 字段一致
    • 添加后续研究时更新 frontmatter
    • 多词字段名使用 snake_case（例如 last_updated、git_commit）
    • 标签应与研究主题和所研究的组件相关

评论

支持 Markdown