Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/snarktank/ralph/llms.txt

Use this file to discover all available pages before exploring further.

​
Customizing Prompts

The prompt.md (for Amp) and CLAUDE.md (for Claude Code) files contain the instructions given to each fresh AI instance. Customizing these for your project is critical for success.

​
Which File to Customize

  • Using Amp? Customize prompt.md
  • Using Claude Code? Customize CLAUDE.md
Both files serve the same purpose but are read by different AI coding tools.

​
Where Are These Files?

After setup, you’ll find them in your project: 
# If you copied Ralph to your project
scripts/ralph/prompt.md      # For Amp
scripts/ralph/CLAUDE.md       # For Claude Code

# Or in your global config
~/.config/amp/skills/ralph/prompt.md
~/.claude/skills/ralph/CLAUDE.md

​
What to Customize

1

Quality check commands

Update section 6 to match your project’s checksDefault:
6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
Customized for Next.js:
6. Run quality checks in this order:
   - `npm run typecheck` - Must pass with zero errors
   - `npm run lint` - Must pass or auto-fix
   - `npm test -- --passWithNoTests` - Run relevant tests
Customized for Python:
6. Run quality checks in this order:
   - `mypy .` - Type checking must pass
   - `ruff check .` - Linting must pass
   - `pytest tests/` - All tests must pass
2

Project conventions

Add a section for codebase-specific patterns
## Project Conventions

- All database queries use the `db.query()` pattern, never raw SQL
- UI components go in `src/components/` with co-located styles
- Server actions must be in files named `actions.ts`
- Always export TypeScript types from action files for UI imports
- Use `sql<number>` template tags for aggregation queries
3

Common gotchas

Document things that AI (and humans) commonly get wrong
## Common Gotchas

- Always use `IF NOT EXISTS` in migrations - we run them in dev and prod
- When adding a new API route, update `src/lib/api-routes.ts` registry
- The settings panel is in `app/settings/components/SettingsPanel.tsx`
- Environment variables must be added to both `.env.example` and Vercel
- Use `revalidatePath()` after mutations to refresh Server Components
4

File structure updates

Tell Ralph where to update AGENTS.md or CLAUDE.md filesFor Amp users (using AGENTS.md):
## Update AGENTS.md Files

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

1. **Identify directories with edited files** - Look at which directories you modified
2. **Check for existing AGENTS.md** - Look in those directories or parent directories
3. **Add valuable learnings** - Document patterns, gotchas, and conventions

Key AGENTS.md locations:
- `src/app/AGENTS.md` - Frontend patterns
- `src/lib/AGENTS.md` - Shared utilities
- `src/server/AGENTS.md` - Backend patterns
For Claude Code users (using CLAUDE.md):
## Update CLAUDE.md Files

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

Key CLAUDE.md locations:
- `src/app/CLAUDE.md` - Frontend patterns
- `src/lib/CLAUDE.md` - Shared utilities  
- `src/server/CLAUDE.md` - Backend patterns

​
Real-World Example

Here’s a customized prompt for a Next.js + PostgreSQL project: 
# Ralph Agent Instructions

You are an autonomous coding agent working on a Next.js 14 app with PostgreSQL.

## Your Task

1. Read the PRD at `prd.json`
2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
3. Check you're on the correct branch from PRD `branchName`
4. Pick the **highest priority** user story where `passes: false`
5. Implement that single user story
6. Run quality checks:
   - `npm run typecheck` - Must pass with zero errors
   - `npm run lint` - Must pass (auto-fix if possible)
   - `npm test -- --passWithNoTests` - Run tests for changed files
7. Update AGENTS.md files if you discover reusable patterns
8. If checks pass, commit ALL changes: `feat: [Story ID] - [Story Title]`
9. Update the PRD to set `passes: true` for the completed story
10. Append your progress to `progress.txt`

## Project Conventions

- **Database**: Use Drizzle ORM, never raw SQL. Queries go in `src/db/queries/`
- **Server Actions**: Must be in `actions.ts` files with `"use server"` directive
- **Components**: 
  - Client components: `"use client"` at top
  - Server components: default, no directive
  - Shared UI: `src/components/ui/` (shadcn)
- **Styling**: Tailwind utility classes, no custom CSS
- **Types**: Export from `actions.ts` for UI components to import

## Common Gotchas

- Migrations need `IF NOT EXISTS` - we run them multiple times
- After mutations, call `revalidatePath("/path")` to refresh UI
- The dev server must be running on PORT 3000 for browser tests
- Never commit `.env` - add new vars to `.env.example` only
- Settings panel is at `app/settings/components/SettingsPanel.tsx`

## Quality Requirements

- Typecheck must pass with **zero** errors
- Keep changes minimal and focused
- Follow existing patterns in nearby files
- Do NOT commit broken code

## Browser Testing (Required for UI Stories)

For any story that changes UI:

1. Load the `dev-browser` skill
2. Navigate to the page (usually http://localhost:3000/...)
3. Verify the changes work
4. Take a screenshot for the progress log

## Progress Report Format

APPEND to progress.txt:

​
[Date/Time] - [Story ID]

Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID
  • What was implemented
  • Files changed
  • Learnings for future iterations:
    • Patterns discovered
    • Gotchas encountered

## Stop Condition

When ALL stories have `passes: true`, reply with:
<promise>COMPLETE</promise>

​
Tips for Great Prompts

Be specific about commands: Don’t say “run tests”, say npm test -- --passWithNoTests or pytest tests/unit
Document the happy path: Tell Ralph where files should go and what patterns to follow
List gotchas explicitly: If you’ve been bitten by something, document it so Ralph doesn’t repeat the mistake
Don’t remove the core Ralph workflow (reading PRD, updating progress.txt, etc). Only add project-specific details.

​
Testing Your Customizations

1

Start with a small story

Create a simple one-story PRD to test your customizations
{
  "userStories": [
    {
      "id": "US-001",
      "title": "Add a test file",
      "acceptanceCriteria": [
        "Create test.txt with 'hello world'",
        "Typecheck passes"
      ]
    }
  ]
}
2

Run one iteration

./scripts/ralph/ralph.sh 1
3

Check the output

  • Did Ralph run your quality checks?
  • Did it follow your conventions?
  • Check progress.txt for the learnings format
4

Iterate on the prompt

Refine based on what worked and what didn’t

​
Version Control

Commit your customized prompt.md or CLAUDE.md to version control so the whole team uses the same instructions.
git add scripts/ralph/prompt.md
git commit -m "docs: customize Ralph prompt for our project"

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us