SSD Nodes Learn Hosting plans →
Посібники Matt ConnorВід Matt Connor · Оновлено 2026-10-26

Чому coding agents ігнорують ваші інструкції

Файл інструкцій містить правило stop, але agent продовжує роботу. Дізнайтеся про 4 причини та перевірку, яку варто виконати до зміни правила.

Чому coding agents ігнорують ваші інструкції

Coding agents ігнорують ваші інструкції з 4 причин, і жодна з них не полягає в тому, що ви були недостатньо наполегливими. Правило ніколи не потрапило у context window. Правило було надто нечітким, щоб зіставити з ним дію. Щось інше в контексті суперечило цьому правилу — зазвичай код, який agent щойно прочитав. Або правило все ще завантажене, але розташоване далеко позаду поточного turn, і agent працює з тим, що знаходиться ближче.

Для кожної причини є окреме виправлення, тому спочатку потрібно їх розрізнити. Великі літери та слово IMPORTANT не допомагають встановити причину. Нижче описано механіку на прикладі Claude Code, оскільки станом на October 2026 його поведінку під час завантаження та compaction докладно задокументовано. Інші інструменти відрізняються деталями, але загалом працюють так само.

Спочатку визначимо 2 терміни. Context window — це блок тексту, який модель бачить у певному turn: system prompt, ваші файли інструкцій, розмова та кожен файл, прочитаний agent. Harness — це програма навколо моделі, яка читає файли з диска та формує цей блок. Майже кожна скарга в цьому дописі насправді стосується harness, а не моделі.

Файл інструкцій — це повідомлення, а не налаштування

Файл інструкцій не є конфігурацією. Середовище виконання не зчитує CLAUDE.md і не забезпечує його дотримання. Harness зчитує файл із диска та вставляє його текст у розмову. У Claude Code цей вміст надходить як повідомлення користувача після системного промпту. Отже, модель бачить ваші правила так само, як і будь-який інший введений вами текст.

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

В офіційній документації це сказано прямо: файли інструкцій розглядаються як контекст, а не як конфігурація, виконання якої забезпечується. Щоб заблокувати дію незалежно від рішення моделі, потрібен hook, а не речення. Запам’ятайте цей принцип. Більшість виправлень наприкінці цього допису є застосуванням цього принципу до конкретного випадку.

Які файли інструкцій завантажуються і коли

Claude Code проходить вгору деревом каталогів, починаючи з каталогу, у якому ви його запустили. Усі CLAUDE.md і CLAUDE.local.md від кореня файлової системи до робочого каталогу завантажуються повністю під час запуску. Вони об’єднуються в цьому порядку, тому файл, найближчий до каталогу запуску, читається останнім. У межах одного каталогу файл .local додається після основного файла.

Файли в підкаталогах нижче робочого каталогу працюють інакше. Вони не завантажуються під час запуску. Вони завантажуються, коли агент читає файл у відповідному каталозі. Те саме стосується правил із визначеною областю дії для шляхів у .claude/rules/, які містять поле frontmatter paths:: вони додаються до контексту, коли читається відповідний файл, а не під час кожного ходу. Починаючи з v2.1.309, для файлів, що завантажуються таким способом, також діє обмеження розміру для кожного файла: 40,000 символів у контекстному вікні на 200K. Тому агент отримує лише початок довшого файла, і правила наприкінці великого вкладеного файла можуть ніколи не потрапити до контексту.

Ця відмінність пояснює значну частину повідомлень про помилки. Ви додаєте правило до packages/api/CLAUDE.md, ставите запитання про API, а агент відповідає, навіть не відкривши файл у packages/api/. Правило не було проігнороване. Воно просто не було присутнє. Якщо у вашому репозиторії вказівки розподілені між файлами інструкцій для кожного пакета в монорепозиторії, це потрібно перевіряти насамперед щоразу.

Є ще одна проблема із завантаженням у репозиторіях, де стандартизували інструкції на AGENTS.md. Починаючи з v2.1.277, Claude Code за замовчуванням читає AGENTS.md як інструкції проєкту, але лише тоді, коли у робочому каталозі або в будь-якому каталозі вище немає CLAUDE.md, .claude/CLAUDE.md чи CLAUDE.local.md. Ваш особистий ~/.claude/CLAUDE.md не враховується. Додайте будь-який із цих файлів, навіть CLAUDE.local.md для особистих нотаток, і Claude Code натомість читатиме ваші файли CLAUDE.md, повністю виключивши AGENTS.md. Щоб завантажувати обидва файли, у /config задайте Project instructions як claude-md-and-agents-md. У версіях до v2.1.277 або коли потрібно зберегти CLAUDE.md, використовуйте CLAUDE.md, першим рядком якого є @AGENTS.md. Він імпортує файл під час запуску, а нижче можна додати будь-які нотатки для Claude. Символічне посилання також працює, якщо додаткові вказівки не потрібні. Визначення того, що саме має міститися в цьому файлі, — окреме питання. Воно розглядається в матеріалі розділення інструкцій для агента та документації для людей.

Перевірте, що файл завантажено, перш ніж переписувати його

Не змінюйте формулювання, доки не переконаєтеся, що агент бачить файл. Є дві перевірки. Спочатку виконайте простішу.

Виконайте /context у сесії. Команда показує поточне вікно, розподілене за категоріями, а список Memory files містить назви всіх файлів інструкцій, завантажених під час запуску. Якщо файлу немає в цьому списку, його не було завантажено під час запуску. Тому нічого записане в ньому не матиме ефекту, доки його не буде завантажено. Вкладений файл у підкаталозі ніколи не з’являється в цьому списку, оскільки завантажується за потреби. Після завантаження в терміналі з’являється рядок Loaded із його шляхом. /memory показує розташування файлів і відкриває їх для редагування, зокрема файли, яких ще не існує.

Для точнішої перевірки реєструйте завантаження. Подія hook InstructionsLoaded спрацьовує щоразу, коли в контекст додається CLAUDE.md або файл правил. Її matcher показує причину завантаження: session_start, nested_traversal, path_glob_match, include або compact. Додайте це до .claude/settings.json:

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "matcher": "nested_traversal",
        "hooks": [
          {
            "type": "command",
            "command": "cat >> /tmp/instructions-loaded.log"
          }
        ]
      }
    ]
  }
}

Hook отримує дані у форматі JSON через стандартний ввід, тому cat дописує весь запис. Переглядайте його за допомогою tail -f /tmp/instructions-loaded.log під час роботи. Код завершення цієї події ігнорується, тому hook може лише спостерігати й не може блокувати виконання. Якщо вкладений файл не з’являється в цьому журналі під час сесії, у якій ви очікували його завантаження, припиніть змінювати формулювання. Проблема полягає в розташуванні файлу. Є один виняток: AGENTS.md, який Claude Code читає безпосередньо, не викликає цю подію. Тому шукайте його шлях у /memory. AGENTS.md, імпортований із CLAUDE.md, викликає цю подію як завжди.

Як тривала сесія впливає на ваші правила

Тут діють два окремі ефекти, і кожен потребує іншого підходу.

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

Compaction. Коли вікно заповнюється, harness узагальнює попередню частину розмови й продовжує роботу на основі цього резюме. Зберігається те, що summariser визнав важливим. Це не обов’язково збігається з тим, що вважаєте важливим ви. Claude Code документує результат для кожного механізму, і відмінності значні. Файл у корені проєкту CLAUDE.md і правила без області дії повторно завантажуються з диска після compaction. Auto memory також повторно завантажується з диска. Правила з frontmatter paths: втрачаються, доки знову не буде прочитано відповідний файл. Вкладені файли CLAUDE.md у підкаталогах втрачаються, доки знову не буде прочитано файл у цьому підкаталозі.

Розташуйте інструкції за цією таблицею, і порядок їхньої ненадійності стане очевидним. Правило, яке ви лише ввели в чаті, є найменш надійним у сесії: воно зберігається лише в тому разі, якщо summariser випадково залишив його в резюме. Правило у packages/api/CLAUDE.md є наступним за ненадійністю, оскільки його було завантажено один раз, потім вилучено під час узагальнення, і воно повернеться лише під час наступного читання в цьому каталозі. Правило у файлі в корені проєкту є найнадійнішим, оскільки цей файл щоразу повторно читається з диска.

Тому інструкцію, яка має діяти протягом усієї сесії, слід зберігати у файлі в корені проєкту без frontmatter paths:. Усе інше є компромісом, який потрібно обирати свідомо. У розділі Керування тим, що залишається у вікні контексту розглядаються /compact за допомогою focus argument і /clear між не пов’язаними завданнями. Обидва чинники змінюють частоту, з якою summariser визначає, які саме ваші правила збереглися.

Чому оточувальний код переважає правило

Це помилка, про яку найчастіше повідомляють і найрідше правильно діагностують. У вашому файлі зазначено, що доступ до бази даних має виконуватися через шар репозиторію. Агент створює обробник, який безпосередньо викликає ORM (object relational mapper). Вас проігнорували не через стиль. Вас переважили наявні приклади.

Правило описує перевагу. Код демонструє одну з них. Коли агент відкриває три файли в модулі, який збирається редагувати, і в усіх трьох безпосередньо викликається ORM, контекст містить одне абстрактне речення з одного боку та три конкретні, нещодавні приклади, що відповідають завданню, — з іншого. Зазвичай копіювати локальний шаблон є правильною поведінкою. У цьому випадку це неправильно лише тому, що ви знаєте те, чого не знає контекст: ці файли є legacy-кодом.

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

Новий доступ до бази даних має виконуватися через app/repositories/. У файлах під app/legacy/ досі викликається ORM безпосередньо. Це старий код, а не шаблон. Не копіюйте його.

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

Розпливчасте правило не можна перевірити, тому його неможливо виконати

"Пишіть чистий код." "Не ускладнюйте." "Зберігайте простоту." "Будьте обережні з міграціями." Жодне з цих правил не можна перевірити за конкретною дією — ні агентом, ні вами. Агент, якому дали правило, яке він не може перевірити за власним результатом, вгадує, а ви оцінюєте це вгадування на око.

Застосовуйте до кожного рядка у файлі таку перевірку. Напишіть shell-команду, яка завершуватиметься з ненульовим кодом, якщо правило порушено. Якщо ви не можете написати таку команду, правило не є перевірюваним. Порівняйте ці пари:

  • Неперевірюване: "Тримайте функції малими." Перевірюване: "Функція довша за 60 рядків має містити над нею коментар із поясненням причини."
  • Неперевірюване: "Тестуйте зміни." Перевірюване: "Виконайте npm test і вставте кількість помилок перед тим, як позначити завдання виконаним."
  • Неперевірюване: "Підтримуйте впорядкованість файлів." Перевірюване: "HTTP-обробники розташовані в src/api/handlers/. В інших місцях цього каталогу нічого немає."
  • Неперевірюване: "Правильно форматуйте код." Перевірюване: "У файлах .ts використовуйте відступ у 2 пробіли."

"Не ускладнюйте" — це правило люди здаються уточнювати найчастіше, оскільки виправлення полягає не в коротшому реченні, а в довшому: чітке визначення того, що саме означає найменша працездатна зміна дає агенту критерії, з якими він може порівняти власний diff.

Розмір створює ту саму проблему під іншим виглядом. Рекомендації Claude Code передбачають менше ніж 200 рядків у файлі інструкцій і прямо зазначають, що довші файли знижують дотримання інструкцій. Файл на 700 рядків не містить чіткіших інструкцій. Це 700 тверджень, які мають більше шансів суперечити одне одному, і вони враховуються у вашому контекстному вікні під час кожного запиту, що безпосередньо відображається у використанні токенів. Структурування файлу так, щоб кожне правило містилося під заголовком, який читач може швидко переглянути, описано в матеріалі як написати файл інструкцій, з яким агент може працювати. Ще краще — вилучіть частини, які описують, а не дають інструкцій: огляд каталогів із розташуванням обробників і моделей — це структура, яку агент може за потреби отримати з розібраної карти репозиторію, замість того щоб зберігати її в контекстному вікні під час кожного запиту.

Як діагностувати проблему за десять хвилин

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

  1. Перевірте, чи файл завантажено. Виконайте /context і перегляньте список Memory files або, якщо це вкладений файл, знайдіть його рядок Loaded у терміналі. Якщо файла немає, виправте шлях і зупиніться. Решта пунктів цього списку наразі не застосовується.
  2. Відтворіть проблему в новому сеансі. Запустіть новий сеанс і поставте найменше завдання, яке має активувати правило. Якщо правило працює тут, але не працює в довгому сеансі, проблема, імовірно, пов’язана з дистанцією або compaction. Якщо воно не працює і тут, проблема в самому правилі.
  3. Усуньте конкуренцію. Попросіть виконати ту саму зміну в каталозі, наявний код якого вже відповідає правилу. Якщо дотримання правила відновиться, навколишній код переважив вашу вказівку.
  4. Знайдіть конфлікт. Два файли з різними вказівками щодо тієї самої поведінки — це документована причина збою: модель може довільно вибрати одну вказівку й не повідомить про це.
  5. Зробіть правило таким, що його можна перевірити, і повторіть тест. Перепишіть правило, додавши конкретний шлях і умову. Значне підвищення відповідності означає, що причиною було формулювання.

Крок 4 виконується однією командою. Виконайте пошук теми в усіх джерелах інструкцій, а не лише у файлі, який ви редагували:

grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null

Збіг у двох файлах із різними вказівками — це ваша помилка. Видаліть одну з них. Не намагайтеся визначити пріоритет за допомогою категоричніших формулювань, оскільки механізму визначення пріоритету немає. У Claude Code v2.1.283 або новішій версії /doctor prompt-audit виконує розширений пошук у файлах інструкцій, правилах і skills та повідомляє про суперечності із запропонованими змінами, не вносячи їх, доки ви не дасте відповідну команду.

Виправлення в порядку зростання впливу

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

  1. Зробіть правило конкретним. Укажіть шлях, команду або умову. Додайте вказівки, які суперечать цьому правилу і які агент знайде в репозиторії, як описано вище. Це нічого не коштує та усуває несподівано велику кількість проблем.
  2. Розмістіть правило ближче до об’єкта, якого воно стосується. Використайте вкладений CLAUDE.md, правило для певного шляху в .claude/rules/ або коментар на початку самого файлу. Тоді правило буде прочитане разом із кодом, до якого воно застосовується. Враховуйте компроміс: усе, що завантажується таким способом, зникає під час наступного скорочення контексту й повертається під час наступного відповідного читання.
  3. Перенесіть контроль у hook. Текстова інструкція лише просить. Hook приймає рішення. Hooks запускаються як код у визначені моменти життєвого циклу та застосовуються незалежно від висновку моделі.
  4. Передайте правило детермінованому інструменту й видаліть текстову інструкцію. Форматування, порядок імпортів, довжина рядків, заборонені імпорти, формат повідомлення коміту. ruff format, prettier --write, eslint, hook pre-commit. Formatter щоразу працює правильно й не витрачає токени. Речення здебільшого правильне, але витрачає токени під час кожного запиту.

Крок 3 повністю. Припустімо, агенту заборонено редагувати файли міграцій. Додайте це до .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
          }
        ]
      }
    ]
  }
}

А це — до .claude/hooks/guard-migrations.sh:

#!/usr/bin/env bash
set -euo pipefail

path=$(jq -r '.tool_input.file_path // empty')

case "$path" in
  */migrations/*)
    echo "Files under migrations/ are written by hand. Stop and ask first." >&2
    exit 2
    ;;
esac

exit 0

Запустіть chmod +x .claude/hooks/guard-migrations.sh, потім почніть новий сеанс і попросіть агента відредагувати файл у migrations/. Редагування буде відхилено, а ваше повідомлення повернеться як причина. Код завершення 2 у PreToolUse блокує виклик інструменту до його запуску, а текст зі stderr передається моделі як повідомлення про блокування. ${CLAUDE_PROJECT_DIR} розгортається в кореневий каталог проєкту, тому hook працює незалежно від поточного каталогу агента. Агенту не потрібно погоджуватися з правилом, пам’ятати його або все ще мати його в контексті. Редагування не виконується.

Для простої заборони без логіки permissions.deny у ваших налаштуваннях виконує ту саму функцію без скрипту, який потрібно супроводжувати, а режими дозволів визначають, що запускається без додаткового запиту до вас. Якщо інструкція справді має бути на рівні системного prompt, а не в повідомленні користувача, --append-system-prompt розміщує її там. Проте це launch flag, який потрібно знову передавати під час запуску кожного нового сеансу, тому він краще підходить для скриптів, ніж для інтерактивної роботи.

Що неможливо забезпечити самими інструкціями

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

Згода не означає дотримання. Агент підтвердить правило, правильно повторить його та порушить через два виклики інструментів. Таке підтвердження нічого не коштує й нічого не прогнозує. Не сприймайте його як виправлення та не зараховуйте як тест.

Деякі звички зберігаються. Додавання коментарів, додавання захисної обробки помилок, написання підсумку наприкінці, виконання очевидної наступної команди. Вони знову проявляються навіть за наявності правила, яке їх забороняє, але з меншою, а не нульовою частотою. Ви можете виміряти власну частоту: виконайте те саме завдання 10 разів у нових сеансах і порахуйте порушення. Якщо це число має дорівнювати нулю, правило потрібно прибрати з prompt. Передчасне оголошення завдання завершеним, коли частина роботи ще не виконана, має ту саму природу звички. Виправлення має бути структурним, а не словесним: skill unlazy замінює речення на Depth Tree і gate files, які агент має пройти, перш ніж може оголосити завдання завершеним.

Ваш власний сеанс стає прикладом. Якщо агент порушив правило на 12-му ході, а ви це пропустили, порушення залишається в контексті як приклад і є значно новішим за саме правило. Виправляйте порушення одразу після його виявлення. Невиправлене порушення навчає решту сеансу.

Файл інструкцій не є межею безпеки. Він формує поведінку, але не забезпечує її дотримання. Усе, де помилка має високу ціну, зокрема облікові дані або деструктивні команди, потрібно захищати за допомогою permissions або hook. Тримайте секрети поза межами доступу агента застосовує той самий принцип до даних: не просіть агента не читати файл, зробіть так, щоб файл не можна було прочитати.

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

FAQ

Чому Claude Code ігнорує мій CLAUDE.md?

Спочатку перевірте, чи файл було завантажено. Виконайте /context і перегляньте список Memory files; якщо файл не зазначений у ньому, його не було завантажено під час запуску. Файли інструкцій передаються як user message після system prompt і розглядаються як контекст, а не як примусова конфігурація, тому суворе дотримання не гарантується. У більшості реальних випадків причина одна з чотирьох: файл розташований у підкаталозі, з якого агент не читав дані; два файли містять суперечливі правила, і модель випадково обрала одне з них; правило надто нечітке, щоб зіставити його з дією; або навколишній код демонструє поведінку, протилежну правилу.

Чи впливає редагування файлу інструкцій під час сеансу?

Не для копії файлу, яка вже є в діалозі. Файли над робочим каталогом повністю завантажуються під час запуску, тому модель має текст у стані на момент запуску. Щоб застосувати зміни, почніть новий сеанс або попросіть агента прочитати файл за допомогою стандартних file tools. У такому разі поточна версія буде додана до діалогу як нове повідомлення. Після compaction файл у корені проєкту повторно читається з диска, тому нова версія також з’являється на цьому етапі.

Який файл має пріоритет, якщо кореневий CLAUDE.md і вкладений файл містять суперечливі правила?

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

Чи зберігаються мої інструкції після /compact?

Це залежить від способу їх завантаження. Кореневий файл проєкту CLAUDE.md, правила без області дії та auto memory повторно додаються з диска після compaction. Правила з frontmatter paths: і вкладені файли CLAUDE.md у підкаталогах втрачаються, доки відповідний файл не буде прочитано знову. Усе, що ви ввели лише в чаті, зберігається тільки в разі, якщо summariser включив це до результату. Якщо правило має діяти протягом усього сеансу, розмістіть його у файлі в корені проєкту без frontmatter paths:.

Коли правило слід реалізувати як hook, а не як текстову інструкцію?

Коли перевірка є детермінованою, а вартість пропуску вища за вартість написання невеликого скрипту. Обмеження шляхів до файлів, обов’язкові команди перед commit і заборонені виклики інструментів відповідають цій умові. PreToolUse hook, який завершується зі статусом 2, безпосередньо блокує виклик інструмента та передає текст stderr моделі як причину. Тому правило діє незалежно від того, чи залишається воно в контексті. Усе, що може визначити formatter або linter, має перевірятися цим інструментом, а відповідне правило слід повністю видалити з файлу інструкцій.

Чи була ця стаття корисною?