From imersao
Use when working in monorepos with multiple apps/packages, when CLAUDE.md or AGENTS.md files need validation, when detecting broken links, redundant or conflicting instructions, vague instructions, incomplete coverage, or inconsistent formatting - validates structure, links, and instruction quality with interactive correction mode
How this skill is triggered — by the user, by Claude, or both
Slash command
/imersao:agents-maintenanceThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Mantém consistência entre arquivos de instrução (CLAUDE.md, AGENTS.md, READMEs) em monorepos. Valida estrutura, links bidirecionais, timestamps e detecta redundâncias/conflitos.
Mantém consistência entre arquivos de instrução (CLAUDE.md, AGENTS.md, READMEs) em monorepos. Valida estrutura, links bidirecionais, timestamps e detecta redundâncias/conflitos.
Princípio central: Cada nível do monorepo tem um par CLAUDE.md → [[AGENTS.md]], formando hierarquia navegável.
Use quando:
Não use quando:
raiz/
├── CLAUDE.md ─────→ [[AGENTS.md]]
├── AGENTS.md (índice geral de agentes)
│
├── apps/
│ └── app1/
│ ├── CLAUDE.md ─→ [[AGENTS.md]]
│ ├── AGENTS.md ─→ [[../../AGENTS.md]] (link pai)
│ └── README.md
│
└── packages/
└── shared/
├── CLAUDE.md ─→ [[AGENTS.md]]
├── AGENTS.md ─→ [[../../AGENTS.md]] (link pai)
└── README.md
Regras:
[[AGENTS.md]]Execute na ordem:
1.1 Encontrar arquivos existentes:
find . -name "CLAUDE.md" -o -name "AGENTS.md" -o -name "README.md"
1.2 Identificar áreas que DEVERIAM ter AGENTS.md:
| Indicador | Por que precisa de AGENTS.md |
|---|---|
Tem package.json próprio | App/package independente |
Tem tsconfig.json próprio | Configuração específica |
Tem pasta src/ ou lib/ | Código fonte significativo |
Tem pasta tests/ ou __tests__/ | Lógica testável |
Tem Dockerfile | Deploy independente |
Tem README.md sem AGENTS.md | Documentado mas sem instruções |
Diretório em apps/, packages/, services/, modules/ | Convenção de monorepo |
Mais de 10 arquivos .ts/.js | Volume de código significativo |
Comando para descobrir candidatos:
# Diretórios com package.json mas sem AGENTS.md
find . -name "package.json" -exec dirname {} \; | while read dir; do
[ ! -f "$dir/AGENTS.md" ] && echo "CANDIDATO: $dir"
done
# Diretórios em apps/ ou packages/ sem AGENTS.md
find ./apps ./packages -mindepth 1 -maxdepth 1 -type d | while read dir; do
[ ! -f "$dir/AGENTS.md" ] && echo "CANDIDATO: $dir"
done
Prioridade de criação:
🔴 Alta: apps/* e packages/* sem AGENTS.md
🟡 Média: Diretórios com package.json próprio
🟢 Baixa: Diretórios com apenas README.md
| Verificação | Ação se falhar |
|---|---|
| AGENTS.md existe mas CLAUDE.md não | Criar CLAUDE.md com template |
CLAUDE.md não contém [[AGENTS.md]] | Adicionar link |
| Verificação | Ação se falhar |
|---|---|
Link [[arquivo]] não existe | Criar arquivo ou remover link |
| Arquivo linkado não linka de volta | Adicionar link bidirecional |
| AGENTS.md filho não linka para pai | Adicionar [[../AGENTS.md]] |
# Comparar datas de modificação
stat -f "%m %N" CLAUDE.md AGENTS.md | sort -n
Se CLAUDE.md mais recente que AGENTS.md relacionado → possível desatualização.
Redundância (mesma instrução em múltiplos níveis):
# AGENTS.md raiz
Use TypeScript para todo código.
# apps/web/AGENTS.md
Use TypeScript para todo código. ← REDUNDANTE
→ Manter apenas no pai (herança implícita)
Conflito (instrução contradiz pai):
# AGENTS.md raiz
Use Jest para testes.
# apps/web/AGENTS.md
Use Vitest para testes. ← CONFLITO
→ Se intencional, marcar com @override:
@override teste: Use Vitest (velocidade para Vite apps)
Avaliar cada instrução nos 4 critérios:
| Problema | Exemplo Ruim | Exemplo Bom |
|---|---|---|
| Vago | "Escreva bom código" | "Use TypeScript strict mode" |
| Ambíguo | "Teste adequadamente" | "Cobertura mínima 80% em use cases" |
| Subjetivo | "Código limpo" | "Funções com máximo 20 linhas" |
Red flags: "adequado", "bom", "limpo", "correto", "melhor", sem métricas.
AGENTS.md deve cobrir (quando aplicável):
| Área | Obrigatório | Exemplos |
|---|---|---|
| Stack/Linguagem | Sim | TypeScript, Node 20, pnpm |
| Padrões de código | Sim | ESLint config, Prettier |
| Testes | Sim | Framework, cobertura mínima |
| Convenções de naming | Recomendado | camelCase, kebab-case para arquivos |
| Estrutura de pastas | Recomendado | Onde criar novos arquivos |
| Commits | Opcional | Conventional commits |
| CI/CD | Opcional | Pipeline obrigatória |
Verificar: Falta alguma área essencial? Há seções vazias ou com {{placeholder}}?
Instrução acionável = agente sabe EXATAMENTE o que fazer.
| Não Acionável | Acionável |
|---|---|
| "Siga boas práticas de segurança" | "Sanitize inputs com zod antes de usar" |
| "Documente o código" | "JSDoc em funções públicas exportadas" |
| "Use padrões do projeto" | "Siga estrutura em src/modules/exemplo/" |
| "Mantenha consistência" | "Use o hook useApiQuery para fetching" |
Teste: Se der a instrução para outro dev sem contexto, ele consegue executar?
Todos os AGENTS.md devem seguir mesmo padrão:
| Elemento | Padrão Esperado |
|---|---|
| Seções | Mesmo nome e ordem em todos |
| Instruções | Bullets ou tabelas (não misturar) |
| Exemplos de código | Mesmo estilo de formatação |
| Links | Sempre [[relativo]], nunca absoluto |
| Data | Formato ISO: YYYY-MM-DD |
Verificar: Compare AGENTS.md de diferentes apps - estão consistentes?
Para cada problema encontrado, perguntar:
Candidato a AGENTS.md (área sem instruções):
.agentsignore)Links quebrados:
Pares incompletos:
Redundância:
Conflito:
@overrideInstrução vaga/não-acionável:
Área faltante (completude):
Inconsistência de formato:
Sempre mostrar diff antes de salvar.
# {{nome}}
> Entry point. Leia primeiro.
## Instruções do Agente
→ [[AGENTS.md]]
## Contexto
- **O quê**: {{descrição}}
- **Stack**: {{tecnologias}}
- **Pai**: [[../../CLAUDE.md]]
## Links
- [[README.md]] - Documentação técnica
- [[../../AGENTS.md]] - Índice geral
---
*Atualizado: {{data}}*
# Agentes do Projeto
> Índice de todos os agentes/apps.
## Hierarquia
| Agente | Caminho | Descrição |
|--------|---------|-----------|
| {{nome}} | [[apps/x/AGENTS.md]] | {{desc}} |
## Instruções Globais
{{instruções para TODOS os agentes}}
## Herança
Instruções aqui se aplicam a filhos.
Filhos podem sobrescrever com `@override: razão`.
---
*Atualizado: {{data}}*
# Agente: {{nome}}
> Instruções específicas.
## Herança
- **Pai**: [[../../AGENTS.md]]
## Instruções Específicas
{{apenas o que é diferente do pai}}
## Sobrescritas
@override {{item}}: {{valor}} ({{razão}})
## Links
- [[CLAUDE.md]]
- [[README.md]]
---
*Atualizado: {{data}}*
| Comando | Descrição |
|---|---|
| "Validar agentes" | Checklist completo + modo interativo |
| "Criar estrutura de agentes" | Cria par CLAUDE.md + AGENTS.md |
| "Adicionar agente em X" | Cria estrutura + atualiza índice |
| "Relatório de agentes" | Lista hierarquia sem corrigir |
| "Sync timestamps" | Atualiza datas após revisão |
| Erro | Correção |
|---|---|
| Esquecer link bidirecional | Sempre verificar: A linka B? B linka A? |
| Duplicar instrução do pai | Usar herança implícita |
Conflito sem @override | Marcar sobrescritas intencionais |
| CLAUDE.md sem link para AGENTS.md | Primeira linha após título: → [[AGENTS.md]] |
| Não atualizar índice raiz | Após criar novo agente, adicionar na tabela |
| Erro | Correção |
|---|---|
| Instrução vaga ("bom código") | Adicionar métrica: "max 20 linhas por função" |
| Sem exemplos concretos | Adicionar: "como em src/modules/user/" |
| Área obrigatória faltando | Adicionar seção mesmo que herde do pai |
| Misturar formatos (bullets + tabelas) | Escolher um e padronizar |
| Usar termos subjetivos | Substituir por critérios objetivos mensuráveis |
Placeholder {{}} não preenchido | Preencher ou remover seção |
| Instrução não-testável | Reformular para ter critério de sucesso claro |
Para ignorar diretórios que não precisam de AGENTS.md:
# .agentsignore na raiz do projeto
node_modules/
dist/
build/
.git/
coverage/
scripts/ # Scripts de build, não precisam de instruções
tools/internal/ # Ferramentas internas simples
Quando ignorar:
Quando NÃO ignorar:
[[memory-bank/]][[link]] compatívelnpx claudepluginhub parisgroup-ai/imersao-ia-setup --plugin imersaoProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.