Когато документацията се превръща в склад на хаоса

Представи си следното: започваш нов проект с чист CLAUDE.md файл. Хвърляш няколко полезни съвета. Добавяш малко контекст. Предупреждение за онзи странен edge case в логиката за автентикация. Месеци по-късно отваряш файла и виждаш цял роман от противоречиви инструкции, остарели напомняния и отчаяни приложения, които вече никой не разбира.

Това не е само твой проблем. Това е универсално явление.

Проучване, обхващащо 247 694 живота на инструкции в 1 867 хранилища, разкрива стряскаща тенденция: agentic промптовете не просто растат — те растат без граници, повече от утроявайки се през целия си жизнен цикъл (+226%). Средно тези файлове печелят +4.9 нови инструкции при всяко едно commit. Файлът никога не намалява. Само се разширява.

Но ето какво прави това наистина интересно: колкото по-стара е инструкцията, толкова по-малко вероятно е да бъде изтрита. Данните показват log-hazard от -0.032 на commit, което означава, че инструкциите стават все по-безсмъртни с времето. Не е, че никой не иска да почисти — просто никой не знае дали може безопасно да премахне каквото и да било.

Проблемът O(2^|D|)

Защо се случва това? Изследователите го наричат „катастрофално помнене" — обратното на познатия проблем с „катастрофалното забравяне" в машинното обучение. Но не ти трябва PhD, за да схванеш логиката.

Помисли за изчислението на разходите: добавянето на нова инструкция е евтино. Виждаш проблем, записваш решение, продължаваш напред. Непосредствената цена е ниска, а възприетата полза — ясна.

Но премахването на инструкция? Това е съвсем друга работа. Трябва да разбереш всяко място, където тази инструкция може да има значение. Трябва да премислиш взаимодействията с всички останали инструкции. Трябва да провериш, че премахването ѝ няма да счупи нещо фино и важно. Изследователите изчислиха този когнитивен разход като O(2^|D|) в промпт с |D| инструкции — растящ експоненционално с броя на съществуващите инструкции.

Така че разработчиците правят това, което рационалните хора правят: спират да се опитват. Нови инструкции се добавят. Старите остават. Файлът расте.

Коментарите: Непризнатият герой

Тук става наистина интересно. Решението не са по-добри техники за писане на промптове или по-умни модели. Това е нещо, което разработчиците използват от зората на програмирането: коментари.

Изследователите приложиха интересен подход — инвертираха IFEval, стандартен бенчмарк, за да създадат „проверяеми светове", където оптималните промптове са известни. Когато добавиха коментари, кодиращи латентното разсъждение, прекомерният растеж на инструкциите падна от +211.3% до едва +1.4%.

Това е 99.3% намаление.

Но истинската същност? Тези коментари не просто ограничиха растежа — те подобриха действителната работа по следване на инструкции с до 23.1% при реални задачи. Коментарите не са организационна плетеница. Те са носещи конструкции, които помагат на AI асистентите да разсъждават правилно върху контекста.

Защо е важно сега

Живеем през фундаментална промяна в това какво означава „код". Изследователите задават провокативен въпрос: „Ако английският е новият код, защо все още нямаме коментари?"

Има смисъл. Десетилетия наред разработчиците са разбирали, че код без коментари е технически дълг. Коментарите обясняват „защо", а не само „какво". Те улавят намерението, edge cases и институционално знание, което не може да се изведе от синтаксиса сам по себе си.

А в нашия бяг да прехвърлим все повече задачи на AI coding асистенти, ние третираме естествения език като че ли е различен. Пишем императиви — направи това, не прави онова, не забравяй да провериш X — без да обясняваме разсъжденията си.

Резултатът е това, което виждаме в онези подуващи се CLAUDE.md файлове: инструкции, които никой не разбира напълно, които може да си противоречат и растат без механизъм за рационализиране.

Пътят напред

Ако поддържаш CLAUDE.md или подобен agentic промпт файл, ето какво сочи изследването:

1. Коментирай инструкциите си, не само кода си. Обясни защо съществува дадено правило. Документирай edge cases. Улавяй разсъжденията зад решенията.

2. Приеми периодично рационализиране. Не просто добавяй — пренаписвай. Изследването изрично отбелязва, че цялостните пренаписвания са едно от малкото неща, които спират растежа.

3. Отнасяй се към AI инструкциите си като към documentation за onboarding. Бихте ли дали на нов разработчик 400-редов файл с недиференцирани правила? На вашия AI асистент се полага същата яснота.

Траекторията, по която сме, не е устойчива. Всеки нов проект започва с добри намерения и завършва с неподдържаема бъркотия. Но поправката може да е по-проста, отколкото си мислехме: пиши за човека (или AI), който ще чете инструкциите ти след шест месеца, а не само за този, който отговаря на въпроса ти днес.

Коментарите не са плетеница. Те са архитектурата на разбирането.