🎯 Por que compor
Uma skill resolve um problema. Uma composicao resolve um workflow inteiro. A diferenca nao e tamanho — e intencao. Quando voce chama 3 skills "porque deu na cabeca", isso e uso isolado. Quando voce desenha A → B → C antes de comecar e cada saida alimenta a proxima, isso e composicao.
💡 Dica fundamental
Skill solo resolve 1 problema (gerar PRD, fazer grilling, escrever teste). Composicao resolve um workflow (descobrir → alinhar → fatiar → implementar → revisar). Se voce esta repetindo a mesma sequencia de 3+ skills em projetos diferentes, voce ja tem um pipeline — falta so dar nome a ele.
✓ Encadear conscientemente
- ✓Desenhar o pipeline antes: "grill → PRD → issues → TDD"
- ✓Cada skill recebe saida da anterior como input explicito
- ✓Revisar a saida intermediaria antes de avancar
- ✓CONTEXT.md acumula termos e decisoes entre etapas
- ✓Saber onde parar e voltar uma etapa se necessario
✗ Chamar skills isoladas
- ✗"Roda o /tdd ai" sem ter PRD nem issues
- ✗Pular grilling: implementa rapido, descobre buraco depois
- ✗Cada turno comeca do zero, sem aproveitar contexto anterior
- ✗Saida de uma skill nunca informa input da proxima
- ✗Refaz a mesma sequencia toda vez sem nomear o pipeline
🧩 Padroes de composicao
Existem quatro padroes que cobrem 90% dos pipelines reais. Cada um tem uma forma e um caso de uso claro. Decorar os quatro e ter um vocabulario pra desenhar workflow.
Sequencial (A → B → C)
Cada etapa depende da anterior. Padrao padrao.
A ──▶ B ──▶ C ──▶ D grill PRD issues TDD
Uso: workflow linear (descobrir, planejar, executar).
Fan-out (A → B + C + D)
Uma skill dispara varias em paralelo.
┌─▶ B (testes) A ─────┼─▶ C (docs) plan └─▶ D (impl)
Uso: paralelizar trabalho independente.
Fan-in (B + C → D)
Varias saidas convergem numa skill final.
B (pesquisa) ─┐
├─▶ D (sintese)
C (entrev.) ─┘
Uso: consolidar inputs (revisao, sintese).
Loop (A → B → A)
Iteracao ate criterio de parada.
A ──▶ B ──┐ ▲ │ └─────────┘ (revisa ate aprovar)
Uso: refinamento iterativo (PRD com grilling, code review).
🧠 Combinacoes
Pipelines reais combinam padroes. Ex: sequencial no esqueleto (grill → PRD → issues), com loop dentro do grill (Codex grilla, Claude revisa, ate LGTM), e fan-out na implementacao (cada issue vira branch paralelo).
📜 Exemplo canonico: grill → PRD → issues → tdd
O pipeline mais usado em features de complexidade media. Cinco skills encadeadas, cada uma com um trabalho especifico, cada saida alimentando a proxima. Decorar essa sequencia.
/grill-with-docs aligns
Stress-testa a ideia contra a linguagem do projeto. Saida: termos canonicos, premissas explicitas, conflitos com decisoes anteriores.
"O termo 'cascade' ja existe no CONTEXT.md como 'materialization cascade'. Use esse termo no PRD pra manter linguagem ubiqua."
/to-prd synthesizes
Transforma o resultado do grill em PRD estruturado (problema, solucao, escopo, nao-escopo, sucesso).
Le os termos do CONTEXT.md e usa eles literalmente. PRD vira documento durable, nao rascunho.
/to-issues slices
Quebra o PRD em issues acionaveis (1-3 dias cada). Saida: lista de issues com criterio de aceite.
"Issue #1: criar tabela materialization_cascade. Issue #2: implementar trigger de invalidacao..."
/triage prioritizes
Ordena as issues por dependencia + risco + valor. Decide o que entra na primeira sprint.
"Issue #1 (tabela) bloqueia #2 e #3. Comeca por #1, deixa #4 (UI) pro final."
/tdd implements
Pega uma issue priorizada e implementa via test-first. Saida: codigo + testes + PR.
"Issue #1: escreve teste que falha pra schema, cria migracao, teste passa, commit."
Prompts reais conectando cada etapa
# Turno 1 /grill-with-docs Quero adicionar cache materializado por usuario. # Turno 2 (apos grill atualizar CONTEXT.md) /to-prd Use os termos definidos no CONTEXT.md (materialization cascade, cache invalidation trigger). Gere PRD em docs/prd/cache.md. # Turno 3 /to-issues Le docs/prd/cache.md. Cria issues no GitHub com label "cache". # Turno 4 /triage Le issues com label "cache". Prioriza por dependencia. # Turno 5 /tdd Pega issue #1 (mais alta prioridade). Test-first.
🧠 Estado compartilhado via CONTEXT.md
O segredo de composicao boa nao e ter skills perfeitas — e ter memoria entre elas. CONTEXT.md funciona como cache durable: skill A escreve um termo, skill B le e usa. Sem isso, cada skill comeca do zero e voce reaprende linguagem toda vez.
📝 Como CONTEXT.md vira ponte
CONTEXT.md tem secoes vivas: Glossary (termos canonicos), Decisions (ADRs leves), Open questions (o que ainda nao foi decidido). Toda skill que muda algo durable escreve aqui. Toda skill que comeca le primeiro.
- •Glossary: nomes oficiais (entidades, conceitos, eventos)
- •Decisions: "decidimos X porque Y, alternativas rejeitadas: Z"
- •Open questions: ambiguidades que precisam ser resolvidas
Turno A: /grill escreve no CONTEXT.md
## Glossary
- materialization cascade: sequencia de invalidacoes
disparadas quando uma fonte upstream muda. Substitui o termo
informal "atualizacao em cadeia".
## Decisions
- ADR-007: cache materializado por usuario, nao global.
Motivo: isolamento de tenant. Alternativa rejeitada:
cache global com chave composta (complexidade > beneficio).
Turno B: /to-prd le e usa os termos
# PRD: Cache materializado ## Problema Consultas pesadas rodam toda vez. Precisamos de materialization cascade por usuario. ## Solucao Conforme ADR-007 (ver CONTEXT.md), implementar cache materializado por usuario. Nao global. ## Termos materialization cascade: ver Glossary do CONTEXT.md.
⚡ Truque
Antes de chamar a skill seguinte no pipeline, faca um turno explicito: "atualize o CONTEXT.md com o que descobrimos". Sem isso, a memoria fica na conversa (efemera) e a proxima skill perde tudo.
🏗️ Quando criar uma skill macro
Macro skill = uma skill que chama outras skills em sequencia. Util quando o pipeline e recorrente. Inutil (e perigoso) quando voce esta tentando "automatizar pensamento".
✓ Macro util
- ✓Workflow recorrente (3+ projetos usam a mesma sequencia)
- ✓Time inteiro usa, nao so voce
- ✓Etapas tem entrada/saida bem definidas
- ✓Existe checkpoint humano entre fases (revisao)
- ✓Mais facil de explicar que de re-explicar 5 skills
✗ Macro inutil
- ✗Chamadas isoladas que mudam toda vez
- ✗Logica condicional complexa ("se X faz Y senao Z")
- ✗Macro feita pra "economizar 1 prompt" — gera mais bug que economia
- ✗Pula revisao humana entre etapas criticas
- ✗So 1 pessoa entende o que ela faz
📦 Template de skill macro
--- name: /feature-pipeline description: Pipeline padrao de feature media. Grill -> PRD -> issues -> TDD. --- # Skill: feature-pipeline ## Quando usar Feature nova de complexidade media (2-5 issues). ## Passos 1. /grill-with-docs <descricao da feature> - PARE aqui. Revise o CONTEXT.md atualizado. 2. /to-prd Use termos do CONTEXT.md. - PARE. Aprove o PRD antes de fatiar. 3. /to-issues Le o PRD. Cria issues com label. 4. /triage Prioriza. 5. /tdd Pega a primeira issue. ## Checkpoints humanos Entre passos 1-2 e 2-3 SEMPRE. Nao pula.
🔧 Exemplo pratico: refactor completo
Cenario real: codigo legado com 3 sistemas duplicados de cache. Vamos refatorar usando 5 skills encadeadas. Note o checkpoint humano entre cada uma.
/zoom-out — mapeia a area
Diagrama de quem chama quem, onde os 3 caches vivem, dependencias.
Saida: "Cache A em src/api/, Cache B em src/jobs/, Cache C em src/web/. Sobrepoem em 7 funcoes."
/improve-codebase-architecture — encontra oportunidades
Le o mapa do zoom-out. Propoe unificacao.
Saida: "Unificar em src/cache/. Caches A e B usam mesma semantica (TTL). Cache C precisa de invalidacao manual — manter como subtipo."
/grill-with-docs — alinha approach
Stress-testa a proposta contra CONTEXT.md.
Saida: "Termo correto e 'cache backend' (ADR-003), nao 'cache provider'. Atualiza Glossary."
/to-issues — gera issues
Quebra o refactor em 4 issues sequenciais.
Saida: "#1 criar interface CacheBackend; #2 migrar Cache A; #3 migrar Cache B; #4 adaptar Cache C como subtipo."
/tdd — implementa
Pega issue #1. Test-first.
Saida: PR com interface + testes verdes. Pronto pra issue #2.
Saida resumida de cada turno
[1] /zoom-out -> mapa.md (3 caches, 7 sobreposicoes) [2] /improve-arch -> propostas.md (unificar em src/cache/) [3] /grill-with-docs -> CONTEXT.md++ (Glossary: cache backend) [4] /to-issues -> 4 issues no GH (labels: refactor/cache) [5] /tdd -> PR #142 (interface + testes)
⚠️ Anti-padroes de composicao
Os dois erros mais comuns sao opostos: pular skills pra "ir mais rapido" e nao revisar saidas intermediarias. Os dois geram retrabalho exponencial.
✓ Composicao saudavel
- ✓Toda etapa tem saida em arquivo (PRD.md, issues.json, CONTEXT.md)
- ✓Revisa a saida antes de chamar a proxima skill
- ✓Quando algo esta errado, volta uma etapa, nao tenta consertar na proxima
- ✓Cada skill assume que a anterior fez seu trabalho corretamente
✗ Composicao quebrada
- ✗Pular o grill "pra economizar tempo" → PRD com termos errados → issues sem sentido → retrabalho 3x maior
- ✗Nao ler saida intermediaria → erro propaga e acumula nas proximas etapas
- ✗"Conserta no /tdd" o que deveria estar no PRD → escopo cresce silencioso
- ✗Chamadas em sequencia sem CONTEXT.md → cada skill reaprende vocabulario
🚨 Atencao
O custo de pular uma etapa nao aparece na hora — aparece 2 ou 3 skills depois, quando voce descobre que a saida do /tdd nao bate com o que o PRD pedia. Aquela "economia" de 5 minutos vira 2 horas de re-execucao do pipeline.
🌐 Composicao cross-projeto
Composicao nao precisa ficar dentro de um projeto. Quando dois projetos compartilham dominio (ex: marketplace + admin), usar grill+CONTEXT.md de um pra informar PRD do outro mantem linguagem ubiqua entre repos.
🔗 Fluxo cross-projeto
- Projeto A (marketplace) usa
/grill-with-docse consolida termos no CONTEXT.md. - Copia (ou symlinka) a secao Glossary pro projeto B (admin).
- Projeto B usa
/to-prdreferenciando o mesmo Glossary. - Ambos os PRDs falam "product listing" (nao "produto" num e "anuncio" no outro).
- Quando uma entidade muda em A, atualiza Glossary, B importa de novo.
💡 Dica avancada
Para times multi-repo, manter um SHARED_CONTEXT.md num repo separado (tipo "docs/") que todos os projetos importam funciona melhor que copy-paste manual. Skills leem desse arquivo central, evitando drift de vocabulario.
🏋️ Exercicio pratico
Escolha 1 feature pendente no seu backlog. Componha 3 skills pra entrega-la. Documente cada turno: prompt, saida resumida, decisao tomada.
Roteiro do exercicio
- Escolha a feature: algo de 1-3 dias de trabalho. Nao muito grande, nao muito trivial.
- Desenhe o pipeline: escreva no papel "skill A → skill B → skill C". Justifique cada uma.
- Execute turno 1: chame a primeira skill. Grave o prompt exato.
- Revise a saida: antes de avancar, leia o que saiu. Esta utilizavel?
- Execute turnos 2 e 3: mesmo processo. Cada saida alimenta a proxima.
- Documente: faca um arquivo
pipeline-log.mdcom prompts, saidas, decisoes. - Reflita: onde voce quase pulou uma etapa? Onde a saida intermediaria salvou voce?
🎯 Criterio de sucesso
Voce conseguiu entregar a feature com 3 skills encadeadas, sem voltar pra "consertar" na proxima etapa o que faltou na anterior. Se voltou, anota no log onde e por que — esse e o aprendizado real.
📚 Resumo do Modulo
Proximo Modulo:
3.2 — Pipelines avancados e debugging de composicao