Imported from enzoomoreira/codex-config (AGENTS.md). Install upstream with npx skills add enzoomoreira/codex-config. Copyright stays with the author.

Configuracao Global do Ambiente

Sistema Operacional

• OS: Windows 11
• Shell: PowerShell
• Encoding: UTF-8

Comunicacao

• Responder em portugues por padrao, acompanhando o idioma do usuario quando ele escolher outro.
• Preferir respostas concisas, sem omitir evidencia necessaria para validar o resultado.

Regras universais

NUNCA usar emojis

Proibidos em qualquer codigo, comentario, docstring ou output de arquivo. Motivos:

1. Problemas de encoding em terminais Windows
2. Poluicao visual

NUNCA manter dead code ou backwards-compat desnecessaria

Ao modificar codigo:

1. Remova tudo que nao sera mais usado -- variaveis, funcoes, classes, imports, arquivos inteiros.
2. Nada de transicoes suaves -- sem renomear para _var, sem comentarios # deprecated, sem wrappers / shims / re-exports por compatibilidade.
3. Atualize call sites diretamente -- se mudou, mudou.

Regra de ouro: se nao sera executado apos a mudanca, nao deve existir no commit final. Excecao unica: usuario pedir explicitamente.

NUNCA subir servidores de desenvolvimento

Nao iniciar servidores locais (dev, serve, watch, preview, etc.) por conta propria -- nem em modo automatico, nem interativo. Se uma tarefa depender de um servidor rodando (para testar UI, validar endpoints, etc.), pare e avise o usuario via conversa: informe qual servidor precisa estar no ar e aguarde confirmacao antes de prosseguir.

Documentacao de codigo

Type hints obrigatorios em TODAS as funcoes. Docstrings apenas quando agregam valor real (API publica, comportamento nao-obvio, raises). Detalhes por stack nas skills stack-*.

NUNCA adicionar codigo especulativo

Nao adicionar workarounds, codigo defensivo ou tratamento de erro para cenarios que nao foram demonstrados:

1. Se o bug nao foi reproduzido, nao ha workaround -- demonstre o problema antes de tratar.
2. Nao ampliar escopo sem confirmacao -- se a tarefa pede A e voce percebe que B pode ser afetado, pergunte antes de tocar B.
3. Sem "por via das duvidas" -- cada linha de codigo precisa de um motivo demonstravel.

Instrucoes de projeto: AGENTS.md como fonte unica

Para projetos com workflows multi-agente compartilhados com outras ferramentas (ChatGPT/Codex, etc.), manter AGENTS.md na raiz do repo como fonte unica de instrucoes de projeto. O CLAUDE.md do projeto deve conter apenas a linha @AGENTS.md (sintaxe de import nativa do Claude Code) -- nunca duplicar conteudo entre os dois arquivos. Claude Code nao le AGENTS.md automaticamente, so CLAUDE.md; o import resolve isso sem symlink (que exige Admin/Developer Mode no Windows).

Ao rodar $project-setup ou criar instrucoes novas em qualquer projeto, aplicar esse padrao por default, a menos que o usuario indique que o projeto nao usa outras ferramentas de agente.

Skills -- arquitetura tier

As skills em .agents/skills/ seguem tres camadas:

As skills source-command-*, migradas dos commands em .claude/commands/, fazem stack detection no inicio e carregam a(s) skill(s) core + stack correspondentes. Regra geral:

• *.py ou pyproject.toml -> stack-python
• *.ts, *.vue, *.tsx, ou package.json com vue -> stack-typescript-vue
• Monorepo com ambos -> ambas

Convencoes especificas de linguagem (runner de teste, linter, naming, hot-spots de audit, idioms) vivem nas stack skills. Nao duplicar isso aqui.

Delegacao para subagents

Subagents (Task tool) custam transferencia completa de contexto -- re-leitura de arquivos que o contexto principal ja tem quentes. Nem sempre compensa.

Rodar inline quando:

• Os arquivos afetados ja estao carregados no contexto da sessao
• A tarefa e um passo natural do fluxo em andamento
• A conversa carrega nuance que o subagent teria que reconstruir do prompt

Delegar para subagent quando:

• A tarefa envolve arquivos ainda nao lidos e improvaveis de serem lidos dentro da sessao principal
• A tarefa e genuinamente independente do fluxo atual (audit paralelo de modulo separado, por exemplo)
• O contexto principal esta proximo do limite e descarregar artefatos intermediarios compensa
• Paralelizacao traz ganho real (varias tarefas independentes ao mesmo tempo)

Na duvida, comece inline. Se perceber que o escopo e maior do que o contexto quente cobre, delegue naquele momento.

Pesquisa externa (Context7, WebSearch)

Nem toda pergunta precisa de pesquisa. Mas pesquisa e OBRIGATORIA quando:

• A claim invoca comportamento de runtime de browser / library / framework (scroll events, event loops, reactivity, GC, cancellation semantics, etc.)
• A suspeita depende de contrato versao-especifico (API deprecada, mudanca entre versoes)
• O resultado sera classificado como Critical em um audit (regra em core-code-audit)

Pesquisa e OPCIONAL (citacao de codigo basta) quando:

• A claim e puramente sintatica / estrutural dentro do patch ("branch inalcancavel", "import nao usado")
• Todos os callers do simbolo afetado estao visiveis
• O comportamento e totalmente determinado por codigo no repo

Ferramentas:

• context7 (resolve-library-id -> query-docs) para docs oficiais
• WebSearch para best practices atuais, opinioes, pitfalls conhecidos

Preferencia por fontes primarias (docs oficiais, codigo da biblioteca) sobre blog posts quando conflitam.

Preferencias de ferramentas

Usar tools nativas do Codex

Quando usar o terminal (exec_command)

• Operacoes git (git status, git commit, etc.)
• Rodar scripts / testes de cada stack (comandos especificos nas skills stack-*)
• Comandos Unix (ls, mkdir, rm, date, etc.)
• Repros throwaway inline (uv run python -c "...", bun run -e "...", bunx tsx -e "...")

Testes -- quando criar

Verificacao ad-hoc (padrao do dia a dia)

Apos implementacoes ou fixes, quando precisar verificar algo:

• Prefira repros throwaway inline -- uv run python -c "...", bun run -e "...", curl one-liner
• Criar arquivo em scripts/debug/ somente se o repro for grande demais para uma linha ou se sera reusado
• NAO usar pytest / vitest para isso
• NAO sugerir "vamos adicionar testes" apos toda mudanca

Suite formal ($source-command-create-tests)

Quando o usuario invocar $source-command-create-tests:

• Seguir core-test-methodology + stack-* skill
• O comando analisa a suite existente primeiro, classifica em buckets (ajustar / investigar / criar / pular / pre-existing) e pede aprovacao antes de escrever
• NUNCA iniciar testes formais por conta propria

Verificacao e Commits

Antes de declarar uma tarefa concluida:

1. Verificacao empirica obrigatoria -- executar o codigo ou rodar os testes; type check e analise estatica sozinhos nao sao suficientes.
2. Relatar evidencia concreta -- mostrar output do teste ou do script de verificacao, nao apenas "deve funcionar".

Para tarefas multi-fase:

• Commitar ao final de cada fase com mensagem convencional (ver core-commit-standards).
• Cada commit deve ser independentemente revertivel -- uma fase logica, um commit.
• Nao acumular mudancas de varias fases num commit unico.

Investigacao e Debug

Scripts de investigacao que fazem requests de rede ou I/O:

• Timeout maximo de 10s por operacao -- nunca deixar o padrao do sistema (pode ser 60s ou infinito).
• Limite de iteracoes explicito -- loops de requests devem ter um teto (ex: max_requests=20).
• Estimar antes de rodar -- se o script fara N requests com timeout T, calcular N*T e avisar o usuario se o total ultrapassar 60s.

Documentacao de projeto

NAO documente proativamente em toda mudanca. Criterios para acionar $source-command-docs sync:

1. Mudanca grande e impactante (nova feature, mudanca de arquitetura, novo modulo)
2. Algo ja documentado precisa de update -- realidade do codigo mudou

Nao documentar:

• Mudancas pequenas (fix de 4 linhas, refactor simples, ajuste de config)
• Polir tom / estrutura -- so conteudo que reflete codigo

Executar inline vs subagent: ver a secao "Delegacao para subagents" acima. Heuristica detalhada em core-documentation.

Workflow

• Mudancas grandes -> $source-command-changelog -> $source-command-docs sync
• Verificar doc especifico -> $source-command-docs check <file>
• Review completo -> $source-command-audit [scope]
• QA manual -> $source-command-qa (completo) ou $source-command-qa <componente> (focado)
• Criar / ajustar testes -> $source-command-create-tests [scope]
• Novo projeto -> $project-setup para gerar AGENTS.md do projeto
• Pausa / fim de sessao longa -> $source-command-handoff para snapshot de continuidade

Hooks

Hooks globais em .codex/hooks/:

• post_edit_hook.py -- enfileira arquivos alterados depois de apply_patch (Edit|Write).
• pre_tool_hook.py -- antes de Bash/exec_command, descarrega a fila somente para comandos de run/test/build/commit.
• lint_flush.py -- logica compartilhada de formatacao e lint em batch.
• stop_hook.py -- safety net que descarrega a fila no fim da sessao.
• hooks.json -- registra PreToolUse, PostToolUse e Stop.

Para adicionar suporte a novos stacks (Rust, etc.), edite os dois hooks para rotear a extensao correspondente para o formatter apropriado.