Project Philosophy
Relevant source files
The following files were used as context for generating this wiki page:The Ralph for Claude Code project is built on a philosophy of enabling structured, autonomous AI-driven development while maintaining high standards of quality, safety, and maintainability. It implements Geoffrey Huntley's "Ralph" technique, creating a continuous development loop where an AI agent iteratively improves a project until completion. This philosophy is enforced through a combination of guiding prompts, control files, automated safeguards, and a rigorous development workflow.
The core idea is to provide the AI agent with clear instructions, prioritized tasks, and robust feedback mechanisms, allowing it to work independently within a well-defined framework. This includes intelligent exit detection to prevent infinite loops, rate limiting to manage API usage, and a "circuit breaker" to handle persistent errors. The project's philosophy extends to human collaboration, advocating for structured specification workshops to ensure features are well-defined before implementation begins.
Sources: README.md:12-14, CLAUDE.md:5-7, SPECIFICATION_WORKSHOP.md:4-6
Autonomous Development Cycle
The project's primary function is an autonomous loop that directs the AI agent. This cycle is designed to be continuous, self-correcting, and aware of its progress toward a defined goal.
The loop operates in a distinct sequence, guided by a set of control files.
This diagram shows the main development loop, where Ralph reads instructions, executes the AI, analyzes the output, and repeats until completion criteria are met, all while governed by safeguards.
Sources: README.md:154-160, create_files.sh:282-291
Control Files
The AI agent's behavior is directed by a set of "control files" that define its goals, tasks, and operational context.
| File | Purpose |
|---|---|
PROMPT.md | Contains the main development instructions, key principles, and status reporting format for the AI agent. |
@fix_plan.md | A prioritized list of tasks. The agent works through this list, starting with high-priority items. |
@AGENT.md | Stores build, run, and test instructions for the project, which the agent maintains and uses. |
specs/* | A directory for detailed project specifications and requirements that the agent must adhere to. |
This structured approach ensures the agent's work is aligned with project goals and priorities. The @ prefix denotes a file specifically for Ralph's control.
Sources: templates/PROMPT.md:1-7, create_files.sh:479-484, CONTRIBUTING.md:104-105
Guiding Principles for the AI Agent
The PROMPT.md template instills a core set of principles in the AI agent to guide its work and ensure efficiency and quality.
- Focus: Execute one primary task per loop to ensure focused progress.
- Efficiency: Search the existing codebase before implementing new functionality to avoid duplication.
- Delegation: Use subagents for resource-intensive operations like file searching and analysis.
- Quality: Write comprehensive tests and clear documentation for all new code.
- Accountability: Update the
@fix_plan.mdtask list with progress and learnings. - Traceability: Commit working changes with descriptive messages.
Sources: templates/PROMPT.md:12-18
Testing Philosophy
A critical aspect of the agent's guiding principles is its approach to testing, which prioritizes implementation over exhaustive testing in the early stages.
- Effort Limitation: Testing should be limited to approximately 20% of the total effort per loop.
- Prioritization: The order of priority is: Implementation > Documentation > Tests.
- Scope: Only write tests for new functionality. Do not refactor existing tests unless they are broken or add "additional test coverage" as busy work.
- Focus: Concentrate on core functionality first, with comprehensive testing to follow later.
This philosophy ensures the agent makes forward progress on features without getting bogged down in perfecting test coverage prematurely.
Sources: templates/PROMPT.md:21-27
Safeguards and Completion Awareness
A core tenet of the project is that an autonomous agent must know when to stop. Ralph incorporates several mechanisms to achieve this, preventing wasted resources and infinite loops.
Intelligent Exit Detection
The system automatically stops when it detects signs of project completion or stagnation.
- Task Completion: All tasks in
@fix_plan.mdare marked as complete. - Completion Signals: The AI agent emits multiple consecutive "done" signals in its status reports.
- Test Saturation: The agent enters a state of running tests without implementing new features for a configured number of loops (
MAX_CONSECUTIVE_TEST_LOOPS=3). - API Limits: The system detects Claude's 5-hour usage limit and prompts the user to wait or exit.
Sources: README.md:162-167, create_files.sh:185-190
Status Reporting
The AI agent is required to provide a structured status report at the end of each response. This feedback is crucial for the ralph_loop.sh script to analyze progress and make decisions.
The following sequence diagram illustrates the interaction between the AI Agent and the Ralph loop for status reporting.
The status block format is strictly defined:
---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
TASKS_COMPLETED_THIS_LOOP: <number>
FILES_MODIFIED: <number>
TESTS_STATUS: PASSING | FAILING | NOT_RUN
WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
EXIT_SIGNAL: false | true
RECOMMENDATION: <one line summary of what to do next>
---END_RALPH_STATUS---
This mechanism provides a clear, machine-readable signal for the system to determine the state of the project.
Sources: templates/PROMPT.md:34-45, templates/PROMPT.md:60-98
Human Collaboration and Quality Standards
The project philosophy emphasizes that autonomous development does not exist in a vacuum. It prescribes rigorous standards for both human collaboration and code quality.
Specification Workshops
The project adopts the "Three Amigos" (Developer, Tester, Product Owner) approach for defining features before implementation. This is detailed in SPECIFICATION_WORKSHOP.md. The goal is to produce concrete, testable specifications through collaborative discussion, preventing ambiguity and bugs.
This diagram shows the collaborative nature of a Specification Workshop.
This process ensures that features are well-understood from multiple perspectives before the AI agent is tasked with building them.
Sources: SPECIFICATION_WORKSHOP.md:4-13, SPECIFICATION_WORKSHOP.md:65-81
Contribution and Quality Standards
The project maintains strict quality gates for all contributions, whether from humans or the AI agent. These standards are designed to ensure traceability, maintainability, and reliability.
Git Workflow
A conventional Git workflow is enforced to maintain a clean and understandable history.
| Element | Convention | Example |
|---|---|---|
| Branch Naming | type/<description> | feature/log-rotation, fix/rate-limit-reset |
| Commit Messages | Conventional Commits | feat(loop): add dry-run mode |
Sources: CONTRIBUTING.md:79-114
Feature Completion Checklist
Before any feature is considered complete, it must meet a mandatory checklist defined in templates/AGENT.md. This serves as a "Definition of Done" for the AI agent.
- All tests pass with 100% pass rate.
- Code coverage meets the required threshold (e.g., 85%).
- All changes are committed with conventional commit messages.
- All commits are pushed to the remote repository.
- The
@fix_plan.mdtask is marked as complete. - All relevant documentation (
AGENT.md,README.md, inline comments) is updated. - The CI/CD pipeline passes.
This checklist ensures that every piece of work is fully integrated, tested, and documented.
Sources: templates/AGENT.md:94-111, CONTRIBUTING.md:195-204
Conclusion
The project philosophy of Ralph for Claude Code is a synthesis of structured autonomy and rigorous engineering discipline. By providing the AI agent with clear principles, prioritized tasks, and a robust feedback loop, it enables efficient, autonomous development. Simultaneously, it enforces strict quality standards, safeguards against common pitfalls, and integrates formal human collaboration to guide the overall process. This dual focus on AI empowerment and human-governed quality aims to create a reliable system for building software with artificial intelligence.
Sources: README.md, CONTRIBUTING.md, CLAUDE.md