How to Customize Ralph's prompt.md Template for Project-Specific Conventions

Ralph's autonomous coding loop relies on a customizable prompt file (prompt.md for Amp or CLAUDE.md for Claude Code) that defines quality checks, project conventions, and common gotchas, which you can tailor to your specific tech stack by copying the template to your repository and editing the relevant sections.

The snarktank/ralph repository provides an agent-driven development framework that feeds structured prompts to AI coding assistants. By customizing the prompt.md template with your project's specific commands, naming rules, and known pitfalls, you transform Ralph from a generic assistant into a codebase-aware collaborator that respects your conventions and catches errors before they reach production.

Where the Template Lives

Ralph supports two filename conventions depending on your underlying AI tool:

• prompt.md – Used when running Ralph with Amp (referenced in README.md and ralph.sh)
• CLAUDE.md – Used when running Ralph with Claude Code

Both files share identical internal structure and reside in the repository root by default. As implemented in snarktank/ralph, these files define the task list, quality requirements, and project-specific instructions that Ralph injects into every iteration of the autonomous loop.

Customizing the Prompt Structure

After copying the template into your project (following the Setup section in README.md), modify these specific sections to match your stack:

Override Quality-Check Commands

Ralph's loop includes a "quality checks" step that validates code before committing. Replace the placeholder commands in the Quality Requirements block with your project's exact toolchain:

## Quality Requirements

- ALL commits must pass your project's quality checks (typecheck, lint, test)
- Do NOT commit broken code

## Quality Checks

Run the full suite before committing:

```bash
npm run lint && npm run typecheck && npm test

For Python projects, you might substitute:

```bash
python -m pytest && ruff check . && mypy src/

Document Project-Specific Conventions

Insert a Project Conventions section to teach Ralph your directory structure, naming patterns, and architectural rules. This ensures the agent generates code that matches your existing patterns:

## Project Conventions

- All React components live under `src/components/` and use PascalCase
- API client functions must return a `Result<T>` type
- Database migrations are placed in `prisma/migrations/` and must include a `down.sql` file

Ralph references this block during code generation and can cite these rules in commit messages or when explaining implementation choices.

Capture Known Gotchas

Add a Known Gotchas section to prevent Ralph from repeating common mistakes specific to your stack:

## Known Gotchas

- Remember to update `src/schema.ts` whenever a Prisma model changes
- The `NEXT_PUBLIC_API_URL` environment variable is required for any API call; missing it crashes the dev server
- The dev server must be running on port 3000 for UI verification; otherwise the `dev-browser` skill will fail

Configure Post-Story Hooks

For workflows requiring documentation generation or deployment previews, append a Post-Story Hooks section:

## Post-Story Hooks

- After any backend change, run `npm run generate-docs`
- Update `API_CHANGELOG.md` when modifying REST endpoints

Reference these hooks in your Quality Requirements to ensure they execute consistently.

Implementation Workflow

Follow these steps to activate your customized template:

1. Copy the template from the Ralph repository to your project directory:

# For Amp users

cp /path/to/ralph/prompt.md ./scripts/ralph/prompt.md

# For Claude Code users

cp /path/to/ralph/CLAUDE.md ./scripts/ralph/CLAUDE.md

2. Edit the file with your project-specific sections, inserting the quality commands and conventions documented above.

3. Commit the customized prompt to version control so it travels with your repository:

git add scripts/ralph/prompt.md
git commit -m "chore: customize Ralph prompt for project conventions"

From now on, every instance of Ralph spawned by ralph.sh will read your customized prompt from the repository, apply your specific conventions, and execute your exact quality checks.

Summary

• Ralph uses prompt.md (Amp) or CLAUDE.md (Claude Code) as the instruction set for its autonomous coding loop, located in the snarktank/ralph repository.
• Customize the Quality Requirements section with your specific lint, typecheck, and test commands to enforce code standards.
• Add Project Conventions and Known Gotchas sections to teach Ralph your directory structure, naming rules, and common pitfalls.
• Commit the customized prompt to your repository so the agent respects your project's evolving standards across all iterations.
• Reference progress.txt (if present) to maintain an append-only log of learnings that Ralph can update after each iteration.

Frequently Asked Questions

What's the difference between prompt.md and CLAUDE.md?

Both files contain identical instructions and structure; only the filename differs to match the expectations of the underlying AI tool. Amp expects prompt.md while Claude Code recognizes CLAUDE.md. You should copy whichever file corresponds to your AI assistant and place it in your project root or a scripts directory.

Where should I place the customized prompt file in my project?

Place the file anywhere in your repository that Ralph can access, typically ./prompt.md in the project root or under a scripts directory like ./scripts/ralph/prompt.md. The ralph.sh launcher reads the file path specified in its configuration, so ensure the location matches your setup script.

Can I use multiple quality-check commands or only one?

You can chain multiple commands using && or list them separately. Ralph executes the quality checks as a shell command block, so any valid bash script works. For example: npm run lint && npm run typecheck && npm test or make lint && make test.

How does Ralph utilize the progress.txt file mentioned in the source?

The progress.txt file serves as an append-only log where Ralph records learnings and state between iterations. While customizing prompt.md, you can reference this file's location to instruct Ralph to update it after fixing difficult bugs or discovering new project constraints, building a cumulative knowledge base for future runs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}