కోడింగ్ ఏజెంట్లు మీ సూచనలు ఎందుకు పట్టించుకోవు

కోడింగ్ ఏజెంట్లు మీ సూచనలను ఎందుకు పట్టించుకోవు

కోడింగ్ ఏజెంట్లు మీ సూచనలను పట్టించుకోకపోవడానికి నాలుగు కారణాలు ఉన్నాయి. వాటిలో ఏదీ మీరు మర్యాదగా వ్యవహరించలేదనేది కాదు. ఆ నియమం context window లోకి ఎప్పుడూ రాలేదు. లేదా ఆ నియమం చాలా అస్పష్టంగా ఉండి, ఒక చర్యను దానితో పోల్చి పరిశీలించడం సాధ్యం కాలేదు. కొన్నిసార్లు context లోని మరొక విషయం ఆ నియమానికి విరుద్ధంగా ఉంటుంది. సాధారణంగా ఏజెంట్ అప్పుడే చదివిన code ఇందుకు కారణమవుతుంది. మరొక సందర్భంలో నియమం ఇంకా load అయి ఉంటుంది, కానీ ప్రస్తుత turn కు చాలా వెనుకగా ఉంటుంది. అప్పుడు ఏజెంట్ తనకు సమీపంలో ఉన్న విషయాల ఆధారంగా పనిచేస్తుంది.

ప్రతి కారణానికి ప్రత్యేక పరిష్కారం ఉంటుంది. కాబట్టి మొదటి పని వాటిని వేరు చేయడం. పెద్ద అక్షరాలు లేదా IMPORTANT అనే పదం ఉపయోగించడం diagnosis కాదు. క్రింది విధానాల్లో August 2026 నాటికి loading మరియు compaction ప్రవర్తనపై వివరమైన documentation ఉన్నందున Claude Code ను ఉదాహరణగా తీసుకున్నాం. ఇతర tools లో వివరాలు మారవచ్చు. అయితే మొత్తం మీద వాటి ప్రవర్తన ఒకే విధంగా ఉంటుంది.

ముందుగా రెండు terms తెలుసుకోవాలి. context window అంటే ఒక turn లో model చూసే text block. ఇందులో system prompt, మీ instruction files, conversation, మరియు agent చదివిన ప్రతి file ఉంటాయి. harness అంటే model చుట్టూ పనిచేసే program. ఇది disk నుంచి files చదివి ఆ text block ను సిద్ధం చేస్తుంది. ఈ post లోని దాదాపు ప్రతి ఫిర్యాదు వాస్తవానికి model గురించి కాదు; harness గురించి.

మీ instruction file ఒక message, setting కాదు

Instruction file అనేది configuration కాదు. Runtime లోని ఏదీ CLAUDE.md ను చదివి అమలు చేయదు. Harness disk నుంచి ఆ file ను చదివి, దాని text ను conversation లో paste చేస్తుంది. Claude Code లో ఆ content system prompt తర్వాత ఉంచిన user message గా అందుతుంది. అందువల్ల మీరు టైప్ చేసిన ఇతర విషయాలను model ఎలా చూస్తుందో, మీ rules ను కూడా అదే విధంగా చూస్తుంది.

దీనివల్ల ఒక అసౌకర్యకరమైన విషయం ఏర్పడుతుంది. Window లోని ప్రతి ఇతర text తో మీ rules సమాన స్థాయిలో పోటీ పడతాయి. ఒక rule అనేది ఒక claim మాత్రమే. Agent ఇప్పుడే తెరిచిన file మాత్రం evidence. ఈ రెండూ విభేదించినప్పుడు evidence తరచుగా గెలుస్తుంది. ఎలాంటి error కూడా కనిపించదు, ఎందుకంటే model దృష్టిలో ఏదీ తప్పుగా జరగలేదు.

Official documentation దీనిని స్పష్టంగా చెబుతుంది: instruction files ను enforced configuration గా కాకుండా context గా పరిగణిస్తారు. Model తీసుకునే నిర్ణయం ఏదైనా సరే ఒక action ను నిరోధించాలంటే sentence కాదు, hook అవసరం. ఆ విషయాన్ని గుర్తుంచుకోండి. ఈ post చివరలో ఉన్న చాలా fixes, నిర్దిష్ట సందర్భానికి వర్తింపజేసిన ఇదే నియమం.

ఏ instruction files లోడ్ అవుతాయి, ఎప్పుడు

Claude Code ను ప్రారంభించిన directory నుంచి directory treeలో పైకి వెళ్తుంది. filesystem root నుంచి మీ working directory వరకు ఉన్న ప్రతి CLAUDE.md మరియు CLAUDE.local.md launch సమయంలో పూర్తిగా లోడ్ అవుతుంది. అవి ఆ క్రమంలో కలపబడతాయి. అందువల్ల మీరు Claude Code ను ప్రారంభించిన స్థానానికి అత్యంత సమీపంలోని file చివరగా చదవబడుతుంది. ఒకే directoryలో .local file ప్రధాన file తర్వాత జోడించబడుతుంది.

మీ working directoryకి క్రింద ఉన్న subdirectoriesలోని files భిన్నంగా పనిచేస్తాయి. అవి launch సమయంలో లోడ్ కావు. Agent ఆ directoryలోని fileను చదివినప్పుడు అవి లోడ్ అవుతాయి. .claude/rules/ లోని path scoped rulesకు paths: frontmatter field ఉన్నప్పుడు కూడా ఇదే విధానం వర్తిస్తుంది. Matching file చదివినప్పుడు అవి contextలోకి వస్తాయి; ప్రతి turnలో కాదు.

నివేదించబడిన failuresలో పెద్ద భాగాన్ని ఈ ఒక్క తేడా వివరిస్తుంది. మీరు packages/api/CLAUDE.md లో ఒక rule ఉంచి, API గురించి ప్రశ్న అడిగారు. కానీ agent packages/api/ కింద ఉన్న ఏ fileనూ తెరవకుండానే సమాధానం ఇచ్చింది. ఆ ruleను విస్మరించలేదు. అది contextలో ఎప్పుడూ లేదు. మీ repositoryలో monorepoలో ప్రతి packageకు instruction files గా guidanceను విభజించి ఉంటే, ప్రతిసారీ ముందుగా ఇదే తనిఖీ చేయాలి.

మరొక loading trap ఉంది. “agent నా instructionsను విస్మరించింది” అనే సమస్యలో ఇదే అత్యంత సాధారణ కారణం: Claude Code AGENTS.md ను కాదు, CLAUDE.md ను చదువుతుంది. AGENTS.md ను standardగా ఉపయోగించే, కానీ CLAUDE.md లేని repositoryలో Claude Code లోడ్ చేయడానికి ఏమీ ఉండదు. దీనికి మద్దతు ఉన్న bridge ఒక CLAUDE.md. దాని మొదటి line @AGENTS.md గా ఉండాలి. ఇది launch సమయంలో fileను import చేస్తుంది; దాని కింద Claude-specific notes ఉండవచ్చు. అదనంగా ఏమీ చేర్చాల్సిన అవసరం లేకపోతే symlink కూడా పనిచేస్తుంది. మొదటగా ఆ fileలో ఏవి ఉండాలో నిర్ణయించడం వేరే విషయం. దాని గురించి agent instructionsను human documentation నుంచి వేరు చేయడం లో వివరించబడింది.

మీరు దాన్ని తిరిగి రాయడానికి ముందు ఫైల్ లోడ్ అయిందని నిర్ధారించండి

Agent ఫైల్‌ను చూడగలదని నిర్ధారించే ఆధారం లభించే వరకు వాక్యాలను మార్చవద్దు. దీనికి రెండు తనిఖీలు ఉన్నాయి. ముందుగా తక్కువ ఖర్చుతో కూడిన తనిఖీ చేయండి.

సెషన్‌లో /context అమలు చేయండి. ఇది ప్రస్తుత window ను categoryల వారీగా చూపిస్తుంది. వాస్తవంగా లోడ్ అయిన ప్రతి instruction file పేరును Memory files జాబితా చూపిస్తుంది. ఆ జాబితాలో లేని ఫైల్ conversation లో లేదు. అందువల్ల దానిలో మీరు ఏది రాసినా ప్రభావం ఉండదు. /memory ఫైల్ స్థానాలను చూపించి, ఇంకా ఉనికిలో లేని వాటితో సహా వాటిని editing కోసం తెరుస్తుంది.

మరింత నిర్ధిష్టమైన సమాధానం కోసం loads ను log చేయండి. ఏదైనా CLAUDE.md లేదా rules file context లోకి వచ్చిన ప్రతిసారి InstructionsLoaded hook event అమలవుతుంది. Load ఎందుకు జరిగిందో దాని 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 తన payload ను standard input పై JSONగా స్వీకరిస్తుంది. అందువల్ల cat మొత్తం record ను append చేస్తుంది. మీరు పని చేస్తున్నప్పుడు tail -f /tmp/instructions-loaded.log తో దాన్ని monitor చేయండి. ఈ event యొక్క exit status విస్మరించబడుతుంది. కాబట్టి hook కేవలం గమనించగలదు; నిరోధించలదు. Nested file లోడ్ అవుతుందని మీరు ఆశించిన సెషన్‌లో అది ఆ log లో కనిపించకపోతే, వాక్యాలను తిరిగి రాయడం ఆపండి. సమస్య file placement లో ఉంది.

దీర్ఘమైన session మీ rules పై చూపే ప్రభావం

ఇక్కడ రెండు వేర్వేరు ప్రభావాలు ఉంటాయి. వాటికి వేర్వేరు స్పందనలు అవసరం.

దూరం. turn 1లో పేర్కొన్న rule, turn 90లో కూడా windowలో ఉంటుంది. అయితే అప్పటికి అది మీ ప్రస్తుత పనికి మరింత సమీపంగా, మరింత నిర్దిష్టంగా ఉన్న 90 turns తాజా textతో పోటీ పడుతుంది. దీన్ని configuration ద్వారా తొలగించలేరు. కానీ దీన్ని కొలవచ్చు. అదే taskను కొత్త sessionలో అమలు చేయండి. అక్కడ rule పనిచేసి, దీర్ఘమైన sessionలో కొంతసేపటి తర్వాత విఫలమైతే, కారణం దూరమే.

Compaction. window నిండినప్పుడు harness ఇప్పటివరకు ఉన్న conversationను summaryగా సంక్షిప్తం చేసి, ఆ summary నుంచి కొనసాగుతుంది. ఏది మిగులుతుందో summariser ముఖ్యమని భావించినదానిపై ఆధారపడి ఉంటుంది. అది మీరు ముఖ్యమని భావించేదానితో తప్పనిసరిగా సమానం కాదు. Claude Code ప్రతి mechanismకు సంబంధించిన ఫలితాన్ని document చేస్తుంది. వాటి మధ్య తేడాలు గణనీయంగా ఉంటాయి. Project root CLAUDE.md మరియు unscoped rules compaction తర్వాత disk నుంచి మళ్లీ inject అవుతాయి. Auto memory disk నుంచి మళ్లీ inject అవుతుంది. paths: frontmatter ఉన్న rules, matching fileను మళ్లీ చదివే వరకు కోల్పోతారు. Subdirectoriesలోని nested CLAUDE.md files, ఆ subdirectoryలోని fileను మళ్లీ చదివే వరకు కోల్పోతారు.

ఆ పట్టిక ఆధారంగా మీ instructionsకు ప్రాధాన్యత క్రమం నిర్ణయిస్తే, fragility order స్పష్టమవుతుంది. మీరు chatలో మాత్రమే టైప్ చేసిన rule sessionలో అత్యంత fragile అంశం. Summary దాన్ని ఉంచినప్పుడే అది కొనసాగుతుంది. packages/api/CLAUDE.md లోని rule తరువాతి స్థాయిలో ఉంటుంది. అది ఒకసారి load అయి, summaryలో తొలగిపోయి, ఆ directoryలో తదుపరి read జరిగినప్పుడు మాత్రమే తిరిగి వస్తుంది. Project root fileలోని rule అత్యంత durableగా ఉంటుంది. ఎందుకంటే అది ప్రతి సారి disk నుంచి మళ్లీ read అవుతుంది.

కాబట్టి ఒక instruction మొత్తం sessionలో తప్పనిసరిగా అమలులో ఉండాలంటే, అది paths: frontmatter లేకుండా project root fileలో ఉండాలి. మిగిలిన వాటి విషయంలో మీరు tradeoffను ఉద్దేశపూర్వకంగా ఎంచుకోవాలి. context windowలో ఏది కొనసాగాలో నిర్వహించడంలో focus argumentతో /compact, సంబంధం లేని tasks మధ్య /clear గురించి వివరిస్తుంది. ఇవి summariserకు మీ rules ఏమిటో నిర్ణయించే అవకాశం ఎంత తరచుగా వస్తుందో మార్చుతాయి.

చుట్టూ ఉన్న కోడ్ నియమాన్ని మించినప్పుడు

ప్రజలు ఎక్కువగా వివరించే, కానీ అతి తక్కువగా నిర్ధారించే వైఫల్యం ఇదే. మీ ఫైల్ ప్రకారం database access repository layer ద్వారా జరగాలి. కానీ agent ORM (object relational mapper) ను నేరుగా పిలిచే handler ను రాస్తుంది. ఇది style కారణంగా మీ సూచనను విస్మరించడం కాదు. అందుబాటులో ఉన్న ఆధారాల ఆధారంగా agent వేరే నమూనాను ఎంచుకుంది.

ఒక rule ఒక అభిరుచిని వివరిస్తుంది. కోడ్ ఒక ఉదాహరణను చూపిస్తుంది. agent తాను సవరించబోయే module లోని మూడు ఫైళ్లను తెరిచినప్పుడు, మూడింటిలోనూ ORM ను నేరుగా పిలుస్తూ ఉంటే, context లో ఒక వైపు ఒక abstract వాక్యం ఉంటుంది; మరో వైపు ఇటీవలి, అదే పనికి సరిపోయే మూడు concrete ఉదాహరణలు ఉంటాయి. స్థానిక నమూనాను అనుసరించడం సాధారణంగా సరైన ప్రవర్తనే. ఇక్కడ అది తప్పు కావడానికి కారణం context కు తెలియని ఒక విషయం మీకు తెలుసు: ఆ ఫైళ్లు legacy code.

కాబట్టి ఆ విషయాన్ని rule లోనే రాయండి. తమకు విరుద్ధమైన ఆధారాలను స్వయంగా పేర్కొనే rules వాస్తవ repository లో ఉపయోగించినప్పుడు కూడా నిలబడతాయి. కేవలం ఒక అభిరుచిని పేర్కొనే rules నిలబడవు.

New database access goes through app/repositories/. Files under app/legacy/ still call the ORM directly. That is old code, not the pattern. Do not copy it.

రెండవ వాక్యమే ప్రధాన పని చేస్తుంది. agent ఆ కోడ్‌ను కనుగొనే ముందే, తాను ఏమి చూడబోతోందో మరియు దాన్ని ఎలా అర్థం చేసుకోవాలో అది చెబుతుంది. repository స్పష్టంగా విరుద్ధంగా చూపించే ఏ rule కైనా ఇదే సవరణ వర్తిస్తుంది: మీ history అనుసరించని commit style, మీ test suite లో సగం పట్టించుకోని test layout, కొత్త code లో మాత్రమే అమలయ్యే import convention. కోడ్ file కు విరుద్ధంగా ఉన్న ప్రతి చోట, ఆ విభేదాన్ని file లోనే పేర్కొనండి.

అస్పష్టమైన నియమాన్ని తనిఖీ చేయలేం, కాబట్టి దాన్ని అనుసరించలేం

"శుభ్రమైన code రాయండి." "అవసరానికి మించి engineering చేయకండి." "దీన్ని సరళంగా ఉంచండి." "Migrations విషయంలో జాగ్రత్తగా ఉండండి." వీటిలో ఏదీ agent లేదా మీరు ఒక నిర్దిష్ట చర్యతో సరిపోల్చి పరీక్షించలేరు. తన output తో సరిపోల్చి తనిఖీ చేయలేని నియమాన్ని అందుకున్న agent ఊహించాల్సి వస్తుంది. ఆ ఊహను మీరు కూడా స్పష్టమైన ప్రమాణం లేకుండా అంచనా వేస్తారు.

మీ file లోని ప్రతి line కు ఈ పరీక్షను వర్తింపజేయండి. నియమం ఉల్లంఘించినప్పుడు non-zero తో exit అయ్యే shell command ను రాయండి. ఆ command ను రాయలేకపోతే, ఆ నియమాన్ని తనిఖీ చేయలేం. ఈ జంటలను పోల్చండి:

• తనిఖీ చేయలేనిది: "Functions ను చిన్నగా ఉంచండి." తనిఖీ చేయగలిగేది: "Function 60 lines కంటే ఎక్కువ ఉంటే, దానికి కారణాన్ని వివరించే comment ను దాని పైన ఉంచాలి."
• తనిఖీ చేయలేనిది: "మీ changes ను test చేయండి." తనిఖీ చేయగలిగేది: "npm test ను run చేసి, task పూర్తయిందని చెప్పే ముందు failure count ను paste చేయాలి."
• తనిఖీ చేయలేనిది: "Files ను క్రమబద్ధంగా ఉంచండి." తనిఖీ చేయగలిగేది: "HTTP handlers src/api/handlers/ లో ఉండాలి. ఆ directory లో మరే ఇతరవి ఉండకూడదు."
• తనిఖీ చేయలేనిది: "Code ను సరిగ్గా format చేయండి." తనిఖీ చేయగలిగేది: ".ts files లో 2 space indentation ఉపయోగించాలి."

Size కూడా వేరే రూపంలో కనిపించే ఇదే సమస్య. Claude Code guidance ప్రతి instruction file ను 200 lines కంటే తక్కువగా ఉంచాలని సూచిస్తుంది. Files పొడవుగా ఉంటే adherence తగ్గుతుందని అది స్పష్టంగా చెబుతుంది. 700 lines ఉన్న file మరింత బలమైన instruction కాదు. పరస్పరం విరుద్ధంగా ఉండే అవకాశాలు ఎక్కువగా ఉన్న 700 claims మాత్రమే అందులో ఉంటాయి. ప్రతి turn లో ఆ file మీ window లోకి చేర్చబడుతుంది, కాబట్టి అది మీ token usage లో నేరుగా కనిపిస్తుంది. ప్రతి rule ను reader సులభంగా scan చేయగల heading కింద ఉంచే విధంగా file ను నిర్మించడం గురించి agent అమలు చేయగల instruction file రాయడం లో వివరించబడింది.

దీన్ని పది నిమిషాల్లో ఎలా నిర్ధారించాలి

ఈ ఆదేశాలను క్రమంలో అమలు చేయండి. చివరి దశకు నేరుగా వెళ్లడం వల్ల, బలంగా రాసిన నియమాలతో నిండిన పొడవైన file తయారవుతుంది. అయినా అది పనిచేయదు.

1. అది load అయిందో నిర్ధారించండి. /context అమలు చేసి Memory files జాబితాను చదవండి. ఆ file అక్కడ లేకపోతే, దాని location ను సరిచేసి ఆపండి. ఈ జాబితాలోని ఇతర దశలు అప్పటివరకు వర్తించవు.
2. కొత్త session లో మళ్లీ పరీక్షించండి. కొత్త session ప్రారంభించి, ఆ rule ను అమలు చేయాల్సిన అతి చిన్న task ను ఇవ్వండి. కొత్త session లో rule పనిచేసి, దీర్ఘమైన session లో విఫలమైతే, context distance లేదా compaction కారణం కావచ్చు. కొత్త session లో కూడా విఫలమైతే, సమస్య rule లోనే ఉంది.
3. పోటీ సూచనలను తొలగించండి. ఇప్పటికే ఉన్న code ఆ rule ను అనుసరిస్తున్న directory లో అదే మార్పు చేయమని అడగండి. అప్పుడు compliance తిరిగి వస్తే, చుట్టుపక్కల code మీ వాక్యాన్ని మించి ప్రభావం చూపుతోంది.
4. విరుద్ధత కోసం శోధించండి. ఒకే behaviour గురించి రెండు files వేర్వేరు guidance ఇస్తే, అది documented failure. Model ఒకదాన్ని యాదృచ్ఛికంగా ఎంచుకోవచ్చు. అలా ఎంచుకున్నట్లు అది మీకు చెప్పదు.
5. దాన్ని తనిఖీ చేయగలిగేలా మార్చి మళ్లీ పరీక్షించండి. నిర్దిష్ట path మరియు condition తో rule ను తిరిగి రాయండి. Compliance గణనీయంగా పెరిగితే, కారణం phrasing లోనే ఉంది.

Step 4 కోసం ఒకే command సరిపోతుంది. మీరు సవరించిన file మాత్రమే కాకుండా, topic కు సంబంధించిన ప్రతి instruction source లో Grep ఉపయోగించి శోధించండి:

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

వేర్వేరు విషయాలు చెప్పే రెండు files లో hit రావడం మీ bug. ఒకదాన్ని తొలగించండి. బలమైన wording ఉపయోగించి వాటికి priority నిర్ణయించడానికి ప్రయత్నించవద్దు, ఎందుకంటే దానికి ఉపయోగించగల ranking engine లేదు.

అమలు ప్రభావం క్రమంలో పరిష్కారాలు

క్రింద ఉన్న ప్రతి దశ దాని పైన ఉన్న దశకన్నా ఎక్కువ ప్రభావాన్ని కలిగి ఉంటుంది. అయితే దాన్ని అమలు చేయడానికి ఎక్కువ setup అవసరం. ఒక నియమాన్ని మార్చి రాయడం సులభంగా ఉన్నప్పుడు పై దశ నుంచే ప్రారంభించండి. అప్పుడప్పుడు తప్పిపోవడం ఆమోదయోగ్యం కానంత ముఖ్యమైనదిగా నియమం మారిన వెంటనే దిగువ దశకు వెళ్లండి.

1. నియమాన్ని స్పష్టంగా చేయండి. ఒక path, command లేదా condition ను పేర్కొనండి. ఇంతకుముందు చూపినట్లుగా, agent repository లో కనుగొనే వ్యతిరేక ఆధారాన్ని కూడా జోడించండి. దీనికి అదనపు ఖర్చు లేదు. ఇది ఊహించిన దానికంటే ఎక్కువ సందర్భాలను పరిష్కరిస్తుంది.
2. నియమం వర్తించే అంశానికి దాన్ని దగ్గరగా ఉంచండి. Nested CLAUDE.md, .claude/rules/ లో path-scoped rule లేదా file ప్రారంభంలోనే comment ఉపయోగించండి. అప్పుడు నియమం, అది వర్తించే code చదివే సమయంలోనే అందుబాటులోకి వస్తుంది. అయితే ఈ పరిమితిని అంగీకరించండి: ఆ విధంగా load చేసినది తదుపరి compaction సమయంలో తొలగిపోతుంది. తరువాత సరిపోలే read సమయంలో మళ్లీ వస్తుంది.
3. Enforcement ను hook లోకి మార్చండి. Prose కేవలం అభ్యర్థిస్తుంది. Hook నిర్ణయం తీసుకుంటుంది. Hooks నిర్దిష్ట lifecycle events సమయంలో codeగా నడుస్తాయి. Model ఏ నిర్ణయానికి వచ్చినా అవి వర్తిస్తాయి.
4. నియమాన్ని deterministic tool కు అప్పగించి, prose ను తొలగించండి. Formatting, import order, line length, నిషేధిత imports, commit message రూపం వంటి వాటికి ఇది వర్తిస్తుంది. ruff format, prettier --write, eslint లేదా pre-commit hook ఉపయోగించండి. Formatter ప్రతిసారీ సరైన ఫలితాన్ని ఇస్తుంది. దీనికి tokens అవసరం ఉండదు. వాక్యం ఎక్కువసార్లు సరైనదే అయినా, ప్రతి turn లో tokens ఖర్చవుతాయి.

దశ 3ను పూర్తిగా చూద్దాం. Migration files ను agent ఎప్పటికీ edit చేయకూడదని అనుకుందాం. దీన్ని .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 ను run చేసి, కొత్త session ప్రారంభించండి. తరువాత migrations/ కింద ఉన్న file ను edit చేయమని agent ను అడగండి. Edit తిరస్కరించబడుతుంది. కారణం మీ message గా తిరిగి వస్తుంది. PreToolUse లో exit status 2 వస్తే, tool call run కాకముందే block అవుతుంది. మీ stderr text blocking message గా model కు అందుతుంది. ${CLAUDE_PROJECT_DIR} project root కు resolve అవుతుంది. అందువల్ల agent ఏ directory లో ఉన్నా hook పనిచేస్తుంది. Agent ఈ నియమంతో ఏకీభవించాల్సిన అవసరం లేదు. నియమాన్ని గుర్తుంచుకోవాల్సిన అవసరం లేదు. ఆ నియమం ఇంకా context లో ఉండాల్సిన అవసరం కూడా లేదు. Edit జరగదు.

ఎలాంటి logic లేని సాధారణ prohibition కోసం, మీ settings లోని permissions.deny అదే పని చేస్తుంది. అయితే maintain చేయాల్సిన script ఉండదు. ముందుగా మీ అనుమతి అడగకుండా ఏవి run అవుతాయో permission modes నిర్ణయిస్తాయి. ఒక instruction నిజంగా user message లో కాకుండా system prompt స్థాయిలో ఉండాల్సి వస్తే, --append-system-prompt దాన్ని అక్కడ ఉంచుతుంది. అయితే ప్రతి invocation సమయంలో దాన్ని pass చేయాలి. అందువల్ల ఇది interactive work కంటే scripts కు ఎక్కువగా అనుకూలంగా ఉంటుంది.

మీరు ఆదేశాలతో మార్చలేని విషయాలు

ఇందులో ఏ భాగం మీ పరిధిలో ఉందో స్పష్టంగా గుర్తించండి. Placement, phrasing, files మధ్య conflicts, file size వంటి విషయాలు author సమస్యలు; వాటికి author స్థాయిలోనే పరిష్కారాలు ఉంటాయి. మిగిలినవి model behaviour కు సంబంధించినవి. మెరుగైన wording వాటిని తొలగించదు.

Agreement అంటే compliance కాదు. ఒక agent నియమాన్ని అంగీకరించినట్లు చెప్పవచ్చు, దాన్ని మీకు సరిగ్గా తిరిగి వివరించవచ్చు, కానీ రెండు tool calls తర్వాత అదే నియమాన్ని ఉల్లంఘించవచ్చు. ఆ acknowledgement కు ఎలాంటి ఖర్చు ఉండదు, దాని ఆధారంగా భవిష్యత్తు ప్రవర్తనను అంచనా వేయలేరు. దాన్ని పరిష్కారంగా పరిగణించవద్దు. దాన్ని test గా కూడా లెక్కించవద్దు.

కొన్ని అలవాట్లు నిరంతరం తిరిగి వస్తాయి. Comments జోడించడం, defensive error handling జోడించడం, చివర్లో summary రాయడం, వెంటనే చేయాల్సిన obvious next command ను run చేయడం వంటివి ఇందులో ఉన్నాయి. వీటిని నిషేధించే నియమం ఉన్నా ఇవి పూర్తిగా ఆగవు; తక్కువ తరచుదనంతో తిరిగి కనిపిస్తాయి. మీ స్వంత rate ను కొలవవచ్చు: fresh sessions లో అదే task ను పది సార్లు run చేసి violations ను లెక్కించండి. ఆ సంఖ్య zero కావాల్సిన చోట, ఆ నియమాన్ని prompt నుంచి తొలగించాలి.

మీ session స్వయంగా ఒక example అవుతుంది. agent turn 12 వద్ద నియమాన్ని ఉల్లంఘించి, మీరు దాన్ని అలాగే వదిలేస్తే, ఆ violation context లో demonstration గా నిలుస్తుంది. అది rule కంటే చాలా recent గా ఉంటుంది. violation కనిపించిన వెంటనే దాన్ని సరిచేయండి. సరిచేయని violation session లోని మిగిలిన భాగానికి ఒక పాఠంగా మారుతుంది.

Instruction file ఒక security boundary కాదు. అది behaviour ను ప్రభావితం చేస్తుంది; అమలు చేయదు. Credentialలు లేదా destructive commands వంటి వాటిలో పొరపాటు ఖరీదైనదైతే, వాటిని permissions లేదా hook లో నియంత్రించాలి. agent కు secrets అందకుండా ఉంచడం అనే విధానం data కు కూడా వర్తిస్తుంది: ఒక file చదవవద్దని agent ను అడగకండి. ఆ file చదవలేని విధంగా వ్యవస్థను అమర్చండి.

సంక్షిప్తంగా: file load అయిందని నిర్ధారించండి, rule ను check చేయగలిగే విధంగా రాయండి, అది నియంత్రించే విషయానికి సమీపంలో ఉంచండి. miss rate ఇంకా ముఖ్యంగా ఉంటే, దాన్ని prose నుంచి తొలగించండి. agent విస్మరించలేని rule ను agent కు అడిగిన rule గా పరిగణించలేం.

FAQ

Claude Code నా CLAUDE.md ను ఎందుకు పట్టించుకోదు?

అది పట్టించుకోలేదని భావించే ముందు, ఆ ఫైల్ లోడ్ అయిందో లేదో తనిఖీ చేయండి. /context ను అమలు చేసి Memory files జాబితాను చూడండి; అక్కడ పేరు లేని ఫైల్ conversation లో భాగం కాదు. Instruction files ను system prompt తర్వాత user message గా అందిస్తారు. అవి enforced configuration గా కాకుండా context గా పరిగణించబడతాయి. అందువల్ల అవి ఖచ్చితంగా పాటించబడతాయనే హామీ లేదు. వాస్తవ సందర్భాల్లో సాధారణంగా నాలుగు కారణాల్లో ఒకటి ఉంటుంది: agent ఎప్పుడూ చదవని subdirectory లో ఫైల్ ఉండటం, రెండు ఫైళ్లు పరస్పరం విరుద్ధంగా ఉండటంతో model ఒకదాన్ని యాదృచ్ఛికంగా ఎంచుకోవడం, ఏ చర్యతో పోల్చి తనిఖీ చేయాలో rule స్పష్టంగా లేకపోవడం, లేదా చుట్టుపక్కల code ఆ rule కు విరుద్ధమైన ప్రవర్తనను చూపించడం.

Session మధ్యలో instruction file ను సవరించితే ఏమైనా మారుతుందా?

ఇప్పటికే conversation లో ఉన్న copy కి మార్పు ఉండదు. మీ working directory పైన ఉన్న ఫైళ్లు launch సమయంలో పూర్తిగా లోడ్ అవుతాయి. అందువల్ల model వద్ద ఉన్న text launch సమయానికి ఉన్నదే. సవరణను ఉపయోగించాలంటే కొత్త session ప్రారంభించండి. లేదా agent తన సాధారణ file tools తో ఆ ఫైల్‌ను చదవమని అడగండి. అప్పుడు ప్రస్తుత version కొత్త message గా conversation లోకి వస్తుంది. Compaction తర్వాత project root file disk నుంచి మళ్లీ చదవబడుతుంది. కాబట్టి ఆ సమయంలో కొత్త version కూడా వస్తుంది.

Root CLAUDE.md మరియు nested CLAUDE.md పరస్పరం విభేదిస్తే ఏ ఫైల్‌కు ప్రాధాన్యం ఉంటుంది?

నమ్మదగిన విధంగా ఏదీ కాదు. కనుగొనబడిన ఫైళ్లు ఒకదానిని మరొకటి override చేయకుండా context లో కలిపి చేర్చబడతాయి. అవి filesystem root నుంచి working directory వరకు క్రమంలో ఉంటాయి. అందువల్ల దగ్గరలోని ఫైల్ కేవలం చివరగా చదవబడుతుంది. విరుద్ధాలను పరిష్కరించే precedence engine లేదు. Claude Code documentation ప్రకారం, విరుద్ధమైన rules యాదృచ్ఛికంగా పరిష్కరించబడవచ్చు. Nested files ను అవి నియంత్రించే path ను పేర్కొనే additions గా రాయండి. మరొక rule పై ప్రాధాన్యం సాధించడానికి ప్రయత్నించకుండా, విరుద్ధమైన rule ను తొలగించండి.

నా instructions /compact తర్వాత కూడా ఉంటాయా?

అవి ఎలా లోడ్ అయ్యాయన్నదిపై ఆధారపడి ఉంటుంది. Project root CLAUDE.md, unscoped rules మరియు auto memory compaction తర్వాత disk నుంచి మళ్లీ inject చేయబడతాయి. paths: frontmatter ఉన్న rules మరియు subdirectories లోని nested CLAUDE.md files, సరిపోలే file మళ్లీ చదివే వరకు కోల్పోతారు. మీరు chat లో మాత్రమే టైప్ చేసిన విషయం summariser దాన్ని ఉంచి ఉంటేనే మిగులుతుంది. మొత్తం session అంతటా ఒక rule తప్పనిసరిగా ఉండాలంటే, దాన్ని paths: frontmatter లేకుండా project root file లో ఉంచండి.

Prose కు బదులుగా rule ను hook గా ఎప్పుడు మార్చాలి?

తనిఖీ deterministic గా ఉన్నప్పుడు, miss అయ్యే ఖర్చు చిన్న script రాసే ఖర్చుకంటే ఎక్కువగా ఉన్నప్పుడు మార్చాలి. File path restrictions, commit కు ముందు తప్పనిసరిగా అమలు చేయాల్సిన commands, మరియు నిషేధిత tool calls ఈ వర్గంలోకి వస్తాయి. status 2 తో ముగిసే PreToolUse hook tool call ను నేరుగా నిరోధిస్తుంది. అలాగే మీ stderr text ను కారణంగా model కు తిరిగి అందిస్తుంది. అందువల్ల ఆ rule context లో ఇంకా ఉన్నా లేకపోయినా అది అమలవుతుంది. Formatter లేదా linter నిర్ణయించగల ఏ విషయాన్నైనా ఆ tool కే అప్పగించి, instruction file నుంచి పూర్తిగా తొలగించండి.