SamuelChien/mega-skills-collection

Mantendo AGENTS.md

AGENTS.md é o documento canônico voltado para agentes. Mantenha-o mínimo — agentes são capazes e não precisam de supervisão. Mire em menos de 60 linhas; nunca ultrapasse 100. A qualidade de seguir instruções degrada conforme o documento aumenta.

Quando Usar

• O usuário pede para criar, atualizar ou auditar AGENTS.md ou CLAUDE.md.
• O projeto precisa de instruções concisas e de alto sinal para agentes, derivadas da toolchain e estrutura real do repositório.
• A documentação existente do agente é muito longa, duplicada ou está se distanciando das convenções reais do projeto.

Configuração do Arquivo

1. Crie AGENTS.md na raiz do projeto
2. Crie um link simbólico: ln -s AGENTS.md CLAUDE.md

Antes de Escrever

Analise o projeto para entender o que deve estar no arquivo:

1. Gerenciador de pacotes — Verifique arquivos de lock (pnpm-lock.yaml, yarn.lock, package-lock.json, uv.lock, poetry.lock)
2. Configurações de linter/formatter — Procure por .eslintrc, biome.json, ruff.toml, .prettierrc, etc. (não duplique em AGENTS.md)
3. Comandos CI/build — Verifique Makefile, scripts em package.json, configs de CI para comandos canônicos
4. Indicadores de monorepo — Verifique pnpm-workspace.yaml, nx.json, Cargo workspace, ou arquivos package.json em subdiretórios
5. Convenções existentes — Verifique CONTRIBUTING.md, docs/ ou padrões em README existentes

Regras de Escrita

• Cabeçalhos + bullets — Sem parágrafos
• Blocos de código — Para comandos e templates
• Referencie, não incorpore — Aponte para documentação existente: "Veja CONTRIBUTING.md para configuração" ou "Siga os padrões em src/api/routes/"
• Sem enchimento — Sem introduções, conclusões ou amenidades
• Confie nas capacidades — Omita contexto óbvio
• Prefira comandos com escopo de arquivo — Comandos de teste/lint/typecheck por arquivo em vez de builds globais
• Não duplique linters — Estilo de código vive em configurações de linter, não em AGENTS.md

Seções Obrigatórias

Gerenciador de Pacotes

Apenas qual ferramenta e comandos principais:

## Gerenciador de Pacotes
Use **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test`

Comandos com Escopo de Arquivo

Comandos por arquivo são mais rápidos e baratos que builds completos. Inclua sempre que disponível:

## Comandos com Escopo de Arquivo
| Tarefa | Comando |
|--------|---------|
| Typecheck | `pnpm tsc --noEmit caminho/para/arquivo.ts` |
| Lint | `pnpm eslint caminho/para/arquivo.ts` |
| Test | `pnpm jest caminho/para/arquivo.test.ts` |

Atribuição de Commits

Sempre inclua esta seção. Agentes devem usar sua própria identidade:

## Atribuição de Commits
Commits de IA DEVEM incluir:

Co-Authored-By: (nome e linha de atribuição do modelo do agente)

Exemplo: `Co-Authored-By: Claude Sonnet 4 <[email protected]>`

Convenções Principais

Padrões específicos do projeto que os agentes devem seguir. Seja breve.

Seções Opcionais

Adicione apenas se realmente necessário:

• Padrões de rotas de API (mostre template, não explicação)
• Comandos CLI (formato de tabela)
• Convenções de nomenclatura de arquivos
• Dicas de estrutura do projeto (aponte para arquivos críticos, sinalize código legado a evitar)
• Substituições de monorepo (arquivos AGENTS.md em subdiretórios substituem a raiz)

Anti-Padrões

Omita:

• "Bem-vindo ao..." ou "Este documento explica..."
• "Você deve..." ou "Lembre-se de..."
• Regras de linter/formatter já em arquivos de configuração (.eslintrc, biome.json, ruff.toml)
• Listar skills ou plugins instalados (agentes descobrem automaticamente)
• Comandos de build globais quando alternativas com escopo de arquivo existem
• Instruções óbvias ("execute testes", "escreva código limpo")
• Explicações do porquê (apenas diga o que fazer)
• Parágrafos longos em prosa

Exemplo de Estrutura

# Instruções do Agente

## Gerenciador de Pacotes
Use **pnpm**: `pnpm install`, `pnpm dev`

## Atribuição de Commits
Commits de IA DEVEM incluir:

Co-Authored-By: (nome e linha de atribuição do modelo do agente)

## Comandos com Escopo de Arquivo
| Tarefa | Comando |
|--------|---------|
| Typecheck | `pnpm tsc --noEmit caminho/para/arquivo.ts` |
| Lint | `pnpm eslint caminho/para/arquivo.ts` |
| Test | `pnpm jest caminho/para/arquivo.test.ts` |

## Rotas de API
[Bloco de código com template]

## CLI
| Comando | Descrição |
|---------|-----------|
| `pnpm cli sync` | Sincronizar dados |

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se as entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem faltando.