research-compound

Research Compound

在研究过程中，将研究所得整理到特定文件夹的 AGENTS.md 文件中。

触发条件

在以下情况下启用此行为：

• 调查特定领域（任务、模型、服务、控制器等）
• 使用研究 Agent（repo-analyst、docs-researcher 等）
• 阅读同一文件夹层级中的多个文件
• 用户要求“了解”“调查”或“研究”某个子系统

研究前：检查现有上下文

在深入代码之前，找到并阅读最近的 AGENTS.md：

# From target folder, traverse up to find nearest AGENTS.md
# Example: researching app/jobs/cash_app/
# Check: app/jobs/cash_app/AGENTS.md
#        app/jobs/AGENTS.md
#        app/AGENTS.md
#        AGENTS.md (root)

提取内容

从现有 AGENTS.md 中记录：

• 已知模式和约定
• 已记录的注意事项
• 文件组织规则
• 测试方法
• 以往的研究所得（避免重复发现）

研究前输出

简要确认：

Found existing context in app/jobs/AGENTS.md:
- Jobs use Sidekiq with retry configuration
- Naming: *Job suffix required
- Testing: Use perform_inline in specs

研究后：评估研究所得

研究完成后，评估每项发现：

值得记录（是）

标准	示例
适用于该领域中的多个文件	“所有任务都继承自 ApplicationJob”
不明显的约定	“任务必须在自定义逻辑之前调用 super”
导致困惑的注意事项	“CashApp 任务需要 merchant_id，而非 user_id”
集成模式	“任务通过 WebhookService 触发 Webhook”
测试方面的经验	“使用 freeze_time 编写计划任务的测试”

跳过记录（否）

标准	示例
一次性的实现细节	“ProcessPaymentJob 会重试 3 次”
已有记录	AGENTS.md 中已存在此模式
过于具体，仅适用于单个文件	“第 42 行有一个 TODO”
从代码中一目了然	“任务处理付款”

更新流程

第 1 步：定位目标 AGENTS.md

采用就近优先层级：

1. 如果 {domain}/AGENTS.md 存在 → 更新该文件
2. 如果不存在，检查父文件夹
3. 如果层级中没有 AGENTS.md → 在领域目录层级创建

# Find existing AGENTS.md files
find . -name "AGENTS.md" -type f | head -20

第 2 步：确定章节

将研究所得的类型映射到章节：

研究所得类型	目标章节
模式/约定	## Patterns 或 ## Conventions
注意事项/警告	## Gotchas 或 ## Common Issues
文件组织	## Structure
测试方法	## Testing
集成点	## Integration 或 ## Dependencies

如果章节不存在，则创建该章节。

第 3 步：整理研究所得

- **[Short title]**: [Concrete description]
  - Example: `path/to/example.rb:42`

记录条目应：

• 使用单个项目符号（1-2 行）
• 具体明确，避免含糊
• 适用时附上文件引用

第 4 步：追加（不要替换）

使用 Edit 工具将内容追加到相应章节：

## Gotchas

- **Existing gotcha**: Description
- **NEW: Merchant ID required**: CashApp jobs use `merchant_id`, not `user_id`
  - Example: `app/jobs/cash_app/process_payment_job.rb:15`

创建新的 AGENTS.md

如果领域层级中不存在 AGENTS.md，则创建一个：

# {Domain Name}

## Purpose

{One-line description of this domain}

## Patterns

- **Pattern name**: Description
  - Example: `path/to/file.rb`

## Gotchas

- **Gotcha name**: Description

## Testing

- **Testing approach**: Description

放置规则

领域深度	创建位置
app/jobs/	app/jobs/AGENTS.md
app/jobs/cash_app/	app/jobs/cash_app/AGENTS.md（如果有 3 个或更多文件）
app/services/payments/	app/services/payments/AGENTS.md

仅在以下情况下创建子文件夹 AGENTS.md：

• 该文件夹中有 3 个或更多文件
• 与父领域存在不同的模式
• 复杂度较高，有必要单独管理

示例

示例 1：研究前检查

User: "Investigate how background jobs work in this app"

Claude:
1. Target domain: app/jobs/
2. Check for AGENTS.md...
   - Found: app/jobs/AGENTS.md
3. Read existing context:
   "Jobs use Sidekiq, ApplicationJob base class, *Job suffix"
4. Proceed with research, avoiding re-discovery of known patterns

示例 2：研究后更新

After researching app/jobs/cash_app/:

Discovered:
- CashApp jobs require merchant_id (not user_id) ← WORTH RECORDING
- ProcessPaymentJob has 3 retries ← SKIP (too specific)
- All CashApp jobs log to separate channel ← WORTH RECORDING

Update app/jobs/cash_app/AGENTS.md:
## Gotchas
+ - **Merchant ID required**: Use `merchant_id`, not `user_id` for CashApp jobs
+   - Example: `app/jobs/cash_app/process_payment_job.rb:15`

## Patterns
+ - **Separate logging**: CashApp jobs use `CashAppLogger` channel
+   - Example: `app/jobs/cash_app/base_job.rb:8`

示例 3：创建新的 AGENTS.md

Researching app/services/webhooks/ (no existing AGENTS.md)

After research, create app/services/webhooks/AGENTS.md:

# Webhooks

## Purpose

Outbound webhook delivery and retry management.

## Patterns

- **Delivery service**: All webhooks go through `WebhookDeliveryService`
  - Example: `app/services/webhooks/delivery_service.rb`
- **Payload builders**: Each event type has a `*PayloadBuilder`
  - Example: `app/services/webhooks/payment_payload_builder.rb`

## Gotchas

- **Idempotency required**: Webhooks may retry; receivers must handle duplicates
- **Timeout**: 30-second timeout on delivery attempts

质量检查

更新 AGENTS.md 之前，请确认：

• 研究所得可泛化（适用于单个文件以外的范围）
• 尚未记录
• 足够具体，可据此采取行动
• 示例附有文件引用
• 符合现有 AGENTS.md 的风格和结构

最佳实践研究

如果研究需要外部最佳实践（而非仅分析代码库），请使用此方法。

研究流程

1. 明确查询内容 - 确定技术及其版本（未提供时请询问）
2. 按版本精确搜索 - 查询中始终包含版本（例如，搜索“Rails 8 API authentication”，而不是“Rails authentication”）
3. 使用 Perplexity MCP（mcp__perplexity-ask__perplexity_ask）搜索：
   • [技术] [版本] 的官方文档
   • “[技术] [版本] 最佳实践 [当前年份]”
   • 备受认可的开源示例
4. 评估来源 - 优先级：官方文档 > 广泛采用的标准 > 社区指南
5. 注明版本特定指导 - 标明仅适用于特定版本的实践

最佳实践输出格式

## [Topic] Best Practices

### Must Have
- **[Practice name]**: [Description]
  > "[Direct quote from source]"
  -- Source: [Link or reference]

### Recommended
- **[Practice name]**: [Description]

### Anti-patterns to Avoid
- **[Anti-pattern]**: [Why it's problematic]

### Sources
- [All referenced sources with links]

研究约束

• 仅做研究 —— 不要实现或编写代码
• 引用所有内容 —— 不提供无来源的建议
• 注明冲突 —— 如果来源意见不一，请呈现双方观点及其权衡
• 保持内容最新 —— 明确标记过时的实践

反模式

不要	应改为
将所有发现一股脑写入 AGENTS.md	仅筛选可泛化的模式
为每个文件夹都创建 AGENTS.md	仅为具有独特模式的领域创建
写成段落	使用带示例的单条项目符号
重复根目录级指导	仅补充领域特定内容
每读一个文件就更新	在研究完成时批量更新