AGENTS.md-এর পর DESIGN.md কেন লিখবেন

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

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

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

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

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

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

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। প্রতিটি ফাইল একটি স্থায়ী public URL-এ থাকে। তাই এখনই terminal-এ একটি ফাইল পড়তে পারেন।

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

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

Nuxt ফাইলটিতে প্রায় 2,100 শব্দ রয়েছে। এর অধিকাংশ অংশে কারণসহ একটি করে নিয়ম দেওয়া হয়েছে:

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 ফাইলটি আরও দীর্ঘ, প্রায় 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.

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

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

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

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

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

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

VPS-এ চলা অধিকাংশ সফটওয়্যারের জন্য নির্দিষ্ট করার মতো কোনো visual language থাকে না। তবু এই ফাইলের প্রয়োজন আছে, কারণ এর বিষয় রং নয়। বিষয়টি হলো এমন constraint লিখে রাখা, যা একজন আত্মবিশ্বাসী editor খেয়াল না করেই অন্যথায় লঙ্ঘন করতে পারে।

Invariants। প্রতিটিতে একটি করে বাক্য লিখুন। যেকোনো 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 দ্রুত করার দায়িত্ব পাওয়া agent Redis যোগ করবে, এবং সেটি করাই যুক্তিসঙ্গত: আপনি তাকে constraint জানাননি। এই section-ই পুরো ফাইলের উপযোগিতা প্রমাণ করে।

Boundaries। যেসব জায়গায় ছোট edit-এর প্রভাব অনেক দূর পর্যন্ত ছড়াতে পারে, সেগুলো উল্লেখ করুন। Database schema। Customers ইতিমধ্যে যে public route prefix-এর বিরুদ্ধে script চালায়। Application start হওয়ার আগে deploy যে config file পড়ে। যে cron entry ধরে নেয় এর মাত্র একটি copy চলছে। এগুলোর নাম লিখুন এবং প্রতিটিতে পরিবর্তন করলে কী খরচ হয়, তা জানান। Agent যদি open web-এও পৌঁছাতে পারে, যেমন search backend হিসেবে সংযুক্ত একটি self-hosted SearXNG instance ব্যবহার করে, সেটিও একটি boundary হিসেবে লিখে রাখা উচিত। কারণ ফাইলে উল্লেখ থাকা দরকার, 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, সেগুলো পূরণ করুন। বাকি অংশ শুধু heading হিসেবে রাখুন। চারটি সৎ লাইন থাকা একটি ফাইল কার্যকর। অনুমান করে লেখা চল্লিশটি লাইন কার্যকর নয়।

কিছু tool repository root-এর প্রতিটি markdown file লোড করে, আবার কিছু tool শুধু নির্দিষ্ট করে দেওয়া file লোড করে। তাই ধরে নেবেন না। AGENTS.md-এর দিকে নির্দেশনা যোগ করুন:

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

যে anti-pattern এড়াতে হবে: README-এর পুনরাবৃত্তি করা একটি DESIGN.md

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

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

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

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

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

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

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

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

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

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

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

FAQ

DESIGN.md কি একটি আনুষ্ঠানিক standard?

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

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

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

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

ADR (architecture decision record) হলো একটি decision-এর তারিখসহ record, এবং একটি সুস্থ project-এর folder-এ এমন কয়েক ডজন record জমা হয়। এটি একটি history, আর history load করা ব্যয়বহুল, কারণ কোন সিদ্ধান্তগুলো এখনও প্রযোজ্য তা বোঝার জন্য 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 এমন ভুল করলে, যা একটি মাত্র sentence লিখলে ঠেকানো যেত, কেবল তখনই এটি বড় করুন। Length কোনো মাপকাঠি নয়। প্রতিটি line এমন একটি বিষয় হওয়া উচিত, যা না লিখলে agent অন্যথায় ভুল করত।