AGENTS.md: Cumraigh Treoracha do Stór
Ar an leathanach seo
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.mdatá 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.mdtreoracha 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.mdmar chód beo