AGENTS.md dhe CLAUDE.md: Si të Shkruash një Skedar Konfigurimi që Agjenti Vërtet e Përdor

Të shkruash një skedar konfigurimi të mirë është lëvizja me leverazh më të lartë dhe përpjekje më të ulët në kodimin agjentic. E vendos kontekstin një herë dhe çdo sesion përfiton: agjenti ndalon të hamendësojë komandën tënde të testimit, ndalon të riformatojë sipas parazgjedhjeve të veta, ndalon të modifikojë direktorinë e vetme që i ke thënë të jetë jashtë kufijve. Kjo faqe është zanati konkret pas aftësisë AI-Native "kontekst & konfigurim" — një nga 17 aftësitë AI-native që vlerësojmë nëpër nivele. Mbajtja e kujtesës së qëndrueshme të projektit në CLAUDE.md / AGENTS.md është një sinjal përcaktues i Zhvilluesit Agjentic të Nivelit 3, ndaj ia vlen ta bësh mirë.

Ideja kryesore është e njëjtë në të gjitha mjetet, edhe pse mekanika ndryshon: një skedar konfigurimi mbart gjërat që agjenti nuk mund t'i nxjerrë vetë nga kodi. Modeli e njeh gjuhën tënde. Ai nuk di që testet tuaja kanë nevojë për një flamur specifik, që ke lëvizur nga një librari tre muaj më parë, ose që infra/ është i gjeneruar dhe nuk duhet të modifikohet kurrë me dorë. Ai boshllëk është ç'ka mbush skedari.

Panorama: një filozofi, shumë skedarë

Çdo agjent kryesor lexon një skedar konteksti projekti. Ata ndajnë një filozofi dhe ndryshojnë në emrin e skedarit dhe mekanikën e ngarkimit. Ja harta për 2026:

File	Tool(s)	Status
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20 tools	Standard i hapur ndër-mjet
CLAUDE.md	Claude Code	Formati nativ i Claude Code
GEMINI.md	Gemini CLI	Formati nativ i Gemini
.github/copilot-instructions.md	GitHub Copilot	Udhëzimet e repo-s për Copilot
.cursor/rules (formerly .cursorrules)	Cursor	Formati i rregullave të Cursor

Konkluzjoni: AGENTS.md është burimi i vetëm i të vërtetës në ngritje — një specifikikim i hapur që ~20 mjete tashmë e lexojnë. Kapja është se Claude Code nuk e lexon AGENTS.md nativisht; ai lexon vetëm CLAUDE.md. Kështu që modeli kanonik me një burim të vetëm të vërtetës është të mbash AGENTS.md kanonik dhe të bësh urë me Claude me një CLAUDE.md minimal që e importon:

@AGENTS.md

<!-- Claude-specific notes can go below -->

Edhe një lidhje simbolike funksionon (ln -s AGENTS.md CLAUDE.md), por në Windows prefero @import — lidhjet simbolike atje kërkojnë të drejta administratori. Tani mirëmban një skedar dhe të dy ekosistemet e lexojnë.

Çfarë të vendosësh konkretisht

Analiza e GitHub-it mbi 2,500 depo ("How to write a great AGENTS.md") zbuloi se konfigurimet që ndihmojnë matshëm agjentët ndajnë gjashtë seksione. Në renditje të përafërt sipas prioritetit:

1. Commands — vendos herët, me komandat ekzakte të ekzekutueshme dhe flamujt (npm test, npm run build, pytest -v), jo vetëm emrat e mjeteve. Ky është seksioni me ROI më të lartë: agjentët tashmë e dinë që ekziston pytest; ata nuk e dinë flamujt e kërkuar të projektit tënd. Vendose pranë majës.
2. Praktikat e testimit — si testoni, çfarë të ekzekutoni para commitit, pritshmëritë e mbulimit.
3. Struktura e projektit — ku jetojnë gjërat, që agjenti të ndalojë gjuetinë.
4. Stili i kodit — trego një fragment real kodi, jo tre paragrafë prose.
5. Rrjedha e Git — emërtimi i degëve, konvencionet e commitit, rregullat e PR.
6. Kufijtë — çfarë agjenti nuk duhet të prekë kurrë (direktoritë e gjeneruara, sekretet, kodin e shitësit, migrimet).

Vëre renditjen e leverazhit. "Commands me flamuj" është i pari për një arsye: është gjëja e vetme që modeli më me besueshmëri nuk mund ta hamendësojë dhe më shpesh e gabon. Nëse nuk shkruan asgjë tjetër mirë, shkruaj atë.

Përfshi / Përjashto: testi rresht-për-rresht

Dokumentet e memories të Anthropic tërheqin një linjë eksplicite me dy kolona. Përdore si filtër për çdo rresht që tundohesh të shtosh.

Përfshi	Përjashto
Komandat Bash që agjenti nuk mund t'i hamendësojë	Gjithçka të nxjerrshme nga kodi
Rregullat e stilit të kodit që ndryshojnë nga parazgjedhjet	Konvencionat standarde të gjuhës që modeli i njeh tashmë
Udhëzimet e testimit / test runner i preferuar	Dokumentacionin e detajuar të API (lidhe në vend)
Etiketa e repo-s (emërtimi i degëve, konvencionet e PR)	Informacionin që ndryshon shpesh
Vendimet arkitekturore specifike të projektit	Shpjegime dhe tutoriale të gjata
Specifikat e mjedisit dev (variabla mjedisore të kërkuara)	Përshkrimet skedar-për-skedar të kodit
Grackat jo të dukshme	Praktika të vetëkuptueshme si "shkruaj kod të pastër"

Ekziston një test që e rrëzon të gjithë tabelën në një zakon:

Testi për çdo rresht: "A do të shkaktonte heqja e këtij rreshti gabime te agjenti? Nëse jo, hiqe."

Kryeje këtë test në çdo rresht. "Përdor TypeScript" — agjenti mund t'i shohë skedarët .ts; hiqe. "Ekzekuto migrimet e bazës së të dhënave me npm run db:migrate, asnjëherë mos modifiko migrations/ me dorë" — ai nuk do ta kishte hamendësuar kurrë, dhe gabuari me të korrupton gjendjen; mba e.

Shkruaje në altitudinën e duhur

Udhëzimi i inxhinierisë kontekstuale të Anthropic i distil parimet e mira të autorimit në katër parime.

1. Specifika / verifikueshmëria. Shkruaj rregulla konkrete sa të mund t'i kontrollosh kundrejt daljes së agjentit. Udhëzimet e vagullta nuk mund të verifikohen, ndaj nuk mund të ndiqen me besueshmëri.

• "Përdor dhëmbëzim 2-hapësinor" — jo "Formato kodin siç duhet."
• "Ekzekuto npm test para commitit" — jo "Testo ndryshimet e tua."
• "Trajtuesit e API jetojnë në src/api/handlers/" — jo "Mbaj skedarët të organizuar."

2. Altitudina e duhur. Synon mes logjikës të ngurtë të koduar dhe dorëlëshimit të vagullt: "i mjaftueshëm specifik për të udhëhequr sjelljen, i mjaftueshëm fleksibël për të qenë një heuristikë e fortë." Shumë i ngurtë dhe thyhet me rastin e parë të skajit; shumë i lirshëm dhe nuk udhëzon asgjë.

3. Minimal-por-i-mjaftueshëm. Minimali nuk do të thotë i shkurtër. Do të thotë të japësh kontekst të mjaftueshëm paraprakisht që agjenti të mos duhet të hamendësojë ose ri-zbulojë — dhe asgjë përtej kësaj. Prit mbushësin, mbaj detajin bazë.

4. Struktura. Përdor seksione të etiketuara — krerë Markdown ose etiketa XML. Një skedar i skanushëm është skedar që agjenti (dhe kolegët tuaj) e analizojnë vërtet.

Mbaje të dobët

Arsyeja e vërtetë për të qëndruar të dobët është buxheti i token-it. Skedari i konfigurimit ngarkohet plotësisht në çdo sesion. Nuk merret sipas kërkesës; shtohet në fillim të kontekstit gjatë nisjes. Ndaj fryrja ka një kosto të drejtpërdrejtë, të matur: një CLAUDE.md i fryrë matshëm zvogëlon respektimin e udhëzimeve. Formulimi i Anthropic është i qartë — skedarë CLAUDE.md të fryrë bëjnë Claude të injorojë udhëzimet tuaja reale. Çdo rresht mbeturinash që shton i dobëson rreshtat e mirë.

Objektivat janë konkrete:

• Anthropic synon nën ~200 rreshta si objektiv të butë për CLAUDE.md.
• Codex zbaton një kufizim të ngurtë 32 KiB në AGENTS.md (project_doc_max_bytes); skedarët e mëdhenj priten, ndaj gjithçka përtej kufirit nuk ngarkohet pa zhurmë.

Dhe një kurth që vlen të emërohet: importet nuk kursejnë buxhet. Një skedar @i-importuar ende ngarkohet në kontekst gjatë nisjes — ke ndarë skedarin, jo zvogëluar gjurmën. Për të zvogëluar realisht çfarë ngarkohet në çdo sesion, transfero përmbajtjen e rëndësishme me kusht:

• Path-scoped rules për shqetësimet transversale që prekin shumë skedarë — ngarkohen vetëm kur agjenti punon në atë shteg.
• Skills për procedurat sipas kërkesës — ngarkohen vetëm kur thirren.
• Lidhjet për material referues të gjatë ose të detajuar — tregoji në vend se ta incorporosh.

Parimi është i njëjti me të cilin zbaton testi për çdo rresht, i aplikuar në nivelin e seksionit: nëse është relevant vetëm nganjëherë, nuk duhet të jetë në skedarin gjithnjë-ngarkues.

DESIGN.md: një konventë ekipi, jo një standard

Një DESIGN.md është aplikimi klasik i "mbaje konfigurimin të dobët, lidhe detajin." Është një dokument i veçantë dizajni/arkitekture — vendimet kryesore, modeli i domain-it, modelet arkitekturore, pse është ndërtuar kështu — që AGENTS.md yt @importon ose referenzon në vend se ta incorporojë. Kjo e mban konfigurimin gjithnjë-ngarkues të shkurtër ndërsa konteksti i thellë qëndron një hop larg.

Ji i sinqertë për statusin e tij, megjithatë: ndryshe nga AGENTS.md dhe CLAUDE.md, nuk ekziston asnjë burim primar që e vendos DESIGN.md si skedar standard të konfigurimit të agjentit. Është një konventë ekipi e fuqishme, jo një standard i dokumentuar. Përdore sepse funksionon për ekipin tënd, jo sepse e kërkon një specifikikim.

Shtrirja & hierarkia

Të dy ekosistemet i shtresojnë skedarët nga të gjerët tek specifikët, por zgjidhin precedencën ndryshe.

CLAUDE.md ka katër shtrirje, duke ngarkuar të gjerë → specifik:

1. Politika e menaxhuar — vendosur nga org-a / IT-ja juaj, zbatohet në të gjithë organizatën.
2. Përdoruesi — ~/.claude/CLAUDE.md, zbatohet në të gjitha projektet tuaja.
3. Projekti — ./CLAUDE.md, kontrolluar në git dhe ndarë me ekipin.
4. Lokal — ./CLAUDE.local.md, gitignoruar, për anashkalimet tuaja personale.

Në monorepos, skedarët e direktorisë prind ngarkohen automatikisht dhe skedarët e direktorisë fëmijë ngarkohen sipas kërkesës. Importet përdorin sintaksën @path/to/file (relative ose absolute), futen deri 4 hop thellë, dhe analizuesi anashkalon blloqut e kodit kështu që një shteg brenda një blloku të kufizuar nuk trajtohet si import.

AGENTS.md zgjidh sipas rregullit fituesi-më-i-afërt. Codex shëtit nga rrënja Git poshtë deri te direktoria juaj aktuale e punës dhe bashkëlidh skedarët që gjen, fillimisht me rrënjën. Meqë skedarët më të afërt shfaqen më vonë, ata anashkalojnë — fituesi është skedari më i afërt. Në një monorepo mban një AGENTS.md për paketë, dhe ai më afër kodit që modifikohet merr precedencën. Mbi të gjitha: një udhëzim eksplicit në chat anashkalon çdo skedar.

Dhe ura ndër-mjet e mëparshme i lidh të dy sistemet: mbaj AGENTS.md kanonik, shto një CLAUDE.md që bën @AGENTS.md, dhe hierarkia juaj ndahet nëpër mjete pa dublikim.

Këshillues, jo zbatues

Kjo është nuanca që të shpëton nga një ndjesi e rreme sigurie: këta skedarë janë kontekst këshillues, jo zbatim deterministik. Ata drejtojnë agjentin; nuk e lidhin.

Fjalët theksuese si IMPORTANT dhe YOU MUST përmirësojnë matshëm respektimin — por nuk e garantojnë. Për kërkesat që duhet të ndodhin çdo herë të vetme (ekzekuto formatuesin, blloko një commit që dështon testit, asnjëherë mos shkruaj në main), pengesën deterministe e ofrojnë hooks (në Claude Code), jo formulime më të forta në konfigurim.

Rregulli praktik: përdor konfigurimin për udhëzime dhe heuristika; arrij te hooks në momentin kur "agjenti zakonisht e bën këtë" nuk mjafton dhe duhet "agjenti gjithmonë e bën këtë."

Mirëmbaje si kod

Një skedar konfigurimi është një artefakt i gjallë, jo një shkrim i njëhershëm. Trajtoje si pjesën tjetër të repo-s.

• Fillo me /init. Lëri mjetin të gjenerojë një draft të parë nga kodi yt, pastaj rafino me dorë — versioni i gjeneruar është pikënisje, jo skedari i përfunduar.
• Rishiko kur gjërat shkojnë keq. Sa herë agjenti bën diçka të mençur, pyet veten nëse një rresht i munguar ose mashtrues në konfigurim e shkaktoi.
• Prit rregullisht. Ri-ekzekuto testin për çdo rresht në të gjithë skedarin. Rreshtat që ishin bazë tremujorin e kaluar mund të jenë pesë e tepërt tani.
• Testo ndryshimet me sjellje. Mos beso se një editim ndihmoi — vëzhgo nëse sjellja e agjentit ndryshoi vërtet. Nëse nuk mund ta shohësh ndryshimin, rreshti ndoshta nuk po punon.
• Kontrollo në git. Një konfigurim i ndarë, i kontrolluar me version do të thotë që i gjithë ekipi kontribuon dhe përfiton, dhe ndryshimet shfaqen në rishikim.

Zakoni më i vlefshëm është laku vetë-përmirësues: kur agjenti bën një gabim, shto një rregull të vetëm me një rresht që të mos përsërisë. Gjatë disa javësh ai lak konvergjoi konfigurimin tënd pikërisht tek grackat që projekti yt vërtet ka — asgjë më shumë, asgjë më pak.

Një AGENTS.md startuese

Ja një skelet real, gati për kopjim-ngjitje me të gjashtë seksionet me ROI të lartë të plotësuara me hapësinë mbajtëse realiste. Zëvendëso me specifikimet tuaja dhe fshi gjithçka që nuk e kalon testin për çdo rresht.

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

Për një burim të vetëm të vërtetës nëpër mjete, vendos një `CLAUDE.md` me një rresht pranë tij që përmban `@AGENTS.md`, dhe lidh shënimin tënd të thellë të arkitekturës (një `DESIGN.md`, ADR-të tuaja) në vend se t'i ngjitësh brenda.

## Ku të shkosh tjetër

Një skedar konfigurimi i dobët dhe specifik është një nga sjelljet konkrete që ndan zhvilluesit e asistuar nga AI nga ata vërtet AI-native. [Gjej nivelin tënd AI-native](/quiz) në tre minuta — klasifikon pikërisht këtë lloj zanati — dhe kur të jesh gati të lidhësh toolchain-in tënd, fillo nga [stack-u i rekomanduar i ProCoders](/stack).