research-compound

Research Compound

調査作業中に学びをまとめ、フォルダーごとの AGENTS.md ファイルに記録します。

Trigger Conditions

次の場合にこの動作を有効にします：

• 特定のドメイン（ジョブ、モデル、サービス、コントローラーなど）を調査する
• 調査エージェント（repo-analyst、docs-researcher など）を使用する
• 同じフォルダー階層内の複数のファイルを読む
• ユーザーがサブシステムの「理解」「調査」「リサーチ」を依頼する

Pre-Research: Check Existing Context

コードを詳しく調べる前に、最も近い 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)

What to Extract

既存の AGENTS.md から次の点を確認します：

• 既知のパターンと規約
• 記載されている注意点
• ファイル構成のルール
• テスト方法
• 過去の学び（再発見を避ける）

Pre-Research Output

簡潔に確認したことを伝えます：

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

Post-Research: Evaluate Learnings

調査後、それぞれの発見を評価します：

Worth Recording (YES)

Criteria	Example
ドメイン内の複数ファイルに適用される	"すべてのジョブは ApplicationJob を継承する"
自明ではない規約	"ジョブは独自のロジックを実行する前に super を呼び出す必要がある"
混乱の原因となった注意点	"CashApp のジョブには user_id ではなく merchant_id が必要"
統合パターン	"ジョブは WebhookService 経由でウェブフックをトリガーする"
テストに関する知見	"スケジュールされたジョブのスペックには freeze_time を使う"

Skip Recording (NO)

Criteria	Example
一度限りの実装詳細	"ProcessPaymentJob は3回再試行する"
すでに記載されている	パターンが AGENTS.md に存在する
単一ファイルに限定されすぎている	"42行目に TODO がある"
コードを見れば明らか	"ジョブは支払いを処理する"

Update Protocol

Step 1: Locate Target AGENTS.md

最も近いものを優先する階層を使用します：

1. {domain}/AGENTS.md が存在する場合 → それを更新する
2. 存在しない場合は、親フォルダーを確認する
3. 階層内に AGENTS.md がない場合 → ドメイン階層に作成する

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

Step 2: Determine Section

学びの種類に応じてセクションを決めます：

Learning Type	Target Section
パターン／規約	## Patterns または ## Conventions
注意点／警告	## Gotchas または ## Common Issues
ファイル構成	## Structure
テスト方法	## Testing
統合箇所	## Integration または ## Dependencies

該当するセクションがない場合は作成します。

Step 3: Format the Learning

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

記載内容は次のとおりです：

• 箇条書き1つ（1～2行）
• 具体的で、曖昧でないこと
• 該当する場合はファイル参照を付けること

Step 4: Append (Don't Replace)

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`

Creating New 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

Placement Rules

Domain Depth	Create At
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つ以上ある
• 親ドメインとは異なるパターンがある
• 分離する価値のある複雑さがある

Examples

Example 1: Pre-Research Check

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

Example 2: Post-Research Update

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`

Example 3: Creating New 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

Quality Checks

AGENTS.md を更新する前に、次の点を確認します：

• 学びが一般化できる（単一ファイルを超えて適用される）
• すでに記載されていない
• 実際の行動に移せるほど具体的である
• 例にファイル参照がある
• 既存の AGENTS.md のスタイル／構成に合っている

Best Practices Research

調査で外部のベストプラクティスが必要な場合（コードベースの分析だけではない場合）は、この方法論を使用します。

調査プロセス

1. クエリを明確にする - 技術とバージョンを特定します（指定されていない場合は尋ねます）
2. バージョンを明示して検索する - クエリには必ずバージョンを含めます（例：「Rails 8 API authentication」。単に「Rails authentication」としないでください）
3. Perplexity MCP（mcp__perplexity-ask__perplexity_ask）を使って、次の項目を検索します。
   • [技術] [バージョン] の公式ドキュメント
   • 「[技術] [バージョン] best practices [現在の年]」
   • 評価の高いオープンソースの例
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を作成する	独自のパターンがあるドメインだけに作成します
段落を書く	例を添えた箇条書きにします
ルートレベルのガイダンスを重複させる	ドメイン固有の追加事項だけを記載します
ファイルを読むたびに更新する	調査の完了時にまとめて更新します