Proč AI coding agenti pořád ztrácejí přehled o projektu (a jak to řešit)

Pracujete s AI coding asistentem na projektu přes několik dní. První den vše běží hladce – agent vygeneruje API, napíše testy, vytvoří dokumentaci. Druhý den spustíte novou konverzaci a najednou agent neví, co se dělo předtím. Musíte mu vše znovu vysvětlovat. Po třech nebo čtyřech dnech končíte tím, že procházíte desítky tisíc tokenů v historii chatu, abyste zrekonstruovali, co se vlastně rozhodlo.

Problém není jen v omezené paměti modelu. Jde o něco základnějšího – ukládáme stav projektu na špatném místě.

Proč chat jako úložiště selhává

Chatové rozhraní je skvělé pro komunikaci. Jako databáze projektu ale nefunguje.

• Chat se zapisuje jednou a čte se těžko. Najít starší rozhodnutí znamená procházet stovky zpráv.
• Chybí jednotný zdroj pravdy. Která verze API specifikace je ta aktuální? Ta z třetí nebo páté konverzace?
• Nový agent začíná od nuly. Každá nová session znamená ztrátu kontextu, bez ohledu na to, kolik historie existuje.
• Nesrovnalosti se hromadí. Jeden agent navrhne strategii testování, další změní implementaci, třetí označí dokumentaci za hotovou, přestože je nedokončená.

Skutečné omezení AI-assisted developmentu není v tom, jestli agent umí psát kód. Moderní modely to zvládají dobře. Problém je, jestli agent rozumí tomu, co se buduje a proč.

Jednoduché řešení, které funguje

Místo chatu ukládejte stav projektu tam, kam patří – jako verzované soubory v repozitáři.

Ne jako wiki. Ne jako samostatný nástroj na správu projektů. Jen čisté, strukturované Markdown soubory s lehkými metadaty.

Příklad takového záznamu:

# Project Architecture Decision

Lifecycle: active
Role: spec
Project: payment-service
Updated: 2024-01-15

Related:
- implements: charter-payment-api
- pairs-with: implementation-log-payment-core

## Overview

Používáme přímé Stripe API místo wrapper knihovny, protože...

## Key Decisions

- Idempotency keys pro všechny operace
- Asynchronní zpracování webhooků s exponential backoff
- PII nikdy neukládáme lokálně

Nic složitého. Žádná speciální syntaxe. Žádná databáze. Jen titulek, metadata o stavu (active, completed, archived), typ záznamu (spec, log, decision, guide), vztahy k dalším záznamům a samotný obsah.

Co s tím můžete dělat

Když máte takovou strukturu, můžete nad ní postavit jednoduchý CLI nástroj. Ten umí vytvářet nové záznamy, archivovat dokončené, přesouvat soubory a aktualizovat vztahy, vypisovat všechny záznamy podle filtrů nebo ověřovat, jestli vztahy mezi záznamy dávají smysl.

Index se generuje automaticky. Nic se nemusí udržovat ručně.

Jak to mění práci s AI

Místo toho, abyste novému agentovi říkali „přečti si celý chat a pochop, co děláme“, mu dáte příkaz:

docs list --project=payment-service --role=spec
docs list --lifecycle=active
docs check

Agent může stav projektu dotazovat, ne prohrabávat historii konverzací. Vidí, co bylo rozhodnuto, co se právě dělá, co je blokováno a které dokumenty jsou autoritativní.

Důležitější je, že agent může stav měnit přes strukturované příkazy, ne přímou editací souborů:

docs create --role=log "Implemented rate limiting"
docs archive --record=spec-v2-deprecated
docs touch --record=spec-payment-api

Příkazy chrání integritu systému. Lifecycle, umístění souborů i vztahy se mění společně. Agent nemůže náhodně rozbít strukturu, protože nástroj mu to nedovolí.

Nová konverzace, známý stav

Nejzajímavější je, jak tento přístup mění začátek nové session:

1. Agent se probudí v nové konverzaci
2. Nejprve spustí docs list a zjistí, co je aktivní
3. Vidí dokončené milníky a to, co se právě řeší
4. Přečte implementation log a ví, co se zkoušelo včera
5. Podívá se do specifikace a ví, co má dělat

Žádné prohledávání starých zpráv. Žádné rekonstruování rozhodnutí. Jen jasný přehled o aktuálním stavu.

Stará konverzace? Ta už není potřeba. Stav žije v repozitáři, kde má být.

Kdy se to vyplatí

Tento přístup oceníte, pokud:

• Pracujete s AI pair programming nástroji přes více dní
• Spravujete AI agenty, které mají pokračovat bez přenosu celého kontextu
• Spouštíte CI/CD pipeline, které potřebují ověřit konzistenci projektu
• Pracujete v týmu a potřebujete sdílené porozumění tomu, co je rozhodnuto a co ještě otevřené
• Rychle iterujete a ztrácíte přehled o aktuální specifikaci

Není to náhrada za Git, testy nebo code review. Je to vrstva, která dává AI-assisted developmentu smysl napříč časem.

Proč to funguje

Nejlepší na tom je, jak obyčejné to je. Nepřicházíte s novou databází. Nepostavujete speciální IDE. Využíváte to, co vývojáři už znají – Markdown, Git, CLI – a používáte to pro účel, pro který to vzniklo.

Edge cases to jen potvrzují. Agent omylem poškodí vztah? Validace to zachytí. Přehlédne archivovaný záznam? Příkaz list ho ukáže. Stav se rozchází mezi dvěma sessiony? Index je kontrakt – buď je validní, nebo není.

Je to ten typ infrastruktury, která zpětně dává smysl. A přesně to rozhoduje o tom, jestli „agent to nějak zvládl“, nebo „agent projektu rozuměl a dodal ho“.