Семь помилок у CLAUDE.md, якія таямніча пагіршуюць рэзультаты роботы Claude Code.

Самэ гэтае сумневы ўтвараюць адлогіяныя конфігурацыі. Ніякіх адказоў, ніякіх паведамленняў — толькі расплывчасты, часткова некоректны код з сесіі ў сесію. Нерошчырэнны чы абмежаны файл не толькі не дапамагае, але і спожывае ресурсы та заважае выкананню справжняй задачы. Таму, прытрымліваючыся перад тым, калі змяніце хоць адну лінію, рэштычна прачытайце, што там ёсць, а пасля поступова вылечвайце проблемы.

Памылка 1: расплывчаста апісанне стэк-трасы

Лінія на кшталт We use React and a database. не дае Клауду практычна нічога. Ён будзе здагадвацца пра Next.js router, выбіраць бібліятэку стану больш-менш аднародна і пісаць тэсты ў фреймворку, які вы не вжываеце. Рэзультат можа скомпілявацца, але ўсё раву не падходзіць да вашай базы кода.

У замене напісціце дэтальна:

Framework: Next.js 15, app router only
State: TanStack Query v5 for server state, Zustand for client state
Testing: Vitest + React Testing Library
Package manager: pnpm

Точныя версіі та стандарты — гэта тое, што ператварае расплывчасты выхід у код, які вярагодна пасядзіць у вашай базе дадзеных. Назвіце іх.

Памылка 2: жадная лімітацыя, жадных «ніколі не робіце гэтага»

Гэта самая распашчатая памылка. Людзі описваюць проект, але ніколи не ставяць чыстых граней. Без лімітаў Claude запускае npm у проекте pnpm, правяць гэнераваныя файлы і перерабляе код, пра які вы ніколи не згадвалі. Гэта не галюцынаціі — гэта разумныя прыпускі, якія з’яўляюцца таму, што жадныя правілы гэтага не прыводзяць.

Дадзі блок з лімітацыямі:

Constraints:
- Never install new dependencies without asking first
- Never edit files under /generated or /prisma/migrations
- Always use pnpm, never npm or yarn
- Do not refactor code outside the scope of the current task

Правілы пра тое, чаго не трэба робіць, даюць большых практычных наследкаў, чым простае опис, таму што яны запобегаюць дорогім памылкам ўсё раней, чым яны выйду на практыку.

Памылка 3: ігнараванне агентаў і падагентаў

Большасць файлаў CLAUDE.md напісаныя так, як будто адна модель працуе сама, без падказак для спецыялістскіх сабагентаў, якія працуюць праза галоўную сесію. Якщо вы выкарыстоўваете сабагентаў для тэставання, документацыі чы аддачы, паказвайце гэта ў файле: перыяктуйце кожнага агента, сферу, за якую ён адпавядае, і ситуацыі, калі галоўны агент павінен перадаць заведамасці далей.

Agents & delegation:
- test-agent: runs Vitest, owns /tests — do not write tests in the main session
- docs-agent: handles JSDoc and README updates only
- main agent: feature code, routing, API handlers

Якщо вы яшчэ праектуеце модель делегавання, будзе корыстна зразумець, як разлічаюцца навыкі, сабагенты, команды з слэшамі і MCP, перш чым вы выберазеце паводлівую структуру.

Памылка 4: занадта вялікі файл, який спрацьоўвае ваш бюджет контэксту

Большае колькасць не значыць лепшае. Файл CLAUDE.md з 2,000 рэядамі, заполнены ўсіма кансэптамі стылю, документацыяю API і логамі змян, завантажвае ўсё гэта ў кожную сесію, незалежна ад таго, чы ён неабходны чы ні. Це заважае выкананню справжняй задачы, а так как увага паслабляецца пад вплывам зайвых даных, у рэзультате маем модель, якая тэхнічна прачытаў вашы правілы, але ўсё раву не можа іх надзейна застосаваць.

Зменшыце колькасць да неабходная. Указаўце на файлы чы навыкі, каб атрымаць деталі, замест таго каб прыклеўваць іх усё. Правіла, якія стосуюцца аднаго пакета, должны знаходзіцца ў файле, прызначанам для гэтага пакета, а не ў корневым файле. Пасчитайце колькасць токэнаў у файле да і пасля скорачэння, каб пераканацца, што такія змены дапамаглі.

Парадох 5: інструкцыі, якія Claude не можа выконваць

Возьмім прыклад Запісуйце чысты, падтрымвальны, высокакалітэтны код. Claude вже смяркае, што гэта робіць, таму неясныя аднародкі нічога не вплываюць. Заменіце іх правіламі, якія можна пераканацца:

- Functions must be under 40 lines
- No default exports
- Colocate test files next to source files
- No inline styles — use CSS modules

Правіла експлуатації надають моделі конкретну, вимірювану мету. Амбітні формулювання такої мети не дають.

Помилка 6: застарілі правила, які суперечать коду

Проблема застарілого CLAUDE.md існує насправді. Уявіть, що через шість місяців після переходу команди на Zustand у файлі все ще написано „use Redux“. Таке правило не залишається без наслідків — воно створює суперечність між налаштуваннями та фактичним кодом, і Claude постійно міняється у своїх припущеннях щодо того, які правила дійсні.

Переглядайте файл щоразу, коли залежності суттєво змінюються, і включіть цей перегляд до списку перевірок у вашому PR. Зберігайте історію змін у Git, щоб бачити, коли останньо змінювалося кожне правило. Застарілий CLAUDE.md часто є гіршим, ніж його відсутність.

Помилка 7: один величезний плоский файл

У монорепозиторії єдиний неструктурований файл CLAUDE.md змушує Claude застосовувати правила фронтенду до коду бекенду та навпаки. Коли все є одним нерозділеним блоком, немає можливості визначити контекст.

Разместіце глобальныя правілы ў файле root CLAUDE.md, а файлы з конкрэтнымі настройкамі — па пакетах або службах. У самым файле root выкорыстоўваце чытальныя загаловкі разделаў:

# Project Overview
# Stack & Versions
# Constraints
# Agents & Delegation
# Per-Package Notes

Структура паведамляе Claude, якія правілы застосоўваюцца дзе.

Короткая перапрацоўка і чарткі

Хавайце здогадкі і оценіце файл па чатырох критэрыях: спецыфічнасць, абмежэння, структура і размах. Пораўнанне з добра структураваным шаблонам таксама дапамагае, адколі ён паказвае, як выглядае хорашы файл на практыцы.

Расгляньце следуючыя пытанні:

• Чы ў нём указаны точныя версіі фрэймворкаў і бібліятэк?
• Чы є блок з абмежэннямі з чысткімі правіламі „ніколі гэтага не робіце“?
• Чы ён пераказвае, якія агенты існуюць і што кожны з іх контролюе?
• Чы ў нём меней 200 ліній, пры чым деталі пакладзеныя ў скілы або скасываныя у іншыя файлы?
• Чы всі інструкцыі ўжоць функцыйнае, а не толькі прагматычныя?

Чы гэты файл быў пераглянут за наявнасць застарэлых правілаў за апошнія 30 дзён?

Чы ён раздзелены па заглав’ях, чы то па файлам по кожнаму пакету, якщо вы вядомаеце манорепо?

Якшы на больш чым два з гэтых пытанняў адпаведзеце «нет», то ваш CLAUDE.md, верагодна, коштае вас больш, чым зарабляе.