Research Compound

Compound learnings into folder-specific AGENTS.md files during research work.

Trigger Conditions

Activate this behavior when:

• Investigating a specific domain (jobs, models, services, controllers, etc.)

• Using research agents (repo-analyst, docs-researcher, etc.)

• Reading multiple files in the same folder hierarchy

• User asks to "understand", "investigate", or "research" a subsystem

Pre-Research: Check Existing Context

Before diving into code, find and read the nearest 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

From existing AGENTS.md, note:

• Known patterns and conventions

• Documented gotchas

• File organization rules

• Testing approaches

• Previous learnings (avoid re-discovering)

Pre-Research Output

Briefly acknowledge:

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

After research, evaluate each discovery:

Worth Recording (YES)

Criteria Example

Applies to multiple files in domain "All jobs inherit from ApplicationJob"

Non-obvious convention "Jobs must call super before custom logic"

Gotcha that caused confusion "CashApp jobs require merchant_id, not user_id"

Integration pattern "Jobs trigger webhooks via WebhookService"

Testing insight "Use freeze_time for scheduled job specs"

Skip Recording (NO)

Criteria Example

One-off implementation detail "ProcessPaymentJob has 3 retries"

Already documented Pattern exists in AGENTS.md

Too specific to single file "Line 42 has a TODO"

Obvious from code "Job processes payments"

Update Protocol

Step 1: Locate Target AGENTS.md

Use nearest-wins hierarchy:

• If {domain}/AGENTS.md exists → update it

• If not, check parent folder

• If no AGENTS.md in hierarchy → create at domain level

Find existing AGENTS.md files

find . -name "AGENTS.md" -type f | head -20

Step 2: Determine Section

Map learning type to section:

Learning Type Target Section

Pattern/Convention

Patterns

or ## Conventions

Gotcha/Warning

Gotchas

or ## Common Issues

File organization

Structure

Testing approach

Testing

Integration point

Integration

or ## Dependencies

If section doesn't exist, create it.

Step 3: Format the Learning

• [Short title]: [Concrete description]
  • Example: path/to/example.rb:42

Keep entries:

• Single bullet point (1-2 lines)

• Concrete, not vague

• With file reference when applicable

Step 4: Append (Don't Replace)

Use Edit tool to append to appropriate section:

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

If no AGENTS.md exists in the domain hierarchy, create one:

{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 (if 3+ files)

app/services/payments/

app/services/payments/AGENTS.md

Only create subfolder AGENTS.md if:

• 3+ files in that specific folder

• Distinct patterns from parent domain

• Significant complexity warranting isolation

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

Before updating AGENTS.md, verify:

• Learning is generalizable (applies beyond single file)

• Not already documented

• Concrete enough to act on

• Has file reference for examples

• Matches existing AGENTS.md style/structure

Best Practices Research

When research requires external best practices (not just codebase analysis), use this methodology.

Research Process

• Clarify the query - Identify the technology AND version (ask if not provided)

• Search with version specificity - Always include version in queries (e.g., "Rails 8 API authentication" not "Rails authentication")

• Use Perplexity MCP (mcp__perplexity-ask__perplexity_ask ) to search for:

• Official documentation for [technology] [version]

• "[technology] [version] best practices [current year]"

• Well-regarded open source examples

• Evaluate sources - Prioritize: official docs > widely-adopted standards > community guides

• Note version-specific guidance - Flag when practices apply only to certain versions

Best Practices Output Format

[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]

Research Constraints

• Research only -- do not implement or write code

• Cite everything -- no unsourced recommendations

• Note conflicts -- if sources disagree, present both views with trade-offs

• Be current -- flag outdated practices explicitly

Anti-Patterns

Don't Do Instead

Dump all findings into AGENTS.md Filter for generalizable patterns only

Create AGENTS.md for every folder Only domains with distinct patterns

Write paragraphs Single bullet points with examples

Duplicate root-level guidance Only domain-specific additions

Update on every file read Batch updates at research completion