Implementovat změnu

Účel

Proveďte inženýrskou změnu tak, jak ji tento repozitář žádá: zjistěte, co je pravda, než se čehokoli dotknete, pojmenujte invariant, který změna zachovává nebo opravuje, rozhodněte, co bude moci volající pozorovat, dokažte to zvenčí, proveďte nejmenší správnou změnu a nechte každý odvozený povrch sesouhlasený. Pořadí je podstatou. Pracovník, který napíše nejdřív mechanismus a invariant najde potom, dodá cokoli, co mechanismus náhodou dělal.

Toto není stylový průvodce, není to licence k refaktoringu všeho v okolí změny a není to správce úkolů. Je to protokol mezi „změň X“ a „X je změněno, tady jsou důkazy“.

Kdy použít

Jakákoli změna stromu, která je víc než překlep: vada, funkce, refaktoring, změna výkonu, přidání generovaných dat nebo katalogu, migrace, adaptér poskytovatele, změna CI nebo nástrojů. Před zahájením spusťte repo-review nad rozsahem, pokud stav této části stromu ještě neznáte; zjištění z posouzení jsou tu prvním vstupem.

Ne tato dovednost: revize bez změn (repo-review) nebo rozhodování, zda se změna má vůbec provést.

Postup

Procházejte fázemi v pořadí; každá vytvoří něco, co čte další. Zaznamenejte invariant, pozorovatelné chování a plán důkazů dřív, než napíšete mechanismus, do checkpointu nebo předávky úlohy, aby je další worker (nebo tentýž po přerušení) neodvozoval znovu.

1. Stanovte rozsah

Uveďte požadovaný výsledek jednou větou, výslovná kritéria přijetí a kritéria, která pravidla repozitáře přidávají implicitně. Klasifikujte změnu (defekt, funkce, refaktoring, výkon, dokumentace, generovaná data, migrace, integrace poskytovatele, CI, architektura) a odpovězte: mění se veřejné chování, mění se sémantika persistence nebo stavu, jsou dotčeny generované projekce, je zapojen poskytovatel, záleží na kompatibilitě. Deklarujte cesty, kterých se práce smí dotknout (majordomus start --scope), a nerozšiřujte je potichu; lze-li požadavek splnit bez nového subsystému, splňte jej bez něj. Pokud požadované chování už existuje, ověřte je místo jeho opětovného budování.

2. Načtěte příslušný kontext

Čtěte to, co se vztahuje na cesty v rozsahu, a nic víc: kořenové instrukce, platná pravidla (majordomus rules list, s poznámkou, která jsou vynucována strojově), dokumenty s rozsahem od kořene dolů (majordomus context resolve <path>), architektonická rozhodnutí dotýkající se subsystému, existující testy, okolní implementaci a veřejnou dokumentaci, která o chování činí tvrzení.

3. Prozkoumat před mutací

Přečtěte si aktuální implementaci, její volající, sousední abstrakce, testy, veřejná rozhraní, generované konzumenty jejího výstupu, konfiguraci a diagnostiku. Přečtěte si historii souborů tam, kde mění rozhodnutí: proč abstrakce existuje, zda je kód přechodný, zda už dřívější oprava řešila stejnou vadu, zda je podezřelý vzor záměrný. Historii nečtěte pro ceremonii; čtěte ji tam, kde mění, co byste udělali.

4. Pojmenujte kanonickou pravdu

U každého artefaktu, kterého se změna dotýká, řekněte, co to je: kanonický, generovaná projekce, cache, stav za běhu, perzistovaný stav, externí stav, dokumentace nebo testovací fixture. Před úpravou najděte zdroj každého odvozeného artefaktu a nikdy neopravujte generovaný drift úpravou generovaného souboru. Dva soupeřící kanonické zdroje jsou architektonická vada; opravte směr odvozování, místo abyste kopie ručně sjednocovali.

5. Uveďte invariant

Zapište jednou falsifikovatelnou větou invariant, který změna zavádí, zachovává nebo opravuje — „pro každý platný <x> existuje právě jeden <y> a každá projekce je z něj odvozena“, „mutace se hlásí jako úspěšná až poté, co je její záznam trvalý“, ne „zlepšit načítání“. Kde žádný invariant neplatí, uveďte místo něj pozorovatelné chování. Pro triviální změnu invariant nevymýšlejte.

6. Definujte pozorovatelné chování

Před implementací řekněte, co uvidí uživatel, test, volající z příkazové řádky, klient MCP nebo pozdější čtenář záznamů: šťastnou cestu, cestu selhání, hraniční podmínky, částečné selhání a restart tam, kde platí, idempotenci, neplatný vstup, chybějící závislost nebo schopnost providera, zastaralé projekce, návratový kód a strojově čitelnou podobu. Tento seznam se stane behaviorálním testem. Implementační detail ho nenahrazuje.

7. Definujte sémantiku selhání

U každé operace, která může selhat, odpovězte: co selže, na jaké hranici, co zůstane zmutované, co je perzistováno, zda je opakování bezpečné, zda je operace idempotentní, zda lze částečný výsledek zaměnit za úspěch, zda je selhání typované a rozlišitelné, zda je degradované chování výslovné a zdokumentované a zda je zastaralý stav detekovatelný. Nikdy nenechávejte spolknutou chybu, tichý návrat ke slabší sémantice, průchod, který nezkoumal nic, úspěch hlášený před trvanlivostí ani mock, který dokazuje hranici, již obchází.

8. Zmapujte povrch dopadu

Vyjmenujte každý povrch, kterého se změna může dotknout — kanonická data a schéma, implementace, příkazová řádka, MCP, generované projekce, dokumenty, web, diagnostika, konfigurace, CI, měření výkonu, adaptéry providerů, příklady, rozhodnutí — a označte, kterých se skutečně dotýká. Upravte ty a jen ty; seznam existuje, aby se nezapomnělo na žádný odvozený stav, ne aby vyráběl práci.

9. Rozhodni o důkazech dřív než o mechanismu

Zvolte, jak se chování prokáže: nejprve behaviorální black-box, pak integrační, pak kontraktní a nakonec cílené unit testy. Defekt se reprodukuje, nebo se napíše regresní test, který by před opravou selhal. Property-based testy patří tam, kde invariant platí přes mnoho vstupů (parsery, normalizace, deterministické generování, idempotence, bezpečnost cest, rekonciliace), ne jako dekorace. Pokud je změnou tvrzení o výkonu, zaznamenejte nejprve základní hodnotu, zátěž a metriku.

10. Implementujte nejmenší správnou změnu

Použijte abstrakci, která už invariantu odpovídá; rozšiřte mechanismus řízený daty, místo abyste přidávali napevno zapsanou větev; nepřidávejte závislost bez zapsaného přesného problému, který řeší, alternativ, které už strom obsahuje, její stopy a ceny nahrazení; nepřidávejte službu, frontu ani úložiště, které požadavek nevyžaduje; nepřidávejte rozšiřující bod pro dosud neprokázanou potřebu; odstraňte mrtvou přechodnou cestu jen tehdy, když je v rozsahu a bezpečné. Udržujte strom neutrální vůči providerům: rozdíl specifický pro providera patří do adaptéru a schopnost, kterou provider nezpřístupňuje, se reprezentuje jako nedostupná, nikdy vymyšlená. Předchozí řešení lze konzultovat a nikdy se na nich nezávisí: pochopte požadavek, pojmenujte invariantu, zahoďte předpoklady zdroje, navrhněte rozhraní, jaké by měl tento repozitář, a implementujte nezávisle.

11. Ověřujte po vrstvách

Po každé ucelené vrstvě: zformátovat dotčený kód, spustit cílené testy, spustit dotčenou validaci, přečíst chybové zprávy a pokračovat, jen když vrstva drží. Nehromadit nesouvisející změny a nezjišťovat na konci, která z nich rozbila parsování.

12. Sladit odvozený stav

Po kanonické změně spusťte generování repozitáře a poté jeho kontroly driftu (majordomus generate, scripts/generate-site-data, pak jejich formy --check a majordomus doctor) a commitněte regenerované výstupy se změnou, která je způsobila. Generování je deterministické, vlastní svůj výstup a nikdy se nesmí nahradit ručně synchronizovanou kopií.

13. Aktualizujte diagnostiku

Kde změna přidává nebo mění provozní chování, dejte doctor, check nebo watch nález, který rozlišuje nakonfigurované, objevené, zapojené, dosažitelné a sladěné, jak se na ně vztahuje, hlásí, co zkoumal, a nikdy neuspěje nad ničím.

14. Zdokumentujte, co je dokázáno

Dokumentace následuje důkazy. Aktualizujte dokumenty, které činí tvrzení o změněném chování, a jen na to, co testy nyní dokazují; zachovejte rozlišení mezi plánovaným, implementovaným, ověřeným a zaručeným a přidejte do matice tvrzení s jeho zdrojem, implementací a testem, když je změnou schopnost. Dávejte přednost invariantům, příkazům, pozorovatelnému chování, chování při selhání a příkladům před popisem. Publikované příklady držte spustitelné a promítejte je, nekopírujte.

15. Spusťte širší ověření

Spusťte sadu, která pokrývá rozsah, kontroly generování a driftu, build webu tam, kde web změnu čte, a kontroly rovnocenné CI, které repozitář jmenuje. Výsledek, který jste nepozorovali, není důkaz.

16. Zrevidujte diff

Přečti celý diff tak, jak by ho četl recenzent, podle kontrolního seznamu repo-review: správnost, invariant, chování při selhání, kanonický vs. generovaný stav, duplicitní pravda, ruční registrace tam, kde existuje odvození, únik poskytovatele, kvalita testů, diagnostika, tvrzení v dokumentaci, drift, regrese výkonu, zbytečná abstrakce a rozsah, který se rozlezl. Oprav, co je podstatné, než budeš pokračovat.

17. Commitujte souvislou práci

Jeden commit na nezávisle srozumitelnou, ověřenou změnu, v konvenci zpráv repozitáře; ani jeden commit na všechno, ani commit na každý úhoz. Před každým commitem procházejí příslušné testy, formátovač a linter, generované projekce jsou sladěné a není přítomen žádný nevysvětlený soubor.

18. Stop

Přestaňte rozšiřovat, když je požadované chování pozorovatelné, invariant platí, důkazy projdou, projekce souhlasí a dokumentace je přesná. Možné vylepšení, neelegantní soused nebo nesouvisející položka plánu rozvoje se zaznamená jako otázka nebo úkol, ne implementuje „když už tu jsem“.

19. Report

Zapište záznam ve tvaru uvedeném pod Output. Nehlaste úspěch jen proto, že se soubory změnily.

Výstup

Záznam implementace, stručný, s těmito sekcemi v tomto pořadí:

Každé tvrzení v záznamu je pozorovaný fakt, odvození nebo doporučení a je označeno, pokud není faktem. Žadatele se ptejte jen tehdy, když důsledná nejednoznačnost nejde rozřešit z repozitáře, jeho historie a testů a špatný odhad by postavil špatné chování; jinak raději volte vratnou možnost a jednejte.