Tinklaraštis

Kas yra AGENTS.md ir kaip susikurti savo failą per 30 minučių

Markdown

AGENTS.md formatas, palaikymas dirbtinio intelekto įrankiuose, paruoštas šablonas, taisyklės ir klaidos. Kaip suderinti AGENTS.md su CLAUDE.md ir kitais instrukcijų failais.

Skaityti visą straipsnį

Praktinė medžiaga apie „vibe coding“ ir darbą su agentais: Ailoot dokumentacija.

AGENTS.md vienoje pastraipoje

Svarbiausia mintis

AGENTS.md yra paprastas „Markdown“ failas projekto šaknyje, kuriame pateikiamos instrukcijos DI agentui: kaip įdiegti priklausomybes, kaip paleisti testus, kokio kodo stiliaus laikytis ir ko neliesti. Šis atviras formatas buvo sukurtas „OpenAI“ 2025 m. rugpjūtį, o tų pačių metų gruodį prisijungė prie „Linux Foundation“. Jį gali naudoti daug programavimo įrankių, tačiau failo aptikimas priklauso nuo kliento ir versijos: vieni AGENTS.md įkelia automatiškai, kitiems reikia aiškiai nustatyti failo vardą arba skaitymo kelią. Nuo 2.1.277 versijos (2026 m. rugsėjis) „Claude Code“ taip pat skaito AGENTS.md, jei projekte nėra CLAUDE.md. Jei CLAUDE.md yra, „Claude Code“ pagal numatytuosius nustatymus skaito tik šį failą, o AGENTS.md įtraukiamas eilute @AGENTS.md arba naudojant simbolinę nuorodą.

Toliau formatas aptariamas remiantis agents.md, „OpenAI Codex“ dokumentacija, „JetBrains Junie“, „Cursor Rules Docs“, „GitHub Copilot Coding Agent“ pakeitimų žurnalu ir „Linux Foundation“ pranešimu apie „Agentic AI Foundation“. Visi skaičiai ir funkcijos atitinka 2026 m. gegužės 30 d. būklę, o AGENTS.md palaikymas „Claude Code“ aprašomas pagal „Anthropic“ dokumentaciją, atnaujintą 2026 m. rugsėjo 24 d.

Jei neįsivaizduojate, kokių įrankių pilna rinkoje ir kam jiems reikia bendro failo, pirmiausia perskaitykite vadovą „Su kuo programuoti 2026 m.: 8 DI įrankiai nuo „Claude Code“ iki „Antigravity““. Šiame straipsnyje daugiausia dėmesio skiriama AGENTS.md formatui ir tam, kaip per 30 minučių susikurti savo failą.

Kas yra AGENTS.md ir iš kur jis atsirado?

Svarbiausia mintis

AGENTS.md yra atviras „Markdown“ failo formatas, kuriame patys rašote instrukcijas DI agentams. „OpenAI“ jį išleido 2025 m. rugpjūtį kartu su „Codex CLI“ ir iškart pakvietė prisidėti bendraautorius: „Cursor“, „Sourcegraph Amp“, „Google Jules“ ir „Factory“. Idėja paprasta: „nekuriame kiekvienam įrankiui nuosavo failo, o susitariame dėl vieno.“ 2025 m. gruodžio 9 d. AGENTS.md kartu su „Anthropic“ MCP ir „Block“ goose prisijungė prie „Linux Foundation“ kaip vienas iš trijų naujosios „Agentic AI Foundation“ steigiamųjų projektų. Tų pačių metų gruodį daugiau nei 60 000 „GitHub“ saugyklų jau turėjo AGENTS.md šakniniame kataloge.

Anksčiau kiekvienas DI įrankis turėjo atskirą taisyklių failą: „Anthropic“ turėjo CLAUDE.md, „Cursor“ – .cursorrules, „GitHub“ – .github/copilot-instructions.md, „Aider“ – .aider.conf.yml, o „JetBrains“ – .junie/guidelines.md. Jei jūsų komanda naudojo tris skirtingus agentus, reikėjo trijų lygiagrečių failų su tuo pačiu turiniu, kurie per savaitę imdavo skirtis.

Pirmoji nuo to pavargo „OpenAI“. 2025 m. rugpjūtį ji išleido „Codex CLI“ ir kartu pristatė atvirą formatą agents.md. Svetainėje rašoma:

„Galvokite apie AGENTS.md kaip apie agentams skirtą README.“

(agents.md, išversta iš anglų kalbos)

Svarbiausia tai, kad AGENTS.md papildo README. README rašomas žmonėms: „kas tai per projektas, kaip jį paleisti vietoje, kaip prisidėti.“ AGENTS.md rašomas agentui: tikslios apvalkalo komandos, patikrinami „baigta“ kriterijai ir ribos, pavyzdžiui, „niekada neliesk šito“.

Svetainėje rašoma:

„AGENTS.md papildo README: jame pateikiamas papildomas, kartais išsamus kontekstas, kurio reikia agentui – kūrimo žingsniai, testai ir susitarimai, kurie užgriozdintų README arba tiesiog nereikalingi žmonėms, prisidedantiems prie projekto.“

(agents.md, išversta iš anglų kalbos)

Iki 2025 m. rugsėjo „GitHub Copilot Coding Agent“ jau palaikė šį formatą (pakeitimų žurnalas, 2025-08-28). Iki gruodžio prie jo prisijungė „Cursor“, „Junie“, „Gemini CLI“, „Aider“ ir dar keliolika įrankių. 2025 m. gruodžio 9 d. „Linux Foundation“ įsteigė „Agentic AI Foundation“ (AAIF): trys jos steigiamieji projektai buvo „OpenAI“ AGENTS.md, „Anthropic“ MCP ir „Block“ goose. Steigėjai buvo AWS, „Anthropic“, „Block“, „Bloomberg“, „Cloudflare“, „Google“, „Microsoft“ ir „OpenAI“. Iki 2026 m. vasario 24 d. fondas jau vienijo 146 organizacijas, tarp jų „Red Hat“, „ServiceNow“, „Akamai“, „Lenovo“, „JPMorgan Chase“, „Huawei“, „UiPath“ ir „Hitachi“.

Nuo tada AGENTS.md nebebuvo „dar vienas „OpenAI“ dalykas“ ir tapo de facto standartu.

Kurie DI agentai skaito AGENTS.md, o kurie – ne?

Svarbiausia mintis

AGENTS.md naudojamas daugelyje programavimo įrankių, įskaitant toliau išvardytus klientus. Lentelę laikykite įkėlimo būdų apžvalga, o ne vienodo natyviojo palaikymo pažadu: automatinis aptikimas, aiški konfigūracija, failų vardų pirmenybė ir įdėtųjų failų apdorojimas gali skirtis. „Anthropic“ „Claude Code“ ilgą laiką buvo išimtis: palaikymo prašymas Nr. 6235 liko atviras nuo 2025 m. rugpjūčio iki 2026 m. rugpjūčio. Nuo 2.1.277 versijos (2026 m. rugsėjo 18 d.) „Claude Code“ pats skaito AGENTS.md, jei projekte nėra CLAUDE.md. Jei CLAUDE.md yra, pagal numatytuosius nustatymus skaitomas tik jis, o AGENTS.md įtraukiamas eilute @AGENTS.md pačiame CLAUDE.md arba naudojant simbolinę nuorodą.

Palaikymo lentelės duomenys pateikti 2026 m. gegužės 30 d.; „Claude Code“ eilutė atnaujinta 2026 m. rugsėjo 24 d.:

ĮrankisSkaito AGENTS.mdData / šaltinis
„OpenAI Codex CLI“Taip (vietinis formatas)2025 m. rugpjūtis, agents.md
„GitHub Copilot Coding Agent“Taip2025-08-28, „GitHub Changelog“
„Cursor“Taip, šaknyje ir įdėtuose kataloguose„Cursor Rules Docs“
„JetBrains Junie“Taip, projekto ir visuotiniame ~/.junie/AGENTS.md„Junie Docs“
„Gemini CLI“ („Google“)Taip, per .gemini/settings.json, naudojant fileName: AGENTS.mdagents.md
Jules („Google“)Taip, standarto bendraautorius2025 m. rugpjūtis
„Sourcegraph Amp“Taip, standarto bendraautorius2025 m. rugpjūtis
„Aider“Taip, per read: AGENTS.md faile .aider.conf.ymlagents.md
„Factory“Taip, standarto bendraautorius2025 m. rugpjūtis
„OpenCode“Taip—
„Zed“Taipagents.md
„Warp“Taipagents.md
„VS Code“Taipagents.md
„Windsurf“Taip—
„Devin“ („Cognition“)Taip, per „Spec Kit Skills“2026 m. balandis
„RooCode“, „Kilo Code“, „Augment Code“Taipagents.md
„Claude Code“ („Anthropic“)Taip, jei projekte nėra CLAUDE.mdNuo 2.1.277 versijos (2026-09-18), „Claude Code“ dokumentacija

„Anthropic“ buvo paskutinė iš didžiųjų žaidėjų, prisijungusi prie šios iniciatyvos. 2025 m. rugpjūtį oficialioje saugykloje anthropics/claude-code buvo atidarytas prašymas Nr. 6235, kuriame prašyta palaikyti AGENTS.md.

Prašymas liko atviras beveik metus ir buvo uždarytas 2026 m. rugpjūčio 17 d.; 2.1.277 versija su AGENTS.md palaikymu išleista rugsėjo 18 d. „Anthropic“ logika tokia: CLAUDE.md turi pirmenybę, o AGENTS.md skaitomas tik tada, kai darbiniame kataloge arba bet kuriame jo tėviniame kataloge nėra CLAUDE.md. Pagal dokumentaciją, tai veikia taip:

Kas yra projekteKą skaito „Claude Code“
Tik AGENTS.mdAGENTS.md
AGENTS.md ir CLAUDE.md (arba CLAUDE.local.md)Tik CLAUDE.md
CLAUDE.md su eilute @AGENTS.mdCLAUDE.md, į kurį įtrauktas AGENTS.md

Ypatybė ta, kad asmeninis CLAUDE.local.md taip pat įskaitomas, todėl „Claude Code“ nustoja skaityti AGENTS.md. Šią elgseną galima pakeisti skiltyje „Project instructions“, esančioje /config, pavyzdžiui, kad „Claude Code“ vienu metu skaitytų abu failus. Senesnės nei 2.1.277 versijos automatiškai neaptinka AGENTS.md; eilutė @AGENTS.md faile CLAUDE.md vis dar yra sprendimas.

Kuo AGENTS.md skiriasi nuo CLAUDE.md ir .cursorrules?

Svarbiausia mintis

Techniškai šie formatai niekuo ypatingi: visi keturi (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md) yra įprasti „Markdown“ failai su instrukcijomis agentui. Skiriasi tai, kas juos skaito ir kur jie laikomi. AGENTS.md gali saugoti keliems klientams bendras instrukcijas, o kiekvieno kliento aptikimo ar įkėlimo konfigūracija tvarkoma atskirai. CLAUDE.md skirtas tik „Claude Code“, bet suteikia prieigą prie pažangių funkcijų: taisyklių pagal failų kelius, CLAUDE.local.md asmeniniams pakeitimams, @import kitų failų įtraukimui ir projekto, naudotojo bei vietinių nustatymų hierarchijai. .cursorrules „Cursor“ sistemoje pasenęs – naujoji sistema naudoja .cursor/rules/*.mdc ir automatiškai pritaiko taisykles pagal failo tipą. .github/copilot-instructions.md reikalingas tik internetiniam „Copilot“.

Keturių formatų palyginimas pagal 2026 m. gegužės 30 d. duomenis:

FormatasKas jį skaitoKur laikomasPrivalumasTrūkumas
AGENTS.mdKeli klientai su savo aptikimu ar konfigūracijaSaugyklos šaknis ir poaplankiai pagal kliento taisyklesBendros instrukcijos, nepriklausomos nuo vieno tiekėjoAptikimas, pirmenybė ir asmeninės taisyklės priklauso nuo kliento
CLAUDE.mdTik „Claude Code“Šaknis + ~/.claude/CLAUDE.md + CLAUDE.local.mdHierarchija, taisyklės pagal failų kelius, @import, įgūdžiai, kabliukaiTik „Claude“. Neveiks „Cursor“, „Codex“ ar „Copilot“
.cursor/rules/*.mdcTik „Cursor“.cursor/rules/<rule>.mdcAutomatinis pritaikymas pagal failo tipą (TS, „Python“, konkretūs keliai)Tik „Cursor“, nestandartinė .mdc sintaksė
.github/copilot-instructions.md„GitHub Copilot“ (internete ir klasikinis).github/Tiesiogiai veikia naršyklėje, GitHub.comTik „Copilot“, dubliuoja AGENTS.md

Esminė mintis: AGENTS.md sprendžia „vieno failo visiems agentams“ problemą, bet ne „asmeninių nustatymų, kurių neįrašau į saugyklą“ problemą. „Claude Code“ tam turi CLAUDE.local.md, o „Cursor“ – naudotojo vietinius .mdc failus. Vien AGENTS.md tokios galimybės nesuteikia – jį reikia derinti su kitais failais arba komandoje susitarti asmenines taisykles rašyti į „gitignore“ įtrauktas skiltis.

Kitas svarbus aspektas – monolitinės saugyklos. „Codex“ ir „Cursor“ taiko taisyklę „laimi artimiausias AGENTS.md“:

„Monolitinėje saugykloje kiekviename pakete įdėkite atskirą AGENTS.md. Agentai automatiškai skaito artimiausią failą katalogų medyje ir laimi artimiausias.“

(agents.md, išversta iš anglų kalbos)

agents.md nurodo, kad pagrindinėje „OpenAI“ monolitinėje saugykloje yra 88 AGENTS.md failai skirtingiems poapankiams. Jei dirbate monolitinėje saugykloje, paskirstykite taisykles pagal lygius: bendras taisykles laikykite šaknyje, o konkrečias – poaplankiuose.

Kas turėtų būti gerame AGENTS.md?

Svarbiausia mintis

Gero AGENTS.md struktūrą sudaro 8 skyriai, randami daugumoje populiarių failų: projekto apžvalga, paruošimo komandos, kodo stilius, kūrimo aplinkos patarimai, testavimo instrukcijos, PR gairės, saugumo aspektai ir ribos (ko nedaryti). Visa kita neprivaloma. Pagrindinė taisyklė: kiekvienas punktas turi būti tiksli komanda arba konkretus pavyzdys, o ne bendra idėja, pavyzdžiui, „rašykite tvarkingą kodą“.

agents.md svetainėje siūlomas lankstus formatas – „bet koks „Markdown““. Tačiau 80% gerų realių failų turi tuos pačius aštuonis skyrius. Pagrindinė taisyklė: kiekvienas punktas turi būti tiksli komanda arba konkretus pavyzdys. Agentas ignoruos abstrakčią idėją, tokią kaip „rašykite tvarkingą kodą“.

  1. Projekto apžvalga – 2–3 eilutės. Kas tai per projektas, kam jis skirtas ir koks jo pagrindinis tikslas. Be rinkodaros. Pavyzdys: „„Telegram“ robotas, skirtas mokamo praktinio seminaro dalyvių įvedimui. Technologijos: Next.js 14, Prisma, PostgreSQL. Paleidžiamas, kai purchases sukuriamas naujas įrašas.“
  2. Paruošimo komandos – tikslios apvalkalo komandos, skirtos darbui vietoje. npm install, npm run dev, npm run build. Jokio „paprastai darome taip“.
  3. Kodo stilius ir susitarimai – konkrečios taisyklės su pavyzdžiu, o ne „rašyk tvarkingai“. Pavyzdžiui: „Griežtas „TypeScript“, viengubos kabutės, be numatytųjų eksportų, komponentų pavadinimai „PascalCase“, kabliukai prasideda use.“
  4. Kūrimo aplinkos patarimai – kur laikomi svarbūs dalykai. Kokių kintamųjų reikia faile .env, kur laikomos paslaptys, kokie prievadai naudojami ir kaip dirbti su vietine DB.
  5. Testavimo instrukcijos – kaip paleisti konkretų testą ir kas laikoma sėkme. Pavyzdžiui: npm test -- --testPathPattern=user-auth; tikimasi 100% sėkmingų testų.
  6. PR ir įsipareigojimų gairės – įsipareigojimo pranešimo formatas, kontrolinis sąrašas prieš PR (testai, linteris, dokumentacija) ir kas patvirtina.
  7. Saugumo aspektai – ko niekada negalima daryti. „Niekada neįrašykite .env į saugyklą. Paslaptys laikomos tik „Vault“. Nerodykite naudotojų asmens duomenų žurnaluose.“
  8. Ribos / niekada taip nedarykite – draudimai ir alternatyvos. „Nenaudokite git push --force šakoje main. Jei reikia atšaukti pakeitimus, naudokite git revert arba git reset funkcijos šakoje.“

Kiekviename skyriuje vadovaukitės principu „komanda vietoj idėjos“. Agentas ignoruos „atsargiai atlikite migracijas“. Jis laikysis nurodymo „Prieš alembic upgrade head paleiskite alembic check. Jei rodoma klaida, netaikykite migracijos – paklauskite manęs.“

Paruoštas naudoti AGENTS.md šablonas (kopijuokite ir pritaikykite)

Svarbiausia mintis

Toliau pateikiamas pradinio AGENTS.md šablonas tipiniam žiniatinklio projektui. Nukopijuokite jį į saugyklos šakninį katalogą, pakeiskite <project-name>, <stack>, tikslias komandas ir pašalinkite nereikalingus skyrius. Pritaikymas trunka 20–30 minučių, o jei tai darote pirmą kartą – ilgiau.

# AGENTS.md

## Projekto apžvalga

<project-name> - <viena frazė, apibūdinanti jo paskirtį>.
Technologijos: <Next.js / Python / Go / ...>.
Pagrindiniai objektai: <naudotojai, užsakymai, įrašai ...>.
Informacija žmonėms pateikiama faile README.md.

## Paruošimo komandos

```bash
# pirmasis įdiegimas
npm install
cp .env.example .env  # tada užpildykite rankiniu būdu; sąrašas pateiktas toliau

# paleidimas
npm run dev           # kūrimo serveris prievade :3000
npm run build         # produkcinis kūrimas
npm run start         # paleisti produkcinį kūrinį
```

## Kūrimo aplinka

- Node 20+ (per nvm: `nvm use 20`)
- PostgreSQL 16 vietoje, prievade :5432 (`docker-compose up postgres`)
- Redis pasirenkamas, reikalingas tik eilėms (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Niekada neskaitykite viso `.env` failo. Jei reikia vieno kintamojo: `grep "^VAR=" .env`

## Kodo stilius

- Griežtas „TypeScript“ režimas
- Viengubos kabutės, be kabliataškių (nebent jų reikalauja ESLint)
- Importai: pirmiausia išoriniai, tada vidiniai per `@/`, galiausiai santykiniai
- Komponentai „PascalCase“ stiliumi; kabliukų pavadinimai prasideda `use`
- Nenaudokite `any` be aiškaus komentaro, paaiškinančio, „kodėl tipo nurodyti negalima“

Gero modulio pavyzdys:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testavimas

```bash
npm test                                # visi testai
npm test -- --testPathPattern=auth      # tik autentifikavimo testai
npm test -- --watch                     # stebėjimo režimas
```

Prieš įrašant pakeitimus visų testų rezultatai turi būti sėkmingi (žali). Jei testas nepraeina, neatlikite įrašo – paklauskite manęs, ką daryti.

## Užklausų dėl pakeitimų gairės

- Įsipareigojimo formatas: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Prieš PR: `npm run build && npm test && npm run lint`
- PR aprašyme nurodykite, kas keičiama, kodėl ir kaip tai išbandyti
- Netvirtinkite savo PR – visada palaukite žmogaus peržiūros

## Saugumas

- Paslaptys laikomos tik `.env` ir „Vault“, niekada kode
- Nerašykite asmens duomenų į žurnalus (el. pašto, telefono, vardo)
- Dirbdami su produkcine DB naudokite tik skaitymo užklausas, nebent būtų aiškiai leista kitaip
- Testuose nekoduokite išorinių paslaugų API raktų („Stripe“, „OpenAI“)

## Niekada taip nedarykite

- Nenaudokite `git push --force` šakoje main. Jei reikia atšaukti pakeitimus, naudokite `git revert` arba atidarykite naują PR
- Nepaleiskite DB migracijų be `alembic check` (arba atitinkamos jūsų ORM komandos)
- Nenaudokite `npm install -g` arba `sudo` projekto priklausomybėms diegti
- Be leidimo nepridėkite priklausomybių (ypač sunkių: „webpack“ įskiepių, ORM)

Šabloną vidutiniškai sudaro 80–120 eilučių. Jei failas ilgesnis nei 150 eilučių, verta jį pertvarkyti: perkelti dalį turinio į docs/, pateikti nuorodą arba sutrumpinti iki vienos eilutės. Praktikoje geriausiai veikia 100–150 eilučių failai; peržengus šią ribą kokybės rodikliai ima prastėti.

Kokios 5 taisyklės daro AGENTS.md tikrai naudingą?

Svarbiausia mintis

Geras AGENTS.md laikosi penkių taisyklių: komandos vietoj idėjų, draudimai su alternatyvomis, tik vienas tiesos šaltinis, patikrinami užbaigimo kriterijai ir trumpesnis nei 150 eilučių failas.

  1. Komandos vietoj idėjų. Agentas nesupranta „atsargiai atlikite migracijas“. Jis laikysis alembic check prieš alembic upgrade head. Agentai veikia pagal komandas ir sąlygas, o ne nuotaikas. Visas pagrindines taisykles formuluokite taip: „daryk X, kitu atveju Y“.

  2. Draudimai su alternatyva. Agentas tyliai ignoruos paprastą „nenaudok priverstinio siuntimo“ po dviejų ar trijų užklausų. Veikia pora „nedaryk X, vietoj to daryk Y“. Pavyzdys: „nenaudokite git push --force šakoje main; jei reikia atšaukti pakeitimus, naudokite git revert arba atidarykite naują PR“.

  3. Tik vienas tiesos šaltinis. Pagrindinis AGENTS.md yra viso projekto tiesos šaltinis. Monolitinėje saugykloje naudokite įdėtuosius AGENTS.md poaplankiuose ir laikykitės taisyklės „laimi artimiausias“. Nelaikykite lygiagrečių failų su prieštaraujančiomis instrukcijomis.

  4. Patikrinami „baigta“ kriterijai. „Testai turi praeiti“ yra nenaudinga. Tikslus kriterijus: npm test grąžina išėjimo kodą 0 ir stdout neišveda FAIL. „Kodas turi būti tvarkingas“ taip pat nenaudinga. Tikslus kriterijus: npm run lint įvykdomas be įspėjimų. Agentas supranta, ką reiškia „baigta“, tik tada, kai aiškiai aprašote sąlygą.

  5. Trumpesnis nei 150 eilučių failas. Peržengus 150 eilučių, rodikliai ima prastėti: agentas sugaišta daugiau konteksto skaitydamas failą ir praleidžia svarbias taisykles. Jei viskas netelpa, perkelkite detales į docs/architecture.md ir pateikite nuorodą į šį failą iš AGENTS.md, palikdami jame tik komandas ir ribas.

Kokios 10 klaidų AGENTS.md paverčia šiukšle?

Svarbiausia mintis

Pagrindinė priežastis, kodėl AGENTS.md neveikia, – neaiškios formuluotės. Daugiau nei 2 500 saugyklų tyrime „GitHub Blog“ parodė, kad dauguma failų nepasiteisina, nes parašyti pernelyg bendrai. Pavyzdžiui, „Esate paslaugus programavimo asistentas“ agentui nesuteikia visiškai jokios naudingos informacijos. Toliau pateikiama 10 dažnų klaidų, būdingų prastiems failams: README dubliavimas, nesustruktūruotas tekstas, daugiau nei 30 draudimų be alternatyvų, prieštaringi prioritetai, įrašytos paslaptys, pasenusi dokumentacija ir paprastoms užduotims per sudėtinga architektūra.

  1. Neaiškios taisyklės be komandų. Agentas ignoruos „atsargiai atlikite migracijas“ – šis sakinys jam tuščias. Veikia tik konkreti komanda su sąlyga: „Prieš alembic upgrade head paleiskite alembic check. Jei rodoma klaida, netaikykite migracijos – paklauskite manęs.“

  2. „Tvarkingas kodas.“ Nenaudinga frazė. Pakeiskite ją konkrečiu šablonu: „Naudokite funkcinius komponentus su kabliukais. Pavyzdys: function LoginForm() { const [email, setEmail] = useState(''); ... }“

  3. Nesustruktūruotas tekstas. Jei AGENTS.md sudaro 300 eilučių teksto be antraščių, agentas sugaiš 80K konteksto žetonų nereikšmingoms ištraukoms ir praleis tai, kas svarbu. Naudokite H2/H3 antraštes, trumpus skyrius ir punktų sąrašus.

  4. Daugiau nei 150 eilučių turintis failas. Peržengus šią ribą kokybės rodikliai prastėja. Padalykite turinį į pagrindinį failą ir nuorodas į detales docs/ kataloge.

  5. Daugiau nei 30 draudimų be alternatyvų. Jei faile ilgas sąrašas „nedaryk X, nedaryk Y“, bet nepasakyta „vietoj to daryk Z“, agentas klaidžios nežinodamas, ką daryti.

  6. README.md dubliavimas. Jei README jau aprašyta, kaip įdiegti ir paleisti projektą, nekopijuokite šios informacijos į AGENTS.md. Vietoj to vienoje eilutėje pateikite nuorodą į README ir aprašykite, ko reikia agentui, bet nereikia prie projekto prisidedantiems žmonėms.

  7. Paslapčių įrašymas į failą. AGENTS.md gali būti viešas (jis yra „git“ saugykloje). Jame neturi būti tikrų API raktų, žetonų ar slaptažodžių. Pateikite tik nuorodas į paslapčių saugyklas: „Žr. „Vault“: secret/staging/db.“

  8. Prieštaringi prioritetai be eiliškumo. „Veikite greitai“ ir „išlaikykite 90% testų aprėptį“ nepadeda agentui pasirinkti. Aiškiai nustatykite eiliškumą: „Pirmiausia testų aprėptis ≥80%, tada greitis. Jei jie prieštarauja, pirmenybė teikiama testams.“

  9. Pasenusi dokumentacija. Architektūros aprašyme nurodyta REST ir apklausa, nors iš tikrųjų jau naudojami „WebSockets“. Agentas vadovausis pasenusiu aprašu ir sugadins architektūrą. Taisyklė: atnaujinkite AGENTS.md tame pačiame PR kaip ir kodą, kai pasikeičia architektūra.

  10. Per sudėtinga architektūra paprastai užduočiai. Jei paprašyta pakeisti dvi konfigūracijos eilutes, agentui nereikia skaityti visos 14 mikropaslaugų topologijos. Išsamią architektūrą perkelkite į docs/architecture.md; AGENTS.md palikite tik „jei užduotis susijusi su architektūra, skaitykite docs/architecture.md“.

„GitHub Blog“ tyrime, apėmusiame daugiau nei 2 500 AGENTS.md saugyklų, pateikiama pagrindinė išvada:

„Dauguma agentų failų neveikia, nes yra pernelyg bendri. „Esate paslaugus programavimo asistentas“ neveikia.“

(„GitHub Blog“, išversta iš anglų kalbos)

Kaip vienoje saugykloje laikyti AGENTS.md ir CLAUDE.md?

Svarbiausia mintis

Galimi trys scenarijai: (1) naudojate tik „Claude Code“ – palikite CLAUDE.md; AGENTS.md nereikia. (2) naudojate tik ne „Claude“ įrankius („Codex“, „Cursor“, „Copilot“, „Junie“) – naudokite AGENTS.md kaip vienintelį tiesos šaltinį. (3) mišri komanda naudoja „Claude Code“ ir kitus įrankius – pagrindiniu failu laikykite AGENTS.md. Jei neturite atskirų taisyklių „Claude“, CLAUDE.md galite praleisti: nuo 2.1.277 versijos „Claude Code“ pats skaito AGENTS.md. Jei turite atskirų taisyklių, susiekite AGENTS.md su CLAUDE.md simboline nuoroda arba @AGENTS.md importu. macOS ir Linux pervadinkite tik kai AGENTS.md nėra. Jei abu failai jau yra, pirmiausia išsaugokite ir sujunkite jų taisykles, tada naudokite trumpą CLAUDE.md su @AGENTS.md; niekada neperrašykite esamo AGENTS.md. „Windows“ sistemoje simbolinėms nuorodoms reikia „Developer Mode“, todėl paprasčiau naudoti importą.

Pagrindinis praktinis klausimas – kaip naudoti abu failus nedubliuojant turinio. Galimi trys scenarijai:

1 scenarijus: tik „Claude Code“. Palikite CLAUDE.md ir naudokite visas „Claude Code“ funkcijas: ~/.claude/CLAUDE.md naudotojo lygio instrukcijoms, CLAUDE.md projektui, CLAUDE.local.md asmeniniams pakeitimams, @import kitiems failams įtraukti ir .claude/skills/ specializuotiems įgūdžiams. AGENTS.md nereikia.

2 scenarijus: keli programavimo klientai. Bendras taisykles laikykite AGENTS.md, tada kiekvieną klientą prijunkite ir patikrinkite atskirai. „Gemini CLI“ leidžia nustatyti konteksto failo vardą, o „Aider“ gali įkelti failą per skaitymo konfigūraciją. Tai aiškiai nustatyti įkėlimo būdai, o ne vienodas automatinis aptikimas.

Įkėlimo būdasKą patikrinti
Automatinis AGENTS.md aptikimasĮdiegtos kliento versijos dokumentuotas šakninio katalogo, įdėtųjų failų ir pirmenybės taisykles
Aiški konfigūracija, pavyzdžiui, „Gemini CLI“ ar „Aider“Nustatytą failo vardą ar skaitymo kelią ir kliento įkelto konteksto rodinį
Sąlyginis įkėlimas ar importas „Claude Code“Įdiegtą versiją ir failų pirmenybę; žr. atskirą AGENTS.md naudojimo „Claude Code“ vadovą

Pradėkite naują sesiją nepavojingoje bandomojoje saugykloje, pridėkite unikalią nepavojingą instrukciją, pavyzdžiui, „bandomajame atsakyme įtrauk žymą instructions-loaded“, ir patikrinkite ne tik atsakymą, bet ir kliento dokumentuotą įkeltų failų rodinį ar žurnalus. Pakartokite su kiekvienu iš tikrųjų naudojamu klientu ir jo versija. Sugeneruotas teiginys, kad failas perskaitytas, nėra nepriklausomas įkėlimo įrodymas; vienas sėkmingas bandymas nepatvirtina palaikymo visuose kituose įrankiuose.

3 scenarijus: mišri komanda („Claude Code“ ir kiti). Tai dažniausias 2026 m. variantas. Sprendimas – pagrindiniu failu laikyti AGENTS.md. Jei neturite specialių „Claude Code“ taisyklių, apskritai nekurkite CLAUDE.md: nuo 2.1.277 versijos „Claude Code“ skaito AGENTS.md, kai projekte nėra CLAUDE.md. Jei tokių taisyklių turite, sukurkite CLAUDE.md kaip simbolinę nuorodą arba trumpą failą su @AGENTS.md importu.

Prieš keisdami kurį nors failą peržiūrėkite ir nukopijuokite abu. Jei abu yra, bendras neprieštaraujančias instrukcijas sujunkite į AGENTS.md, o Claude skirtas palikite CLAUDE.md su @AGENTS.md importu. Esamas simbolines nuorodas išlaikykite, o ne pakeiskite.

Įprastam CLAUDE.md tik kai AGENTS.md nėra ši macOS/Linux apsauga atsisako perrašyti esamą tikslą ar simbolinę nuorodą:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

Po sėkmingo pervadinimo CLAUDE.md yra simbolinė nuoroda į AGENTS.md.

„Windows“ sistemoje simbolinei nuorodai sukurti reikia „Developer Mode“ (arba administratoriaus teisių), o tai gali būti nepatogu visai komandai. Alternatyva – trumpas CLAUDE.md failas, kuriame importuojamas AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Tik „Claude Code“ skirtos instrukcijos

- Specializuotiems nurodymams naudokite .claude/skills/
- Dirbdami su Skills peržiūrėkite .claude/skills/INDEX.md
- Prieš didelius pakeitimus naudokite Plan Mode (Shift+Tab)

„Claude Code“ ši sintaksė viena eilute įtraukia AGENTS.md ir po juo prideda „Claude Code“ skirtas papildomas taisykles. Jei vėliau norėsite pašalinti AGENTS.md, tiesiog ištrinkite importą. Dėl šios eilutės turinys neskaitomas dukart: pagal „Claude Code“ dokumentaciją, tas pats AGENTS.md įkeliamas tik vieną kartą, net jei įrankis gali jį perskaityti ir pats.

Rekomenduojama 2026 m. kelių įrankių komandos struktūra:

repo-root/
├── AGENTS.md                              # tiesos šaltinis, ≤150 eilučių
├── CLAUDE.md                              # tik jei yra specialių „Claude“ taisyklių: simbolinė nuoroda → AGENTS.md ARBA @AGENTS.md + papildomos taisyklės
├── .cursor/rules/                         # tik „Cursor“ skirtos konkrečios taisyklės
├── .github/copilot-instructions.md        # „Žr. AGENTS.md“, jei naudojamas
└── docs/architecture.md                   # išsami architektūra, minima AGENTS.md

Daugiau apie CLAUDE.md skaitykite vadove „Kaip tinkamai sukonfigūruoti CLAUDE.md“. Daugiau apie priežastis, kodėl agentui reikia didelio instrukcijų failo, skaitykite „Kas yra konteksto inžinerija“.

Kas pasikeitė 2026 m.: kodėl AAIF perdavė AGENTS.md „Linux Foundation“?

Svarbiausia mintis

2025 m. gruodžio 9 d. „Linux Foundation“ įsteigė „Agentic AI Foundation“ (AAIF), kurios trys steigiamieji projektai buvo „OpenAI“ AGENTS.md, „Anthropic“ MCP ir „Block“ goose. Steigėjai buvo AWS, „Anthropic“, „Block“, „Bloomberg“, „Cloudflare“, „Google“, „Microsoft“ ir „OpenAI“. Iki 2026 m. vasario 24 d. fondas vienijo 146 organizacijas. Tai reiškia, kad AGENTS.md iš „OpenAI dalyko“ tapo pramonės standartu greta MCP. Praktikoje, jei kuriate produktą, kuris turi veikti su skirtingų tiekėjų agentais, AGENTS.md šakniniame kataloge yra būtina tvarka. Be jo teks prižiūrėti tris ar keturis lygiagrečius failus, kurie per mėnesį ims skirtis.

Pagrindinė 2026 m. gegužės DI programavimo politinė istorija buvo ne dar vieno modelio išleidimas, o formatų konsolidacija. Anksčiau kiekvienas tiekėjas turėjo savo taisyklių failą – tai buvo patogu tiekėjams, bet apsunkino darbą komandoms, naudojančioms kelis įrankius.

2025 m. gruodžio 9 d. pranešime spaudai „Linux Foundation“ paskelbė apie „Agentic AI Foundation“ – trijų formatų skėtinę organizaciją:

  • AGENTS.md iš „OpenAI“ – instrukcijų agentams failo formatas
  • Model Context Protocol (MCP) iš „Anthropic“ – protokolas išoriniams įrankiams prijungti prie agentų
  • goose iš „Block“ – atvirojo kodo agentų sistema

Iš „Linux Foundation“ pranešimo spaudai:

„Sujungus šiuos projektus po AAIF skėčiu užtikrinama, kad jie galės vystytis skaidriai ir stabiliai – taip gali nutikti tik esant atviram valdymui.“

(„Linux Foundation“ pranešimas spaudai, 2025 m. gruodžio 9 d., išversta iš anglų kalbos)

Iki 2026 m. vasario 24 d. AAIF priklausė 146 organizacijos (per du mėnesius prisijungė 97 nauji nariai). Tarp naujųjų aukso lygio narių buvo „Red Hat“, „ServiceNow“, „Akamai“, „Lenovo“, „JPMorgan Chase“, „Huawei“, „Hitachi“, „UiPath“, „American Express“ ir „Autodesk“. „Anthropic“ yra platinos lygio narė ir remia MCP. „OpenAI“ yra platinos lygio narė ir remia AGENTS.md. „Block“ yra platinos lygio narė ir remia goose.

Tai pakeitė AGENTS.md statusą: iš „OpenAI formato“ jis tapo pramonės standartu. 2026 m. pavasarį „Claude Code“ vis dar buvo nuošalyje, tačiau rugsėjį, išleidus 2.1.277 versiją, išmoko pats skaityti AGENTS.md. CLAUDE.md niekur nedingo, o jei jis yra projekte, pagal numatytuosius nustatymus vis dar turi pirmenybę.

Praktiškas pradinis variantas – bendros projekto taisyklės AGENTS.md ir kiekvienam naudojamam klientui reikalingas importas, susiejimo failas ar aiški skaitymo konfigūracija. „Claude Code“ atveju patikrinkite įdiegtą versiją ir instrukcijų failų pirmenybę prieš nuspręsdami, ar reikia CLAUDE.md importo arba simbolinės nuorodos. Įkėlimą patikrinkite kiekviename kliente; šis vadovas nenustato jokios aprėpties procentais.

Kas toliau?

AGENTS.md yra pirmasis elementas, padedantis „susitarti su agentu, kad jis veiktų nuspėjamai“. Toliau eina antrasis elementas – projekto žinių aplankas, kuriame pateikiamas verslo kontekstas, auditorija, produktai ir kainos. Trečiasis elementas – konteksto inžinerija, sujungianti viską: kokius failus agentas mato kiekviename žingsnyje, kaip išsaugoma būsena tarp sesijų ir kaip perjungti skirtingus modelius.

Praktinė medžiaga: Ailoot dokumentacija.

Daugiau medžiagos ir įrankių: Ailoot.

Išsamiau

Klausimai ir atsakymai

Ką daryti, jei AGENTS.md ir CLAUDE.md jau abu yra?

Prieš keisdami pasidarykite abiejų kopijas ir palyginkite. Bendras taisykles sujunkite į AGENTS.md, Claude skirtas palikite CLAUDE.md ir pridėkite @AGENTS.md importą; nepervadinkite vieno ant kito.

Kaip instrukcijas padaryti patikrinamas?

Rašykite tikslias sąrankos ir testų komandas, apibrėžkite tikėtiną rezultatą ir nurodykite, ko agentas neturi keisti. Išsamią architektūrą perkelkite į susietus dokumentus, kad pagrindinės instrukcijos liktų lengvai peržvelgiamos.

Visi straipsniai