एजेंट ने "तैयार" लिखा, पर फ़ीचर काम नहीं करता: AI एजेंट का काम कैसे जाँचें

ऐसा क्यों होता है

यह स्थिति एजेंट के साथ काम करने वाले हर व्यक्ति के लिए जानी-पहचानी है: एजेंट ने "तैयार" लिखा, पर फ़ीचर काम नहीं करता। वह जानबूझकर झूठ नहीं बोलता। वह वही बताता है जो उसने ख़ुद जाँचा, और ईमानदारी से मानता है कि यह काफ़ी है। बयान और वास्तविकता के बीच का अंतर इस योजना की ख़ासियत है कि "निष्पादक ख़ुद अपना काम आँकता है", न कि किसी ख़ास मॉडल का दोष।

तीन कारण हैं। पहला: मॉडल आत्मविश्वास में अधिक होते हैं, यानी उनके जवाब की निश्चितता उसकी सटीकता से ज़्यादा होती है। दूसरा: एजेंट अपना काम उसी context में आँकता है जिसमें उसने उसे किया। वह पहले ही मान चुका है कि समाधान सही है, और "ज़्यादा निष्पक्ष रहो" कहने से context नहीं बदलता। तीसरा और सबसे व्यावहारिक: एजेंट के पास केवल आंशिक जाँच उपलब्ध है। Unit tests जल्दी हरे हो जाते हैं, जबकि end-to-end परिदृश्य किसी ने चलाया ही नहीं।

एक झूठे "तैयार" का इतिहास

एजेंट को पासवर्ड रीसेट का काम दिया गया। उसने database schema बदला, एक endpoint जोड़ा, ईमेल template लगाया, unit tests चलाए, सब हरा। चैट में आत्मविश्वास से लिखा गया "तैयार"।

असल में:

• migration बीच में गिर गया और schema असंगत स्थिति में छूट गया;
• ईमेल template है, पर mail सर्वर (SMTP) वातावरण में कॉन्फ़िगर नहीं है, इसलिए मेल नहीं जाता;
• परिदृश्य "उपयोगकर्ता लिंक दबाता है → नया पासवर्ड डालता है → लॉग इन करता है" एक बार भी नहीं चला।

इनमें से कोई समस्या unit tests नहीं पकड़ सकते थे: database को mock किया गया था, मेल भेजना mock किया गया था, और सिरे-से-सिरे की कोई जाँच हुई ही नहीं।

हरे टेस्ट यह क्यों साबित नहीं करते कि फ़ीचर काम करता है

Unit test एक module को अलग करके जाँचता है: निर्भरताएँ mock होती हैं, बाहरी दुनिया बंद होती है। इससे गति और सटीकता मिलती है, पर एक व्यवस्थित अंधापन भी आता है। यह अंधापन टेस्ट की गलती नहीं, उनके डिज़ाइन में है। हरे unit tests केवल यह साबित करते हैं कि हर हिस्सा अलग से काम करता है, न कि यह कि हिस्से एक साथ काम करते हैं।

चार तरह की खामियाँ unit test कभी नहीं देख सकता:

जाँच के स्तर एक-दूसरे में समाए हैं: जो unit tests पकड़ते हैं, उसे integration tests भी पकड़ते हैं, और जो integration tests पकड़ते हैं, उसे सिरे-से-सिरे (E2E) चलाना भी पकड़ता है। हर अगला स्तर ठीक एक-दूसरे से ज़्यादा देखता है। इसलिए "तैयार" कहने का अधिकार केवल सबसे ऊपर के स्तर को होना चाहिए।

verification gap कैसे मापें

सुधारने से पहले गिनें। एजेंट द्वारा बंद किए गए आख़िरी 10 कामों को लें। हर एक पर दो सवालों के जवाब दें: क्या एजेंट ने "तैयार" कहा था, और क्या स्वतंत्र जाँच ने इसकी पुष्टि की (आपने ख़ुद परिदृश्य चलाया, E2E टेस्ट हरा है)? इन दोनों के बीच के बेमेल का अनुपात आपका verification gap है।

यह संख्या दो कारणों से उपयोगी है। यह समस्या का पैमाना दिखाती है, "हाँ ठीक चल रहा है लगता है" जैसी बहस के बिना। और यह एक आधार-रेखा देती है: हर बदलाव के बाद मिलते-जुलते कामों पर इसे दोबारा गिनें और देखें कि असर हुआ या नहीं।

असल में कैसे जाँचें: तीन स्तर का सत्यापन

एक सुविधाजनक तुलना: कार गाड़ी-मरम्मत की दुकान की तीन चौकियों से गुज़रती है, और कोई चौकी छोड़ी नहीं जा सकती।

1. डायग्नोस्टिक्स (सेकंड): syntax, types, linter। टाइपो और मोटी गलतियाँ पकड़ता है।
2. स्टैंड (मिनट): unit और integration tests, एप्लिकेशन शुरू होता है। इंजन चल रहा है, पर गाड़ी अभी भी खड़ी है।
3. टेस्ट-ड्राइव: सिरे-से-सिरे परिदृश्य, जैसे उपयोगकर्ता उसे चलाता है: API, browser या CLI के ज़रिए, असली database और configuration के साथ।

प्रगति का नियम: जब तक डायग्नोस्टिक्स में गलतियाँ हों, टेस्ट-ड्राइव पर न जाएँ, और टेस्ट-ड्राइव पास किए बिना गाड़ी न छोड़ें। हरे unit tests दूसरी चौकी पास करना हैं, तीसरी नहीं।

सब कुछ एक प्रवेश बिंदु में समेटना सुविधाजनक है:

# Makefile
check:
	ruff check .
	mypy app
	pytest tests/unit tests/integration

e2e:
	docker compose up -d db mailhog
	alembic upgrade head
	pytest tests/e2e

verify: check e2e

यहाँ E2E असली database और परीक्षण मेल सर्वर चढ़ाता है, migrations लागू करता है और परिदृश्य पूरा चलाता है। टूटी migration या बिना कॉन्फ़िगर की मेल तुरंत दिखती है, ग्राहक के पास नहीं।

AGENTS.md में Definition of Done

एजेंट को यह तय नहीं करना चाहिए कि "तैयार" का मतलब क्या है। मानदंड निर्देश फ़ाइल में लिखा जाए और जाँचा जा सकने वाला हो:

## Definition of Done
फ़ीचर तभी तैयार है, जब सभी बिंदु पूरे हों:
1. make check कोड 0 पर पूरा हुआ
2. make e2e कोड 0 पर पूरा हुआ, फ़ीचर का परिदृश्य tests/e2e में है
3. Migrations खाली database पर लागू होते हैं और वापस भी होते हैं
4. नए environment variables .env.example में दर्ज हैं
5. PROGRESS.md में लिखा है कि क्या किया और कैसे जाँचा

तैयारी का संकेत नहीं हैं:
- "कोड लिखा है और सही दिखता है"
- "unit tests पास हो रहे हैं"
- "मेरे पास लोकल पर चल रहा है"

स्पष्ट सूची कि क्या तैयारी नहीं है, उम्मीद से बेहतर काम करती है: एजेंट पहले हरे रन पर रुकना बंद कर देता है।

passing का निशान कौन लगाए

अगला कदम है तैयारी का निशान एजेंट के हाथ से पूरी तरह हटाना। फ़ीचर एक सूची में रहते हैं (जैसे feature_list.json), जिसमें फ़ील्ड होते हैं: "व्यवहार", "जाँच की कमांड", "स्थिति"। फ़ीचर को passing में केवल स्क्रिप्ट बदल सकती है: वह सामान्य make check चलाती है, फिर उस फ़ीचर की जाँच की कमांड, और सफल होने पर स्थिति को commit hash के साथ सबूत के तौर पर दर्ज करती है। पास न हो, तो फ़ीचर सक्रिय रहता है, "लगभग हो गया" कुछ नहीं होता।

{
  "id": "F04",
  "behavior": "उपयोगकर्ता को लिंक वाला ईमेल मिलता है और वह पासवर्ड बदलता है",
  "verification": "pytest tests/e2e/test_password_reset.py",
  "state": "active"
}

यहाँ एक जाल है: स्क्रिप्ट ठीक वही जाँचती है जो verification फ़ील्ड में लिखा है। अगर कोई आर्किटेक्चर-जाँच Definition of Done में है, पर फ़ीचर की कमांड में नहीं, तो वह खामी अदृश्य रहेगी। इसलिए सामान्य make check में सभी अनिवार्य जाँचें शामिल हों, केवल tests नहीं।

स्वतंत्र मूल्यांकक

निष्पादक की ख़ुद की रिपोर्ट कभी स्वतंत्र सच्चाई का स्रोत नहीं होती। समाधान है भूमिकाएँ अलग करना:

• योजनाकार आवश्यकता को स्वीकृति-मानदंड वाले फ़ीचरों में बदलता है और कोड नहीं लिखता;
• जनरेटर एक फ़ीचर लागू करता है और टेस्ट चलाता है, पर तय नहीं करता कि काम तैयार है;
• मूल्यांकक चेकलिस्ट के मानदंडों पर फ़ैसला सुनाता है।

मूल्यांकक जनरेटर का तर्क नहीं देखता, वरना वह उसका आत्मविश्वास विरासत में ले लेगा। उसे केवल आवश्यकता, diff और जाँच के परिणाम मिलते हैं। Claude Code में यह आसानी से subagent के रूप में होता है, जिसका अपना साफ़ context होता है। और बेहतर यह है कि मूल्यांकक दूसरा मॉडल हो, क्योंकि उसकी अंधी जगहें अलग होती हैं। "ठीक लगता है" वाला आकलन मना है: हर निष्कर्ष फ़ाइल, पंक्ति या लॉग का हवाला दे।

ऐसे संदेश जिन्हें एजेंट ख़ुद ठीक कर सके

जाँच तभी उपयोगी है जब उसका संदेश सुधार की ओर ले जाए। "Test failed" या केवल AssertionError एजेंट को कुछ नहीं बताता। अच्छे संदेश में होता है: क्या टूटा, नियम क्यों है, और कैसे ठीक करें।

ERROR arch-check: app/services/refund.py, app/db/session.py को import करता है
WHY: services database से सीधे बात नहीं करते, केवल repositories के ज़रिए
FIX: app/repositories/refund.py का RefundRepository उपयोग करें

ऐसा फ़ॉर्मेट जाँच को मनाही से सुझाव में बदल देता है: एजेंट आपकी मदद के बिना उल्लंघन ठीक कर लेता है।

हाथ से जाँच अब भी कहाँ ज़रूरी है

स्वचालन इंसान को नहीं हटाता, केवल उसकी भूमिका सीमित करता है। हाथ से जाँच वहाँ चाहिए जहाँ मानदंड को औपचारिक बनाना कठिन है: इंटरफ़ेस का रूप, शब्द, परिदृश्य की सुविधा। इसे चेकलिस्ट के स्वीकृति-मानदंडों से करें, न कि "बस थोड़ा क्लिक करके देखना"। अगर आप एक ही टिप्पणी एजेंट को दूसरी बार लिख रहे हैं, तो यह संकेत है कि उसे स्वचालित जाँच बना दें: टेस्ट, linter नियम, या make check में grep-guard।

E2E एजेंट का व्यवहार पहले से बदल देता है

सिरे-से-सिरे टेस्ट की कीमत केवल पकड़े गए बग में नहीं। अगर एजेंट को पता है कि उसका काम E2E परिदृश्य जाँचेगा, तो वह अलग तरीक़े से कोड लिखता है: पड़ोसी घटक के साथ अनुबंध पर सोचता है, न कि सिर्फ़ अपने फ़ंक्शन पर, त्रुटि के रास्तों को संभालता है, और आर्किटेक्चर की सीमाएँ नहीं तोड़ता, क्योंकि उनका उल्लंघन रन में सामने आएगा। जाँच इनपुट पर सीमा की तरह काम करती है, केवल आउटपुट पर फ़िल्टर की तरह नहीं।

एक शर्त है: E2E तभी सार्थक है जब प्रणाली की सीमाएँ साफ़ हों। स्पैगेटी आर्किटेक्चर पर सिरे-से-सिरे टेस्ट सिर्फ़ यह साबित करेगा कि स्पैगेटी चलती है, और यह नहीं बताएगा कि योजना कहाँ टूटी। इसलिए पहले परतें और निर्भरता के नियम तय करें, फिर सिरे-से-सिरे परिदृश्य बनाएँ। एजेंट रिपॉज़िटरी के मौजूदा पैटर्न आसानी से कॉपी करते हैं, अच्छे और बुरे दोनों, इसलिए सीमाएँ पहले ही दिन लगाएँ।

आम गलतियाँ

• एजेंट से "और ध्यान से जाँचो" कहना। Context वही है, आकलन फिर भी बढ़ा-चढ़ा रहेगा।
• 100% coverage को गारंटी मानना। Unit coverage जोड़ों को नहीं ढकता।
• फ़ीचर की पुष्टि से पहले refactoring करना। क्रम सख़्त है: सही होना → तेज़ होना → सुंदर होना।
• E2E में वही mock करना जो सबसे ज़्यादा टूटता है। Database, migrations और configuration सिरे-से-सिरे टेस्ट में असली चलने चाहिए; बाहरी पेड API को परीक्षण सर्वर से बदलना ठीक है।

निष्कर्ष

जब एजेंट "तैयार" लिखे और फ़ीचर काम न करे, तो समस्या लगभग हमेशा जाँच की प्रक्रिया में होती है, मॉडल में नहीं। verification gap गिनें, AGENTS.md में Definition of Done लिखें, E2E को अनिवार्य बनाएँ, तैयारी का निशान स्क्रिप्ट को दें, और स्वतंत्र मूल्यांकक जोड़ें। यह योजना एक व्यावहारिक पाठ्यक्रम में, असली परियोजना पर, विस्तार से दिखाई गई है।