Skip to content

artubss/SKILLS-CLAUDE-CODE / skills/skills/development/agent-md-refactor

agent-md-refactor

Verified

Refatore arquivos de instruções de agentes AGENTS.md, CLAUDE.md ou similares para seguir princípios de divulgação progressiva. Divide arquivos monolíticos em documentação organizada e vinculada.

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

FaseAçãoOutput
1. AnalisarEncontrar contradiçõesLista de conflitos para resolver
2. ExtrairIdentificar essenciaisInstruções centrais para arquivo raiz
3. CategorizarAgrupar instruções restantesCategorias lógicas
4. EstruturarCriar hierarquia de arquivosRaiz + arquivos vinculados
5. PodarSinalizar para exclusãoInstruções redundantes/vagas

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):

CategoriaExemplo
Descrição do projetoUma frase: "Um dashboard React para análise"
Gerenciador de pacotesApenas se não for npm (ex: "Usa pnpm")
Comandos não-padrãoComandos customizados build/test/typecheck
Overrides críticosCoisas que DEVEM sobrescrever padrões
Regras universaisSe aplica a 100% das tarefas

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:

CategoriaConteúdo
typescript.mdConvenções TS, padrões de tipo, regras de modo strict
testing.mdFrameworks de teste, cobertura, padrões de mock
code-style.mdFormatação, naming, comentários, estrutura
git-workflow.mdCommits, branches, PRs, reviews
architecture.mdPadrões, estrutura de pastas, dependências
api-design.mdConvenções REST/GraphQL, tratamento de erros
security.mdPadrões de auth, validação de entrada, secrets
performance.mdRegras de otimização, caching, lazy loading

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:

CritérioExemploPor Quê Excluir
Redundante"Use TypeScript" (em projeto .ts)Agent já sabe
Muito vago"Escreva código limpo"Não é acionável
Óbvio demais"Não introduza bugs"Desperdiça contexto
Comportamento padrão"Use nomes descritivos de variáveis"Prática padrão
DesatualizadoReferencia APIs obsoletasNão se aplica mais

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

EvitePor QuêAo Invés
Manter tudo na raizBloated, difícil de manterDivida em arquivos vinculados
Muitas categoriasFragmentaçãoConsolide tópicos relacionados
Instruções vagasDesperdiça tokens, sem valorSeja específico ou exclua
Duplicar padrõesAgent já sabeSobrescreva apenas quando necessário
Deep nestingDifícil de navegarEstrutura flat com links

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

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 318kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 318kUpdated Claude CodeCodexVerifiedInstall