Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

AGENTS.md: Cumraigh Treoracha do Stór

Ceacht 15 as 20 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Saineolas ar Chomhad Cumraíochta Codex
  2. Ordlathas AGENTS.md
  3. Na Rannáin a Dhéanann an Comhad
  4. Dhá Phatrún a Choscann Iontais
  5. An Comhad a Choinneáil Beo
  6. Príomhphointí

Nuashonraíodh an ceacht ar an 3 Samhain, 2026 bunaithe ar an leathanach Custom instructions with AGENTS.md: Ní léann Codex ach comhaid AGENTS.md atá suite idir fréamh an tionscadail agus an chomhadlann oibre reatha (chomh maith leis an gcomhad domhanda ag ~/.codex). Ní lódáiltear comhad i bhfo-chomhadlann lasmuigh den chonair seo, rud atá contrártha leis an méid a thug le tuiscint an leagan roimhe seo. Foinse: AGENTS.md.

Saineolas ar Chomhad Cumraíochta Codex

D’fhoghlaim tú faoi AGENTS.md i gCeacht 3. Anseo, déanaimid iniúchadh ar phatrúin chasta—ar an difríocht idir comhad maisiúil (trí líne scríofa ag am tosaithe agus dearmadta ina dhiaidh sin) agus ceann a stiúrann i ndáiríre iompar an ghníomhaire ar thionscadal beo.

Ordlathas AGENTS.md

Léann Codex na comhaid seo go hordlathach, ón gcoitinne go dtí an sonrach: ar dtús an comhad domhanda i do chomhadlann Codex (~/.codex/AGENTS.md, nó AGENTS.override.md má tá sé ann), agus ansin, ag tosú ó fhréamh an tionscadail, na comhaid sna comhadlanna a thrasnaítear síos go dtí an chomhadlann oibre reatha. Ar thionscadal struchtúrtha, dealraíonn an crann mar seo:

mon-projet/
  AGENTS.md                    → Rialacha domhanda (tosaíocht íseal)
  src/
    AGENTS.md                  → Rialacha don chód foinse go léir
    api/
      AGENTS.md                → Rialacha sonrach do APIanna
      routes/
        AGENTS.md              → Rialacha do bhealaí (routes)
    components/
      AGENTS.md                → Rialacha do chomhpháirteanna React
  tests/
    AGENTS.md                  → Rialacha do thástálacha

Carnaítear na rialacha: Déanann Codex comhcheangal ar na comhaid ón bhfréamh síos go dtí an chomhadlann reatha, agus sáraíonn na cinn is gaire don chomhadlann sin, a léitear go deireanach, treoracha ginearálta. Is pointe é a thuigtear go mícheart go minic: ní léitear ach comhadlanna ar an gconair idir an fhréamh agus an chomhadlann reatha. Má chuireann do chomhad fréimhe cosc ar any cé go gceadaíonn tests/AGENTS.md dearbhuithe níos scaoilte i mocks, ní bhaineann an lamháltas sin ach nuair a bheidh Codex ag obair ó tests/ nó ó cheann dá fho-chomhadlanna; má sheoltar é ón bhfréamh, ní léann sé tests/AGENTS.md. Oibríonn athbhreithniú cód GitHub go difriúil: Cuardaíonn Codex an stór iomlán le haghaidh comhaid AGENTS.md ann agus cuireann sé na rialacha athbhreithnithe (## Code Review Rules) ón gcomhad is gaire don chód i gceist i bhfeidhm. Stopann an comhcheangal ag 32 KiB de réir réamhshocraithe (project_doc_max_bytes): gearrtar comhad atá ró-fhada.

Na Rannáin a Dhéanann an Comhad

Tagann an comhthéacs ar dtús, toisc go gcruthaíonn sé gach cinneadh a leanas. Ní chódáiltear feidhmchlár SaaS atá faoi réir an GDPR (An Rialachán Ginearálta maidir le Cosaint Sonraí) ar an mbealach céanna le huirlis inmheánach do chúigear daoine:

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

Agus a fhios aige go láimhseálann sé sonraí atá faoi réir an GDPR, cuirfidh Codex na cosaintí expected leis gan ort iad a shonrú i ngach iarratas. Tagann na coinbhinsiúin ina dhiaidh sin, a fhreagraíonn ceist amháin: cén chuma atá ar chód ceart anseo?

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

Is é an rannán orduithe an ceann is minice a fhágtar ar lár, agus tá costas leis an easnamh sin: gan na horduithe seo, ní féidir le Codex a chuid oibre a fhíorú agus filleann sé cód nach ndearna sé riamh a fhorghníomhú ná a thástáil.

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

Is iad na rialacha docht an ráille cosanta. Nuair a fhrásaítear iad mar “NÁ DÉAN” agus “DÉAN I GCONAÍ”, coiscíonn siad earráidí a chosnaíonn oíche iomlán le deisiú: imirce Prisma a scriosadh agus a bheidh ort a athchruthú ón táirgeadh, rún a chuirtear in áirithe agus a theastaíonn a chúlghairm, nó innerHTML a shleamhnaítear isteach i gcomhpháirt a osclaíonn leochaileacht XSS.

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

Ar deireadh, déanann an ailtireacht cur síos ar an sreabha ceadaithe idir sraitheanna. Gan é seo, táirgeann Codex cód a oibríonn ach a ghiorraíonn do struchtúr—bealach a dhéanann ceist ar Prisma go díreach, mar shampla, toisc gurb é sin an conair is giorra.

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

Cuirtear treoracha sonracha do gach teicneolaíocht a úsáidtear leis seo, tionscadal ar thionscadal:

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

Dhá Phatrún a Choscann Iontais

Cuireann dearbhú na n-athróg timpeallachta expected cosc ar Codex ainmneacha eochracha a cheapadh nuair a scríobhann sé script, nó luach íogair a logáil go taismeach in ίarmharc díbhugála:

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

Réitíonn ainmniú do leabharlanna preferred, agus go háirithe iad siúd a dhiúltaíonn tú, fadhb athfhillteach: suiteálann an gníomhaire spleáchas atá bailí go hiomlán ann féin, ach a dhiúltaigh d’fhoireann dhá bhliain ó shin tar éis drochtaithí.

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

An Comhad a Choinneáil Beo

Éabhlóidíonn AGENTS.md le do chód, díreach cosúil le tástáil nó le README. Nuashonraigh é chomh luath agus a ghlacann tú le coinbhinsiún nua, a athraíonn tú leabharlanna nó frámaí oibre, agus go háirithe chomh luath agus a shainaithníonn tú earráid athfhillteach Codex: léiríonn an cás deireanach sin treoir in easnamh i gcónaí seachas teip mhúnla. Is fiú súil a choinneáil ar spreagadh ceathrú, níos mine—nuair a chuireann forbróir nua ceist ar cheart do AGENTS.md freagra a thabhairt uirthi, ba chóir an freagra sin a bheith sa chomhad.

Príomhphointí

  • Ceadaíonn ordlathas AGENTS.md treoracha atá níos sonraí de réir a chéile
  • Tá orduithe ríthábhachtach chun go bhféadfadh Codex a chuid oibre a fhíorú
  • Is iad na rialacha NÁ DÉAN an tábhachtaí chun earráidí a sheachaint
  • Doiciméadaigh spleáchais preferred chun drochroghanna a chosc
  • Coinnigh AGENTS.md mar chód beo