কোডিং এজেন্ট কেন আপনার নির্দেশ উপেক্ষা করে?

কেন কোডিং এজেন্ট আপনার নির্দেশ উপেক্ষা করে

কোডিং এজেন্ট আপনার নির্দেশ উপেক্ষা করার চারটি কারণ রয়েছে, এবং এর কোনোটিই এই নয় যে আপনি খুব বেশি বিনয়ী ছিলেন। নিয়মটি কখনোই কনটেক্সট উইন্ডোতে ছিল না। নিয়মটি এতই অস্পষ্ট ছিল যে কোনো কাজের সাথে তা মিলিয়ে দেখা সম্ভব ছিল না। কনটেক্সটের অন্য কিছু এর বিপরীত ছিল, সাধারণত এজেন্ট এইমাত্র যে কোডটি পড়েছে সেটি। অথবা নিয়মটি এখনো লোড করা আছে কিন্তু বর্তমান টার্ন থেকে অনেক পেছনে পড়ে আছে, এবং এজেন্ট তার কাছাকাছি থাকা তথ্যগুলো নিয়ে কাজ করছে।

প্রতিটি কারণের নিজস্ব সমাধান আছে, তাই প্রথম কাজ হলো সেগুলোকে আলাদা করা। বড় হাতের অক্ষর এবং IMPORTANT শব্দটি কোনো রোগ নির্ণয় নয়। নিচের মেকানিজমগুলোতে Claude Code-কে উদাহরণ হিসেবে ব্যবহার করা হয়েছে, কারণ 2026 সালের আগস্ট মাস পর্যন্ত এর লোডিং এবং কমপ্যাকশন আচরণ বিস্তারিতভাবে নথিভুক্ত করা আছে। অন্যান্য টুলের ক্ষেত্রে বিস্তারিত তথ্যে পার্থক্য থাকলেও মূল কাঠামো একই।

প্রথমে দুটি পরিভাষা জেনে নেওয়া যাক। context window হলো সেই টেক্সট ব্লক যা একটি নির্দিষ্ট টার্নে মডেলটি দেখতে পায়: সিস্টেম প্রম্পট, আপনার নির্দেশনার ফাইলগুলো, কথোপকথন এবং এজেন্ট যে ফাইলগুলো পড়েছে তার প্রতিটি। harness হলো মডেলের চারপাশের প্রোগ্রাম, যা ডিস্ক থেকে ফাইল পড়ে এবং সেই ব্লকটি তৈরি করে। এই পোস্টে প্রায় প্রতিটি অভিযোগই আসলে মডেলের বিরুদ্ধে নয়, বরং হারনেসের বিরুদ্ধে।

আপনার ইনস্ট্রাকশন ফাইলটি কোনো সেটিং নয়, বরং একটি বার্তা

একটি ইনস্ট্রাকশন ফাইল কনফিগারেশন নয়। রানটাইমে কোনো কিছুই CLAUDE.md পড়ে না এবং এটি কার্যকর করে না। হারনেস ডিস্ক থেকে ফাইলটি পড়ে এবং টেক্সটটিকে কথোপকথনে পেস্ট করে। Claude Code-এ এই বিষয়বস্তু সিস্টেম প্রম্পটের পরে একটি ব্যবহারকারী বার্তা হিসেবে প্রদান করা হয়, যার অর্থ হলো মডেলটি আপনার নিয়মগুলোকে ঠিক সেভাবেই দেখে যেভাবে আপনি টাইপ করা অন্য কিছু দেখে।

এর একটি অস্বস্তিকর ফলাফল রয়েছে। আপনার নিয়মগুলো উইন্ডোতে থাকা অন্য সব টেক্সটের সাথে সমানভাবে প্রতিযোগিতা করে। একটি নিয়ম হলো একটি দাবি। এজেন্ট এইমাত্র যে ফাইলটি খুলেছে তা হলো প্রমাণ। যখন এই দুটির মধ্যে অমিল থাকে, তখন প্রায়শই প্রমাণটি জয়ী হয় এবং কোনো এরর তৈরি হয় না, কারণ মডেলের দৃষ্টিভঙ্গি থেকে কোনো ভুল হয়নি।

অফিসিয়াল ডকুমেন্টেশনে এটি স্পষ্টভাবে বলা হয়েছে: ইনস্ট্রাকশন ফাইলগুলোকে কনটেক্সট হিসেবে বিবেচনা করা হয়, কার্যকর করা কনফিগারেশন হিসেবে নয়। মডেল যা-ই সিদ্ধান্ত নিক না কেন, কোনো কাজকে ব্লক করতে হলে আপনার একটি হুক প্রয়োজন, কোনো বাক্য নয়। এই বিষয়টি মনে রাখুন। এই পোস্টের শেষে দেওয়া বেশিরভাগ সমাধানই হলো কোনো নির্দিষ্ট ক্ষেত্রে এই লাইনের প্রয়োগ।

কোন instruction ফাইলগুলো লোড হয় এবং কখন

Claude Code যে ডিরেক্টরি থেকে আপনি শুরু করেছেন, সেখান থেকে ডিরেক্টরি ট্রি ধরে উপরের দিকে যেতে থাকে। ফাইলসিস্টেমের রুট থেকে আপনার বর্তমান ওয়ার্কিং ডিরেক্টরি পর্যন্ত প্রতিটি CLAUDE.md এবং CLAUDE.local.md লঞ্চের সময় পুরোপুরি লোড হয়। এগুলো সেই ক্রমেই সংযুক্ত (concatenate) হয়, তাই আপনি যেখান থেকে লঞ্চ করেছেন তার সবচেয়ে কাছের ফাইলটি সবার শেষে পড়া হয় এবং একটি ডিরেক্টরির ভেতরে .local ফাইলটি মূল ফাইলের পরে যুক্ত হয়।

আপনার ওয়ার্কিং ডিরেক্টরির নিচের সাব-ডিরেক্টরিগুলোতে থাকা ফাইলগুলো ভিন্নভাবে কাজ করে। এগুলো লঞ্চের সময় লোড হয় না। যখন এজেন্ট সেই ডিরেক্টরির কোনো ফাইল পড়ে, তখন এগুলো লোড হয়। .claude/rules/-এ থাকা পাথ-স্কোপড রুলগুলোর ক্ষেত্রেও একই কথা প্রযোজ্য, যেগুলোতে paths: ফ্রন্টম্যাটার ফিল্ড থাকে: এগুলো প্রতিবার নয়, বরং একটি ম্যাচিং ফাইল পড়ার সময় কনটেক্সটে যুক্ত হয়।

এই একটি পার্থক্যই রিপোর্ট করা ব্যর্থতার বড় একটি অংশের কারণ। আপনি packages/api/CLAUDE.md-এ একটি রুল রাখলেন, API সম্পর্কে একটি প্রশ্ন করলেন, আর এজেন্ট packages/api/-এর নিচের কোনো ফাইল না খুলেই উত্তর দিয়ে দিল। রুলটি উপেক্ষা করা হয়নি; এটি কখনোই সেখানে উপস্থিত ছিল না। যদি আপনার রিপোজিটরি per package instruction files in a monorepo-এর মাধ্যমে নির্দেশনা ভাগ করে রাখে, তবে প্রতিবার এটিই সবার আগে চেক করা উচিত।

লোডিংয়ের আরও একটি ফাঁদ আছে, এবং এটি "এজেন্ট আমার নির্দেশনা উপেক্ষা করেছে" জাতীয় সমস্যার সবচেয়ে সাধারণ সংস্করণ: Claude Code CLAUDE.md পড়ে, AGENTS.md নয়। যে রিপোজিটরি AGENTS.md-এর ওপর ভিত্তি করে তৈরি এবং যেখানে কোনো CLAUDE.md নেই, সেখানে Claude Code লোড করার মতো কিছুই পায় না। সমর্থিত ব্রিজটি হলো একটি CLAUDE.md, যার প্রথম লাইনটি হলো @AGENTS.md; এটি লঞ্চের সময় ফাইলটিকে ইমপোর্ট করে এবং এর নিচে Claude-এর জন্য প্রয়োজনীয় নোটগুলো থাকে। আপনার যদি বাড়তি কিছু যোগ করার না থাকে, তবে একটি symlink-ও কাজ করবে। সেই ফাইলে কী থাকা উচিত তা একটি আলাদা বিষয়, যা splitting agent instructions from human documentation-এ আলোচনা করা হয়েছে।

ফাইলটি নতুন করে লেখার আগে নিশ্চিত হোন যে সেটি লোড হয়েছে

ফাইলটি এজেন্ট দেখতে পাচ্ছে কি না তা নিশ্চিত না হওয়া পর্যন্ত এর বিষয়বস্তু পরিবর্তন করবেন না। এখানে দুটি যাচাইকরণ পদ্ধতি আছে, যার মধ্যে সহজটি আগে প্রয়োগ করতে হয়।

সেশনের ভেতর /context চালান। এটি বর্তমান উইন্ডোর বিষয়বস্তুকে বিভিন্ন ক্যাটাগরিতে ভাগ করে দেখায় এবং Memory files তালিকায় প্রতিটি লোড হওয়া ইন্সট্রাকশন ফাইলের নাম থাকে। এই তালিকায় কোনো ফাইল না থাকলে সেটি কনভারসেশনের অংশ নয়, তাই সেই ফাইলের ভেতর আপনি যা-ই লিখুন না কেন, তার কোনো প্রভাব পড়বে না। /memory ফাইলের অবস্থানগুলো তালিকাভুক্ত করে এবং সেগুলোকে এডিটিংয়ের জন্য খুলে দেয়, এমনকি যে ফাইলগুলো এখনো তৈরি হয়নি সেগুলোও।

আরও নিশ্চিত হওয়ার জন্য, লোডগুলো লগ করুন। InstructionsLoaded হুক ইভেন্টটি প্রতিবার কার্যকর হয় যখন কোনো CLAUDE.md বা রুলস ফাইল কনটেক্সটে প্রবেশ করে এবং এর ম্যাচার আপনাকে জানায় কেন লোডটি ঘটেছে: 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"
          }
        ]
      }
    ]
  }
}

হুকটি তার পেলোড স্ট্যান্ডার্ড ইনপুটে JSON হিসেবে গ্রহণ করে, তাই cat পুরো রেকর্ডটি যুক্ত করে। কাজ করার সময় tail -f /tmp/instructions-loaded.log দিয়ে এটি পর্যবেক্ষণ করুন। এই ইভেন্টের এক্সিট স্ট্যাটাস উপেক্ষা করা হয়, তাই হুকটি কেবল পর্যবেক্ষণ করতে পারে, কোনো কিছু ব্লক করতে পারে না। যদি আপনার নেস্টেড ফাইলটি এমন কোনো সেশনে লগে না আসে যেখানে আপনি সেটি আশা করেছিলেন, তবে নতুন করে লেখা বন্ধ করুন। সমস্যাটি ফাইলের অবস্থানে।

দীর্ঘ সেশনের ফলে আপনার নিয়মগুলোর ওপর যে প্রভাব পড়ে

এখানে দুটি ভিন্ন প্রভাব কাজ করে এবং এগুলোর জন্য ভিন্ন ভিন্ন পদক্ষেপ প্রয়োজন।

দূরত্ব (Distance)। 1 নম্বর টার্নে দেওয়া একটি নিয়ম 90 নম্বর টার্নেও উইন্ডোর ভেতরে থাকে, কিন্তু এখন এটি 90 টার্নের নতুন এবং আপনার বর্তমান কাজের সাথে অধিক প্রাসঙ্গিক টেক্সটের সাথে প্রতিযোগিতায় লিপ্ত হয়। আপনি কনফিগারেশনের মাধ্যমে এটি দূর করতে পারবেন না, তবে পরিমাপ করতে পারবেন। একটি নতুন সেশনে একই কাজ চালিয়ে দেখুন। যদি নিয়মটি সেখানে কার্যকর থাকে কিন্তু দীর্ঘ সেশনের অনেক গভীরে গিয়ে ব্যর্থ হয়, তবে বুঝতে হবে দূরত্বই এর কারণ।

কম্প্যাকশন (Compaction)। উইন্ডো পূর্ণ হয়ে গেলে, হারনেস এখন পর্যন্ত হওয়া কথোপকথনের একটি সারাংশ তৈরি করে এবং সেই সারাংশ থেকে কাজ চালিয়ে যায়। সারাংশ তৈরিকারী যা গুরুত্বপূর্ণ মনে করেছে কেবল সেটিই টিকে থাকে, যা আপনার কাছে গুরুত্বপূর্ণ বিষয়ের সাথে সবসময় মেলে না। Claude Code প্রতিটি মেকানিজম অনুযায়ী ফলাফল নথিবদ্ধ করে এবং এদের মধ্যে বড় ধরনের পার্থক্য থাকে। প্রজেক্ট রুট CLAUDE.md এবং আনস্কোপড (unscoped) নিয়মগুলো কম্প্যাকশনের পর ডিস্ক থেকে পুনরায় ইনজেক্ট করা হয়। অটো মেমোরি ডিস্ক থেকে পুনরায় ইনজেক্ট হয়। paths: ফ্রন্টম্যাটারযুক্ত নিয়মগুলো হারিয়ে যায়, যতক্ষণ না সংশ্লিষ্ট ফাইলটি পুনরায় পড়া হয়। সাব-ডিরেক্টরিতে থাকা নেস্টেড CLAUDE.md ফাইলগুলোও হারিয়ে যায়, যতক্ষণ না সেই সাব-ডিরেক্টরির কোনো ফাইল পুনরায় পড়া হয়।

আপনার নির্দেশাবলিকে এই টেবিল অনুযায়ী সাজান, তাহলেই বুঝতে পারবেন কোনটি কতটা ভঙ্গুর। চ্যাটে টাইপ করা নিয়মটি সেশনের সবচেয়ে ভঙ্গুর অংশ: এটি কেবল তখনই টিকে থাকে যদি সারাংশে সেটি থেকে যায়। packages/api/CLAUDE.md-এ থাকা নিয়মটি এর পরের অবস্থানে আছে, কারণ এটি একবার লোড হওয়ার পর সারাংশ থেকে বাদ পড়ে যেতে পারে এবং কেবল সেই ডিরেক্টরিতে পুনরায় ফাইল পড়ার সময় ফিরে আসে। প্রজেক্ট রুট ফাইলে থাকা নিয়মটি সবচেয়ে টেকসই, কারণ প্রতিবার এটি ডিস্ক থেকে পুনরায় পড়া হয়।

তাই যদি কোনো নির্দেশনা পুরো সেশন জুড়ে কার্যকর রাখতে হয়, তবে সেটি কোনো paths: ফ্রন্টম্যাটার ছাড়া প্রজেক্ট রুট ফাইলে রাখা উচিত। বাকি সবকিছুই একটি ট্রেড-অফ, যা আপনার সচেতনভাবে করা উচিত। কনটেক্সট উইন্ডোতে যা থাকে তা পরিচালনা করা অংশে /compact-কে ফোকাস আর্গুমেন্টসহ এবং /clear-কে সম্পর্কহীন কাজের মাঝে ব্যবহার করার বিষয়টি আলোচনা করা হয়েছে, যার উভয়ই সারাংশ তৈরিকারী আপনার নিয়মগুলো সম্পর্কে কী সিদ্ধান্ত নেবে তা পরিবর্তন করে দেয়।

কেন পারিপার্শ্বিক কোড নিয়মের চেয়ে বেশি কার্যকর

এটি এমন একটি ব্যর্থতা যা মানুষ সবচেয়ে বেশি বর্ণনা করে কিন্তু সবচেয়ে কম নির্ণয় করে। আপনার ফাইলে বলা আছে যে ডাটাবেস অ্যাক্সেস রিপোজিটরি লেয়ারের মাধ্যমে হতে হবে। কিন্তু এজেন্ট এমন একটি হ্যান্ডলার লেখে যা সরাসরি ORM (object relational mapper)-কে কল করে। আপনাকে স্টাইলের কারণে উপেক্ষা করা হয়নি। প্রমাণের ভিত্তিতে আপনার মতামতের চেয়ে কোডের বাস্তবতাকে প্রাধান্য দেওয়া হয়েছে।

একটি নিয়ম কেবল একটি পছন্দের বর্ণনা দেয়। আর কোড একটি বাস্তব উদাহরণ প্রদর্শন করে। যখন এজেন্ট যে মডিউলটি এডিট করতে যাচ্ছে তার তিনটি ফাইল খোলে এবং তিনটিই সরাসরি ORM-কে কল করে, তখন প্রেক্ষাপটে একদিকে একটি বিমূর্ত বাক্য থাকে এবং অন্যদিকে তিনটি সুনির্দিষ্ট, সাম্প্রতিক ও কাজের সাথে সামঞ্জস্যপূর্ণ উদাহরণ থাকে। স্থানীয় প্যাটার্ন অনুসরণ করা সাধারণত সঠিক আচরণ। এটি এখানে ভুল কারণ আপনি এমন কিছু জানেন যা প্রেক্ষাপটে নেই: ওই ফাইলগুলো লিগ্যাসি কোড।

তাই সেই তথ্যটি নিয়মের মধ্যে লিখে রাখুন। যে নিয়মগুলো তাদের নিজস্ব বিপরীত প্রমাণকে উল্লেখ করে, সেগুলো বাস্তব রিপোজিটরিতে টিকে থাকে। যে নিয়মগুলো কেবল একটি সাধারণ পছন্দ প্রকাশ করে, সেগুলো টিকে থাকে না।

নতুন ডাটাবেস অ্যাক্সেস অবশ্যই app/repositories/-এর মাধ্যমে হতে হবে। app/legacy/-এর অধীনে থাকা ফাইলগুলো এখনও সরাসরি ORM-কে কল করে। সেটি পুরনো কোড, বর্তমান প্যাটার্ন নয়। সেটি অনুসরণ করবেন না।

দ্বিতীয় বাক্যটিই মূল কাজ করে। এটি এজেন্টকে কিছু পাওয়ার আগেই জানিয়ে দেয় যে সে কী খুঁজে পাবে এবং কীভাবে তা পড়তে হবে। একই সমাধান আপনার রিপোজিটরির যেকোনো নিয়মের ক্ষেত্রে প্রযোজ্য যা কোডের সাথে সাংঘর্ষিক: যেমন এমন কোনো কমিট স্টাইল যা আপনার হিস্ট্রি অনুসরণ করে না, টেস্ট লেআউট যা আপনার টেস্ট সুইটের অর্ধেক অংশ মানে না, অথবা ইমপোর্ট কনভেনশন যা কেবল নতুন কোডেই বজায় থাকে। যেখানেই কোড ফাইলের নিয়মের সাথে দ্বিমত পোষণ করে, সেই দ্বিমতের কথা ফাইলে উল্লেখ করে দিন।

একটি অস্পষ্ট নিয়ম যাচাই করা যায় না, তাই তা অনুসরণ করাও সম্ভব নয়

"পরিচ্ছন্ন কোড লিখুন।" "অতিরিক্ত ইঞ্জিনিয়ারিং করবেন না।" "সহজ রাখুন।" "মাইগ্রেশনের সময় সতর্ক থাকুন।" এগুলোর কোনোটিই কোনো নির্দিষ্ট কাজের বিপরীতে পরীক্ষা করা সম্ভব নয়, এজেন্ট বা আপনার কারো পক্ষেই এটি করা সম্ভব নয়। কোনো এজেন্টকে এমন নিয়ম দিলে যা সে তার নিজের আউটপুটের বিপরীতে যাচাই করতে পারে না, তবে সে কেবল অনুমান করছে, আর আপনি সেই অনুমানকে আপনার অনুভূতির ভিত্তিতে মূল্যায়ন করছেন।

আপনার ফাইলের প্রতিটি লাইনের জন্য এই পরীক্ষাটি প্রয়োগ করুন। এমন একটি shell command লিখুন যা নিয়মটি ভাঙলে non-zero exit code প্রদান করবে। যদি আপনি সেই command লিখতে না পারেন, তবে নিয়মটি যাচাইযোগ্য নয়। নিচের জোড়াগুলো তুলনা করুন:

• যাচাইযোগ্য নয়: "ফাংশন ছোট রাখুন।" যাচাইযোগ্য: "60 লাইনের চেয়ে বড় ফাংশনের উপরে কেন তা বড়, তার ব্যাখ্যাসহ একটি comment থাকতে হবে।"
• যাচাইযোগ্য নয়: "আপনার পরিবর্তনগুলো পরীক্ষা করুন।" যাচাইযোগ্য: "npm test চালান এবং কোনো কাজ সম্পন্ন করার আগে failure count পেস্ট করুন।"
• যাচাইযোগ্য নয়: "ফাইলগুলো গুছিয়ে রাখুন।" যাচাইযোগ্য: "HTTP handler-গুলো src/api/handlers/-এ থাকবে। অন্য কোনো ফাইল ওই ডিরেক্টরিতে রাখা যাবে না।"
• যাচাইযোগ্য নয়: "কোড সঠিকভাবে ফরম্যাট করুন।" যাচাইযোগ্য: ".ts ফাইলগুলোতে 2 স্পেস indentation ব্যবহার করুন।"

"অতিরিক্ত ইঞ্জিনিয়ারিং করবেন না" এমন একটি নিয়ম যা মানুষ সবার আগে ছেড়ে দেয়, কারণ এর সমাধান ছোট কোনো বাক্য নয় বরং দীর্ঘ একটি ব্যাখ্যা: সবচেয়ে ছোট কার্যকর পরিবর্তন বলতে কী বোঝায় তা বিস্তারিত লেখা এজেন্টকে এমন মানদণ্ড দেয় যার বিপরীতে সে তার নিজের diff যাচাই করতে পারে।

ফাইলের আকারও একই সমস্যার ভিন্ন রূপ। Claude Code-এর নির্দেশিকা প্রতিটি instruction ফাইলের জন্য 200 লাইনের কম রাখার পরামর্শ দেয় এবং সরাসরি উল্লেখ করে যে বড় ফাইল নির্দেশ মানার হার কমিয়ে দেয়। 700 লাইনের একটি ফাইল মানেই শক্তিশালী নির্দেশনা নয়। এটি 700 লাইনের দাবি, যেখানে একে অপরের সাথে সাংঘর্ষিক হওয়ার সম্ভাবনা বেশি থাকে এবং এটি প্রতিবার আপনার window-তে চার্জ হিসেবে যুক্ত হয়, যা সরাসরি আপনার token ব্যবহারে ফুটে ওঠে। ফাইলটিকে এমনভাবে সাজানো যাতে প্রতিটি নিয়ম এমন শিরোনামের নিচে থাকে যা পাঠক দ্রুত স্ক্যান করতে পারে, তা এজেন্ট কাজ করতে পারে এমন একটি instruction ফাইল লেখা-তে আলোচনা করা হয়েছে। এর চেয়েও ভালো হয় যদি বর্ণনামূলক অংশগুলো বাদ দিয়ে নির্দেশনামূলক অংশ রাখা হয়: handler এবং model কোথায় থাকে তার একটি ডিরেক্টরি ট্যুর হলো এমন কাঠামো যা এজেন্ট repository-এর একটি parsed map থেকে প্রয়োজনে দেখে নিতে পারে, প্রতিবার window-তে বহন করার প্রয়োজন নেই।

দশ মিনিটে কীভাবে এটি নির্ণয় করবেন

এগুলো ক্রমানুসারে চালান। শেষ ধাপে সরাসরি চলে গেলে আপনি এমন একটি দীর্ঘ ফাইল তৈরি করবেন যেখানে অনেক নিয়ম থাকবে কিন্তু কোনোটিই কাজ করবে না।

1. এটি লোড হয়েছে কি না নিশ্চিত করুন। /context চালান এবং Memory ফাইলের তালিকা পড়ুন। যদি ফাইলটি সেখানে না থাকে, তবে লোকেশন ঠিক করুন এবং এখানেই থামুন। এই তালিকার অন্য কোনো ধাপ এখন প্রযোজ্য নয়।
2. নতুন সেশনে পুনরায় তৈরি করুন। একটি নতুন সেশন শুরু করুন এবং সবচেয়ে ছোট কাজটি দিন যা নিয়মটিকে ট্রিগার করবে। এখানে কাজ করলে কিন্তু দীর্ঘ সেশনে ব্যর্থ হলে বুঝতে হবে সমস্যাটি দূরত্ব বা কমপ্যাকশনের। এখানেও ব্যর্থ হলে বুঝতে হবে নিয়মটি নিজেই সমস্যার কারণ।
3. প্রতিযোগিতা দূর করুন। এমন একটি ডিরেক্টরিতে একই পরিবর্তন করতে বলুন যার বিদ্যমান কোড ইতিমধ্যেই নিয়মটি মেনে চলে। যদি কমপ্লায়েন্স ফিরে আসে, তবে বুঝতে হবে আশেপাশের কোড আপনার নির্দেশকে উপেক্ষা করছিল।
4. দ্বন্দ্ব খুঁজুন। একই আচরণের জন্য দুটি ফাইল ভিন্ন নির্দেশনা দিলে তা একটি নথিভুক্ত ব্যর্থতা: মডেলটি যেকোনো একটিকে ইচ্ছামতো বেছে নিতে পারে এবং আপনাকে তা জানাবে না।
5. যাচাইযোগ্য করুন এবং পুনরায় পরীক্ষা করুন। একটি নির্দিষ্ট পাথ এবং শর্ত দিয়ে নিয়মটি পুনরায় লিখুন। কমপ্লায়েন্সে বড় ধরনের উন্নতি হলে বুঝতে হবে আপনার বাক্যগঠনই ছিল সমস্যার কারণ।

ধাপ 4 হলো একটি কমান্ড। শুধুমাত্র যে ফাইলটি এডিট করছেন তা নয়, বরং প্রতিটি ইন্সট্রাকশন সোর্সে বিষয়টি খুঁজুন:

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

দুটি ফাইলে ভিন্ন ভিন্ন নির্দেশনা পাওয়া গেলে সেটিই আপনার বাগ। একটি মুছে ফেলুন। সেগুলোকে শক্তিশালী শব্দ দিয়ে র‍্যাঙ্ক করার চেষ্টা করবেন না, কারণ এর কোনো র‍্যাঙ্কিং ইঞ্জিন নেই যার কাছে আপনি আপিল করতে পারেন।

প্রভাবের ক্রমানুসারে সমাধানসমূহ

নিচের প্রতিটি ধাপ তার আগের ধাপের চেয়ে বেশি কার্যকর, তবে তা সেট আপ করতে খরচও বেশি। যখন কোনো নিয়ম পুনরায় লেখা সহজ, তখন তালিকার ওপর থেকে শুরু করুন। যখন কোনো নিয়ম এতই গুরুত্বপূর্ণ যে মাঝে মাঝে ভুল হওয়া গ্রহণযোগ্য নয়, তখন নিচের ধাপগুলোতে যান।

1. নিয়মটিকে সুনির্দিষ্ট করুন। একটি path, command বা condition-এর নাম উল্লেখ করুন। আগে দেখানো উপায়ে repository-তে agent যে পাল্টা প্রমাণ (counter-evidence) পাবে তা যোগ করুন। এটি বিনামূল্যে করা যায় এবং অনেক ক্ষেত্রেই সমস্যার সমাধান করে।
2. নিয়মটিকে তার নিয়ন্ত্রিত বিষয়ের কাছাকাছি নিয়ে যান। একটি nested CLAUDE.md, .claude/rules/-এ থাকা path-scoped নিয়ম, অথবা সরাসরি ফাইলের ওপরের দিকে একটি comment। এতে কোড পড়ার সময়ই নিয়মটি নজরে আসে। এই tradeoff-টি মেনে নিন: এভাবে লোড হওয়া যেকোনো কিছু পরবর্তী compaction-এর সময় মুছে যায় এবং পরবর্তী matching read-এর সময় আবার ফিরে আসে।
3. নিয়ম কার্যকর করার দায়িত্ব একটি hook-এর ওপর ন্যস্ত করুন। গদ্য বা বর্ণনামূলক নির্দেশ অনুরোধ করে, কিন্তু একটি hook সিদ্ধান্ত নেয়। hook নির্দিষ্ট lifecycle ইভেন্টে কোড হিসেবে চলে এবং model কী সিদ্ধান্ত নিল তা নির্বিশেষে কার্যকর হয়।
4. নিয়মটি একটি deterministic tool-কে দিন এবং গদ্য বা বর্ণনামূলক নির্দেশ মুছে ফেলুন। যেমন: formatting, import order, line length, banned imports, commit message-এর গঠন। ruff format, prettier --write, eslint, অথবা একটি pre-commit hook ব্যবহার করুন। formatter প্রতিবার সঠিক কাজ করে এবং কোনো token খরচ করে না। অন্যদিকে, একটি বাক্য অধিকাংশ সময় সঠিক হলেও প্রতিবারই token খরচ করে।

ধাপ 3-এর বিস্তারিত। ধরুন, migration ফাইলগুলো agent-এর দ্বারা কখনোই এডিট করা যাবে না। .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 চালান, তারপর একটি নতুন session শুরু করুন এবং agent-কে migrations/-এর অধীনে থাকা কোনো ফাইল এডিট করতে বলুন। এডিটটি প্রত্যাখ্যান করা হবে এবং আপনার দেওয়া বার্তাটি কারণ হিসেবে ফিরে আসবে। PreToolUse-এ exit status 2 টুল কলটিকে চলার আগেই আটকে দেয় এবং আপনার stderr টেক্সটটি blocking message হিসেবে model-এর কাছে পাঠানো হয়। ${CLAUDE_PROJECT_DIR} project root-কে নির্দেশ করে, তাই agent যে ডিরেক্টরিতেই থাকুক না কেন, hook-টি কাজ করবে। agent-কে নিয়মটির সাথে একমত হতে হবে না, নিয়মটি মনে রাখতে হবে না, অথবা নিয়মটি context-এ রাখতে হবে না। এডিটটি সম্পন্ন হবে না।

কোনো যুক্তি ছাড়া সরাসরি নিষেধাজ্ঞার ক্ষেত্রে, আপনার settings-এ permissions.deny একই কাজ করে, যার জন্য কোনো script রক্ষণাবেক্ষণ করতে হয় না, এবং permission mode-গুলো আপনাকে না জিজ্ঞেস করেই সিদ্ধান্ত নেয় কী চলবে। যদি কোনো নির্দেশনা সত্যিই user message-এর পরিবর্তে system prompt লেভেলে থাকা প্রয়োজন হয়, তবে --append-system-prompt তা সেখানে রাখে। তবে এটি প্রতিবার invocation-এর সময় পাস করতে হয়, যা interactive কাজের চেয়ে script-এর জন্য বেশি উপযোগী।

যা আপনি নির্দেশ দিয়ে নিয়ন্ত্রণ করতে পারবেন না

কোন অংশটি আপনার এবং কোন অংশটি মডেলের, তা পরিষ্কার রাখুন। প্লেসমেন্ট, শব্দচয়ন, ফাইলের মধ্যে দ্বন্দ্ব এবং ফাইলের আকার—এগুলো লেখকের সমস্যা এবং লেখককেই তা সমাধান করতে হবে। বাকি অংশগুলো মডেলের আচরণগত বৈশিষ্ট্য, যা কেবল ভালো শব্দ ব্যবহার করে দূর করা সম্ভব নয়।

সম্মতি মানেই নিয়ম মেনে চলা নয়। একটি এজেন্ট কোনো নিয়ম স্বীকার করবে, তা আপনাকে সঠিকভাবে পুনরায় বলবে এবং দুই ধাপ পরেই তা ভেঙে ফেলবে। এই স্বীকারোক্তির কোনো মূল্য নেই এবং এটি কোনো কিছুর পূর্বাভাস দেয় না। একে সমাধান হিসেবে দেখবেন না এবং একে কোনো পরীক্ষার ফলাফল হিসেবে গণ্য করবেন না।

কিছু অভ্যাস স্থায়ী হয়। মন্তব্য যোগ করা, ডিফেন্সিভ এরর হ্যান্ডলিং যোগ করা, শেষে সারসংক্ষেপ লেখা, পরবর্তী স্পষ্ট কমান্ডটি চালানো—এগুলো নিয়ম দ্বারা নিষিদ্ধ করার পরেও ফিরে আসে, তবে হার কিছুটা কমে। আপনি নিজেই এই হার পরিমাপ করতে পারেন: নতুন সেশনে একই কাজ দশবার চালান এবং কতবার নিয়ম লঙ্ঘন হয়েছে তা গণনা করুন। যেখানে এই সংখ্যা শূন্য হওয়া প্রয়োজন, সেখানে নিয়মটি প্রম্পট থেকে সরিয়ে ফেলতে হবে। কাজ শেষ না হওয়া সত্ত্বেও শেষ হয়েছে বলে দাবি করা একই ধরনের অভ্যাস। এর সমাধান মৌখিক নয়, বরং কাঠামোগত: the unlazy skill trades the sentence for a Depth Tree and gate files the agent has to clear before it may claim done।

আপনার নিজের সেশনটিই একটি উদাহরণ হয়ে ওঠে। যদি এজেন্ট 12 নম্বর ধাপে নিয়ম ভাঙে এবং আপনি তা এড়িয়ে যান, তবে সেই লঙ্ঘনটি কনটেক্সটে একটি উদাহরণ হিসেবে থেকে যায় এবং এটি নিয়মের চেয়েও সাম্প্রতিক। কোনো লঙ্ঘন দেখার সাথে সাথেই তা সংশোধন করুন। একটি অসংশোধিত লঙ্ঘন পুরো সেশনকে ভুল শিক্ষা দেয়।

একটি ইনস্ট্রাকশন ফাইল কোনো নিরাপত্তা সীমানা নয়। এটি আচরণকে রূপ দেয় কিন্তু তা কার্যকর করে না। যেখানে ভুল হওয়া ব্যয়বহুল, যেমন ক্রেডেনশিয়াল বা ধ্বংসাত্মক কমান্ড, তা পারমিশন বা হুকের মাধ্যমে নিয়ন্ত্রণ করা উচিত। Keeping secrets out of reach of an agent ডেটার ক্ষেত্রেও একই নীতি প্রয়োগ করে: এজেন্টকে কোনো ফাইল না পড়ার অনুরোধ না করে, ফাইলটি যাতে পড়ার যোগ্য না হয় তার ব্যবস্থা করুন।

সংক্ষেপে: ফাইলটি লোড হয়েছে তা প্রমাণ করুন, নিয়মটিকে যাচাইযোগ্য করুন, যে বিষয়টিকে নিয়ন্ত্রণ করতে চান তার পাশেই নিয়মটি রাখুন। যখন ভুলের হার গুরুত্বপূর্ণ হয়ে দাঁড়ায়, তখন তা গদ্য থেকে সরিয়ে ফেলুন। যে নিয়ম এজেন্ট উপেক্ষা করতে পারে না, তা এমন একটি নিয়ম যা এজেন্টকে কখনো অনুরোধই করা হয়নি।

FAQ

কেন Claude Code আমার CLAUDE.md ফাইলটি উপেক্ষা করে?

এটি উপেক্ষা করা হয়েছে বলে ধরে নেওয়ার আগে নিশ্চিত হয়ে নিন যে ফাইলটি লোড হয়েছে কি না। /context চালান এবং Memory files তালিকাটি দেখুন; যে ফাইলের নাম সেখানে নেই, সেটি কথোপকথনের অংশ নয়। নির্দেশনাবলী ফাইলগুলো সিস্টেম প্রম্পটের পরে একটি ইউজার মেসেজ হিসেবে পাঠানো হয় এবং এগুলোকে কঠোর কনফিগারেশনের পরিবর্তে কনটেক্সট বা প্রেক্ষাপট হিসেবে বিবেচনা করা হয়, তাই এগুলো মেনে চলার কোনো কঠোর নিশ্চয়তা নেই। বেশিরভাগ ক্ষেত্রে চারটি কারণের একটি ঘটে: ফাইলটি এমন কোনো সাব-ডিরেক্টরিতে থাকে যা এজেন্ট কখনো পড়েনি, দুটি ফাইলের মধ্যে অমিল থাকায় মডেল যেকোনো একটি বেছে নিয়েছে, নিয়মটি এতই অস্পষ্ট যে কোনো কাজের সাথে তা যাচাই করা সম্ভব নয়, অথবা আশেপাশের কোডটি নিয়মের ঠিক বিপরীত আচরণ প্রদর্শন করছে।

সেশনের মাঝপথে নির্দেশনাবলী ফাইল সম্পাদনা করলে কি কোনো পরিবর্তন হয়?

কথোপকথনে ইতিমধ্যে থাকা কপির ক্ষেত্রে কোনো পরিবর্তন হয় না। আপনার ওয়ার্কিং ডিরেক্টরির উপরের ফাইলগুলো লঞ্চের সময় সম্পূর্ণ লোড হয়, তাই মডেলের কাছে থাকা টেক্সটটি লঞ্চের সময়ের টেক্সট। কোনো পরিবর্তন কার্যকর করতে নতুন সেশন শুরু করুন অথবা এজেন্টকে তার সাধারণ ফাইল টুল ব্যবহার করে ফাইলটি পড়তে বলুন, যা বর্তমান সংস্করণটিকে একটি নতুন মেসেজ হিসেবে কথোপকথনে যুক্ত করবে। কমপ্যাকশন (compaction)-এর পরে প্রজেক্ট রুট ফাইলটি ডিস্ক থেকে পুনরায় পড়া হয়, তাই সেই সময়ে নতুন সংস্করণটি কার্যকর হয়।

রুট CLAUDE.md এবং নেস্টেড CLAUDE.md-এর মধ্যে অমিল থাকলে কোনটি কার্যকর হয়?

কোনটিই নির্ভরযোগ্যভাবে কার্যকর হয় না। খুঁজে পাওয়া ফাইলগুলো একে অপরকে ওভাররাইড করার পরিবর্তে কনটেক্সটে যুক্ত (concatenate) করা হয়, যা ফাইলসিস্টেমের রুট থেকে আপনার ওয়ার্কিং ডিরেক্টরি পর্যন্ত ক্রমানুসারে সাজানো থাকে, তাই নিকটতম ফাইলটি সবার শেষে পড়া হয়। এখানে কোনো বিরোধ নিষ্পত্তির ইঞ্জিন নেই, এবং Claude Code-এর ডকুমেন্টেশন অনুযায়ী পরস্পরবিরোধী নিয়মগুলো মডেল যেকোনোভাবে সমাধান করতে পারে। নেস্টেড ফাইলগুলোকে এমন সংযোজন হিসেবে লিখুন যা তাদের নিয়ন্ত্রিত পাথ উল্লেখ করে, এবং নিয়মটিকে প্রাধান্য দেওয়ার চেষ্টা করার পরিবর্তে বিরোধপূর্ণ অংশটি মুছে ফেলুন।

আমার নির্দেশনাবলী কি /compact কমান্ডের পরেও টিকে থাকে?

এটি নির্ভর করে সেগুলো কীভাবে লোড হয়েছে তার ওপর। প্রজেক্ট রুট CLAUDE.md, আনস্কোপড (unscoped) নিয়ম এবং অটো মেমোরি কমপ্যাকশনের পরে ডিস্ক থেকে পুনরায় ইনজেক্ট করা হয়। paths: ফ্রন্টম্যাটারসহ নিয়ম এবং সাব-ডিরেক্টরিতে থাকা নেস্টেড CLAUDE.md ফাইলগুলো ততক্ষণ পর্যন্ত হারিয়ে যায় যতক্ষণ না সংশ্লিষ্ট ফাইলটি পুনরায় পড়া হয়। আপনি চ্যাটে যা টাইপ করেছেন তা কেবল তখনই টিকে থাকে যদি সামারাইজার (summariser) সেটি রেখে দেয়। যদি কোনো নিয়ম পুরো সেশন জুড়ে কার্যকর রাখতে হয়, তবে সেটিকে paths: ফ্রন্টম্যাটার ছাড়া প্রজেক্ট রুট ফাইলে রাখুন।

কখন একটি নিয়মকে প্রোজের (prose) পরিবর্তে হুক (hook) করা উচিত?

যখন যাচাইকরণটি ডিটারমিনিস্টিক বা সুনির্দিষ্ট হয় এবং কোনো ভুল হওয়ার খরচ একটি ছোট স্ক্রিপ্ট লেখার খরচের চেয়ে বেশি হয়। ফাইলের পাথ সীমাবদ্ধতা, কমিট করার আগে প্রয়োজনীয় কমান্ড এবং নিষিদ্ধ টুল কল—এগুলো সবই এর অন্তর্ভুক্ত। একটি PreToolUse হুক যা স্ট্যাটাস 2 নিয়ে এক্সিট করে, তা টুল কলটিকে সরাসরি আটকে দেয় এবং আপনার stderr টেক্সটটিকে কারণ হিসেবে মডেলের কাছে ফেরত পাঠায়, তাই কনটেক্সটে নিয়মটি থাকুক বা না থাকুক, এটি কার্যকর থাকে। ফরম্যাটার বা লিন্টার যা সিদ্ধান্ত নিতে পারে, তা সেই টুলের ওপর ছেড়ে দিন এবং নির্দেশনাবলী ফাইল থেকে তা পুরোপুরি মুছে ফেলুন।