xufang5219/agent-skills

Ask Matt

Você não se lembra de todas as skills, então pergunte.

Antes de afirmar o que uma skill faz ou recomendar que uma etapa seja pulada, leia o SKILL.md daquela skill: os resumos aqui são apenas para orientação.

Um fluxo é um caminho através das skills. A maioria dos caminhos segue um fluxo principal, e duas rampas de acesso se fundem a ele. Todo o resto é independente ou uma camada de vocabulário que roda por baixo.

O fluxo principal: ideia → lançamento

A rota que a maioria do trabalho percorre. Você tem uma ideia e quer que ela seja construída.

1. /grill-with-docs aprimora a ideia por meio de entrevista. Comece aqui sempre que estiver trabalhando em um diretório de trabalho: é stateful, retendo o que aprende em GLOSSARY.md e ADRs. (Sem diretório de trabalho? Use /grill-me em vez disso, coberto em Standalone. Ambos executam o mesmo primitivo /grilling; grill-with-docs é aquele que deixa um rastro documental, o que o torna o melhor dos dois sempre que houver um repositório para deixá-lo.)

2. Ramificação: você consegue resolver todas as perguntas em conversa? Se uma pergunta precisa de uma resposta executável (estado, lógica de negócio, uma UI que você precisa ver), faça um desvio por um protótipo, intermediado por /handoff em ambas as direções (um protótipo vive em seu próprio diretório, que é exatamente para isso que /handoff serve; veja Limites de fase):

   • /handoff para sair, depois abra uma nova sessão naquele arquivo,
   • /prototype para responder à pergunta com código descartável,
   • /handoff de volta com o que aprendeu, e referencie-o a partir do tópico da ideia original.

3. Ramificação: isso é uma construção de múltiplas sessões?

   • Sim → /to-spec (transforme o tópico em uma especificação), depois /to-tickets para dividi-lo em tickets de bala traçadora, cada um declarando suas arestas de bloqueio. Em seguida, trabalhe os tickets de uma das duas maneiras:
     • /implement por ticket, limpando o contexto entre cada um (/clear). Em um rastreador local, isso é um arquivo por ticket em .scratch/<feature>/issues/, trabalhados primeiro pelos bloqueadores manualmente; em um rastreador real, as arestas se tornam links de bloqueio nativos, então qualquer ticket cujos bloqueadores estejam concluídos pode ser pego. Cada ticket é autocontido, então o contexto do último é descartável.
     • /implement-spec para toda a especificação em uma execução. Ele lê os tickets como um grafo de tarefas, executa subagentes implementadores na fronteira pronta em paralelo e consolida tudo em um ramo de integração. Recorra a ele quando preferir orquestrar a construção em vez de conduzir cada ticket você mesmo.
   • Não → /implement aqui mesmo, na mesma janela de contexto.

   De qualquer forma, o código é construído usando /tdd (uma fatia vermelho-verde de cada vez) e finalizado com /code-review, uma revisão de dois eixos (Padrões + Especificação) do diff. /implement executa ambos por ticket; os implementadores do /implement-spec cada um roda /tdd, e ele executa um /code-review sobre o ramo de integração. Recorra a /tdd por conta própria quando quiser apenas construir um comportamento concreto com teste primeiro, sem uma especificação completa, e /code-review por conta própria sempre que quiser revisar um ramo ou PR contra um ponto fixo.

   Quando o trabalho sobe como um pull request, /pr molda o corpo: o menor visual que mostra a mudança, evidências de antes/depois de que funciona e uma chamada de porta unidirecional ou bidirecional. É invocado pelo modelo, então o agente o alcança sempre que escreve um PR.

4. /retro fecha o ciclo. Após uma construção, especialmente uma que deu errado, ele analisa a sessão e sugere mudanças no ambiente do agente, não no código: ponteiros de navegação, verificações automatizadas, os padrões de codificação que /code-review aplica, arquivos de direção, ferramentas. Erros mecânicos tornam-se verificações determinísticas; decisões de julgamento tornam-se padrões de codificação. A próxima construção então começa de um ambiente melhor.

Higiene de contexto

Mantenha as etapas 1–3 em uma janela de contexto ininterrupta (não compacte ou limpe até depois de /to-tickets) para que a entrevista, especificação e tickets se baseiem no mesmo pensamento. Cada /implement então começa fresco, trabalhando a partir do ticket. Execute /retro na sessão que está sendo analisada, antes de limpar; após limpar, aponte-o para o log dessa sessão.

O limite para isso é a zona inteligente: a janela (~150k tokens em modelos de ponta) dentro da qual o modelo ainda raciocina nitidamente. Se uma sessão se aproximar dela antes de /to-tickets, não insista com degradação; use /compact no limite de fase mais próximo e continue (veja Limites de fase).

Rampas de acesso

Uma situação inicial que gera trabalho e depois se funde ao fluxo principal.

• Bugs e solicitações se acumulando → /triage. Ele move issues através de funções de triagem e produz issues prontas para o agente, que /implement posteriormente pega.

  A triagem é apenas para issues que você não criou: relatórios de bug, solicitações de funcionalidades recebidas, qualquer coisa que chegue crua. Tickets que /to-tickets produziu já estão prontos para o agente, então não os trie.

• Algo está quebrado → /diagnosing-bugs. Para os difíceis: o bug que resiste a um primeiro olhar, a falha intermitente, a regressão que se infiltrou entre dois estados conhecidos como bons. Ele se recusa a teorizar até ter um ciclo de feedback apertado (um comando que já fica vermelho neste bug), então corrige com um teste de regressão. Assim que a correção estiver no lugar, execute /retro na mesma sessão para perguntar o que teria prevenido o bug; onde a verdadeira descoberta é que não há uma boa costura para bloqueá-lo, isso é trabalho para /improve-codebase-architecture.

• Um esforço enorme e nebuloso: um projeto greenfield ou uma grande construção de funcionalidade, grande demais para uma sessão → /wayfinder, o fluxo mais cognitivamente exigente aqui. Quando o caminho daqui até o destino ainda não está visível, ele mapeia um mapa compartilhado de tickets de decisão no rastreador de issues e os resolve um de cada vez, produzindo decisões, não entregáveis, até que a névoa seja empurrada para trás e o caminho esteja claro. Onde /grill-with-docs aprimora uma ideia que você pode manter em uma sessão, o wayfinder é para a ideia que você não pode, e é mais lento e denso, então guarde-o exatamente para isso, nunca para uma funcionalidade bem escopada.

  Quando o mapa clareia, ele faz handoff, não constroi: funda-se ao fluxo principal em /to-spec, que colapsa as decisões vinculadas do mapa em um plano construível, então /to-tickets e /implement como de costume. Loopar o mapa diretamente em /implement pula esse colapso e joga fora os detalhes vinculados, então vá direto para /implement apenas quando o esforço se revelar genuinamente pequeno.

Saúde do código

Não é trabalho de funcionalidade, apenas manutenção.

• /improve-codebase-architecture executa sempre que você tiver um momento livre para manter o código-fonte bom para os agentes operarem. Ele revela oportunidades de aprofundamento; escolher uma gera uma ideia que você pode levar para o fluxo principal em /grill-with-docs. É a pesquisa que encontra os candidatos; /codebase-design (abaixo) é a bancada onde você projeta o escolhido.

Vocabulário subjacente

Duas referências invocadas pelo modelo que rodam por baixo das outras skills, cada uma a única fonte da verdade para seu vocabulário. Recorra a elas diretamente quando as palavras, e não o processo, forem o problema; ou deixe que as skills acima as puxem.

• /domain-modeling: aprimora a linguagem de domínio do projeto: desafie um termo impreciso, resolva uma palavra sobrecarregada ("conta" fazendo três trabalhos), registre uma decisão difícil de reverter como um ADR. É a disciplina ativa que /grill-with-docs impulsiona para manter GLOSSARY.md um glossário limpo.
• /codebase-design é o vocabulário de módulo profundo (módulo, interface, profundidade, costura, adaptador, alavancagem, localidade) para projetar a forma de um módulo: muito comportamento por trás de uma interface pequena em uma costura limpa. /tdd e /improve-codebase-architecture ambos falam essa linguagem.

Limites de fase

Uma fase é um pedaço de trabalho dentro de uma sessão: a entrevista, a implementação, o QA. No limite entre duas delas, você tem cinco opções, e escolher entre elas é a decisão mais difusa em todo este mapa:

• Continuar: fique onde está. Não custa nada, não perde nada.
• /clear: esvazie a janela, quando nada aqui importa para o que vem a seguir.
• /handoff escreve um arquivo markdown portátil. Estreito: apenas para um novo harness, um novo diretório, um colega, ou bifurcar uma tarefa lateral no meio da fase. O que ele compra é portabilidade.
• Subagente: envie uma tarefa com escopo restrito para sua própria janela e receba um relatório de volta.
• /compact comprime este contexto e semeia uma nova sessão com ele. O padrão, na base da árvore em vez do primeiro alcance.

Leia PHASE-BOUNDARIES.md para a árvore ordenada: as cinco perguntas, o raciocínio por trás de cada ramo e por que o custo da fonte primária faz de Continuar aquele a ser descartado primeiro. Tome a decisão no limite; no meio da fase, continue ou divida o restante em subagentes.

Standalone

Fora do fluxo principal completamente.

• /grill-me: a mesma entrevista implacável que /grill-with-docs, mas stateless: não salva nada localmente e não constroi GLOSSARY.md. Recorra a ele quando você não estiver trabalhando em um diretório de trabalho (aprimorando um plano, um design, um texto, qualquer coisa sem um repositório por baixo). Se você estiver em um diretório de trabalho, use /grill-with-docs: ele executa a mesma entrevista e deixa um rastro documental, então é estritamente o melhor.
• /grilling é o primitivo de entrevista em si: rodadas, a fronteira, fatos são trabalho do agente e decisões são suas. /grill-me e /grill-with-docs são as duas maneiras nomeadas de entrar, e /triage, /wayfinder e /improve-codebase-architecture todos o executam internamente. Recorra a ele diretamente apenas quando quiser a entrevista sem nenhum invólucro.
• /prototype é um pequeno programa descartável que responde a uma pergunta de design: este modelo de estado parece certo, ou como deve ser esta UI. Descartável é uma restrição sobre como o código é escrito, não uma promessa de destruí-lo: a resposta se dobra no código real, e o protótipo em si é mantido como uma fonte primária em um ramo prototype/<name> a partir do main, apontado a partir da issue de implementação. É o desvio na etapa 2 do fluxo principal, mas recorra a ele sempre que uma pergunta de design for difícil de resolver no papel.
• /research: delegue trabalho de leitura a um agente de fundo: ele investiga uma pergunta contra fontes primárias, depois deixa um arquivo Markdown citado no repositório. Continue trabalhando enquanto ele lê. O arquivo que ele produz é algo para levar para o fluxo principal em /grill-with-docs, já que a pesquisa alimenta o pensamento em vez de substituí-lo.
• /to-questionnaire surge quando a coisa que está bloqueando você não está na sua cabeça ou no código, mas na de outra pessoa, e ele escreve um questionário para ela preencher. É o inverso de /grill-me: em vez de entrevistar você sobre o assunto, ele entrevista você sobre o envio (para quem vai, o que você precisa de volta) e aponta as perguntas para a lacuna. O que retorna é material para /grill-with-docs ou /to-spec.
• /wizard é para os passos que apenas um humano pode dar: provisionar infraestrutura, configurar credenciais ou segredos de CI, navegar por um dashboard de terceiros desconhecido, executar uma migração ou cutover único. Ele gera um script bash interativo que abre cada URL, captura cada valor e o escreve em .env e segredos do GitHub, para que o procedimento pare de ser algo que você reexplica a um agente toda vez. Invocado pelo modelo, então o agente o alcança no momento em que encontra uma parede que só você pode passar. Se o agente pudesse simplesmente fazer isso sozinho, deveria; isso é para onde um humano está genuinamente no loop.
• /wait-what é o corretivo para uma mensagem que não foi compreendida. Use-o no meio da conversa, dentro de qualquer outra skill, e o agente reformula o que acabou de dizer com o contexto que estava faltando, em inglês simples, usando o vocabulário do GLOSSARY.md. Funciona retrospectivamente; /grill-with-docs é a cura preventiva, porque uma linguagem compartilhada acordada no início é o que impede o jargão de aparecer.
• /teach: aprenda um conceito ao longo de várias sessões, usando o diretório atual como um workspace stateful.
• /writing-for-agents é a referência para escrever documentos que agentes consomem: skills, AGENTS.md, documentação apontada.

Pré-condição

/setup-matt-pocock-skills: execute antes do seu primeiro fluxo de engenharia para configurar o rastreador de issues, etiquetas de triagem e layout de documentos que as outras skills assumem. Rastreadores de issues personalizados também funcionam.