codex-workflows

English | 简体中文 | 日本語 | Español | 한국어 | Português (Brasil)

Em trabalhos maiores de produto, o Codex pode buscar uma consistência técnica que vai além do que o usuário realmente precisa. Cobrir todos os casos extremos e tornar cada caminho determinístico parece rigoroso, mas pode alterar o que o usuário vê mesmo quando o resultado aprovado não exige isso.

O codex-workflows mantém o trabalho dentro do menor resultado aprovado. Primeiro, deixa claro quais comportamentos visíveis podem mudar e quais devem permanecer intactos; depois, exige evidências antes de considerar o trabalho concluído. Dentro desses limites, o Codex escolhe detalhes de implementação reversíveis com base no que já existe no repositório.

Os fluxos são instalados como Agent Skills e agentes personalizados para o OpenAI Codex CLI. A sessão principal do Codex confirma o escopo e o custo aproximado antes do design, acompanha o andamento e decide como tratar as revisões, levando o trabalho aprovado da implementação até uma verificação independente.

Por que não usar o Codex diretamente?

O Codex sozinho é mais indicado para uma correção bem delimitada, um experimento descartável ou um script pontual. Quando o resultado esperado e o limite seguro de implementação já estão claros, essa opção é mais rápida e econômica.

Use o codex-workflows quando uma escolha técnica puder ampliar o escopo do produto, alterar o comportamento percebido pelo usuário ou quando uma decisão precisar sobreviver à troca de contexto.

Por exemplo, um pedido para estender um fluxo de autenticação existente pode acabar criando um segundo mecanismo — tecnicamente mais elegante —, validações mais amplas e um novo contrato de resposta. O frontend pode se adaptar e todos os testes podem passar, mas o usuário recebe um comportamento que nunca foi aprovado.

O codex-workflows controla esse crescimento de escopo ao longo de toda a execução:

Esse fluxo usa mais chamadas de agentes e mais tokens do que uma execução direta. Use-o quando proteger o resultado aprovado valer esse custo.

Um caso extremo não exige trabalho só porque o Codex sabe resolvê-lo. Validações adicionais, comportamento determinístico ou uma nova abstração precisam servir para proteger um requisito aprovado ou um contrato observável, ou para corrigir uma falha comprovada.

Um caso real

A integração do provedor BytePlus Seedream no mcp-image adicionou um terceiro provedor externo de imagens em 18 arquivos. Oito tarefas planejadas permitiram evoluir a implementação específica do provedor sem alterar os contratos públicos de solicitação MCP, cliente, salvamento de arquivos ou URI de arquivo.

Antes do merge, uma avaliação com o serviço real definiu o roteamento final dos modelos, os limites do prompt, o timeout e o tratamento das respostas. Revisões independentes também encontraram uma leitura de arquivo sem limite, uma forma de contornar a validação, um caminho FIFO bloqueante e uma normalização inconsistente das chaves de API. Os quatro problemas foram corrigidos, e o PR passou por 303 testes em 19 arquivos, além de uma chamada real ao provedor sem novas tentativas. Os contratos públicos aprovados permaneceram intactos durante as oito tarefas e as quatro correções.

Início rápido

Requer Node.js 22 ou mais recente e a versão mais atual do Codex CLI.

Instalar e executar

cd your-project
npx codex-workflows install

Depois, invoque um fluxo no Codex CLI:

$recipe-implement Adicione autenticação de usuários com JWT

O prefixo $ invoca uma skill explicitamente. Digite $recipe- para ver os fluxos disponíveis.

Escolha o ponto de partida

Como funciona

flowchart LR
    A[Pedido] --> B[Concordar com o menor resultado útil]
    B --> C{Há um caminho de implementação evidente?}
    C -->|Sim| S[Ciclo direto de tarefas e revisão de segurança]
    S --> L[Concluído]
    C -->|Não| D[Inspeção, design e revisão]
    D --> E[Planejar trabalhos dependentes]
    E --> F[Aprovar o escopo da implementação]
    F --> H[Por tarefa: implementar, verificar, checar qualidade e fazer commit]
    H --> K[Revisão independente de código e segurança]
    K -->|Correção| H
    K -->|Requisito ou design principal mudou| B
    K -->|Aprovado| L[Concluído]

O caminho depende da quantidade de decisões independentes de produto e design, não do número de arquivos nem da quantidade de casos extremos que o Codex consegue identificar.

Um ADR só é criado para uma escolha duradoura dentro do escopo atual quando existem pelo menos duas opções materialmente diferentes. Se várias escolhas atenderem a esses critérios, seus ADRs são revisados em conjunto. Um teste de integração ou E2E só é escolhido quando um teste mais barato não consegue comprovar a interação necessária. Algumas mudanças não exigem nenhum dos dois.

Somente decisões que afetam o produto ou a implementação do repositório seguem para documentos permanentes do projeto. Aprovação de terceiros, acesso à produção, execução de releases e tarefas operacionais sem relação com a mudança não se tornam bloqueios de implementação.

Depois da aprovação do escopo, o orquestrador executa as tarefas, as verificações específicas, as checagens aplicáveis do repositório e um commit de implementação por tarefa. Primeiro, resolve problemas com base nos documentos aprovados e nas evidências do repositório. O comportamento percebido pelo usuário continua sendo um limite de produto: a implementação não pode ajustá-lo por conta própria em nome da consistência interna. O orquestrador só consulta o usuário quando avançar exige um novo requisito de produto, uma mudança em uma decisão principal já aprovada, uma autorização que apenas o usuário possui ou uma ação irreversível que não foi autorizada.

Cada especialista recebe um trabalho com escopo definido, os documentos e caminhos relevantes e um resultado claro para entregar. O especialista conduz esse trabalho até o fim, enquanto a sessão principal mantém as decisões de produto e do fluxo, só intervém diante de uma decisão ou bloqueio concreto e verifica o resultado antes da próxima fase. Assim, os especialistas têm espaço para trabalhar sem receber autoridade para ampliar o resultado aprovado.

Como as decisões sobrevivem à troca de contexto

Separar os contextos evita que exploração, design, implementação e revisão compartilhem premissas de forma silenciosa. O modelo de Work Plan incluído associa cada tarefa de implementação à seção correspondente do Design Doc e aos critérios de aceite:

### P1-T1: Preservar o contrato de respostas de erro

- **Fonte**: `docs/design/example-design.md`, contrato da API, AC-2
- **Escopo**: Atualizar a implementação do repositório e seus testes específicos
- **Dependências**: nenhuma
- **Verificação**: Executar o teste de contrato e observar o formato de resposta documentado

O Task File Contract leva para a implementação a fonte, o resultado esperado, os arquivos-alvo e uma verificação executável. Ele só acrescenta um Verification Focus quando um teste pode passar sem comprovar um comportamento importante. Após a execução, todas as checagens aplicáveis do repositório rodam sobre a mudança completa antes do commit. Os revisores finais comparam o código concluído com os documentos aprovados. Eles também procuram mudanças fora do escopo aprovado e problemas sérios de qualidade do código. Quando uma correção é aceita, a revisão seguinte se concentra nas verificações que ela pode afetar. Execute $recipe-quality-profile para definir em docs/project-context/quality.yaml as regras de qualidade do repositório usadas durante a implementação e a revisão.

Instalação

Requisitos

• Codex CLI (versão mais recente)
• Node.js >= 22

Instalar

Instale no projeto atual:

cd your-project
npx codex-workflows install

Os seguintes itens serão copiados para o projeto:

• .agents/skills/: skills do Codex (fundamentos e fluxos)
• .codex/agents/: definições TOML dos subagentes
• Um manifesto para acompanhar os arquivos gerenciados

Para disponibilizar os fluxos em todos os projetos, instale-os no CODEX_HOME do usuário:

npx codex-workflows install --user

As skills são instaladas em $CODEX_HOME/skills/ e os agentes em $CODEX_HOME/agents/. Quando CODEX_HOME não está definido, o padrão é ~/.codex.

Personalizar agentes

As definições dos agentes são arquivos TOML comuns. Em uma instalação de projeto, edite os arquivos em .codex/agents/; em uma instalação de usuário, edite os arquivos em $CODEX_HOME/agents/. É possível alterar model, sandbox_mode ou developer_instructions. Os arquivos editados são preservados nas atualizações, conforme explicado a seguir.

Atualizar

# Visualizar as mudanças
npx codex-workflows update --dry-run

# Aplicar a atualização
npx codex-workflows update

# Atualizar uma instalação de usuário
npx codex-workflows update --user

O atualizador preserva os arquivos modificados localmente. Ele compara cada arquivo com o hash registrado na instalação e ignora os que mudaram. O histórico versionado de atualizações aplica movimentações e exclusões na ordem correta, de modo que as alterações locais acompanham um arquivo movido até o caminho atual. Arquivos modificados que forem removidos sem substituto são transferidos para .codex-workflows-preserved/<version>/. Arquivos novos são adicionados automaticamente.

# Consultar a versão instalada
npx codex-workflows status

# Consultar uma instalação de usuário
npx codex-workflows status --user

Referência dos fluxos

No Codex, use $recipe-name para invocar um fluxo. Digite $recipe- e use o preenchimento com Tab para ver todas as opções.

Estado de trabalho

Os fluxos usam docs/plans/ como estado temporário para Work Plans, Task Files de implementação e Task Files provisórios de correção ou adição de testes. O progresso de tarefas e fases é atualizado ali depois de cada commit aprovado pelas checagens de qualidade, mas esses arquivos de estado não entram no commit. Adicione o diretório ao .gitignore do projeto, a menos que a equipe queira revisar deliberadamente esses arquivos transitórios:

docs/plans/

PRDs, ADRs, UI Specs e Design Docs são documentos permanentes do projeto e devem ser incluídos nos commits.

Orientações incluídas

Cada fluxo carrega as orientações adaptadas ao repositório de que a tarefa atual precisa. Raramente é necessário selecionar essas skills manualmente.

Agentes especializados

O Codex cria esses agentes conforme a necessidade durante a execução dos fluxos. Não é preciso conhecer seus papéis antes: os fluxos encaminham o trabalho para o especialista adequado, enquanto o orquestrador mantém o controle geral. Cada agente trabalha em um contexto próprio, com instruções especializadas e skills obrigatórias nomeadas explicitamente.

Estrutura do projeto

Após a instalação, o projeto recebe:

your-project/
├── .agents/skills/           # Skills do Codex
│   ├── coding-rules/         # Orientações fundamentais
│   ├── testing/
│   ├── ai-development-guide/
│   ├── reviewee-judgment/
│   ├── documentation-criteria/
│   ├── requirement-convergence/
│   ├── implementation-approach/
│   ├── integration-e2e-testing/
│   ├── external-resource-context/
│   ├── llm-friendly-context/
│   ├── task-analyzer/
│   ├── subagent-delegation/
│   ├── subagents-orchestration-guide/
│   └── recipe-*/             # Pontos de entrada ($recipe-*)
├── .codex/agents/            # Definições TOML dos subagentes
│   ├── requirement-analyzer.toml
│   ├── technical-designer.toml
│   ├── ui-analyzer.toml
│   ├── task-executor.toml
│   └── ... (26 agentes no total)
└── docs/                     # Criado conforme os fluxos são usados
    ├── prd/
    ├── design/
    ├── adr/
    ├── ui-spec/
    └── plans/
        └── tasks/

Ecossistema

O Nautilus valida ideias de produto e gera PRDs, enquanto o linear-prism transforma requisitos aprovados em issues do Linear prontas para implementação. O claude-code-workflows aplica a mesma abordagem ao Claude Code e pode ser instalado no mesmo projeto que o codex-workflows.

Quer usar o Astra aqui?

Rodar um fluxo inteiro no Astra esgota o limite de uso rapidamente. O codex-subagent-playbook é um plugin do Codex que escolhe o modelo de cada subagente, então o Astra só é usado onde realmente faz diferença no resultado.

codex plugin marketplace add shinpr/codex-subagent-playbook

[[skills.config]]
path = "/Users/you/.codex/skills/subagent-delegation/SKILL.md"
enabled = false

[[skills.config]]
path = "/absolute/path/to/your-project/.agents/skills/subagent-delegation/SKILL.md"
enabled = false

Fundamentos do design

Licença

Licença MIT. Uso, modificação e distribuição são livres.

Criado e mantido por @shinpr.