Mapa da trilha
🧭 Por que skills existem
Os 4 problemas que matam projetos com agentes
🔥 Grilling: alinhamento
Pare de adivinhar o que voce quer
📖 Linguagem Ubiqua
1 palavra no lugar de 20
✅ Codigo que Funciona
Red, green, refactor — com agente junto
🏗️ Arquitetura Saudavel
Sair da bola de lama sem refatorar tudo
🔄 Workflow Completo
Da ideia ao PR mergeado
Conteudo detalhado
🧭 Por que skills existem
Os 4 problemas que matam projetos com agentes — e como skills atacam cada um.
Pacote estruturado (SKILL.md + scripts + refs) que o agente carrega sob demanda para executar um trabalho especifico.
Sem skills, voce repete contexto a cada sessao. Com skills, conhecimento fica versionado, testavel e reutilizavel.
SKILL.md, frontmatter, triggers, references, scripts, escopo unico.
Gap entre o que voce pediu e o que o agente entendeu — gera retrabalho silencioso.
E a causa #1 de "agente nao funciona". Reconhecer cedo evita horas de codigo errado.
Ambiguidade, premissas implicitas, falta de exemplos, escopo difuso.
Excesso de palavras, repeticao e ruido no prompt — degrada precisao do agente.
Linguagem ubiqua compacta intent. 1 termo bem definido vale 20 linhas de explicacao.
Token budget, ruido vs sinal, terminologia compartilhada.
Codigo gerado sem testes vivos: aparenta funcionar mas falha em edge cases.
TDD com agente transforma "espero que funcione" em "prova que funciona".
Red/green/refactor, vertical slice, regression test.
Codebase sem fronteiras claras — qualquer mudanca quebra coisas distantes.
Agentes amplificam acoplamento ruim. Skills de arquitetura combatem entropia.
Acoplamento, fronteiras, ADRs, melhoria progressiva.
Sistema de skills do Matt Pocock — grill, ubiqua, tdd, arquitetura — encadeadas no workflow.
Entender o mapa antes do detalhe acelera adocao e evita uso solto.
Composicao, ordem de uso, slash commands, agentic OS.
🔥 Grilling: alinhamento com o agente
Pare de adivinhar o que voce quer — deixe o agente perguntar primeiro.
Tecnica em que o agente faz perguntas afiadas antes de codar — extrai requisitos escondidos.
Evita semanas de retrabalho. 30min de grilling salva 5h de codigo errado.
Adversarial questioning, premissas, escopo, criterios de aceite.
/grill-me ataca a ideia crua; /grill-with-docs confronta o plano com CONTEXT.md e ADRs do projeto.
Usar o modo errado desperdica grilling. Cada um tem gatilho proprio.
Ideia crua, plano maduro, documento de referencia, ADR.
Gatilhos: feature ambigua, decisao arquitetural, conflito de equipe, pre-PRD.
Saber QUANDO grilling agrega evita usar onde nao precisa.
Heuristicas de gatilho, custo/beneficio, timing.
Transcricao anotada de uma sessao /grill-me transformando ideia vaga em PRD acionavel.
Ver na pratica o que e uma boa pergunta vs uma resposta evasiva.
Drill-down, contraexemplo, materializacao de premissa.
Grilling raso, perguntas retoricas, agente concordando sempre — sinal de sessao desperdicada.
Detectar cedo evita ilusao de alinhamento.
Sycophancy, perguntas fechadas, ancoramento.
Grilling fechado vira PRD via /to-prd — sem perda de contexto.
Conecta alinhamento com execucao. Fim do "fiz grilling e perdi tudo".
PRD, criterios de aceite, vertical slices, handoff.
📖 Linguagem Ubiqua: CONTEXT.md + ADRs
1 palavra no lugar de 20 — terminologia compartilhada entre voce e o agente.
Vocabulario compartilhado entre dominio, codigo e agente — mesmo termo, mesmo significado.
Reduz traducao mental. "Materialization cascade" vale por um paragrafo de explicacao.
DDD, bounded context, glossario vivo, conceitos do dominio.
Documento raiz com dominio, conceitos, fronteiras e termos — lido pelo agente em todo contexto.
Sem CONTEXT.md, agente reaprende seu dominio toda sessao.
Secoes obrigatorias, glossario, fronteiras, exemplos.
Registro curto e imutavel de cada decisao arquitetural — contexto, opcoes, escolha e consequencias.
Evita refazer decisao antiga sem saber. Agente respeita restricoes documentadas.
Decisao, contexto, alternativas, status, consequencia.
Caso real do Matt — termo cunhado uma vez no CONTEXT.md, reutilizado em dezenas de prompts.
Ver o ganho concreto de compactacao via vocabulario.
Compactacao semantica, reuso de termo, intent denso.
Rotina de atualizar CONTEXT.md e ADRs em cada PR relevante — nao deixar virar arqueologia.
Documento desatualizado e pior que documento ausente.
Doc-as-code, drift, gates de PR.
Metricas comparando antes/depois de adotar linguagem ubiqua — tokens, tempo de sessao, bugs.
Justificar adocao para o time com numero, nao opiniao.
Token spend, lead time, retrabalho, NPS dev.
✅ Codigo que Funciona: TDD + Diagnose
Red, green, refactor — com agente junto. E quando quebra, /diagnose.
TDD usado como contrato entre voce e o agente — teste antes de codigo.
Sem teste primeiro, agente "alucina" comportamento. Com teste, comportamento e verificavel.
Contrato executavel, feedback loop, criterios objetivos.
Slash command que orquestra o ciclo TDD com o agente — gera teste, roda, implementa, refatora.
Padroniza qualidade. Cada feature nasce com teste verde.
Ciclo, gates, automacao do refactor.
Entregar valor minimo end-to-end por vez — UI, API, banco — em vez de camadas horizontais.
Permite TDD real. Cada slice e testavel sozinho.
Slice, walking skeleton, MVP, incremento testavel.
Skill que conduz investigacao sistematica de bug — repro, minimize, hipotetize, testa.
Bug intermitente sem metodo vira loop infinito. /diagnose impoe disciplina.
Hipotese, observacao, isolamento, falsificacao.
Sequencia obrigatoria: reproduzir o bug, reduzir o caso, formular hipotese antes de tocar codigo.
Pular passo gera correcao que mascara o bug.
MCVE, bisect, falsificacao.
Teste escrito a partir do repro minimizado — garante que o bug nao volta.
Sem regression test, voce paga pelo mesmo bug 3x ao ano.
Captura, fixture, mutation testing.
🏗️ Arquitetura Saudavel
Sair da bola de lama sem refatorar tudo — melhoria progressiva guiada por agente.
Sinais: mudar 1 linha quebra 3 features distantes, ninguem sabe onde algo mora, medo de mexer.
Diagnostico vem antes de tratamento. Sem nomear sintomas, voce trata sintoma errado.
Acoplamento, coesao, fronteiras, shotgun surgery.
Skill que escaneia o codigo, identifica hotspots e propoe melhorias priorizadas.
Substitui "refactor de big bang" por intervencoes cirurgicas.
Hotspot, priorizacao, mudanca segura.
Skill que abstrai do arquivo atual para o sistema todo — quebra o tunel de visao.
Decisao local boa pode ser ruim no global. Zoom-out forca visao sistemica.
Macro vs micro, system thinking, cascading impact.
Areas do codigo onde investir em modelagem traz retorno desproporcional.
Tempo e finito. Aprofundar no lugar errado = polir lateral.
Core domain, ROI de modelagem, leverage.
Usar os documentos da trilha 1.3 para guiar onde e como melhorar — agente segue restricoes documentadas.
Refator sem norte vira gosto pessoal. Norte documentado e auditavel.
Restricoes, conformidade, traceability.
Walkthrough de codebase saindo do "lama" para "saudavel" via passos pequenos guiados pelas skills.
Inspira coragem: nao precisa parar tudo para arrumar.
Strangler fig, boy scout rule, branches curtas.
🔄 Workflow Completo
Da ideia ao PR mergeado — todas as skills da trilha em ordem de uso.
Comando que instala todas as skills do Matt no seu Claude Code e prepara o ambiente.
Tudo comeca aqui. Sem setup, o resto da trilha nao funciona.
Bootstrap, dependencias, verificacao.
Fluxo: ideia → /grill-me → /to-prd. Saida e PRD pronto para fatiar.
Conecta modulos 1.2 e 1.6 — sem essa ponte, grilling vira papo perdido.
PRD, criterios de aceite, handoff documental.
/to-prd estrutura o documento; /to-issues fatia em issues testaveis para execucao.
Issue bem fatiada = sprint sem ambiguidade.
Fatiamento, INVEST, criterios de aceite.
Skill que decide qual papel (PM, dev, reviewer) o agente assume conforme estado da issue.
Evita agente atuando como dev quando deveria estar revisando, e vice-versa.
State machine, persona, gates de transicao.
Cada issue triada vira ciclo /tdd — teste, codigo, refactor — ate verde.
E onde teoria vira merge. Sem TDD aqui, qualidade desmorona.
Definition of done, CI gates, slice completo.
Etapa final: review automatica + humana, atualizacao de CONTEXT.md/ADRs, merge.
Sem fechamento doc + review, ciclo "vaza" e arquitetura volta a degradar.
Review gates, doc update, merge policy.