Back to Details

research-compound

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Research Compound

研究成果整合

Compound learnings into folder-specific AGENTS.md files during research work.
将研究过程中的学习成果整合到特定文件夹的AGENTS.md文件中。

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
在以下情况触发该行为：
  • 研究特定领域（如任务、模型、服务、控制器等）
  • 使用研究Agent（如repo-analyst、docs-researcher等）
  • 读取同一文件夹层级中的多个文件
  • 用户要求“理解”“调研”或“研究”某个子系统

Pre-Research: Check Existing Context

研究前：检查现有上下文

Before diving into code, find and read the nearest AGENTS.md:
bash
undefined
在深入研究代码之前，找到并读取最近的AGENTS.md：
bash
undefined

From target folder, traverse up to find nearest AGENTS.md

从目标文件夹开始，向上遍历查找最近的AGENTS.md

Example: researching app/jobs/cash_app/

示例：研究app/jobs/cash_app/

Check: app/jobs/cash_app/AGENTS.md

检查：app/jobs/cash_app/AGENTS.md

app/jobs/AGENTS.md

app/jobs/AGENTS.md

app/AGENTS.md

app/AGENTS.md

AGENTS.md (root)

AGENTS.md (根目录)

undefined
undefined

What to Extract

需要提取的内容

From existing AGENTS.md, note:
  • Known patterns and conventions
  • Documented gotchas
  • File organization rules
  • Testing approaches
  • Previous learnings (avoid re-discovering)
从现有AGENTS.md中记录：
  • 已知的模式和约定
  • 已记录的注意事项
  • 文件组织规则
  • 测试方法
  • 之前的研究成果（避免重复发现）

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
简要确认：
在app/jobs/AGENTS.md中找到现有上下文：
- 任务使用Sidekiq并配置重试机制
- 命名规则：必须以*Job为后缀
- 测试：在测试用例中使用perform_inline

Post-Research: Evaluate Learnings

研究后：评估研究成果

After research, evaluate each discovery:
研究完成后，评估每个发现：

Worth Recording (YES)

值得记录（是）

CriteriaExample
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"
判定标准示例
适用于该领域的多个文件"所有任务都继承自ApplicationJob"
非显而易见的约定"任务必须在自定义逻辑前调用
super
"
易造成混淆的注意事项"CashApp任务需要merchant_id，而非user_id"
集成模式"任务通过WebhookService触发Webhook"
测试见解"在定时任务测试用例中使用
freeze_time
"

Skip Recording (NO)

无需记录（否）

CriteriaExample
One-off implementation detail"ProcessPaymentJob has 3 retries"
Already documentedPattern exists in AGENTS.md
Too specific to single file"Line 42 has a TODO"
Obvious from code"Job processes payments"
判定标准示例
一次性实现细节"ProcessPaymentJob有3次重试机会"
已在文档中记录模式已存在于AGENTS.md中
仅针对单个文件的细节"第42行有一个TODO注释"
从代码中可直接看出"任务处理支付"

Update Protocol

更新流程

Step 1: Locate Target AGENTS.md

步骤1：定位目标AGENTS.md

Use nearest-wins hierarchy:
  1. If 
    {domain}/AGENTS.md
    exists → update it
  2. If not, check parent folder
  3. If no AGENTS.md in hierarchy → create at domain level
bash
undefined
采用“最近优先”层级规则：
  1. 若
    {domain}/AGENTS.md
    已存在 → 更新该文件
  2. 若不存在，检查父文件夹
  3. 若层级中无AGENTS.md → 在领域层级创建
bash
undefined

Find existing AGENTS.md files

查找现有AGENTS.md文件

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

Step 2: Determine Section

步骤2：确定章节

Map learning type to section:
Learning TypeTarget 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.
将研究成果类型映射到对应章节：
研究成果类型目标章节
模式/约定
## Patterns
或 
## Conventions
注意事项/警告
## Gotchas
或 
## Common Issues
文件组织
## Structure
测试方法
## Testing
集成点
## Integration
或 
## Dependencies
若对应章节不存在，则创建该章节。

Step 3: Format the Learning

步骤3：格式化研究成果

markdown
- **[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
markdown
- **[简短标题]**: [具体描述]
  - 示例：`path/to/example.rb:42`
保持条目：
  • 单个项目符号（1-2行）
  • 具体明确，而非模糊描述
  • 如有适用，附带文件引用

Step 4: Append (Don't Replace)

步骤4：追加（而非替换）

Use Edit tool to append to appropriate section:
markdown
undefined
使用编辑工具将内容追加到对应章节：
markdown
undefined

Gotchas

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
undefined
  • 已有的注意事项: 描述
  • 新增：需要商家ID: CashApp任务使用
    merchant_id
    ，而非
    user_id
    • 示例：
      app/jobs/cash_app/process_payment_job.rb:15
undefined

Creating New AGENTS.md

创建新的AGENTS.md

If no AGENTS.md exists in the domain hierarchy, create one:
markdown
undefined
若领域层级中无AGENTS.md，则创建新文件：
markdown
undefined

{Domain Name}

{领域名称}

Purpose

用途

{One-line description of this domain}
{该领域的一行描述}

Patterns

Patterns

  • Pattern name: Description
    • Example: 
      path/to/file.rb
  • 模式名称: 描述
    • 示例：
      path/to/file.rb

Gotchas

Gotchas

  • Gotcha name: Description
  • 注意事项名称: 描述

Testing

Testing

  • Testing approach: Description
undefined
  • 测试方法: 描述
undefined

Placement Rules

放置规则

Domain DepthCreate 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
领域深度创建位置
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

示例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
用户：“调研这个应用中后台任务的工作方式”

Claude:
1. 目标领域：app/jobs/
2. 检查AGENTS.md...
   - 找到：app/jobs/AGENTS.md
3. 读取现有上下文：
   “任务使用Sidekiq、ApplicationJob基类，必须以*Job为后缀”
4. 开始研究，避免重复发现已知模式

Example 2: Post-Research Update

示例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:
在研究app/jobs/cash_app/后：

发现：
- CashApp任务需要merchant_id（而非user_id） ← 值得记录
- ProcessPaymentJob有3次重试机会 ← 无需记录（过于具体）
- 所有CashApp任务记录到独立日志通道 ← 值得记录

更新app/jobs/cash_app/AGENTS.md：

Gotchas

Gotchas

    • Merchant ID required: Use 
      merchant_id
      , not 
      user_id
      for CashApp jobs
    • Example: 
      app/jobs/cash_app/process_payment_job.rb:15
    • 需要商家ID: CashApp任务使用
      merchant_id
      而非
      user_id
    • 示例：
      app/jobs/cash_app/process_payment_job.rb:15

Patterns

Patterns

    • Separate logging: CashApp jobs use 
      CashAppLogger
      channel
    • Example: 
      app/jobs/cash_app/base_job.rb:8
undefined
    • 独立日志: CashApp任务使用
      CashAppLogger
      通道
    • 示例：
      app/jobs/cash_app/base_job.rb:8
undefined

Example 3: Creating New AGENTS.md

示例3：创建新的AGENTS.md

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

After research, create app/services/webhooks/AGENTS.md:
研究app/services/webhooks/（无现有AGENTS.md）

研究完成后，创建app/services/webhooks/AGENTS.md：

Webhooks

Webhooks

Purpose

用途

Outbound webhook delivery and retry management.
出站Webhook的交付与重试管理。

Patterns

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
  • 交付服务: 所有Webhook都通过
    WebhookDeliveryService
    处理
    • 示例：
      app/services/webhooks/delivery_service.rb
  • 负载构建器: 每种事件类型都有对应的
    *PayloadBuilder
    • 示例：
      app/services/webhooks/payment_payload_builder.rb

Gotchas

Gotchas

  • Idempotency required: Webhooks may retry; receivers must handle duplicates
  • Timeout: 30-second timeout on delivery attempts
undefined
  • 需要幂等性: Webhook可能重试，接收方必须处理重复请求
  • 超时设置: 交付尝试的超时时间为30秒
undefined

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
在更新AGENTS.md之前，验证：
  • 研究成果具有通用性（适用于多个文件）
  • 未在现有文档中记录
  • 具体到可执行
  • 附带示例文件引用
  • 符合现有AGENTS.md的风格/结构

Anti-Patterns

反模式

Don'tDo Instead
Dump all findings into AGENTS.mdFilter for generalizable patterns only
Create AGENTS.md for every folderOnly domains with distinct patterns
Write paragraphsSingle bullet points with examples
Duplicate root-level guidanceOnly domain-specific additions
Update on every file readBatch updates at research completion
不要做正确做法
将所有发现都写入AGENTS.md仅筛选具有通用性的模式
为每个文件夹都创建AGENTS.md仅为有独特模式的领域创建
编写大段文字使用带示例的单个项目符号
重复根层级的指导内容仅添加领域特定的补充内容
每次读取文件都更新在研究完成后批量更新