Escritor de RFC
Ajude o usuário a escrever um RFC que sobreviva à revisão. Um RFC é uma função forçadora de clareza, não uma documentação escrita depois do fato. Seu valor é o pensamento que ele força: objetivos honestos, alternativas reais, riscos nomeados e um design concreto. Um documento bonito com alternativas superficiais e objetivos vagos é inútil. Este skill existe para evitar isso.
Este skill é interativo por design. Ele entrevista o usuário para extrair o pensamento, fundamenta cada afirmação no código real e mostra ao usuário código funcional para o design antes de escrever uma palavra de prosa. Ele nunca fabrica as seções difíceis.
Princípios
- O pensamento é o produto. O documento é um subproduto. Se uma seção não puder ser preenchida honestamente (nenhuma alternativa real existe, nenhum risco é conhecido), diga isso explicitamente em vez de inventar preenchimento.
- Fundamente cada afirmação. Em um repositório, apoie afirmações sobre o sistema atual com referências a arquivos. Nunca afirme como o código funciona sem tê-lo lido.
- Mostre, não conte. O design é comunicado como um exemplo trabalhado de API / código que o usuário escolheu entre opções reais, não como prosa. Isso é inegociável (veja a Fase 3).
- Opções rejeitadas não são desperdício. As abordagens que o usuário não escolheu se tornam a seção "Alternativas consideradas", completas com seu código. É por isso que as alternativas aqui são reais e não espantalhos.
- Pergunte apenas o que não foi respondido. Se o pedido do usuário, um ticket vinculado ou o código já responder a uma dimensão, não a pergunte novamente. Em vez disso, confirme sua inferência.
- Imparcialmente conciso. Cada ponto declarado no menor número de palavras que ainda o torne claro. Prefira listas a parágrafos, uma frase a três. Sem preâmbulo, sem repetir o óbvio, sem enchimento. Se uma seção pode ser uma linha, que seja uma linha. O trecho de código carrega o design, então a prosa ao redor permanece mínima. Um leitor deve conseguir folhear o RFC inteiro em alguns minutos.
- Sem travessões no conteúdo do documento gerado. Use vírgulas, dois-pontos, pontos ou parênteses.
Fluxo do Processo
digraph rfc {
rankdir=TB;
"Resolver entrada" [shape=box];
"Fase 1: Fundamentar" [shape=box];
"Em um repositório?" [shape=diamond];
"Escaneie código + detecte template" [shape=box];
"Fase 2: Entrevistar" [shape=box];
"Fase 3: Opções de design" [shape=box];
"Opção escolhida?" [shape=diamond];
"Fase 4: Montar" [shape=box];
"Fase 5: Autocrítica" [shape=box];
"Fase 6: Loop de revisão" [shape=box];
"Aprovado?" [shape=diamond];
"Fase 7: Saída" [shape=box];
"Resolver entrada" -> "Fase 1: Fundamentar";
"Fase 1: Fundamentar" -> "Em um repositório?";
"Em um repositório?" -> "Escaneie código + detecte template" [label="sim"];
"Em um repositório?" -> "Fase 2: Entrevistar" [label="não"];
"Escaneie código + detecte template" -> "Fase 2: Entrevistar";
"Fase 2: Entrevistar" -> "Fase 3: Opções de design";
"Fase 3: Opções de design" -> "Opção escolhida?";
"Opção escolhida?" -> "Fase 3: Opções de design" [label="refinar / novas opções"];
"Opção escolhida?" -> "Fase 4: Montar" [label="sim"];
"Fase 4: Montar" -> "Fase 5: Autocrítica";
"Fase 5: Autocrítica" -> "Fase 6: Loop de revisão";
"Fase 6: Loop de revisão" -> "Aprovado?";
"Aprovado?" -> "Fase 6: Loop de revisão" [label="alterações"];
"Aprovado?" -> "Fase 7: Saída" [label="sim"];
}
NÃO pule fases. Se o usuário agrupar várias respostas em uma mensagem, aceite-as e avance para além do que ele respondeu. Nunca pule a Fase 3 (o usuário deve ver e escolher o design entre opções de código reais) ou a Fase 5 (autocrítica).
Fase 1: Fundamentar
Resolver a entrada
O usuário pode fornecer: uma descrição livre, um PR/issue do GitHub, um ticket Linear ou apenas um tópico. Extraia o que já foi respondido para não perguntar novamente na Fase 2.
Se estiver dentro de um repositório (obrigatório)
Escaneie o código para entender o contexto real do que o usuário está propondo. Você não pode escrever um RFC fundamentado sem conhecer o sistema que ele altera.
- Detecte convenção da casa. Pesquise por uma configuração RFC existente:
rfcs/,docs/rfcs/,docs/rfc/,**/*rfc*template*,adr/,docs/adr/,.github/*TEMPLATE*. Se existir um arquivo de template, adote seus cabeçalhos de seção e seu diretório em vez do template embutido e informe o usuário em uma linha:Usando seu template em docs/rfcs/template.md; substituindo minha estrutura padrão.Sem pergunta bloqueante. - Escaneie o subsistema relevante. Leia a árvore de diretórios (nomes), LEIA os documentos de arquitetura/README e os módulos reais que a proposta toca. Entenda: como a área afetada funciona hoje, os padrões e abstrações já em uso, as restrições reais (tipos, interfaces, fluxo de dados). Isso fundamenta a seção de Contexto e, crucialmente, permite que as opções de código da Fase 3 correspondam às convenções existentes.
- Anote referências de arquivos que você citará no RFC (
caminho:linha).
Se estiver fora de um repositório: pule o escaneamento e a detecção; a entrevista gera um documento independente usando o template embutido.
Fase 2: Entrevistar
Conduza em direção às dimensões abaixo. Para cada uma, primeiro verifique se já foi respondida pela entrada ou pelo escaneamento do código; se sim, confirme sua inferência (Eu li que X funciona via Y - correto?) em vez de perguntar do zero. Faça perguntas genuinamente abertas uma de cada vez. Quando o escaneamento do código fornecer uma resposta candidata (especialmente alternativas e riscos), proponha-a para que o usuário reaja em vez de gerá-la do zero.
Dimensões centrais (sempre)
| # | Dimensão | Alimenta seção |
|---|---|---|
| 1 | Problema - o que está quebrado/faltando, a dor hoje | Contexto / Motivação |
| 2 | Por que agora - gatilho, custo da inação | Motivação |
| 3 | Objetivos - como é o sucesso, mensuráveis quando possível | Objetivos |
| 4 | Não objetivos - explicitamente fora do escopo | Não Objetivos |
| 5 | Abordagem proposta - tratada como opções de design na Fase 3 | Design Proposto |
| 6 | Alternativas - produzidas de graça a partir das opções rejeitadas na Fase 3 | Alternativas Consideradas |
| 7 | Riscos / compensações - o que pode dar errado, o que custa | Riscos e Compensações |
| 8 | Implantação - migração, fases, compatibilidade reversa, teste | Plano de Implantação |
| 9 | Aprovadores / partes interessadas - quem decide, quem é afetado | Aprovadores |
| 10 | Perguntas em aberto - desconhecidos conhecidos | Perguntas em Aberto |
Dimensões condicionais (pergunte apenas quando justificado)
- Segurança / privacidade - quando a proposta toca autenticação, segredos, PII ou um limite de confiança.
- Desempenho / custo - quando toca um caminho crítico, adiciona um serviço ou tem um orçamento de recursos.
- Observabilidade - quando introduz um novo serviço ou um modo de falha que merece alerta.
Julgue a relevância a partir do escaneamento do código e da superfície da proposta. Não interrogue o usuário sobre isso por reflexo.
Verificação de qualidade dos objetivos
Pressione contra objetivos vagos durante a entrevista. "Tornar mais rápido" não é um objetivo; "p99 abaixo de 200ms para o endpoint de lista de locatários" é. Peça a versão mensurável.
Fase 3: Opções de design (o núcleo do skill)
É aqui que o RFC ganha seu valor. Apresente 2 a 3 abordagens distintas e concretas para o design, cada uma mostrada como um trecho de API / código trabalhado fundamentado nas convenções do código da Fase 1. Não descrições em prosa: código real mostrando como seria a API final, assinaturas de função, esquema ou configuração.
Para cada opção forneça:
- Um nome curto e resumo de uma linha.
- Um trecho de código da API / uso / assinatura resultante (aquilo que um engenheiro futuro realmente escreveria contra).
- Suas compensações: no que é bom, o que custa, o que descarta.
Apresente-as lado a lado e peça ao usuário para escolher ou refinar. Itere se ele quiser uma nova opção ou uma combinação.
A opção escolhida se torna o Design Proposto (com seu código). As opções que ele rejeita se tornam a seção Alternativas Consideradas, cada uma mantendo seu trecho de código e o motivo pelo qual perdeu. É por isso que as alternativas nestes RFCs são reais: foram candidatos genuínos com código funcional, não espantalhos retrospectivos.
Se apenas uma abordagem viável existir genuinamente, diga isso e apresente-a sozinha com uma nota explícita de que alternativas foram consideradas e por que nenhuma era viável. Não fabrique opções falsas para preencher a tabela.
Fase 4: Montar
Escreva o RFC completo no arquivo de saída (caminho resolvido na Fase 7, confirmado no início). Mantenha-o enxuto (veja o princípio "Imparcialmente conciso"): listas em vez de parágrafos, texto mais curto que permaneça claro, sem enchimento. O trecho de código faz a explicação; a prosa apenas o emoldura. Use o template da casa do repositório se um foi detectado na Fase 1; caso contrário, use a estrutura embutida abaixo.
Inclua um diagrama Mermaid quando o design tiver estrutura que vale a pena ver (arquitetura, sequência, fluxo de dados, máquina de estados). Um diagrama respondendo a uma pergunta. Pule para alterações puramente no nível da API sem fluxo interessante.
Template embutido
# RFC: <título>
## Resumo
<TL;DR que um leitor obtém em 30 segundos: o que isso propõe e por quê.>
## Contexto e Motivação
<O problema, o estado atual (com referências a arquivos se estiver em um repositório) e por que agora.
O que acontece se não fizermos nada.>
## Objetivos
<Mensuráveis quando possível. Listas.>
## Não Objetivos
<Explicitamente fora do escopo, para que os revisores não reabram discussão.>
## Design Proposto
<A abordagem escolhida. Comece com o código / exemplo de API trabalhado da Fase 3.
Depois explique como funciona, fundamentado em módulos reais. Diagrama se justificado.>
## Alternativas Consideradas
<Cada opção rejeitada da Fase 3, com seu trecho de código e por que perdeu.>
## Riscos e Compensações
<Cada risco emparelhado com uma mitigação, ou um "aceito, porque ..." explícito.>
## Plano de Implantação
<Migração, fases, compatibilidade reversa, estratégia de teste.>
## Perguntas em Aberto
<Desconhecidos conhecidos. Melhor nomeá-los do que fingir que estão resolvidos.>
## Aprovadores
<Quem assina, quem é afetado. Nomes, para que fique claro onde está a decisão.>
Inclua seções condicionais (Segurança, Desempenho, Observabilidade) apenas quando foram relevantes na Fase 2.
Metadados opcionais (apenas se o usuário solicitou)
Por padrão, não adicione frontmatter ou número. Se o usuário pedir, anexe:
---
status: Rascunho # Rascunho | Em Revisão | Aceito | Rejeitado | Substituído
autor: <nome>
data: <AAAA-MM-DD>
aprovadores: [ ]
---
Numeração automática (NNNN-slug.md) apenas se o diretório de destino já contiver arquivos NNNN-*.md; escaneie o maior e incremente. Caso contrário, use um nome de arquivo slug simples.
Fase 5: Autocrítica (obrigatória, antes de o usuário ver o rascunho)
Execute o RFC montado contra esta rubrica e corrija o que puder. Depois relate o que você pegou e o que ainda precisa do usuário.
- Objetivos mensuráveis? Aspirações vagas apertadas para algo testável.
- Alternativas reais? Pelo menos uma alternativa genuína com seu próprio código, não um espantalho. (A Fase 3 deve garantir isso.)
- Cada risco mitigado? Cada risco tem uma mitigação ou um "aceito, porque ..." explícito.
- Design concreto? O Design Proposto contém um trecho de API/código real, não apenas prosa.
- Afirmações fundamentadas? Cada afirmação sobre o código tem uma referência de arquivo por trás. Nenhuma afirmação sem suporte.
Relate brevemente, por exemplo: Autocrítica: apertei 2 objetivos vagos; sinalizei um risco (tempo de inatividade de migração de dados) sem mitigação ainda - preciso de sua decisão. Todo o resto fundamentado.
Fase 6: Loop de revisão
RFC escrito em <caminho>. Abra em um visualizador de markdown para o diagrama renderizado. Quer alguma alteração?
Aplique alterações editando o arquivo. Faça um loop até a aprovação.
Fase 7: Saída
Resolução do caminho (confirme no início, no começo da Fase 4)
- Repositório com diretório RFC detectado:
<esse_diretório>/<NNNN->slug.md. - Repositório sem um:
docs/rfcs/<slug>.md. - Fora de um repositório: diretório atual, ou o scratchpad se o diretório atual não for gravável.
Pergunte uma vez no início: Vou escrever o RFC em docs/rfcs/<slug>.md. Local diferente?
Ao concluir
- Abra automaticamente para o usuário em uma nova janela do VS Code:
code --new-window "<caminho-absoluto>". - Imprima um breve resumo no terminal (título + uma linha + caminho). NÃO despeje o documento completo no terminal.
Tratamento de Erros
- Nenhuma entrada / tópico vago - tudo bem, a entrevista lida com isso. Comece a Fase 2.
- PR/issue/ticket referenciado ilegível - informe o usuário, prossiga com o que ele descrever.
- Repositório grande demais para escanear completamente - limite o escaneamento ao subsistema que a proposta toca; anote o que você pulou.
- Usuário não consegue responder a uma dimensão - registre-a como uma Pergunta em Aberto em vez de inventar uma resposta.