Domovská stránka říká, co Majordomus je, a dokazuje to na jedné stránce. Toto je argument, z něhož byla tato stránka destilována, celý: problém tak, jak jej prožívá repozitář, model, který hájí, a — fázi po fázi — kolik z tohoto modelu dnes běží a kolik je zatím jen argument.
Celá argumentace
Delší výklad za domovskou stránkou: proč vývoj řízený prompty neškáluje s repozitářem, co je záměr, model provádění s poctivým označením toho, co existuje, proč musí být governance spustitelná, a doktrína.
01 / problém
Vývoj řízený prompty se s repozitářem neškáluje
Vývojář řekne: uprav tento soubor, přidej tento endpoint, napiš tyto testy, aktualizuj tuto komponentu. Model následuje bezprostřední instrukci. Někdy to funguje.
- Staví druhou implementaci něčeho, co už existuje.
- Ignoruje ADR, které před ni nikdo nepředložil.
- Dokumentace tvrdí jedno, zatímco runtime dělá jiné.
- Testy procházejí, zatímco je rozbitá celá integrační plocha.
- Změna se sloučí a nikdo později nedokáže odpovědět na docela základní otázku.
Jaký záměr uživatele měla tato změna ve skutečnosti naplnit?
Kontext je roztříštěn mezi
- zdrojový kód
- tests
- historie gitu
- úkoly
- milníky
- ADR
- rules
- doktríny
- politiky
- kontexty relací
- předávky
- knowledge
- generovaná dokumentace
- stav za běhu
- Schémata API
- stav nasazení
- další agenti pracující na tomtéž systému
Větší kontextové okno modelu to neřeší. Větší hromada nestrukturovaných informací je pořád hromada.
Agenti jsou rychlí. Důvěra je pomalá.
- znovu vysvětloval stejný kontext zbrusu nové relaci
- zjistil, že dva agenti opravují stejnou chybu ve dvou branchích
- sledoval, jak nejsilnější model na maximální úsilí přejmenoval proměnnou
- přijal "done", protože to řekl model, a zaplatil za to další ráno
- otevřel CLAUDE.md a AGENTS.md a našel dvě různé sady pravidel pro jeden repozitář
- sledoval, jak relace zrušila loňské rozhodnutí z důvodu, kvůli kterému bylo přijato
- našel úlohu "in progress", které se tři týdny nikdo nedotkl
- se zeptal, co workeři dělali včera v noci, a měl jen přepisy, které by mohl prohledávat
- našel pravidlo pro daný adresář v README, které žádná relace nikdy nenačetla
- četl tři plány rozvoje jednoho projektu a nevěřil žádnému z nich
Všech 38, podle toho, kdo jste, a podle oblasti provozu, do které patří →
Majordomus řeší všechny tři na jediném místě, kde už každý agent pracuje: ve vašem repozitáři.
02 / hlavní myšlenka
Popište požadovaný stav, ne úpravu
Záměr je výrok o realitě: co se musí stát pravdou, co musí zůstat pravdou a jaké důkazy to rozhodnou. Záměrně to není seznam souborů k otevření.
Každý programovací agent vstupující do tohoto repozitáře musí automaticky objevit runtime, načíst příslušné řízení a kontext relace, připojit se k aktivnímu prostředí peerů a být připraven spolupracovat bez ručního bootstrapu.
Modify .envrc. Add a bootstrap. Create a peer registry. Add a route. Update the Cockpit.Ty mohou být správné. Mohou být neúplné. Mohou už existovat. Mohou odporovat architektuře. První otázka je ta druhá.
Co se musí v aktuálním repozitáři změnit, aby se záměr stal pravdou?
Záměr je primární artefakt
Prompt není zdrojem pravdy. Je jedním ze způsobů, jak sdělit záměr pracovníkovi. Není jím ani úkol, milník, commit, pull request, ADR či test: to jsou projekce, omezení, důkazy nebo následky kolem něj.
kontext před kódem
Kontext se kompiluje, nejen vyhledává
Cílem není nalít repozitář do modelu. Je to zkompilovat nejmenší užitečnou reprezentaci reality, kterou práce potřebuje. Byla by řazena podle autority, nesla svou provenienci, vešla se do rozpočtu řádků, který jmenuje každé vyloučení, vynechala, co worker už má, a řekla, kde se dva zdroje rozcházejí.
Vysypat dvacet souborů Markdownu do kontextového okna není architektura. Je to znečišťování pomocí GPU.
Co pracovník skutečně dostane, když otevře tento repozitář →
03 / model provádění
Záměr → Kontext → Plán → Provedení → Ověření → Důkaz
Vývoj jako transformace ze současné reality repozitáře k žádoucí. Každá fáze má vstup, který nevymyslela, a výstup, který může ověřit další. Pod každou fází jsou tvrzení, která ji pokrývají, každé se stavem, který deklaruje matice tvrzení.
flowchart TD
capture["INTENT CAPTURE"]
context["CONTEXT"]
plan["PLAN"]
execute["EXECUTE"]
verify["VERIFY"]
proof["PROOF"]
capture --> context
context --> plan
plan --> execute
execute --> verify
verify --> proof
verify -- "not satisfied" --> plan-
1 / 6 · zachycení
Zachycení záměru
Tvrzení a co by o něm rozhodlo.požadované výsledky · omezení · invarianty · kritéria přijetí · původ
- zaručenointent-links-resolve
- zaručenointent-stage-derived
-
2 / 6 · zjištění
Kontext
Preflight governance, pak zjišťování, pak kompilace — ne vyhledávání.pravidla, doktríny, politiky, ADR · kontexty a předávky relací · rozhodnutí, znalosti, otevřené otázky · úkoly, milníky, stav worktree a větví · pořadí autority a původ · rozpočet řádků, který jmenuje svá vynechání
- zaručenocontext-assembly
- zaručenocontext-selection-budget
- zaručenointent-in-session-context
-
3 / 6 · vyřešit
Plán
Nejednoznačnost pojmenována, dopad odvozen, strategie zvolena proti architektuře.detekce nejednoznačnosti · analýza dopadu · architektonická omezení · mapování schopností · zdroje, testy, dokumentace, schémata · integrační povrchy a nasazení
- zaručenointent-criteria-covered
- zaručenointent-plan-reviewed
- zaručenointent-refused-at-plan-start
-
4 / 6 · provedení
Provést
Několik pracovníků, různé odpovědnosti, jeden koordinační objekt.implementace · oponentura · review · testování · ověření
- zaručenoscoped-task
- zaručenoscope-enforcement
- zaručenomcp-peers
- zaručenoworktree-topology-derived
-
5 / 6 · ověřit
Ověřit
Proti kritériím přijetí, ne proti diffu.kritéria přijetí · invarianty · regresní kontroly · tvrzení proti implementaci · důkazy z běhu
- zaručenofinish-contract
- zaručenoevidence-gates-done
- zaručenointent-realization-held-to-evidence
-
6 / 6 · dokázat
Důkaz
Prozkoumatelný balík, ne slovo success.požadavky a změněný kód · testy a runtime kontroly · governance, která se uplatnila · commity, artefakty, API a stav nasazení · zbývající omezení
- zaručenoevidence-proof-is-an-execution
- plánovánointent-command-deployment-evidence
- plánovánointent-closes-github-milestones
řídicí smyčka
Agent nemůže prohlásit úspěch jen proto, že se jeho patch aplikoval
Uzavřete tytéž fáze a máte řídicí systém místo asistenta: kontext by pozoroval, plán by počítal rozdíl, provádění by jednalo, ověření by měřilo a výsledek by se porovnával se záměrem, ne s diffem — přeplánování, dokud není uspokojen. Majordomus nikdy nevolá model a nikdy nepíše kód; rozhoduje, co se pracovníkovi řekne a zda lze věřit jeho tvrzení, že je hotov.
Repozitář, testy, runtime, governance i důkazy mají hlas. Důkazy mají poslední.
04 / governance je spustitelná
Blokující pravidlo zastaví příkaz; cokoli menšího je dokumentace
Pravidla a doktríny nejsou inspirativní próza; účastní se provádění. Pravidla, která se na práci vztahují, se vyhodnotí před jejím začátkem z politiky a profilu a blokující pravidlo příkaz zastaví, místo aby radilo. Model by je vyhodnocoval i vůči záměru.
Záměr plus správa repozitáře dávají efektivní požadavky na změnu. Níže uvedená pravidla nejsou výběr, který pro tuto stránku někdo udělal — jsou to ta, na nichž stojí veřejné funkce, vyřešená spustitelným souborem.
- pravidel, která zastaví příkaz
- 68
- pravidla, která hlásí a nechají to projít
- 15
- vyřešeno pro veřejné funkce
- 83
Každé z nich jménem — 83 pravidel, vyřešených a deduplikovaných spustitelným souborem
- blokující Integrita architektonických rozhodnutí
- blokující Integrita vrstvy AI
- blokující Řešení blokátorů
- blokující Integrita bootstrapu
- blokující Integrita katalogu
- poradní Aktuálnost checkpointu
- blokující Rozpočet kontextu
- blokující Integrita kontextu
- blokující Integrita grafu závislostí
- poradní Záznamy rozhodnutí
- blokující Rozhodovací práh
- poradní Definovat dokončení před provedením
- blokující Integrita zapojení doktríny
- blokující Zapojení vynucování
- poradní Externalizovat rozhodnutí a trvalý stav
- blokující Integrita předávky
- poradní Předávky přenášejí stav, ne přepisy
- poradní Paralelní práce vyžaduje izolaci
- poradní Integrita rozložení
- blokující Integrita účetní knihy
- poradní Načíst minimální dostatečný kontext
- blokující Integrita poznámek
- poradní Jeden pracovník, jeden jasný rozsah
- blokující Úplnost politiky
- blokující Integrita politiky
- blokující Požadavky profilu
- blokující Integrita modelu projektu
- blokující Integrita projekcí
- blokující Zachycení promptu je prokázané, nebo hlášené jako nedostupné
- blokující Stropy uchovávání
- blokující Plán rozvoje je projekce, nikdy dokument
- blokující Integrita balíčku pravidel
- blokující Integrita rozsahu
- blokující Hranice epizody se vede pod modelem a jeho pracovní kontext je lokální
- blokující Záznamy relací jsou sdílené objekty s uzavřenou množinou polí
- blokující Integrita dovedností
- blokující Konzistence stavu
- poradní Kontinuita úlohy
- blokující Pokrytí případy užití
- blokující Integrita ověření
- poradní Ověřujte výsledky, ne aktivitu
- blokující Osobní vrstva nemění nic sdíleného
- blokující Poradci jsou volitelní; uvažování, governance a CI na žádném nezávisejí
- poradní Každý veřejný příkaz lze změřit z registru
- blokující Blokující kontroly jsou deterministické a levné
- blokující Lokalita kontextu
- blokující Zpráva commitu je hodnota, kterou tento repozitář posuzuje, ne konvence, v kterou doufá
- blokující Odvozené soubory se regenerují, nikdy neupravují
- poradní Odvozený stav se počítá jednou na verzi stavu
- blokující Distribuce má jeden kanonický model
- blokující Pouze anglicky
- blokující Každý nález nese příkaz k reprodukci
- blokující Generovaný artefakt deklaruje svůj dokument, kódování, kontrakt a zdroj
- poradní Příkaz čte každý kanonický soubor nejvýše jednou
- blokující Externí rozhraní jsou projekce jedné definice schopnosti
- blokující Spolupráce v meshi se připouští po jednotlivých linkách, replikuje se jedním žurnálem a každý povrch ji promítá stejně
- blokující Mesh pozoruje uzly; nic neautorizuje a drží jeden registr
- blokující Nativní příkaz příkazové řádky existuje jen se svou dokumentací a spustitelnými příklady
- blokující Nikdy nepsat pole identity
- blokující Nikdy neukládat ani nesumarizovat přepisy
- blokující Nový a změněný spustitelný kód je pokrytý testem; starý dluh se smí jen zmenšovat
- blokující Žádné tvrzení bez testu
- blokující Nic, co tento repozitář commituje, nepojmenovává cestu na stroji, kde to bylo napsáno
- blokující Žádná síť, žádná telemetrie, žádný eval, žádné tiché přepsání, žádné rekurzivní mazání
- poradní Tvrzení o výkonu nese své měření
- blokující Přenosný shell
- blokující Nezávislá revize je zaznamenaný fakt, vážený důkazy, nikdy tvrzený a nikdy počítaný
- blokující Nové vynucené pravidlo je doktrína, ne vložená kontrola
- blokující Žádný endpoint spustitelného souboru v Rustu bez měření a žádné číslo bez důkazů
- blokující Jedna kanonická deklarace; moduly skládají schopnosti; kořen skládá moduly
- blokující Spustitelný soubor v Rustu nese své důkazy s sebou
- blokující Příkaz v souboru, který jej deklaruje, tvrdí, že je tím, čím se prohlašuje, a skládá se, neregistruje
- blokující Požadavek nikdy nepřestavuje kanonický stav a cache se nikdy nedůvěřuje bez testu ekvivalence
- blokující Co worker čte, je deklarováno jednou a nic mimo to se nečte ani neposkytuje
- blokující Nic, co klient zanechá, nezamkne jiného klienta
- blokující Testy běží v jednorázových repozitářích
- blokující Rozhraní ukazuje jen to, co je odvozeno, a neznámé se nikdy nevykresluje jako zdravé
- blokující Neznámé konfigurační klíče jsou chyby
- blokující Případ užití se dokazuje provedením a schopnost je pokryta případem užití
- blokující Webový povrch se deklaruje jednou a z něj se odvozují všechny webové projekce
- blokující Webový povrch se objeví od svého producenta a nikdy se neregistruje dvakrát
- blokující Provozní způsob selhání je objekt katalogu, nikdy stránka
- blokující Worktree branche je v <repo>-wt/<branch>, odvozený z gitu, nikdy neregistrovaný
Každé pravidlo, s validátorem, který o něm rozhoduje, a testem, který ho dokazuje →
doktrína
Implementace je podřízena záměru
Změna není dokončená proto, že byl napsán kód, prošly testy, byl sloučen pull request nebo uspělo nasazení. Je dokončená, když platí všechno z následujícího.
- výchozí záměr je znám
- relevantní kontext byl zvážen
- platná správa drží
- požadovaná implementace existuje
- dotčené povrchy jsou synchronizovány
- akceptační kritéria prošla
- tvrzení odpovídají implementaci
- chování za běhu se ověřuje tam, kde se uplatňuje
- dost důkazů k předvedení, že výsledek existuje
Zbytek argumentace
Každá významná změna by měla být vysvětlitelná
Záměr by měl nést svůj původ, své řízení, svá omezení, svou realizaci, své ověření a rozhraní, jichž dosáhl. To je to, co mění historii vývoje v něco, na co se lze ptát.
Místo “Proč tento kód existuje?” — “fix stuff” říká zodpověditelná historie
Tento subsystém existuje, protože záměr vyžadoval automatický bootstrap workera. Byl zaveden v těchto commitech, pod touto doktrínou, ověřen tímto testem, vystaven na těchto rozhraních a jeho stav ověření je aktuální.
Tracker přestává předstírat, že je sémantický model
Úkoly zůstávají užitečné. Milníky zůstávají užitečné. V tomto modelu se z nich stávají projekce záměru, ne místo, kde se záměr drží, a níže uvedené otázky se stávají nálezy místo vyšetřování.
- implementace bez aktivního záměru za ní
- záměr bez implementace
- úkol označený jako dokončený, zatímco jeho kritéria přijetí selhávají
- commit nepropojený se záměrem, kterému slouží
- milník tvrdící dokončení, zatímco závislé záměry zůstávají nevyřešené
Na žádnou z těchto otázek tracker odpovědět nedokáže, protože tracker drží práci, ne to, k čemu práce byla.
Graf práce, který tento repozitář vede, úkol po úkolu a milník po milníku →
Automatické. Podporované. Vynucované. Generované. Testované.
Repozitáře takovými slovy hromadí a jsou překvapivě nebezpečná. Tvrzení má cenu jen tehdy, když ho něco spojuje s důkazy. Zde každé tvrzení jmenuje zdroj, implementaci a test, které ho rozhodují, a tvrzení, jehož důkazy se už nerozlišují, shodí build.
Pak se změní buď implementace, nebo tvrzení. Vyhrává realita — v softwarové dokumentaci nezvyklá politika, to se musí nechat.
Index tohoto repozitáře jich obsahuje 250, každé pojmenovává zdroj, implementaci a test, které o něm rozhodují. Tvrzení, jehož důkazy se už nedají dohledat, shodí build dřív, než lze web publikovat; porovnat znění tvrzení s chováním, které popisuje, je tu stále úkol pro člověka.
Dokončení znamená splnění záměru
Kód napsán, testy zelené, PR sloučen: vše užitečné, nic z toho není důkaz výsledku. Sloučený pull request, jehož záměr zůstává nepravdivý, je nedokončená práce a git server není orákulum.
Smlouva tak, jak ji ukazuje README samotného repozitáře: zaznamenaný běh z výzvy, začerněný a jinak nedotčený, který build odmítne publikovat, pokud přestane odpovídat. Jeden řádek na kontrolu, každý uvádí, co dokázal; selhávající řádek nese příkaz, který ho reprodukuje, a dokud neprojdou všechny řádky, nic se nezapíše.
- 1scope
- 2ověření
- 3state
- 4blockers
- 5poznámka
Práce odchází jako completed jen tehdy, když projde každý řádek. Cokoli jiného dostane jméno, ne pokrčení rameny.
Neshoda je před nasazením levná a po něm drahá
Než se implementace přijme, měl by se druhý průchod pokusit ji vyvrátit. Je to disciplína, kterou model žádá, a tohle jsou otázky, které skutečně zachytí selhání.
- Pochopili jsme záměr špatně?
- Řeší to už existující implementace?
- Duplikuje to jiný subsystém?
- Které rozhodnutí ho omezuje?
- Na které okrajové případy a které povrchy se zapomnělo?
- Odpovídají testy požadavku, nebo jen implementaci?
- Může se to později tiše zhoršit?
Kde návrh stojí, tvrzení po tvrzení
Argument výše je doktrína a návrh. Kolik z něj existuje, na této stránce napsáno není: matice funkcí odpovídá funkci po funkci a rozhraní po rozhraní, tvrzení pod každou fází pipeline nesou stav, který deklaruje matice tvrzení, a stránka omezení jmenuje, co nástroj nedělá.
Příkazy, každý deklarovaný jednou
Každý příkaz je deklarován jednou a tato deklarace je tím, čeho jsou příkazový řádek, HTTP API, nástroje MCP i tento web projekcemi.
initupdatedoctorwatchstartcontextcheckpointhandovercheckfinishhistorydecisionquestionpromptevidenceskillscapturesearchdoctrineplanversionsessionknowledgeadrusecaserulesmigraterecoverbencharchive
Napsat jednou. Zobrazit všude.
Pravidlo, dovednost, rozhodnutí, případ užití, provozní okamžik, funkce: každé je jeden soubor pod vrstvou se schématem. Zjišťování ho najde, schéma ho validuje, index ho drží a každé rozhraní čte index. Nic nic neregistruje.
adr158application5area9audience8claim250command31context39critique29deployment1derive-offload1distribution-model1document350domain6feature29gap4implementation52intent33issue802knowledge50mesh-declaration1milestone100moment38policy1profile4prompt5release-record33rule189scope1session90skill8taxonomy10test567use-case49workspace1
Každý z nich je objevován deklarovanou třídou zdrojů, validován proti publikovanému schématu, držen v jednom indexu a čten každým rozhraním. Nic nic neregistruje. Schémata, jedno na druh →
Objevit jednou. Uvažovat jednou. Odvodit všude. Ověřit proti záměru.
Repozitář přestává být sbírkou částečně synchronizovaných artefaktů a stává se zkoumatelným modelem toho, co jsme chtěli, co jsme věděli, co jsme rozhodli, co se změnilo, proč se to změnilo, co to omezuje, zda to funguje a jak to víme.
Lidé definují záměr. Majordomus udržuje systém poctivý.
Tato stránka je projekcí repozitáře, který popisuje. Každá funkce, počet, poskytovatel, rozhraní a okamžik na ní vzešly ze stejného spustitelného souboru, který odpovídá agentům, a zastaralá stránka shodí build dřív, než ji lze nasadit.
Každá funkce Přečtěte si záruky Jak je tato stránka odvozena Zobrazit na GitHubu