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 প্রকাশ করে, সেগুলো পড়া। repository official-design-md শুধু সেই 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.

October 2026 অনুযায়ী এতে এগারোটি নাম আছে: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel এবং VoltAgent। প্রতিটি file একটি public URL-এ থাকে। বেশির ভাগ publisher-এর নিজস্ব domain-এ, আর বাকিগুলো public GitHub repository-তে থাকে। তাই এখনই terminal থেকে একটি পড়তে পারেন।

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। বিষয়বস্তুর মধ্যে আটকে থাকবেন না। লেখার বিষয়ের চেয়ে এর গঠনই বেশি গুরুত্বপূর্ণ।

October 27, 2026 অনুযায়ী Nuxt file-এ প্রায় 2,000 শব্দ আছে, এবং এর বেশির ভাগ অংশে কারণসহ একটি করে rule দেওয়া হয়েছে। শুরুতেই বলা হয়েছে যে dark mode হলো default theme। এতে brand green #00DC82 দেওয়া হয়েছে এবং একটি note-এ বলা হয়েছে, brand colour-গুলো হলো "For logos, social images, and print. Do not use them as raw values in UI code." শেষের দিকে Reject these শিরোনামের একটি section-এ রয়েছে:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Vercel file-টি আরও বড়। October 2026 অনুযায়ী এতে প্রায় 6,000 শব্দ আছে, এবং এটি আরও এক ধাপ এগিয়ে যায়। এর একটি heading হলো Reject generated-design reflexes। এর নিচে এমন জিনিসগুলোর একটি list আছে, যেগুলো কাউকে নিষেধ না করলে একটি সক্ষম 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 তৈরি করে, তার লিখিত list; model যেন সেগুলো তৈরি করা বন্ধ করে, সেই উদ্দেশ্যে list-টি প্রকাশ করা হয়। commit করার মতো প্রতিটি DESIGN.md কোনো না কোনো domain-এর জন্য সেই list।

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

কমিউনিটি আগে এই কাজ শুরু করেছে। awesome-design-md-এর README-তে 2026 সালের October 27 তারিখে দেওয়া হিসাব অনুযায়ী, এতে public website থেকে সংগৃহীত 84টি file আছে। প্রতিটি file একই নয়-টি section-এর format অনুসরণ করে লেখা। ফলে কোনো agent-কে একটি file দেখিয়ে কাছাকাছি ধরনের design তৈরি করানো যায়। এই file-গুলো উপকারী, তবে এগুলো এখনো অনুমানভিত্তিক। পর্যালোচনা করা কোম্পানিগুলোর কেউ এগুলো যাচাই করেনি।

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

Elevenটি publisher এখনো অল্পসংখ্যক। Repository-ও তা স্বীকার করে: standard-টি নতুন, এবং official adoption বাড়ছে। উভয় collection-ই VoltAgent রক্ষণাবেক্ষণ করে। VoltAgent একটি open source agent framework, যা নিজের file-ও প্রকাশ করে। তাই এই তালিকাকে নিরপেক্ষ census নয়, tracker হিসেবে পড়ুন। তবু তালিকাটি নজরে রাখা মূল্যবান, কারণ এতে কারা আছে। এগুলোর কয়েকটি এমন কোম্পানি, যাদের front-end code অন্য developer-রা সবচেয়ে বেশি copy করে। নতুন entry-গুলো—Ant Design, Microsoft FAST, Juspay এবং Oxide Computer—এমন design system, যার ওপর অন্য team-গুলো তাদের কাজ তৈরি করে। তাদের file-গুলো DESIGN.md কী হতে পারে, তার ব্যবহারিক উদাহরণ হয়ে উঠছে।

AGENTS.md যে পথ নিয়েছে, তা তুলনা করুন: agents.md-এ এখন format-টি ব্যবহার করা 60,000-এর বেশি open source project গণনা করা হয়, এবং এর stewardship Linux Foundation-এর অধীন Agentic AI Foundation-এর কাছে রয়েছে। DESIGN.md একই পথে এগোতে শুরু করেছে। 2026 সালের April 21 তারিখে Google format-টির একটি draft specification open source করে। এটি google-labs-code/design.md হিসেবে প্রকাশিত হয়েছে। এতে token schema এবং Apache-2.0 licence-এর অধীনে একটি CLI রয়েছে। October 2026 পর্যন্ত format-টি alpha version-এ রয়েছে এবং সক্রিয়ভাবে উন্নয়নাধীন। এটি কোনো neutral foundation নয়, Google Labs রক্ষণাবেক্ষণ করে। Format-টি visual identity বর্ণনা করে, তাই backend file-এর প্রয়োজনীয় invariants সম্পর্কে এতে কিছু বলা নেই। Agent-readable file-এর conventions দ্রুত নির্ধারিত হচ্ছে, এবং সেগুলো উপর থেকে নির্ধারিত হচ্ছে।

ইউজার ইন্টারফেস না থাকলে 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-এর অধীনে এটি পরিচালিত হয়। DESIGN.md-এর একটি published specification আছে, কিন্তু কোনো নিরপেক্ষ steward নেই। Google April 21, 2026-এ একটি draft spec open source করেছে, এবং এটি Apache-2.0 licence-এর অধীনে google-labs-code/design.md repository-তে রয়েছে। October 2026 অনুযায়ী এটি alpha version-এ আছে এবং active development চলছে। এতে visual identity বর্ণনা করা হয়েছে: colours, typography, layout এবং components। DESIGN.md-এর first-party adoption-ও আছে: Vercel, Nuxt, Atlassian এবং Resend-সহ 11টি company ও project এটি publish করে। October 27, 2026 অনুযায়ী একটি community collection-এ public site থেকে সংগৃহীত আরও 84টি DESIGN.md ছিল। Backend file-এ invariants এবং rejected alternatives রাখার ক্ষেত্রে এটিকে এমন একটি convention হিসেবে বিবেচনা করুন যা এখনই গ্রহণ করে স্বাধীনভাবে বাড়ানো যায়, কারণ কোনো specification ওই section name-গুলো নির্ধারণ করে না।

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

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

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

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

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

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