Оригінальна назва: Правила Karpathy’s 4 CLAUDE.md зменшили помилки Claude з 41% до 11%. Після 30 кодових баз я додав ще 8
Автор оригіналу: @Mnilax
Компиляція: Peggy, BlockBeats

Редакторський коментар: у січні 2026 року Анджей Карпатьї висловив скаргу на спосіб написання коду Claude, що привело до появи файлу, який здається дуже малим, але вкрай важливим у робочому процесі AI-програмування: CLAUDE.md. Forrest Chang згодом систематизував ці проблеми у 4 правила поведінки, щоб обмежити поширені помилки Claude під час кодування: мовчазні припущення, надмірна інженерія, випадкові пошкодження несуміжного коду та відсутність чітких критеріїв успіху.

Через кілька місяців сценарії використання Claude Code вже не обмежувалися лише «написанням коду моделлю». З появою багатоступеневих агентів, ланцюгів hook, завантаження навичок і співпраці між кількома кодовими базами, почали з’являтися нові моделі невдач: модель виходить з-під контролю у довгих завданнях, проходить тестування, але не перевіряє реальну логіку, пропускає помилки мовчки після міграції, змішуються різні стилі коду.

Автор цієї статті за 6 тижнів протестував 30 кодових баз і додав 8 нових правил до існуючих 4 правил Karpathy, щоб охопити нові проблеми, що виникають у AI-програмуванні після переходу від одноразового доповнення до агентної співпраці.

Нижче наведено оригінал:

У січні 2026 року, наприкінці місяця, Анджей Карпатьї опублікував серію твітів, у яких висловив скарги на спосіб написання коду Claude. Він виділив три типи типових проблем: робити неправильні припущення без пояснення, надмірно ускладнювати рішення та завдавати шкоди несуміжному коду, який не потрібно змінювати.

Forrest Chang побачив цю серію твітів і систематизував скарги у 4 правила поведінки, записав їх у окремий файл CLAUDE.md і опублікував на GitHub. Цей проект за перший день отримав 5828 зірок, за два тижні — 60 000, а зараз має понад 120 000 зірок, ставши найшвидше зростаючим односторінковим репозиторієм у 2026 році.

Після цього я за 6 тижнів протестував його на 30 кодових базах.

Ці 4 правила дійсно ефективні. Помилки, які раніше траплялися з ймовірністю близько 40%, у задачах, де ці правила працюють, знизилися до менше ніж 3%. Але проблема в тому, що цей шаблон був спочатку створений для вирішення помилок, що виникали у січні при написанні коду Claude.

До травня 2026 року екосистема Claude Code вже стикнулася з іншими проблемами: конфлікти між агентами, ланцюги hook, конфлікти завантаження навичок і переривання багатоступеневих робочих процесів між сесіями.

Тому я додав ще 8 правил. Нижче наведено повний варіант CLAUDE.md із 12 правилами: кожне з них — чому воно важливе і де оригінальний шаблон Karpathy може не працювати у 4 ключових випадках.

Якщо ви хочете пропустити пояснення і одразу скопіювати, повний файл — наприкінці статті.

Чому це важливо

CLAUDE.md у системі AI-програмування — найнедооціненіший файл. Більшість розробників роблять три типи помилок:

Перша — сприймати його як смітник для переваг, куди звалюють усі свої звички, і в результаті доводять довжину до понад 4000 токенів, а рівень дотримання правил падає до 30%.

Друга — зовсім не використовувати його, кожного разу починаючи з нового запиту. Це призводить до п’ятимильних витрат токенів і відсутності послідовності між сесіями.

Третя — скопіювати шаблон і більше його не редагувати. Він може працювати дві тижні, але з часом, через зміни у кодовій базі, стає неактуальним.

Офіційна документація Anthropic чітко каже: CLAUDE.md — це рекомендація, а не обов’язкова інструкція. Claude приблизно дотримується її 80% часу. Якщо довжина перевищує 200 рядків, рівень дотримання знижується, оскільки важливі правила губляться у шумі.

Шаблон Karpathy вирішує цю проблему: один файл, 65 рядків, 4 правила — це мінімальна база.

Але можна й краще. Додавши ще 8 правил, ми охоплюємо не лише проблеми написання коду у січні 2026 року, але й нові сценарії — оркестрування агентів у травні 2026 року, яких у початковому шаблоні ще не було.

Початкові 4 правила

Якщо ви ще не бачили репозиторій Forrest Chang, почніть з цього базового варіанту:

Правило 1: Перед кодуванням подумайте.

Не робіть мовчазних припущень. Поясніть свої припущення, відкрийте компроміси. Перед тим, як щось здогадатися, поставте запитання. Якщо є простіше рішення — висловіть заперечення.

Правило 2: Простота понад усе.
Використовуйте мінімальну кількість коду, щоб вирішити проблему. Не додавайте уявних функцій. Не створюйте абстракції для одноразового коду. Якщо досвідчений інженер вважає це надмірним — спростіть.

Правило 3: Хірургічне редагування.
Змінюйте лише те, що потрібно. Не оптимізуйте сусідній код, коментарі або формат. Не рефакторіть те, що не зламалося. Дотримуйтеся існуючого стилю.

Правило 4: Орієнтація на ціль.
Спочатку визначте критерії успіху, потім ітеративно рухайтеся до їх досягнення. Не говоріть Claude, що робити на кожному кроці, а повідомте йому, яким має бути результат, і він сам ітиме до нього.

Ці 4 правила здатні зменшити приблизно на 40% кількість невдач у безнаглядних сесіях Claude Code. Решта 60% — у «прірвах», що залишилися.

Я додав ще 8 правил і пояснення

Кожне з них виникло у реальній ситуації: початкові 4 правила Карпатьї вже не достатні. Спершу я опишу цю ситуацію, потім — відповідне правило.

Правило 5: Не дозволяйте моделі виконувати не мовленнєву роботу

Можна використовувати Claude для: класифікації, складання чернетки, підсумків, витягання інформації з неструктурованого тексту. Не використовуйте його для: маршрутизації, повторних спроб, обробки статус-кодів, детермінованих перетворень. Якщо статус-код вже відповів на питання — нехай це зробить звичайний код.

Це правило не було враховане у Карпатьї. Тому модель почала самостійно вирішувати питання, які мають оброблятися детермінованим кодом: повторити API-запит, маршрутизувати повідомлення, оновлювати обробку. В результаті щотижня рішення ставали все більш різними. Ви отримували нестабільний «if-else» з оплатою 0.003 долара за токен.

Приклад: був код, що викликав Claude для «визначення, чи потрібно повторити при 503». Спочатку він працював добре, але через два тижні став нестабільним, бо модель почала враховувати тіло запиту як частину контексту. Стратегії повтору ставали випадковими через випадковий prompt.

Правило 6: Встановіть жорсткий ліміт токенів без винятків

Бюджет для однієї задачі: 4000 токенів.
Бюджет для однієї сесії: 30 000 токенів.
Якщо завдання наближається до ліміту — підсумуйте поточний стан і починайте заново. Не намагайтеся «затягнути». Чітко повідомляйте про перевищення бюджету — краще за все.

Без обмежень у CLAUDE.md — це порожня чекова книжка. Кожен цикл може перетворитися на «контекст на 50 000 токенів». Модель не зупиниться сама.

Приклад: один сеанс нудився 90 хвилин. Модель безперервно працювала з однією 8-кілобайтною помилкою, і з часом забула, які виправлення вже пробувала. В кінці вона пропонувала 40 повідомлень, які я вже відхиляв. За наявності ліміту токенів цей процес слід було б зупинити на 12-й хвилині.

Правило 7: Виявляйте конфлікти, не компромісуйте

Якщо у кодовій базі існують дві протилежні моделі — не змішуйте їх. Оберіть одну, віддаючи перевагу новішій або більш протестованій, і поясніть чому. Позначте іншу модель для подальшого очищення. Спроба поєднати дві моделі — найгірший код.

Коли у коді є два протилежних підходи, Claude намагається задовольнити обидві, і виходить безлад.

Приклад: у кодовій базі були два підходи до обробки помилок — асинхронний з try/catch і глобальні обробники. Claude додав обидва, і помилки зникли двічі. Мені довелося 30 хвилин розбиратися, чому помилки ігноруються двічі.

Правило 8: Спочатку читайте, потім пишіть

Перед додаванням нового коду до файлу — ознайомтеся з його експортами, викликами та спільними функціями. Якщо не розумієте структуру — запитайте, не додавайте «згідно з моїм уявленням». «Це не має значення» — найнебезпечніше слово у цьому коді.

«Хірургічне редагування» Карпатьї не вказує, що потрібно змінювати, але не навчає читати існуючий код. Без цього Claude може додати функцію, яка конфліктує з уже існуючою.

Приклад: Claude додав функцію, що дублює існуючу, не ознайомившись з нею. Вона робила те саме, але через порядок імпортів нова функція перекривала стару, яка існувала 6 місяців.

Правило 9: Тестування — не опція, але тест не є ціллю

Кожен тест має пояснювати, чому ця поведінка важлива, а не просто що вона робить. Тест, що перевіряє лише повернення значення — безглуздий, якщо функція отримує фіксований ID. Якщо не можете створити тест, що зламається при зміні логіки — функція неправильна.

«Орієнтація на ціль» Карпатьї натякає, що тест — це критерій успіху. Але у практиці Claude часто вважає «успішним» лише те, що проходить тест, навіть якщо він не перевіряє ключову логіку.

Приклад: Claude написав 12 тестів для функції авторизації, всі пройшли. Але у продакшені логіка зламалася, бо тести лише перевіряли, що функція повертає щось, а не що саме. Вона проходила через константу.

Правило 10: Довготривалі операції потребують контрольних точок

У багатоступеневих завданнях після кожного кроку підсумовуйте, що зроблено, що перевірено і що залишилось. Не продовжуйте без ясного розуміння стану. Якщо втрачаєте орієнтацію — зупиніться і повторно сформулюйте поточний стан.

Карпатьї передбачає односторонню взаємодію. Але у реальності робота з Claude — багатоступенева: рефакторинг 20 файлів, побудова функцій у сесії, налагодження через кілька комітів. Без контрольних точок — ризик втратити весь прогрес.

Приклад: у 6-кроковому рефакторингу на 4-му кроці сталася помилка. Я помітив це, коли Claude вже виконав 5-й і 6-й кроки. Витрати на виправлення — більше, ніж повторне виконання всього. За наявності контрольної точки — можна було б виявити проблему на 4-му кроці.

Правило 11: Угоди важливіше новизни

Якщо у кодовій базі використовується snake_case, а вам подобається camelCase — залишайтеся в рамках існуючих угод. Якщо використовуються класові компоненти, а ви віддаєте перевагу hooks — дотримуйтеся їх. Розбіжності — це ще одна дискусія. Внутрішньо в проекті — послідовність важливіша за особисті вподобання. Якщо вважаєте, що якась угода шкідлива — пропонуйте її змінити, але не створюйте розгалуження.

У вже сформованому кодовому стилі Claude намагається ввести свої варіанти. Навіть якщо вони «кращі», це порушує цілісність.

Приклад: у React-проекті на класових компонентах Claude додав hooks. Вони працювали, але порушили існуючі тести, що залежали від componentDidMount. Після довгих зусиль довелося видалити.

Правило 12: Відкрито про невдачі, а не мовчки

Якщо ви не впевнені, що щось завершено — скажіть про це. Якщо пропущено 30 записів — не кажіть «міграція завершена». Якщо пропущено тест — не кажіть «успіх». Якщо не перевірили крайні випадки — не кажіть «функція працює». Відкривайте невизначеність, а не приховуйте її.

Найкоштовніші невдачі Claude — ті, що здаються успіхами. Функція «може працювати», але повертає неправильні дані; міграція «завершена», але пропущено 14% записів із порушеннями; тест «пройшов», але лише через неправильні припущення.

Приклад: Claude заявив, що міграція бази даних «успішна», але мовчки пропустила 14% записів із порушеннями обмежень. Це виявили лише через 11 днів, коли почалися проблеми з даними у звітах.

Результати

За 6 тижнів я відстежив 50 типових завдань у 30 кодових базах, протестував три конфігурації.

Помилка — це ситуація, коли потрібно виправити або переписати завдання, щоб воно відповідало початковому наміру. Враховуються мовчазні помилки припущень, надмірна інженерія, несуміжне пошкодження, мовчазний збій, порушення угод, компроміси, пропуски контрольних точок.

Рівень дотримання — ймовірність того, що при застосуванні правила Claude явно його дотримуватиметься.

Найцікавіший результат — не лише зниження помилок з 41% до 3%. Важливо, що розширення з 4 до 12 правил зменшило навантаження на дотримання з 78% до 76%, але помилки знизилися ще на 8%. Нові правила охоплюють ті невдачі, які не були враховані у перших 4, і не конкурують за увагу з ними.

Де саме шаблон Karpathy може не працювати

Навіть без додавання нових правил, початковий шаблон із 4 правил має щонайменше 4 слабких місця.

Перше — довготривалі агентські завдання.
Правила Карпатьї орієнтовані на момент написання коду. Але що трапляється, коли Claude виконує багатоступеневий pipeline? В оригінальному шаблоні немає правил щодо бюджету, контрольних точок або явного повідомлення про невдачу. Тому pipeline може розмиватися.

Друге — узгодженість у кількох кодових базах.
«Відповідність стилю» за замовчуванням — один стиль. Але у монорепозиторії з 12 сервісами потрібно обрати стиль. Оригінальні правила не вказують, як це зробити. В результаті — випадковий вибір або змішування стилів.

Третє — якість тестування.
«Орієнтація на ціль» трактує «успішне проходження тесту» як критерій. Але у реальності Claude часто вважає «успішним» те, що просто проходить тест, навіть якщо він не перевіряє ключову логіку.

Четверте — різниця між продакшн і прототипом.
Ті самі 4 правила можуть запобігти надмірній інженерії у виробництві, але гальмувати розробку прототипів, де потрібно швидко експериментувати. «Простота» у ранніх етапах може спрацьовувати неправильно.

Ці 8 нових правил не замінюють оригінальні, а доповнюють їх, закриваючи прогалини: початковий шаблон — для автоматичного доповнення у січні 2026 року; у травні 2026 року, коли з’явилися агентські системи, потрібен інший підхід.

Що не працювало

Перед остаточним формулюванням 12 правил я спробував інші підходи.

Додати правила з Reddit / X.
Більшість — просто перефразування оригінальних 4 правил Карпатьї або специфічні правила, наприклад «завжди використовувати Tailwind». Вони були видалені.

Більше 12 правил.
Я тестував до 18. Після 14 правил рівень дотримання знизився з 76% до 52%. Обмеження у 200 рядків — реальність. Більше — модель починає імітувати правила, а не читати їх.

Залежність від інструментів.
Наприклад, «завжди використовувати eslint». Якщо eslint не встановлений — правило не працює і мовчки зламується. Тому я зробив його більш універсальним: «дотримуйтесь стилю, що вже застосовується у кодовій базі».

Показати приклади у CLAUDE.md, а не правила.
Приклади займають багато контексту і легко призводять до overfitting. Правила — абстрактні, приклади — конкретні. Тому краще — правила.

«Будьте обережні», «подумайте», «зосередьтеся».
Ці фрази мають низький рівень дотримання (~30%), бо їх важко перевірити. Замість них — конкретні командні правила, наприклад «чітко формулюйте припущення».

Командуйте Claude, щоб він був «досвідченим інженером».
Це не працює. Claude вже вважає себе досвідченим інженером. Реальна проблема — у тому, як він виконує цю роль. Команди допомагають зменшити різницю, але не змінюють його ставлення.

Повний варіант CLAUDE.md із 12 правилами

Нижче наведено повний, готовий до копіювання файл.

Поки що цей контент не можна показати у Feishu.

Збережіть його у кореневій папці репозиторію як CLAUDE.md. Після 12 правил додайте свої правила — для техстеку, тестів, помилок. Не більше 200 рядків, інакше рівень дотримання знизиться.

Як встановити

Два кроки:

1. Додайте до вашого CLAUDE.md 4 базові правила Карпатьї
   curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. Вставте правила 5–12 з цієї статті у нижню частину

Збережіть файл у кореневій папці. Важливо — команда «>>» додає до існуючого файлу, не перезаписує.

Модель мислення

CLAUDE.md — це не список бажань, а договір поведінки для запобігання конкретних невдач.

Кожне правило відповідає на питання: що воно запобігає?

Карпатьї’s 4 правила — це запобігання мовчазним припущенням, надмірній інженерії, несуміжним пошкодженням і слабким критеріям успіху. Це основа, її не можна пропускати.

Мої 8 додаткових правил — це запобігання новим невдачам після травня 2026 року: безлімітним агентським циклам, багатоступеневим завданням без контрольних точок, тестам, що не перевіряють ключову логіку, і мовчазним невдачам, що маскуються під успіх. Це — інкрементальні патчі.

Звісно, ефект залежить від конкретного випадку. Якщо ви не використовуєте багатоступеневі pipeline, правило 10 — не так важливе. Якщо у вас є єдина стильова конвенція, яку контролює lint — правило 11 можна пропустити. Після ознайомлення з цими 12 правилами — залиште ті, що відповідають вашим помилкам, і видаліть інші.

Краще мати 6 правил, адаптованих під реальні невдачі, ніж 12 правил, що ніколи не використовуються.

Заключення

Твіт Карпатьї у січні 2026 — це був скарга. Forrest Chang перетворив її у 4 правила. В результаті 120 тисяч розробників поставили зірки. Більшість досі користується лише цими 4 правилами.

Модель і екосистема змінилися. Багатоступеневі агенти, ланцюги hook, навички, співпраця між кодовими базами — все це з’явилося після того, як Карпатьї написав ту скаргу. Початкові 4 правила вже не враховують нові виклики. Вони не неправильні, але неповні.

Додані 8 правил. За 6 тижнів протестовано 30 баз. Помилки зменшилися з 41% до 3%.

Збережіть цю статтю і вставте ці 12 правил у ваш CLAUDE.md. Якщо вони допоможуть уникнути помилок хоча б на один тиждень — поширюйте.

[Посилання на оригінал]

Клацніть, щоб дізнатися про вакансії в律од BlockBeats

Приєднуйтесь до офіційної спільноти律од BlockBeats:

Telegram підписка: https://t.me/theblockbeats

Telegram група: https://t.me/BlockBeats_App

Twitter: https://twitter.com/BlockBeatsAsia