Розділ 12. Нормативна база¶
Цю книжку я пишу з агентом. У розділі 2 він написав «управління» — я виправив на «керування». У розділі 6 — виправив знову. Після третього разу це стало рядком у стайлгайді книжки, і далі слово не з’являлось.
У розділі 13 я порахував, скільки разів у тексті трапилось слово «зелений»: двадцять чотири. Кожне окремо було доречним — «зелений прогін», «зелена галочка». Разом — двадцять чотири згадки зеленого на один розділ. Ще один рядок у стайлгайді: «зелений» лише там, де він конкретний.
Стайлгайду не було до першого розділу. Він ріс із правок: зустрів — поміняв; зустрів ще раз — поміняв; на третій раз записав. Зараз у ньому триста рядків, і жодного я не придумав наперед. Кожен — моє зауваження, яке повторилось.
Що відрізняє знахідку від норми? У розділі 2 я назвав нормативну базу підсилювачем — різноманіттям, законсервованим у текст, — і пообіцяв окремий розділ. Ось він.
Двічі — збіг, тричі — клас¶
Норма з’являється не з одної ситуації, а з повторення.
Один вдалий результат — це все-таки поки один результат, і в ньому відбиток усього, що було навколо: вашого формулювання, часу дня, того, скільки ви встигли прочитати. Людина як прилад нестабільна: та сама задача, та сама людина, вранці і ввечері — різні відповіді. Тому з одного результату не видно, що в ньому ваше рішення, а що збіг обставин. Порівняйте три — і те, що збереглось у всіх трьох, і є рішення. Решта — шум.
Звідси визначення. Норма — це записана реакція з інструкціями на клас ситуацій, які у вас повторюються. Ключове слово — клас. Один випадок — випадок. Два — збіг. Три — клас, і відповідь на нього варто записати, бо буде й четвертий.
Поки норми немає, «добре» на рев’ю — думка, і в кожного своя: три рев’ювери на один пул-реквест дадуть три оцінки, і всі три обґрунтовані. Записана норма перетворює оцінку на порівняння: ось із чим рівняємо, ось відхилення. Наступний розділ, про контроль, будуватиме на цьому зону допуску: норма каже, що правильно, контур перевіряє, чи процес не вийшов за її межі.
І ще одне: норма повертається в практику. Практика — усталений спосіб працювати з агентом: промпти, перевірки, звички команди. Практика створює норми, а норми ведуть практику далі. Це замкнене коло.
Кухня¶
Уявимо кухню ресторану о шостій вечора.
Лінійний кухар ставить стейк на пательню. Він не куштує, не прикидає і не радиться: на стіні картка. Стейк, двісті п’ятдесят грамів; пательня розігріта до першого диму; дві хвилини на бік; потім п’ять хвилин відпочити під фольгою, щоб сік не витік на дошку; готовий — скоринка темна, всередині п’ятдесят чотири градуси за термометром. Шефа на кухні немає, але стейк на смак такий самий, ніби його готував сам шеф.
Цю картку не написали в день відкриття. Шеф зробив цей стейк сотні разів — на цій плиті, з м’ясом від цього постачальника — так він виділив, що в процесі стале і може бути формалізоване, а що — емоційний фон. Так з’явилась картка-інструкція. У ній чотири блоки: назва страви; що робити, крок за кроком; навіщо — «відпочити, щоб сік не витік»; і як перевірити, що вийшло, — термометр, а не «на око». Шеф виділив це все з нескінченного різноманіття варіантів готування, і тепер воно спрацьовує кожного разу без нього. Нова точка мережі відкривається з папкою карток, а не з шефом.
А тепер сцена домашня.
Ми купуємо товсту книгу відомого шефа — шістсот сторінок, тверда обкладинка — і думаємо стати великим кухарем. Готуємо з неї один рецепт. Найімовірніше — жодного. Книга стоїть на полиці, і ми час від часу торкаємось її поглядом із теплим відчуттям. Я знаю це з власної полиці.
Що ми купили? Не норми — бажаний стан. Рецепт у книзі і картка на кухні виглядають однаково: ті самі чотири блоки, ті самі грами й хвилини. Різниця не в тексті. За карткою — сто вечорів на цій кухні. За рецептом — сто вечорів на чужій. Книга обіцяє, що чужі повтори замінять наші.
І ще одна деталь із кухні. Картку писали під ту плиту. Поставили нову, індукційну — і «дві хвилини на бік» дають інший стейк. Картка та сама, кухня інша.
Чому норма працює без вас¶
Тепер механізм роботи норми — три складові.
Перша — арифметика розділу 2. Норма — це розрізнення, винесене з голови назовні. Поки воно в голові, воно працює, доки ви уважні і доки пам’ятаєте. У файлі — працює, коли ви втомлені, у відпустці, коли за клавіатурою колега або працює агент. Кожна записана норма — плюс один стан, який розрізняє вже не ваша увага, а записаний текст. Ви написали її раз, а спрацьовує вона в кожній сесії — і в кожній сесії кожного з команди.
Друга складова — про розуміння. Розділ 10 показав: частину діяльності «зрозуміти» не можна віддавати AI. Норма з блоком «чому» переносить шматок розуміння через межу сесії: наступного разу його читають, а не відтворюють з нуля. «Не пишемо down-метод у міграціях, бо відкат у нас робиться зі знімка бази» — і людина, яка бачить цей рядок уперше, знає не тільки що, а й чому така норма існує. Норма без «чому» переносить лише припис. Її можуть виконувати і після того, як причина зникла, — і ніхто не помітить, що вона вже не актуальна.
Третя складова — про агента. Колега читає стайлгайд раз, під час онбордингу, і за тиждень пам’ятає з нього три рядки. Це нормально: у колеги є голова, і решту він відновить із контексту. Агент читає нормативну базу на початку кожної сесії і виконує буквально — так само буквально, як «поправ тест» у розділі 6. Тому норма для агента множить усе, що в ній записано: і рішення, і помилки. Приклад «так/не так», який для людини звучав би педантично, для агента — єдина робоча форма: він не здогадається, що ви мали на увазі.
Умова, без якої три складові не працюють. Норма має бути в сесії. Це межа контексту: що в сесії — те і в грі, агент бачить лише те, що йому показали, — відкриті файли, вставлений текст, інструкцію на вході. Стайлгайд на вікі, на який ніхто не дав посилання, для агента не існує — норма, якої немає в сесії, не керує нічим.
Що робить запис нормою¶
Чотири блоки — ті самі, що в картці на кухні. Покажу на одній нормі з реального файлу пам’яті проєкту.
Ситуація. Коли це застосовувати — клас, названий явно: «у міграціях бази даних». Норма без «коли» діє або скрізь, і тоді це шум, або ніде, і тоді це побажання.
Рішення. Що робити, конкретно і для буквального читача: «down-метод не пишемо; кожному індексу — явна назва за шаблоном idx_<таблиця>_<поля>». Один приклад «так», один «не так».
Чому. Одним рядком: «відкат робимо зі знімка бази, тому down-метод не виконується ніколи, а автоматичні назви індексів у двох середовищах відрізнялись і зламали деплой». Цей блок дає перевірити за пів року, чи норма ще потрібна: зникла причина — знімайте норму, змінилась — перепишіть.
Перевірка. Як дізнатись, що виконано: «лінтер міграцій у CI падає на down-методі і на індексі в хибному форматі». Тут норма зі слів переходить у структуру — це те саме лікування мегапромпта з розділу 2, тільки тепер зрозуміло, звідки беруться рядки для винесення в структуру.
У стайлгайді цієї книжки кожен рядок записаний так само: що було, на що поміняли, чому. Без «чому» я сам через два розділи не пам’ятав би, навіщо заборонив слово.
Де живе норма¶
Одна й та сама норма може жити в чотирьох місцях, і від місця залежить, чи виконається вона без вас. Тест для кожного рівня один: що станеться з нормою, якщо завтра ви не прийдете?
У голові. Ви знаєте, як треба, і пояснюєте агентові щоразу. Норма є, але вона — ви. Щоразу з нуля: варіант, у якому шеф куштує кожну страву перед подачею гостю. Завтра без вас — норми немає.
У промпті. Ви скопіювали вдалу інструкцію собі в нотатки і вставляєте на початку сесії. Уже відтворюється — але лише вами і лише коли згадали. Блокнот шефа в кишені. Завтра без вас норми теж немає, але хоча б є текст, який можна знайти.
У проєкті. Файл пам’яті проєкту, системний промпт у чаті, навик в агенті, README, який кажуть прочитати спершу, — усе це форми одного: тексту, який агент читає перед роботою. Тут норму читає кожна сесія і кожен колега — і це перший рівень, на якому норма виконується без вас. Папка карток на кухні.
У конструкції. Лінтер, тест, шаблон, перевірка в CI. Норма більше не текст, який можна прочитати й проігнорувати, — неприйнятний стан не проходить фізично. Термощуп у стейку, який пищить на п’ятдесяти чотирьох градусах. Це послаблювачі з розділу 2, і тепер видно їхнє походження: кожен із них починався як норма в чиїйсь голові.
Чи має кожна норма дійти до конструкції? Ні. Норма в конструкції коштує гнучкості — це бюджет контролю з розділу 2: затиснули один вимір — розтягнувся інший. Що жорсткіше правило, то дорожче його міняти. У конструкцію іде те, де помилка дорога і незворотна: дані, доступи, публічні інтерфейси. Тут і поріг «тричі» знижується: якщо помилка один раз зламала деплой, другого разу не чекають. Норми смаку — назви, стиль коментарів, порядок імпортів — можуть лишатися текстом. Жорстке внизу, м’яке вгорі.
Як виміряти, де зараз ваша практика на цій шкалі? Візьміть останні десять зауважень, які ви зробили агентові на рев’ю, і поставте три питання. Скільки з них ви робили вже не вперше? Скільки з них записано так, що їх читає кожна сесія? Скільки перевіряється без вас? Три числа — і це профіль вашої нормативної бази. Коли я вперше порахував свій, вийшло: сім, нуль, нуль.
Історія одного файлу з нормами¶
Команда взяла на підтримку легасі-сервіс білінгу — той, який усі бояться чіпати.
Місяць перший. Рев’ю коду, який пише агент, перетворюється на повторення. За тиждень я записав тридцять зауважень, і двадцять два з них — повтори п’яти класів: зайва залежність замість утиліти проєкту, міграція з безіменним індексом, тест, що мокає базу, print замість логера, ендпоінт списку без пагінації. Наперед ми б їх не виділили — загубились би серед правил, написаних «про всяк випадок». П’ять норм записуємо у файл пам’яті проєкту.
Місяць другий. Зауважень за тиждень — шість замість тридцяти, і три з них — нові класи, які за місяць встигли повторитися: виклик платіжного шлюзу без таймауту, секрет у конфігу замість змінної оточення, нова фіча без фіча-атрибута. Записали і їх — у файлі вісім норм. Одну зняли: блок «чому» показав, що після переїзду в Kubernetes, де збирач логів читає все, що сервіс виводить у консоль, причини для норми про print більше немає. Лишилось сім. Дві з них переїхали в конструкцію — лінтер міграцій і перевірка залежностей у CI, — а п’ять лишаються текстом і виконуються, бо агент читає файл на початку кожної сесії.
Місяць третій. Новий інженер першого дня зробив пул-реквест без жодного з семи зауважень. Файл пам’яті він прочитати не встиг, а агент — прочитав.
Це і є «норми виконуються без мене»: сім розрізнень переїхали з моєї голови в процес у вигляді норм, і тепер вони є в кожній сесії кожного, хто відкриє цей репозиторій.
Велика кулінарна книга¶
Анти-патерн цього розділу виглядає як прискорення.
Команда бере «найкращий набір скілів» з GitHub — чотириста рядків, тисячі зірочок. Або копіює стайлгайд великої компанії. Або — інший бік того самого — сідає перед стартом і пише норми наперед, «як має бути»: двадцять правил на повтори, яких ще ніхто не бачив. Файл готовий у перший день. Виглядає як професіоналізм.
За жодним із чотирьохсот рядків немає пройденого шляху: ні моменту «зустріли», ні «поміняли», ні «поміняли ще раз». Норма — відповідь на ваш клас ситуацій, який повторився; без реальних повторів це не норма, а бажання чи навіть припущення.
Що відбувається далі — передбачувано. Агент виконує чужі рядки буквально: він не знає, що вони не ваші. Разом із чужими нормами приходять чужі дефекти — правило «завжди використовуй бібліотеку X» із проєкту, де для цього була причина, у вашому проєкті затягує залежність, яку ви ніколи не вибрали б. А власні повтори лишаються незаписаними, бо «у нас же є стайлгайд». Ознака проста: спитайте команду, від якого випадку захищає будь-який рядок файлу. Якщо ніхто не пам’ятає — це рядок із чужої книги.
У системній теорії є закономірність, яка пояснює, чому так виходить: людина в діяльності керується цінностями, які створила її ж практика. Практика народжує норми, а норми ведуть практику далі. Це те саме замкнене коло, з якого почався розділ.
Скільки б дисципліни команда ні вклала у виконання чужих рядків, власних повторів це не додасть.
Лікується це не видаленням файлу. Спершу варто порахувати власні повтори, як у секції «Де живе норма»: взяти останні десять зауважень агентові і з’ясувати, скільки з них повторювались, скільки вже записані і скільки перевіряються без вас. Потім чужий файл читається як список кандидатів: рядок лишається, якщо відповідає на повтор, який у вас справді був; решта переїжджає у «поки не траплялось» або зникає. Чужу книгу читати можна і варто — як джерело ідей, кожна з яких ще має заслужити місце повтором на вашій кухні. Що саме переноситься між проєктами, а що ні — розмова розділу 16.
Нормативна база масштабується¶
Агент читає нормативну базу до старту, і це його єдине «зрозуміти» перед роботою. Як збудувати агента на нормах, критеріях і контурі контролю — розділ 14.
Команда — наступний рівень. Онбординг — це читання нормативної бази, і командна норма відрізняється від особистої одним: вона лишається, коли пішов той, хто її знайшов. Про це — розділ 17.
Механіка на всіх рівнях одна: розрізнення, яке повторилось, переїжджає з голови в процес — і далі працює без вас.
У вашому ремеслі¶
Норми не знають, що таке код. Картка на кухні є в кожному ремеслі.
Текст. Редактор щоразу руками виправляє в тексті агента «управління» на «керування». Поки так, норма живе в голові редактора. Коли заміна записана в стайлгайд і агент читає його перед роботою, норма вже в проєкті. А коли скрипт сам проганяє готовий текст на заборонені слова, «управління» не пройде, навіть якщо редактор у відпустці. Стайлгайд цієї книжки виріс саме так.
Аналітика. Що таке «активний користувач»? Поки визначення не записане, три аналітики дадуть три різні числа, і кожен буде правий. Записане визначення метрики — це норма в проєкті: агент рахує за ним, а не вигадує своє. А коли поруч стоїть тест на дані, який падає, щойно хтось рахує інакше, норма спрацьовує сама, навіть якщо визначення ніхто не відкривав.
Дизайн. Дизайнер щоразу пише агентові: «бери тільки наші кнопки і відступи, кратні восьми». Поки так, норма живе в голові дизайнера. Коли ці правила записані в гайдлайн і агент читає його перед кожним макетом, норма вже в проєкті. А коли зібрана дизайн-система з готовими компонентами, іншої кнопки агент узяти просто не може, навіть якщо про правило ніхто не згадав.
Наостанок — три питання до вашої практики.
— Візьміть останні десять зауважень, які ви зробили агентові: скільки з них ви робили вже не вперше?
— Яка норма у вашому проєкті виконається завтра, якщо ви не прийдете, — і яка не виконається?
— І глибше: чи є у вашому файлі пам’яті проєкту рядок, про який ніхто не пам’ятає, від якого випадку він захищає?