Skip to content

CLAUDE.md

Latest commit

 

History

History
111 lines (81 loc) · 4.57 KB

CLAUDE.md

File metadata and controls

111 lines (81 loc) · 4.57 KB

Ralph Agent Instructions

You are an autonomous coding agent working on a software project.

CRITICAL RULE: ONE STORY ONLY

You MUST implement exactly ONE user story per invocation, then STOP. Do NOT continue to the next story. Do NOT implement multiple stories. After completing one story, write your progress report and end your response. A separate invocation will handle the next story.

Your Task

  1. Read the PRD at .ralph/current/prd.json
  2. Read the progress log at .ralph/current/progress.txt (check Codebase Patterns section first)
  3. Verify you are on the correct branch from PRD branchName. Do NOT create branches — run.sh handles that.
  4. Pick the highest priority user story where passes: false
  5. Implement ONLY that single user story — do NOT touch other stories
  6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
  7. Update CLAUDE.md files if you discover reusable patterns (see below)
  8. If checks pass, commit ALL changes with message: feat: [Story ID] - [Story Title]
  9. Update the PRD to set passes: true for ONLY the completed story
  10. Append your progress to .ralph/current/progress.txt
  11. STOP — do not start the next story

Progress Report Format

APPEND to progress.txt (never replace, always append):

## [Date/Time] - [Story ID]
- What was implemented
- Files changed
- **Learnings for future iterations:**
  - Patterns discovered (e.g., "this codebase uses X for Y")
  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
  - Useful context (e.g., "the evaluation panel is in component X")
---

The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.

Consolidate Patterns

If you discover a reusable pattern that future iterations should know, add it to the ## Codebase Patterns section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:

## Codebase Patterns
- Example: Use `sql<number>` template for aggregations
- Example: Always use `IF NOT EXISTS` for migrations
- Example: Export types from actions.ts for UI components

Only add patterns that are general and reusable, not story-specific details.

Update CLAUDE.md Files

Before committing, check if any edited files have learnings worth preserving in nearby CLAUDE.md files:

  1. Identify directories with edited files - Look at which directories you modified
  2. Check for existing CLAUDE.md - Look for CLAUDE.md in those directories or parent directories
  3. Add valuable learnings - If you discovered something future developers/agents should know:
    • API patterns or conventions specific to that module
    • Gotchas or non-obvious requirements
    • Dependencies between files
    • Testing approaches for that area
    • Configuration or environment requirements

Examples of good CLAUDE.md additions:

  • "When modifying X, also update Y to keep them in sync"
  • "This module uses pattern Z for all API calls"
  • "Tests require the dev server running on PORT 3000"
  • "Field names must match the template exactly"

Do NOT add:

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

Only update CLAUDE.md if you have genuinely reusable knowledge that would help future work in that directory.

Quality Requirements

  • ALL commits must pass your project's quality checks (typecheck, lint, test)
  • Do NOT commit broken code
  • Keep changes focused and minimal
  • Follow existing code patterns

Browser Testing (If Available)

For any story that changes UI, verify it works in the browser if you have browser testing tools configured (e.g., via MCP):

  1. Navigate to the relevant page
  2. Verify the UI changes work as expected
  3. Take a screenshot if helpful for the progress log

If no browser tools are available, note in your progress report that manual browser verification is needed.

Stop Condition

After completing ONE user story, check if ALL stories now have passes: true.

If ALL stories are complete and passing, reply with: COMPLETE

If there are still stories with passes: false, STOP IMMEDIATELY. End your response. Do NOT implement the next story. Another invocation will handle it.

Important

  • ONE story per invocation — this is the most important rule
  • After implementing one story: commit, update prd.json, write progress, then STOP
  • Do NOT look at the next story, do NOT start implementing it
  • Commit frequently
  • Keep CI green
  • Read the Codebase Patterns section in progress.txt before starting