# VÝZKUM — jak zabránit, aby si nová session vybrala špatný plán

**4. 10. 2026.** Výzkum + návrh. Každý zdroj s URL a datem přístupu.

---

## 1. Ověření předpokladu

Návrh stojí na tom, že `AGENTS.md` je jediný soubor, který se načítá do každé
session. **Potvrzeno externě:**

| Zdroj | Tvrzení |
|---|---|
| <https://agents.md/> | „a dedicated, predictable place to provide the context and instructions" |
| <https://github.com/agentsmd/agents.md> | „A simple, open format for guiding coding agents" |
| <https://code.visualstudio.com/docs/agent/customization/custom-instructions> | „**Use an AGENTS.md file** … Place the primary file at the repository root" |
| <https://developers.openai.com/codex/guides/agents-md> | Codex načítá `AGENTS.md` **před jakoukoli prací**, precedence: global → project root → dolů k CWD |

Standard spravuje Agentic AI Foundation pod Linux Foundation
(<https://agent-ready.dev/how-to-write-an-effective-agents-md>).

**Precedence je oficiálně zdokumentovaná a je deterministická:**

<https://developers.openai.com/codex/guides/agents-md>
> „Codex includes at most one file per directory. Merge order: Codex concatenates
> files from the root down… Files closer to your current directory override earlier
> guidance because they appear later in the combined prompt."

---

## 2. Proč právě `AGENTS.md` selhal v tomto repu

`AGENTS.md:17` dnes říká:
> `PRODUCT_BRIEF_V5.md` a budoucí fáze roadmapy jsou hypotézy či plán, dokud je
> nepotvrdí implementace a testy.

Tři věci najednou, každá škodlivá:

1. **Nejmenuje žádný plán.** Autentický plán (`CyberBrain26cil-031026-v2.md`)
   v `AGENTS.md` není uvedený vůbec.
2. **Odkazuje na V5**, ne na schválené v2.
3. **Říká „roadmapy jsou hypotézy"** — tedy pokyn „plánům nevěř".

Výsledek: session načte `AGENTS.md`, nedostane odkaz, a plán si vybere podle názvu.

### Tento stav není výjimečný — je známý

<https://www.agentpatterns.ai/standards/agents-md/>
> „**Stale and contradictory instructions** … A file that correctly described
> tooling … misleads agents into using … commands. **Static files need active
> maintenance — they do not self-update as conventions change.**"

> „**Mismatch with dynamic environments:** `AGENTS.md` is a static snapshot. A
> single root file serves projects poorly when they have frequent toolchain changes,
> several distinct workflows, or constraints that vary per run."

---

## 3. Čtyři pravidla, která návrh přebírá

### Pravidlo 1 — `AGENTS.md` je mapa, ne encyklopedie

<https://www.agentpatterns.ai/standards/agents-md/>
> „The `AGENTS.md` as table of contents pattern goes further: `AGENTS.md` should be
> about 100 lines of pointers, not an encyclopedia of project knowledge. **The
> knowledge lives in a `docs/` directory that the agent navigates on demand.**"

<https://agent-ready.dev/how-to-write-an-effective-agents-md>
> „**Missing 'don't touch' section.** … The agents file is the index, not the
> encyclopedia. Link out to deeper docs."

**Důsledek pro nás:** do `AGENTS.md` nepůjde obsah plánu. **Půjde tam jeden
řádek s názvem souboru a datem.**

Proč: <https://www.agentpatterns.ai/standards/agents-md/>
> „An **ETH Zurich evaluation** of `AGENTS.md` found context files increased
> inference cost by **over 20% on average**, largely because agents followed their
> instructions into broader-than-necessary exploration. **The file works against
> itself when it embeds knowledge instead of linking to it.**"

### Pravidlo 2 — jeden kanonický zdroj, ostatní na něj odkazují

<https://github.com/artificial-intelligence-first/ssot/blob/main/docs/README_AGENTS.md>
> „If instructions conflict, agents **must not 'average' them**. **The winner must
> be deterministic.**"

> „Make one source canonical (usually `AGENTS.md`) and make tool-specific files
> **reference it**."

> „Child files **SHOULD** link to parent `AGENTS.md` … instead of copying content."

> „`AGENTS.md` **SHOULD** stay under ~200 lines."

**Důsledek pro nás:** `-v2.md` je kanonický. `ROADMAP_V6.md`, `ROADMAP_V7.md` a
V8 draft **neobsahují kopii pravidla**, nýbrž odkaz + stav `návrh`.

### Pravidlo 3 — `AGENTS.md` je kód, ne text

<https://ctxwire.com/articles/write-agents-md-for-coding-agents/> (23. 7. 2026)
> „**Formatting, schemas, coverage thresholds** → Formatter, linter, test, or CI
> configuration → **Deterministic enforcement is more reliable than prose.**"

> „**Contradictions are worse than missing detail because they create
> nondeterministic choices.** Search for other agent instruction files, contributor
> guides, CI requirements, and nested `AGENTS.md` files before adding a rule."

<https://github.com/artificial-intelligence-first/ssot/blob/main/docs/README_AGENTS.md>
> „**Commands** in `AGENTS.md` **MUST** be copy-paste runnable in the repo as written."

**Důsledek pro nás:** tvrzení v `AGENTS.md` se musí dá **vyvrátit příkazem**.
Proto test, ne poznámka.

### Pravidlo 4 — ověřuje se zkouškou, ne čtením

<https://ctxwire.com/articles/write-agents-md-for-coding-agents/>
> „**Do not judge `AGENTS.md` by how complete it looks. Test whether an agent can
> use it.**"

> „Ask the agent to summarize: **the instruction files it loaded**; the intended
> files and prohibited files; the commands it plans to run; the approval points and
> completion evidence."

> „**A strong final file is usually shorter after testing.** Delete redundant prose."

<https://devagentstack.com/templates/agents-md/>
> „**Test the instructions.** Run one bounded task and verify the agent found the
> right files, stayed in scope, and reported real evidence."

**Důsledek pro nás:** po úpravě `AGENTS.md` se spustí zkouška — čerstvá session
dostane úkol a musí **jménovat plán, který načetla**. To je jediný test, který
řeší problém, který jsme měli.

---

## 4. Návrh — čtyři kroky, každý reverzibilní

### Krok 1 — jeden řádek v `AGENTS.md`

Nahradit dnešní `:17` směrem na autoritativní plán, **s datem**, a oddělit
dvě věci, které dnes splývají:

- **plán je autorita pro rozhodování** (co se staví, v jakém pořadí)
- **obchodní závěry v plánu jsou hypotézy** do validace

Druhý bod není kosmetika. Z `-v2.md:26`:
> „Kvalitní architektura sama o sobě **nezaručuje prodejnost**. Obchodní směr je
> zatím hypotéza."

A dnešní `AGENTS.md:17` říká „roadmapy jsou hypotézy". **Obě věty jsou pravdivé a
dohromady vytvořily past**, ve které jsem v této session uvázl: plán byl schválený,
a já jsem z toho vyvodil, že nemá cenu se ho řídit. Ukazatel to musí rozlišit
výslovně.

### Krok 2 — banner v každém neautoritativním plánu

`ROADMAP_V6.md`, `ROADMAP_V7.md`, `1791036626945-…-v8.md` dostanou hlavičku
„návrh, neautoritativní, autorita je X, datum". **Nemazat** — `ROADMAP_V6.md` je
citovaný z 30 testů a z `DECISIONS_V7.md`.

### Krok 3 — test, který hlídá ukazatel

Soubor `tests/test_plan_authority.py`, ~40 řádků, ve stejném stylu jako
existující `test_kilo_agent_policy.py` (který kontroluje konfiguraci jako kód):

1. vytáhne plánovou reference z `AGENTS.md`
2. **assert soubor existuje** — chytí přejmenování
3. **assert žádný jiný plán si nenárokuje autoritu** (hledá „hlavní cílový plán"
   nebo „autoritativní" mimo `-v2.md`)
4. **assert reference na `-v2.md` existuje ve V6 testech** — protože 30 testů se
   odvolává na V6, a kdyby V6 zmizel, mlčely by důvodem

Bez bodu 4 by se stalo přesně to, co se stalo: **testy zelené, dokumentace
zastaralá.**

### Krok 4 — ověření zkouškou

Nová session dostane úkol a musí **jménovat plán**. Pokud jmenuje jiný, ukazatel
nesplnil účel.

---

## 5. Co je kandidát na CI drift kontrolu

Vzor z reálného workflow
(<https://github.com/artificial-intelligence-first/ssot/blob/main/docs/README_AGENTS.md>):

```yaml
# drift detection: vysoko-impaktní soubor se změnil, AGENTS.md ne
needs_docs=0
git diff --name-only "$base" "$head" | grep -E -q '(pyproject.toml|.github/workflows/)' && needs_docs=1 || true
if [ "$needs_docs" = 1 ]; then
  git diff --name-only "$base" "$head" | grep -E -q '(^AGENTS.md$|^docs/)' || {
    echo "Error: AGENTS.md nebo docs/ nebyly aktualizovány"; exit 1; }
fi
```

`.github/` je v chráněném seznamu → vyžaduje schválení.

---

## 6. Upřímná odpověď: je to nástroj, nebo proces?

**Je to obojí, a nástroj pokrývá jen menšinu.**

Výzkum to potvrzuje: <https://www.agentpatterns.ai/standards/agents-md/>
> „**Static files need active maintenance — they do not self-update as
> conventions change.**"

Test krok 3 pokrývá **rozpad odkazu**. Pokrývá, že soubor nezmizí.

**Nepokrývá:** že se `-v2.md` stane zastaralým, ani že vznikne `V9`. To je
**disciplina vlastníka** a nic to nenahradí. Nejpřesnější formulace z výzkumu:

> „A strong final file is usually **shorter after testing**."

To platí i pro plán. `-v2.md` má 617 řádků; pokud vzroste na 2000, stane se
stejným problémem, který dnes řešíme, jen větším.

---

## Zdroje

1. <https://agents.md/> — oficiální standard, přístup 4. 10. 2026
2. <https://github.com/agentsmd/agentsmd> — specifikace, přístup 4. 10. 2026
3. <https://code.visualstudio.com/docs/agent/customization/custom-instructions> — podpora VS Code, přístup 4. 10. 2026
4. <https://developers.openai.com/codex/guides/agents-md> — precedence a `AGENTS.override.md`, přístup 4. 10. 2026
5. <https://www.agentpatterns.ai/standards/agents-md/> — stale drift, ETH eval +20 %, tabulkový vzor, přístup 4. 10. 2026
6. <https://github.com/artificial-intelligence-first/ssot/blob/main/docs/README_AGENTS.md> — deterministická precedence, CI drift, přístup 4. 10. 2026
7. <https://ctxwire.com/articles/write-agents-md-for-coding-agents/> — „test, ne čtení", 23. 7. 2026, přístup 4. 10. 2026
8. <https://devagentstack.com/templates/agents-md/> — Map→Boundaries→Checks→Evidence, přístup 4. 10. 2026
9. <https://agent-ready.dev/how-to-write-an-effective-agents-md> — Linux Foundation stewardship, <200 řádků, přístup 4. 10. 2026