# How to Customize Ralph's prompt.md Template for Project-Specific Conventions > Learn how to customize Ralph's prompt.md template for your project. Tailor quality checks and conventions to your specific tech stack by editing the prompt file in your repository. - Repository: [Ryan Carson/ralph](https://github.com/snarktank/ralph) - Tags: how-to-guide - Published: 2026-04-13 --- **Ralph's autonomous coding loop relies on a customizable prompt file ([`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) for Amp or [`CLAUDE.md`](https://github.com/snarktank/ralph/blob/main/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`](https://github.com/snarktank/ralph/blob/main/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`](https://github.com/snarktank/ralph/blob/main/prompt.md)** – Used when running Ralph with Amp (referenced in [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) and [`ralph.sh`](https://github.com/snarktank/ralph/blob/main/ralph.sh)) - **[`CLAUDE.md`](https://github.com/snarktank/ralph/blob/main/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`](https://github.com/snarktank/ralph/blob/main/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: ```markdown ## 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: ```markdown ## Project Conventions - All React components live under `src/components/` and use PascalCase - API client functions must return a `Result` 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: ```markdown ## 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: ```markdown ## 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: ```bash # 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: ```bash 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`](https://github.com/snarktank/ralph/blob/main/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`](https://github.com/snarktank/ralph/blob/main/prompt.md) (Amp) or [`CLAUDE.md`](https://github.com/snarktank/ralph/blob/main/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`](https://github.com/snarktank/ralph/blob/main/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`](https://github.com/snarktank/ralph/blob/main/prompt.md) and [`CLAUDE.md`](https://github.com/snarktank/ralph/blob/main/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`](https://github.com/snarktank/ralph/blob/main/prompt.md) while Claude Code recognizes [`CLAUDE.md`](https://github.com/snarktank/ralph/blob/main/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`](https://github.com/snarktank/ralph/blob/main/./prompt.md) in the project root or under a scripts directory like [`./scripts/ralph/prompt.md`](https://github.com/snarktank/ralph/blob/main/./scripts/ralph/prompt.md). The [`ralph.sh`](https://github.com/snarktank/ralph/blob/main/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`](https://github.com/snarktank/ralph/blob/main/progress.txt) file mentioned in the source? The [`progress.txt`](https://github.com/snarktank/ralph/blob/main/progress.txt) file serves as an append-only log where Ralph records learnings and state between iterations. While customizing [`prompt.md`](https://github.com/snarktank/ralph/blob/main/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.