Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Työskentely usean repositorion projekteissa

Oppitunti 13 / 20 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Hajautettujen arkkitehtuurien monimutkaisuuden hallinta
  2. Poikittaisen muutoksen todellinen hinta
  3. Usean repositorion koordinointi
  4. AGENTS.md:n määrittäminen monorepossa
  5. Kaksi viitekelvollista poikittaista työkulkua
  6. Mitä Codex ei voi tehdä puolestasi
  7. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 Codex Cloud -dokumentaation perusteella: useat repositoriot toimivat nyt yhdessä Codex Cloud -ympäristössä (vanha osoite codex.openai.com ei ole enää sisäänmenopiste). Lähde: Codex Cloud.

Hajautettujen arkkitehtuurien monimutkaisuuden hallinta

Nykyaikaiset projektit kattavat usein useita repositorioita: frontend, backend, jaettu kirjasto ja maksupalvelu. Jokaisella on oma elinkaarensa, CI-putkensa ja ylläpitäjänsä. Tämä toimii moitteettomasti – kunnes muutos ylittää repositorioiden rajat. Tässä Codex muuttaa pelin: se pystyy työskentelemään useassa repositoriossa samanaikaisesti.

Poikittaisen muutoksen todellinen hinta

Ota esimerkiksi rutiinitehtävä: lisäät kentän API-vastaukseen backend-repositoriossa. Tämän jälkeen sinun on päivitettävä API-asiakas frontend-repositoriossa, jaetut tyypit yhteisessä repositoriossa, dokumentaatio docs-repositoriossa ja integraatiotestit e2e-repositoriossa. Mikään näistä neljästä tehtävästä ei ole itsessään vaikea. Yhdessä ne tarkoittavat neljää kontekstinvaihtoa, neljää haaraa, neljää pull requestia ja neljää mahdollisuutta unohtaa jokin osa. Käytännössä dokumentaatio tai e2e-testit jäävät usein väliin, ja ongelma nousee uudelleen kolmen viikon kuluttua virheenä, jota kukaan ei osaa jäljittää alkuperäiseen commitiin.

Usean repositorion koordinointi

Codex Cloudissa ympäristö voi yhdistää useita GitHub-repositorioita: valitset ne ympäristöä luodessasi, Codex määrittää niiden riippuvuudet ja työkalut, ja jokainen kyseisessä ympäristössä käynnistetty tehtävä toimii koko joukon yli. Kehotuksesi kuvaa sitten muutosta kokonaisuutena erillisten palasten sijaan:

"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"

Codex toteuttaa muutokset kussakin repositoriossa ja avaa koordinoidut pull requestit. Jaetun tyypin levittäminen noudattaa samaa logiikkaa, mutta siihen liittyy yksi lisävaatimus, joka sinun tulee ilmaista eksplisiittisesti: varmista, että kääntäminen onnistuu kaikissa affected repositorioissa. Ilman tätä ohjetta huomaat tyyppivirheen mobiilisovelluksen repositorion CI:ssä kaksi tuntia kaiken muun yhdistämisen jälkeen.

"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."

AGENTS.md:n määrittäminen monorepossa

Jos projektisi on monorepo (Turborepo, Nx, Lerna), logiikka kääntyy päälaelleen: paketit jakavat yhden puurakenteen, ja AGENTS.md-tiedostojen hierarkia kantaa vastuun niiden välisistä eroista. Juuritiedosto kuvaa yleistä rakennetta ja sääntöjä, jotka pätevät kaikkialla:

# 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`

Jokainen alipaketti rakentaa tämän pohjan päälle omilla käytännöillään toistamatta koskaan sitä, mikä on jo juuritiedostossa:

# 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__/

Kaksi viitekelvollista poikittaista työkulkua

Ensimmäinen kattaa ominaisuuden, joka ulottuu koko ketjun läpi. Kiinnitä huomiota neljänteen ohjeeseen: pull requestien välinen ristiinlinkitys saattaa vaikuttaa valinnaiselta, mutta juuri sen ansiosta frontend-repositorion katselmoija ymmärtää, miksi tämä painike on olemassa, joutumatta metsästämään vastaavaa backend-PR:ää.

"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"

Toinen kattaa versionoidun API:n migraation. Tässä vaiheiden järjestys ei ole kosmeettista: se takaa, että mikään asiakas ei jää jumiin migraation puoliväliin, vaan v2 on paikallaan ja v1 edelleen toiminnassa koko kuluttajien siirtymäikkunan ajan.

"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"

Mitä Codex ei voi tehdä puolestasi

Codex työskentelee repositorio kerrallaan erillisissä hiekkalaatikoissa. Se ei voi ajaa kahta repositoriota yhdessä: et esimerkiksi voi käynnistää backendiä ja frontendiä samanaikaisesti aidon integraatiotestin suorittamiseksi. Repositorioiden välisten testien osalta sekvenssi pysyy manuaalisena:

  1. Yhdistä yksittäiset PR:t
  2. Suorita integraatiotestit CI/CD-putkestasi
  3. Käytä Codexia havaittujen ongelmien korjaamiseen

Toisin sanoen Codex takaa kirjoitetun koodin johdonmukaisuuden, ei koskaan suoritettavan järjestelmän johdonmukaisuutta. CI/CD-järjestelmäsi on viimeinen tuomari, ja varovaisuus sanelee, ettet ota käyttöön sarjaa koordinoituja PR:iä ennen kuin se on antanut tuomionsa.

Keskeiset asiat

  • Codex voi luoda koordinoituja PR:iä useiden repositorioiden yli
  • Jaetut tyypit ovat ihanteellinen käyttötapaus usean repositorion työkuluille
  • Määritä AGENTS.md monorepon jokaiselle paketille
  • Repositorioiden väliset integraatiotestit on edelleen varmistettava CI/CD:ssä
  • Dokumentoi repositorioiden väliset riippuvuudet tiedostoon AGENTS.md