deepinit

Habilidade de Inicialização Profunda (Deep Init Skill)

Cria documentação AGENTS.md abrangente e hierárquica em toda a base de código.

Conceito Central

Os arquivos AGENTS.md servem como documentação legível por IA que ajuda os agentes a entender:

• O que cada diretório contém
• Como os componentes se relacionam entre si
• Instruções especiais para trabalhar naquela área
• Dependências e relacionamentos

Sistema de Marcação Hierárquica

Todo AGENTS.md (exceto o raiz) inclui uma tag de referência ao pai:

<!-- Parent: ../AGENTS.md -->

Isso cria uma hierarquia navegável:

/AGENTS.md                          ← Raiz (sem tag de pai)
├── src/AGENTS.md                   ← <!-- Parent: ../AGENTS.md -->
│   ├── src/components/AGENTS.md    ← <!-- Parent: ../AGENTS.md -->
│   └── src/utils/AGENTS.md         ← <!-- Parent: ../AGENTS.md -->
└── docs/AGENTS.md                  ← <!-- Parent: ../AGENTS.md -->

Modelo de AGENTS.md

<!-- Parent: {relative_path_to_parent}/AGENTS.md -->
<!-- Generated: {timestamp} | Updated: {timestamp} -->

# {Nome do Diretório}

## Propósito
{Parágrafo descrevendo o que este diretório contém e seu papel}

## Arquivos Principais
{Liste cada arquivo significativo com uma descrição de uma linha}

| Arquivo | Descrição |
|---------|-----------|
| `file.ts` | Breve descrição do propósito |

## Subdiretórios
{Liste cada subdiretório com breve propósito}

| Diretório | Propósito |
|-----------|-----------|
| `subdir/` | O que contém (veja `subdir/AGENTS.md`) |

## Para Agentes de IA

### Trabalhando Neste Diretório
{Instruções especiais para agentes de IA modificando arquivos aqui}

### Requisitos de Teste
{Como testar mudanças neste diretório}

### Padrões Comuns
{Padrões de código ou convenções usados aqui}

## Dependências

### Internas
{Referências a outras partes da base de código das quais depende}

### Externas
{Principais pacotes/bibliotecas externas usados}

<!-- MANUAL: Quaisquer notas adicionadas manualmente abaixo desta linha são preservadas na regeneração -->

Fluxo de Execução

Passo 1: Mapear Estrutura de Diretórios

Task(subagent_type="explore", model="haiku",
  prompt="Liste todos os diretórios recursivamente. Exclua: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")

Passo 2: Criar Plano de Trabalho

Gere itens de tarefa para cada diretório, organizados por nível de profundidade:

Nível 0: / (raiz)
Nível 1: /src, /docs, /tests
Nível 2: /src/components, /src/utils, /docs/api
...

Passo 3: Gerar Nível por Nível

IMPORTANTE: Gere níveis pai antes dos níveis filho para garantir que as referências de pai sejam válidas.

Para cada diretório:

1. Leia todos os arquivos no diretório
2. Analise propósito e relacionamentos
3. Gere o conteúdo do AGENTS.md
4. Escreva o arquivo com a referência de pai correta

Passo 4: Comparar e Atualizar (se existir)

Quando o AGENTS.md já existe:

1. Leia o conteúdo existente
2. Identifique seções:
   • Seções geradas automaticamente (podem ser atualizadas)
   • Seções manuais (<!-- MANUAL --> preservadas)
3. Compare:
   • Novos arquivos adicionados?
   • Arquivos removidos?
   • Estrutura alterada?
4. Mescle:
   • Atualize conteúdo gerado automaticamente
   • Preserve anotações manuais
   • Atualize timestamp

Passo 5: Validar Hierarquia

Após a geração, execute verificações de validação:

Verificação	Como Verificar	Ação Corretiva
Referências de pai resolvem	Leia cada AGENTS.md, verifique se o caminho <!-- Parent: --> existe	Corrija o caminho ou remova o órfão
Nenhum AGENTS.md órfão	Compare locais de AGENTS.md com estrutura de diretórios	Exclua arquivos órfãos
Completude	Liste todos os diretórios, verifique se existe AGENTS.md	Gere arquivos ausentes
Timestamps atuais	Verifique datas de <!-- Generated: -->	Regere arquivos desatualizados

Padrão de script de validação:

# Encontre todos os arquivos AGENTS.md
find . -name "AGENTS.md" -type f

# Verifique referências de pai
grep -r "<!-- Parent:" --include="AGENTS.md" .

Delegação Inteligente

Tarefa	Agente
Mapeamento de diretórios	explore
Análise de arquivos	architect
Geração de conteúdo	writer
Escrita de AGENTS.md	writer

Tratamento de Diretórios Vazios

Ao encontrar diretórios vazios ou quase vazios:

Condição	Ação
Sem arquivos, sem subdiretórios	Pular - não criar AGENTS.md
Sem arquivos, com subdiretórios	Criar AGENTS.md mínimo apenas com listagem de subdiretórios
Apenas arquivos gerados (*.min.js, *.map)	Pular ou AGENTS.md mínimo
Apenas arquivos de configuração	Criar AGENTS.md descrevendo o propósito da configuração

Exemplo de AGENTS.md mínimo para contêineres de apenas diretórios:

<!-- Parent: ../AGENTS.md -->
# {Nome do Diretório}

## Propósito
Diretório contêiner para organizar módulos relacionados.

## Subdiretórios
| Diretório | Propósito |
|-----------|-----------|
| `subdir/` | Descrição (veja `subdir/AGENTS.md`) |

Regras de Paralelização

1. Diretórios do mesmo nível: Processar em paralelo
2. Níveis diferentes: Sequencial (pai primeiro)
3. Diretórios grandes: Gerar agente dedicado por diretório
4. Diretórios pequenos: Agrupar vários em um agente

Padrões de Qualidade

Deve Incluir

• Descrições precisas de arquivos
• Referências de pai corretas
• Links para subdiretórios
• Instruções para agentes de IA

Deve Evitar

• Texto genérico
• Nomes de arquivos incorretos
• Referências de pai quebradas
• Arquivos importantes faltando

Exemplo de Saída

AGENTS.md Raiz

<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# my-project

## Propósito
Uma aplicação web para gerenciar tarefas de usuários com funcionalidades de colaboração em tempo real.

## Arquivos Principais
| Arquivo | Descrição |
|---------|-----------|
| `package.json` | Dependências e scripts do projeto |
| `tsconfig.json` | Configuração do TypeScript |
| `.env.example` | Modelo de variáveis de ambiente |

## Subdiretórios
| Diretório | Propósito |
|-----------|-----------|
| `src/` | Código fonte da aplicação (veja `src/AGENTS.md`) |
| `docs/` | Documentação (veja `docs/AGENTS.md`) |
| `tests/` | Suítes de teste (veja `tests/AGENTS.md`) |

## Para Agentes de IA

### Trabalhando Neste Diretório
- Sempre instale dependências após modificar o manifesto do projeto
- Use modo estrito do TypeScript
- Siga as regras do ESLint

### Requisitos de Teste
- Execute testes antes de commitar
- Garanta >80% de cobertura

### Padrões Comuns
- Use exportações barrel (index.ts)
- Prefira componentes funcionais

## Dependências

### Externas
- React 18.x - Framework de UI
- TypeScript 5.x - Segurança de tipos
- Vite - Ferramenta de build

<!-- MANUAL: Notas personalizadas do projeto podem ser adicionadas abaixo -->

AGENTS.md Aninhado

<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# components

## Propósito
Componentes React reutilizáveis organizados por funcionalidade e complexidade.

## Arquivos Principais
| Arquivo | Descrição |
|---------|-----------|
| `index.ts` | Exportação barrel para todos os componentes |
| `Button.tsx` | Componente de botão principal |
| `Modal.tsx` | Componente de diálogo modal |

## Subdiretórios
| Diretório | Propósito |
|-----------|-----------|
| `forms/` | Componentes relacionados a formulários (veja `forms/AGENTS.md`) |
| `layout/` | Componentes de layout (veja `layout/AGENTS.md`) |

## Para Agentes de IA

### Trabalhando Neste Diretório
- Cada componente tem seu próprio arquivo
- Use módulos CSS para estilização
- Exporte via index.ts

### Requisitos de Teste
- Testes unitários no subdiretório `__tests__/`
- Use React Testing Library

### Padrões Comuns
- Interfaces de props definidas acima do componente
- Use forwardRef para componentes que expõem DOM

## Dependências

### Internas
- `src/hooks/` - Hooks personalizados usados pelos componentes
- `src/utils/` - Funções utilitárias

### Externas
- `clsx` - Nomes de classe condicionais
- `lucide-react` - Ícones

<!-- MANUAL: -->

Acionando Modo de Atualização

Ao executar em uma base de código existente com arquivos AGENTS.md:

1. Detecte arquivos existentes primeiro
2. Leia e analise o conteúdo existente
3. Analise o estado atual do diretório
4. Gere diff entre o existente e o atual
5. Aplique atualizações preservando seções manuais

Considerações de Performance

• Armazene em cache listagens de diretórios - Não re-escaneie os mesmos diretórios
• Agrupe diretórios pequenos - Processe vários de uma vez
• Pule inalterados - Se o diretório não mudou, pule a regeneração
• Escritas paralelas - Vários agentes escrevendo arquivos diferentes simultaneamente