Jak jsem sjednotil dokumentaci pro Aimee Skill Architect
V projektu Aimee existovaly dva dokumenty definující pravidla pro generování AI skillů – `skill-generation-rules.md` a `skills-architect.md`. Oba měly odlišné požadavky na objem obsahu (10-30 vs 6-12 příkladů), různé struktury a chybějící vzájemné reference.
To vytvářelo zmatek při generování nových skillů a riskovalo nekonzistentní výstupy.
Problém, který jsem řešil
Potřeba sjednotit dokumentaci do jednoho autoritativního zdroje pravdy. Dokumenty měly různé požadavky na `resistance_protocols` – jeden je vyžadoval, druhý vůbec nezmiňoval. Chybějící `gemini-prompt.md` v jednom dokumentu, zastaralé kategorie.
Jak jsem ho vyřešil
Systematicky jsem prohledal codebase pomocí semantic search a grep. Identifikoval jsem dva klíčové dokumenty v `Prompts for generating stuff/` a vytvořil jsem detailní srovnávací tabulku konfliktů. Následně jsem navrhl sloučenou strukturu, která zachovala to nejlepší z obou zdrojů.
Vytvořil jsem unified dokument (`skill-architect-unified.md`) s konzistentními požadavky (10-30 příkladů/nudges), kompletní 6-souborovou strukturou, 5 novými kategoriemi (perception, memory, intelligence, creation, connection). Přeložil jsem do češtiny a aktualizoval jsem kategorie podle nového systému.
Výsledek: 1 unified dokument, 0 konfliktů, 100% pokrytí požadavků. Původní soubory zálohované v `zaloha/`.
Jak to funguje v praxi
Každý, kdo bude generovat skill, má teď jeden zdroj. Žádné hádání, který dokument je "ten správný". Unified dokument šetří budoucí čas – investice do sjednocení se vrací při každém dalším použití.
Co jsem se naučil
Dokumentace degraduje postupně. Když projekt roste, vznikají nové dokumenty bez revize starých. Výsledkem jsou konfliktní "zdroje pravdy". Pravidelný audit dokumentace je stejně důležitý jako audit kódu.
AI exceluje v detekci nekonzistencí. Manuální porovnání dvou 70+ řádkových dokumentů by trvalo 30+ minut. AI to udělala za sekundy a systematicky identifikovala všechny rozdíly. Využívej AI na "nudnou práci" – porovnávání, validaci, cross-referencing.
Unified dokument šetří budoucí čas. Každý, kdo bude generovat skill, má teď jeden zdroj. Žádné hádání, který dokument je "ten správný". Investice do sjednocení se vrací při každém dalším použití.
Proč to stojí za to
Když máš konfliktní dokumenty a chceš je sjednotit, nemusíš to dělat manuálně. Můžeš použít AI na systematickou analýzu a vytvoření unified dokumentu.
Unified Skill Architect je teď součástí Aimee. Šetří mi čas, protože nemám konfliktní dokumenty. A zároveň mám kontrolu nad tím, jak dokumentace vypadá, protože všechno je v jednom unified dokumentu.
Pokud máš podobný problém – konfliktní dokumenty – zkus to. Možná zjistíš, že je to jednodušší, než sis myslel.
Časté otázky
Proč je důležité mít jednotnou dokumentaci pro AI generování?
Když máš dva dokumenty s různými pravidly, AI generuje nekonzistentní výstupy. Jeden říká 10-30 příkladů, druhý 6-12. Výsledek? Hádání a zmatek při každém generování. Jeden autoritativní zdroj tohle eliminuje.
Jak AI pomáhá při sjednocování dokumentace?
Manuální porovnání dvou 70+ řádkových dokumentů by trvalo 30+ minut. AI to udělala za sekundy a systematicky identifikovala všechny rozdíly. Ty pak rozhoduješ, co zachovat – to je ta část, která potřebuje člověka.
Co je "single source of truth" v kontextu dokumentace?
Jeden dokument, který platí. Žádné "moment, který dokument je ten správný?". Každý v týmu ví, kam se podívat. Nula konfliktů, nula hádání.
Jak často by se měla dokumentace auditovat?
Pravidelně, stejně jako kód. S růstem projektu vznikají nové dokumenty bez revize starých. Dokumentace degraduje postupně – a když si toho všimneš, máš dva "zdroje pravdy", které si protiřečí.
Jak postupovat při sjednocování konfliktních dokumentů?
Systematicky prohledej codebase, vytvoř srovnávací tabulku rozdílů, navrhni sloučenou strukturu. Zachovej to nejlepší z obou zdrojů. Původní soubory přesuň do zálohy – kdyby něco, můžeš se vrátit.
Tom