generate-agents-context

Gere um AGENTS.md de alta qualidade para qualquer repositório, com um único comando no Claude Code.

/generate-agents-context

O que isso faz

O comando instrui o Claude Code a analisar seu repositório (README, manifests de dependências, arquivos de configuração, estrutura de pastas) e gerar um AGENTS.md na raiz do projeto — um arquivo de contexto escrito para ser seguido por agentes de IA (Claude Code, Cursor, Copilot, Gemini), não lido por humanos.

Exemplo do tipo de conteúdo gerado:

Ruim: "Utilizamos Angular." Bom: "Utilize Standalone Components."

Por que isso existe

Agentes de IA produzem código melhor quando têm contexto explícito sobre stack, arquitetura, convenções e anti-patterns do projeto. Escrever esse contexto manualmente é repetitivo. Este projeto automatiza a primeira versão desse arquivo, aproveitando a capacidade do próprio Claude Code de navegar e entender um repositório — sem exigir um scanner customizado.

Filosofia

• Simples primeiro. A IA faz toda a análise; não há parsing determinístico de código na v1.
• Foco em tokens. O comando prioriza arquivos de alto sinal (README, package.json, configs) antes de código-fonte.
• Extensível por design. A arquitetura reserva pontos de extensão claros para scanners determinísticos, plugins por linguagem, perfis por empresa e exportação para outros formatos (Cursor Rules, Copilot, JSON, YAML) — nada disso é implementado agora.

Por que não só usar um prompt?

No fundo, o generate-agents-context é um prompt — só que estruturado, versionado e distribuído. A diferença em relação a pedir "gere um AGENTS.md pra esse projeto" na mão não é mágica; é curadoria, consistência e reprodutibilidade:

| | Prompt manual | generate-agents-context | |---|---|---| | Consistência | Varia a cada vez e a cada pessoa | Mesmo fluxo e mesma estrutura sempre | | Cobertura | Depende de você lembrar de pedir arquitetura, testes, segurança, anti-patterns… | As 6 dimensões são garantidas por construção | | Qualidade da saída | Tende ao descritivo ("Usamos Angular") | Força o estilo imperativo ("Use Standalone Components") via output.md + template | | Custo de tokens | O modelo decide sozinho o que ler | Prioriza arquivos de alto sinal (README, manifests, config) antes do código-fonte | | Reprodutibilidade | Não versionável | Versionado no git, distribuível via npm/skill, igual para todo o time |

O maior valor está na engenharia embutida: alguém já decidiu quais perguntas fazer ao repositório e como o resultado deve ser escrito para ser útil a um agente. Um prompt improvisado costuma pular justamente isso — e é aí que a qualidade cai.

Use um prompt manual para um caso único e fora do padrão; use o generate-agents-context quando quiser que qualquer repo, qualquer pessoa do time, qualquer dia gere um AGENTS.md com a mesma qualidade.

Duas formas de uso: command ou skill

Você pode instalar o generate-agents-context de duas maneiras — ambas produzem o mesmo AGENTS.md:

• Command (/generate-agents-context) — um slash command que você dispara explicitamente. Instalado em .claude/commands/ + .claude/generate-agents-context/.
• Skill — invocada automaticamente pelo Claude Code quando você pede para gerar um AGENTS.md (sem precisar lembrar do comando). Instalada em .claude/skills/generate-agents-context/ (auto-contida: SKILL.md + references/).

Na instalação, você escolhe qual (ou ambos).

Instalação

Opção 1 — via npm/npx (requer Node.js):

npx generate-agents-context            # pergunta o que instalar (ou instala o command em modo não-interativo)
npx generate-agents-context --command  # apenas o slash command
npx generate-agents-context --skill    # apenas a skill
npx generate-agents-context --all      # ambos

Opção 2 — via script shell (requer apenas git e bash, sem Node):

# apenas o command (default):
curl -fsSL https://raw.githubusercontent.com/dutra21/generate-agents-context/main/install.sh | bash
# apenas a skill:
curl -fsSL https://raw.githubusercontent.com/dutra21/generate-agents-context/main/install.sh | bash -s -- --skill
# ambos:
curl -fsSL https://raw.githubusercontent.com/dutra21/generate-agents-context/main/install.sh | bash -s -- --all

Se o command/skill já existir, use --force para sobrescrever:

curl -fsSL https://raw.githubusercontent.com/dutra21/generate-agents-context/main/install.sh | bash -s -- --all --force

Depois, dentro do Claude Code:

• se instalou o command, rode /generate-agents-context;
• se instalou a skill, basta pedir algo como "gere um AGENTS.md para este projeto" — ela é acionada automaticamente.

Estrutura do repositório

generate-agents-context/
├── src/
│   ├── index.ts                     # CLI: parsing de args e orquestração
│   ├── installer.ts                 # lógica de instalação e reescrita de referências
│   ├── fs-utils.ts                  # utilitários de filesystem
│   ├── paths.ts                     # caminhos de origem/destino
│   └── installer.test.ts            # testes unitários
├── commands/
│   └── generate-agents-context.md   # comando slash, orquestra o fluxo
├── prompts/
│   ├── analyze.md                   # identifica stack, framework, arquitetura
│   ├── architecture.md              # descreve padrões arquiteturais
│   ├── coding.md                    # convenções de código
│   ├── testing.md                   # estratégia de testes
│   ├── security.md                  # práticas de segurança
│   ├── output.md                    # regras de formatação da saída final
│   └── languages/                   # (extensão futura) plugins por linguagem
├── templates/
│   └── agents.template.md           # contrato de estrutura do AGENTS.md
├── skills/
│   └── generate-agents-context/
│       ├── SKILL.md                 # skill: orquestra o fluxo (auto-invocável)
│       └── references/              # cópia auto-contida dos prompts + template
├── examples/                        # AGENTS.md gerados de exemplo
└── docs/
    └── ARCHITECTURE.md

Ao rodar npx generate-agents-context:

• para o command, o CLI copia commands/, prompts/ e templates/ para dentro de .claude/, reescrevendo as referências internas para o novo local;
• para a skill, o CLI copia skills/generate-agents-context/ para .claude/skills/generate-agents-context/. A skill é auto-contida (referências relativas a references/), então não há reescrita.

Linguagens/stacks suportadas na v1

Angular · React · Java · .NET · Node.js

Novas stacks podem ser adicionadas sem alterar a arquitetura central (ver docs/ARCHITECTURE.md).

Roadmap (não implementado ainda)

• Scanner determinístico como pré-etapa opcional de analyze.md
• Plugins de linguagem em prompts/languages/
• Perfis por empresa (regras customizadas)
• Renderizadores para Cursor Rules, Copilot, Gemini
• Exportação em JSON/YAML

Licença

MIT