AGENTS.md / CLAUDE.md Files

AGENTS.md and CLAUDE.md files provide directory-specific context to AI coding agents and developers. They document patterns, conventions, and gotchas specific to a module or area of the codebase.

Purpose

While progress.txt tracks what Ralph implemented across iterations, AGENTS.md/CLAUDE.md files capture reusable knowledge about specific parts of the codebase:

API patterns or conventions specific to a module
Non-obvious requirements or constraints
Dependencies between files in the directory
Testing approaches for that area
Configuration or environment requirements

These files help future developers and AI agents understand the local context without reading the entire codebase.

AGENTS.md vs CLAUDE.md

AGENTS.md

Used when running Ralph with Amp (the default).Amp automatically loads AGENTS.md files from the working directory and parent directories as context.

CLAUDE.md

Used when running Ralph with Claude Code (./ralph.sh --tool claude).Claude Code uses CLAUDE.md files for the same purpose.

The content and format are identical - only the filename differs based on which AI tool you’re using.

When to Create/Update

Ralph iterations should check for and update these files before committing:

Create AGENTS.md when:

Starting work in a new directory that doesn’t have one
Discovering patterns that future work in this area should know
Encountering non-obvious requirements or constraints

Update AGENTS.md when:

You discover a pattern specific to this module
You encounter a gotcha that’s not documented
You learn about dependencies between files
You add new conventions that should be followed

DO NOT update AGENTS.md for:

Story-specific implementation details
Temporary debugging notes
Information already in progress.txt

Only add genuinely reusable knowledge that would help future work in that directory.

Location

Place AGENTS.md/CLAUDE.md files in the directories where the knowledge applies:

project/
├── AGENTS.md (project-wide patterns)
├── src/
│   ├── AGENTS.md (general src patterns)
│   ├── components/
│   │   ├── AGENTS.md (component patterns)
│   │   ├── TaskCard.tsx
│   │   └── PriorityBadge.tsx
│   ├── api/
│   │   ├── AGENTS.md (API patterns)
│   │   └── tasks.ts
│   └── db/
│       ├── AGENTS.md (database patterns)
│       └── schema.ts
└── migrations/
    ├── AGENTS.md (migration patterns)
    └── 001_init.sql

AI tools automatically load AGENTS.md/CLAUDE.md from the current directory and parent directories, so knowledge cascades down.

Content Structure

There’s no strict format, but a typical AGENTS.md file includes:

# [Module/Directory Name]

## Overview
[Brief description of what this directory contains]

## Patterns
[Conventions and patterns used in this area]

## Gotchas
[Non-obvious requirements or common mistakes]

## Dependencies
[Key dependencies between files]

## Testing
[How to test code in this area]

## Configuration
[Environment or config requirements]

Example: src/components/AGENTS.md

# UI Components

## Overview

React components for the task management UI. All components are TypeScript + CSS modules.

## Patterns

- Component files: `ComponentName.tsx`
- Styles: `ComponentName.module.css`
- Export components from `index.ts` for cleaner imports
- Use shared types from `src/types/` (not inline types)

## Props Pattern

All components use explicit prop interfaces:

```tsx
interface TaskCardProps {
  task: Task;
  onUpdate?: (task: Task) => void;
  variant?: 'compact' | 'full';
}

export function TaskCard({ task, onUpdate, variant = 'full' }: TaskCardProps) {
  // ...
}

Shared Components

TaskCard - Used in both ListView and BoardView (changes affect both)
PriorityBadge - Reusable badge for priority display
StatusDropdown - Shared by TaskCard and TaskEditModal

Gotchas

When modifying TaskCard, test in both ListView AND BoardView
Color tokens are in src/styles/theme.css - don’t hardcode colors
All components that mutate state should accept optional onUpdate callback
Icons come from lucide-react - import individually for tree-shaking

Testing

Tests live next to components: ComponentName.test.tsx
Use React Testing Library (not Enzyme)
Mock the useTask hook for task-dependent components
Run tests: npm test

Browser Verification

For UI changes, always verify in browser:

Start dev server: npm run dev
Navigate to relevant page
Test interactions (clicks, hovers, form inputs)
Check responsive behavior (resize browser)

## Example: migrations/AGENTS.md

```markdown
# Database Migrations

## Overview

SQL migration files for schema changes. Migrations run automatically on app start in development.

## Patterns

- Filename format: `NNN_description.sql` (e.g., `001_init.sql`, `002_add_priority.sql`)
- Migrations run in numeric order
- Use `IF NOT EXISTS` for idempotency

## Migration Template

```sql
-- Migration: [Description]
-- Created: [Date]

-- Add new column
ALTER TABLE tasks 
ADD COLUMN IF NOT EXISTS priority TEXT DEFAULT 'medium';

-- Add index if needed
CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority);

Gotchas

Always use IF NOT EXISTS / IF EXISTS for idempotency
Test migrations on a copy of production data before deploying
After adding a migration, restart the dev server to apply it
Update TypeScript types in src/db/schema.ts to match

Rollback

No automatic rollback. To undo a migration:

Create a new migration that reverses the change
Never delete or modify existing migration files

Testing

Run migrations: npm run migrate
Verify with: psql -d myapp -c "\d tasks"
Check TypeScript types compile after schema changes

## Example: src/api/AGENTS.md

```markdown
# API Layer

## Overview

Server-side API endpoints and actions. Uses Next.js Server Actions pattern.

## Patterns

### Return Type

All server actions return this shape:

```typescript
type ActionResult<T> = 
  | { success: true; data: T }
  | { success: false; error: string };

Error Handling

export async function updateTask(id: string, updates: Partial<Task>): Promise<ActionResult<Task>> {
  try {
    const task = await db.update(...);
    return { success: true, data: task };
  } catch (error) {
    console.error('Failed to update task:', error);
    return { success: false, error: 'Failed to update task' };
  }
}

Type Exports

Export TypeScript types from action files for use in UI:

// src/api/tasks.ts
export type { Task, TaskStatus, TaskPriority };

UI components import types from actions, NOT from db/schema:

// ✅ Good
import type { Task } from '@/api/tasks';

// ❌ Bad
import type { Task } from '@/db/schema';

Gotchas

Server actions run on the server - no access to window, document, etc.
Always validate input (don’t trust client data)
Use revalidatePath() after mutations to update UI
Rate limiting is handled by middleware (see src/middleware.ts)

Testing

Unit tests for individual actions: tasks.test.ts
Integration tests for full flows: tests/api/tasks.integration.test.ts
Run: npm test api

## What to Document

### DO Document:

<ResponseField name="Patterns" type="markdown">
  Local conventions specific to this module.
  
  **Examples:**
  - "Use pattern X for all API calls"
  - "Component files follow naming convention Y"
  - "All mutations return shape Z"
</ResponseField>

<ResponseField name="Gotchas" type="markdown">
  Non-obvious requirements or common mistakes.
  
  **Examples:**
  - "When modifying X, also update Y to keep them in sync"
  - "Tests require the dev server running on port 3000"
  - "Field names must match the template exactly"
</ResponseField>

<ResponseField name="Dependencies" type="markdown">
  Key relationships between files.
  
  **Examples:**
  - "TaskCard is used in both ListView and BoardView"
  - "schema.ts types are re-exported from actions.ts"
  - "Changing the Task type affects 12+ components"
</ResponseField>

<ResponseField name="Testing" type="markdown">
  How to test code in this area.
  
  **Examples:**
  - "Run `npm test` for unit tests"
  - "Use dev-browser skill to verify UI changes"
  - "Integration tests require Docker containers running"
</ResponseField>

<ResponseField name="Configuration" type="markdown">
  Environment or config requirements.
  
  **Examples:**
  - "Requires DATABASE_URL in .env"
  - "API key must be set in config.ts"
  - "Dev server runs on port 3000"
</ResponseField>

### DON'T Document:

- Story-specific implementation details
- Temporary debugging notes
- Information already in `progress.txt`
- Obvious patterns ("files are named after their component")

## Ralph Workflow

Before committing, Ralph should:

1. **Identify directories with edited files** - Look at which directories were modified
2. **Check for existing AGENTS.md/CLAUDE.md** - In those directories or parent directories
3. **Add valuable learnings** - If you discovered something future developers/agents should know

<Note>
  Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work in that directory.
</Note>

## Example Update During Ralph Iteration

```markdown
# Scenario

While implementing US-002 (priority badges), Ralph discovers that:
- TaskCard is used in two different views
- Color tokens should come from theme.css (not hardcoded)
- The dev server needs restart after CSS changes

Ralph updates `src/components/AGENTS.md`:

## Before

```markdown
# UI Components

React components for the task management UI.

After

# UI Components

React components for the task management UI. All components are TypeScript + CSS modules.

## Patterns

- Component files: `ComponentName.tsx`
- Styles: `ComponentName.module.css`
- Use shared types from `src/types/` (not inline types)

## Shared Components

- `TaskCard` - Used in both ListView and BoardView (changes affect both)
- `PriorityBadge` - Reusable badge for priority display

## Gotchas

- When modifying TaskCard, test in both ListView AND BoardView
- Color tokens are in `src/styles/theme.css` - don't hardcode colors
- Dev server needs restart after CSS module changes

## Benefits

- **Reduces context window usage** - AI agents don't need to read entire codebase
- **Speeds up iterations** - Future work can apply existing patterns immediately
- **Helps human developers** - Onboarding documentation for each module
- **Prevents repeated mistakes** - Gotchas are documented once, avoided forever

## Related

- [progress.txt Format](/reference/progress-txt) - Cross-iteration learnings log
- [prd.json Format](/reference/prd-json) - PRD structure Ralph implements
- [How Ralph Works](/concepts/how-it-works) - How Ralph uses knowledge files

CLI

File Formats

Examples

AGENTS.md / CLAUDE.md Files

Purpose

AGENTS.md vs CLAUDE.md

When to Create/Update

Create AGENTS.md when:

Update AGENTS.md when:

Location

Content Structure

Example: src/components/AGENTS.md

Shared Components

Gotchas

Testing

Browser Verification

Gotchas

Rollback

Testing

Error Handling

Type Exports

Gotchas

Testing

After

Build docs developers (and LLMs) love

CLI

File Formats

Examples

Documentation Index

​Purpose

​AGENTS.md vs CLAUDE.md

​When to Create/Update

​Create AGENTS.md when:

​Update AGENTS.md when:

​Location

​Content Structure

​Example: src/components/AGENTS.md

​Shared Components

​Gotchas

​Testing

​Browser Verification

​Gotchas

​Rollback

​Testing

​Error Handling

​Type Exports

​Gotchas

​Testing

​After

Build docs developers (and LLMs) love

Purpose

AGENTS.md vs CLAUDE.md

When to Create/Update

Create AGENTS.md when:

Update AGENTS.md when:

Location

Content Structure

Example: src/components/AGENTS.md

Shared Components

Gotchas

Testing

Browser Verification

Gotchas

Rollback

Testing

Error Handling

Type Exports

Gotchas

Testing

After