O que o Prompt 01 Entrega
Estrutura do plugin + worktree setup — a Camada de Isolamento completa
O primeiro prompt constrói apenas a Camada de Isolamento: o scaffold do plugin e a infraestrutura de git worktree. Não há lógica de revisão ainda — só o contêiner que vai receber a lógica nos próximos prompts.
claude.json com hooks registrados e slash command /pr-reviewerhooks/stop-hook.sh — stub fail-open com ERR trapscripts/setup-worktree.sh — cria worktree em /tmp/pr-review-$PR_NUMBERscripts/cleanup-worktree.sh — remove worktree via EXIT trapO scaffold define o contrato externo: como o plugin é invocado, quais hooks são registrados, onde ficam os scripts. Mudar isso depois exige refatorar os prompts 2-5. Acertar aqui é barato. Acertar no Prompt 04 significa reescrever tudo.
O Prompt 01 Completo
Cole este texto no Claude Code para construir a primeira camada
Este é o texto exato do primeiro prompt de build. Cole no Claude Code com o SPEC.md em contexto. Observe a estrutura: o que entregar, as restrições não-negociáveis e a verificação antes de avançar.
Prompt 01 — Cole no Claude Code
Read SPEC.md if present — it's the source of truth.
You are building a Claude Code plugin called "pr-reviewer".
This is Prompt 01: build the scaffold and isolation layer only.
Do NOT implement any review logic yet.
**Deliver in this prompt:**
1. `claude.json` with:
- Hook registration: Stop hook pointing to `hooks/stop-hook.sh`
- Slash command: `/pr-reviewer <pr_number>` that sets PR_NUMBER
env var and runs `scripts/setup-worktree.sh`
2. `hooks/stop-hook.sh` — fail-open stub:
- `set -euo pipefail` + ERR trap that prints to stderr and exits 0
- Reads PR_NUMBER from environment (exits 0 if not set)
- Always returns `{"decision":"approve"}` for now
- No review logic whatsoever
3. `scripts/setup-worktree.sh <pr_number>`:
- Validates that PR_NUMBER is numeric
- Checks if worktree already exists with `git worktree list`
- If exists: reuses it (idempotent)
- If not: `git worktree add /tmp/pr-review-$1 origin/$(gh pr view $1 --json headRefName -q .headRefName)`
- On any failure: log to stderr, exit 0 (fail-open)
- Sets WORKTREE_PATH=/tmp/pr-review-$1 in state (creates state/ dir)
4. `scripts/cleanup-worktree.sh <pr_number>`:
- `git worktree remove --force /tmp/pr-review-$1 2>/dev/null || true`
- Removes state/review.yaml if present
- Always exits 0
**Constraints:**
- All scripts: `set -euo pipefail` + ERR trap (fail-open)
- setup-worktree.sh MUST be idempotent (safe to run twice)
- stop-hook.sh MUST return exit 0 on any error
- No hardcoded PR numbers anywhere
**Verification after delivery:**
- `claude --version` loads the plugin without error
- `bash -n hooks/stop-hook.sh` passes with no syntax errors
- `bash -n scripts/setup-worktree.sh` passes with no syntax errors
- `bash scripts/setup-worktree.sh 123` creates worktree at /tmp/pr-review-123
(run in a real git repo with GitHub remote)
- Running setup-worktree.sh 123 twice does NOT error
Tell me the file count and the result of `bash -n` on each script.O que está certo neste prompt
- ✓Referência explícita ao SPEC.md no início
- ✓Escopo limitado: "somente a camada de isolamento"
- ✓Restrições não-negociáveis explícitas
- ✓Verificação com comandos exatos a rodar
Armadilhas a evitar
- ✗Pedir lógica de revisão no Prompt 01
- ✗Omitir a instrução de fail-open no stop-hook
- ✗Não verificar idempotência do setup-worktree
- ✗Avançar para Prompt 02 sem rodar a verificação
Arquivos Gerados pelo Prompt 01
claude.json, hooks/ e scripts/ — responsabilidades e conteúdo esperado
Após o Prompt 01, você deve ter 4 arquivos novos. Cada um tem responsabilidade única e clara. Se o Claude gerou mais arquivos sem motivo, algo saiu do escopo.
claude.json
Manifest do plugin — registra hooks e slash commands
{
"name": "pr-reviewer",
"version": "0.1.0",
"hooks": {
"Stop": [{ "matcher": "", "hooks": ["bash hooks/stop-hook.sh"] }]
},
"commands": {
"pr-reviewer": {
"description": "Review a pull request",
"command": "bash scripts/setup-worktree.sh $PR_NUMBER"
}
}
}hooks/stop-hook.sh
Stub fail-open — será substituído no Prompt 03
#!/usr/bin/env bash
set -euo pipefail
trap 'echo "[pr-reviewer] ERR on line $LINENO" >&2; exit 0' ERR
# Stub: always approve (no review logic yet)
printf '{"decision":"approve"}\n'O stub existe para que o plugin seja válido e carregável desde o Prompt 01. Cada prompt subsequente substitui pedaços dele com lógica real, verificando que o comportamento esperado ainda funciona antes de avançar.
Como o Worktree Funciona
git worktree add + cleanup garantido via EXIT trap
Um git worktree é um segundo working directory ligado ao mesmo repositório. Diferente de um clone, ele compartilha o histórico e objetos do repositório original — sem duplicar dados. É o mecanismo correto para trabalhar com múltiplas branches simultaneamente.
# 1. Obter nome da branch do PR
BRANCH=$(gh pr view $PR_NUMBER --json headRefName -q .headRefName)
# 2. Criar worktree em /tmp (isolado do working tree atual)
git worktree add /tmp/pr-review-$PR_NUMBER origin/$BRANCH
# 3. Trabalhar no worktree (revisar código)
cd /tmp/pr-review-$PR_NUMBER
git diff origin/main...HEAD
# 4. Cleanup GARANTIDO — o EXIT trap chama isso mesmo se o script falhar
trap 'git worktree remove --force /tmp/pr-review-$PR_NUMBER 2>/dev/null || true' EXIT
# Verificar worktrees ativos
git worktree list
Sem --force, o git worktree remove falha se o worktree tem arquivos modificados não commitados. Como o plugin opera no worktree (lendo diff, criando arquivos temporários), --force garante que o cleanup sempre funciona.
Fail-Open no Setup
O que acontece se o worktree já existe ou o setup falha
O setup-worktree.sh deve ser idempotente e fail-open. Idempotente significa que rodar duas vezes produz o mesmo resultado que uma. Fail-open significa que qualquer falha resulta em exit 0 — nunca bloqueia o usuário.
Worktree já existe
Verificar com git worktree list | grep "/tmp/pr-review-$PR_NUMBER". Se encontrar: reutiliza e continua. Não tenta criar novamente.
Branch não existe no remote
O gh pr view falha. O ERR trap captura, loga no stderr e faz exit 0. O usuário vê a mensagem de erro mas o Claude Code continua funcionando normalmente.
Disco cheio ou permissão negada
Falha de infraestrutura. O ERR trap captura, loga o motivo e retorna exit 0. A revisão não acontece, mas o usuário não fica bloqueado.
Verificação Antes do Prompt 02
Testes obrigatórios — não avance sem estes passarem
A verificação do Prompt 01 é a mais importante do projeto — é aqui que você confirma que a base está sólida. Bugs no scaffold são baratos aqui. Baratos no Prompt 01. Caros no Prompt 04.
claude --version
Deve carregar o plugin pr-reviewer sem erros. Se falhar, o claude.json tem problema de sintaxe.
bash -n hooks/stop-hook.sh && bash -n scripts/setup-worktree.sh && bash -n scripts/cleanup-worktree.sh
Lint de sintaxe bash. Deve passar sem output — erros de sintaxe aparecem como mensagens de erro.
bash scripts/setup-worktree.sh 999
Em um repo com PR #999 no GitHub: deve criar worktree em /tmp/pr-review-999. Verificar com `git worktree list`.
bash scripts/setup-worktree.sh 999 && bash scripts/setup-worktree.sh 999
Rodar duas vezes não deve erro. Confirma idempotência.
bash scripts/cleanup-worktree.sh 999 && git worktree list
Após cleanup, o worktree não deve aparecer mais na lista. Confirma que o remove funciona.
Crie um repo de teste no GitHub com um PR aberto. Os testes 3, 4 e 5 precisam de um PR real porque usam gh pr view. Um PR com um arquivo modificado qualquer é suficiente para validar o scaffold.
✅ Resumo do Módulo 4.2
Próximo Módulo:
4.3 — Prompt 02: A Máquina de Estados — estado YAML atômico e lockfile