Module 3 · Day 17

CLAUDE.md as a Contract

Day 16-তে `/init` দিয়ে শুরু করেছিলে — আজ CLAUDE.md-এর পুরোটা। কী রাখবে, কী বাদ দেবে, কীভাবে স্তরে ভাগ হয়, আর কীভাবে ভালো একটা clause লেখো — যেটা Claude সত্যিই মেনে চলে।

~120 min read6 learning objectives

What you'll learn

•CLAUDE.md কী — তোমার আর Claude-এর মধ্যে একটা contract, যেটা ও প্রতি session-এর শুরুতে পড়ে।
•কেন chat যথেষ্ট না — /clear, /compact, session বন্ধ হলে কথা মুছে যায়; file থেকে যায়।
•Memory hierarchy — user (~/.claude) · project (git-এ) · local (gitignored) — কোন নিয়ম কোথায়।
•কী রাখবে, কী বাদ দেবে — "এই line না থাকলে Claude ভুল করত?" এই একটা প্রশ্নে decide করা।
•ভালো clause লেখা — specific, verifiable, imperative English (এই lesson-এর আসল লক্ষ্য)।
•Living contract — /init দিয়ে শুরু; Claude একই ভুল ২য় বার করলে একটা clause যোগ করা।

Before this

•Day 16 — Claude Code basics; /init আর starter CLAUDE.md দেখা হয়ে গেছে।
•একটা project-এ `claude` চালাতে পারা।
•Git-এর হালকা ধারণা (.gitignore কী করে — জানা থাকলে ভালো)।

The Contract

Chat ভুলে যায়, file মনে রাখে।

Day 16-এ `/init` চালিয়ে একটা starter CLAUDE.md বানিয়েছিলে — শুধু পরিচয় হয়েছিল। আজ পুরোটা: এই file আসলে কী, কেন এত গুরুত্বপূর্ণ, আর কীভাবে ভালো একটা লেখো।

CLAUDE.mdতোমার আর Claude-এর contract

CLAUDE.md হলো একটা সাধারণ markdown file, যেটা Claude Code প্রতি session-এর শুরুতে নিজে থেকেই পড়ে। ভাবো এটা একটা contract — এই project কীভাবে চলে, তার নিয়মগুলো একবার লিখে রাখা। Chat-এ বলা কথা /clear, /compact বা session বন্ধ হলে মুছে যায়; contract থেকে যায়।

Why it matters

এটাই beginner-এর সবচেয়ে বড় leverage। একই কথা প্রতি session-এ আবার বোঝানো বনাম একবার file-এ লিখে রাখা — পার্থক্যটা আকাশ-পাতাল। Claude Code-কে নির্ভরযোগ্য বানানোর প্রথম ধাপ এই file।

নিচে দেখো — একটা clause থাকলে আর না থাকলে, একই request-এ Claude-এর ফল কতটা আলাদা হয়। এটাই contract-এর মানে — লেখা থাকলে binding।

Interactive · contract টা কাজ করে কিনা দেখো

একই request — clause ছাড়া বনাম সহ

রাফি একই কাজ চায়। নিচের switch দিয়ে CLAUDE.md-র একটা clause OFF/ON করো — দেখো Claude-এর আচরণ কীভাবে বদলায়। একটা লাইনই পুরো ফল ঘুরিয়ে দেয়।

রাফি বলল:

❯ Add the requests library to the project.

CLAUDE.md clause:

clause ছাড়া Claude যা করল

$ npm install requests
⚠ npm package-lock.json বানায় — team-এর pnpm-lock.yaml-এর সাথে conflict।

Clause না থাকলে Claude সবচেয়ে common জিনিসটা ধরে নেয় — npm। তোমার project pnpm হলে lockfile ভেঙে যায়। একটা লাইন সেটা ঠেকায়।

মনে রাখো: contract মানে binding — file-এ লেখা থাকলে Claude প্রথম turn থেকেই সেটা মেনে চলে। নিয়মটা একবার লেখো, প্রতি session-এ কাজ করে।

Memory Hierarchy

CLAUDE.md এক জায়গায় থাকে না — কয়েকটা স্তরে।

CLAUDE.md বললে মনে হয় একটাই file। আসলে কয়েকটা স্তর একসাথে মিশে Claude যা পড়ে সেটা তৈরি করে — কোন নিয়ম কোথায় যাবে, সেটাই এই স্তরগুলো ঠিক করে দেয়।

Memory hierarchyuser · project · local

CLAUDE.md এক জায়গায় থাকে না — কয়েকটা স্তরে। ~/.claude/CLAUDE.md (তুমি, সব project) · ./CLAUDE.md (team-এর, git-এ committed) · ./CLAUDE.local.md (শুধু তুমি, এই project, gitignored)। সবগুলো একসাথে load হয়ে Claude যা পড়ে সেটা তৈরি করে। (উপরে কোম্পানির managed policy থাকতে পারে।)

Why it matters

কোন নিয়ম কোথায় যাবে — এটা জানা জরুরি। তোমার নিজের sandbox URL বা পছন্দ team-এর file-এ দিলে সবার কাছে চলে যাবে; ওটা CLAUDE.local.md-তে রাখো। Team-এর shared standard ./CLAUDE.md-তে, যাতে git দিয়ে সবার কাছে যায়।

Interactive · কোন নিয়ম কোথায় থাকে

Memory hierarchy — স্তরে স্তরে

CLAUDE.md এক জায়গায় থাকে না — কয়েকটা স্তরে। প্রতিটায় চাপ দিয়ে দেখো সেটা কী জন্য, কে দেখে, আর কী ধরনের clause সেখানে যায়। সবগুলো একসাথে load হয়ে Claude যা পড়ে সেটা তৈরি করে।

এই project-এর shared standard — build/test command, convention, architecture। এটাই মূল file।

দেখে: পুরো team (git দিয়ে আসে)

Test: pytest -q. Categories: delivery_delay, wrong_item, damaged, billing, other.

সব স্তর একসাথে join হয়ে → Claude session শুরুতে যা পড়ে। তোমার নিজের sandbox URL team-এর ./CLAUDE.md-তে দিও না — ওটা CLAUDE.local.md-তে রাখো, যাতে git-এ না যায়।

কী রাখবে, কী বাদ দেবে

আজকের সবচেয়ে দরকারি skill — কম রাখা।

Beginner-এর সহজাত ভুল হলো CLAUDE.md-তে সব ভরে দেওয়া — "যত বেশি নিয়ম, তত ভালো।" আসল skill ঠিক উল্টো: কম রাখা।

Signal, not noiseকী রাখবে, কী বাদ

নিয়ম একটাই: Claude কি এটা code পড়ে নিজে বুঝে নিতে পারবে? পারলে — বাদ (ভাষা কী, function কী করে — derivable)। না পারলে — রাখো (test command, category-র নাম, env var, একটা gotcha, branch convention)। সাথে vague জিনিস ("clean code লেখো") বাদ — ওটা কিছু বদলায় না।

Why it matters

প্রতি line-এ জিজ্ঞেস করো: "এই line টা না থাকলে কি Claude ভুল করত?" উত্তর না হলে কেটে দাও। নিচের ৮টা লাইন সাজিয়ে নিজে practice করো।

Interactive · আজকের আসল skill

CLAUDE.md-এ রাখবে, না বাদ দেবে?

প্রতিটা line-এর জন্য নিজেকে জিজ্ঞেস করো: "এটা না থাকলে কি Claude ভুল করত?" — আর Claude কি এটা code পড়ে নিজে বুঝে নিতে পারত? তারপর Keep বা Leave out বাছো।

Test command: pytest -q

Categories: delivery_delay, wrong_item, damaged, billing, other, unclassifiable

Never edit data/labels.csv by hand — it's generated.

Branch names: feature/<ticket-id>.

This project is written in Python.

classify() takes a string and returns a category label.

Write clean, readable, well-organized code.

(A 200-line list of every function in the repo and what it does.)

Lean beats longছোট রাখো — নাহলে ignored

CLAUDE.md প্রতি session-এ পুরোটা context-এ load হয় — মানে প্রতিবার token খরচ। আর বড় file-এ জরুরি নিয়মগুলো অপ্রয়োজনীয় কথার ভিড়ে চাপা পড়ে যায়, তখন Claude সেগুলো ignore করতে শুরু করে। লক্ষ্য: ২০০ line-এর কম।

Why it matters

এটা উল্টো লাগে কিন্তু সত্যি: বড় CLAUDE.md মানে Claude তোমার নিয়ম কম মানে, বেশি না। তাই বেশি লিখলে আসলে ক্ষতি। বড় হয়ে গেলে নিয়মিত prune করো — code-এর মতোই।

Tip

একটাই test মনে রাখো: "এই line-টা না থাকলে কি Claude ভুল করত?" — উত্তর না হলে কেটে দাও। এই একটা প্রশ্ন বেশিরভাগ সিদ্ধান্ত সহজ করে দেয়।

Clause লেখা যেটা Claude মানবে

Vague না — specific আর verifiable।

কী রাখবে সেটা ঠিক করা অর্ধেক কাজ। বাকি অর্ধেক — সেটা কীভাবে লেখো। একটা vague clause আর একটা verifiable clause-এর ফল আকাশ-পাতাল, যদিও দুটোই এক লাইন।

Verifiable clausesspecific > vague

Clause এমনভাবে লেখো যেন Claude যাচাই করতে পারে। "test properly" অকেজো; "Run `pytest -q` before declaring done" কাজের — command আছে, সময় আছে, ফল মাপা যায়। ভাষা imperative রাখো: Always… / Never… / Use X, not Y… / Run … before …। খুব দরকারে জোর দিতে IMPORTANT বা YOU MUST।

Why it matters

এটাই এই lesson-এর আসল লক্ষ্য — তুমি যেন কাজে গিয়ে English-এ এই নির্দেশগুলো নিজে লিখতে পারো। নিচের প্রতিটা vague clause চাপ দিয়ে দেখো, কীভাবে verifiable হয়ে ওঠে।

Interactive · clause-টা নিজে লিখতে শেখো

Vague বনাম verifiable clause

এটাই এই lesson-এর আসল হৃদয় — CLAUDE.md-এ তুমি যে English নির্দেশগুলো নিজে টাইপ করবে। নিচের vague clause-গুলোয় চাপ দিয়ে দেখো, কীভাবে একই নিয়মকে Claude যাচাই করতে পারে এমন করে লেখা যায়।

Vague — Claude মাপতে পারে না

"test your changes"

Verifiable — CLAUDE.md-এ এভাবে লেখো

Run `pytest -q` before declaring a task done.

specific commandwhen to run

শুধু "test করো" বললে কীভাবে আর কখন, Claude জানে না। command (pytest -q) + কখন (done বলার আগে) দিলে ও নিজে চালিয়ে যাচাই করে নেয়।

Pattern: Always … · Never … · Use X, not Y · Run … before …। একটা command, একটা মাপকাঠি, বা একটা example — তাহলেই clause টা কাজের।

এই টুকরোগুলো জোড়া দিলে একটা আসল CLAUDE.md এমন দেখতে হয় — commands, conventions, আর gotchas, প্রতিটা লাইন কাজের, ২০০ line-এর অনেক নিচে।

markdown

# CLAUDE.md — complaint-classifier

## Commands
- Test: pytest -q
- Run:  python classify.py

## Conventions
- Categories are exactly: delivery_delay, wrong_item,
  damaged, billing, other, unclassifiable
- Keep classify() signature stable

## Gotchas
- Never edit data/labels.csv by hand — it's generated

Living Contract

একবার লেখো, তারপর বড় করো।

CLAUDE.md একবার লিখে ফেলে দেওয়ার জিনিস না। /init দিয়ে একটা draft বানাও, তারপর সময়ের সাথে বাড়াও।

A living contract/init দিয়ে শুরু, সময়ে বাড়াও

CLAUDE.md একবার লিখে ফেলে দেওয়ার জিনিস না। /init দিয়ে একটা draft বানাও, তারপর বাড়াতে থাকো। নিয়মটা পরিষ্কার: Claude একই ভুল ২য় বার করলে — সেটা chat-এ ঠিক না করে file-এ একটা clause যোগ করো। /memory দিয়ে file গুলো দেখো/এডিটো; @import দিয়ে গুছাও। (নতুন auto memory feature Claude-কে নিজে থেকেও কিছু শিখে রাখতে দেয়।)

Why it matters

চ্যাটে ঠিক করলে শুধু এই session-এ কাজ হয়; পরের fresh session-এ একই ভুল ফেরে। File-এ clause দিলে সমস্যা একবারে শেষ। তোমার contract যত পরিণত হবে, Claude তত নির্ভরযোগ্য।

Interactive · contract টা জীবন্ত

একই ভুল ২য় বার → একটা clause যোগ

রাফির গল্পটা ধাপে ধাপে দেখো। Chat-এ ঠিক করলে শুধু এই session-এ কাজ হয়; পরের fresh session-এ একই ভুল ফেরে। আসল সমাধান — CLAUDE.md-তে একটা clause।

Start চাপলে গল্পটা শুরু হবে…

Note

নিয়মটা মনে রাখো: Claude একই ভুল ২য় বার করলে chat-এ ঠিক কোরো না — file-এ একটা clause যোগ করো। তখন সমস্যাটা একবারে শেষ।

Check Your Understanding

ভুল হলে সমস্যা নেই — প্রতিটার ব্যাখ্যা আছে।

Misconception check

CLAUDE.md যত বড় আর বিস্তারিত, তত ভালো — সব নিয়ম ভরে দাও

Misconception check

CLAUDE.md-তে আমার code কী করে সব ব্যাখ্যা করে দিলে Claude ভালো বুঝবে

Misconception check

একবার /init চালিয়ে CLAUDE.md বানালেই কাজ শেষ

Misconception check

আমার personal preference (sandbox URL, পছন্দের test data) team-এর ./CLAUDE.md-তে দিই

Misconception check

Chat-এ একবার বলে দিলেই Claude মনে রাখবে — file-এ লেখার দরকার নেই

Quick check