/acreadiness-generate-instructions — criar instruções para agentes de IA

Use esta habilidade sempre que o usuário quiser criar, recriar ou atualizar suas instruções personalizadas para agentes de codificação de IA (Copilot, Claude, etc.). Esta é a etapa Gerar do loop Medir → Gerar → Manter do AgentRC e a ação de maior alavancagem para o pilar Ferramentas de IA.

Opções de saída

O VS Code reconhece vários tipos de arquivos de instrução — o AgentRC gera os mais comuns:

Estratégias

• flat (padrão) — um único .github/copilot-instructions.md no caminho escolhido. Simples, fácil de revisar.
• nested — hub em .github/copilot-instructions.md + arquivos de detalhes por tópico em .github/instructions/<topic>.instructions.md, cada um com um glob applyTo para que o VS Code carregue o tópico apenas quando for relevante. Melhor para repositórios grandes ou com múltiplas pilhas.

Por que .github/instructions/ e não .agents/? O layout aninhado padrão do AgentRC escreve em .agents/, que é o local correto para repositórios agnósticos de agente (Copilot + Claude + Cursor lendo AGENTS.md). Para o VS Code Copilot especificamente, o local nativo é .github/instructions/ com frontmatter applyTo — é isso que o Copilot descobre automaticamente. Esta habilidade reescreve a saída aninhada do AgentRC para o local nativo do VS Code sempre que a saída principal é .github/copilot-instructions.md. Se você escolheu --output AGENTS.md em vez disso, o aninhado mantém o layout padrão .agents/ do AgentRC.

Para monorepos, gere instruções com escopo de área usando --areas, --area <name> ou --areas-only. As áreas são definidas em agentrc.config.json. A saída por área é escrita como arquivos .instructions.md do VS Code com um glob applyTo (veja abaixo).

Arquivos de tópico vs. área .instructions.md

Ambos acabam em .github/instructions/, mas respondem a perguntas diferentes:

Você pode ter ambos ao mesmo tempo: um conjunto aninhado de arquivos de tópico mais arquivos por área para um monorepo.

Arquivos por área com applyTo

Quando o usuário opta por áreas, emita um arquivo .instructions.md nativo do VS Code por área em .github/instructions/<area>.instructions.md. Cada arquivo DEVE começar com frontmatter declarando o glob ao qual as regras se aplicam:

---
applyTo: "apps/frontend/**"
---

# Frontend area instructions

…AgentRC-generated content for this area…

Fluxo de trabalho:

1. Leia agentrc.config.json para descobrir as áreas declaradas e seus paths / globs. Se paths estiver faltando, pergunte ao usuário o glob (por exemplo, src/api/**).
2. Execute agentrc instructions --areas (ou --area <name>) para produzir o conteúdo do corpo por área.
3. Envolva o conteúdo de cada área em .github/instructions/<area>.instructions.md com o frontmatter applyTo retirado do paths da área. Se o usuário passou --apply-to <glob> em uma chamada de área única, use esse glob literalmente.
4. Deixe o arquivo principal em paz — o .github/copilot-instructions.md raiz permanece como as instruções sempre ativas; os arquivos .instructions.md só entram em vigor para caminhos correspondentes.

Nomenclatura: nome da área em minúsculas, estilo kebab-case. Exemplos: .github/instructions/frontend.instructions.md, .github/instructions/api.instructions.md, .github/instructions/infra.instructions.md.

Etapas

1. Escolha o arquivo de destino. Padrão para .github/copilot-instructions.md. Mude para AGENTS.md apenas se o usuário mencionar suporte a múltiplos agentes / Claude / Cursor.
2. Sempre pergunte qual estratégia usar — flat ou nested — a menos que o usuário já tenha especificado uma em sua mensagem ou via --strategy. Apresente a troca brevemente:
   • Plana (padrão) — um único .github/copilot-instructions.md. Simples, fácil de revisar em um único PR. Melhor para repositórios pequenos/médios com uma única pilha.

…