চিট শিট

Agent harness-এর চিট শিট: উপাদান, ফাইল, সমস্যা ও চালুর চেকলিস্ট

হালনাগাদ: · Skillaria.Top

Agent harness পাঁচটি উপাদানে গঠিত: নির্দেশনা, টুল, পরিবেশ, অবস্থা ও প্রতিক্রিয়া। ন্যূনতম ফাইল সেট: AGENTS.md ছোট রাউটার হিসেবে, যাচাই-স্ক্রিপ্ট (make check, verify.sh), অগ্রগতির ফাইল, এবং অবস্থাসহ ফিচার তালিকা; সম্পন্নতার স্ট্যাটাস দেয় স্ক্রিপ্ট, এজেন্ট নয়।

Agent harness-এর পাঁচটি উপাদান

উপাদানকীউপকরণভাঙনের লক্ষণ
নির্দেশনাপ্রকল্প সম্পর্কে এজেন্টের যা জানা দরকারAGENTS.md / CLAUDE.md, skills, docs/, ADRপরিচিত কনভেনশন লঙ্ঘন
টুলএজেন্ট কী করতে পারেshell, test, linter, browser, MCP সার্ভার«চায়, কিন্তু পারে না»
পরিবেশএজেন্ট কোথায় কাজ করেlock ফাইল, Docker/devcontainer, git worktree, sandbox, init.shপ্রতিটি সেশন পরিবেশ ঠিক করে শুরু হয়
অবস্থাপুনরায় চালুর পরও যা টিকে থাকেPROGRESS.md, DECISIONS.md, feature_list.json, commitনতুন সেশন জানে না কাজ কোথায় থামল
প্রতিক্রিয়াএজেন্ট কীভাবে নিজের ভুল জানেmake check, E2E, hook, arch-check, মূল্যায়নকারী«সম্পন্ন», কিন্তু কাজ করে না

শূন্য থেকে গড়ার ক্রম: প্রতিক্রিয়া → নির্দেশনা → অবস্থা → পরিবেশ → টুল।

Harness-এর ফাইল

ফাইলকাজনিয়ম
AGENTS.md / CLAUDE.mdপ্রবেশপথ: প্রকল্প কী, কীভাবে চালাতে হয়, কীভাবে যাচাই হয়ছোট রাউটার (প্রায় ৮০ লাইন), «কখন পড়বে» শর্তসহ নথির লিংক
docs/*.mdবিষয়ভিত্তিক বিস্তারিতপ্রয়োজনমতো পড়া হয়, পুরোটা নয়
.claude/skills/*/SKILL.mdপুনরাবৃত্ত প্রক্রিয়া (deploy, review)কাজ বর্ণনার সঙ্গে মিললে লোড হয়
PROGRESS.mdঅবস্থা, সম্পন্ন কাজ, বাধা, পরের ধাপপ্রতিটি সেশনের শেষে হালনাগাদ
DECISIONS.mdসিদ্ধান্ত, কারণ, বাতিল বিকল্পশুধু ফল নয়, পথটিও লিখুন
feature_list.jsonফিচার: behavior, verification, stateঠিক একটি ফিচার active (WIP=1)
scripts/verify.shফিচার যাচাই ও passing-এ নেওয়াএকমাত্র যে passing ঠিক করে, SHA সহ
scripts/arch-check.shস্থাপত্যের সীমানাকোড 1 + আউটপুটে WHY ও FIX
scripts/init.shকাজের আগে পরিবেশ যাচাইপরিবেশ, পরিষ্কার git, সবুজ make check, সক্রিয় ফিচার
sprint contractকোডের আগে প্রতি ফিচারের চুক্তিপরিধির ভেতরে / বাইরে / খোলা প্রশ্ন
.claude/settings.jsonClaude Code-এর অনুমতি ও hookঘটনায় যাচাই, এজেন্টের স্মৃতিতে নয়

AGENTS.md-এর কাঠামো

# প্রকল্প: payment backend (FastAPI, PostgreSQL)

## চালানো
docker compose up -d && ./scripts/init.sh

## যাচাই
make check   # lint, type, unit, arch-check
make e2e     # end-to-end পরিস্থিতি

## Definition of Done
- make check ও make e2e — কোড 0
- scripts/verify.sh স্ক্রিপ্ট দিয়ে ফিচার passing-এ নেওয়া
- PROGRESS.md হালনাগাদ

## MUST
- database-এ কুয়েরি শুধু repository-র মাধ্যমে
- secret শুধু environment variable থেকে

## নথি
- docs/payments.md — কাজ পেমেন্ট ও refund ছুলে
- docs/migrations.md — database schema বদলালে

ফিচারের অবস্থা

অবস্থাঅর্থকে বদলায়
pendingসারিতে আছেপরিকল্পনাকারী
activeকাজ চলছে (একটিই)এজেন্ট, শুরুতে
passingযাচাই পাসশুধু verify.sh
blockedমানুষের সিদ্ধান্ত দরকারএজেন্ট, কারণসহ

যাচাইয়ের স্তর

স্তরকীকখন
1Lint, typeসবসময়
2Unit ও integration testসবসময়
3E2Eএকাধিক স্তর ছুঁলে; «সম্পন্ন» বলার আগে
4arch-checkনতুন স্তর-অতিক্রমী আমদানি

«সম্পন্ন» বলার অধিকার শুধু সর্বোচ্চ স্তরের পরে। সবুজ unit test মানে প্রস্তুতি নয়।

নিয়ম যান্ত্রিক করা

স্তরটুলখরচ
Guard grepWHY/FIX বার্তাসহ প্যাটার্ন খোঁজার স্ক্রিপ্টমিনিট
Linter নিয়মimport-linter (Python), dependency-cruiser, eslint-plugin-boundaries (JS/TS)এক ঘণ্টা
Architecture testCI-এর test, স্তর ভাঙলে ব্যর্থবেশি, কিন্তু make check-এ দৃশ্যমান
 
#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: service সরাসরি database স্পর্শ করবে না"
  echo "FIX: app/repositories/ থেকে repository ব্যবহার করুন"
  fail=1
fi
exit $fail

সাধারণ সমস্যা ও সমাধান

সমস্যাউপাদানসমাধান
CLAUDE.md-এর নিয়ম মানা হচ্ছে নানির্দেশনাফাইল ছোট করুন, নিয়মকে যাচাই বা hook বানান
এজেন্ট test চালাতে পারছে নাটুলকমান্ডটি অনুমতি দিন, image-এ dependency ইনস্টল করুন
প্রতিটি মেশিনে আচরণ আলাদাপরিবেশlock ফাইল, Docker/devcontainer, নির্দিষ্ট runtime সংস্করণ
সেশনের মধ্যে বিস্মৃতিঅবস্থাPROGRESS.md, সেশন হস্তান্তর, শুরুতে পড়া
তিনটি ফিচার শুরু, একটিও শেষ নয়অবস্থাfeature_list.json-এ WIP=1
«সম্পন্ন», কিন্তু কাজ করে নাপ্রতিক্রিয়াDoD, E2E, verify.sh, স্বাধীন মূল্যায়নকারী
Test সবুজ, ফিচার ভাঙাপ্রতিক্রিয়াআসল database ও কনফিগারেশনসহ E2E
এজেন্ট খারাপ প্যাটার্ন নকল করছেপ্রতিক্রিয়াপ্রথম দিন থেকে arch-check
এজেন্ট কী করেছে বোঝা যাচ্ছে নাঅবস্থাছোট commit, PROGRESS.md-এ প্রতিবেদন, DECISIONS.md
এজেন্ট রাতারাতি পরিবেশ ভেঙেছেপরিবেশSandbox, git worktree, চেকপয়েন্ট, init.sh দিয়ে rollback
একই রিভিউ-মন্তব্য দুইবারসামগ্রিক harnessmake check-এ যাচাই বানান, নির্দেশনা থেকে লেখা সরান

দীর্ঘ কাজের ভূমিকা

ভূমিকাকরেকরে না
পরিকল্পনাকারীগ্রহণযোগ্যতার মানদণ্ডসহ ফিচারকোড লেখে না
জেনারেটরএকটি ফিচার বাস্তবায়ন, test চালায়সম্পন্ন কি না ঠিক করে না
মূল্যায়নকারীরুব্রিক ধরে রায়, ফাইল/লাইন/লগের উল্লেখসহজেনারেটরের যুক্তি দেখে না
Mergereview == pass হলে commitএটি কোড, এজেন্ট নয়

স্বয়ংক্রিয় কাজের বাজেট

  • লক্ষ্য — এক বাক্য (যেমন সব ফিচার passing-এ নেওয়া)।
  • WIP=1, প্রতি ফিচারে সময় ও চেষ্টার সীমা।
  • মেট্রিক একমুখী বাড়ে; রিগ্রেশন মানে তৎক্ষণাৎ rollback।
  • Migration, অবকাঠামো, টাকা — মানুষের কাছে এসকেলেশন।
  • কয়েকবার review ব্যর্থ হলে ফিচার পরিষ্কার প্রসঙ্গে শুরু।

এজেন্ট চালুর চেকলিস্ট

  1. AGENTS.md আছে: stack, চালানোর উপায়, যাচাই-কমান্ড, DoD।
  2. পরিষ্কার ক্লোনে make check পাস করে।
  3. পরিবেশ পুনরুৎপাদনযোগ্য: lock ফাইল, Docker বা devcontainer।
  4. দরকারি কমান্ড এজেন্টের কাছে আছে; বিপজ্জনকগুলো নিষিদ্ধ বা sandbox-এ।
  5. মূল স্কেনারিওর জন্য অন্তত একটি E2E আছে।
  6. PROGRESS.md আছে এবং সেশনের শুরুতে পড়ার নিয়ম।
  7. ফিচার তালিকায় অবস্থাসহ, একটিমাত্র সক্রিয়।
  8. Passing স্ট্যাটাস দেয় স্ক্রিপ্ট।
  9. যাচাই-বার্তায় WHY ও FIX আছে।
  10. কাজটি গ্রহণযোগ্যতার মানদণ্ড ও পরিধির সীমাসহ লেখা।
  11. কোন বিষয়ে মানুষের সিদ্ধান্ত লাগবে তা ঠিক করা।
  12. পরিবর্তনের আগে verification gap মাপা, তুলনার জন্য।

Harness-এর মেট্রিক

মেট্রিককীভাবে হিসাব
Verification gap১০টি কাজে «সম্পন্ন» কিন্তু যাচাই-নিশ্চিত নয় এমনের অনুপাত
MTTRভাঙন থেকে কাজের অবস্থায় ফেরা পর্যন্ত সময়
Cold startনতুন সেশন «আমরা কোথায়, পরে কী» প্রশ্নের আন্দাজ ছাড়া উত্তর দিতে পারে কি না
Ablationস্থির কাজের সেটে একটি উপাদান বন্ধ করলে মানের পতন

সারসংক্ষেপ

Harness একটি চক্র, একটি ফাইল নয়: নির্দেশনা, টুল, পরিবেশ, অবস্থা ও প্রতিক্রিয়া। যাচাই দিয়ে শুরু করুন, AGENTS.md ছোট রাখুন, সম্পন্নতার স্ট্যাটাস স্ক্রিপ্টকে দিন, এবং harness নিয়মিত পর্যালোচনা করুন। এই সবকিছু কোর্সের একটি প্রকল্পে একটি পূর্ণ সমন্বয়ে আসে।

সাধারণ প্রশ্ন

AGENTS.md আর CLAUDE.md-এর পার্থক্য কী?

উদ্দেশ্যে একই: এজেন্টের নির্দেশনার ফাইল। CLAUDE.md-কে Claude Code পড়ে, AGENTS.md একাধিক এজেন্টের সাধারণ ফরম্যাট; CLAUDE.md-এ শুধু AGENTS.md-এর উল্লেখ করা যায়।

AGENTS.md-এ কত লাইন থাকা উচিত?

কঠোর সীমা নেই, তবে প্রবেশ-ফাইল ছোট রাখা ভালো — প্রায় একশো লাইন, সূচির মতো। বিস্তারিত আলাদা নথিতে যায়।

ছোট প্রকল্পে feature_list.json কি লাগে?

একবারের ছোট পরিবর্তনে লাগে না। এজেন্ট একাধিক ফিচার পরপর বা একাধিক সেশনে কাজ করলে এর মূল্য হয়।

এজেন্টের যেসব গোপন তথ্য দরকার, সেগুলো কোথায় রাখব?

Environment variable বা secret manager-এ, নির্দেশনার ফাইল বা কোডে নয়। এজেন্টকে পরিবেশে প্রবেশাধিকার দিন, লেখায় থাকা মানে নয়।

ভিডিওতে বিষয়টি শিখুন

“Harness Engineering: инженерия надёжности AI-агентов” কোর্সে বিষয়টি অনুশীলনসহ বিস্তারিত শেখানো হয়েছে।

কোর্সে যান