Ralph Loops Template

Template para rodar o Ralph — agente autonomo que implementa features a partir de PRDs.

Como usar

1. Copie para seu projeto

cp -r ralph-loops-template/.claude/ seu-projeto/.claude/
cp -r ralph-loops-template/scripts/ seu-projeto/scripts/
cp -r ralph-loops-template/tasks/ seu-projeto/tasks/
cp ralph-loops-template/CLAUDE.md seu-projeto/CLAUDE.md

Ou use como base para um projeto novo.

2. Configure o CLAUDE.md

O CLAUDE.md e o arquivo mais importante — e o que da contexto ao Ralph sobre seu projeto.

Abra uma sessao interativa do Claude Code na pasta do seu projeto e explique:

• O que e o projeto e o que ele faz
• Quais tecnologias, frameworks e linguagens usa
• Estrutura de pastas
• Comandos de build, test, lint, typecheck
• Convencoes de codigo (idioma, naming, patterns)
• O que ja esta implementado e o que falta

Depois peca para ele gerar o CLAUDE.md. Exemplo:

Estou montando o CLAUDE.md do meu projeto. Aqui esta um template de referencia:

[cole o conteudo do CLAUDE.md template que esta neste repo]

Agora gere um CLAUDE.md para o meu projeto com base no que te expliquei.

O Claude vai gerar um CLAUDE.md completo e adaptado ao seu projeto. Salve na raiz e copie para dentro do Ralph:

cp CLAUDE.md scripts/ralph/CLAUDE.md

Importante: O Ralph le o scripts/ralph/CLAUDE.md, nao o da raiz. Sempre que atualizar um, atualize o outro. O da raiz serve para sessoes interativas, o de dentro do Ralph serve para o loop autonomo.

3. Adicione permissoes da sua stack no settings.json

Edite .claude/settings.json e adicione os comandos da sua stack no allow:

"Bash(npm run *)",
"Bash(cargo build *)",
"Bash(python -m pytest *)"

4. Gere um PRD

Dentro do Claude Code:

/prd [descricao da feature]

Responda as perguntas. O PRD sera salvo em tasks/.

5. Converta para prd.json

/ralph

Aponte para o PRD gerado. Ele cria scripts/ralph/prd.json.

6. Rode o loop

chmod +x scripts/ralph/ralph.sh
./scripts/ralph/ralph.sh --tool claude

Opcoes do ralph.sh

./scripts/ralph/ralph.sh --tool claude      # Usa Claude Code (padrao)
./scripts/ralph/ralph.sh --tool amp         # Usa Amp
./scripts/ralph/ralph.sh --tool claude 5    # Maximo 5 iteracoes
./scripts/ralph/ralph.sh 20                 # Maximo 20 iteracoes

Estrutura

seu-projeto/
├── CLAUDE.md                          # Contexto do projeto (edite!)
├── .devcontainer/                     # Container isolado para rodar o Ralph
│   ├── devcontainer.json              # Config do VS Code Dev Container
│   ├── Dockerfile                     # Debian + Node.js + Claude Code CLI
│   └── init-firewall.sh              # Firewall (so permite GitHub, npm, Anthropic)
├── .claude/
│   ├── settings.json                  # Permissoes do Claude Code
│   └── skills/
│       ├── prd/SKILL.md               # Skill /prd — gera PRDs
│       └── ralph/SKILL.md             # Skill /ralph — converte PRD em prd.json
├── scripts/ralph/
│   ├── ralph.sh                       # O loop principal
│   ├── prompt.md                      # Prompt enviado a cada iteracao
│   ├── prd.json                       # PRD atual (gerado pelo /ralph)
│   ├── progress.txt                   # Log de progresso (atualizado pelo Ralph)
│   └── archive/                       # Runs anteriores (auto-arquivado)
└── tasks/
    └── prd-*.md                       # PRDs gerados pelo /prd

Fluxo

/prd  →  gera tasks/prd-feature.md
/ralph  →  converte em scripts/ralph/prd.json
ralph.sh  →  loop: le prd.json + progress.txt → implementa → commita → repete

Cada iteracao do Ralph:

1. Le o CLAUDE.md para contexto
2. Le o prd.json para saber o que fazer
3. Le o progress.txt para saber o que ja foi feito
4. Implementa a proxima user story
5. Commita e atualiza o progress.txt
6. Se tudo completo, emite <promise>COMPLETE</promise> e para

Dev Container (opcional mas recomendado)

O template inclui um .devcontainer/ que cria um ambiente isolado com:

• Debian + Node.js 20 + Claude Code CLI pre-instalado
• Firewall que so permite acesso a: GitHub, npm, Anthropic API
• jq, git, zsh e ferramentas basicas

Para usar: abra o projeto no VS Code e clique em "Reopen in Container" (precisa da extensao Dev Containers).

O firewall e importante para seguranca — o Ralph roda com bypassPermissions, entao o container garante que ele so acessa os servicos necessarios.

Requisitos (sem Dev Container)

• Claude Code instalado (npm install -g @anthropic-ai/claude-code)
• jq instalado (para o ralph.sh parsear JSON)