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

AGENTS.md: Määritä repositoriosi ohjeet

Oppitunti 15 / 20 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. AGENTS.md-määritystiedoston hallinta
  2. AGENTS.md-hierarkia
  3. Osiot, jotka tekevät tiedostosta toimivan
  4. Kaksi mallia, jotka estävät yllätykset
  5. Tiedoston pitäminen elävänä
  6. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 perustuen sivuun Custom instructions with AGENTS.md: Codex lukee vain AGENTS.md-tiedostoja, jotka sijaitsevat projektin juuren ja nykyisen työhakemiston välillä (sekä globaalin tiedoston kohdassa ~/.codex). Hakemistossa, joka on tämän polun ulkopuolella, olevaa tiedostoa ei ladata, toisin kuin edellinen versio antoi ymmärtää. Lähde: AGENTS.md.

AGENTS.md-määritystiedoston hallinta

Tutustuit AGENTS.md:ään oppitunnilla 3. Tässä syvennymme edistyneisiin malleihin – eroon koristetiedoston (kolme riviä, jotka kirjoitetaan käynnistyksen yhteydessä ja unohdetaan) ja tiedoston välillä, joka todella ohjaa agentin toimintaa elävässä projektissa.

AGENTS.md-hierarkia

Codex lukee nämä tiedostot hierarkkisesti yleisestä erityiseen: ensin globaali tiedosto Codex-kansiossasi (~/.codex/AGENTS.md, tai AGENTS.override.md, jos se on olemassa), sitten projektin juuresta alkaen hakemistot, joita traversoidaan alas nykyiseen työhakemistoon saakka. Jäsennellyssä projektissa puu näyttää tältä:

mon-projet/
  AGENTS.md                    → Globaalit säännöt (matala prioriteetti)
  src/
    AGENTS.md                  → Säännöt kaikelle lähdekoodille
    api/
      AGENTS.md                → Säännöt erityisesti API:lle
      routes/
        AGENTS.md              → Säännöt reiteille
    components/
      AGENTS.md                → Säännöt React-komponenteille
  tests/
    AGENTS.md                  → Säännöt testeille

Säännöt kertyvät: Codex liittää tiedostot yhteen juuresta nykyiseen hakemistoon saakka, ja hakemistoa lähimpänä olevat, viimeisenä luetut tiedostot ohittavat yleiset ohjeet. Yksi kohta on helppo ymmärtää väärin: vain hakemistot, jotka ovat polulla juuren ja nykyisen hakemiston välillä, luetaan. Jos juuritiedostosi kieltää any:n käytön, kun taas tests/AGENTS.md sallii löysemmät väitteet mockeissa, tämä toleranssi pätee vain, kun Codex työskentelee hakemistosta tests/ tai sen alihakemistosta; juuresta käynnistettynä se ei lue tiedostoa tests/AGENTS.md. GitHub-koodikatselmus toimii eri tavalla: Codex etsii koko repositoriosta AGENTS.md-tiedostoja ja soveltaa katselmussääntöjä (## Code Review Rules) kyseistä koodia lähimpänä olevasta tiedostosta. Yhdistäminen pysähtyy oletusarvoisesti 32 kt:n kohdalla (project_doc_max_bytes): liian pitkä tiedosto typistetään.

Osiot, jotka tekevät tiedostosta toimivan

Konteksti tulee ensin, koska se muokkaa jokaista seuraavaa päätöstä. GDPR:n (General Data Protection Regulation) alaista SaaS-sovellusta ei koodata samalla tavalla kuin viiden hengen sisäistä työkalua:

## Context
SaaS invoice management application for French SMEs.
GDPR compliance mandatory. Data hosted in France (OVH).
Stack: Astro 6, React, Strict TypeScript, Prisma, PostgreSQL.
Authentication: Better Auth with server sessions.

Kun Codex tietää käsittelevänsä GDPR:n alaisia tietoja, se lisää odotetut suojaukset ilman, että sinun tarvitsee määrittää niitä jokaisessa pyynnössä. Seuraavaksi tulevat käytännöt, jotka vastaavat yhteen kysymykseen: miltä oikea koodi näyttää täällä?

## Conventions
- Strict TypeScript (no any, no implicit any)
- Functional React components only
- Naming: kebab-case files, PascalCase components, 
  camelCase variables
- Imports: @/ for path aliases
- Validation: Zod for all user inputs
- Errors: custom error classes in src/lib/errors.ts
- Logging: use src/lib/logger.ts (no console.log)

Komennot-osio on useimmiten jätetty pois, ja sen puuttuminen on kallista: ilman näitä komentoja Codex ei voi varmistaa omaa työtään ja palauttaa koodia, jota se ei ole koskaan suorittanut tai testannut.

## Commands
- `npm run dev` — Development server (port 4321)
- `npm run build` — Production build
- `npm run test` — Vitest tests
- `npm run test:e2e` — Playwright tests
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Prisma migrations
- `npm run db:seed` — Database seed

Tiukat säännöt muodostavat kaiteen. Muotoiltuna sanoin “EI KOSKAAN” ja “AINA” ne estävät virheet, joiden korjaaminen maksaa koko illan: poistettu Prisma-migraatio, joka on rekonstruoitava tuotannosta, commitoitu salaisuus, joka pitää mitätöidä, tai komponenttiin lipsahtanut innerHTML, joka avaa XSS-haavoittuvuuden.

## Strict Rules (NEVER break these)
- NEVER modify the Prisma schema without creating a migration
- NEVER store secrets in code (use .env)
- NEVER use innerHTML (XSS risk)
- NEVER delete an existing Prisma migration
- NEVER expose internal IDs in public URLs
- ALWAYS validate user inputs with Zod
- ALWAYS use Prisma transactions for multi-table operations

Lopuksi arkkitehtuuri kuvaa kerrosten välisen sallitun virran. Ilman sitä Codex tuottaa koodia, joka toimii, mutta oikosulkee rakenteesi – esimerkiksi reitti, joka kysyy Prismaa suoraan, koska se oli lyhin polku.

## Architecture
Layers:
1. Routes (src/pages/) → receive requests
2. Services (src/services/) → business logic
3. Repositories (src/repositories/) → data access

Rule: Routes MUST NOT access Prisma directly.
Everything goes through a service, which goes through a repository.

Tähän lisätään projektikohtaisesti ohjeet, jotka koskevat kutakin käytettyä teknologiaa:

## React
- Prefer Server Components by default
- Client Components only when necessary (interactivity)
- No useEffect for data fetching (use Server Actions)
- Local state with useState, global state with Zustand

## Prisma
- Relations: always include required fields explicitly
- Pagination: use cursor-based, not offset-based
- Soft delete: use deletedAt instead of DELETE

Kaksi mallia, jotka estävät yllätykset

Odotettujen ympäristömuuttujien määrittäminen estää Codexia keksimästä avainten nimiä skriptiä kirjoittaessaan tai vahingossa lokittamasta arkaluonteista arvoa debug-jäljitykseen:

## Required Environment Variables
- DATABASE_URL — PostgreSQL connection URL
- AUTH_SECRET — Secret for Better Auth (min 32 chars)
- SMTP_HOST — SMTP server for emails
- STRIPE_SECRET_KEY — Stripe API key (never log)

Suosikkikirjastojen nimeäminen ja erityisesti niiden, jotka kiellät, ratkaisee toistuvan harmistuksen: agentti asentaa riippuvuuden, joka itsessään on täysin kelvollinen, mutta jonka tiimisi hylkäsi kaksi vuotta sitten huonojen kokemusten jälkeen.

## Dependencies
If you need:
- Validation → Zod (NOT Joi, NOT Yup)
- Dates → date-fns (NOT moment, NOT dayjs)
- HTTP client → ofetch (NOT axios)
- Tests → Vitest (NOT Jest)
- E2E → Playwright (NOT Cypress)

Tiedoston pitäminen elävänä

AGENTS.md kehittyy koodisi mukana, aivan kuten testi tai README. Päivitä se heti, kun otat käyttöön uuden käytännön, vaihdat kirjastoja tai kehyksiä, ja erityisesti heti, kun tunnistat toistuvan Codex-virheen: tämä viimeinen tapaus signaloi aina puuttuvaa ohjetta eikä mallin vikaa. Neljäs, hienovaraisempi laukaisin kannattaa pitää silmällä – kun uusi kehittäjä kysyy kysymyksen, johon AGENTS.md:n olisi pitänyt vastata, tuo vastaus kuuluu tiedostoon.

Keskeiset asiat

  • AGENTS.md:n hierarkia mahdollistaa yhä tarkemmat ohjeet
  • Komennot ovat kriittisiä, jotta Codex voi varmistaa työnsä
  • EI KOSKAAN -säännöt ovat tärkeimpiä virheiden välttämiseksi
  • Dokumentoi suositut riippuvuudet estääksesi huonot valinnat
  • Ylläpidä AGENTS.md:tä elävänä koodina