Context engineering v repozitári: čo vidí AI agent

Context engineering je rozhodovanie o tom, čo AI agent na kód vidí pred prácou a počas nej: súbory s pravidlami, zadanie, kód, ktorý otvorí, a výstupy jeho nástrojov. V repozitári sa to zúži na tri veci. Krátky súbor, ktorý sa načíta vždy (AGENTS.md alebo CLAUDE.md), pravidlá, ktoré sa načítajú len tam, kde platia, a písomné zadanie s kritériami prijatia. Všetko ostatné si má agent dotiahnuť, keď to potrebuje, nie to nosiť od začiatku.

Kód u nás píše hlavne AI. Každú zmenu kontroluje senior, ktorý ručí za to, čo ide do produkcie. Nižšie je, čo patrí do ktorej vrstvy, so všeobecnými príkladmi na skopírovanie, ako kontext držíme malý a čo sme vyhodili, lebo agenta zhoršovalo.

Čo je context engineering?

Model vie len to, čo má pri danom volaní v kontextovom okne. Pri coding agentovi sa okno plní rýchlo: systémový prompt, súbory s pravidlami, zadanie, každý prečítaný súbor, každý spustený príkaz a výstup, ktorý sa vráti.

Okno je rozpočet, nie kôš. Anthropic opisuje context rot: s rastúcim kontextom klesá schopnosť modelu vybaviť si, čo v ňom je. Pravidlo na 400. riadku dlhého súboru tam technicky je, prakticky nie.

Context engineering sú teda hlavne dve rozhodnutia. Čo ide dnu predvolene. A čo ostane vonku, kým si o to agent nepovie.

Kontext, prompt alebo špecifikácia: aký je rozdiel?

Tie tri pojmy sa pletú. Opisujú rôzne vrstvy tej istej veci.

Špecifikácia si zaslúži vlastný článok a má ho: spec-driven development s AI agentmi. Tu ostaneme pri repozitári: čo v ňom leží, aby každá session agenta začala so správnym kontextom.

Čo patrí do súboru, ktorý sa načíta vždy?

AGENTS.md (pri Claude Code CLAUDE.md) sa načíta pri každej úlohe. Je to preto najdrahší text v repozitári. Patrí doň len to, čo agent z kódu nevyčíta.

Všeobecný príklad, ktorý pokryje väčšinu repozitárov:

# AGENTS.md

## Run
- Install: `pnpm install`
- Check everything: `pnpm check` (typecheck, lint, tests)
- One test file: `pnpm test path/to/file.test.ts`

## Map
- `src/billing/` holds the invoice rules. It has its own AGENTS.md.
- `src/generated/` is generated. Never edit it by hand.
- Tests sit next to the code as `*.test.ts`.

## Never
- Touch the production database or `.env*` files.
- Change a migration that is already merged. Add a new one.
- Push to `main`. Open a pull request.

## Done means
- `pnpm check` is green.
- New behaviour has a test that failed before the change.
- The PR says what changed and how it was checked.

Štyri nadpisy: ako to spustiť, kde čo je, čo je zakázané, čo znamená hotovo. Ak tím používa Claude Code popri iných nástrojoch, držte jeden súbor. Aktuálny Claude Code číta AGENTS.md priamo a tam, kde nie, ho CLAUDE.md s jediným riadkom @AGENTS.md naimportuje.

Čo tam nepatrí: štýl, ktorý už stráži formátovač, eseje o architektúre, história rozhodnutí a pravidlá, ktoré platia len v jednom priečinku. Ako rozhodnúť, kam ktoré pravidlo patrí a ktoré má byť radšej lint než text, je v článku CLAUDE.md a AGENTS.md: pravidlá pre AI kód v tíme.

Ako sa pravidlá načítajú len tam, kde platia?

Cez štruktúru priečinkov. Pravidlo, ktoré platí len pre fakturáciu, nemá nič stáť, kým agent upravuje prihlasovaciu stránku.

Mechanizmy sú tri a fungujú v tomto poradí:

• Súbor v priečinku modulu. src/billing/AGENTS.md alebo src/billing/CLAUDE.md. Claude Code ho načíta, až keď treba, teda keď agent číta alebo upravuje súbor v tom priečinku.
• Pravidlá viazané na cestu. Súbor pravidiel v .claude/rules/ s poľom paths v hlavičke sa načíta, len keď agent siahne na zodpovedajúci súbor:

---
paths:
  - "src/billing/**/*.ts"
---

# Billing rules
- Money is integer cents. Never floats.
- Every price change writes an audit row.

• Skills a prepojené dokumenty. Postup ako „ako u nás píšeme migráciu“ žije v skille alebo dokumente. Agent vidí jednoriadkový popis a telo si načíta, len keď ho úloha potrebuje.

Jedna pasca: import cez @path kontext nešetrí. Importovaný súbor sa načíta spolu so súborom, ktorý ho importuje. Importy udržia dlhý súbor prehľadný. Kratší ho neurobia.

Čo vidí agent pri jednej úlohe?

U nás jedna úloha znamená jedno GitHub issue, jednu novú session a jeden pull request. Takto sa kontext pre túto session skladá.

Zadanie je časť, ktorú tímy podceňujú. Minimálne issue, ktoré agent dotiahne:

## What
Add CSV export to the invoice list.

## Acceptance
- An empty list exports the header row only.
- Totals in the file match the invoice detail.

## Output
One PR with a test that fails on main and passes on the branch.

Dve ďalšie pravidlá sa oplatia v každej slučke. Text zvonku, napríklad komentáre v issue a vložené e-maily, dostane model označený ako dáta, nie ako pokyny. A recenzent dostane vlastný nový kontext s nástrojmi len na čítanie. Vidí zadanie, zmenu a kontroly, nie úvahy agenta, ktorý kód písal. O to ide: posudzuje výsledok, nie príbeh. Viac v článku harness engineering v praxi.

Ako udržať kontext malý?

Väčšinu kontextu nikto nepridá zámerne. Nahromadí sa. Tieto návyky ho držia na uzde:

• Odkazy, nie kópie. „Pravidlá pre API sú v docs/api.md“ stojí jeden riadok. Vložený dokument stojí sto a zastará.
• Rozpočet, ktorý stráži build. „Píšte stručne“ vydrží asi dva týždne. Počet riadkov v CI vydrží.
• Jedna úloha na session. Dlhá session vlečie každú predchádzajúcu úlohu do ďalšej. Nová session je lacnejšia než zhrnutie.
• Hľadanie v subagentovi. Nech vedľajší agent prečíta dvadsať súborov a vráti desať riadkov. Hlavná session dostane odpoveď, nie hľadanie.
• Krátke výstupy nástrojov. Test runner, ktorý vypíše len chyby, dá agentovi, čo potrebuje. Dvetisíc riadkov úspešných testov mu dá šum.

Kontrola rozpočtu má pár riadkov. Anthropic odporúča menej ako 200 riadkov na CLAUDE.md:

# fail CI when the always-loaded agent files grow past the budget
total=$(cat AGENTS.md CLAUDE.md 2>/dev/null | wc -l)
[ "$total" -le 200 ] || { echo "Agent context: $total lines (max 200)"; exit 1; }

Naša kontrola sčíta koreňový súbor a všetky pravidlá, ktoré sa načítajú bez podmienky, preto má strop 300 riadkov, nie 200. Beží v našich repozitároch v CI. Ako to zapadá do nastavenia tímu, je v článku Claude Code best practices pre tím.

Čo sme z kontextu vyhodili?

Viac, než sme pridali. Najviac pomohlo mazanie:

• Staré plány v komentároch issue. Naša kontrola pripravenosti čítala celé vlákno issue. Zastaraný plán v komentári ju viedol k tomu, že vyvracala issues, ktoré boli v poriadku. Dnes sa za zadanie počíta len telo issue. Zastaraný kontext je horší ako žiadny.
• Kópie pravidiel. Pravidlá skopírované do viacerých repozitárov sa za pár týždňov rozišli. Dnes sa všade načítajú z jedného verzovaného zdroja.
• Postupy v koreňovom súbore. Dlhé návody sa presunuli do skills, ktoré sa načítajú len pri použití. V koreňovom súbore ostal len text, ktorý platí pri každej úlohe.
• Najdôležitejšie pravidlá ako text. Tie podstatné sa zmenili na lint, testy a hooky. V kontexte už vôbec nemusia byť, lebo zlú zmenu zastavia samy.

Tým posledným bodom sa context engineering končí. Kontext robí správnu cestu pravdepodobnou. Kontroly robia zlú cestu nemožnou. Potrebujete oboje.

Je kontext vo vašom repozitári v poriadku?

Chcete to mať nastavené vo svojom repozitári?

Súbory pravidiel, pravidlá viazané na cestu, formát issue aj kontroly nastavujeme priamo v repozitári tímu v rámci služby AI-native SDLC pre vývojové tímy. Od roku 2023 sme dodali 15+ produkčných projektov. Senior sa zapojí do vášho repozitára a pull requestov od prvého dňa.

Ozveme sa do dvoch pracovných dní s pár otázkami k vašej práci. Potom dostanete zoznam: čo bude hotové a ako si to overíte.

Ak sa chcete najprv porozprávať, rezervujte si úvodný hovor na 15 minút.

Čo dnes váš agent číta ako prvé a kedy z toho naposledy niekto zmazal riadok?

Časté otázky

Čo je context engineering?

Rozhodovanie o tom, čo AI model uvidí, kým pracuje: pokyny, súbory s pravidlami, zadanie, súbory, ktoré otvorí, výstupy nástrojov a históriu. Pri coding agentovi väčšina tohto kontextu leží v repozitári, takže context engineering je hlavne práca na repozitári.

Aký je rozdiel medzi context engineeringom a prompt engineeringom?

Prompt engineering ladí jednu správu. Context engineering riadi všetko ostatné, čo model počas celej úlohy vidí: ktoré pravidlá sa načítajú, ktoré súbory číta, čo vráti nástroj a čo sa zahodí. Dobrý prompt nezachráni agenta, ktorý vaše konvencie nikdy neuvidí.

Čo patrí do AGENTS.md alebo CLAUDE.md?

To, čo agent z kódu nevyčíta: ako projekt spustiť a overiť, kde čo je, čo nesmie nikdy urobiť a čo znamená hotovo. Držte ho krátky, lebo sa načíta pri každej úlohe. Pravidlá jedného modulu patria do toho modulu, nie do koreňového súboru.

Je pre coding agenta viac kontextu lepšie?

Nie. Každý riadok súťaží o pozornosť modelu a s rastúcim kontextom si model pamätá horšie. Dajte agentovi malý, relevantný základ a nech si zvyšok dotiahne, keď ho potrebuje.

Ako súvisí context engineering so špecifikáciou?

Špecifikácia je tá časť kontextu, ktorá hovorí, čo znamená hotovo. U nás je to issue: čo zmeniť, kritériá prijatia a kam pôjde výstup. Bez nej viac kontextu prinesie len sebavedomejší zlý výsledok.