| name | spec-a23 |
| description | Workflow de spec-driven development para Claude Code, focado em VELOCIDADE e BAIXO CUSTO de tokens, mas com regras pesadas de SEGURANÇA, qualidade, review e testes. Cria estrutura completa de implementação em pastas .md (resumo, visão geral, research, fases) na pasta `implementacao/<slug>/` do projeto, pré-cria todas as fases e subfases de uma vez para discussão única, executa cada subfase via subagent em modelo padrão e effort padrão e VALIDA tudo (segurança, qualidade, testes, correções) com o modelo da sessão. Use sempre que o usuário falar sobre planejar, implementar, especificar, criar implementação, ajustar feature, refatorar módulo, migrar sistema, ou pedir spec/roadmap de qualquer demanda técnica. Use quando o usuário disser /spec-a23 ou citar 'spec a23'. Funciona em qualquer stack — detecta a linguagem/framework do projeto e segue as convenções existentes. Toda interação e todos os documentos em PT-BR com acentuação correta. |
| argument-hint | Descreva a demanda/implementação que deseja planejar e executar |
spec-a23 — Spec-Driven Implementation (Claude Code, A23)
Você transforma demandas em uma estrutura completa de implementação documentada, com fases atômicas e subfases auto-executáveis. A prioridade é velocidade e baixo custo de tokens, mas com regras pesadas e inegociáveis de segurança, qualidade e validação.
A skill é exclusiva para Claude Code e usa subagents, hooks e ferramentas do harness para reduzir o atrito do usuário e acelerar o fluxo.
REGRAS MÁXIMAS (não negociáveis)
- 🔒 SEGURANÇA é o fator principal. Toda fase tem
security-review obrigatório (ver references/security-rules.md). Nada vai pra "concluído" sem passar.
- 🇧🇷 PT-BR com acentuação correta em TUDO: discovery, docs
.md, mensagens da sessão, retornos de API e textos de frontend gerados nas fases. Nunca trocar acentos por ASCII (ex: nunca "nao" — sempre "não").
- ⚡ Custo e velocidade são prioridade, mas qualidade NÃO é negociável. Discovery é proporcional à demanda — curto para tarefas simples, profundo para tarefas complexas. Nunca cortar etapas de validação para ganhar velocidade.
- 📁 Output prioritário em
.md — a sessão emite o mínimo possível de texto. Tudo que importa vai pra arquivo. A sessão só comunica: status, perguntas, checkpoints e blockers.
- 🤖 Construção via subagent em modelo padrão e effort padrão (sem especificar
model/effort) — sempre. Validação, testes, review de segurança, review de qualidade e correções pelo MODELO DA SESSÃO — nunca delegar isso a subagent (a menos que o usuário peça explicitamente outro agent).
- 💬 Discussão única — depois do discovery, todas as fases e subfases são apresentadas de uma vez. O usuário discute tudo, aprova tudo, e só então a skill cria os
.md em paralelo.
- 🧠 Use a memória do projeto (
MEMORY.md em .claude/projects/.../memory/) para puxar feedback prévio, regras críticas e contexto antes do discovery — reduz perguntas e evita repetir erros do passado.
- 🌳 Commit obrigatório por fase. Ao final de cada fase, depois que TODOS os reviews passaram (security, quality, testes, validação final), a sessão comita as mudanças com mensagem em PT-BR no padrão do repo (
feat(escopo): FASE-XX — <título>), referenciando a fase. Preferir adicionar arquivos específicos a git add -A/. (evita incluir secrets/binários acidentais). Nunca --no-verify. Push só sob comando explícito do usuário. O hash do commit vai pro log da fase. Builder agent NÃO comita — só a sessão. Detalhes em agents/reviewer.md.
Como invocar
/spec-a23 [descrição da demanda]
Exemplos:
/spec-a23 adicionar painel de relatórios de vendas com export CSV/PDF/spec-a23 migrar autenticação de JWT cookie para refresh token rotation/spec-a23 criar fluxo de checkout com PIX, cartão e split de pagamento
Estrutura de Output (obrigatória)
Tudo dentro do projeto, em pasta dedicada:
implementacao/<slug>/
├── README.md ← índice navegável (links pros docs e fases)
├── 00-VISAO-GERAL.md ← objetivo, escopo (dentro/fora), estado atual vs desejado, riscos macro, stakeholders
├── 01-RESUMO.md ← resumo executivo curto (TL;DR — 1 página)
├── 02-RESEARCH.md ← pesquisa técnica, padrões aplicáveis, decisões de arquitetura, referências
├── 10-LOG-EXECUCAO.md ← log vivo (formato em [`templates/10-LOG-EXECUCAO.md`](./templates/10-LOG-EXECUCAO.md))
├── evidencias/ ← screenshots, dumps, logs de validação (criada sob demanda)
└── fases/
├── FASE-00-<nome>.md ← uma fase = um conjunto coeso de mudanças
├── FASE-01-<nome>.md
└── ...
Slug = kebab-case derivado da demanda (ex: painel-relatorios-vendas, auth-refresh-rotation, checkout-pix-split). Se já existir uma pasta com o mesmo slug, criar <slug>-v2.
Cada arquivo de fase contém:
- Objetivo, dependências, duração estimada, entregável
- Subfases (A, B, C, D, …) — cada subfase é uma unidade construível por subagent
- Para CADA subfase: o que construir, arquivos afetados, padrões a seguir, critérios de validação, checks de segurança, testes, review de qualidade
- Riscos e mitigações
- Comandos de verificação
Templates prontos em templates/.
Fluxo (5 fases sequenciais)
| Fase | Nome | Quem faz | Output |
|---|
| F0 | Discovery proporcional | Sessão | Contexto consolidado em memória |
| F1 | Auto-geração de docs base | Subagent (paralelo) | README.md, 00, 01, 02, 10 em disco |
| F2 | Pré-criação textual das fases + subfases | Sessão | Apresentação única na sessão para discussão |
| F3 | Geração paralela dos .md de fase | Subagent (paralelo) | fases/FASE-XX-*.md em disco |
| F4 | Execução fase a fase (loop) | Subagent constrói + sessão valida | Código + log atualizado |
F0 — Discovery proporcional à demanda
Princípio: discovery é o suficiente para garantir qualidade. Curto para demandas simples, profundo para demandas complexas. Nunca cortar perguntas críticas para ganhar velocidade.
F0.1 — Classificar a demanda
Categorize internamente:
| Tipo | Exemplos | Discovery esperado |
|---|
| Trivial | Ajuste de copy, fix bug pontual, ajuste visual isolado | 0–2 perguntas, pode até pular F0 |
| Simples | Novo CRUD pequeno, novo endpoint, nova página estática | 3–5 perguntas, 1 rodada |
| Média | Feature com UI + API + DB, integração externa simples | 6–10 perguntas, 1–2 rodadas |
| Complexa | Refator estrutural, migração de subsistema, multi-módulo | 10–20 perguntas, 2–3 rodadas, possivelmente Architecture Overview |
| Épica | Sistema novo inteiro, redesenho de domínio | Faça o Architecture Overview primeiro (ver F0.5) |
A classificação NÃO é compartilhada com o usuário — é interna pra calibrar o discovery.
F0.2 — Pré-discovery (sem perguntar nada ainda)
Antes de qualquer pergunta, explore o projeto em paralelo para reduzir perguntas:
- Ler memória —
MEMORY.md em .claude/projects/.../memory/ e arquivos referenciados. Puxa feedback, regras críticas, preferências.
- Ler
CLAUDE.md — instruções do projeto.
- Ler
.claude/napkin.md se existir (skill napkin) — runbook curado do repo.
- Listar
implementacao/ — pra evitar duplicar slug e pra reaproveitar padrão de SPECs anteriores.
- Detectar stack via arquivos de manifesto (
package.json, pyproject.toml/requirements.txt, go.mod, Cargo.toml, composer.json, Gemfile, pom.xml, etc.) e configs de framework — usar Glob + Grep em paralelo, NÃO subagent (mais barato).
- Detectar convenções do projeto — estrutura de pastas, modelos/entidades, rotas, camada de dados, biblioteca de UI — referenciar nas fases.
- Skills relacionadas ao domínio da demanda — se a demanda for SEO, invocar
seo-audit para diagnóstico antes do discovery; se for sobre Claude API/SDK, invocar claude-api. Reduz perguntas de discovery porque a skill especializada já levanta o estado atual.
Apresentar uma linha curtinha com o que detectou (não detalhar muito — economizar tokens):
🔍 Detectei: <stack do projeto — ex: Django + PostgreSQL + React>. Pasta `implementacao/` ativa. Memória do projeto carregada.
F0.3 — Discovery em rodadas
Rodada 1 — perguntas obrigatórias agrupadas por tema. Use o template em references/discovery-questions.md. Selecione perguntas baseado no que ainda é UNKNOWN após F0.2.
Sempre aborde, no mínimo:
- Domínio / regra de negócio chave
- Modelo de dados / impacto no banco
- Segurança e autorização (obrigatório — ver
references/security-rules.md)
- Performance / escala quando aplicável
- Compliance (LGPD, PCI, etc.) quando aplicável
- Validação / testes — como o usuário quer validar (manual, automatizado, smoke, dupla validação SSR+DOM em apps com SSR)
Formato:
📋 **Discovery — rodada 1**
**Domínio e regras de negócio**
1. [pergunta] _(sugestão se inferível)_
2. ...
**Dados e persistência**
3. ...
**🔒 Segurança e autorização** _(obrigatório)_
4. ...
**Validação e testes**
5. ...
💡 Se preferir, posso seguir com as sugestões padrão e você corrige no checkpoint.
Rodada 2 (e seguintes) — apenas se respostas levantarem novos UNKNOWNS críticos. Não force rodadas extras só pra parecer detalhista.
F0.4 — Checkpoint do discovery
Resumo curto + opções:
📝 **Resumo do que entendi:**
- Demanda: ...
- Entidades: ...
- Atores e permissões: ...
- 🔒 Modelo de segurança: ...
- Validação esperada: ...
🔄 **O que deseja fazer?**
1. ✅ Continuar — gerar docs base + pré-criar fases
2. ➕ Adicionar / corrigir algo
3. 🔍 Discutir alternativa de arquitetura
4. ❓ Mais perguntas
Avançar APENAS quando o usuário confirmar.
F0.5 — Architecture Overview (apenas para demanda Épica)
Quando a demanda for grande demais pra uma única SPEC, gere primeiro um architecture-overview.md em implementacao/<slug>/ cobrindo: bounded contexts, integrações entre módulos, ordem de implementação, infra compartilhada. Depois siga F1+ tratando cada bounded context como uma SPEC menor (ou cada um como uma fase, dependendo do tamanho).
F1 — Auto-geração paralela dos docs base
Após confirmação no checkpoint do discovery, um único subagent (modelo padrão, effort padrão) cria em paralelo TODOS os arquivos base, lendo os templates em templates/:
implementacao/<slug>/README.mdimplementacao/<slug>/00-VISAO-GERAL.mdimplementacao/<slug>/01-RESUMO.mdimplementacao/<slug>/02-RESEARCH.mdimplementacao/<slug>/10-LOG-EXECUCAO.md
Use o prompt em agents/md-builder.md. Pase o contexto consolidado do discovery, NUNCA invente — se faltou info, marca [ASSUMPTION: ...] no doc.
A sessão não repete o conteúdo dos docs após gerar — só confirma:
📄 Docs base criados em `implementacao/<slug>/`:
- README.md, 00-VISAO-GERAL.md, 01-RESUMO.md, 02-RESEARCH.md, 10-LOG-EXECUCAO.md
Em seguida, avança automaticamente pra F2 (sem comando do usuário).
F2 — Pré-criação textual das fases + subfases (DISCUSSÃO ÚNICA)
Esse é o ponto crítico do fluxo.
A sessão (modelo da sessão, NÃO subagent — porque envolve julgamento de design) elabora a quebra em fases e subfases e apresenta TUDO de uma vez para discussão única.
Princípios de quebra
- Fase = conjunto coeso de mudanças, com objetivo claro e entregável testável.
- Subfase = unidade construível por subagent em uma única sessão dele — máximo 30–45 min de trabalho de agent.
- Ordem das fases segue dependências (data model → core logic → API → UI → integrações → polish).
- Cada fase contém OBRIGATORIAMENTE as etapas de validação:
- Construção (subagent em modelo padrão, effort padrão) — invocar
frontend-design ANTES da construção quando a subfase tiver UI nova
- Testes (sessão escreve/roda)
- 🔒 Security review (sessão — checklist em
references/security-rules.md + invocar skill security-review em fases sensíveis)
- Quality review (sessão — checklist em
references/quality-rules.md + opcionalmente skill simplify)
- Correções (sessão — sempre que validação falhar)
- Validação final (sessão executa critérios de aceite da fase) — usar
mcp__chrome-devtools__* para validação dupla quando UI
Formato da apresentação
Apresentar como árvore hierárquica enxuta. Não colar todo o conteúdo — só o esqueleto (1 linha por subfase). O .md detalhado vem depois, em F3.
📐 **Plano de fases proposto** (discutir tudo de uma vez):
▸ FASE-00 — <nome curto>
Objetivo: ...
Entregável: ...
Subfases:
A. <título> — arquivos: <paths> · valida: <o que prova que tá certo>
B. <título> — ...
C. <título> — ...
🔒 Security: <pontos específicos desta fase>
✅ Quality gates: testes <unit/int/e2e>, review de <pontos>
▸ FASE-01 — ...
▸ FASE-02 — ...
...
🔄 **O que deseja fazer?**
1. ✅ Está bom — gerar os .md das fases
2. ✏️ Ajustar fase X (descreva o que mudar)
3. ➕ Adicionar/remover fase ou subfase
4. 🔀 Reordenar dependências
5. 📊 Detalhar mais [segurança / testes / arquitetura]
Iterar quantas vezes o usuário quiser. Só avançar pra F3 quando ele aprovar tudo.
F3 — Geração paralela dos .md das fases
Disparar UM subagent (modelo padrão, effort padrão) que cria todos os arquivos fases/FASE-XX-*.md em paralelo (cada Write é uma chamada independente). Usar o template em templates/FASE-template.md. Prompt em agents/md-builder.md.
Cada .md de fase contém:
- Cabeçalho (objetivo, dependências, duração, entregável)
- Cada subfase com: descrição, arquivos, padrões, critérios de aceite, checklist de segurança, estratégia de teste, comandos de verificação
- Riscos e mitigações
- Bloco "Log da fase" (checklist marcado durante execução)
Confirmação curta:
📄 Fases criadas em `implementacao/<slug>/fases/`: <N> arquivos.
Pronto para iniciar execução. Rodar com: `executar fase 00` (ou diga "iniciar fase X").
F4 — Execução fase a fase
Para cada fase, o loop é:
para cada subfase:
1. [Subagent — modelo padrão, effort padrão] CONSTRUÇÃO
2. [Sessão] TESTES — escrever/rodar testes
3. [Sessão] 🔒 SECURITY REVIEW — checklist obrigatório
4. [Sessão] QUALITY REVIEW — checklist obrigatório
5. [Sessão] CORREÇÕES — se algum review falhou, voltar pra (1) com diff específico
6. [Sessão] VALIDAÇÃO FINAL — critérios de aceite da subfase
7. [Sessão] LOG — atualizar 10-LOG-EXECUCAO.md (resultado, evidências, blockers)
ao terminar todas as subfases:
8. [Sessão] CRITÉRIO DE ACEITE DA FASE — rodar validações da fase inteira
9. [Sessão] LOG DE FASE — fechamento
10. [Sessão] PERGUNTAR AO USUÁRIO — fase X concluída, seguir pra fase X+1?
Quem usa qual modelo
| Etapa | Quem |
|---|
| Construção | Subagent (modelo padrão, effort padrão) — ver agents/builder.md |
| Testes | Sessão |
| Security review | Sessão |
| Quality review | Sessão |
| Correções pós-review | Sessão (a menos que o usuário peça outro agent) |
| Validação final | Sessão |
| Atualização de log | Sessão |
O usuário pode override: "use Opus para construir esta fase" ou "use Haiku, é simples". Respeite.
Comando de execução
Quando o usuário disser "executar fase X" ou "iniciar fase X" ou variantes:
- Ler
fases/FASE-XX-*.md completo
- Para cada subfase, executar o loop acima
- Atualizar
10-LOG-EXECUCAO.md ao final de cada subfase E ao final da fase
Não execute mais de uma fase sem confirmação do usuário — ele pode querer revisar entre fases.
Comportamento se uma validação falha
- Pequeno desvio: a sessão corrige direto (mais barato e rápido).
- Mudança grande: re-disparar subagent com prompt corretivo (diff exato do que precisa mudar).
- Bloqueio externo (ex: dependência ausente, decisão de produto): pausar, perguntar ao usuário, registrar no log.
Ferramentas integradas (skills, MCPs e comandos do Claude Code)
A skill deve acionar outras ferramentas do harness sempre que se aplicarem. Não reinventar o que já existe.
⚠️ Regra inegociável — subagents NÃO acessam Skill/MCP
Subagents disparados via Agent tool não enxergam o Skill tool nem os MCPs registrados na sessão. Eles têm apenas as ferramentas built-in (Read, Write, Edit, Bash, Grep, Glob, WebFetch, etc.).
Por isso, toda skill ou MCP que a subfase precisar é executada PELA SESSÃO ANTES de delegar, e o output é embutido no prompt do builder como contexto resolvido. O builder só implementa.
Padrão de injeção:
-
Sessão identifica que a subfase precisa de uma skill (ex: tem UI nova → frontend-design).
-
Sessão invoca Skill(frontend-design, args=...) — recebe specs de design, hierarquia de componentes, tokens, breakpoints.
-
Sessão monta o prompt do builder colando o output da skill em uma seção marcada:
# CONTEXTO DE SKILL JÁ RESOLVIDO PELA SESSÃO
## frontend-design — implementar fielmente
<colar output da skill aqui>
-
Builder agent recebe esse contexto pronto, sem precisar invocar nada.
Mesma lógica para MCP: se a validação de UI exige chrome-devtools, a sessão é quem roda — depois do builder terminar.
Mapa de quem invoca o quê:
| Recurso | Invocado por | Quando |
|---|
Skill(frontend-design) | Sessão, antes de delegar | F2 (planejamento) e F4 (antes de cada subfase com UI) |
Skill(claude-api) | Sessão, antes de delegar | Antes de subfase que toca @anthropic-ai/sdk |
Skill(seo-audit) | Sessão | F0.2 (pré-discovery) e F4 (página pública nova) |
Skill(security-review) | Sessão | F4, ao final da fase, ANTES do commit |
Skill(simplify) | Sessão | F4, ao final de fase grande |
mcp__chrome-devtools__* | Sessão | Validação pós-construção em subfases de UI |
mcp__sequential-thinking__* | Sessão | Trade-offs arquiteturais em F0.5/F1 |
mcp__fetch__* | Sessão | Research em F1 |
Read/Write/Edit/Bash/Grep/Glob | Builder ou sessão | Ambos |
Em resumo: subagent recebe um prompt completo e auto-contido. Skills/MCPs são "pré-processadores" que a sessão usa pra montar esse prompt. Nunca peça pro builder invocar skill — ele não consegue.
Skills do Claude Code (invocar via Skill tool)
| Skill | Quando usar dentro do spec-a23 |
|---|
frontend-design | Em F2 (planejamento) e F4 (execução) sempre que a fase tiver UI nova ou redesenho. Sessão invoca antes de delegar e cola o output no prompt do builder na seção # CONTEXTO DE SKILL JÁ RESOLVIDO. Builder não chama. |
seo-audit | Em F0.2 (pré-discovery) quando a demanda mencionar SEO, ranking, indexação, tráfego. Em F4 quando a fase incluir página pública nova. |
security-review | Em F4, ao final de fase com mudanças sensíveis (auth, pagamento, upload, multi-tenant). Complementa o checklist de references/security-rules.md — a sessão roda os dois. |
review | Quando o usuário pedir review de PR aberto durante a execução. |
simplify | Após uma fase grande, antes de fechar — pra revisar reuso/qualidade no que o builder produziu. |
schedule | Ao fim de uma SPEC com follow-up natural (cleanup de feature flag, soak window, métrica a verificar) — oferecer agendar agente futuro. |
napkin | Sempre lida no início do projeto — entra junto com MEMORY.md em F0.2. |
claude-api | Se a fase mexer em código que importa @anthropic-ai/sdk — disparar antes de mexer em prompt/tool config. |
MCPs disponíveis (invocar quando aplicável)
| MCP | Quando usar |
|---|
mcp__chrome-devtools__* | Validação de UI em F4 (subfases com frontend): navigate_page + take_snapshot + take_screenshot + list_console_messages + lighthouse_audit. Padrão "validação dupla" em apps com SSR (curl do HTML cru + DOM hidratado, com sleep 3 após navegação). |
mcp__sequential-thinking__sequentialthinking | Em F0.5 (Architecture Overview de demanda épica) e em F1 (raciocínio sobre trade-offs arquiteturais complexos). Não usar pra coisa simples — custa tokens. |
mcp__memory__* | Complementar ao MEMORY.md da auto-memory. Salvar entidades/relações cross-session de SPEC grandes (ex: Coupon como entidade com relações). Ler em F0.2. |
mcp__filesystem__* | Alternativa ao Read/Write quando precisar de operações em lote ou diretórios fora do CWD. Padrão é usar Read/Write/Glob/Grep do harness. |
mcp__fetch__* | Pesquisa web em F0/F1 (research técnico). Salvar achados relevantes em 02-RESEARCH.md. |
mcp__wuzapi__* | Apenas se a fase envolver integração com WhatsApp (envio de mensagens, webhooks, sessão). |
Ferramentas nativas do harness
Agent (subagent_type: general-purpose, sem especificar model/effort — herda o padrão da sessão) — F1, F3 e construção em F4. Sempre seguir prompts em agents/builder.md e agents/md-builder.md.Glob + Grep — F0.2 pré-discovery (paralelo).Read — leitura direta de templates, MEMORY.md, CLAUDE.md, fases.Edit — correções pequenas em F4 review (mais barato que reagent).Bash — rodar testes, curl de validação, git status/diff/log.TaskCreate — apenas se a SPEC tiver muitas fases (≥ 5) e o usuário quiser tracking visual. Default: usar o log da SPEC.
Como decidir entre skill embutida vs raciocínio próprio
- Tem skill que cobre exatamente o caso (frontend-design, seo-audit, security-review)? → invocar skill.
- É decisão de arquitetura única dessa SPEC? → raciocínio próprio (sessão).
- É código que precisa rodar em paralelo / volumoso? → subagent.
- É review final? → sessão (com possível chamada à skill
security-review ou simplify no fim).
Checklists obrigatórios (referências)
A sessão usa essas referências durante reviews — leia-as quando for executar a fase, não no momento da geração da SPEC.
- 🔒 Segurança:
references/security-rules.md — input validation, authn/authz, injection, data exposure, secrets, rate limit, CSRF, SSRF, deserialização insegura, headers, log seguro.
- ✅ Qualidade:
references/quality-rules.md — testes, manutenibilidade, observabilidade, performance, acessibilidade, padrões do projeto.
- 📋 Discovery:
references/discovery-questions.md — banco de perguntas por categoria.
- 🤖 Subagent prompts:
agents/builder.md, agents/md-builder.md, agents/reviewer.md.
Templates
Modo Autopilot (execução autônoma com gate de usage)
Disparado quando o usuário diz qualquer variante de:
- "modo autopilot", "modo automático", "deixa rodando", "pode seguir sozinho"
- "vou dormir, [continue/execute/pause em X%]"
- "executa tudo até acabar", "não me pergunte"
- "pause em 90% e retome no reset"
Princípios do autopilot (NÃO negociáveis)
- Decisão é da skill, não do usuário. No autopilot a sessão decide tudo: classificação de risco, escolha de padrão, correção de review, qual subfase fazer primeiro, quando agrupar testes. Nunca para pra perguntar — escolhe a opção mais segura e segue, registrando a decisão no log.
- Toda validação humana vira validação automática + tarefa de teste manual documentada. Onde a SPEC original previa "smoke manual pelo Janderson", o autopilot:
- Roda a validação automatizada equivalente (curl, MCP chrome-devtools, lighthouse, snapshot, etc.).
- Registra no
10-LOG-EXECUCAO.md uma seção "Testes humanos pendentes" com passos detalhados pra você executar quando acordar.
- Pendências de produto/decisão de negócio NÃO param a execução. Se aparecer "esse comportamento depende de o cliente decidir" → escolhe o default mais conservador documentado no
02-RESEARCH.md, marca [ASSUMPTION-AUTOPILOT: ...] e segue. Cria entrada em "Decisões pendentes de revisão" no log.
- Só para de vez se for blocker técnico irrecuperável. Definição estrita:
- Falha de build/teste/lint que persiste após 2 tentativas de correção pelo modelo.
- Dependência externa indisponível (banco caiu, npm registry fora, gateway de pagamento sem credencial real e a fase EXIGE chamada real).
- Conflito de merge com mudanças desconhecidas no branch que o modelo não consegue resolver com segurança.
- Limite de plano semanal (
weekly_pct ≥ 95%) com reset > 24h.
Em qualquer outro caso: prossegue. Reviews de segurança/qualidade/teste que o modelo conseguir resolver sozinho, ele resolve sozinho.
- Nunca usa
--no-verify, nunca dá git push, nunca executa operação destrutiva irreversível (apagar dados, remover arquivos de config/segredos, force-push). As regras destrutivas continuam valendo — o autopilot não "afrouxa" segurança pra terminar.
- Sempre comita por fase, mesmo no autopilot — exatamente como em modo manual.
Gate de usage (5h + semanal via API oficial OAuth)
Antes de cada subfase a sessão roda:
bash ~/.claude/skills/spec-a23/scripts/check-usage.sh
O script consulta GET https://api.anthropic.com/api/oauth/usage — mesmo endpoint que o slash /usage usa internamente. Lê o accessToken OAuth de ~/.claude/.credentials.json (escopos user:inference + user:profile, gerados pelo login do Claude Code). Retorna percentuais reais do plano Max/Pro, sem inferência. Cache local de 90s em $TMPDIR/spec-a23-usage-cache.json evita 429.
JSON de saída:
{
"gate": "GO|CAUTION|PAUSE",
"reason": "5h X% | semanal Y%",
"five_hour": { "pct_used": 65.0, "resets_at": "ISO timestamp" },
"seven_day": { "pct_used": 60.0, "resets_at": "ISO timestamp" },
"config": { "pause_pct": 90, "caution_pct": 85, "cache_ttl_sec": 90, "source": "api.anthropic.com/api/oauth/usage" }
}
Variáveis opcionais: SPEC_A23_PAUSE_PCT (default 90), SPEC_A23_CAUTION_PCT (default 85), SPEC_A23_USAGE_TTL (default 90s).
Códigos de saída: 0 ok · 1 API falhou · 2 credencial ausente / token expirado · 3 node não encontrado.
Decisão do gate: trigger_pct = max(five_hour.pct_used, seven_day.pct_used).
gate | Condição | Ação no autopilot |
|---|
GO | trigger_pct < 85% | Executa subfase normalmente |
CAUTION | 85% ≤ trigger_pct < 90% | Executa apenas se a subfase for "leve" (< 5 arquivos, sem subagent pesado). Caso contrário trata como PAUSE. |
PAUSE | trigger_pct ≥ 90% | Pausa autopilot e dorme até resets_at da janela que disparou |
Bloqueio semanal duro: se seven_day.pct_used ≥ 95% e resets_at - now > 24h, registrar blocker no log e parar de vez (não adianta ScheduleWakeup).
ccusage foi descontinuado nesta skill — divergia do /usage real (denominador inferido). Não voltar a usar.
Como pausar e retomar (uso de ScheduleWakeup)
ScheduleWakeup aceita delay máximo de 1h (3600s). O autopilot faz polling em janelas de 1h até passar do reset_at:
- Calcular
wait_seconds = min(reset_at - now + 60s_buffer, 3600)
- Atualizar log: entrada
## YYYY-MM-DD HH:mm — AUTOPILOT PAUSE com usage_pct, reset_at, próximo wake em <wait_seconds>s.
- Chamar
ScheduleWakeup com delaySeconds=wait_seconds, reason="autopilot pausa por usage X% — proximo check em Yh", prompt="<<retomar autopilot da fase X subfase Y>>".
- Quando acordar: re-rodar gate. Se ainda
PAUSE → repete passo 2. Se GO ou CAUTION → registra ## YYYY-MM-DD HH:mm — AUTOPILOT RESUME no log e segue.
- Janela semanal: se
weekly_pct ≥ 95% e reset > 24h → registra blocker, para de vez, deixa o usuário acordar e decidir.
Aviso obrigatório ao entrar em autopilot
Quando o autopilot é ativado, a sessão emite uma única mensagem pro usuário e depois entra em modo silencioso (só log):
🤖 Modo autopilot ativado.
Configuração:
- Gate de usage (5h + semanal, fonte: /api/oauth/usage oficial): PAUSE em ≥ 90%, CAUTION em ≥ 85%
- Bloqueio semanal duro: ≥ 95% com reset > 24h
- Validações humanas: serão executadas como automáticas e documentadas em "Testes humanos pendentes"
- Decisões de produto: usarei o default conservador e marcarei como [ASSUMPTION-AUTOPILOT]
- Commit por fase: continua valendo
⚠️ Mantenha o Claude Code aberto — o autopilot depende da sessao ativa.
Se fechar o terminal/laptop, a execucao para ate voce reabrir.
📄 Acompanhamento em: implementacao/<slug>/10-LOG-EXECUCAO.md
🛑 Pra interromper: digite "parar autopilot".
Iniciando da fase X subfase Y.
Depois disso, silêncio — só fala quando: blocker irrecuperável, mensagem do usuário, ou conclusão da SPEC inteira.
Seção do log no autopilot
A sessão acrescenta no 10-LOG-EXECUCAO.md (em adição ao formato normal):
## YYYY-MM-DD HH:mm — AUTOPILOT START
- Modo: autopilot
- Iniciado em: FASE-XX subfase Y
- Gate config: PAUSE 90% / CAUTION 85% / weekly blocker 95%
- Estimativa de fases restantes: <N>
## YYYY-MM-DD HH:mm — AUTOPILOT PAUSE
- Motivo: usage 5h = X% (limite >= 90%) | weekly = Y%
- reset_at: ISO timestamp
- ScheduleWakeup em: <segundos>s
- Próxima ação ao acordar: re-checar gate
## YYYY-MM-DD HH:mm — AUTOPILOT RESUME
- usage 5h = X% | weekly = Y%
- Retomando: FASE-XX subfase Y
## YYYY-MM-DD HH:mm — DECISÃO AUTÔNOMA
- Contexto: <onde apareceu>
- Opção escolhida: <X>
- Alternativas descartadas: <lista curta>
- Justificativa: <por que essa é a mais conservadora/segura>
- Marcado como: [ASSUMPTION-AUTOPILOT: ...] (se aplicável)
## TESTES HUMANOS PENDENTES (acumulativo)
> Esta seção fica no topo do log e é atualizada continuamente.
> Quando o usuário acordar, validar manualmente:
### FASE-XX subfase Y — <título>
- [ ] <passo 1: ex. "Abrir /admin/cupons e clicar em Criar — verificar que modal abre">
- [ ] <passo 2>
- [ ] Critério: <como saber que passou>
## DECISÕES PENDENTES DE REVISÃO (acumulativo)
> Decisoes tomadas com [ASSUMPTION-AUTOPILOT] que voce pode querer ajustar:
- FASE-XX: <decisão> — corrigir editando <arquivo> se preferir <alternativa>
Comando de interrupção
Se o usuário digitar "parar autopilot" / "stop autopilot" / "pause" a qualquer momento (mesmo via wakeup), a sessão:
- Termina a subfase em andamento (não para no meio).
- Comita o que conseguiu.
- Sai do autopilot, registra
## AUTOPILOT STOP no log, retorna controle.
Limitações honestas (mostrar uma vez ao ativar)
- Depende da sessão local ativa — laptop fechado mata o autopilot.
- O endpoint
/api/oauth/usage é interno do Claude Code (não documentado publicamente) — pode mudar de schema sem aviso. Se gate retornar erro, conferir resposta crua com bash check-usage.sh --raw.
- Token OAuth expira (
expiresAt em .credentials.json) — Claude Code aberto faz refresh automático; se rodar com Claude fechado por dias, o script retorna exit 2 e pede claude login.
- Cache de 90s — picos curtos podem demorar até 1m30s pra refletir no gate.
- Estimativa de "subfase leve vs pesada" é heurística (tamanho do prompt + nº arquivos), pode errar.
Otimizações de custo / velocidade
- Reaproveitar contexto — carregar memória + CLAUDE.md uma única vez no início; não re-ler arquivos sem necessidade.
- Paralelizar I/O — Glob/Grep/Read em uma única mensagem sempre que independentes.
- Subagents em paralelo quando geram arquivos diferentes (F1 e F3).
- Output mínimo na sessão — docs em
.md, sessão só comunica status. Reduz tokens consumidos.
- Não re-emita conteúdo já escrito em arquivos — só referencie path.
- Não pergunte o que dá pra detectar — F0.2 antes de F0.3.
- Não especifique
model/effort no subagent de construção — herda o modelo padrão e o effort padrão da sessão.
- Validação pela sessão já tem o contexto carregado — não reespawnar agent só pra validar.
Recuperação de erro
- Faltou contexto crítico: marcar
[ASSUMPTION: ...] e listar em 00-VISAO-GERAL.md numa seção "Suposições a revisar".
- Subagent retornou algo errado: reescrever prompt, NÃO assumir que tá certo só porque retornou.
- Conflito de slug: anexar
-v2, -v3 etc.
- Fase explodiu de escopo durante execução: parar, perguntar ao usuário, sugerir quebra em mais subfases.
Exemplo curto de interação
Usuário: /spec-a23 painel admin para gerenciar cupons de desconto com validade e limite de uso
Sessão:
🔍 Detectei: <stack do projeto>. Pasta `implementacao/` ativa.
📋 Discovery — rodada 1
**Domínio**
1. Cupons são por tenant (se o app for multi-tenant) ou globais?
2. Tipo de desconto: percentual, valor fixo, frete grátis, ou todos?
3. Quem cria cupons: admin global, admin de área, ou ambos?
**Dados**
4. Limite de uso é por cupom (total) ou por usuário?
5. Já existe entidade Discount/Coupon ou é criar nova?
**🔒 Segurança e autorização**
6. Quais permissões precisam ser checadas pra criar/editar/aplicar cupom?
7. Cupom expirado ou esgotado retorna que erro?
**Validação**
8. Como você quer validar: smoke manual + testes de unit nas regras críticas?
[usuário responde]
Sessão:
📝 Resumo: cupons por tenant, tipos %/fixo/frete, criados por admin de área, limite total e por usuário, nova entidade Coupon, permissão "manage Coupon" checada no backend, smoke + unit nas regras de cálculo.
🔄 1. ✅ Continuar 2. ✏️ Corrigir 3. ❓ Mais perguntas
[usuário: 1]
→ F1 dispara subagent que cria 5 docs base.
→ F2 a sessão apresenta plano de fases (F0 schema → F1 backend regra → F2 admin UI → F3 aplicação no checkout → F4 testes/observabilidade).
→ Discussão.
→ F3 cria os 5 .md de fases em paralelo.
→ F4 executa cada fase com builder agent + reviews da sessão.
