Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Trabalhar em projetos com múltiplos repositórios

Aula 13 de 20 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Gerir a complexidade de arquiteturas distribuídas
  2. O custo real de uma alteração transversal
  3. Coordenar múltiplos repositórios
  4. Configurar o AGENTS.md num monorepositório
  5. Dois fluxos de trabalho transversais de referência
  6. O que o Codex não consegue fazer por si
  7. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base na documentação do Codex Cloud: vários repositórios coexistem agora num ambiente Codex Cloud (o antigo endereço codex.openai.com deixou de ser o ponto de entrada). Fonte: Codex Cloud.

Gerir a complexidade de arquiteturas distribuídas

Os projetos modernos abrangem frequentemente vários repositórios: um frontend, um backend, uma biblioteca partilhada, um serviço de pagamentos. Cada um tem o seu próprio ciclo de vida, pipeline de CI e equipas de manutenção. Esta configuração funciona perfeitamente — até que uma alteração atravesse as fronteiras dos repositórios. É aqui que o Codex muda as regras do jogo: consegue trabalhar simultaneamente em vários repositórios.

O custo real de uma alteração transversal

Considere uma tarefa de rotina: adiciona um campo a uma resposta de API no repositório do backend. De seguida, precisa de atualizar o cliente da API no repositório do frontend, os tipos partilhados no repositório comum, a documentação no repositório de docs e os testes de integração no repositório e2e. Nenhuma destas quatro tarefas é difícil isoladamente. Em conjunto, implicam quatro mudanças de contexto, quatro branches, quatro pull requests e quatro oportunidades de esquecer uma delas. Na prática, a documentação ou os testes e2e são omitidos, e o problema ressurge três semanas depois como um erro que ninguém consegue rastrear até àquele commit original.

Coordenar múltiplos repositórios

No Codex Cloud, um ambiente pode reunir vários repositórios GitHub: seleciona-os ao criar o ambiente, o Codex configura as suas dependências e ferramentas, e cada tarefa lançada nesse ambiente funciona em todo o conjunto. O seu prompt descreve então a alteração como um todo, em vez de isolar fragmentos:

"In the backend repo (api-service):
- Add a GET /api/v2/products endpoint with pagination

In the frontend repo (web-app):
- Update the API client to use the new endpoint
- Add pagination to the ProductList component"

O Codex aplica as alterações em cada repositório e abre pull requests coordenados. A propagação de um tipo partilhado segue a mesma lógica, com um requisito adicional que deve indicar explicitamente: verifique se a compilação é bem-sucedida em todos os repositórios afetados. Sem essa instrução, só descobrirá o erro de tipo no CI do repositório móvel duas horas após ter fundido todo o resto.

"The Product type in shared-types/src/product.ts has been 
modified (added tags: string[] field). 
Update all usages in:
- api-service: routes and services that use Product
- web-app: components that display a Product
- mobile-app: screens that display a Product
Ensure each repo compiles without errors."

Configurar o AGENTS.md num monorepositório

Se o seu projeto for um monorepositório (Turborepo, Nx, Lerna), a lógica inverte-se: os pacotes partilham uma única árvore de ficheiros, e a hierarquia de ficheiros AGENTS.md contém as distinções entre eles. O ficheiro raiz descreve a estrutura global e as regras aplicáveis em toda a parte:

# AGENTS.md (monorepo root)

## Structure
Turborepo monorepo with the following packages:
- packages/api — Fastify backend
- packages/web — Next.js frontend
- packages/shared — Shared types and utilities
- packages/e2e — Playwright end-to-end tests

## Rules
- Changes to packages/shared MUST be followed by a build 
  of all dependent packages
- Global build command: `turbo run build`
- Global test command: `turbo run test`

Cada subpacote constrói então sobre esta base com as suas próprias convenções, sem repetir o que já está no ficheiro raiz:

# packages/api/AGENTS.md

## Backend API
- Framework: Fastify
- Validation: Zod (schemas in src/schemas/)
- Types from packages/shared are imported via @myorg/shared
- Every new route requires a test in __tests__/

Dois fluxos de trabalho transversais de referência

O primeiro abrange uma funcionalidade que percorre toda a cadeia. Preste atenção à quarta instrução: a ligação cruzada entre pull requests pode parecer opcional, mas é o que permite ao revisor do repositório do frontend compreender por que razão aquele botão existe, sem ter de procurar o PR correspondente no backend.

"New feature: favorites system.
1. shared-types: Add the Favorite type
2. api-service: CRUD /api/favorites with auth
3. web-app: Heart button on product cards
4. Create a PR in each repo with links 
   to the other repos' PRs in the description"

O segundo abrange a migração de uma API versionada. Aqui, a ordem dos passos não é cosmética: garante que nenhum cliente fica isolado a meio da migração, com a v2 no lugar e a v1 ainda ativa durante toda a janela de migração dos consumidores.

"API v1 /users is deprecated. Create v2:
1. api-service: Add v2 routes with the new format
2. api-service: Mark v1 routes as deprecated (header)
3. web-app: Migrate all calls from v1 to v2
4. mobile-app: Migrate all calls from v1 to v2
5. docs: Update the API documentation"

O que o Codex não consegue fazer por si

O Codex trabalha repositório por repositório, em sandboxes separadas. Não consegue executar dois repositórios em conjunto: por exemplo, não pode lançar o backend e o frontend simultaneamente para um teste de integração real. Para testes entre repositórios, a sequência permanece manual:

  1. Fundir os PRs individuais
  2. Executar testes de integração a partir do seu pipeline de CI/CD
  3. Utilizar o Codex para corrigir quaisquer problemas detetados

Por outras palavras, o Codex garante a consistência do código escrito, nunca a consistência do sistema em execução. O seu CI/CD permanece o árbitro final, e a prudência dita que não deve implementar uma série de PRs coordenados até que este tenha proferido o seu veredicto.

Pontos-chave

  • O Codex pode criar PRs coordenados em vários repositórios
  • Tipos partilhados são um caso de uso ideal para fluxos de trabalho multi-repositório
  • Configure o AGENTS.md em cada pacote de um monorepositório
  • Os testes de integração entre repositórios devem continuar a ser verificados no CI/CD
  • Documente as dependências entre repositórios no AGENTS.md