Decyzje architektoniczne: dowody zamiast intuicji

AGENTS.md jako onboarding agenta: krótki, specyficzny dla repo, z najważniejszymi regułami na górze - przyszły agent czyta go raz i nie blokuje się. Każde zdanie musi wynikać z pliku, komendy albo commita, który skill faktycznie obejrzał.

Wejście: repozytorium - manifest, README, konfiguracja lint/test, układ katalogów, 30 ostatnich commitów. Wyjście: jeden plik AGENTS.md („Repository Guidelines") o budżecie 200-400 słów; wariant katalogowy jeszcze mniejszy (120-250 słów), bo opisuje reguły jednego katalogu, nie całego repo.

Discovery w ustalonej kolejności, potem ekstrakcja: 1-3 komendy, które agent uruchamia najczęściej, konwencje, które recenzent wytknąłby w PR, twarde zakazy „nigdy nie rób X". Gdy plik już istnieje - edycja chirurgiczna, nie przepisanie: każda linia klasyfikowana jako KEEP / UPDATE / REMOVE / MISSING na podstawie diffu od ostatniego dotknięcia pliku.

Sekcje uporządkowane według dźwigni, nie tradycji:

• twarde reguły i tripwires - zawsze na górze,
• struktura projektu i komendy build/test/dev,
• styl, nazewnictwo, testy, konwencje commitów.

Zamiast wklejania konfiguracji - referencje @package.json, @docs/...: dawka kontekstu dociągana na żądanie.

Pięć twardych bramek przed zapisem: budżet słów, zero wieloliniowych snippetów, każda reguła sprawdzalna na diffie („clean code" i „best practices" wylatują), zero wiedzy, którą agent i tak ma z treningu, reguły krytyczne w pierwszej jednej trzeciej pliku.

Odpowiedzieć dowodami na pytanie o kod projektu: równoległe subagenty przeczesują osobne wymiary, główny agent tylko syntetyzuje. Mapa powstaje z odczytów plik:linia, nie z przeczuć.

Wejście: pytanie badawcze plus pliki wskazane przez użytkownika - czytane w całości, zanim ruszy delegacja. Wyjście: research.md w folderze zmiany - samowystarczalny raport z odnośnikami do kodu, wnioskami architektonicznymi i otwartymi pytaniami.

Dekompozycja pytania na obszary → doprecyzowanie zakresu i głębokości → 2-4 subagenty równolegle w jednej wiadomości: Explore do szukania plików i wzorców, general-purpose do analizy złożonych systemów. Synteza zaczyna się dopiero, gdy wrócą wszyscy.

• Summary i Detailed Findings per komponent,
• Code References ze ścieżkami i numerami linii,
• Architecture Insights - wzorce i decyzje projektowe,
• kontekst historyczny z context/changes/ i context/archive/,
• Open Questions - co wymaga dalszego zbadania.

Research jest read-only - subagenty dostają zakaz edycji i obowiązek zwracania referencji plik:linia. Świeży odczyt kodu ma pierwszeństwo; historia zmian to kontekst uzupełniający, nie źródło prawdy.

Rozdzielić obserwację od deklarowanej przyczyny, zanim powstanie plan. Perfekcyjny plan na źle postawiony problem to stracony dzień: rozwiązanie trafia w hipotezę, a prawdziwy problem zostaje.

Wejście: zgłoszenie w kształcie „bug + proponowany fix", pytanie o zakres albo założenie do sprawdzenia. Wyjście: frame.md - potwierdzone lub przeramowane sformułowanie problemu z poziomem pewności (HIGH / MEDIUM / LOW) i wnioskiem dla /10x-plan.

Obserwacja zostaje zamrożona jako jedyny pewny grunt - wszystko inne to hipotezy. Powstaje mapa wymiarów, z których obserwacja mogła wyniknąć, a równoległe subagenty testują każdy z nich pytaniem: jakich dowodów byśmy się spodziewali, gdyby pękło właśnie tutaj - i czy one istnieją? Na końcu wiodąca hipoteza przechodzi próbę ciśnieniową - ocenia ją także świeży agent, któremu nie zdradza się faworyta.

Serce briefu to tabela hipoteza / dowód / werdykt (STRONG / WEAK / NONE). Obok: obserwacja, pierwotne założenie zachowane dosłownie, mapa wymiarów, sygnały zawężające i sekcja „co zmienia się dla planu".

Dozwolony wniosek brzmi także „założenie było trafne" - wymuszone przeramowanie jest gorsze niż brak frame'u. Pewnie brzmiąca hipoteza bez dowodu plik:linia to dokładnie ten błąd, przed którym skill chroni. Pytania zawężające opisują obserwacje, nigdy rozwiązania.

Zamienić zadanie w plan pocięty na etapy z jawnymi kryteriami sukcesu - automatycznymi i manualnymi - zanim powstanie pierwsza linijka kodu. Plan jest kontraktem: implementacja ma się do czego cofnąć.

Wejście: opis zadania, opcjonalnie frame.md i research.md - każdy artefakt z wcześniejszych kroków to decyzje już podjęte, więc mniej pytań. Wyjście: plan.md plus plan-brief.md - dwustronicowy skrót z tabelą kluczowych decyzji.

Research repozytorium subagentami → ocena złożoności (LOW / MEDIUM / HIGH) potwierdzona z użytkownikiem → skalowane dopytywanie: 4-15 pytań, każda opcja z rekomendacją oraz jawną siłą i kosztem → akceptacja szkieletu etapów → dopiero wtedy pełny plan.

Stan obecny, stan docelowy, „czego NIE robimy", etapy z parą Intent / Contract dla każdej zmiany, kryteria Automated / Manual, na dole sekcja Progress - jedyne miejsce, gdzie żyją checkboxy.

Plan opisuje intencję, nie implementację - snippet kodu tylko przy zmianie nieoczywistej. Zero otwartych pytań w finalnym planie. Po każdym etapie pauza na ludzkie potwierdzenie weryfikacji manualnej, zanim ruszy następny.

Sformalizować terminologię domeny w jeden spójny glosariusz: jedno pojęcie - jedna nazwa. Synonimy i wieloznaczności wyłapane, zanim rozmyją model i oderwą kod od rozmowy.

Wejście: rozmowa o domenie - sesja modelowania, dyskusja o wymaganiach. Wyjście: UBIQUITOUS_LANGUAGE.md - tabele terminów z definicjami i aliasami do unikania, relacje, przykładowy dialog i sekcja zgłoszonych wieloznaczności.

Skan rozmowy pod kątem pojęć → wykrycie dwóch klas problemów: to samo słowo dla różnych pojęć i różne słowa dla tego samego pojęcia → stanowczy wybór terminu kanonicznego → jawne flagowanie konfliktów z rekomendacją.

Termin, definicja w jednym zdaniu (czym pojęcie JEST, nie co robi), aliasy do unikania. Relacje z kardynalnością: „Invoice należy do dokładnie jednego Customer". Do tego krótki dialog dev / ekspert domeny, który pokazuje granice pojęć w naturalnym użyciu.

Tylko terminy istotne dla eksperta domeny: nazwy modułów, klas i generyczne pojęcia programistyczne (array, endpoint) nie wchodzą, chyba że niosą znaczenie domenowe. Definicje ciasne - maksymalnie jedno zdanie.