Instructree

Visão Geral

Use o Instructree para determinar quais arquivos de instrução existem, quais podem se aplicar a um alvo e se seus metadados, links ou importações recursivas estão malformados. Ele audita formatos comuns de instruções de agente de código localmente, sem chamar um modelo ou fazer upload do conteúdo do repositório.

Quando Usar Esta Habilidade

• Use antes de alterar código em um repositório com AGENTS.md, CLAUDE.md, instruções do Copilot, habilidades de agente, agentes personalizados, regras do Cursor ou regras do Windsurf.
• Use quando o usuário perguntar quais instruções podem se aplicar a um arquivo alvo.
• Use ao auditar importações recursivas do Copilot CLI @path ou ao exportar diagnósticos de instrução para CI.

Como Funciona

Etapa 1: Escolha o comando local

Trabalhe a partir da raiz do repositório. Prefira um comando instructree já instalado ou o binário local do pacote baixado.

Se nenhum estiver disponível, explique que o próximo comando baixa o código executável do pacote e peça aprovação antes de executar a versão fixada:

npx github:kotobuki09/instructree#364dddc66badac13a284b79f0dc71f2b4362f6de scan .

Não adicione --yes a menos que o usuário tenha autorizado downloads de pacotes não interativos.

Etapa 2: Execute a auditoria mais restrita

• instructree scan . --json lista os arquivos suportados e emite diagnósticos estáveis.
• instructree explain <file> --root . mostra as instruções que podem se aplicar a um alvo.
• instructree explain <file> --root . --effective inclui importações recursivas do Copilot CLI.
• instructree imports . --json audita o grafo recursivo de @path.
• instructree scan . --sarif emite SARIF 2.1.0 para integrações de varredura de código.
• Adicione --strict apenas quando avisos deverem falhar na verificação.

Etapa 3: Interprete o resultado

Relate caminhos de arquivo, números de linha, códigos de diagnóstico e o status de saída do comando. Separe erros de esquema ou caminho de avisos. Descreva conflitos always/never como possíveis conflitos que exigem revisão humana, não como prova do comportamento do agente.

Exemplos

Auditar um repositório

instructree scan . --json

Explicar um alvo com importações recursivas

instructree explain src/api/client.ts --root . --effective

Gerar um relatório de varredura de código

instructree scan . --sarif > instructree.sarif

Melhores Práticas

• Prefira um comando local e já revisado em vez de baixar o código do pacote.
• Use explain para um único alvo em vez de escanear um escopo maior do que o necessário.
• Execute o mesmo comando novamente após uma correção autorizada de instrução e relate os diagnósticos antes e depois.
• Mantenha os avisos separados dos erros e declare claramente quando uma descoberta é heurística.

Limitações

• O Instructree é uma análise estática; ele não estabelece as regras de precedência exatas ou o comportamento em tempo de execução de cada cliente de agente.
• A descoberta de clientes e o comportamento de importação podem mudar, portanto, explain relata o que pode se aplicar em vez de prever o que um modelo seguirá.
• A auditoria não prova que o conteúdo da instrução é correto, seguro ou eficaz.
• Não edite arquivos de instrução, a menos que o usuário tenha solicitado alterações.

Notas de Segurança e Proteção

• As varreduras são somente leitura e locais; elas não chamam um modelo nem fazem upload do conteúdo do repositório.
• Trate qualquer fallback npx como código de terceiros executável: mantenha-o fixado, revise a origem e obtenha aprovação antes de baixar.
• Não execute o conteúdo da instrução importada. O Instructree segue referências suportadas apenas como dados.