Waarom negeren coding agents mijn instructies?

Waarom coding agents uw instructies negeren

Coding agents negeren uw instructies om vier redenen, en geen daarvan is dat u te beleefd was. De regel bevond zich niet in het contextvenster. De regel was te vaag om een actie aan te toetsen. Iets anders in de context sprak de regel tegen, meestal de code die de agent zojuist had gelezen. Of de regel is nog wel geladen, maar staat ver achter de huidige beurt, waardoor de agent werkt op basis van wat dichtbij staat.

Elke oorzaak heeft een eigen oplossing, dus de eerste taak is het onderscheiden hiervan. Hoofdletters en het woord IMPORTANT zijn geen diagnose. De onderstaande mechanismen gebruiken Claude Code als uitgewerkt voorbeeld, omdat het laad- en compactiegedrag daarvan per augustus 2026 in detail gedocumenteerd is. Andere tools verschillen in de details, maar vertonen in grote lijnen hetzelfde gedrag.

Eerst twee termen. Het contextvenster is het tekstblok dat het model ziet tijdens een bepaalde beurt: de system prompt, uw instructiebestanden, het gesprek en elk bestand dat de agent heeft gelezen. De harness is het programma rondom het model, het onderdeel dat bestanden van de schijf leest en dat blok samenstelt. Bijna elke klacht in dit bericht is in feite een klacht over de harness, niet over het model.

Uw instructiebestand is een bericht, geen instelling

Een instructiebestand is geen configuratie. Niets in de runtime leest CLAUDE.md en dwingt dit af. De harness leest het bestand van de schijf en plakt de tekst in het gesprek. In Claude Code wordt die inhoud afgeleverd als een gebruikersbericht dat na de systeemprompt wordt geplaatst. Dit betekent dat het model uw regels op dezelfde manier ziet als al het andere dat u heeft getypt.

Dit heeft een ongemakkelijk gevolg. Uw regels concurreren op gelijke voet met elk ander stuk tekst in het venster. Een regel is een bewering. Het bestand dat de agent zojuist heeft geopend, is bewijsmateriaal. Wanneer de twee met elkaar in tegenspraak zijn, wint het bewijsmateriaal vaak, en er wordt geen foutmelding gegenereerd. Vanuit het perspectief van het model is er immers niets misgegaan.

De officiële documentatie stelt dit duidelijk: instructiebestanden worden behandeld als context, niet als afgedwongen configuratie. Om een actie te blokkeren, ongeacht wat het model beslist, heeft u een hook nodig, geen zin. Houd die regel vast. De meeste oplossingen aan het einde van dit bericht zijn die regel toegepast op een specifiek geval.

Welke instructiebestanden worden geladen en wanneer

Claude Code doorloopt de mappenstructuur vanaf de map waarin u het heeft opgestart. Elk CLAUDE.md- en CLAUDE.local.md-bestand vanaf de root van het bestandssysteem tot aan uw werkmap wordt bij het opstarten volledig geladen. Deze worden in die volgorde samengevoegd, waardoor het bestand dat zich het dichtst bij uw opstartlocatie bevindt als laatste wordt gelezen. Binnen één map wordt het .local-bestand na het hoofdbestand toegevoegd.

Bestanden in submappen onder uw werkmap gedragen zich anders. Deze worden niet bij het opstarten geladen. Ze worden geladen op het moment dat de agent een bestand in die map leest. Hetzelfde geldt voor regels met een pad-scope in .claude/rules/ die een paths:-frontmatter-veld bevatten: deze worden aan de context toegevoegd wanneer een bijbehorend bestand wordt gelezen, niet bij elke actie.

Dat ene verschil verklaart een groot deel van de gerapporteerde problemen. U plaatst een regel in packages/api/CLAUDE.md, u stelt een vraag over de API, en de agent antwoordt zonder ooit een bestand onder packages/api/ te openen. De regel werd niet genegeerd. Hij was simpelweg niet aanwezig. Als uw repository richtlijnen verdeelt over instructiebestanden per pakket in een monorepo, is dit het eerste wat u altijd moet controleren.

Nog een valkuil bij het laden, en dit is de meest voorkomende versie van "de agent negeerde mijn instructies": Claude Code leest CLAUDE.md, niet AGENTS.md. Een repository die gestandaardiseerd is op AGENTS.md en geen CLAUDE.md heeft, geeft Claude Code niets om te laden. De ondersteunde brug is een CLAUDE.md waarvan de eerste regel @AGENTS.md is; dit importeert het bestand bij het opstarten, met eventuele Claude-specifieke notities eronder. Een symlink werkt ook als u niets extra's toe te voegen heeft. De beslissing wat er in dat bestand thuishoort, is een aparte kwestie die wordt behandeld in het scheiden van agent-instructies en menselijke documentatie.

Bevestig dat het bestand is geladen voordat u het herschrijft

Wijzig de tekst pas als u bewijs heeft dat de agent het bestand kan zien. Er zijn twee controles, en de eenvoudigste voert u als eerste uit.

Voer /context uit binnen de sessie. Dit geeft het huidige venster weer, onderverdeeld per categorie, en de lijst Memory files benoemt elk instructiebestand dat daadwerkelijk is geladen. Een bestand dat in die lijst ontbreekt, is niet aanwezig in het gesprek; alles wat u daarin schrijft, heeft dus geen effect. /memory toont de bestandslocaties en opent deze voor bewerking, inclusief bestanden die nog niet bestaan.

Voor een grondigere controle kunt u de laadacties loggen. De InstructionsLoaded hook-gebeurtenis wordt geactiveerd telkens wanneer een CLAUDE.md of een regelbestand in de context wordt geladen, en de matcher geeft aan waarom het laden plaatsvond: session_start, nested_traversal, path_glob_match, include of compact. Plaats dit in .claude/settings.json:

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

De hook ontvangt de payload als JSON via de standaardinvoer, dus cat voegt het volledige record toe. Monitor dit met tail -f /tmp/instructions-loaded.log terwijl u werkt. De exit-status van deze gebeurtenis wordt genegeerd, waardoor de hook alleen kan observeren en nooit kan blokkeren. Als uw geneste bestand tijdens een sessie waarin u het verwachtte nooit in dat logboek verschijnt, stop dan met herschrijven. Het probleem ligt bij de locatie.

Wat een lange sessie doet met uw regels

Er zijn twee afzonderlijke effecten van toepassing, die elk een andere aanpak vereisen.

Afstand. Een regel die bij beurt 1 is opgegeven, bevindt zich bij beurt 90 nog steeds in het venster, maar concurreert nu met 90 beurten aan tekst die recenter is en specifieker voor wat u op dat moment doet. U kunt dit niet wegconfigureren, maar u kunt het wel meten. Voer dezelfde taak uit in een nieuwe sessie. Als de regel daar wel standhoudt en faalt diep in een lange sessie, dan is afstand de oorzaak.

Compressie. Wanneer het venster vol raakt, vat het systeem het gesprek tot dan toe samen en gaat het verder vanaf die samenvatting. Wat overblijft is wat de samenvattingsfunctie belangrijk vond, wat niet hetzelfde is als wat u belangrijk vindt. Claude Code documenteert de uitkomst per mechanisme, en de verschillen zijn groot. Project root CLAUDE.md en regels zonder scope worden na een compressie opnieuw vanaf de schijf ingeladen. Auto memory wordt opnieuw vanaf de schijf ingeladen. Regels met paths: frontmatter gaan verloren totdat een bijbehorend bestand opnieuw wordt gelezen. Geneste CLAUDE.md bestanden in submappen gaan verloren totdat een bestand in die submap opnieuw wordt gelezen.

Rangschik uw instructies aan de hand van die tabel en de volgorde van kwetsbaarheid wordt duidelijk. Een regel die u alleen in de chat hebt getypt, is het meest kwetsbaar in de sessie: deze blijft alleen behouden als de samenvatting deze toevallig heeft bewaard. Een regel in packages/api/CLAUDE.md is de volgende in de rij, omdat deze eenmaal werd geladen, werd weggefilterd door de samenvatting en pas terugkeert bij de volgende leesactie in die map. Een regel in het project root-bestand is het meest duurzaam, omdat deze elke keer opnieuw vanaf de schijf wordt gelezen.

Dus als een instructie voor een hele sessie moet gelden, hoort deze thuis in het project root-bestand zonder paths: frontmatter. Al het andere is een afweging die u bewust moet maken. Beheer van wat in het contextvenster blijft behandelt /compact met een focus-argument en /clear tussen niet-gerelateerde taken, die beide veranderen hoe vaak de samenvattingsfunctie mag bepalen wat uw regels waren.

Waarom de omliggende code de regel overtreft

Dit is de fout die mensen het vaakst beschrijven en het minst vaak diagnosticeren. Uw bestand stelt dat databasetoegang via de repository-laag verloopt. De agent schrijft een handler die de ORM (object relational mapper) rechtstreeks aanroept. U werd niet genegeerd op basis van stijl. U werd overstemd door bewijslast.

Een regel beschrijft een voorkeur. De code demonstreert er een. Wanneer de agent drie bestanden opent in de module die hij gaat bewerken en alle drie de ORM rechtstreeks aanroepen, bevat de context aan de ene kant één abstracte zin en aan de andere kant drie concrete, recente, taakgerelateerde voorbeelden. Het kopiëren van het lokale patroon is meestal correct gedrag. Het is hier alleen fout omdat u iets weet wat de context niet weet: die bestanden zijn legacy.

Schrijf dat dus in de regel. Regels die hun eigen tegenbewijs benoemen, overleven contact met een echte repository. Regels die slechts een kale voorkeur uitspreken, doen dat niet.

Nieuwe databasetoegang verloopt via app/repositories/. Bestanden onder app/legacy/ roepen de ORM nog steeds rechtstreeks aan. Dat is oude code, niet het patroon. Kopieer dit niet.

De tweede zin doet het werk. Deze vertelt de agent wat hij gaat tegenkomen en hoe hij dit moet interpreteren, voordat hij het vindt. Hetzelfde herstel is van toepassing op elke regel die uw repository zichtbaar tegenspreekt: een commit-stijl die uw geschiedenis niet volgt, een testindeling die de helft van uw suite negeert, een importconventie die alleen in nieuwe code standhoudt. Waar de code het oneens is met het bestand, benoem het meningsverschil in het bestand.

Een vage regel is niet controleerbaar en kan dus niet worden opgevolgd

"Schrijf schone code." "Voorkom over-engineering." "Houd het simpel." "Wees voorzichtig met migraties." Geen van deze regels kan worden getoetst aan een specifieke actie, noch door de agent, noch door u. Een agent die een regel krijgt die hij niet aan zijn eigen output kan toetsen, is aan het gissen, en u beoordeelt die gok op gevoel.

Pas de volgende test toe op elke regel in uw bestand. Schrijf het shell-commando dat een non-zero exitcode geeft wanneer de regel wordt overtreden. Als u dat commando niet kunt schrijven, is de regel niet controleerbaar. Vergelijk deze paren:

• Niet controleerbaar: "Houd functies klein." Controleerbaar: "Een functie langer dan 60 regels moet voorzien zijn van een commentaar erboven waarin de reden wordt uitgelegd."
• Niet controleerbaar: "Test uw wijzigingen." Controleerbaar: "Voer npm test uit en plak het aantal fouten voordat u een taak als voltooid markeert."
• Niet controleerbaar: "Houd bestanden georganiseerd." Controleerbaar: "HTTP-handlers staan in src/api/handlers/. Niets anders mag in die map staan."
• Niet controleerbaar: "Formatteer code correct." Controleerbaar: "Gebruik 2 spaties inspringing in .ts-bestanden."

"Voorkom over-engineering" is de regel waar mensen het snelst opgeven, omdat de oplossing geen kortere zin is, maar een langere: het expliciet benoemen wat de kleinst mogelijke werkende wijziging daadwerkelijk inhoudt geeft de agent criteria waaraan hij zijn eigen diff kan toetsen.

Omvang is hetzelfde probleem in een ander jasje. De richtlijnen voor Claude Code mikken op minder dan 200 regels per instructiebestand en stellen direct dat langere bestanden de naleving verminderen. Een bestand van 700 regels is geen krachtigere instructie. Het is 700 regels aan beweringen met meer kans op onderlinge tegenstrijdigheden, en het wordt bij elke beurt in rekening gebracht in uw contextvenster, wat direct zichtbaar is in uw tokenverbruik. Het structureren van het bestand zodat elke regel onder een kop staat die een lezer kan scannen, wordt behandeld in het schrijven van een instructiebestand waar een agent op kan acteren.

Hoe u dit binnen tien minuten diagnosticeert

Voer deze stappen in volgorde uit. Het overslaan naar de laatste stap is de reden dat mensen eindigen met een lang bestand vol afgedwongen regels die nog steeds niet werken.

1. Bevestig dat het is geladen. Voer /context uit en lees de lijst met Memory-bestanden. Als het bestand daar niet staat, corrigeer dan de locatie en stop. Niets anders in deze lijst is dan nog van toepassing.
2. Reproduceer in een nieuwe sessie. Start een nieuwe sessie en voer de kleinste taak uit die de regel zou moeten activeren. Als het hier wel werkt maar in een lange sessie niet, wijst dit op afstand of compactie. Als het hier ook faalt, is de regel zelf het probleem.
3. Verwijder de concurrentie. Vraag om dezelfde wijziging in een map waarvan de bestaande code de regel al volgt. Als de naleving terugkeert, overstemde de omliggende code uw instructie.
4. Zoek naar een conflict. Twee bestanden die verschillende richtlijnen geven voor hetzelfde gedrag is een gedocumenteerde fout: het model kan er willekeurig een kiezen en zal u niet vertellen dat dit gebeurt.
5. Maak het controleerbaar en test opnieuw. Herschrijf de regel met een concreet pad en een voorwaarde. Een grote sprong in naleving betekent dat de formulering de oorzaak was.

Stap 4 is één commando. Doorzoek elke instructiebron op het onderwerp, niet alleen het bestand dat u aan het bewerken was:

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

Een treffer in twee bestanden die verschillende dingen zeggen is uw bug. Verwijder er één. Probeer ze niet te rangschikken met krachtiger bewoordingen, want er is geen rangschikkingsmechanisme om op terug te vallen.

De oplossingen, gerangschikt naar effectiviteit

Elke onderstaande stap heeft meer effect dan de voorgaande, maar vereist ook meer configuratie. Begin bovenaan wanneer een regel eenvoudig te herformuleren is. Stap over naar een lagere optie zodra een regel zo belangrijk wordt dat incidentele fouten onacceptabel zijn.

1. Maak de regel concreet. Benoem een pad, een commando of een voorwaarde. Voeg het tegenbewijs toe dat de agent in de repository zal vinden, zoals eerder getoond. Dit kost niets en lost een verrassend groot deel van de gevallen op.
2. Plaats de regel dichter bij wat hij reguleert. Een geneste CLAUDE.md, een regel met een specifiek pad in .claude/rules/, of een opmerking bovenaan het bestand zelf. De regel wordt dan gelezen op hetzelfde moment als de code waarop deze van toepassing is. Accepteer de afweging: alles wat op die manier wordt geladen, vervalt bij de volgende compactie en keert terug bij de volgende relevante leesactie.
3. Verplaats de handhaving naar een hook. Tekst vraagt. Een hook beslist. Hooks draaien als code tijdens vaste lifecycle-events en worden toegepast ongeacht wat het model concludeert.
4. Geef de regel aan een deterministische tool en verwijder de tekst. Formattering, importvolgorde, regelbreedte, verboden imports, structuur van commit-berichten. ruff format, prettier --write, eslint, een pre-commit hook. De formatter heeft altijd gelijk en kost nul tokens. De zin heeft meestal gelijk en kost bij elke beurt tokens.

Stap 3 in detail. Stel dat migratiebestanden nooit door de agent mogen worden bewerkt. Plaats dit in .claude/settings.json:

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

En dit in .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

Voer chmod +x .claude/hooks/guard-migrations.sh uit, start daarna een nieuwe sessie en vraag de agent om een bestand onder migrations/ te bewerken. De bewerking wordt geweigerd en uw bericht wordt als reden teruggegeven. Exit status 2 in PreToolUse blokkeert de tool-aanroep voordat deze wordt uitgevoerd, en uw stderr-tekst wordt aan het model doorgegeven als blokkerend bericht. ${CLAUDE_PROJECT_DIR} verwijst naar de root van het project, waardoor de hook werkt ongeacht in welke map de agent zich bevindt. De agent hoeft het niet eens te zijn met de regel, de regel niet te onthouden en de regel niet in de context te hebben. De bewerking vindt niet plaats.

Voor een absoluut verbod zonder logica, doet permissions.deny in uw instellingen hetzelfde werk zonder dat er een script onderhouden hoeft te worden, en de permissiemodi bepalen wat wordt uitgevoerd zonder u eerst te vragen. Als een instructie echt op het niveau van de system prompt moet staan in plaats van in een gebruikersbericht, plaatst --append-system-prompt deze daar, hoewel dit bij elke aanroep moet worden meegegeven, wat beter geschikt is voor scripts dan voor interactief werk.

Wat u niet kunt afdwingen met instructies

Wees duidelijk over welk deel hiervan uw verantwoordelijkheid is. Plaatsing, formulering, conflicten tussen bestanden en bestandsgrootte zijn problemen van de auteur die door de auteur moeten worden opgelost. De rest is gedrag van het model; betere bewoordingen zullen dit niet wegnemen.

Instemming is geen naleving. Een agent zal een regel erkennen, deze correct aan u herhalen en deze twee tool-aanroepen later alsnog overtreden. De erkenning kost niets en voorspelt niets. Zie dit niet als een oplossing en beschouw het niet als een test.

Sommige gewoonten zijn hardnekkig. Het toevoegen van commentaar, het toevoegen van defensieve foutafhandeling, het schrijven van een afsluitende samenvatting, het uitvoeren van het voor de hand liggende volgende commando. Deze keren terug onder een regel die ze verbiedt, zij het in mindere mate in plaats van volledig. U kunt uw eigen foutmarge meten: voer dezelfde taak tien keer uit in nieuwe sessies en tel de overtredingen. Waar dat aantal nul moet zijn, moet de regel uit de prompt worden verwijderd.

Uw eigen sessie wordt een voorbeeld. Als de agent de regel in beurt 12 overtrad en u liet dit passeren, dan fungeert die overtreding nu als demonstratie in de context, en deze is veel recenter dan de regel zelf. Corrigeer een overtreding zodra u deze ziet. Een ongecorrigeerde overtreding is bepalend voor de rest van de sessie.

Een instructiebestand is geen beveiligingsgrens. Het vormt het gedrag, maar dwingt het niet af. Alles waarbij een fout kostbaar is, zoals inloggegevens of destructieve commando's, hoort thuis in rechtenstructuren of een hook. Geheimen buiten bereik van een agent houden past hetzelfde principe toe op data: vraag een agent niet om een bestand niet te lezen, maar zorg ervoor dat het bestand niet leesbaar is.

De korte versie. Bewijs dat het bestand is geladen, maak de regel controleerbaar, plaats deze naast het object waarvoor hij geldt, en wanneer de foutmarge nog steeds van belang is, haal de regel dan uit de tekst. Een regel die een agent niet kan negeren, is een regel die nooit aan de agent is gevraagd.

FAQ

Waarom negeert Claude Code mijn CLAUDE.md?

Controleer of het bestand is geladen voordat u aanneemt dat het wordt genegeerd. Voer /context uit en bekijk de lijst Memory files; een bestand dat daar niet wordt genoemd, maakt geen deel uit van het gesprek. Instructiebestanden worden als een gebruikersbericht na de systeemprompt afgeleverd en worden behandeld als context in plaats van als afgedwongen configuratie, waardoor er geen strikte nalevingsgarantie is. De meeste gevallen zijn terug te voeren op vier oorzaken: het bestand staat in een submap die de agent nooit heeft gelezen, twee bestanden spreken elkaar tegen en het model heeft er willekeurig een gekozen, de regel is te vaag om een actie aan te toetsen, of de omliggende code demonstreert het tegenovergestelde van wat de regel voorschrijft.

Verandert het bewerken van het instructiebestand tijdens een sessie iets?

Niet voor de kopie die zich al in het gesprek bevindt. Bestanden boven uw werkmap worden bij het opstarten volledig geladen, dus de tekst die het model vasthoudt, is de tekst van het moment van opstarten. Om een wijziging door te voeren, start u een nieuwe sessie of vraagt u de agent om het bestand te lezen met de normale bestandstools, waardoor de huidige versie als een nieuw bericht in het gesprek wordt opgenomen. Na een compactie wordt het bestand in de project-root opnieuw vanaf de schijf gelezen, waardoor de nieuwe versie op dat moment ook wordt ingeladen.

Welk bestand wint er als een CLAUDE.md in de root en een genest bestand elkaar tegenspreken?

Geen van beide, op betrouwbare wijze. Gevonden bestanden worden aan de context toegevoegd in plaats van elkaar te overschrijven, waarbij de volgorde van de root van het bestandssysteem naar beneden naar uw werkmap loopt; het dichtstbijzijnde bestand wordt dus simpelweg als laatste gelezen. Er is geen prioriteitsmechanisme dat tegenstrijdigheden oplost, en de documentatie van Claude Code stelt dat tegenstrijdige regels willekeurig kunnen worden opgelost. Schrijf geneste bestanden als toevoegingen die het pad benoemen waarvoor ze gelden, en verwijder de tegenstrijdigheid in plaats van te proberen deze te overtroeven.

Blijven mijn instructies behouden na /compact?

Dit hangt af van hoe ze zijn geladen. Regels in de project-root CLAUDE.md, niet-gescoped regels en automatisch geheugen worden na een compactie opnieuw vanaf de schijf ingevoegd. Regels met paths: frontmatter en geneste CLAUDE.md-bestanden in submappen gaan verloren totdat een overeenkomstig bestand opnieuw wordt gelezen. Alles wat u alleen in de chat hebt getypt, blijft alleen behouden als de samenvattingsfunctie het toevallig heeft bewaard. Als een regel gedurende een hele sessie moet gelden, plaats deze dan in het bestand in de project-root zonder paths: frontmatter.

Wanneer moet een regel een hook worden in plaats van tekst?

Wanneer de controle deterministisch is en de kosten van een misser hoger zijn dan de kosten van het schrijven van een klein script. Beperkingen op bestandspaden, vereiste commando's voor een commit en verboden tool-aanroepen komen hiervoor in aanmerking. Een PreToolUse-hook die afsluit met status 2 blokkeert de tool-aanroep volledig en geeft uw stderr-tekst terug aan het model als reden, waardoor deze van kracht blijft, ongeacht of de regel zich nog ergens in de context bevindt. Alles waarover een formatter of linter kan beslissen, moet door die tool worden beheerd en volledig uit het instructiebestand worden verwijderd.