Context engineering v repozitáři: co vidí AI agent

Context engineering je rozhodování o tom, co AI agent na kód vidí před prací a během ní: soubory s pravidly, zadání, kód, který otevře, a výstupy jeho nástrojů. V repozitáři se to zúží na tři věci. Krátký soubor, který se načte vždy (AGENTS.md nebo CLAUDE.md), pravidla, která se načtou jen tam, kde platí, a písemné zadání s kritérii přijetí. Všechno ostatní si má agent dotáhnout, když to potřebuje, ne to nosit od začátku.

Kód u nás píše hlavně AI. Každou změnu kontroluje senior, který ručí za to, co jde do produkce. Níže je, co patří do které vrstvy, s obecnými příklady ke zkopírování, jak kontext držíme malý a co jsme vyhodili, protože agenta zhoršovalo.

Co je context engineering?

Model ví jen to, co má při daném volání v kontextovém okně. U coding agenta se okno plní rychle: systémový prompt, soubory s pravidly, zadání, každý přečtený soubor, každý spuštěný příkaz a výstup, který se vrátí.

Okno je rozpočet, ne koš. Anthropic popisuje context rot: s rostoucím kontextem klesá schopnost modelu vybavit si, co v něm je. Pravidlo na 400. řádku dlouhého souboru tam technicky je, prakticky ne.

Context engineering jsou tedy hlavně dvě rozhodnutí. Co jde dovnitř ve výchozím stavu. A co zůstane venku, dokud si o to agent neřekne.

Kontext, prompt nebo specifikace: jaký je rozdíl?

Ty tři pojmy se pletou. Popisují různé vrstvy téže věci.

Specifikace si zaslouží vlastní článek a má ho: spec-driven development s AI agenty. Tady zůstaneme u repozitáře: co v něm leží, aby každá session agenta začala se správným kontextem.

Co patří do souboru, který se načte vždy?

AGENTS.md (u Claude Code CLAUDE.md) se načte u každého úkolu. Je to proto nejdražší text v repozitáři. Patří do něj jen to, co agent z kódu nevyčte.

Obecný příklad, který pokryje většinu repozitářů:

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

Čtyři nadpisy: jak to spustit, kde co je, co je zakázané, co znamená hotovo. Pokud tým používá Claude Code vedle jiných nástrojů, držte jeden soubor. Aktuální Claude Code čte AGENTS.md přímo a tam, kde ne, ho CLAUDE.md s jediným řádkem @AGENTS.md naimportuje.

Co tam nepatří: styl, který už hlídá formátovač, eseje o architektuře, historie rozhodnutí a pravidla, která platí jen v jedné složce. Jak rozhodnout, kam které pravidlo patří a které má být raději lint než text, je v článku CLAUDE.md a AGENTS.md: pravidla pro AI kód v týmu.

Jak se pravidla načtou jen tam, kde platí?

Přes strukturu složek. Pravidlo, které platí jen pro fakturaci, nemá nic stát, zatímco agent upravuje přihlašovací stránku.

Mechanismy jsou tři a fungují v tomto pořadí:

• Soubor ve složce modulu. src/billing/AGENTS.md nebo src/billing/CLAUDE.md. Claude Code ho načte, až když je potřeba, tedy když agent čte nebo upravuje soubor v té složce.
• Pravidla vázaná na cestu. Soubor pravidel v .claude/rules/ s polem paths v hlavičce se načte, jen když agent sáhne na odpovídající soubor:

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

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

• Skills a propojené dokumenty. Postup jako „jak u nás píšeme migraci“ žije ve skillu nebo dokumentu. Agent vidí jednořádkový popis a tělo si načte, jen když ho úkol potřebuje.

Jedna past: import přes @path kontext nešetří. Importovaný soubor se načte spolu se souborem, který ho importuje. Importy udrží dlouhý soubor přehledný. Kratší ho neudělají.

Co vidí agent u jednoho úkolu?

U nás jeden úkol znamená jedno GitHub issue, jednu novou session a jeden pull request. Takto se kontext pro tuto session skládá.

Zadání je část, kterou týmy podceňují. Minimální issue, které agent dotáhne:

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

Dvě další pravidla se vyplatí v každé smyčce. Text zvenku, třeba komentáře v issue a vložené e-maily, dostane model označený jako data, ne jako pokyny. A recenzent dostane vlastní nový kontext s nástroji jen pro čtení. Vidí zadání, změnu a kontroly, ne úvahy agenta, který kód psal. O to jde: posuzuje výsledek, ne příběh. Víc v článku harness engineering v praxi.

Jak udržet kontext malý?

Většinu kontextu nikdo nepřidá záměrně. Nahromadí se. Tyto návyky ho drží na uzdě:

• Odkazy, ne kopie. „Pravidla pro API jsou v docs/api.md“ stojí jeden řádek. Vložený dokument stojí sto a zastará.
• Rozpočet, který hlídá build. „Pište stručně“ vydrží asi dva týdny. Počet řádků v CI vydrží.
• Jeden úkol na session. Dlouhá session vleče každý předchozí úkol do dalšího. Nová session je levnější než shrnutí.
• Hledání v subagentovi. Ať vedlejší agent přečte dvacet souborů a vrátí deset řádků. Hlavní session dostane odpověď, ne hledání.
• Krátké výstupy nástrojů. Test runner, který vypíše jen chyby, dá agentovi, co potřebuje. Dva tisíce řádků úspěšných testů mu dají šum.

Kontrola rozpočtu má pár řádků. Anthropic doporučuje méně než 200 řádků 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še kontrola sečte kořenový soubor a všechna pravidla, která se načtou bez podmínky, proto má strop 300 řádků, ne 200. Běží v našich repozitářích v CI. Jak to zapadá do nastavení týmu, je v článku Claude Code best practices pro tým.

Co jsme z kontextu vyhodili?

Víc, než jsme přidali. Nejvíc pomohlo mazání:

• Staré plány v komentářích issue. Naše kontrola připravenosti četla celé vlákno issue. Zastaralý plán v komentáři ji vedl k tomu, že vyvracela issues, která byla v pořádku. Dnes se za zadání počítá jen tělo issue. Zastaralý kontext je horší než žádný.
• Kopie pravidel. Pravidla zkopírovaná do více repozitářů se za pár týdnů rozešla. Dnes se všude načítají z jednoho verzovaného zdroje.
• Postupy v kořenovém souboru. Dlouhé návody se přesunuly do skills, které se načtou jen při použití. V kořenovém souboru zůstal jen text, který platí při každé úloze.
• Nejdůležitější pravidla jako text. Ta podstatná se změnila na lint, testy a hooky. V kontextu už vůbec nemusí být, protože špatnou změnu zastaví sama.

Tím posledním bodem context engineering končí. Kontext dělá správnou cestu pravděpodobnou. Kontroly dělají špatnou cestu nemožnou. Potřebujete obojí.

Je kontext ve vašem repozitáři v pořádku?

Chcete to mít nastavené ve svém repozitáři?

Soubory pravidel, pravidla vázaná na cestu, formát issue i kontroly nastavujeme přímo v repozitáři týmu v rámci služby AI-native SDLC pro vývojové týmy. Od roku 2023 jsme dodali 15+ produkčních projektů. Senior se zapojí do vašeho repozitáře a pull requestů od prvního dne.

Ozveme se do dvou pracovních dnů s pár otázkami k vaší práci. Pak dostanete seznam: co bude hotové a jak si to ověříte.

Pokud si chcete nejdřív promluvit, zarezervujte si úvodní hovor na 15 minut.

Co dnes váš agent čte jako první a kdy z toho naposledy někdo smazal řádek?

Časté otázky

Co je context engineering?

Rozhodování o tom, co AI model uvidí, zatímco pracuje: pokyny, soubory s pravidly, zadání, soubory, které otevře, výstupy nástrojů a historii. U coding agenta většina tohoto kontextu leží v repozitáři, takže context engineering je hlavně práce na repozitáři.

Jaký je rozdíl mezi context engineeringem a prompt engineeringem?

Prompt engineering ladí jednu zprávu. Context engineering řídí všechno ostatní, co model během celého úkolu vidí: která pravidla se načtou, které soubory čte, co vrátí nástroj a co se zahodí. Dobrý prompt nezachrání agenta, který vaše konvence nikdy neuvidí.

Co patří do AGENTS.md nebo CLAUDE.md?

To, co agent z kódu nevyčte: jak projekt spustit a ověřit, kde co je, co nesmí nikdy udělat a co znamená hotovo. Držte ho krátký, protože se načte u každého úkolu. Pravidla jednoho modulu patří do toho modulu, ne do kořenového souboru.

Je pro coding agenta víc kontextu lepší?

Ne. Každý řádek soutěží o pozornost modelu a s rostoucím kontextem si model pamatuje hůř. Dejte agentovi malý, relevantní základ a ať si zbytek dotáhne, když ho potřebuje.

Jak souvisí context engineering se specifikací?

Specifikace je ta část kontextu, která říká, co znamená hotovo. U nás je to issue: co změnit, kritéria přijetí a kam půjde výstup. Bez ní víc kontextu přinese jen sebevědomější špatný výsledek.