Documentação do ChatGPT
Português
Contacto goolvyouyou@gmail.com

Instruções personalizadas com AGENTS.md

Dê ao Codex instruções e contexto adicionais para o seu projeto

O Codex lê os ficheiros AGENTS.md antes de realizar qualquer trabalho. Ao combinar orientações globais com substituições específicas do projeto, pode iniciar cada tarefa com expectativas consistentes, independentemente do repositório que abrir.

Como o Codex encontra orientações

O Codex cria uma cadeia de instruções quando é iniciado (uma vez por execução; na TUI, isto significa geralmente uma vez por sessão iniciada). A deteção segue esta ordem de precedência:

  1. Âmbito global: No diretório base do Codex (a predefinição é ~/.codex, a menos que defina CODEX_HOME), o Codex lê AGENTS.override.md, caso exista. Caso contrário, o Codex lê AGENTS.md. O Codex utiliza apenas o primeiro ficheiro não vazio neste nível.
  2. Âmbito do projeto: A partir da raiz do projeto (normalmente, a raiz do Git), o Codex percorre os diretórios até ao diretório de trabalho atual. Se não conseguir encontrar uma raiz de projeto, verifica apenas o diretório atual. Em cada diretório do caminho, procura AGENTS.override.md, depois AGENTS.md e, em seguida, quaisquer nomes alternativos definidos em project_doc_fallback_filenames. O Codex inclui, no máximo, um ficheiro por diretório.
  3. Ordem de combinação: O Codex concatena os ficheiros a partir da raiz, separando-os com linhas em branco. Os ficheiros mais próximos do diretório atual substituem as orientações anteriores, pois aparecem mais tarde na instrução combinada.

O Codex ignora ficheiros vazios e deixa de adicionar ficheiros quando o tamanho combinado atinge o limite definido por project_doc_max_bytes (32 KiB por predefinição). Para obter detalhes sobre estas opções, consulte Deteção de instruções do projeto. Aumente o limite ou distribua as instruções por diretórios aninhados quando atingir o limite máximo.

Criar orientações globais

Crie predefinições persistentes no diretório base do Codex para que todos os repositórios herdem os seus acordos de trabalho.

  1. Certifique-se de que o diretório existe:

    mkdir -p ~/.codex

  2. Crie ~/.codex/AGENTS.md com preferências reutilizáveis:

    # ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

  3. Execute o Codex em qualquer local para confirmar que o ficheiro é carregado:

    codex --ask-for-approval never "Summarize the current instructions."

    Resultado esperado: o Codex cita os itens de ~/.codex/AGENTS.md antes de propor trabalho.

Utilize ~/.codex/AGENTS.override.md quando precisar de uma substituição global temporária sem eliminar o ficheiro base. Remova a substituição para repor as orientações partilhadas.

Organizar instruções do projeto em camadas

Os ficheiros ao nível do repositório mantêm o Codex informado sobre as normas do projeto, continuando a herdar as predefinições globais.

  1. Na raiz do repositório, adicione um AGENTS.md que abranja a configuração básica:

    # AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

  2. Adicione substituições em diretórios aninhados quando equipas específicas precisarem de regras diferentes. Por exemplo, dentro de services/payments/, crie AGENTS.override.md:

    # services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

  3. Inicie o Codex a partir do diretório de pagamentos:

    codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

    Resultado esperado: o Codex apresenta primeiro o ficheiro global, depois o AGENTS.md da raiz do repositório e, por último, a substituição de pagamentos.

O Codex deixa de procurar quando chega ao diretório atual, por isso coloque as substituições tão perto quanto possível do trabalho especializado.

Este é um exemplo de repositório depois de adicionar um ficheiro global e uma substituição específica para pagamentos:

<FileTree class="mt-4" tree={[ { name: "AGENTS.md", comment: "Expectativas do repositório", highlight: true, }, { name: "services/", open: true, children: [ { name: "payments/", open: true, children: [ { name: "AGENTS.md", comment: "Ignorado porque existe uma substituição", }, { name: "AGENTS.override.md", comment: "Regras do serviço de pagamentos", highlight: true, }, { name: "README.md" }, ], }, { name: "search/", children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }], }, ], }, ]} />

Adicionar regras de revisão de código

Para a revisão de código do Codex no GitHub, adicione uma secção ## Code Review Rules ao AGENTS.md mais próximo do código ao qual as regras se aplicam. Coloque as verificações de todo o repositório na raiz e as verificações específicas de cada serviço num ficheiro aninhado.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Mantenha as regras concisas, explique o comportamento a assinalar e qualquer procedimento seguro ou exceção, e reserve as verificações de formatação e lint para a CI. Consulte Personalizar o que o Codex revê para obter orientações sobre a configuração e a redação de regras.

Personalizar nomes de ficheiros alternativos

Se o seu repositório já utilizar um nome de ficheiro diferente (por exemplo, TEAM_GUIDE.md), adicione-o à lista de nomes alternativos para que o Codex o trate como um ficheiro de instruções.

  1. Edite a configuração do Codex:

    # ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

  2. Reinicie o Codex ou execute um novo comando para carregar a configuração atualizada.

Agora, o Codex verifica cada diretório por esta ordem: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Os nomes de ficheiros que não constem desta lista são ignorados durante a deteção de instruções. O limite de bytes superior permite combinar mais orientações antes de ocorrer o truncamento.

Com a lista de nomes alternativos definida, o Codex trata os ficheiros alternativos como instruções:

<FileTree class="mt-4" tree={[ { name: "TEAM_GUIDE.md", comment: "Detetado através da lista de nomes alternativos", highlight: true, }, { name: ".agents.md", comment: "Ficheiro alternativo na raiz", }, { name: "support/", open: true, children: [ { name: "AGENTS.override.md", comment: "Substitui as orientações alternativas", highlight: true, }, { name: "playbooks/", children: [{ name: "…", placeholder: true }], }, ], }, ]} />

Defina a variável de ambiente CODEX_HOME quando pretender utilizar um perfil diferente, como um utilizador de automatização específico do projeto:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

Resultado esperado: a saída apresenta ficheiros relativos ao diretório .codex personalizado.

Verificar a configuração

  • Execute codex --ask-for-approval never "Summarize the current instructions." a partir da raiz de um repositório. O Codex deverá reproduzir as orientações dos ficheiros globais e do projeto pela ordem de precedência.
  • Utilize codex --cd subdir --ask-for-approval never "Show which instruction files are active." para confirmar que as substituições aninhadas substituem regras mais abrangentes.
  • Para auditar os ficheiros de instruções carregados pelo Codex, ative um registo da TUI em texto simples com codex -c log_dir=./.codex-log e consulte ./.codex-log/codex-tui.log, ou inspecione o ficheiro session-*.jsonl mais recente, caso tenha ativado o registo de sessões.
  • Se as instruções parecerem desatualizadas, reinicie o Codex no diretório de destino. O Codex recria a cadeia de instruções em cada execução (e no início de cada sessão da TUI), pelo que não existe nenhuma cache para limpar manualmente.

Resolver problemas de deteção

  • Nada é carregado: Confirme que se encontra no repositório pretendido e que codex status apresenta a raiz esperada da área de trabalho. Certifique-se de que os ficheiros de instruções têm conteúdo; o Codex ignora ficheiros vazios.
  • São apresentadas orientações incorretas: Procure um AGENTS.override.md num nível superior da árvore de diretórios ou no diretório base do Codex. Mude o nome ou remova a substituição para voltar ao ficheiro normal.
  • O Codex ignora nomes alternativos: Confirme que incluiu os nomes em project_doc_fallback_filenames sem erros ortográficos e, em seguida, reinicie o Codex para que a configuração atualizada entre em vigor.
  • As instruções são truncadas: Aumente project_doc_max_bytes ou distribua ficheiros grandes por diretórios aninhados para manter intactas as orientações essenciais.
  • Confusão de perfis: Execute echo $CODEX_HOME antes de iniciar o Codex. Um valor diferente do predefinido direciona o Codex para um diretório base diferente daquele que editou.

Próximos passos