DESIGN.md: AGENTS.md-এর পরের গুরুত্বপূর্ণ ফাইল

DESIGN.md কী এবং AGENTS.md কী নির্ধারণ করে না

DESIGN.md হলো repository root-এ থাকা একটি markdown file। এতে coding agent-কে জানানো হয়, code কেন বর্তমান কাঠামোতে আছে। AGENTS.md ভিন্ন একটি প্রশ্নের উত্তর দেয়: এখানে কীভাবে কাজ করতে হবে। এর মধ্যে build command, test command, সফল হতে হবে এমন lint এবং যেসব path পরিবর্তন করা যাবে না, সেগুলো থাকে। DESIGN.md-তে ইতিমধ্যে নির্ধারিত সিদ্ধান্তগুলো এবং সেগুলোর কোনোটি বাতিল করলে কী ভেঙে যাবে, তা নথিভুক্ত করা হয়।

Coding agent বলতে Claude Code বা Cursor-এর মতো এমন tool বোঝায়, যা নিজে আপনার repository পড়ে এবং সম্পাদনা করে। এই ধরনের agent ডিফল্টভাবে আত্মবিশ্বাসী থাকে। এটি এমন কোনো pattern খুঁজে পেলে, যা তার পরিচিত নয়, সেটিকে উন্নত করার চেষ্টা করে। হাতে লেখা একটি cache Redis-এ পরিবর্তিত হয়ে যেতে পারে—Redis একটি in-memory data store—কারণ model যে code পড়েছে, তার বেশিরভাগে cache এভাবেই তৈরি করা হয়। AGENTS.md এটি আটকায় না, কারণ make test দুই ক্ষেত্রেই পাস করে। যে নিয়মটি ভাঙা হয়েছে, তা agent পড়তে পারে এমন কোথাও লেখা ছিল না।

আপনি যদি এখনও প্রথম file-টি না লিখে থাকেন, তাহলে সেখান থেকেই শুরু করুন। এর পাশে থাকা AGENTS.md এবং HUMAN.md-এ format এবং প্রতিটি tool কোন অবস্থান থেকে file খোঁজে, তা ব্যাখ্যা করা হয়েছে। এর পরের অধ্যায়ে সেই আলোচনার পরবর্তী বিষয় বর্ণনা করা হয়েছে।

প্রকাশিত DESIGN.md-তে আসলে কী থাকে

এই format শেখার দ্রুততম উপায় হলো কোম্পানিগুলো নিজেদের সম্পর্কে প্রকাশ করা file পড়া। official-design-md repository শুধু এই file-গুলোই track করে। এর inclusion rule এক লাইনের, এবং collection-টির মূল উদ্দেশ্যও ওই লাইনেই স্পষ্ট:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

August 2026 অনুযায়ী তালিকায় সাতটি নাম আছে: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel এবং VoltAgent। প্রতিটি file একটি স্থায়ী public URL-এ রয়েছে। তাই এখনই terminal-এ একটি file পড়তে পারেন।

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

দুটিই design system document। এগুলো product দেখতে কেমন হওয়া উচিত তা বর্ণনা করে: colour, type, spacing এবং motion। বিষয়বস্তুর বাইরে গিয়ে লেখার গঠনটি দেখুন, কারণ কার্যকর অংশটি বিষয় নয়, লেখার ধরন।

Nuxt file-টি প্রায় 2,100 শব্দের। এর অধিকাংশই কারণসহ একটি করে rule:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

August 2026-এ Vercel file-টি আরও বড়, প্রায় 6,500 শব্দের। এটি আরও এক ধাপ এগিয়ে যায়। এর একটি heading হলো Reject generated-design reflexes। এর নিচে এমন কিছু বিষয়ের তালিকা রয়েছে, যেগুলো না করতে বলা না হলে একটি সক্ষম generator স্বাভাবিকভাবেই বেছে নেয়:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

এই sentence-টিই file type-টি সংজ্ঞায়িত করে। এটি হলো কোনো domain-এ একটি confident model যে default-গুলো তৈরি করে, সেগুলোর লিখিত তালিকা; model যেন সেগুলো তৈরি করা বন্ধ করে, সেই উদ্দেশ্যে তালিকাটি প্রকাশ করা হয়। Commit করার মতো প্রতিটি DESIGN.md কোনো একটি domain-এর জন্য সেই তালিকাই।

কোম্পানিগুলো নিজেদের DESIGN.md কেন প্রকাশ করে?

কমিউনিটি আগে এই কাজ শুরু করেছে। awesome-design-md-এ public website থেকে reverse-engineer করা 73টি file রয়েছে। প্রতিটি file একই নয়-সেকশনের format-এ লেখা, তাই agent-কে এমন একটি file দেখিয়ে কাছাকাছি ধরনের design তৈরি করানো যায়। এই file-গুলো উপকারী, তবে এগুলো এখনও অনুমানভিত্তিক। পর্যালোচনা করা কোম্পানিগুলোর কেউই এগুলো যাচাই করেনি।

First-party file আলাদা, কারণ এটি output-এর ব্যাখ্যা নয়; এটি source। Vercel তার type scale পরিবর্তন করলে vercel.com/design.md-ও তার সঙ্গে পরিবর্তিত হয়। March-এ scrape করা একটি copy আপনার agent-কে পুরোনো scale শেখাতে থাকবে, এবং copy-টি stale হয়ে গেছে—এ কথা আপনার repository-র কোথাও উল্লেখ থাকবে না।

Seven publisher একটি ছোট সংখ্যা, এবং repository-ও তা স্বীকার করে: standard-টি নতুন, আর official adoption বাড়ছে। উভয় collection-ই VoltAgent রক্ষণাবেক্ষণ করে। এটি একটি open source agent framework, যা নিজেদের file-ও প্রকাশ করে। তাই এই তালিকাকে নিরপেক্ষ census নয়, tracker হিসেবে পড়ুন। তবু তালিকাটি পর্যবেক্ষণ করার মতো, কারণ এই seven publisher কারা। অন্য developers সবচেয়ে বেশি যেসব কোম্পানির front-end code copy করেন, এগুলো সেই কোম্পানিগুলো। তাদের file-গুলো DESIGN.md কীভাবে ব্যবহার করতে হয়, তার বাস্তব উদাহরণ হয়ে উঠছে। AGENTS.md-এর পথের সঙ্গে তুলনা করুন: agents.md format-টি ব্যবহার করা open source project-এর সংখ্যা এখন 60,000-এর বেশি দেখাচ্ছে, এবং এর stewardship Linux Foundation-এর অধীন Agentic AI Foundation-এর হাতে রয়েছে। Agent-readable file-এর convention দ্রুত স্থির হচ্ছে, এবং এই পরিবর্তন শীর্ষস্থানীয় প্রতিষ্ঠানগুলো থেকেই শুরু হচ্ছে।

ইউজার ইন্টারফেস না থাকলে DESIGN.md-তে কী থাকবে

VPS-এ চলা অধিকাংশ software-এর জন্য নির্ধারণ করার মতো কোনো visual language থাকে না। তবুও এই file-এর প্রয়োজন আছে, কারণ এর উদ্দেশ্যের সঙ্গে colour-এর কোনো সম্পর্ক নেই। এর উদ্দেশ্য হলো এমন constraints লিখে রাখা, যেগুলো না জানলে একজন আত্মবিশ্বাসী editor অজান্তেই ভেঙে ফেলতে পারে।

Invariants। প্রতিটিতে একটি করে sentence লিখুন, যেখানে বলা থাকবে যে যেকোনো edit-এর পরও কোন বিষয়টি সত্য থাকতে হবে। "প্রতিটি write queue.enqueue()-এর মাধ্যমে হবে। সরাসরি database write করলে audit log এড়িয়ে যায়, অথচ compliance export audit log থেকেই data পড়ে।" কারণসহ লেখা invariant এমন task-এর ক্ষেত্রেও কার্যকর থাকে, যা আপনি আগে অনুমান করেননি। কারণ ছাড়া invariant শুধু preference মনে হয়, আর preference সাধারণত বাদ দেওয়া হয়।

Rejected alternatives। কোন obvious option নেওয়া হয়নি এবং কেন নেওয়া হয়নি, তা লিখুন। "আমরা caching-এর জন্য Redis ব্যবহার করি না। service একটি single VPS-এ চলে, তাই in-process map দ্রুততর এবং চালু রাখার জন্য একটি daemon কম লাগে। দ্বিতীয় application server থাকলে এই সিদ্ধান্ত পুনর্বিবেচনা করুন।" এই paragraph না থাকলে cache দ্রুত করার task পাওয়া agent Redis যোগ করবে, এবং সেটি করাই তার পক্ষে যৌক্তিক: আপনি constraint-টি জানিয়ে রাখেননি। এই section-ই পুরো file-এর প্রয়োজনীয়তা সবচেয়ে ভালোভাবে পূরণ করে।

Boundaries। যেসব জায়গায় ছোট একটি edit-এর প্রভাবের পরিসর অনেক বড় হতে পারে, সেগুলো লিখুন। Database schema। Public route prefix, যার ওপর customer-দের script ইতিমধ্যে নির্ভর করে। Deploy শুরু হওয়ার আগে যে config file পড়ে। এমন cron entry, যা ধরে নেয় যে এর একটির বেশি copy একসঙ্গে চলছে না। এগুলোর নাম লিখুন এবং প্রতিটির পরিবর্তনের খরচ কী, তা উল্লেখ করুন। Agent যদি open web-এও পৌঁছাতে পারে, যেমন search backend হিসেবে সংযুক্ত একটি self-hosted SearXNG instance-এর মাধ্যমে, সেটিও লিখে রাখার মতো একটি boundary। কারণ file-এ উল্লেখ থাকা উচিত, fetched text-এর কোন অংশ code-কে প্রভাবিত করতে পারে এবং কোন অংশ কেবল আপনাকে উদ্ধৃত করে দেখানো যাবে।

Vocabulary। Code-এ যদি tenant এবং team-এ যদি customer বলা হয়, তাহলে তাদের mapping লিখে রাখুন। এখানে agent ভুল অনুমান করলে এমন code তৈরি হয়, যা পড়তে ঠিক মনে হয় কিন্তু ভুল বিষয়কে model করে। Review-এ শনাক্ত করা সবচেয়ে কঠিন ধরনের ভুল এটাই।

আজই কপি করতে পারেন এমন একটি DESIGN.md

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

আজই স্মরণ থেকে লিখতে পারবেন এমন দুটি section পূরণ করুন: invariants এবং rejected alternatives। বাকি অংশ headings হিসেবে রেখে দিন। চারটি সৎ line-সহ একটি file কার্যকর। অনুমান করে লেখা চল্লিশটি line কার্যকর নয়। repository-তে একাধিক package থাকলে একটি root file সবগুলোর জন্য উপযুক্ত হবে না। এই ক্ষেত্রে monorepo-তে nested AGENTS.md file-এর জন্য কার্যকর একই per-directory বিভাজন প্রয়োগ করুন: সব package-এর অভিন্ন সিদ্ধান্তের জন্য একটি সংক্ষিপ্ত root file এবং নিজস্ব সিদ্ধান্ত থাকা প্রতিটি package-এর পাশে একটি ছোট file।

কিছু tool repository root-এর প্রতিটি markdown file load করে। কিছু tool কেবল যেটির উল্লেখ করা হয় সেটিই load করে। তাই ধরে নেবেন না। AGENTS.md-তে একটি pointer যোগ করুন:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

বিরোধী নকশা: README-এর পুনরাবৃত্তি করা DESIGN.md

সবচেয়ে প্রচলিত খারাপ সংস্করণটি পড়তে ভালো লাগে, কিন্তু কিছু শেখায় না। এটি শুরুতেই project কী করে তা বলে, feature-এর তালিকা দেয়, কীভাবে এটি install করতে হয় তা ব্যাখ্যা করে এবং licence দিয়ে শেষ হয়। এর প্রতিটি তথ্য ইতিমধ্যেই README-তে আছে। এগুলোর কোনোটিই বলে না কেন কোনো সিদ্ধান্ত এভাবে নেওয়া হয়েছে।

এতে আপনার দুইবার খরচ হয়। প্রথম খরচটি হলো context। প্রতিটি task-এর শুরুতে agent যে file পড়ে, প্রতিটি task-এ তার জন্য খরচ হয়। নির্দিষ্ট window-এর মধ্যে পুনরাবৃত্ত install section সম্পূর্ণ অতিরিক্ত বোঝা। ওই window-এর জন্য যথাযথ budget নির্ধারণ করাও একটি আলাদা দক্ষতা। এটি Claude Code-এ context window পরিচালনা-এ ব্যাখ্যা করা হয়েছে। সংক্ষেপে: যে text স্বয়ংক্রিয়ভাবে load হয়, repository-তে তার মূল্য সবচেয়ে বেশি হওয়া উচিত।

দ্বিতীয় খরচটি আরও গুরুতর। একই বক্তব্যের দুটি copy পরস্পরের থেকে আলাদা হয়ে যায়। README-তে বলা আছে service 8080-এ listening করছে, কিন্তু DESIGN.md-তে এখনও 3000 লেখা আছে। কোনোটিকে অগ্রাধিকার দিতে হবে, agent-এর তা বোঝার উপায় নেই। ফলে এটি যেকোনো একটি বেছে নিয়ে তার ভিত্তিতে code লেখে। কোনো file কখনও ভুল হলে, সব সময় সঠিক থাকা file-এর মতো একই আস্থায় সেটিও ব্যবহার করা হয়।

পরীক্ষাটি দ্রুত করা যায়। কোনো paragraph README-তে স্বাভাবিকভাবে বসতে পারলে, সেটি DESIGN.md থেকে বাদ দিন। বাকি অংশে এমন বিষয় থাকা উচিত যা code review-তে আপনি সরাসরি বলতেন—যে অংশটি শুরু হয়, “আমরা এটি আগেই চেষ্টা করেছি” দিয়ে।

ফাইলটি কাজ করছে কি না কীভাবে বুঝবেন?

এর জন্য কোনো linter নেই। তবে এক মিনিটে চালানো যায় এমন একটি পরীক্ষা আছে।

এমন একটি কাজ agent-কে দিন, যা সরাসরি একটি invariant-এর মুখোমুখি হয়। “stale row-গুলোকে expired হিসেবে চিহ্নিত করার জন্য একটি background job যোগ করুন।” ফাইলটি ঠিকমতো কাজ করলে কোনো code লেখার আগেই তার প্রভাব উত্তরে দেখা যাবে: agent-এর বলা উচিত, job-টি queue.enqueue()-এর মাধ্যমে write করবে, কারণ সরাসরি write করলে audit log এড়িয়ে যাবে। এটি যদি database connection খুলে write করে, তাহলে দুটি সম্ভাবনার একটি সত্য। ফাইলটি একেবারেই পড়া হচ্ছে না, অথবা invariant-টি এত অস্পষ্টভাবে লেখা হয়েছে যে তা নিয়ে তর্ক করা যায়।

Token count-ও লক্ষ্য করুন, কারণ প্রতিটি turn-এ এই ফাইলটি load হয়। DESIGN.md যোগ করার পর যদি context usage বেড়ে যায় কিন্তু উত্তর উন্নত না হয়, তাহলে ফাইলটিতে এমন prose আছে যা agent আগে থেকেই জানত। Claude Code-এ token counter পড়া দেখায়, সেই budget কোথায় ব্যবহার হচ্ছে।

Agent আপনার laptop-এর বদলে কোনো server-এ চললে এটি সবচেয়ে গুরুত্বপূর্ণ। tmux-সহ VPS-এ Claude Code workspace-এর মতো দীর্ঘস্থায়ী session-এ কাজ করা agent-এর আগের দিনের conversation মনে থাকে না। Repository-ই memory হিসেবে কাজ করে। Chat-এ আপনি যা ব্যাখ্যা করেছেন কিন্তু কখনো commit করেননি, পরের session-এ তা আর থাকে না। সেই ব্যাখ্যা সংরক্ষণ করে রাখার জায়গা হলো DESIGN.md।

যেসব সিদ্ধান্ত নিয়ে আপনাদের মধ্যে মতবিরোধ হয়, সেগুলো দিয়ে শুরু করুন

প্রথম সংস্করণ তৈরি করতে বিশ মিনিট লাগে। সর্বশেষ কয়েকটি pull request খুলুন, যেখানে কোনো reviewer লিখেছেন, “না, আমরা এখানে এটি ভিন্নভাবে করি।” প্রতিটি মন্তব্য এমন একটি invariant, যা কখনো লিখে রাখা হয়নি। প্রতিটি মন্তব্য এমন একটি জায়গাও নির্দেশ করে, যেখানে কোনো agent একই ভুল করবে—মানুষের চেয়ে দ্রুত এবং বেশি বার। কোনো schedule অনুযায়ী নয়; কোনো বিষয় আপনাকে ব্যর্থ করলে তখনই ফাইলটিতে তা যোগ করুন। স্বাভাবিক development workflow-এ agent কোথায় ব্যবহার করবেন, তা যদি এখনও নির্ধারণ করে থাকেন, তাহলে AI agent শেখার 2026 সালের নির্দেশিকা পরবর্তী ধাপ হিসেবে উপযোগী।

FAQ

DESIGN.md কি একটি অফিসিয়াল standard?

AGENTS.md-এর মতো অর্থে নয়। AGENTS.md-এর জন্য agents.md-এ একটি নির্দিষ্ট home আছে, 60,000-এর বেশি open source project এটি ব্যবহার করে, এবং Linux Foundation-এর অংশ Agentic AI Foundation এর stewardship পরিচালনা করে। August 2026 পর্যন্ত DESIGN.md-এর কোনো governing body বা published specification নেই। তবে first-party adoption আছে: Vercel, Nuxt, Atlassian এবং Resend-সহ সাতটি company public URL-এ এটি প্রকাশ করে, আর একটি community collection-এ public site থেকে reverse-engineer করা আরও 73টি রয়েছে। এটিকে এখনই গ্রহণযোগ্য এবং প্রয়োজনে স্বাধীনভাবে সম্প্রসারণযোগ্য একটি convention হিসেবে ব্যবহার করুন, কারণ আপনার section name যাচাই করার কোনো ব্যবস্থা নেই।

DESIGN.md কি শুধু AGENTS.md-এর একটি section হওয়া উচিত?

ছোট repository-এর ক্ষেত্রে, হ্যাঁ। Agent নিশ্চিতভাবে পড়ে এমন একটি file, এমন দুটি file-এর চেয়ে ভালো যার একটি উপেক্ষিত হতে পারে। AGENTS.md পড়ে দ্রুত বোঝা কঠিন হয়ে গেলে, অথবা দুই অংশ ভিন্ন হারে পরিবর্তিত হচ্ছে বুঝতে পারলে file দুটি আলাদা করুন। Build পরিবর্তিত হলে AGENTS.md পরিবর্তিত হয়। কোনো decision পরিবর্তিত হলে DESIGN.md পরিবর্তিত হয়, যা তুলনামূলকভাবে কম ঘটে এবং বেশি গুরুত্বপূর্ণ। আলাদা করার সময় AGENTS.md-এ একটি line যোগ করে agent-কে code edit করার আগে DESIGN.md পড়তে বলুন, কারণ প্রতিটি tool root-এর প্রতিটি markdown file load করে না।

DESIGN.md একটি architecture decision record থেকে কীভাবে আলাদা?

ADR (architecture decision record) হলো একটি decision-এর তারিখসহ record, এবং একটি সুস্থ project সাধারণত একটি folder-এ এমন কয়েক ডজন record জমা করে। এটি একটি history, আর history load করা ব্যয়বহুল, কারণ কোন record এখনও প্রযোজ্য তা বোঝার জন্য agent-কে সবগুলো পড়তে হবে। DESIGN.md হলো বর্তমান অবস্থা, যা প্রতিটি task-এ সম্পূর্ণ পড়ার জন্য লেখা হয়। আপনি আগে থেকেই ADR লিখলে দুটিই রাখুন। ADR বলে কী সিদ্ধান্ত নেওয়া হয়েছিল এবং কখন। DESIGN.md বলে আজ কী সত্য, এবং agent-কে নির্দেশ করার জন্য এটিই ব্যবহার করুন।

DESIGN.md কত দীর্ঘ হওয়া উচিত?

এতটাই ছোট হওয়া উচিত যাতে প্রতিটি turn-এ অনুতাপ ছাড়াই load করা যায়। Published example-গুলো দীর্ঘ, কারণ সেগুলো একটি সম্পূর্ণ visual language নির্দিষ্ট করে: August 2026 অনুযায়ী Nuxt file-এ প্রায় 2,100 word এবং Vercel file-এ প্রায় 6,500 word রয়েছে। একটি backend service-এর সাধারণত এর চেয়ে অনেক কম প্রয়োজন। এক page দিয়ে শুরু করুন। কোনো agent এমন ভুল করলে তবেই এটি বড় করুন, যা একটি বাক্য লিখলে প্রতিরোধ করা যেত। Length হলো মাপকাঠি নয়। প্রতিটি line এমন একটি বিষয় হওয়া উচিত, যা না থাকলে agent অন্যথায় ভুল করত।