Fluxo de trabalho Codex e multiagente: trabalhe com agentes sem perder o controle

spinny:~/writing $ vim codex-multi-agent-workflows.md

1~
2Na primeira vez que um agente de codificação corrige um bug para você, a reação é quase sempre a mesma: uma mistura de entusiasmo e suspeita. Legal, claro. Mas aí você olha para o diff e se pergunta: "Ok, mas no que exatamente ele tocou? Posso confiar nele? Ele fará isso de novo da mesma forma amanhã?".
3~
4É aí que acho que começa a parte interessante. Não quando o agente escreve uma função, mas quando ele se torna capaz o suficiente para realizar trabalhos inteiros: ler o repositório, criar um patch, executar testes, abrir um PR, voltar após um comentário de revisão. O Codex está caminhando precisamente nessa direção: trabalho em segundo plano, árvores de trabalho separadas, navegador integrado, automações, plug-ins, memória e controles de permissão mais explícitos.
5~
6A questão não é imaginar um futuro onde ninguém leia mais código. Seria um futuro terrível, além de bastante ingênuo. A questão é descobrir como trabalhar com agentes que podem fazer muito sem deixá-los fazer tudo.
7~
8## A mudança de hábito
9~
10Com o preenchimento automático tradicional você estava sempre ao volante. A IA sugeriu uma fala, você decidiu. Com um agente, porém, o relacionamento muda: você dá a ele uma meta e ele passa por várias etapas sozinho.
11~
12Isso é poderoso, mas muda o problema. A questão não é mais apenas “o modelo pode programar?”. A questão passa a ser:
13~
14- Eu dei a ele um escopo pequeno o suficiente?
15- você sabe como verificar o resultado?
16- Estou trabalhando em um ambiente isolado?
17- A revisão final ainda é humana e cuidadosa?
18~
19Um fluxo de trabalho saudável se parece mais com isto do que com uma varinha mágica:
20~
21```mermaid
22flowchart LR
23    Idea[Tarefa humana] --> Scope[Propósito pequeno e verificável]
24    Scope --> Agent[Agente na árvore de trabalho isolado]
25    Agent --> Checks[Teste, lint, construção, navegador]
26    Checks --> Review[Revisão humana]
27    Review --> Merge[Mesclar ou nova iteração]
28    Review --> Iterate[Comentários precisos sobre o diff]
29    Iterate --> Agent
30```
31~
32Parece menos romântico do que “o agente constrói tudo”, mas funciona muito melhor. E é também assim que trabalham as equipes que são boas com os humanos: tarefas claras, feedback rápido, responsabilidade explícita.
33~
34## A boa dica é quase um bom ingresso
35~
36A solicitação mais perigosa é a vaga, mas confiante: “consertar a página de faturas”, “melhorar a arquitetura”, “limpar o módulo de autenticação”. São solicitações que parecem produtivas e geram enormes diferenças. Mas então você se pega fazendo arqueologia.
37~
38Um prompt útil é mais chato. Por exemplo: implementar exportação CSV para a página de faturas, sabendo que a tabela está em `app/(dashboard)/invoices/page.tsx`, as consultas estão em `src/server/invoices.ts` e já existe um padrão semelhante em `app/(dashboard)/reports`.
39~
40Em seguida, adicione restrições claras: não altere o esquema do banco de dados, não adicione dependências se um pequeno utilitário for suficiente, mantenha o estilo de UI existente. E feche com a verificação: `npm test -- invoices` e `npm run build`.
41~
42Este tipo de briefing não é para “explicar melhor para a IA”. Serve sobretudo para deixar mais claro o que você está delegando. Se você não consegue anotar concretamente, talvez a tarefa ainda não esteja pronta para um agente.
43~
44## Três tarefas que delego de boa vontade
45~
46O primeiro é um trabalho repetitivo, mas verificável: adicionar testes, migrar chamadas para uma nova API interna, atualizar importações, substituir componentes obsoletos, corrigir erros de TypeScript. Aqui o agente pode economizar horas e o risco é controlável.
47~
48O segundo é um trabalho exploratório: “descobrir onde esse total é calculado”, “explique-me porque esse teste é frágil”, “reproduzir o bug e me dizer quais arquivos parecem estar afetados”. Mesmo quando não produz um patch imediatamente, pode fazer um reconhecimento útil.
49~
50O terceiro é o trabalho de manutenção recorrente: pequenas atualizações de dependências, limpeza de sinalizadores de recursos antigos, resumo de PRs bloqueados, verificação de TODOs esquecidos. Não é glamoroso, mas é exatamente o tipo de trabalho que tende a se acumular.
51~
52## Três empregos que mantenho humanos
53~
54As decisões sobre produtos permanecem humanas. Se uma mudança alterar a forma como um usuário paga, exclui dados, vê preços ou entende uma permissão, quero uma pessoa responsável.
55~
56Os limites de segurança também merecem atenção humana: autenticação, funções, tokens, registro de dados confidenciais, migrações de banco de dados. Um agente pode ajudar na implementação, mas não precisa ser o único tomador de decisões.
57~
58Por fim, mantenho humano tudo o que exige gosto arquitetônico. Um agente pode propor um refatorador, mas entender se uma abstração é realmente necessária ou se estamos apenas polindo um problema inexistente continua sendo um trabalho.
59~
60## A revisão não é opcional
61~
62A tentação, quando um agente é bom, é confiar no verde do CI. É compreensível. É também quando os problemas começam.
63~
64Eu sempre olho para pelo menos cinco coisas:
65~
661. O patch resolve apenas a tarefa solicitada?
672. Ele tocou em arquivos que não tinham nada a ver com isso?
683. Os testes cobrem comportamentos novos ou apenas um feliz acaso?
694. O código segue padrões locais?
705. Os erros são tratados como no resto do projeto?
71~
72Quando algo está errado, o feedback precisa ser específico. “Consertar” é preguiçoso. Melhor: este utilitário duplica `parseMoney` em `src/lib/money.ts`; reutilize essa função, adicione um teste para o caso EUR e não altere a API pública do módulo de cobrança.
73~
74Os agentes respondem muito melhor a comentários pequenos e verificáveis. Curiosamente, o mesmo acontece com as pessoas.
75~
76## Guarda-corpos que valem o esforço
77~
78Se um agente puder ler arquivos, escrever código e executar comandos, ele deverá ser tratado como um processo poderoso. Não há necessidade de paranóia, você precisa de higiene.
79~
80Use árvores de trabalho ou ramificações separadas. Assim, você pode comparar as diferenças, descartar experimentos fracassados e não misturar o trabalho do agente com o que você estava fazendo.
81~
82Limitar permissões. Comandos como `rg`, `git diff`, `npm test` e `npm run build` podem ser bastante gratuitos. Implantações, migrações de bancos de dados, acesso a segredos e comandos destrutivos devem permanecer explícitos.
83~
84Reduza o acesso à rede quando não precisar dele. Para muitas tarefas, documentação oficial, registro de pacotes e serviços internos específicos são suficientes. Menos superfície, menos surpresas.
85~
86Acompanhe as ações. Quando um patch chega para revisão, você deve ser capaz de reconstruir prompts, comandos executados, testes aprovados e arquivos modificados. Não para criar burocracia, mas para poder entender o que acontece se algo der errado.
87~
88## Uma maneira fácil de começar em equipe
89~
90Se eu introduzisse agentes em uma equipe pequena, começaria sem grandes revoluções.
91~
92Eu criaria um rótulo `agent-ready` para questões com escopo claro. Eu adicionaria um modelo com contexto, restrições e comandos de verificação. Eu pediria um pequeno PR, de preferência com algumas centenas de linhas. Eu exigiria testes ou capturas de tela para alterações visíveis. E acima de tudo manteria uma pessoa responsável pela fusão.
93~
94Depois de duas semanas, eu analisaria os dados: quais tarefas foram realmente aceleradas, quais revisões foram pesadas, quais prompts foram confusos, quais partes da base de código são frágeis demais para serem delegadas.
95~
96É uma abordagem menos espectacular do que “a partir de hoje faremos tudo com os agentes”, mas é a que permite chegar à terceira semana sem arrependimentos.
97~
98## A parte mais humana
99~
100O engraçado é que quanto mais autônomos os agentes se tornam, mais importantes voltam a ser as habilidades clássicas: escrever um bom ticket, fazer pequenos cortes, criar testes, ler diferenças, comunicar trade-offs. O agente acelera quem já sabe trabalhar bem. Também amplifica o caos daqueles que delegam mal.
101~
102Portanto, não, não vejo os fluxos de trabalho multiagentes como um atalho para parar de fazer engenharia. Vejo-os como uma forma de transferir mais energia para as partes que importam: decidir o que construir, garantir que funciona, manter o sistema compreensível.
103~
104Os agentes podem ser ótimos colegas assíncronos. Mas um colega assíncrono, para ser útil, precisa de contexto, limites e revisão. Assim como todo mundo.
105~
106## Fontes úteis
107~
108- [Codex para (quase) tudo - OpenAI](https://openai.com/index/codex-for-almost-everything/)
109- [Executando Codex com segurança no OpenAI](https://openai.com/index/running-codex-safely/)
110- [Apresentando o Codex - OpenAI](https://openai.com/index/introducing-codex/)
111- [O que há de novo no agente de codificação GitHub Copilot](https://github.blog/ai-and-ml/github-copilot/whats-new-with-github-copilot-coding-agent/)
112~

NORMAL · codex-multi-agent-workflows.md [readonly]112 lines · :q to close

2Na primeira vez que um agente de codificação corrige um bug para você, a reação é quase sempre a mesma: uma mistura de entusiasmo e suspeita. Legal, claro. Mas aí você olha para o diff e se pergunta: "Ok, mas no que exatamente ele tocou? Posso confiar nele? Ele fará isso de novo da mesma forma amanhã?".

4É aí que acho que começa a parte interessante. Não quando o agente escreve uma função, mas quando ele se torna capaz o suficiente para realizar trabalhos inteiros: ler o repositório, criar um patch, executar testes, abrir um PR, voltar após um comentário de revisão. O Codex está caminhando precisamente nessa direção: trabalho em segundo plano, árvores de trabalho separadas, navegador integrado, automações, plug-ins, memória e controles de permissão mais explícitos.

6A questão não é imaginar um futuro onde ninguém leia mais código. Seria um futuro terrível, além de bastante ingênuo. A questão é descobrir como trabalhar com agentes que podem fazer muito sem deixá-los fazer tudo.

8## A mudança de hábito

10Com o preenchimento automático tradicional você estava sempre ao volante. A IA sugeriu uma fala, você decidiu. Com um agente, porém, o relacionamento muda: você dá a ele uma meta e ele passa por várias etapas sozinho.

11~

12Isso é poderoso, mas muda o problema. A questão não é mais apenas “o modelo pode programar?”. A questão passa a ser:

13~

14- Eu dei a ele um escopo pequeno o suficiente?

15- você sabe como verificar o resultado?

16- Estou trabalhando em um ambiente isolado?

17- A revisão final ainda é humana e cuidadosa?

18~

19Um fluxo de trabalho saudável se parece mais com isto do que com uma varinha mágica:

20~

21```mermaid

22flowchart LR

23 Idea[Tarefa humana] --> Scope[Propósito pequeno e verificável]

24 Scope --> Agent[Agente na árvore de trabalho isolado]

25 Agent --> Checks[Teste, lint, construção, navegador]

26 Checks --> Review[Revisão humana]

27 Review --> Merge[Mesclar ou nova iteração]

28 Review --> Iterate[Comentários precisos sobre o diff]

29 Iterate --> Agent

30```

31~

32Parece menos romântico do que “o agente constrói tudo”, mas funciona muito melhor. E é também assim que trabalham as equipes que são boas com os humanos: tarefas claras, feedback rápido, responsabilidade explícita.

33~

34## A boa dica é quase um bom ingresso

35~

36A solicitação mais perigosa é a vaga, mas confiante: “consertar a página de faturas”, “melhorar a arquitetura”, “limpar o módulo de autenticação”. São solicitações que parecem produtivas e geram enormes diferenças. Mas então você se pega fazendo arqueologia.

37~

38Um prompt útil é mais chato. Por exemplo: implementar exportação CSV para a página de faturas, sabendo que a tabela está em `app/(dashboard)/invoices/page.tsx`, as consultas estão em `src/server/invoices.ts` e já existe um padrão semelhante em `app/(dashboard)/reports`.

39~

40Em seguida, adicione restrições claras: não altere o esquema do banco de dados, não adicione dependências se um pequeno utilitário for suficiente, mantenha o estilo de UI existente. E feche com a verificação: `npm test -- invoices` e `npm run build`.

41~

42Este tipo de briefing não é para “explicar melhor para a IA”. Serve sobretudo para deixar mais claro o que você está delegando. Se você não consegue anotar concretamente, talvez a tarefa ainda não esteja pronta para um agente.

43~

44## Três tarefas que delego de boa vontade

45~

46O primeiro é um trabalho repetitivo, mas verificável: adicionar testes, migrar chamadas para uma nova API interna, atualizar importações, substituir componentes obsoletos, corrigir erros de TypeScript. Aqui o agente pode economizar horas e o risco é controlável.

47~

48O segundo é um trabalho exploratório: “descobrir onde esse total é calculado”, “explique-me porque esse teste é frágil”, “reproduzir o bug e me dizer quais arquivos parecem estar afetados”. Mesmo quando não produz um patch imediatamente, pode fazer um reconhecimento útil.

49~

50O terceiro é o trabalho de manutenção recorrente: pequenas atualizações de dependências, limpeza de sinalizadores de recursos antigos, resumo de PRs bloqueados, verificação de TODOs esquecidos. Não é glamoroso, mas é exatamente o tipo de trabalho que tende a se acumular.

51~

52## Três empregos que mantenho humanos

53~

54As decisões sobre produtos permanecem humanas. Se uma mudança alterar a forma como um usuário paga, exclui dados, vê preços ou entende uma permissão, quero uma pessoa responsável.

55~

56Os limites de segurança também merecem atenção humana: autenticação, funções, tokens, registro de dados confidenciais, migrações de banco de dados. Um agente pode ajudar na implementação, mas não precisa ser o único tomador de decisões.

57~

58Por fim, mantenho humano tudo o que exige gosto arquitetônico. Um agente pode propor um refatorador, mas entender se uma abstração é realmente necessária ou se estamos apenas polindo um problema inexistente continua sendo um trabalho.

59~

60## A revisão não é opcional

61~

62A tentação, quando um agente é bom, é confiar no verde do CI. É compreensível. É também quando os problemas começam.

63~

64Eu sempre olho para pelo menos cinco coisas:

65~

661. O patch resolve apenas a tarefa solicitada?

672. Ele tocou em arquivos que não tinham nada a ver com isso?

683. Os testes cobrem comportamentos novos ou apenas um feliz acaso?

694. O código segue padrões locais?

705. Os erros são tratados como no resto do projeto?

71~

72Quando algo está errado, o feedback precisa ser específico. “Consertar” é preguiçoso. Melhor: este utilitário duplica `parseMoney` em `src/lib/money.ts`; reutilize essa função, adicione um teste para o caso EUR e não altere a API pública do módulo de cobrança.

73~

74Os agentes respondem muito melhor a comentários pequenos e verificáveis. Curiosamente, o mesmo acontece com as pessoas.

75~

76## Guarda-corpos que valem o esforço

77~

78Se um agente puder ler arquivos, escrever código e executar comandos, ele deverá ser tratado como um processo poderoso. Não há necessidade de paranóia, você precisa de higiene.

79~

80Use árvores de trabalho ou ramificações separadas. Assim, você pode comparar as diferenças, descartar experimentos fracassados e não misturar o trabalho do agente com o que você estava fazendo.

81~

82Limitar permissões. Comandos como `rg`, `git diff`, `npm test` e `npm run build` podem ser bastante gratuitos. Implantações, migrações de bancos de dados, acesso a segredos e comandos destrutivos devem permanecer explícitos.

83~

84Reduza o acesso à rede quando não precisar dele. Para muitas tarefas, documentação oficial, registro de pacotes e serviços internos específicos são suficientes. Menos superfície, menos surpresas.

85~

86Acompanhe as ações. Quando um patch chega para revisão, você deve ser capaz de reconstruir prompts, comandos executados, testes aprovados e arquivos modificados. Não para criar burocracia, mas para poder entender o que acontece se algo der errado.

87~

88## Uma maneira fácil de começar em equipe

89~

90Se eu introduzisse agentes em uma equipe pequena, começaria sem grandes revoluções.

91~

92Eu criaria um rótulo `agent-ready` para questões com escopo claro. Eu adicionaria um modelo com contexto, restrições e comandos de verificação. Eu pediria um pequeno PR, de preferência com algumas centenas de linhas. Eu exigiria testes ou capturas de tela para alterações visíveis. E acima de tudo manteria uma pessoa responsável pela fusão.

93~

94Depois de duas semanas, eu analisaria os dados: quais tarefas foram realmente aceleradas, quais revisões foram pesadas, quais prompts foram confusos, quais partes da base de código são frágeis demais para serem delegadas.

95~

96É uma abordagem menos espectacular do que “a partir de hoje faremos tudo com os agentes”, mas é a que permite chegar à terceira semana sem arrependimentos.

97~

98## A parte mais humana

99~

100O engraçado é que quanto mais autônomos os agentes se tornam, mais importantes voltam a ser as habilidades clássicas: escrever um bom ticket, fazer pequenos cortes, criar testes, ler diferenças, comunicar trade-offs. O agente acelera quem já sabe trabalhar bem. Também amplifica o caos daqueles que delegam mal.

101~

102Portanto, não, não vejo os fluxos de trabalho multiagentes como um atalho para parar de fazer engenharia. Vejo-os como uma forma de transferir mais energia para as partes que importam: decidir o que construir, garantir que funciona, manter o sistema compreensível.

103~

104Os agentes podem ser ótimos colegas assíncronos. Mas um colega assíncrono, para ser útil, precisa de contexto, limites e revisão. Assim como todo mundo.

105~

106## Fontes úteis

107~

108- [Codex para (quase) tudo - OpenAI](https://openai.com/index/codex-for-almost-everything/)

109- [Executando Codex com segurança no OpenAI](https://openai.com/index/running-codex-safely/)

110- [Apresentando o Codex - OpenAI](https://openai.com/index/introducing-codex/)

111- [O que há de novo no agente de codificação GitHub Copilot](https://github.blog/ai-and-ml/github-copilot/whats-new-with-github-copilot-coding-agent/)

112~