Yhdistä Codex, Claude Code ja Cursor yhdeksi CLI-tiimiksi

Codex, Claude Code ja Cursor voivat muokata koodivarastoja, suorittaa komentoja ja noudattaa projektin ohjeita niille määritettyjen ominaisuuksien ja oikeuksien rajoissa. Tässä artikkelissa kokeillaan tiedostoihin perustuvaa toimintamallia. Se ei väitä, että jokainen tiimi tarvitsee kolme agenttia tai että yhteinen sopimus poistaisi työkalujen väliset erot.

Työnkulku rakentuu tiedostoista ja komentorivityökaluista, jotka ovat jo käytössäsi:

• Projektin yhteiset ohjeet tiedostossa AGENTS.md
• Claude-yhteensopivuus tiedoston CLAUDE.md avulla, jonka kautta tuodaan @AGENTS.md-ohjeet
• Cursorin perusohjeet ja tarvittaessa .cursor/rules-säännöt
• Roolien välinen rakenteinen Markdown-luovutus
• Suunnittelun, tarkastuksen ja toteutuksen ei-vuorovaikutteiset komentoriviajot

Tämä malli ei edellytä erillistä projektinhallinta-alustaa. Jos haluat myöhemmin agenteille yhteisen työjonon, yhdistä malli moniagenttisen projektin hallintaan Linearilla. Tässä koordinointi tapahtuu Gitin ja Markdown-tiedostojen avulla.

Tuotedokumentaatio tarkistettiin uudelleen 2026-08-04 seuraavien lähteiden avulla: AGENTS.md, OpenAI Codexin AGENTS.md-ohje, Codexin ei-vuorovaikutteinen tila, Claude Coden muistiohjeet, Claude Coden CLI-ohje ja Cursorin CLI-ohjeet. Kolmen asiakasohjelman koko luovutusketjua ei suoritettu tässä tarkastuksessa alusta loppuun. Varmenna komennot ja oikeudet ennalta valituilla ja lukituilla asiakasohjelmaversioilla ennen kuin otat työnkulun käyttöön.

Tiimin roolijako

Toimiva aloitusjako:

Roolit ovat työskentelysopimus, eivät työkalutoimittajien asettamia rajoja. Jokainen työkalu voi suunnitella, tarkastaa tai toteuttaa. Erikoistuminen auttaa, koska se luo kirjallisen rajapinnan: yksi agentti laatii suunnitelman, toinen etsii siitä puutteet ja kolmas toteuttaa vain tarkastuksessa hyväksytyn osuuden.

Jaetut ohjeet: yksi totuuden lähde

Käytä AGENTS.md:tä siirrettävänä perustana

AGENTS.md on Agentic AI Foundationin ylläpitämä, eri työkaluille tarkoitettu ohjemuoto. Codex lukee sitä suoraan. Cursor tukee projektin juuressa olevaa AGENTS.md-tiedostoa yhteisenä projektiohjeena .cursor/rules-sääntöjen rinnalla. Pidä tiedosto lyhyenä ja käytännöllisenä:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`

## Patch rules
- One behavior change per branch
- Prefer existing helpers over new dependencies
- Do not edit secrets or `.env*` files
- Do not merge to main

## Multi-agent protocol
- Read `docs/handoffs/` before starting
- Write status back into the active handoff file
- Designer, reviewer, and implementer must be different runs
- Stop for auth, payments, production infra, or data deletion

OpenAI:n Codex-ohjeiden mukaan ohjetiedostoja etsitään projektin juuresta nykyiseen työhakemistoon asti. Lähempänä työhakemistoa olevat tiedostot ovat etusijalla, AGENTS.override.md on valinnainen ja yhdistetyn sisällön oletusraja on 32 KiB, ellei sitä kasvateta. Pidä juuritiedosto tiiviinä ja sijoita pakettikohtaiset säännöt alempien hakemistojen AGENTS.md-tiedostoihin.

Yhdistä Claude Code yhteisiin ohjeisiin CLAUDE.md:llä

Claude Code lukee CLAUDE.md:tä, ei AGENTS.md:tä. Virallinen ohje on tuoda yhteinen tiedosto siihen näin:

@AGENTS.md

## Claude Code
- Prefer plan mode before edits on `src/billing/` and auth code
- For review jobs, do not implement unless the handoff status is `implement` or `fixes`

Symbolinen linkki (ln -s AGENTS.md CLAUDE.md) toimii myös, jos et tarvitse Claude-kohtaisia lisäyksiä. Windowsissa kannattaa käyttää @AGENTS.md-tuontia.

Varmista latautuminen Clauden /context-komennolla ja tarkista kohta Memory files.

Pidä Cursor-kohtaiset säännöt kapeina

Cursor voi käyttää juuren AGENTS.md:tä yhteisiin käytäntöihin. Käytä .cursor/rules/*.mdc-tiedostoja vain Cursor-kohtaisiin tarpeisiin, kuten tiedostokuvioihin rajattuihin sääntöihin. Älä ylläpidä samoista ohjeista kolmea erilleen ajautuvaa versiota.

Luovutustiedosto vastaa tiimiläisten välistä keskustelua

Luo hakemisto:

mkdir -p docs/handoffs

Käytä yhtä tiedostoa per työkokonaisuus:

docs/handoffs/2026-07-29-pricing-section.md

# Handoff: pricing section

- ID: pricing-section
- Status: design
- Owner now: codex
- Next owner: claude
- Branch: codex/design-pricing-section
- Worktree: ../app-pricing-section

## Goal
Implement the marketing pricing section using existing Section/PlanCard patterns.

## Non-goals
Billing, coupons, seat math.

## Design
(Codex fills this)

## Review
(Claude fills this)

## Implementation notes
(Cursor fills this)

## Verification
- Command: `pnpm test:e2e --grep "pricing"`
- Last result:

## Decision log
- 2026-07-29 Codex: drafted component boundaries

Seuraava tilajoukko toimii hyvin, kun palaute voi palauttaa työn aiempaan vaiheeseen:

1. design
2. design-review: estävät löydökset palauttavat työn tilaan design; hyväksytty tarkastus vie sen tilaan implement
3. implement
4. impl-review: estävät löydökset vievät työn tilaan fixes; hyväksytty tarkastus asettaa tilaksi done
5. fixes: toteuttaja korjaa löydökset ja palauttaa työn sitten tilaan impl-review
6. done
7. blocked-human

Kaikkien tehtävien ei tarvitse käydä tilassa fixes. Hyväksytty impl-review voi edetä suoraan tilaan done.

Jokainen komentoriviajo alkaa tiedoston lukemisella ja päättyy tilan, nykyisen omistajan ja päätöslokin päivittämiseen. Se muodostaa koko orkestrointikerroksen.

Esimerkki: yhden suunnittelu- ja tarkastuskierroksen jälkeen

Tältä luovutustiedosto voisi näyttää sen jälkeen, kun Codex on suunnitellut ja Claude tarkastanut työn:

- Status: implement
- Owner now: cursor
- Next owner: claude

## Design
Files: `PricingSection.tsx` (new), reuse `PlanCard.tsx`
CTA must track clicks with `trackEvent()` + `getCtaClickProps()` from `src/lib/analytics.ts`
Mobile: stacked below `md`, three columns from `md` up
Plan IDs: `starter`, `pro`, `business`
Test: `pnpm test:e2e --grep "pricing"`

## Review
Blocking: none remaining (breakpoint + plan IDs resolved in Design above)
Non-blocking:
- Extract plan constants later if CMS arrives.

## Decision log
- 2026-07-29 Codex: initial component boundaries
- 2026-07-29 Claude: requested breakpoint + explicit plan IDs
- 2026-07-29 Codex: updated Design; Claude cleared blocking items → implement

Cursorin on noudatettava juuri tätä tiedostoa. Keskusteluhistoria on valinnainen, mutta luovutustiedosto on pakollinen.

Asenna ja käytä kutakin komentorivityökalua

Tarkat asennustavat muuttuvat, joten tarkista ne aina toimittajan ajantasaisista ohjeista. Olennaista on ei-vuorovaikutteisten komentojen rakenne.

Codex: suunnitteluvaihe

Codexin ei-vuorovaikutteinen tila on codex exec. Se käynnistyy oletuksena vain lukuoikeuden hiekkalaatikossa. Luovutustiedostoa päivittävä suunnittelutehtävä tarvitsee kirjoitusoikeuden työtilaan:

cd ../app-pricing-section
codex exec --sandbox workspace-write "$(cat <<'EOF'
Read AGENTS.md and docs/handoffs/2026-07-29-pricing-section.md.
Status is design. Produce the Design section only:
- proposed files
- component/API boundaries
- test plan
- risks
- open questions
Do not implement application code.
Set status to design-review and next owner to claude.
Append a Decision log entry.
EOF
)"

Käytä vuorovaikutteista codex-komentoa vain, kun haluat ohjata suunnittelua ajon aikana. Käytä skripteissä ja peräkkäisissä ajoissa mieluummin komentoa codex exec.

Claude Code: tarkastusvaihe

Claude Coden tulostustila voi tarkastaa ja päivittää luovutustiedoston, mutta vain jos käyttöoikeusasetukset sallivat kirjoittamisen kyseisessä työpuussa. Rajaa tehtävä tarkasti:

cd ../app-pricing-section
claude -p --permission-mode acceptEdits --max-turns 30 --max-budget-usd 5 --output-format text "$(cat <<'EOF'
Read AGENTS.md / CLAUDE.md and docs/handoffs/2026-07-29-pricing-section.md.
You are the reviewer. Do not implement application code.
Challenge the Design section for missing edge cases, local-architecture mismatches, weak tests, and security issues.
Write findings into the Review section as Blocking vs Non-blocking.
If blocking findings exist, set status to design and next owner to codex.
Otherwise set status to implement and next owner to cursor.
Append a Decision log entry.
EOF
)"

Jos Claude Coden käyttöoikeustila ei salli tiedostojen kirjoittamista ei-vuorovaikutteisessa ajossa, tee tarkastus vain lukuoikeudella ja anna ihmisen tai skriptin lisätä tarkastusosio luovutustiedostoon. Käytä erillisessä työpuussa mieluiten asetusta --permission-mode acceptEdits tai asetustiedoston sallittujen toimintojen luetteloa. Älä käytä valitsinta --dangerously-skip-permissions oikeassa työhakemistossa.

Hyödyllisiä Claude Coden asetuksia automatisoituihin ajoihin on lueteltu CLI-ohjeessa:

• -p / --print ei-vuorovaikutteiseen ajoon
• --max-turns silmukoiden rajaamiseen
• --max-budget-usd kulutuksen rajaamiseen
• --output-format json|text|stream-json automaatioon
• --permission-mode acceptEdits, kun tarkastuksen on kirjoitettava luovutustiedostoon rajatussa työpuussa

Älä käytä valitsinta --dangerously-skip-permissions harkitsematta tuotantokoodin työhakemistoissa.

Cursor: toteutusvaihe

Cursorin komentorivityökalu on agent. Käytä samaa erillistä työpuuta, joka on kirjattu luovutustiedostoon. Älä toteuta muutoksia päätyöhakemistossa:

cd ../app-pricing-section
agent -p --trust --sandbox enabled --output-format text "$(cat <<'EOF'
Read AGENTS.md and docs/handoffs/2026-07-29-pricing-section.md.
Status must be implement or fixes.
Implement only the approved Design, respecting Review blocking resolutions.
Keep the patch small. Add or update tests from the Verification section.
Run the verification command and record the result in the handoff file.
Set status to impl-review and next owner to claude.
Do not merge.
EOF
)"

Cursorin komentorivin tärkeimmät valitsimet:

• -p / --print: ei-vuorovaikutteinen ajo, jolla on jo kirjoitus- ja komentotulkkityökalut käytössä
• --force / --yolo: hyväksyy komentotulkin komennot automaattisesti, ellei niitä ole estetty; käytä vain kertakäyttöisissä hiekkalaatikoissa, älä koodin kirjoittamisen oletuksena
• --sandbox enabled|disabled: ajon hiekkalaatikkotila; suosi arvoa enabled, kun toteutat valitsimella --trust
• --trust: merkitsee työtilan luotetuksi automaatiossa
• -w / --worktree [name]: erillinen työhakemisto polun ~/.cursor/worktrees/<repo>/ alla; polku poikkeaa komennolla git worktree add luodusta työpuusta, joten päivitä luovutuksen Branch- ja Worktree-kentät vastaamaan sitä
• --mode plan tai --mode ask: suunnittelu tai vain lukuoikeus
• --output-format text|json|stream-json

Käytä pelkkään tarkastukseen tarkoitetuissa Cursor-ajoissa ask- tai plan-tilaa tai yksiselitteistä ”älä muokkaa” -ohjetta. Luo työpuu mieluiten itse komennolla git worktree add, jotta luovutustiedoston polku vastaa toteuttajan työhakemistoa.

Katso automatisoituja työnkulkuja varten myös Cursorin headless CLI -ohje.

Ohjetiedostojen kartta: vältä ristiriitaiset ohjeet

Jos sääntö koskee jokaista agenttia, säilytä siitä yksi ensisijainen, työkalusta riippumaton versio ja käytä vain kunkin työkalun vaatimia yhdistäviä tiedostoja. Työkalukohtaiset säännöt pysyvät paikallisina. Saman käytännön kopioiminen useaan paikkaan lisää erilleen ajautumisen riskiä, joten testin kannattaa varmistaa, että jokainen työkalu lataa tarkoitetut säännöt.

Esimerkki koko työnkulusta

Lähtökohtana ovat puhdas koodivarasto ja uusi ominaisuus.

1. Luo erillinen työpuu

git fetch origin main
git worktree add -b feat/pricing-section ../app-pricing-section origin/main
cd ../app-pricing-section
mkdir -p docs/handoffs

Alusta luovutustiedosto Goal-, Non-goals- ja Verification-osioilla. Tallenna runko omana Git-committinaan, jos tiimisi haluaa sopimuksen näkyvän PR:ssä.

2. Codex suunnittelee

Codex kirjoittaa Design-osioon tiedostot, rajapinnat, testit ja riskit. Tilaksi tulee design-review.

Käytännöllinen suunnittelutulos voi olla tämän muotoinen:

## Design
Files:
- `src/components/marketing/PricingSection.tsx` (new)
- `src/components/marketing/PlanCard.tsx` (reuse)
- `tests/e2e/marketing-pricing.spec.ts` (new)

Boundaries:
- PricingSection owns layout and plan list
- PlanCard remains presentational
- CTA links use existing `trackEvent()` + `getCtaClickProps()` helpers

Test plan:
- three plans visible
- CTA hrefs resolve
- analytics helper called once per click

Risks:
- hardcoding plan IDs out of sync with CMS

3. Claude tarkastaa suunnitelman

Tarkastuskehote vaatii estävien ja ei-estävien löydösten erottelun, joten epämääräinen suunnitelma palautuu korjattavaksi. Esimerkki:

Blocking:
1. Pinottujen pakettikorttien mobiiliasettelua ei ole määritetty.
2. Design ei ilmoita varmennuskomentoa (lisää se Design- ja Verification-osioihin).
Non-blocking:
- Harkitse suunnitelmadatan vakion erottamista.

Tila palaa arvoon design tai etenee arvoon implement vasta, kun estävät kohdat on ratkaistu suunnitteluosiossa.

4. Cursor toteuttaa

Cursor toteuttaa vain hyväksytyn suunnitelman ja suorittaa seuraavan komennon:

pnpm test:e2e --grep "pricing"

Se kirjaa tuloksen, avaa tai valmistelee PR:n ja asettaa tilaksi impl-review.

5. Claude tarkastaa toteutuksen

Toinen Claude-ajo tarkastaa muutokset suhteessa luovutustiedostoon, ei juuri keksittyyn ihanneratkaisuun. Estävät löydökset asettavat tilaksi fixes ja omistajaksi cursor. Hyväksytty tarkastus asettaa tilaksi done, jonka jälkeen ihminen voi yhdistää muutokset.

6. Ihminen yhdistää muutokset

Suojatut haarat pysyvät ihmisen hallinnassa. Agentit voivat toimia nopeina nuorempina tiimiläisinä, mutta niiden ei pidä vastata julkaisuista.

Komentoriviohjaus ilman erillistä alustaa

Yksinkertainen vaiheistaja riittää:

#!/usr/bin/env bash
set -euo pipefail
ROOT="${1:?worktree path}"
HANDOFF="${2:?handoff file}"
cd "$ROOT"

status() {
  # Prefer the metadata Status field near the top of the handoff file.
  awk '/^- Status:/{print $3; exit}' "$HANDOFF"
}

case "$(status)" in
  design)
    codex exec --sandbox workspace-write "Read AGENTS.md and $HANDOFF. Fill Design only, then set status=design-review and next owner=claude. Do not implement application code."
    ;;
  design-review|impl-review)
    claude -p --permission-mode acceptEdits --max-turns 30 --max-budget-usd 5 --output-format text "Review $HANDOFF per AGENTS.md. Update Review + status only. Do not implement application code."
    ;;
  implement|fixes)
    agent -p --trust --sandbox enabled --output-format text "Status must be implement or fixes. Implement or fix per $HANDOFF and AGENTS.md. Update handoff. Do not merge."
    ;;
  done|blocked-human)
    echo "No agent action for $(status)"
    ;;
  *)
    echo "Unknown status in $HANDOFF" >&2
    exit 1
    ;;
esac

Ratkaisu on tarkoituksella yksinkertainen, koska sellaista on helppo selvittää virhetilanteissa. Rajaa hiekkalaatikko ja käyttöoikeudet kunkin vaiheen tarpeisiin. Suunnittelu ja tarkastus eivät tarvitse laajaa pääsyä järjestelmään.

Vikatilat

Ei-vuorovaikutteiset valitsimet, jotka hyväksyvät muokkaukset tai oikeudet automaattisesti, ovat hiekkalaatikoihin ja tarkasti rajattuihin työpuihin tarkoitettuja mukavuustyökaluja. Ne eivät muodosta tuotantoympäristön pääsynhallintaa.

Mitä ei vielä automatisoida

• Muutosten yhdistäminen suojattuihin haaroihin
• Tuotantojulkaisut
• Salaisuuksien kierto
• Tietokantaskeeman muutokset ilman ihmisen tarkastamaa suunnitelmaa
• Työnkulku, jossa luovutustiedosto tulee epäluotettavalta ulkoiselta lähettäjältä eikä sen sisältöä puhdisteta

Käytännön aloituspakkaus

1. Lisää juureen AGENTS.md, joka sisältää komennot, muutossäännöt ja moniagenttisen toimintamallin.
2. Lisää CLAUDE.md, joka sisältää @AGENTS.md.
3. Lisää docs/handoffs/_template.md.
4. Valitse yksi pieni ominaisuus.
5. Tee suunnittelu, tarkastus, toteutus ja toinen tarkastus kerran käsin.
6. Automatisoi tilojen vaiheistus komentorivillä vasta sen jälkeen.

Jos samojen agenttien pitää ottaa tehtäviä yrityksen yhteisestä työjonosta, lisää Linear MCP sekä tehtävien varaus- ja tarkastusmalli artikkelista moniagenttisen projektin hallinta Linearilla. Markdown-luovutus säilyy silti hyödyllisenä tehtäväkohtaisena teknisenä muistikirjana.

Standardi on sopimus

Codexin, Claude Coden ja Cursorin ominaisuudet ovat jo osittain päällekkäisiä. Niistä muodostuu tiimi, kun epämääräinen pyyntö ”työskennelkää yhdessä” korvataan näkyvällä sopimuksella:

• jaetut ohjeet
• yksiselitteinen rooli jokaista ajoa kohti
• tilan sisältävä Markdown-luovutus
• erilliset työpuut
• rajatut CLI-kutsut
• ihmisen vastuu muutosten yhdistämisestä ja julkaisusta

Tämä riittää vakavasti otettavan paikallisen agenttitiimin pyörittämiseen nykyisillä työkaluilla. Samalla huomaat nopeasti, milloin tiimi poikkeaa sovitusta toimintamallista ja alkaa improvisoida.