DESIGN.md: AGENTS.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 উভয় ক্ষেত্রেই pass করে। যে rule ভঙ্গ হয়েছে, তা agent পড়তে পারে এমন কোথাও লেখা ছিল না।

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

একটি প্রকাশিত 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-টি সংজ্ঞায়িত করে। এটি হলো একটি 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 তৈরি করানো যায়। এই file-গুলো উপকারী, তবে এগুলো এখনও অনুমানভিত্তিক। পর্যালোচনা করা কোম্পানিগুলোর কেউই এগুলো যাচাই করেনি।

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

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

ইউজার ইন্টারফেস না থাকলে 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 শুরু হওয়ার আগে deploy যে config file পড়ে। এমন cron entry, যা ধরে নেয় যে এর কেবল একটি copy চলছে। এগুলোর নাম লিখুন এবং প্রতিটির পরিবর্তনের খরচ কী, তা উল্লেখ করুন।

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 হিসেবে রাখুন। চারটি সঠিক লাইন থাকা একটি file কার্যকর। অনুমান করে লেখা চল্লিশটি লাইন কার্যকর নয়।

কিছু tool repository root-এর প্রতিটি markdown file load করে, আবার কিছু tool শুধু নির্দিষ্ট করে দেওয়া file 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-এ তার জন্য খরচ হয়; আর একই install section আবার লেখা একটি নির্দিষ্ট window-এর মধ্যে সম্পূর্ণ অপ্রয়োজনীয় overhead। সেই window-এর budget নির্ধারণ করাও নিজস্ব একটি দক্ষতা, যা Claude Code-এ context window পরিচালনা করা অংশে ব্যাখ্যা করা হয়েছে। সংক্ষেপে: যেকোনো text স্বয়ংক্রিয়ভাবে load হলে সেটিই repository-এর সর্বোচ্চ মূল্যবান text হওয়া উচিত।

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

পরীক্ষাটি দ্রুত করা যায়। কোনো 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 রয়েছে যা agent আগেই জানত। Claude Code-এ token counter পড়া দেখায়, সেই budget কোথায় ব্যবহার হচ্ছে।

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

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

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

FAQ

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

AGENTS.md যেভাবে একটি আনুষ্ঠানিক standard, DESIGN.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-এ একটি করে ফাইল প্রকাশ করে, এবং একটি community collection-এ public site থেকে reverse-engineer করা আরও 73টি ফাইল রয়েছে। এটিকে এখনই গ্রহণযোগ্য একটি convention হিসেবে ব্যবহার করুন এবং প্রয়োজনে স্বাধীনভাবে সম্প্রসারণ করুন, কারণ আপনার section name যাচাই করার কোনো ব্যবস্থা নেই।

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-এর সব markdown file load করে না।

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

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