AI एजेंटों के लिए अच्छा स्पेक कैसे लिखें

• अगर AI coding agent को एक ही बार में बहुत बड़ा spec दे दिया जाए, तो वह ठीक से काम नहीं करता; असली बात smart spec writing में है
• पहले high-level vision दें और AI को detailed plan विस्तार करने दें, फिर Plan Mode में read-only रूप से plan की समीक्षा करके code writing चरण में जाने का तरीका सुझाया गया है
• GitHub के 2,500 से अधिक agent configuration files के विश्लेषण से पता चला कि प्रभावी spec में 6 मुख्य क्षेत्र शामिल होते हैं: Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries
• बड़े काम को एक विशाल prompt की बजाय modular छोटे tasks में बाँटना चाहिए, और हर task के लिए केवल वही context देना चाहिए जो उसके लिए ज़रूरी हो, ताकि quality गिरने से बचा जा सके
• spec में 3-स्तरीय boundaries (Always/Ask first/Never), self-verification, और suitability tests को शामिल करना, और उसे लगातार test, iterate, और evolve करना ही spec-driven development workflow का केंद्र है

---

TL;DR

• उचित स्तर की detail (structure, style, testing, boundaries आदि) के साथ स्पष्ट specification लिखें
• बड़े कामों को एक बड़े prompt की बजाय छोटी इकाइयों में विभाजित करने का तरीका सुझाया गया है
• plan को पहले read-only mode में बनाएं, फिर execute करें और लगातार सुधारें

मुख्य सिद्धांत: smart spec लिखना

• सिर्फ बहुत बड़ा spec AI agent को दे देने का तरीका अक्सर विफल होता है, क्योंकि यह context window की सीमा और model के attention budget से टकराता है
• “smart spec” ऐसा दस्तावेज़ है जो agent को स्पष्ट दिशा देता है, practical context size के भीतर रहता है, और project के साथ-साथ evolve होता है
• Claude Code, Gemini CLI जैसे coding agents के उपयोग के अनुभव से निकाले गए सिद्धांतों को framework के रूप में व्यवस्थित किया गया है

सिद्धांत 1: पहले बड़ा चित्र दें, details का draft AI से बनवाएं

• शुरुआत में हर चीज़ को ज़रूरत से ज़्यादा design करने की कोशिश करने के बजाय, पहले goal statement और कुछ मुख्य requirements को स्पष्ट करें
• इस शुरुआती spec को “product brief” की तरह रखें, और agent को इसके आधार पर detailed spec को विस्तार से लिखने दें
• LLM-आधारित agents तब details अच्छी तरह भरते हैं जब high-level निर्देश साफ हों, लेकिन mission अस्पष्ट हो तो वे आसानी से भटक जाते हैं
• इसलिए मुख्य बात यह है कि शुरुआत में ही agent के लिए स्पष्ट mission तय कर दिया जाए, ताकि वह इधर-उधर न भटके

• Plan Mode का उपयोग

  • Claude Code का Plan Mode ऐसा mode है जो agent को read-only में रखता है और उससे केवल codebase analysis और detailed planning करवाता है
  • Shift+Tab से Plan Mode में जाकर अगर आप “क्या बनाना चाहते हैं” यह समझाते हैं, तो agent मौजूदा code को देखकर spec का draft तैयार करता है
  • इस समय आप उससे plan के साथ architecture, best practices, security risks, और testing strategy की भी जाँच करने को कह सकते हैं
  • जब तक plan बिना किसी भ्रम की गुंजाइश के पर्याप्त रूप से परिष्कृत न हो जाए, तब तक Plan Mode बनाए रखें; उसके बाद ही Plan Mode से बाहर निकलकर execution चरण में जाएँ

• spec को context की तरह इस्तेमाल करना

  • अंतिम रूप दिया गया spec SPEC.md जैसी file में सहेजें, और काम करते समय केवल ज़रूरी sections चुनकर agent को फिर से दें
  • क्योंकि spec file sessions के बीच बनी रहती है, इसलिए project को दोबारा शुरू करते समय भी यह AI को उसी reference point पर स्थिर रखने का काम करती है
  • इससे लंबे conversation history या agent restart के दौरान होने वाली भूल को कम करने में मदद मिलती है
  • जैसे टीम में PRD (product requirements document) साझा reference के रूप में काम करता है, वैसे ही यह इंसानों और AI दोनों के लिए “single source of truth” की भूमिका निभाता है

• goal-oriented बने रहना

  • high-level spec में शुरुआत से implementation method की हर बात लिखने के बजाय what/why पर ध्यान देना और specific how को बाद के लिए छोड़ना अधिक उपयुक्त है
  • इसे user story और acceptance criteria की तरह संरचित करें: “उपयोगकर्ता कौन है? / उसे क्या चाहिए? / सफलता कैसी दिखेगी?”
  • GitHub Spec Kit में भी इस flow पर ज़ोर दिया गया है कि “क्या और क्यों बनाया जा रहा है” इसका high-level विवरण दें, और coding agent को user experience तथा success criteria के आधार पर detailed specification तैयार करने दें”

सिद्धांत 2: स्पेक को प्रोफेशनल PRD (या SRS) की तरह संरचित करें

• AI स्पेक को सिर्फ नोट्स के संग्रह की तरह नहीं, बल्कि स्पष्ट सेक्शन वाला एक संरचित दस्तावेज़ मानना महत्वपूर्ण है
• PRD या सिस्टम डिज़ाइन दस्तावेज़ जैसी व्यापक और व्यवस्थित संरचना, कंटेंट को शाब्दिक रूप से समझने वाले AI के लिए खास तौर पर उपयुक्त होती है
• GitHub पर 2,500 से अधिक एजेंट कॉन्फ़िगरेशन फ़ाइलों के विश्लेषण से पता चला कि प्रभावी स्पेक में आम तौर पर 6 प्रमुख क्षेत्र शामिल होते हैं

  • 1. Commands

    • चलाए जा सकने वाले कमांड दस्तावेज़ की शुरुआत में रखें
    • सिर्फ टूल का नाम नहीं, बल्कि फ्लैग सहित पूरा कमांड लिखें: npm test, pytest -v, npm run build

  • 2. Testing

    • टेस्ट कैसे चलाने हैं, कौन-सा framework इस्तेमाल होता है, टेस्ट फ़ाइलों का स्थान क्या है, और अपेक्षित coverage स्तर क्या है—इसे स्पष्ट रूप से लिखें

  • 3. Project Structure

    • source code, tests और documentation की लोकेशन को स्पष्ट रूप से अलग करें
    • उदाहरण: "src/ application code के लिए, tests/ unit tests के लिए, docs/ documentation के लिए"

  • 4. Code Style

    • स्टाइल को लंबा-चौड़ा समझाने से बेहतर एक वास्तविक code snippet कहीं अधिक प्रभावी होता है
    • naming rules, formatting standards, और वांछित output examples साथ में दें

  • 5. Git Workflow

    • branch naming rules, commit message format, और PR requirements स्पष्ट कर दें, तो एजेंट भी उसी flow का पालन करता है

  • 6. Boundaries

    • साफ़ तौर पर बताएं कि एजेंट किन क्षेत्रों को बिल्कुल नहीं छू सकता
    • secrets, vendor directories, production settings, खास folders आदि
    • GitHub रिसर्च में “कभी भी secrets commit न करें” सबसे अधिक बार दिखाई देने वाली उपयोगी सीमा के रूप में सामने आया

• स्टैक के बारे में ठोस रूप से लिखें

  • “React project” जैसा सामान्य लिखने के बजाय, “React 18 + TypeScript + Vite + Tailwind CSS” जैसी ठोस जानकारी देना ज़रूरी है
  • version और मुख्य dependencies भी साथ में लिखें; अस्पष्ट स्पेक अंततः अस्पष्ट code पैदा करता है

• एकसमान फ़ॉर्मैट का उपयोग करें

  • स्पष्टता सबसे महत्वपूर्ण है, और कई डेवलपर Markdown headings या XML-जैसे tags से सेक्शन अलग करते हैं
  • AI मॉडल मुक्त गद्य की तुलना में अच्छी तरह संरचित टेक्स्ट को कहीं अधिक स्थिरता से प्रोसेस करते हैं
  • Anthropic के इंजीनियर भी <background>, <instructions>, <tools>, <output_format> जैसे स्पष्ट रूप से अलग सेक्शन सुझाते हैं

• स्पेक को toolchain में इंटीग्रेट करें

  • स्पेक को सिर्फ दस्तावेज़ नहीं, बल्कि version control और CI/CD से जुड़ा “executable artifact” मानें
  • GitHub Spec Kit, स्पेक को engineering process के केंद्र में रखने वाला 4-स्टेज gate workflow इस्तेमाल करता है
    • Specify: क्या और क्यों बनाना है इसका high-level विवरण दें, और coding agent विस्तृत specification तैयार करे
    • Plan: वांछित stack, architecture, और constraints सहित तकनीकी योजना बनाएँ
    • Tasks: स्पेक और योजना को वास्तविक कार्य इकाइयों में बाँटें, और हर एक को testable size में तोड़ें
    • Implement: coding agent tasks को एक-एक करके या parallel में पूरा करे

• agents.md के ज़रिए specialized persona

  • GitHub Copilot जैसे tools में specialized agent persona परिभाषित किए जा सकते हैं
  • @docs-agent (technical documentation), @test-agent (QA), @security-agent (code review) जैसी भूमिकाएँ अलग की जा सकती हैं
  • हर agents.md फ़ाइल उस persona के व्यवहार, commands और boundaries को समेटने वाले focused spec की भूमिका निभाती है

• Agent Experience (AX) डिज़ाइन

  • जैसे API को developer experience (DX) के हिसाब से डिज़ाइन किया जाता है, वैसे ही स्पेक को भी agent experience (AX) को ध्यान में रखकर डिज़ाइन करना चाहिए
  • साफ़-सुथरा और parse करने में आसान फ़ॉर्मैट महत्वपूर्ण है
    • एजेंट द्वारा उपयोग किए जाने वाले API का OpenAPI schema
    • LLM consumption के लिए documentation summary (llms.txt)
    • स्पष्ट type definitions
  • MCP (Model Context Protocol) जैसे standards का पालन करने वाले स्पेक को एजेंट अधिक स्थिरता से समझते और इस्तेमाल करते हैं

• इसे living document की तरह बनाए रखें

  • स्पेक ऐसा दस्तावेज़ नहीं है जिसे एक बार लिखकर छोड़ दिया जाए; AI के साथ निर्णय लेते समय या नए तथ्य सामने आने पर इसे लगातार अपडेट करना चाहिए
  • spec-based workflow में स्पेक implementation, testing, और task breakdown को आगे बढ़ाता है, और स्पेक validate हुए बिना अगला चरण शुरू नहीं होता
  • यह स्पेक सिर्फ AI के लिए नहीं, बल्कि डेवलपर के लिए भी एक मुख्य उपकरण है, जिससे वह पूरे flow की निगरानी कर सके और यह सुनिश्चित कर सके कि AI का आउटपुट वास्तविक requirements को पूरा करता है

सिद्धांत 3: टास्क को मॉड्यूलर prompts और context में विभाजित करें

• एक ही विशाल prompt में सब कुछ भरने के बजाय, एक समय में सिर्फ एक टास्क पर ध्यान देने लायक context दें
• पूरे प्रोजेक्ट की requirements, code और instructions को एक single prompt में भर देने से उल्टा भ्रम बढ़ सकता है
• सिर्फ token limit से टकराने का जोखिम ही नहीं, बल्कि “instructions का curse (curse of instructions)” मॉडल का focus भी तेजी से गिरा सकता है

• instructions का curse

  • शोध के अनुसार, prompt में जितनी ज्यादा instructions या data जोड़े जाते हैं, हर instruction को सही तरीके से follow करने की क्षमता स्पष्ट रूप से घटती जाती है
  • GPT-4 या Claude जैसे शक्तिशाली models भी, एक साथ बहुत सारी requirements पूरी करने वाले अनुरोधों में कठिनाई महसूस करते हैं
  • उदाहरण के लिए, अगर 10 detailed rules bullets में दिए जाएँ, तो model अक्सर शुरुआती कुछ नियम मानता है और बाद के नियमों को धीरे-धीरे नजरअंदाज करने लगता है
  • बेहतर रणनीति है iterative focus: एक बार में सिर्फ एक sub-problem पर ध्यान दिलाएँ, और उसके पूरा होने के बाद अगले पर जाएँ

• स्पेक को चरणों या components में बाँटें

  • अगर spec document लंबा है या उसका दायरा बड़ा है, तो उसे कई हिस्सों में बाँटने पर विचार करें
  • उदाहरण: “Backend API Spec” और “Frontend UI Spec” को अलग sections में बाँटना
  • backend पर काम करते समय frontend spec को हर बार साथ देना जरूरी नहीं है
  • multi-agent environment में हर domain के लिए अलग agent या sub-process भी रखा जा सकता है
  • DigitalOcean AI guide भी चेतावनी देती है कि “authentication task और database schema changes को एक साथ mix न करें”

• बड़े specs के लिए extended TOC/summary

  • agent से पहले पूरे spec का summary देने वाली extended TOC लिखवाने का तरीका
  • हर section को कुछ मुख्य points या keywords में compress करें, और साथ में यह भी refer करें कि details कहाँ हैं
  • उदाहरण: “Security: HTTPS का उपयोग, API key protection, input validation लागू करें (पूरे spec के §4.2 को देखें)”
  • इस तरह की hierarchical summary तैयार होने पर prompt में सिर्फ बड़ा चित्र रखा जा सकता है और details जरूरत पड़ने पर दी जा सकती हैं
  • extended TOC एक तरह के index की तरह काम करती है, जिससे agent समझ पाता है कि “अच्छा, security section भी है” और वह उस हिस्से को माँग सकता है
  • इस तरह का hierarchical summarization approach LLM को high-level structure बनाए रखने में मदद करता है

• sub-agents या “skills” का उपयोग

  • Anthropic के बताए sub-agents (या “skills”) की तरह, भूमिका-विभाजित multi-agent approach इस्तेमाल की जा सकती है
  • हर sub-agent को किसी खास विशेषज्ञता वाले domain के हिसाब से सेट किया जाता है, और उसे spec का सिर्फ वही हिस्सा दिया जाता है जो उसके domain से जुड़ा हो
  • उदाहरण: Database Designer sub-agent सिर्फ data model section जाने, और API Coder sub-agent सिर्फ API endpoint spec जाने
  • इससे हर agent के पास छोटा context और ज्यादा स्पष्ट role होता है, जिससे accuracy में सुधार और parallel work संभव होता है
  • Claude Code, अपने system prompt और tools वाले sub-agents define करने की सुविधा देता है

• throughput के लिए parallel agents

  • कई agents को एक साथ चलाने का तरीका developer productivity के अगले चरण के रूप में उभर रहा है
  • एक agent के खत्म होने का इंतजार करने के बजाय, एक-दूसरे से न टकराने वाले कामों में agents को parallel लगाया जाता है
  • Simon Willison इसे “parallel coding agents को अपनाना” कहते हैं, और बताते हैं कि यह हैरान करने वाली हद तक प्रभावी है, लेकिन मानसिक रूप से काफी थकाऊ भी
  • मुख्य बात यह है कि agents के task boundaries साफ़ हों, ताकि वे एक-दूसरे के काम में बाधा न डालें
  • LangGraph या OpenAI Swarm जैसे orchestration frameworks इस तरह के coordination में मदद करते हैं,
  • और Chroma जैसे vector databases को shared memory की तरह इस्तेमाल किया जाए तो बिना duplicate prompting के common context तक पहुँचा जा सकता है

• single vs multi-agent: कब क्या इस्तेमाल करें

  पहलू	single agent	parallel/multi-agent
  फायदे	setup सरल, overhead कम, और debug व flow tracking आसान	throughput अधिक, जटिल interdependency संभालने की क्षमता, और domain-specific specialization संभव
  नुकसान	बड़े projects में context overload, iteration की गति धीमी, single point of failure	coordination cost बढ़ती है, conflicts की संभावना, shared memory की जरूरत
  उपयुक्त स्थिति	isolated modules, छोटे-मध्यम projects, शुरुआती prototyping	बड़े codebases, coding-testing-review का विभाजन, स्वतंत्र feature development
  टिप	spec summary का उपयोग, task-wise context refresh, session को बार-बार reset करें	शुरुआत में agents की संख्या 2~3 तक सीमित रखें, MCP से tools share करें, boundaries स्पष्ट रखें

• हर prompt को एक टास्क/section पर केंद्रित रखें

  • जटिल multi-agent environment न होने पर भी, modularity को manually काफी हद तक लागू किया जा सकता है
  • उदाहरण: spec लिखने के बाद “Step 1: database schema implementation” चरण में spec का सिर्फ Database section दें
  • जब भी मुख्य task बदले, context को फिर से व्यवस्थित करें ताकि पुरानी या अप्रासंगिक जानकारी से होने वाला distraction कम हो
  • कुछ guides सलाह देती हैं कि बड़े feature switch पर नई session शुरू करें ताकि context साफ़ हो जाए

• inline instructions और code TODO का उपयोग

  • code में // TODO comments लिखकर काम दर्ज करें, और agent से उन्हें एक-एक करके पूरा करवाएँ
  • हर TODO, छोटे task के लिए एक mini spec की तरह काम करता है
  • नतीजतन AI बहुत सीमित scope पर ध्यान देता है, जैसे “इस spec snippet के अनुसार सिर्फ यह function implement करो”

सिद्धांत 4: self-check, constraints, और human expertise को एम्बेड करना

• स्पेक को सिर्फ एजेंट के to-do list की तरह नहीं, बल्कि quality को मैनेज करने वाले guide की तरह देखें और अपनी expertise को सक्रिय रूप से उसमें शामिल करें
• अच्छा स्पेक पहले से पहचान लेता है कि AI कहाँ गलती कर सकता है, और उन बिंदुओं पर guardrails खड़े कर देता है
• domain knowledge, edge cases, और तरह-तरह की “सावधानियां” शामिल करें ताकि AI बिना context वाले vacuum में काम न करे
• स्पेक को AI का coach और judge मानें: सही approach की ओर ले जाए, और गलत behavior पर तुरंत रोक लगाए
• GitHub की 2,500 से अधिक agent files के analysis के अनुसार, सबसे प्रभावी specs सिर्फ साधारण प्रतिबंध सूची नहीं, बल्कि 3-स्तरीय boundary system का उपयोग करते हैं
  • यह साफ बताता है कि एजेंट कब सीधे आगे बढ़ सकता है, कब रुककर पूछना चाहिए, और कब पूरी तरह रुक जाना चाहिए

  • ✅ Always do (हमेशा करें)

    • वे कार्य जो बिना पूछे किए जाने चाहिए
    • उदाहरण: “commit से पहले हमेशा tests चलाएँ”, “style guide की naming convention का हमेशा पालन करें”, “errors को हमेशा monitoring service में log करें”

  • ⚠️ Ask first (पहले पूछें)

    • वे कार्य जिनके लिए इंसानी approval चाहिए
    • उदाहरण: “database schema बदलने से पहले पूछें”, “नई dependency जोड़ने से पहले पूछें”, “CI/CD settings बदलने से पहले पूछें”
    • तकनीकी रूप से संभव होने पर भी, जिन बदलावों का प्रभाव क्षेत्र बड़ा हो और मानवीय निर्णय की जरूरत हो, उन्हें यहाँ फ़िल्टर किया जाता है

  • 🚫 Never do (कभी न करें)

    • स्पष्ट hard-stop क्षेत्र
    • उदाहरण: “secrets या API keys कभी commit न करें”, “node_modules/ या vendor/ को कभी edit न करें”, “स्पष्ट approval के बिना failing tests को न हटाएँ”
    • शोध में भी “कभी secrets commit न करें” सबसे अधिक दिखाई देने वाली उपयोगी constraint साबित हुई

• self-validation को बढ़ावा दें

  • एजेंट को स्पेक के आधार पर खुद परिणाम की जाँच करने के लिए प्रेरित करें
  • अगर tools की अनुमति हो, तो code generation के बाद unit tests या linting खुद चलाने को workflow में शामिल करें
  • prompt स्तर पर भी दोबारा जाँच के निर्देश दिए जा सकते हैं
    • उदाहरण: “implementation के बाद परिणाम की स्पेक से तुलना करें, जाँचें कि सभी requirements पूरी हुई हैं या नहीं, और जो छूटी हों उन्हें सूचीबद्ध करें”
  • इससे LLM अपनी output को स्पेक से मिलाकर देखता है और omissions कम होते हैं

• व्यक्तिपरक जाँच के लिए LLM-as-a-Judge

  • code style, readability, और architecture pattern compliance जैसे ऐसे मानदंडों के लिए जिन्हें automate करना मुश्किल हो, LLM-as-a-Judge approach उपयोगी है
  • दूसरा एजेंट (या अलग prompt) पहले एजेंट की output को स्पेक के quality standards के अनुसार review करता है
  • उदाहरण: “review करें कि यह code हमारे style guide का पालन करता है या नहीं, और violations को चिह्नित करें”
  • judge की भूमिका वाला एजेंट feedback लौटाता है, जिसे लागू किया जा सकता है या revision की शुरुआत के रूप में उपयोग किया जा सकता है

• conformance testing

  • Willison conformance suite बनाने की सिफारिश करते हैं
  • यह language-independent tests का सेट होता है, अक्सर YAML-आधारित, जो हर implementation के लिए pass करना अनिवार्य contract बनता है
  • अगर आप API बना रहे हैं, तो conformance suite expected inputs और outputs को define करता है, और एजेंट द्वारा बनाया गया code उन सभी को पूरा करना चाहिए
  • स्पेक के Success section में “conformance/api-tests.yaml के सभी cases pass करना अनिवार्य है” जैसी शर्त स्पष्ट लिखें

• स्पेक में tests का उपयोग

  • जहाँ संभव हो, स्पेक और prompt flow में test plan या वास्तविक tests सीधे शामिल करें
  • TDD की तरह test cases से requirements को स्पष्ट करें
    • उदाहरण: Success Criteria में “यह sample input अनिवार्य रूप से यह output generate करे”
  • Willison मज़बूत test suite को एजेंट के लिए लगभग superpower बताते हैं
  • क्योंकि test fail होने पर तुरंत verify करके iteration किया जा सकता है
  • sub-agent setup में, स्पेक के मानदंड लेकर code output को लगातार validate करने वाला समर्पित test agent भी रखा जा सकता है

• domain knowledge को शामिल करें

  • स्पेक में ऐसे व्यावहारिक insights होने चाहिए जो सिर्फ अनुभवी developers या context जानने वाले लोगों को पता होते हैं
  • उदाहरण: e-commerce एजेंट बनाते समय साफ लिखें कि “products” और “categories” के बीच many-to-many relationship है
    • यह उम्मीद न करें कि AI इसे अपने आप infer कर लेगा
  • अगर कोई specific library tricky है, तो उससे जुड़ी आम pitfalls या precautions भी लिखें
  • यह अपनी mentorship को स्पेक में उतारने का तरीका है
    • उदाहरण: “library X का उपयोग करते समय version Y में memory leak की समस्या है, इसलिए workaround Z लागू करें”

• सरल tasks के लिए minimalism

  • thorough spec महत्वपूर्ण है, लेकिन expertise का एक हिस्सा यह जानना भी है कि कब चीज़ों को सरल रखना चाहिए
  • अपेक्षाकृत सरल और isolated कामों में ज़रूरत से ज़्यादा स्पेक उल्टा भ्रम बढ़ा सकता है
  • उदाहरण: “page पर div को center align करना” जैसे काम में
    • “solution को concise रखें, और अनावश्यक markup या styles न जोड़ें” इतना ही काफ़ी हो सकता है
  • इसके विपरीत, “token refresh और error handling सहित OAuth flow implement करना” जैसे जटिल tasks के लिए detailed spec चाहिए
  • अनुभवजन्य नियम यह है कि task की complexity के अनुसार स्पेक की density को समायोजित करें

• इंसान को अंतिम quality filter बनाए रखें

  • स्पेक एजेंट को अधिकार सौंपता है, लेकिन अंतिम quality की जिम्मेदारी developer की ही रहती है
  • भले ही एजेंट तकनीकी रूप से स्पेक पूरा कर दे, अगर feel या context सही न लगे तो अपने judgment पर भरोसा करें
  • ज़रूरत पड़े तो स्पेक को फिर से refine करना या output को खुद संपादित करना भी स्वाभाविक प्रक्रिया है
  • Willison AI agents के साथ काम करने को “management का एक बहुत अजीब रूप” बताते हैं, और “यह human intern को manage करने जैसा असहज रूप से मिलता-जुलता है” जैसी उपमा देते हैं
  • अंततः स्पष्ट निर्देश (spec), पर्याप्त context, और actionable feedback देना अब भी इंसान की ही भूमिका है

सिद्धांत 5: टेस्टिंग, पुनरावृत्ति, और स्पेक का विकास (सही टूल्स का उपयोग)

• स्पेक लिखने और एजेंट बनाने को एक बार में खत्म होने वाला काम नहीं, बल्कि एक iterative loop के रूप में समझें
  • जल्दी टेस्ट करना, फीडबैक इकट्ठा करना, स्पेक को परिष्कृत करना, और टूल्स से जांच को automate करना — यही सही प्रवाह है
• शुरुआती स्पेक अंतिम संस्करण नहीं, बल्कि साइकिल की शुरुआत है

• निरंतर टेस्टिंग

  • सभी implementation पूरा होने का इंतज़ार न करें; प्रमुख milestone या function स्तर पर टेस्ट या सरल manual check करें
  • अगर failure मिले, तो बस आगे न बढ़ें; पहले स्पेक या prompt को ठीक करें
  • automated tests खास तौर पर प्रभावी होते हैं, और अगर टेस्ट मौजूद हों, तो एजेंट से npm test जैसे commands सीधे चलवाए जा सकते हैं
  • टेस्ट failure के परिणाम को अगली prompt के input के रूप में ज्यों का त्यों इस्तेमाल करें
    • उदाहरण: “output X, Y, Z पर स्पेक को पूरा नहीं कर पाया, इसलिए इसे ठीक करो”
  • code → test → fix → repeat वाला agentic loop बहुत शक्तिशाली तरीका है

• स्पेक पर ही पुनरावृत्ति

  • अगर एजेंट ने गलत समझा हो या requirements की कमी सामने आई हो, तो समस्या को ढकें नहीं; पहले स्पेक दस्तावेज़ को ठीक करें
  • बदले हुए स्पेक को एजेंट के साथ स्पष्ट रूप से फिर से sync करें
    • उदाहरण: “स्पेक को इस तरह update किया गया है। इस बदलाव को दर्शाते हुए plan समायोजित करो या code को refactor करो”
  • स्पेक को हमेशा single source of truth बनाए रखें
  • संभव हो तो commit messages या notes में version history रखें, ताकि क्या और क्यों बदला, यह trace किया जा सके

• context management और memory tools का उपयोग

  • AI एजेंट के context और knowledge management में मदद करने वाला tool ecosystem तेज़ी से बढ़ रहा है
  • RAG (retrieval-augmented generation) pattern का उपयोग करने पर एजेंट vector database जैसे knowledge base से ज़रूरी जानकारी तुरंत ला सकता है
  • अगर स्पेक बहुत बड़ा हो, तो sections को embed करके रखें ताकि एजेंट पूरा दस्तावेज़ लेने के बजाय सिर्फ सबसे relevant हिस्से खोजे
  • MCP (Model Context Protocol) आधारित frameworks मौजूदा task के हिसाब से context अपने-आप उपलब्ध करा सकते हैं
  • Context7(context7.com) जैसे टूल्स काम के दौरान दस्तावेज़ से relevant snippets अपने-आप ला सकते हैं

• सावधानीपूर्वक parallelization

  • कुछ डेवलपर्स कई एजेंट instances को अलग-अलग tasks पर parallel चलाकर गति बढ़ाते हैं
  • उदाहरण: एक एजेंट code generate करे, जबकि दूसरा एजेंट साथ में tests लिखे
  • अगर यह तरीका अपनाएँ, तो tasks सचमुच स्वतंत्र हों या साफ़ तौर पर अलग किए गए हों, ताकि टकराव न हो
  • उदाहरण: दो एजेंट एक ही समय में एक ही file को edit न करें, इसकी सीमा तय करें
  • management overhead कम रखने के लिए शुरुआत में अधिकतम 2–3 एजेंट से शुरू करना व्यावहारिक है

• version control और स्पेक लॉक

  • Git जैसे version control tools से एजेंट के काम को बारीकी से track करें
  • AI का उपयोग जितना बढ़ता है, अच्छी version control आदतों का महत्व उतना ही बढ़ता है
  • स्पेक file को भी repository में commit करें ताकि बदलावों का इतिहास रहे
  • एजेंट git diff या blame पढ़कर बदलाव का context समझ सकता है
    • वास्तव में, LLMs diff समझने में काफी सक्षम होते हैं
  • स्पेक को repo में रखने से डेवलपर और AI दोनों प्रोजेक्ट के विकास को साथ-साथ track कर सकते हैं
  • Willison के शब्दों में, मॉडल “Git में बेहद सक्षम” हैं

• लागत और गति पर विचार

  • बड़े models और लंबे context वाले काम धीमे और महंगे हो सकते हैं
  • model selection को रणनीतिक रूप से अलग रखें
    • शुरुआती drafts या दोहराव वाले काम के लिए तेज़ और सस्ते models
    • अंतिम output या जटिल reasoning के लिए सबसे सक्षम (महंगे) models
  • उदाहरण: GPT-4 या Claude को planning और critical steps के लिए रखें, जबकि साधारण विस्तार या refactoring लोकल models या छोटे API models को दें
  • test-running agent या linter agent के लिए अपेक्षाकृत छोटे models भी पर्याप्त हो सकते हैं
  • context size भी प्रबंधन का विषय है
    • जिस काम के लिए 5k tokens काफी हों, उसमें 20k tokens डालने की ज़रूरत नहीं
    • tokens की संख्या बढ़ने पर efficiency घट सकती है

• हर चीज़ को monitor और log करें

  • जटिल एजेंट workflows में एजेंट के व्यवहार और output logs अनिवार्य हैं
  • logs से पता लगाया जा सकता है कि एजेंट इरादे से भटका या कोई त्रुटि हुई
  • कई frameworks trace logs देते हैं या step-by-step reasoning process को output करने का समर्थन करते हैं
  • logs देखने पर यह सामने आता है कि स्पेक या निर्देश कहाँ गलत समझे गए

• सीखना और सुधार

  • हर प्रोजेक्ट को स्पेक लिखने की क्षमता निखारने का सीखने का अवसर मानें
  • आप देख सकते हैं कि कौन-सी अभिव्यक्तियाँ बार-बार AI को भ्रमित करती हैं, और किस तरह की स्पेक संरचना बेहतर निभाई जाती है
  • इन सीखों को अगले स्पेक में सक्रिय रूप से शामिल करें
  • AI एजेंट का क्षेत्र तेज़ी से विकसित हो रहा है, और नए टूल्स व best practices लगातार सामने आ रहे हैं

आम गलतियों से बचें

• GitHub पर 2,500 से अधिक एजेंट files के विश्लेषण से पता चला कि विफलता का सबसे बड़ा कारण स्पेक और निर्देशों का अत्यधिक अस्पष्ट होना है

• अस्पष्ट prompts

  • “कुछ बढ़िया बनाओ”, “इसे बेहतर चलने लायक बना दो” जैसी requests में एजेंट के पास निर्णय का आधार ही नहीं होता
  • input, output, और constraints को जितना हो सके उतना ठोस रूप से लिखना चाहिए
  • “आप एक helpful coding assistant हैं” जैसी सामान्य role assignment का लगभग कोई असर नहीं होता
  • इसके उलट, “आप React component tests लिखने वाले test engineer हैं, यह example follow करें, और source code को कभी modify न करें” की तरह role, scope, और constraints को साथ में निर्दिष्ट करने पर कहीं बेहतर परिणाम मिलते हैं

• सारांश के बिना अत्यधिक context

  • 50-पेज का दस्तावेज़ सीधे prompt में dump करके यह उम्मीद करना कि model खुद समझ जाएगा, ज़्यादातर मामलों में असफल होता है
  • hierarchical summarization या RAG का उपयोग करके सिर्फ वही सामग्री सामने लानी चाहिए जो मौजूदा task से सीधे जुड़ी हो
  • context length बढ़ाना, context की कमज़ोर गुणवत्ता की भरपाई नहीं कर सकता

• human review को छोड़ देना

  • Willison का निजी सिद्धांत: “ऐसा code commit मत करो जिसे तुम किसी दूसरे इंसान को समझा न सको”
  • सिर्फ इसलिए कि एजेंट ने कुछ ऐसा बनाया जो tests पास कर गया, इसका मतलब यह नहीं कि वह code तुरंत सही, सुरक्षित, और maintainable भी है
  • खासकर महत्वपूर्ण code paths की हमेशा इंसान द्वारा सीधी समीक्षा होनी चाहिए
  • AI-generated code ऊपर से मज़बूत दिख सकता है, लेकिन untested edge cases में ढह सकता है; इस लिहाज़ से “ताश के पत्तों का घर” वाली उपमा ठीक बैठती है

• vibe coding और production engineering को गड़बड़ाना

  • AI की मदद से तेज़ prototyping, यानी तथाकथित “vibe coding”, खोजबीन के चरण या one-off projects के लिए उपयुक्त है
  • बिना सख्त स्पेक, testing, और review के उसके परिणाम को सीधे production में deploy करने पर बड़ी समस्या हो सकती है
  • “vibe coding” और “AI-assisted engineering” में स्पष्ट अंतर होना चाहिए; बाद वाले के लिए इस गाइड में बताए गए अनुशासन और प्रक्रिया ज़रूरी हैं
  • यह समझना महत्वपूर्ण है कि आप इस समय किस mode में काम कर रहे हैं

• “घातक त्रयी” को नज़रअंदाज़ करना

  • Willison जिन तीन गुणों को AI एजेंट को खतरनाक बनाने वाला बताते हैं
    • गति: इंसान जितनी तेज़ी से review कर सके, उससे भी तेज़ परिणाम बनाना
    • अनिर्धारितता: एक ही input पर हर run में अलग output
    • लागत: पर्याप्त verification करने के बजाय shortcuts लेने के लिए प्रेरित करना
  • स्पेक और review process को इन तीनों को ध्यान में रखकर डिज़ाइन किया जाना चाहिए
  • खास तौर पर यह सुनिश्चित करने के लिए सचेत नियंत्रण चाहिए कि गति verification क्षमता से आगे न निकल जाए

• 6 मुख्य क्षेत्रों को छोड़ देना

  • अगर स्पेक में Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries शामिल नहीं हैं, तो एजेंट के लिए काम की महत्वपूर्ण जानकारी छूटना आसान है
  • एजेंट को सौंपने से पहले 6-क्षेत्र checklist से एक बार फिर जाँच लेना सुरक्षित है

निष्कर्ष

• AI coding agents के लिए प्रभावी spec लिखने के लिए मज़बूत software engineering principles और LLM की विशेषताओं को समझकर उनके अनुसार ढला हुआ approach—दोनों की ज़रूरत होती है
• सब कुछ उद्देश्य को स्पष्ट रूप से तय करने से शुरू होता है, और उसके बाद भूमिकाएँ इस तरह बाँटी जाती हैं कि AI planning और details को आगे विस्तार दे सके
• Spec को memo नहीं बल्कि गंभीर design document की तरह देखना चाहिए, जिसमें 6 मुख्य क्षेत्र शामिल हों और जिसे toolchain से जुड़ा हुआ executable artifact माना जाए
• सब कुछ एक साथ देने के बजाय, काम को इकाइयों में बाँटकर देना चाहिए ताकि agent का focus बना रहे
  (summary TOC, sub-agents, parallel orchestration बड़े specs को संभालने के व्यावहारिक तरीके हैं)
• 3-स्तरीय boundaries (Always / Ask first / Never), self-checks, और suitability tests के ज़रिए उन आम pitfalls को पहले से रोका जा सकता है जिनमें AI अक्सर फँस जाता है
• Spec और implementation को स्थिर output नहीं बल्कि iterative process की तरह लेना चाहिए, और tests व feedback के जरिए spec और code—दोनों को लगातार निखारते रहना ही मुख्य बात है
• इन guidelines का पालन करने पर बड़े context में AI agent के दिशा खो देने या बकवास करने की संभावना स्पष्ट रूप से कम की जा सकती है

[gomjellie]

यह AI अनुवाद है, लेकिन इसका एक कोरियाई अनुवाद संस्करण भी है, इसलिए लिंक साझा कर रहा/रही हूँ.

https://rosetta.page/post/…

[qor0923]

धन्यवाद।

[googol]

व्यक्तिगत रूप से जब मैंने SDD(Specs Driven Development) के साथ प्रोजेक्ट डेवलप किए, तो शुरुआत में मुझे स्पष्ट productivity improvement महसूस हुआ, लेकिन अभी भी मैं सारा code spec-आधारित नहीं लिख सकता, और जब भी direct modification की ज़रूरत पड़ती है, code और spec दोनों को साथ में update करना पड़ता है, इसलिए उल्टा productivity कम होने का अनुभव हुआ।