Дзе павінны знаходзіцца інструкцыі Claude Code: CLAUDE.md, правілы шляхоў або хукі

Большасць команд, які выкарыстоўвают Claude Code, зараз трываюць файл CLAUDE.md, але мало хто з іх можа сказаць, чыя-такі ён праблемы рашае. Часты варыянт — файл, які вырасае да колькасці сотняў ліній, пры чым модель выпалняе дзеякі інструкцыі, а іншыя проста ігнаруе. Рашэння рэдкасцю ёст толькі кращы шаблон; насправды трэба зрозумець, чым на самай працоўвае гэты файл, і направіць кожную інструкцыю да механізма, які можа ёй паслужыць. У гэтым кярыянце раскрываюцца семь практычных падходаў: ад скорачэння файлу да задання правілаў па шляху, пераказвання строгіх трэбавань у хукі і перагляду таго, што насправды запускае Claude.

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

CLAUDE.md – це контекст, а не настройкі

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

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

Зберагаюце канечны файл пад 200 лініямі

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

Это супрацэнтуізнае: чым большая колькасць інструкцый, тым меньшыя з яных выконваюцца. Кожны рэяд конкуруець за тую ж самую обмежаную увагу, як і кожны іншы рэяд, а таксама за увагу пад самай беседой. Узгляніце команду, чыя дакументацыя складалася з 340 рэядоў. Як толькі ёё колькасць была зменшана да апошніх 120 рэядоў, Claude стаў адносна надзеяму выконваць інструкцыі. Ні адны з выдаленых рэядоў не быў некоректным; яны проста былі шумам, які перакрываў важныя інструкцыі.

Існуе таксама жорсткія меры, проты якіх не хочацца проектаваць: згодна з дакументацыяй на момент напісання, файлы большыя за 4 МБ проста ігнаруюцца. Выконання інструкцый паслабляеся задоўга да таго, як файл нават падыходзіць да такога размеру.

Выдаліце тое, што Claude можа знайсці ў репазітарыі

Сама эфектывае правіла рэдагавання ўсё проста: трэба адмахнуцца всьму, што Claude можа з’ясавіць, прачытаўшы кодавую базу. Гэта адпавядае тым правілам выкарыстоўвання, якія прымае сама функцыя /doctor у Claude Code — яна адмахнуцца структуры папак, спіса залежнасцяў і описаў архітектуры высокага рэвляюшну, заўсёды залічаючы проблемы, праграматыку і стандарты, якія адрозніццая ад значэнняў, заданых інструментам. Іншымі словамі, гэта ператварае звычны содержанне этых файлоў.

Тое, што трэба адмахнуцца:

• Структуру папак, адколькі Claude сам можа перыявіць катэгорыі.
• Спіс залежнасцяў, які вже ўтримваецца ў файле package.json.
• Наратыўны апіс архітектуры, які код выражае болей тачна.

Тое, што трэба залічыць:

• Код, які выглядае як памылка, але є навмешаным.
• Прычыны, чаму быў адхілены звычайны падход.

Будзь-яяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяя

<!-- Deleted the API section — moved to .claude/rules/api.md, Sep 2026 -->

Вашы саўетнікі бачаюць гісторыю; модэль ніколі за ўсё гэта не плаціць.

@imports арганізуюць файл, але не зберагаюць контекст

Калі файл CLAUDE.md стае вялікім, прыродны ўспрыем стае его разбіўка на калькі дакументаў і ўвоз яных:

@docs/architecture.md
@docs/api-conventions.md
@docs/testing.md

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

Імпорты дзейсна маюць практычныя застосоўванні. Яны дапамагаюць у арганізацыі і прабачаюць дзеліцца аднам канонічным наборам інструкцый между рознымі інструментамі. Якщо у репазітарыі вялічка AGENTS.md, то адна лінія @AGENS.md у CLAUDE.md запобегае падтрымкі двух розныя версый. Толькі не чакайце, што яны зменшыю выкарыстоўванне контэксту. Для інструкцый, якія должны загружацца толькі часамі, патрэбны правілы з дзеянням на пацек.

Установка умовных правілаў за дапамою .claude/rules і пацек

Файлы ў .claude/rules/ можаць заявіць поле paths у своем фронтматеры. Гэта тая функцыя, якая задае тое, чаго люди спакульвуюць ад імпортаў: правілы з глобальным дыапазонам застаюцца пахаванымі ў контэксте, пакуль Claude не прачытае або не зменіць адпаведны файл. Фронтматер файла правілаў API можа выглядаць так:

---
paths:
  - "src/api/**/*.ts"
---

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

# API rules- Every endpoint validates input before touching the database
- Errors use the standard envelope in `src/api/errors.ts`
- No direct SQL outside `src/api/repositories/`

Эфект такі: робота над фронтэндам больш не платіць за викорыстоўванне токенаў, прызначаных для стандартаў API, а робота над API больш не платіць за стандарты тэставання.

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

Функція Glob падтрымлеў расширэнне складак, таму адна правіла можа стосавацца кальколькі расширэнняў і аднае окремай схемы тэставання:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"
---

Крокі, які неабяжнае трэба выкарыстоўваць, павінны быць у хукі

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

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

Практычны спосаб размежавання кожнага типу інструкцый:

• Узусы, якім Claude павінен загалом следаваць, паказваны ў CLAUDE.md.

Правілля для адміністрацыі якога-небудзь рэгіону кодбазы кладуцца ў .claude/rules/ разам з параметрам paths.

Тэрэтарыў, які не дапускае жадных асаблівасцей, стае хукам.

Павтаральная багатыядерная процедура стае навыкам.

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

Пераканацца, што насправды заваносіцца

Заўяжыце /context і адзірніце раздел з файламі памяці, які точна паказваюць, што было завантажана ў часе роботы сесіі. /memory дапамагае ў гэтым, перыявляючы файлы на рывень корыстніка і проекту, а таксама дазволяючы ўсунуць іх. Разам яны ператвараюць пытанне „Чы не ігноруе Claude гэта?“ з простага здогадвання на ўсё, што можна пераконтраць. Дзівным чынам лёгка запрацаваць над формулюванням файла, які важовсе не завантажаецца.

Супераспакоўкі ў скалачаных файлах

Нічыта не пераканалеваецца; усё сумачваецца. Пачынаючы з катэгорыі працы, Claude Code падыходзіць да корана файлавой системы і збірае кожны файл CLAUDE.md па дарозе, а потым распрацоўвае іх з верху да нізу. На будзь-ям рэвэле, дзе таксама ёсць файл CLAUDE.local.md, гэты файл нарадзіваецца пасля свога братоўскага файла CLAUDE.md. У манорепо два файлы можу лёгка даць працупадзяючыя адказы. Калі такая ситуацыя выйшла, Claude можа проста выбраць адны з іх, і нічыта не паведамляе вас пра канфлікт.

Файлы-прадкуроры, якія вы не прасілі

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

Што застаецца пасля скаплівання

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

Прыёмны план

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

• Корань у вигледзе файла CLAUDE.md з прыбліжна 120 рэядамі, які мае містіць толькі тое, што ўсюды є правдай.
• Умовныя інструкцыі, якія знаходзяцца ў каталозе .claude/rules/ з викорыстаннем шаблонавых пацек.
• Кожна непераглядная „заўжды“ неабходнасць рэалізуецца у вигледзе спецыяльнага хука.
• Нічога такога, што хтось мог бы дазнацца, прачытаўшы репазітарый за дзесяць хвілін.
• Шыраная перацягвання команды /context пасля кожных змян.

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

Галоўныя выводы

• Запішыце CLAUDE.md для колеги, які чытае, а не для машыны, якая выконвае: каротка, конкрэтна і без суперсчыненняў.
• Кораткія файлы выконваюцца надзеямлівей; адмахніцеся ад усьога, што кодбаза вже паведамляе Claude.
• Імпорты перарганізуюць контэнт, але завантажаюць усё; правіла, прызначаныя для парадку путаў, насправдзе затрымліваюць завантажэнне.
• Усё, што павінна выконвацца ў кожны раз, трэба задаць за дапамогою хука, таму што контэкст можа вплываць толькі на працоўнае яксцэнт.
• Перад налагоджэнням формулюванняў спрыяйце /context як сваю аснову правды.