Дві екосистеми: Claude Code і OpenAI Codex

Правила Claude Code: локальні вказівки без хаосу

Навчальний розділ курсу «AI Development» (Artificial Intelligence, штучний інтелект) · зріз документації: 10.10.2026

Глава 30Заморожене українське видання

Навчальний розділ курсу «AI Development» (Artificial Intelligence, штучний інтелект) · зріз документації: 10.10.2026

У кореневому файлі інструкцій не обов’язково зберігати кожне правило для кожної частини репозиторію. Команда, яка змінює схему даних, має бачити контракт міграцій; редактор текстів інтерфейсу не мусить щоразу перечитувати його. У Claude Code це можна організувати через каталог .claude/rules/, а за потреби — обмежити окреме правило файлами, які воно описує.

Однак шляхове правило не є фільтром дозволів. Якщо текст завантажується лише для db/migrations/, це означає, що його передають у контекст під час роботи з відповідними файлами. Це не гарантує, що агент не може підключитися до бази через інший інструмент. І навпаки: заборона виклику в налаштуваннях доступу не описує команді, як підготувати безпечну міграцію. Ці механізми потрібно проєктувати й перевіряти окремо.

У розділі показано поточну поведінку саме Claude Code. Інші продукти Anthropic, включно зі звичайним чатом, можуть мати інші способи читання файлів. Офіційні сторінки перевірено 10 жовтня 2026 року; документація може змінитися. На цю дату сторінка релізів показувала v2.1.296 від 9 жовтня. Це часовий зріз, тож перед практичним використанням звірте встановлений клієнт і його документацію.

30.1. Що таке rule і для чого він потрібен

У цьому розділі правило — Markdown-файл з настановами, який Claude Code додає до контексту безпосередньо або після збігу з шляхом файла. Команда може використати його для конвенції щодо міграцій, перевірки відповіді програмного інтерфейсу (Application Programming Interface, API), доступності інтерфейсу користувача, форматування документації або класифікації імпортованих даних.

Правило доречне, якщо воно відповідає на кілька запитань:

  • До якої роботи воно належить: усього репозиторію, певного домену, каталогу чи типу файла?
  • Яку саме поведінку очікують і як вона відрізняється від бажаного стилю?
  • Яку причину або контракт варто знати перед зміною?
  • Де лежить повне першоджерело: технічний опис, запис рішення, специфікація чи інструкція процесу?
  • Як перевірити результат і що робити, якщо дані або вимоги суперечать одне одному?

Фраза «пиши надійний код» не визначає ні область, ні дію, ні критерій. Інструкція «для файлів db/migrations/** не переписуй історичний файл після його застосування до спільного середовища; підготуй нову зміну й звір її з docs/data-retention.md» має перевірне місце застосування, дію та посилання на контракт. Вона все ще є текстом для агента, а не блокувальним механізмом.

За нинішньою документацією Claude Code проєктні правила зберігають у .claude/rules/ як файли Markdown із розширенням .md. Каталог знаходиться в репозиторії, тому його вміст може бути спільним через Git. Персональні правила можна зберігати в ~/.claude/rules/; вони стосуються різних проєктів цього користувача. Підкаталоги всередині .claude/rules/ допомагають організувати теми, але самі по собі не обмежують, які файли активують текст. Для обмеження потрібен підтримуваний шаблон paths у заголовку файла.

30.2. Завантаження: від місця файла до контексту

Claude Code рекурсивно знаходить Markdown-файли під проєктним .claude/rules/. Правило без paths завантажується на початку сесії так само, як ./.claude/CLAUDE.md. Це стосується й правила у вкладеному підкаталозі .claude/rules/: перенесення в frontend/ організовує дерево, але не робить його автоматично правилом лише для frontend.

Правило з paths має умовну область: воно додається, коли Claude Code читає файл, шлях якого відповідає одному із шаблонів. Документація прямо відрізняє це від «кожного виклику інструмента». Якщо на запиті про дизайн інтерфейсу агент ще не читав жодного файла, відповідне шляхове правило могло ще не потрапити в контекст. Самої згадки шляху в повідомленні користувача недостатньо, щоб виснувати про завантаження.

Це має практичний наслідок для підготовки задачі. Якщо важливе правило стосується коду міграції, агент має прочитати конкретний файл міграції або інший шлях, що збігається. Текст правила не є заміною завантаженню. Щоб перевірити діагноз, зафіксуйте видимий шлях файла, поточний робочий каталог, продукт і його версію; після цього перевірте, що Claude Code відобразив як завантажене.

Поточна документація визначає два способи перевірки. Команда /context показує завантажені інструкції та правила в контексті. Гачок InstructionsLoaded може реєструвати, який файл, коли і чому було завантажено; це корисно для діагностики правил із paths і файлів, що завантажуються пізніше. Самописаний гачок мусить справді бути налаштований і доступний у потрібній сесії. Журнал завантаження доводить, що контекстний файл було під’єднано; він не доводить, що модель виконала кожен його пункт.

Можливі й причини, через які правильний файл не завантажиться. Правила проєкту можна виключити, якщо джерело project прибрано зі списку джерел налаштувань Claude Code. З поточної версії треба перевіряти фактичний клієнт, обрану конфігурацію і вміст /context. Історична примітка з офіційної сторінки: до v2.1.211 шляхові та вкладені правила могли завантажуватися навіть за виключеного project; не переносіть ту стару поведінку на сучасну версію.

30.3. Заголовок paths і формат

Для шляхового правила Claude Code читає YAML (YAML Ain’t Markup Language, «YAML — не мова розмітки») frontmatter — короткий блок метаданих на початку Markdown-файла між двома рядками з трьома дефісами. Документована назва поля — paths. Це поле може бути списком YAML або рядком, де кілька шаблонів розділено комами. Поточна документація каже, що paths — єдине поле frontmatter, яке Claude Code читає з файла правила; інші поля ігноруються без помилки.

Мінімальний приклад для правил міграції:

---
paths:
  - "db/migrations/**/*.sql"
  - "db/migrations/**/*.ts"
---

# Міграції схеми

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

Відкривальний роздільник frontmatter має бути на початку файла, закривальний — окремим рядком. Кожен елемент списку розміщуйте під paths: з відступом і як текстовий шаблон. Якби YAML між роздільниками не розбирався, поточна документація каже, що frontmatter ігнорується, а файл завантажується так, наче paths немає. Це особливо небезпечна помилка: замість вузького правила команда отримує загальне правило на кожному запуску. claude --debug може показати помилку frontmatter.

Шаблони наслідують glob-синтаксис — спосіб зіставити шлях із зірочками та іншими шаблонними символами. Офіційна таблиця наводить такі приклади:

Шаблон Що збігається за документацією
**/*.ts файли TypeScript у різних каталогах
src/**/* будь-які файли під src/
*.md Markdown-файли лише в корені проєкту
src/components/*.tsx React-компоненти в конкретному каталозі

Точна структура репозиторію має значення. Наприклад, *.md не є скороченням для «усі Markdown-файли в усіх вкладених каталогах»; якщо треба охопити піддерево, у документації є окремі зірочки для вкладених шляхів. Перед застосуванням rule перевірте щонайменше один очікуваний збіг і один шлях, який має залишитися поза областю.

У paths можна вказати кілька шаблонів або використати розширення фігурних дужок для групи розширень. Наприклад, src/**/*.{ts,tsx} розгортається у варіанти для .ts і .tsx. Розгортання обмежене: список paths одного правила має спільний бюджет 1 000 розгорнутих шаблонів і 4 MiB (мебібайта; 1 MiB = 1 048 576 байтів). Шаблон, який перевищив бюджет, залишиться нерозгорнутим; тоді його буквальні фігурні дужки не збігатимуться зі шляхом. Не створюйте комбінації десятків груп лише для того, щоб заповнити frontmatter; кілька зрозумілих правил легше перевірити.

Квадратна дужка [ вводить набір символів на кшталт [abc]. Якщо шаблон має непарну або невалідну конструкцію, наприклад photos [2024/**, документація каже, що він не збігається з жодним файлом, але інші шаблони того самого правила продовжують працювати. Щоб у назві шляху збігалася буквальна дужка, її треба екранувати: photos \[2024/**. Перевірте цей крайовий випадок, якщо в репозиторії є такі імена.

30.4. Правило, Skill, дозвіл і автоматична перевірка

Подібні механізми можуть згадувати той самий файл або дію, але мають різне призначення. Їх не слід підміняти один одним.

Механізм Claude Code Для чого він Приклад і межа
CLAUDE.md Стабільний контекст, корисний у широкій частині сесій Карта проєкту й головні контракти; подробиці лишаються в документах
.claude/rules/*.md Контекстна настанова, яку завантажують безумовно або за збігом шляху Вимоги до файлів міграції; текст не блокує команду SQL
Skill із SKILL.md Повторювана процедура та потрібні ресурси, які Claude Code може застосувати за викликом чи коли вони доречні Покроковий аналіз міграції; повний вміст не є системним дозволом
settings.json і permissions Налаштування поведінки клієнта й правил allow/ask/deny для викликів інструментів Заборонити відповідний виклик shell або вимагати підтвердження; правило діє лише на конкретний інструмент і його обсяг
Hook Автоматична дія чи перевірка у визначеній події PreToolUse може перевірити або відхилити відповідний виклик, якщо саме цей гачок налаштовано
Лінтер або CI (Continuous Integration, безперервна інтеграція) Автоматична перевірка формалізованої властивості у відповідному робочому процесі Перевірити формат міграції при відкритті запиту на злиття; це не доводить, що локальний запуск був неможливим

Шляхові правила і Skills обидва можуть враховувати paths, але функція має інший сенс. У поточному Claude Code Skills frontmatter paths обмежує, коли Skill активується, використовуючи формат шляхових шаблонів. Правило при цьому додає текстову домовленість до контексту; Skill пакує послідовність кроків та ресурси й може завантажитися повністю, коли його викликають або коли продукт визначає його доречним. Документація Skills не вказує мінімальної версії для paths, тому перевіряйте цю можливість у конкретному Claude Code. Інші способи розповсюдження Skill — наприклад, веб-завантаження в claude.ai, Skills API або package_skill.py — приймають обмеженішу спільну підмножину метаданих і не обов’язково мають paths.

Якщо правило каже «не запускай міграцію у виробничому середовищі», а середовище дає агенту мережевий шлях і облікові дані, текст самостійно не прибирає цей шлях. Треба налаштувати доступ, пісочницю, дозволи конкретних інструментів і процедуру схвалення. Якщо умова машинно перевірна, лінтер або CI може шукати небезпечну схему в самій зміні. Кожен контроль має межі: дозволи на shell не автоматично накривають окремий інструмент бази даних чи підключений сервер Model Context Protocol (MCP, протокол контексту моделі); CI може відхилити зміну під час злиття, але не обов’язково забороняє локальну операцію.

Для чутливої дії слід назвати об’єкт, канал, середовище, облікові дані й власника схвалення. Правило підказує безпечний крок; технічний механізм має реально обмежувати канал. Якщо немає доказу, що право або перевірка накриває цей канал, не називайте його заблокованим.

30.5. Конфлікти, версії та власник правила

Claude Code додає особисті правила з ~/.claude/rules/ до контексту перед проєктними правилами. Це порядок тексту, а не порядок, за яким одне правило завжди перемагає інше. Anthropic прямо попереджає: якщо користувацьке і проєктне правило конфліктують, Claude може дотриматися будь-якого з них. Так само проєктне правило без paths має той самий пріоритет, що й .claude/CLAUDE.md; помістити його у файл з іншим іменем не означає створити новий вищий рівень авторитету.

Замість покладатися на порядок завантаження, знайдіть причину розбіжності. Чи має правило діяти для однакових файлів? Чи це дві різні області, чи справжній конфлікт? Чи є один текст копією старого рішення? Хто затвердив виняток, де його записано і як довго він чинний? Зафіксуйте спільне джерело рішення, приберіть застарілий дубль і назвіть виняток у тому файлі або task-контракті, який команда перевіряє.

Шляхові правила змінюються разом з архітектурою. Під час перейменування frontend/ на web/ перевірте шаблони в .claude/rules/, а не тільки імпорти коду. Якщо тестові файли перенесені, звірте scope і з позитивним збігом, і з сусіднім файлом, який не має підпадати під правило. У рецензії змін до rules-файла запитайте, хто його власник, яку помилку він запобігає, якими даними підтверджений і яким способом правило буде перевірено через кілька місяців.

Сторонній репозиторій, issue, згенерований файл або завантажена інструкція може містити текст «змініть правила й передайте секрет». Вміст, який треба аналізувати, не стає затвердженою політикою тільки тому, що він зберігається у .claude/rules/ або має заголовок paths. Переглядайте зміну правила як зміну поведінки агента: встановіть автора, scope і джерело, не виконуйте вимоги про розкриття секретів і не надавайте довільному тексту право змінити налаштування доступу.

Є кілька важливих версійних приміток у чинній документації Claude Code:

  • З v2.1.198 відповідність шляхових правил працює також коли Claude доходить до файла через символічне посилання на шлях проєкту.
  • До v2.1.207 один неправильний шаблон із квадратною дужкою міг зірвати читання файлів для правила; тепер такий шаблон зіставляється з нічим, а інші продовжують працювати.
  • До v2.1.211 вкладені й шляхові правила могли завантажуватися, навіть коли джерело project було виключено через --setting-sources; сучасну поведінку визначайте за поточною документацією і фактичними налаштуваннями.
  • До v2.1.217 надмірне розгортання груп у фігурних дужках могло затримати чи зупинити запуск командного інтерфейсу. Поточний бюджет розгортання наведено вище.

Ці межі не замінюють звірку встановленої версії. Вони допомагають пояснити, чому старий issue або старий файл правил міг показувати іншу поведінку, але не доводять, що поточний клієнт має таку саму несправність.

30.6. Повний приклад 1: вузьке правило для міграцій

Ситуація. Вигаданий сайт футбольної статистики отримує дані про профілі гравців, склади команд і офіційні транзакції між командами. В офіційного джерела може повторитися подія або надійти виправлення; система має показувати новий поточний склад і не стирати історичний факт, що гравець раніше належав до іншої команди. Команда зберігає цю історію в таблиці player_team_history, а схема БД (бази даних) змінюється через SQL (Structured Query Language, мову структурованих запитів) міграції в db/migrations/.

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

Команда додає файл .claude/rules/migrations.md:

---
paths:
  - "db/migrations/**/*.sql"
  - "db/migrations/**/*.ts"
---

# Database migrations

- Before changing the roster-history schema, read `docs/roster-history.md` and the applicable decision record.
- Preserve the source transaction identifier (ID) and enough history to explain each current-roster change.
- Do not rewrite a migration that has been applied to a shared environment. Add a new migration and describe forward and recovery steps.
- Treat upstream corrections and duplicate transaction events explicitly; do not infer that a player is currently on a team from a rumor feed.
- Never connect to or apply a migration to production from an agent task. Prepare reviewable changes only and report unknown data-retention or dependency facts.

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

Проблема та альтернативи. Є щонайменше три можливості. Перша — переписати старий файл міграції, щоб додати індекс і поле source_transaction_id; це може змінити результат у середовищі, де той файл уже застосовано. Друга — додати нову міграцію, що додає нове поле, заповнює відсутні дані з перевіреного джерела, і залишає стару історію незмінною. Третя — поміняти логіку таблиці, не уточнивши, звідки брати запис для старих рядків; це приховає невідомість, а не розв’яже її.

Рішення й дія. Для навчальної задачі команда обирає новий файл міграції. Автор спершу читає docs/roster-history.md та відповідний запис архітектурного рішення; з’ясовує, чи зовнішній ідентифікатор транзакції (transaction identifier, ID) унікальний і як система поводиться з повторним імпортом. Якщо контракт не дає відповіді на питання, чи можна обчислити джерело для історичних рядків, автор не вигадує значення для всіх записів, а позначає потрібне рішення власнику даних. У pull request (PR, запиті на злиття) він описує план застосування й відновлення та зазначає, чого не перевіряв.

Спостережуваний результат. Новий файл лишає застосовану історичну міграцію незмінною; його diff містить додавання, а не переписування; перевірка схеми підтверджує, що transaction ID має визначену область унікальності. Рецензент може порівняти новий перехід із контрактом історії та побачити джерело кожної нової вимоги. Перевірка файлу через /context або InstructionsLoaded може показати, що це правило завантажилося після читання відповідного файла. Це свідчить про контекст, але не про виконання перевірки бази й не про можливість підключитися до виробничого середовища.

Технічна межа й чому так. Правило просить підготувати зміну, а технічна політика прикладу має прибрати виробничі облікові дані та мережевий шлях із середовища агента; CI окремо перевіряє формат і заборонені зміни міграцій. Ці контроли є заданими умовами прикладу, а не властивістю Claude Code. Якщо команда запускає SQL із shell, а також має підключений інструмент бази або сервер MCP, кожний шлях треба врахувати. Текстовий rule не блокує ні один із них.

Обмеження. Іноді треба змінити модель даних швидко, бо попередня схема не може представляти виправлення транзакції. Тоді нова міграція може бути недостатньою: команда має розробити контрольоване переповнення чи окремий план перерахунку історії. Правило підсвічує проблему, але власник даних і DBA (Database Administrator, адміністратор бази даних) підтверджують збереження, залежності й відновлення. Якщо каталог db/migrations/ має ще генераторні або довідкові файли, шаблон теж треба переглянути, щоб правило не навантажувало зайві сесії.

30.7. Повний приклад 2: frontend-rule завантажується для всіх TypeScript-файлів

Ситуація. Вигадана студія розробляє портал керування підписками. Правило .claude/rules/frontend.md задумане для форм і віджетів користувацького інтерфейсу: зберігати видимий підпис контролу, відповідність навігації клавіатурою та стани очікування. У першій версії воно має paths: - "**/*.{ts,tsx}". Команда помічає, що ті самі настанови завантажуються під час роботи над серверними обробниками, планувальником і міграціями в TypeScript. Це не означає, що вони шкідливі, але довгий чекліст інтерфейсу користувача в незв’язаних задачах додає шум і може приховувати потрібні правила.

Чому scope ширший, ніж задумано. Шаблон охоплює .ts і .tsx у будь-яких каталогах. Збіг матиме, наприклад, apps/portal/src/forms/AddressForm.tsx, а також services/billing/src/retry-worker.ts і db/migrations/20260901.ts. Каталог або назва файла не гарантують призначення коду: components/ може містити не лише візуальні компоненти, а tsx може бути згенерованим чи серверним. Потрібно зіставити шаблон із реальною структурою.

Альтернативи. Команда може залишити широкий шаблон, бо деякі правила інтерфейсу користувача корисні й для тестів або прикладів; може без розбору створити окреме дубльоване правило для кожної папки; або описати спільне правило один раз і звузити саме ті частини, які стосуються браузерного інтерфейсу. Правильний варіант залежить від того, де саме розміщені файли, а не від назви frontend.md.

Рішення й дія. Структура порталу має дві області інтерфейсу користувача: apps/portal/src/forms/ і packages/ui/src/. Правило змінюють на:

---
paths:
  - "apps/portal/src/forms/**/*.{ts,tsx}"
  - "packages/ui/src/**/*.{ts,tsx}"
---

# Browser interface

- Every interactive control needs a visible name and a keyboard path.
- Show loading and error states in the component that owns the request.
- Read `docs/accessibility.md` before changing shared interaction behavior.

Далі власник робить маленьку матрицю перевірки: очікуваний збіг apps/portal/src/forms/AddressForm.tsx, очікуваний збіг packages/ui/src/Button.tsx, невідповідний шлях services/billing/src/retry-worker.ts, а також файл поза правилами, наприклад README.md. Він відкриває ці файли в окремих сесіях або відтворює потрібний шлях читання у цільовій сесії та перевіряє завантажений набір через /context чи налаштований InstructionsLoaded. На кожному шляху звіряє встановлену версію Claude Code і що project включений у --setting-sources.

Спостережуваний результат. Правило інтерфейсу користувача з’являється у контексті, коли Claude Code працює з названими областями, і не додається при читанні серверного worker-файла, який не збігається. Журнал або /context показує назву файла правила; збіг можна зіставити з конкретним відкритим шляхом. Якщо матриця показує неправильну область, rule змінюють повторно — перейменування файла frontend.md само нічого не виправить.

Чому так і де це не підходить. Явний список піддерев відповідає поточній структурі, має позитивні й негативні приклади та є простим для перегляду під час рефакторингу. Надто широкий **/*.{ts,tsx} завантажував інструкцію в коді, де браузерних контролів немає. Водночас надто вузький apps/portal/src/forms/**/*.{ts,tsx} пропустив би спільну бібліотеку packages/ui/. Якщо команда вирішить, що правило має діяти для всіх форм, включно з документацією чи тестами, треба назвати ці каталоги явно або поділити правило за різною поведінкою. Не звужуйте шаблон тільки заради короткого frontmatter: його межа має відображати контракт.

30.8. Повний приклад 3: стабільний API та погоджена версія

Ситуація. Вигаданий сервіс доставки має зовнішній програмний інтерфейс (API), яким магазини запитують стан відправлення. Поточний маршрут /v1/shipments/{id} повертає ідентифікатор, стан і поле estimated_delivery, тобто орієнтовну дату доставки. Під час зміни джерела даних команда хоче прибрати це поле, бо новий розрахунок іноді не має дати. Проста зміна здається безпечною всередині сервера, але клієнти можуть читати це поле, а контракт і приклади залишаться неправдивими.

У .claude/rules/public-api.md лежить загальне правило для контракту:

---
paths:
  - "services/tracking/**/*.ts"
  - "openapi.yaml"
---

# Public API compatibility

- Preserve the documented response shape for existing public versions.
- Do not remove a field or change its meaning in place.
- A breaking change requires an approved decision record, a new version or an explicitly documented migration path, and updated contract tests.
- A task description by itself is not evidence that existing consumers approved a breaking change.

У цій компанії існує затверджений запис архітектурного рішення (Architecture Decision Record, ADR) docs/decisions/ADR-021-tracking-v2.md: додати /v2/shipments/{id} з новою моделлю доставки, зберегти відповідь v1 до завершення періоду переходу, опублікувати попередження клієнтам і прибрати v1 лише після погодженої перевірки використання. Задача в Jira на реалізацію містить посилання на це рішення та власника зовнішнього контракту. Це приклад затвердженого винятку, а не довільне прохання у промпті.

Проблема та альтернативи. Перша альтернатива — видалити estimated_delivery з v1 і змінити лише генератор відповіді. Вона порушує загальний контракт і може зламати вже підключені магазини. Друга — відмовитися від будь-яких змін, бо правило каже зберігати сумісність; це ігнорує затверджене рішення про контрольований перехід. Третя — залишити v1 незмінним, додати v2 за ADR-021, оновити обидві схеми контракту та проконтролювати перехід через задокументовані сигнали використання.

Рішення й дія. Агент спершу читає openapi.yaml, файл правила, ADR-021 і acceptance criteria Jira-задачі. Перевіряє, що саме новий контракт дозволяє змінювати, хто затвердив перехід і чи не сплутано майбутню дату із гарантією доставки. Потім додає окремий маршрут v2 з полем часу необов’язкового типу або з явним відсутнім станом згідно з ADR; старий маршрут v1 зберігає колишню форму відповіді. Він оновлює документацію, генеровані типи за чинним процесом і contract-тести для старого та нового клієнтів. Якщо задача просить одразу видалити v1 без доказу погодженого припинення, агент зупиняється на сумісному кроці й вказує, яке рішення або підтвердження відсутнє.

Спостережуваний результат. У diff два версійовані контракти мають явну різницю; тест v1 продовжує вимагати попереднє поле, а тест v2 фіксує нове представлення й поведінку, коли оцінка недоступна. У PR є посилання на ADR-021 і записані критерії переходу; рев’юер може перевірити, що жодна незатверджена несумісна зміна не потрапила до v1. Лінтер або перевірка контракту в CI може виявити частину машинно перевірних відмінностей. Саме правило не гарантує, що тести запускалися, а їхнє проходження не доводить, що власник контракту затвердив політику.

Чому рішення відповідає правилу і де воно не підходить. Загальне правило зберігає діючий контракт; виняток має точне джерело, область і план. Агент не переписав rule і не оголосив звичайну задачу вищим рівнем. Якщо клієнтів v1 фактично немає, все одно потрібні підтверджені метрики та погоджений процес завершення версії. Якщо обслуговування двох версій створює неприйнятний ризик, власник може обрати інший перехід, наприклад адаптер сумісності або одноразове контрольоване припинення. Rule підказує, що з’ясувати; він не підміняє рішення власника контракту.

30.9. Як діагностувати правило, що не спрацювало

Коли Claude Code пропустив очікувану настанову, не починайте з висновку «модель не послухалась». Відтворіть конкретну ситуацію й перевірте її послідовно:

  1. Зафіксуйте середовище. Назвіть Claude Code, встановлену версію, тип сесії, корінь репозиторію й шлях файла. Поверхня, яка не є Claude Code, може взагалі не використовувати .claude/rules/.
  2. Перевірте файл. Він має бути Markdown у підтримуваному .claude/rules/ для проєкту або у ~/.claude/rules/ для користувача. frontend.md в іншому місці може бути звичайною документацією.
  3. Перевірте frontmatter. Переконайтеся, що paths написане точно, розміщене між рядками ---, має коректний YAML і включає справжній шлях. За помилки розбору правило може перетворитися на безумовне.
  4. Зіставте шлях. Відкрийте саме той файл, де очікуєте правило. Перевірте один позитивний та один негативний шлях, включно з вкладеністю й розширенням.
  5. Перевірте момент завантаження. Шляхове правило додається при читанні файла, що збігається, а не при кожній дії інструмента. Інструкція могла ще не завантажитися на момент вибору.
  6. Звірте джерела налаштувань. Переконайтеся, що потрібне джерело проєкту не виключено; перевірте /context або доступний лог InstructionsLoaded. Самозвіт агента може бути корисним, але не замінює цих свідчень.
  7. Розділіть невідповідність і контроль. Якщо правило видно, але небезпечний виклик залишається доступним, перевіряйте налаштування permission, пісочницю, мережу, підключення до бази, hook і CI окремо.
  8. Перевірте конфлікт. Знайдіть інші user/project rules і CLAUDE.md; актуальні документи прямо попереджають, що змістовний конфлікт може бути розв’язаний непередбачувано. Видаліть дубль або запишіть джерело затвердженого винятку.

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

30.10. Публічні приклади та межі їхніх свідчень

У відкритому репозиторії Trail of Bits є файл rules/python.md, який обмежує Python-настанови файлами Python, ноутбуками, pyproject.toml і uv.lock. У ньому також спрямовано частину структурних обмежень до конфігурації Ruff, де їх можна перевірити автоматизовано, а не залишати лише у прозі. Це корисний приклад розділення контекстної поради та інструментально перевірного правила; він не доводить, що така сама структура підходить кожному репозиторію.

У злитому PR #60 репозиторію claude-code-config автор описує перевірку InstructionsLoaded на Claude Code CLI (command-line interface, інтерфейсі командного рядка) v2.1.238: читання .py завантажило Python rule, читання .rs — Rust rule, а невідповідний файл не завантажив жодного з них. Це конкретний звіт автора pull request про його середовище та версію. Він показує спосіб перевірки, але не обіцянку для всіх продуктів і всіх клієнтів.

Є й issue #25562 у репозиторії Claude Code, де користувач повідомляв, що персональне шляхове правило збігалося з файлами основного каталогу, але не з файлами іншого репозиторію чи додаткового каталогу. Issue вказував CLI v2.1.41 та був закритий як not planned. Це звіт про досвід зі старою версією, а не нормативне пояснення чи підтвердження виправлення. Сучасні docs кажуть, що ~/.claude/rules/ застосовується до всіх проєктів, але не встановлюють точну межу шляхового збігу для кожного доданого репозиторію. Якщо цей випадок важливий для команди, відтворіть його на фактичному клієнті та задокументуйте результат.

30.11. Підсумок

Claude Code Rules дають змогу тримати тематичну настанову окремо від кореневого CLAUDE.md і, через paths, завантажувати її для відповідних файлів. Каталог допомагає підтримці; frontmatter задає шляхову область; /context і InstructionsLoaded дають свідчення завантаження. Синтаксис варто перевіряти: помилка YAML може непомітно перетворити вузький rule на загальний.

Ні місце файла, ні пізніший порядок тексту, ні шаблон paths не створюють технічної заборони. Для повторюваної процедури може бути доречнішим Skill; для контролю викликів потрібні permissions або hook; для перевірки зміни — лінтер чи CI. Під час конфлікту знайдіть власника й затверджене джерело, не покладайтеся на порядок завантаження. Під час зміни архітектури перевіряйте правила позитивним і негативним шляхом, щоб обсяг контексту відповідав реальній області коду.

Джерела

Функціональність і випуски Claude Code перевірено 10.10.2026. Офіційні сторінки Anthropic не показували дати окремої редакції; мінімальні версії наведено тільки там, де їх прямо називають docs. Посилання на продукт стосуються Claude Code, якщо явно не вказано іншу поверхню.

  1. Anthropic, How Claude remembers your project — Organize rules with .claude/rules/, доступ 10.10.2026. Розміщення, рекурсивний пошук Markdown-файлів і завантаження без paths.
  2. Anthropic, Path-specific rules, доступ 10.10.2026. YAML paths, приклади glob, момент збігу під час читання файла та обмеження розширення.
  3. Anthropic, Rule frontmatter reference, доступ 10.10.2026. Поля frontmatter, допустима форма paths і діагностика некоректного YAML.
  4. Anthropic, User-level rules, доступ 10.10.2026. Розташування користувацьких правил, порядок завантаження і попередження щодо конфліктів.
  5. Anthropic, Extend Claude with skills — Skill frontmatter reference і Using Skill frontmatter outside Claude Code, доступ 10.10.2026. paths на Skills Claude Code та відмінності інших способів розповсюдження.
  6. Anthropic, Settings files and precedence та Configure permissions, доступ 10.10.2026. Шари налаштувань і межі allow/ask/deny.
  7. Anthropic, Hooks reference, доступ 10.10.2026. Події гачків та PreToolUse.
  8. Anthropic, Claude Code releases, станом на 10.10.2026. Сторінка показувала v2.1.296 від 09.10.2026 як останню версію; інші версійні межі походять із відповідних секцій документації, а не з припущень за датою випуску.
  9. Trail of Bits, правило rules/python.md, доступ 10.10.2026; PR #60 з авторським описом перевірки, доступ 10.10.2026. Публічний приклад області й перевірки на v2.1.238.
  10. Anthropic, Issue #25562, CLI v2.1.41, закрито як not planned; доступ 10.10.2026. Історичний звіт користувача, не нормативний опис поточної поведінки.

Межі перевірки. У цій главі звірено офіційні сторінки, їхні поточні версійні примітки та відкриті GitHub-приклади. Claude Code не запускали в цільовому репозиторії, конфігурацій користувача не змінювали, прикладні команди, тести, збірку та рендеринг не виконували. Усі продукти, репозиторії прикладів міграції, файли й API у навчальних сценаріях є вигаданими, якщо прямо не позначені як публічне джерело.