Projeto guiado: construa um PreToolUse hook de linting aplicando exatamente a metodologia que você acabou de aprender. Do SPEC ao safety pass, passo a passo.
Template e exemplo real do linting hook
Antes de escrever o primeiro prompt de código do seu linting hook, você precisa de um SPEC. Não uma descrição informal — um documento com as cinco seções que forçam decisões de design. Abaixo está um SPEC plausível para o hook que vamos construir: um PreToolUse hook que intercede em operações de escrita de arquivo e bloqueia saves quando o linter reporta erros.
# Lint Hook — SPEC
## 1. Propósito
PreToolUse hook para Claude Code que intercepta operações Write
e Edit, roda o linter configurado no projeto e bloqueia a
operação se o linter reportar erros com exit code não-zero.
NÃO faz: auto-fix, formatação, type-checking, ou qualquer
modificação nos arquivos.
## 2. Componentes
lint-hook.sh — o hook principal (registrado em hooks.json)
lint-config.json — qual linter rodar e em qual diretório
state/ — diretório de estado de sessão (opcional)
## 3. Interfaces
Entrada: stdin JSON do Claude Code com tool_name e tool_input
Linter: chamado via shell com o caminho do arquivo extraído
Saída: exit 0 (permitir) ou exit 1 + JSON com decision/reason
## 4. Invariantes
- Qualquer falha interna → exit 0 (fail-open obrigatório)
- Nunca modificar o arquivo sendo avaliado
- Nunca bloquear se o linter não estiver instalado
- Mensagem de bloqueio deve incluir o output do linter
## 5. Sequência de Build
Prompt 1: Scaffold + fail-open (hook existe, registra, exit 0)
Prompt 2: Linter integration (extrai path, chama linter, parseia)
Prompt 3: State (log de runs, métricas simples por sessão)
Prompt 4: Safety pass (ERR trap, timeouts, edge cases)Granularidade certa para o linting hook
O linting hook pode ser construído em 4 prompts. Cada prompt adiciona exatamente uma responsabilidade e produz algo verificável antes do próximo começar. A tentação é juntar tudo em um prompt grande — resistir a isso é a disciplina central da metodologia.
Hook shell criado, registrado em hooks.json, retorna exit 0 incondicionalmente, loga no stderr que foi chamado.
Extrai o path do arquivo do JSON de entrada, chama o linter configurado, parseia o exit code e retorna exit 1 com reason quando há erros.
Log de runs em state/runs.json com timestamp, arquivo avaliado e resultado. Escrita atômica.
ERR trap, timeout no linter (não travar se linter pendurar), validação de path, fail-open explícito em todos os branches de erro.
Antes de escrever um prompt, pergunte: "Se o Claude entregar exatamente isso e nada mais, consigo verificar que está correto sem executar o sistema inteiro?" Se a resposta for não, o prompt está grande demais ou as responsabilidades estão misturadas.
A sequência obrigatória em ação
Cada prompt do linting hook segue a sequência da metodologia. O scaffold existe para carregar. O estado existe para persistir. A lógica existe para decidir. A segurança existe para garantir que tudo isso funciona mesmo quando algo dá errado. Aqui está o Prompt 1 completo que você vai enviar para o Claude.
lint-hook.sh, registra em hooks.json como PreToolUse para Write/Edit, loga no stderr, retorna exit 0 sempre. Sistema operacional do Claude Code não muda.{"decision":"block","reason":"..."} quando linter falha.state/runs.json com timestamp, arquivo e resultado. Falha de I/O no log não bloqueia a execução principal.timeout 10s, validação de path (não vazio, não relativo perigoso), fail-open explícito em todos os branches.Se você adicionar o linter integration antes de verificar o scaffold, um bug de registro no hooks.json vai parecer um bug de parsing de JSON. Se você adicionar o state antes de verificar a linter integration, um bug de escrita atômica vai parecer um bug de bloqueio. A ordem importa porque cada camada adiciona variáveis de debug — e você só quer uma variável nova por vez.
Leia o SPEC.md neste diretório antes de começar.
Crie um PreToolUse hook chamado lint-hook.sh que intercepta
operações Write e Edit do Claude Code.
Por agora, o hook deve apenas:
1. Existir como shell script executável
2. Ser registrado em .claude/hooks.json para os tool names
"write_file" e "str_replace_editor"
3. Logar no stderr que foi chamado, com timestamp e o
tool_name recebido no stdin
4. Retornar exit 0 sempre, sem nenhuma lógica adicional
Fail-open é obrigatório: nenhum caminho de erro deve
retornar exit 1 ou deixar o processo travado.
Ao terminar, mostre como verificar que o hook está sendo
chamado corretamente pelo Claude Code.Critérios de pronto para cada prompt do linting hook
Critérios de "pronto" precisam ser definidos antes de executar o prompt, não depois. Se você define depois, você vai racionalizá-los para aceitar o que foi entregue. Abaixo estão os critérios para cada um dos 4 prompts do linting hook.
Adaptando as perspectivas para o linting hook e outros projetos
O Claudex usa personas para diversificar a perspectiva durante as revisões — cada persona traz um conjunto diferente de preocupações. Para o linting hook, as personas relevantes não são as mesmas do Claudex. A adaptação é parte do processo.
| Persona no Claudex | Preocupação | Adaptação para Linting Hook |
|---|---|---|
| Codex AI reviewer | Qualidade do código gerado | Developer experience — o hook é chato de usar? Mensagens de erro são claras? |
| Loop orchestrator | Continuidade e progresso | CI/CD operator — o hook funciona em pipelines automatizados, não só localmente? |
| Safety guardian | Não travar o usuário | Security reviewer — o hook pode ser enganado por paths maliciosos? |
| Token economist | Eficiência do contexto | Performance — o linter roda em milissegundos ou segundos? Afeta o flow do usuário? |
Para cada persona, escreva um system prompt que responda: quem é essa persona, o que ela mais teme, o que ela mais valoriza, e quais perguntas ela sempre faz. Exemplo para "Developer Experience" no contexto do linting hook:
O safety pass universal — aplica a qualquer hook
Antes de colocar qualquer hook em uso real — seja o linting hook, seja o seu próximo projeto — passe por este checklist sistematicamente. Não como formalidade, mas como verificação real. Cada item representa uma categoria de bug que já foi encontrada em hooks em produção.
Agora você sabe como construir.
Os 7 prompts reais que construíram o Claudex estão no repositório. Não são rascunhos — são os prompts que produziram o código que você usou. Leia-os em ordem, compare com o que foi construído, e use como referência para seus próximos projetos.
O que você aplicou neste projeto guiado: