Agent Md Refactor

Agent MD Refactor

Refatore arquivos de instruções de agentes bloated (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) para seguir princípios de divulgação progressiva - mantendo essenciais na raiz e organizando o resto em arquivos categorizados e vinculados.

Triggers

Use essa skill quando:

• "refatore meu AGENTS.md" / "refatore meu CLAUDE.md"
• "divida minhas instruções de agente"
• "organize meu arquivo CLAUDE.md"
• "meu AGENTS.md é muito longo"
• "divulgação progressiva para minhas instruções"
• "limpe minha configuração de agente"

Referência Rápida

Processo

Fase 1: Encontrar Contradições

Identifique instruções que conflitem umas com as outras.

Procure por:

• Guias de estilo contraditórios (ex: "use ponto-e-vírgula" vs "sem ponto-e-vírgula")
• Instruções de workflow conflitantes
• Preferências de ferramentas incompatíveis
• Padrões mutuamente exclusivos

Para cada contradição encontrada:

## Contradição Encontrada

**Instrução A:** [citação]
**Instrução B:** [citação]

**Pergunta:** Qual deve ter precedência, ou ambas devem ser condicionais?

Peça ao usuário para resolver antes de prosseguir.

Fase 2: Identificar os Essenciais

Extraia APENAS o que pertence ao arquivo raiz do agente. A raiz deve ser mínima - informações que se aplicam a todas as tarefas.

Conteúdo essencial (manter na raiz):

NÃO essencial (mover para arquivos vinculados):

• Convenções específicas de linguagem
• Diretrizes de teste
• Detalhes de estilo de código
• Padrões de framework
• Padrões de documentação
• Detalhes de workflow Git

Fase 3: Agrupar o Resto

Organize instruções restantes em categorias lógicas.

Categorias comuns:

Regras de agrupamento:

1. Cada arquivo deve ser auto-contido para seu tópico
2. Aim para 3-8 arquivos (nem muito granular, nem muito amplo)
3. Nomeie arquivos claramente: {topico}.md
4. Inclua apenas instruções acionáveis

Fase 4: Criar a Estrutura de Arquivos

Estrutura de output:

project-root/
├── CLAUDE.md (ou AGENTS.md)      # Raiz mínima com links
└── .claude/                       # Ou docs/agent-instructions/
    ├── typescript.md
    ├── testing.md
    ├── code-style.md
    ├── git-workflow.md
    └── architecture.md

Template do arquivo raiz:

# Nome do Projeto

Descrição de uma frase do projeto.

## Referência Rápida

- **Gerenciador de Pacotes:** pnpm
- **Build:** `pnpm build`
- **Teste:** `pnpm test`
- **Typecheck:** `pnpm typecheck`

## Instruções Detalhadas

Para diretrizes específicas, consulte:
- [Convenções TypeScript](.claude/typescript.md)
- [Diretrizes de Teste](.claude/testing.md)
- [Estilo de Código](.claude/code-style.md)
- [Workflow Git](.claude/git-workflow.md)
- [Padrões de Arquitetura](.claude/architecture.md)

Template de cada arquivo vinculado:

# Diretrizes de {Tópico}

## Visão Geral
Contexto breve de quando estas diretrizes se aplicam.

## Regras

### Categoria de Regra 1
- Instrução específica e acionável
- Outra instrução específica

### Categoria de Regra 2
- Instrução específica e acionável

## Exemplos

### Bom
\`\`\`typescript
// Exemplo de padrão correto
\`\`\`

### Evitar
\`\`\`typescript
// Exemplo do que não fazer
\`\`\`

Fase 5: Sinalizar para Exclusão

Identifique instruções que devem ser removidas completamente.

Exclua se:

Formato de output:

## Sinalizado para Exclusão

| Instrução | Razão |
|-----------|-------|
| "Escreva código limpo e mantível" | Muito vago para ser acionável |
| "Use TypeScript" | Redundante - projeto já é TS |
| "Não cometa secrets" | Agent já sabe disso |
| "Siga best practices" | Sem sentido sem especificidades |

Checklist de Execução

[ ] Fase 1: Todas as contradições identificadas e resolvidas
[ ] Fase 2: Arquivo raiz contém APENAS essenciais
[ ] Fase 3: Todas as instruções restantes categorizadas
[ ] Fase 4: Estrutura de arquivo criada com links apropriados
[ ] Fase 5: Instruções redundantes/vagas removidas
[ ] Verificar: Cada arquivo vinculado é auto-contido
[ ] Verificar: Arquivo raiz tem menos de 50 linhas
[ ] Verificar: Todos os links funcionam corretamente

Anti-Padrões

Exemplos

Antes (Raiz Bloated)

# CLAUDE.md

Este é um projeto React.

## Code Style
- Use 2 espaços
- Use ponto-e-vírgula
- Prefira const sobre let
- Use arrow functions
... (200 linhas mais)

## Testing
- Use Jest
- Cobertura > 80%
... (100 linhas mais)

## TypeScript
- Habilite strict mode
... (150 linhas mais)

Depois (Divulgação Progressiva)

# CLAUDE.md

Dashboard React para visualização de análise em tempo real.

## Comandos
- `pnpm dev` - Inicie servidor de desenvolvimento
- `pnpm test` - Execute testes com cobertura
- `pnpm build` - Build de produção

## Diretrizes
- [Estilo de Código](.claude/code-style.md)
- [Teste](.claude/testing.md)
- [TypeScript](.claude/typescript.md)

Verificação

Após refatorar, verifique:

1. Arquivo raiz é mínimo - Menos de 50 linhas, apenas info universal
2. Links funcionam - Todos os arquivos referenciados existem
3. Sem contradições - Instruções são consistentes
4. Conteúdo acionável - Cada instrução é específica
5. Cobertura completa - Nenhuma instrução foi perdida (a menos que sinalizada para exclusão)
6. Arquivos auto-contidos - Cada arquivo vinculado é independente