पर्याप्त रूप से विस्तृत spec अपने आप में code है

• Agentic coding के बारे में यह दावा कि “spec document code की जगह ले सकता है”, इस मूल सीमा की ओर इशारा करता है कि spec अगर पर्याप्त रूप से सटीक हो जाए तो अंततः code के ही समान रूप में सिमटने लगता है
• OpenAI के Symphony प्रोजेक्ट को देखें तो उसका SPEC.md कोई spec नहीं, बल्कि व्यवहार में Markdown फ़ॉर्मैट का pseudocode है
• वास्तव में Symphony spec के आधार पर Haskell implementation करने की कोशिश में कई bugs और agent का अनंत प्रतीक्षा जैसी reliability समस्याएँ सामने आईं
• spec लिखने का काम मूल रूप से coding से भी अधिक गहरी सोच मांगता है, लेकिन मौजूदा उद्योग की speed optimization प्रवृत्ति में AI-जनित low-quality specs का ढेर बनता है
• “garbage in, garbage out” सिद्धांत coding agents पर भी ज्यों का त्यों लागू होता है, और स्पष्टता व detail से रहित documents से विश्वसनीय code generation संभव नहीं

---

Agentic coding के दो भ्रम

• Agentic coding के समर्थक जिन दो मुख्य भ्रमों पर निर्भर करते हैं
  • भ्रम 1: spec document अपने संबंधित code से सरल होता है — यानी engineer को spec document लिखने वाले manager में बदलकर, काम agents की टीम को outsource किया जा सकता है
  • भ्रम 2: spec लिखना coding से ज़रूर अधिक विचारशील काम है — यानी spec document से होकर जाने पर quality सुधरती है और बेहतर engineering practices को बढ़ावा मिलता है

code जैसा दिखने वाला spec: Symphony केस का विश्लेषण

• OpenAI का Symphony प्रोजेक्ट अपने आपको spec document (SPEC.md) से उत्पन्न agent orchestrator के रूप में पेश करता है, लेकिन वास्तविक SPEC.md की सामग्री spec से अधिक Markdown फ़ॉर्मैट के pseudocode के करीब है
• SPEC.md में शामिल सामग्री के प्रकार:
  • database schema का गद्य-आधारित dump — session_id, thread_id, codex_input_tokens जैसे fields की सूची
  • code को गद्य में बदला हुआ रूप — concurrency control का available_slots = max(max_concurrent_agents - running_count, 0) जैसा formula, retry backoff formula (delay = min(10000 * 2^(attempt-1), agent.max_retry_backoff_ms)) आदि
  • model की code generation में मदद के लिए स्पष्ट रूप से जोड़े गए "Config Fields Summary (Cheat Sheet)" जैसे दोहराव वाले sections
  • start_service() function जैसे लगभग स्वयं code ही लगने वाले “Reference Algorithms” sections
• जब यह दावा किया जाता है कि spec document code का विकल्प है, लेकिन वही document पढ़ने में code जैसा लगे, तो यह भ्रामक है
• spec document को पर्याप्त रूप से सटीक बनाने के लिए उसे अनिवार्य रूप से code के रूप में बदलना पड़ेगा, या बहुत अधिक structured formal English में लिखना होगा

Dijkstra का “narrow interface” तर्क

• Dijkstra के लेख का हवाला देते हुए कहा गया है कि interface का चुनाव केवल श्रम-विभाजन का मामला नहीं है; interface के पार collaboration और communication की लागत भी जुड़ती है
• ऐतिहासिक उदाहरण दिए गए हैं कि Greek गणित भाषाई और दृश्य गतिविधियों तक सीमित रहकर ठहर गया, Islamic algebra rhetorical style में लौटकर कमजोर हुआ, और पश्चिमी यूरोप मध्यकालीन scholasticism की “व्यर्थ भाषाई सटीकता की कोशिश” से बाहर निकलकर Vieta, Descartes, Leibniz, Boole आदि की formal symbolic systems की वजह से आगे बढ़ा
• Agentic coders engineering labor द्वारा माँगे गए “narrow interface” (= code) से बच नहीं सकते; वे केवल उस श्रम को सतही रूप से अलग दिखने वाले, लेकिन उसी स्तर की सटीकता मांगने वाले रूप में परिवर्तित कर सकते हैं

अस्थिरता: spec-आधारित code generation की reliability समस्या

• Symphony README की सिफारिश के अनुसार Claude Code से Haskell implementation माँगने पर, वह काम नहीं करता
  • कई bugs आए, जिन्हें prompts के ज़रिए ठीक करना पड़ा (यह commit history में देखा जा सकता है)
  • बिना error message के “चलने” वाले मामलों में भी codex agent एक साधारण Linear ticket (“खाली git repository बनाना”) पर बिना किसी प्रगति के अनंत प्रतीक्षा में चला गया
• Dijkstra की भाषा उधार लें तो Symphony की “व्यर्थ भाषाई सटीकता की कोशिश” भी अब तक विश्वसनीय implementation बनाने में विफल रहती है
• यह समस्या केवल Symphony तक सीमित नहीं है — YAML spec जैसी अत्यंत विस्तृत, व्यापक रूप से प्रयुक्त, और conformance test suite वाली specs में भी अधिकांश YAML implementations spec का पूर्ण पालन नहीं करतीं
• Symphony की spec पहले से शामिल Elixir implementation के 1/6 आकार तक पहुँचती है, और अगर इसे और बढ़ाया जाए तो यह Borges की “On Exactitude in Science” जैसी स्थिति तक पहुँचती है — जहाँ साम्राज्य के बराबर आकार का नक्शा बनाकर वह अंततः बेकार हो जाता है
• “अगर इसे किसी अधिक mainstream language में generate किया जाए तो नतीजा बेहतर होगा” जैसी आपत्ति के जवाब में कहा गया है कि अगर agent को Haskell code generation में कठिनाई होती है, तो यह training data से आगे generalize करने की कमी को दिखाता है

Slop: AI-जनित specs की quality समस्या

• spec लिखने का काम मूल रूप से coding से अधिक कठिन होना चाहिए, क्योंकि इसका उद्देश्य code लिखने से पहले project को विचारशील और आलोचनात्मक दृष्टि से देखना है
• लेकिन tech कंपनियों में श्रम को घटाकर आँकने और उसका अवमूल्यन करने वाली उद्योग प्रवृत्ति के बीच, अगर शुरुआत ही इस मान्यता से हो कि “spec लिखना coding से आसान है”, तो विफलता तय है
• delivery speed optimization को लक्ष्य बनाकर spec writing के लिए आवश्यक कठिन और असुविधाजनक काम करना संभव नहीं है
• Symphony SPEC.md का Section 10.5 (linear_graphql extension contract) slop का प्रतिनिधि उदाहरण है — ऐसे agent output का रूप, जिसमें एकरूपता, उद्देश्य और बड़े परिप्रेक्ष्य की समझ का अभाव है, फिर भी वह “spec जैसा” दिखता है
  • query खाली न होने वाली string होनी चाहिए, उसमें ठीक एक GraphQL operation होना चाहिए, जैसी अलग-अलग rules दी गई हैं, लेकिन समग्र संदर्भ गायब है
• ऐसे spec documents, चाहे इंसान ने लिखे हों, फिर भी अनिवार्य रूप से slop बन सकते हैं — क्योंकि वे एकरूपता या स्पष्टता नहीं, बल्कि delivery time के लिए optimize किए गए होते हैं
• code snippets को syntax highlighting के बिना text के रूप में annotate किया जाना भी AI-जनित document का संकेत है — संभवतः model ने अनुरोध की मंशा नहीं, बल्कि उसका शाब्दिक अर्थ पकड़ा

निष्कर्ष

• specs मूल रूप से समय बचाने के उपकरण के रूप में डिज़ाइन नहीं की गई थीं
• अगर लक्ष्य delivery time optimization है, तो बीच में spec document रखने की बजाय सीधे code लिखना अधिक लाभकारी है
• “garbage in, garbage out” सिद्धांत यहाँ भी ज्यों का त्यों लागू होता है — यदि input document में स्पष्टता और detail की कमी हो, तो ऐसा कोई संसार नहीं है जहाँ coding agent उस कमी को विश्वसनीय रूप से भर दे
• coding agent मन पढ़ने वाली सत्ता नहीं है, और भले ही वह ऐसा हो, अगर सोच ही अव्यवस्थित हो तो उसके पास करने के लिए कुछ नहीं बचेगा

[gracefullight]

यह मॉडल-ड्रिवन डेवलपमेंट के समय जैसा ही लगता है।

[wedding]

क्या spec-आधारित development SDD पहले से ही मौजूद नहीं था?

[koreacglee]

लगता है कि Python या JavaScript-आधारित solutions में सिर्फ़ विस्तृत specification documents के आधार पर भी संतोषजनक implementation संभव है। मैं C/C++-आधारित game/medical क्षेत्र में हूँ, और आजकल मुझे यह ज़्यादा लगता है कि FULL AI AGENT को delegate करना तो दूर, सिर्फ़ विस्तृत specification documents के आधार पर automation करना भी बहुत बड़ा जोखिम है।

[GN⁺]

Hacker News की राय

• मैं इस बात से सहमत नहीं हूँ कि अगर दस्तावेज़ अस्पष्ट हों तो coding agent उनमें विवरण नहीं भर सकते
  LLM मूल रूप से language interpolation/extrapolation machine हैं, और missing details भरने में बहुत सक्षम हैं
  सिर्फ़ छोटे और संक्षिप्त विवरण से काम करने वाला code बनाने के बहुत से उदाहरण हैं
  लेकिन यह detail completion हमेशा सही नहीं होता, और reliability सुनिश्चित करने के लिए महत्वपूर्ण हिस्सों को स्पष्ट रूप से constrain करना पड़ता है
  अभी code लिखने की culture तो है, लेकिन ultra-precise spec लिखने की culture NASA जैसी जगहों को छोड़कर लगभग नहीं है

  • LLM छोटे description से code बना सकते हैं, लेकिन उसे reliably नहीं बनाते
    code जितना छोटा और common होगा, उतना अच्छा काम करेगा, लेकिन complex description पर जल्दी टूट जाता है
    आखिरकार, यह मान लेना कि “detail completion गलत हो सकता है”, यही कहने जैसा है कि reliable generation कठिन है
  • दरअसल हमारे पास पहले से ऐसे precise specification language मौजूद हैं
    उदाहरण के लिए Synquid जैसी program synthesis language है
    यह दिखाती है कि mathematically exact specification से program generation की क्या सीमाएँ हैं
    specification gap कहलाने वाली समस्या, यानी यह साबित करना कि program specification को faithfully implement करता है या नहीं, यही मुख्य चुनौती है
    natural language बहुत ambiguous है, इसलिए program define करने के लिए उपयुक्त नहीं है
    सिर्फ़ इसलिए कि LLM plausible detail भर देता है, यह gap हल नहीं हो जाता
    mathematical specification language precise तो हैं, लेकिन उनकी learning curve बहुत ऊँची है, और सिर्फ़ Markdown में prompt लिखने की तुलना में कहीं ज़्यादा कठिन और labor-intensive हैं
  • यह कहना कि “detail completion गलत हो सकता है”, अपने ही दावे का खंडन करना है
  • अगर आप ChatGPT 5.4 Pro इस्तेमाल करें, तो सिर्फ़ “क्या यह संभव है?” पूछने पर भी यह वास्तव में काम करने वाले example बना देता है
    model मेरी रुचियों को याद रखता है, या अपने knowledge से gaps भरकर पूरा app, game, या whitepaper बना देता है
    कभी-कभी वह “बिल्कुल वही होता है जो मैं चाहता था”, और कभी “ठीक वही feeling जिसे मैं कह रहा था”
    meaning, context, और nuance सँभालने की इसकी क्षमता कुछ मामलों में इंसानों से भी आगे है
    AI धीरे-धीरे और ज़्यादा smart और capable होता जा रहा है
  • LLM जो बनाते हैं, उसका ज़्यादातर हिस्सा boilerplate या पहले से ज्ञात algorithm का extension होता है
    यानी वे पूरी तरह नए details create नहीं करते, बल्कि training data से खींचकर लाने के अधिक करीब होते हैं

• “काफ़ी विस्तार वाला specification ही code है” इस बात से सहमति है
  यह Brooks की No Silver Bullet वाली दलील जैसा ही है
  लेकिन ज़्यादातर लोग इतने स्तर का detail चाहते ही नहीं
  अगर आप “AI से मेरे लिए एक to-do app बना दो” कहते हैं, तो असल में उसका मतलब होता है “मेरी कल्पना से भी बेहतर app बना दो”

  • ऐसा इसलिए है क्योंकि training data में पहले से अनगिनत to-do app मौजूद हैं
    लेकिन यह approach दूसरे kinds के software पर अच्छी तरह scale नहीं होती
  • अगर आप सच में app बनाना चाहते हैं, तो आपको बताना पड़ेगा कि वह existing apps से अलग कैसे है
    अंततः उस differentiation को specification के रूप में व्यक्त करना ही होगा
  • web frontend जैसे visual और concrete domain में specification लगभग code के बराबर हो सकता है
    लेकिन database, filesystem, parallel computation जैसे क्षेत्र, जहाँ correctness और performance महत्वपूर्ण हैं, वहाँ specification से implementation तक पहुँचना कहीं अधिक कठिन है
    ऐसी जगहों पर AI द्वारा formal verification pass करने वाला code बनाना बहुत बड़ी चुनौती है
  • “बेहतर app” का मतलब क्या है, यह परिभाषित करने के लिए अंततः spec की ज़रूरत होती है
  • अगर app को commercial रूप से बेचना है, तो specification अनिवार्य है
    पैसा कमाने या compete करने के लिए concrete requirements चाहिए

• अगर vibe coding को information theory के नज़रिए से देखें, तो यह इस धारणा पर टिका है कि छोटे prompt space से useful program space को reconstruct करने वाला एक decoder मौजूद है
  यहाँ compression ratio ही vibe coding का लाभ है
  “IRC channel आधारित team communication app” जैसा prompt, अगर आप Slack को नहीं जानते, तो decode ही नहीं किया जा सकता
  इसलिए यह पहचानना महत्वपूर्ण है कि क्या गायब है
  AI coding को प्रभावी बनाने के लिए prompt को छोटे units में तोड़ना चाहिए, और existing documents या पहले से आज़माया गया code साथ देना चाहिए

  • यह वास्तव में algorithmic information theory जैसा ही है
    Algorithmic Information Theory के अनुसार, किसी string की information की मात्रा उसके सबसे compressed self-contained representation की लंबाई के बराबर होती है
    हालाँकि “self-contained” की यह शर्त तभी लागू होती है जब model के weights codebook की भूमिका निभा रहे हों
  • “छोटे prompt से program को reconstruct किया जा सकता है” यह विचार मुझे बहुत पसंद आया
    इंसान LLM की तुलना में कहीं अधिक shared context मानकर चलते हैं, इसलिए वे decoder की सीमाओं का अक्सर अधिक आकलन करते हैं
    लेकिन अगर किसी system में मज़बूत constraints और स्पष्ट emphasis हों, तो vibe coding का compression ratio विस्फोटक रूप से बढ़ सकता है
  • यह सिर्फ़ conciseness का मामला नहीं है
    natural language उन लोगों के लिए एक नया interface देती है, जिनके लिए programming language कम सुलभ है
    LLM उनकी जगह सोचता नहीं है, लेकिन ideas को working system में बदलने का एक नया रास्ता खोल देता है

• जल्द ही लोग model performance और token efficiency के लिए LLMSpeak जैसी technical English dialect बना सकते हैं
  इसका मक़सद ambiguity घटाना, tokens बचाना, और complex concepts को एक शब्द में compress करना होगा
  grammar में भी शायद Oxford comma जैसे नियम आ जाएँ ताकि clarity बढ़े

  • यह अंततः programming language को फिर से invent करने जैसा ही है
    अगर specification इतनी बारीकी से करनी ही है, तो फिर prompt लिखने का कारण ही क्या है
  • लेकिन अगर model उस dialect पर trained नहीं है, तो हर बार उसकी definitions भी साथ भेजनी पड़ेंगी
    अंततः उसे human language में फिर से define करना पड़ेगा, इसलिए token savings सीमित रहेंगी
  • कुछ लोग तो Lojban जैसी unambiguous language इस्तेमाल करने का सुझाव भी देते हैं
    Lojban wiki, Lojban speaker video देखें
  • human language पहले से ही ज़्यादातर ideas पहुँचाने के लिए काफ़ी efficient है
    artificial dialect की कोशिशें Esperanto की तरह विफल हो सकती हैं
  • अगर LLM इस dialect पर trained नहीं है, तो अंततः ambiguous human language को interpret करने की क्षमता ही ज़्यादा महत्वपूर्ण है
    ऐसी language शायद LLMs के बीच उपयोगी हो सकती है
    programming languages पहले से वही भूमिका निभा रही हैं

• spec, उन सभी programs को समेटने वाला एक envelope है जो दिए गए conditions को satisfy करते हैं
  इस envelope को बनाना किसी एक program को लिखने से भी कठिन है
  जैसे LLM हर बार अलग code generate कर सकता है, वैसे ही specification अच्छे और बुरे दोनों implementations की अनुमति दे सकती है
  व्यवहार में, एक implementation adopt हो जाने के बाद वही अगले version की de facto specification बन जाता है
  brownfield environment में, जहाँ existing code मौजूद होता है, specification साफ़-सुथरी नहीं होती, इसलिए LLM के लिए अच्छे से respond करना कठिन होता है

  • 20 साल के अनुभव के बाद जब मैंने specs लिखना शुरू किया, तब समझ आया कि यह coding से कठिन क्यों है
    इसमें combinatorial explosion होता है, क्योंकि specification की एक line दूसरी lines के साथ कैसे interact करेगी, यह भी सोचना पड़ता है
    लेकिन compiler के नज़रिए से code भी आखिर specification ही है
    अंततः “code specification से आसान है” यह एक सापेक्ष बात है
  • दो programs एक ही specification satisfy कर सकते हैं, लेकिन उनके security properties पूरी तरह अलग हो सकते हैं
    “user credentials store करता है” जैसी specification, bcrypt से लेकर plain-text cookie तक सबको शामिल कर सकती है
    इंसानों में “यह नहीं करना चाहिए” वाली सहज समझ होती है, लेकिन agent को वह तब तक नहीं पता चलेगा जब तक आप explicitly न लिखें
    इसलिए security सुनिश्चित करने के लिए क्या नहीं करना है यह भी specification में लिखना होगा
  • अच्छी specification सिर्फ़ “क्या करना है” परिभाषित करती है, “कैसे करना है” नहीं
    अगर performance या security महत्वपूर्ण है, तो उन properties को explicitly लिखना चाहिए
    जैसे “यह program O(n) होना चाहिए” कहना, implementation लिखने से बहुत आसान है

• लगता है लोग spec का मतलब अलग-अलग तरह से इस्तेमाल करते हैं
  मेरे लिए spec का मतलब है “क्या करना है(what)” को define करना, plan का मतलब “कैसे(how)”, और build packet का मतलब “विस्तृत चरण”
  ज़्यादातर मामलों में महत्वपूर्ण चीज़ “क्या” होती है
  यह specification में लिखना कि data A से B, फिर C के रास्ते D में preserve हो, और E पर F के रूप में represent हो, Rust code में implement करने से कहीं आसान है

• अगर आप agentic engineering करते हैं, तो कई बार spec document code से लंबा हो जाता है
  natural language अपूर्ण है, लेकिन code precise है
  specification का उद्देश्य कई iterations के development के बाद भी functionality को बनाए रखना है
  tests या comments की तुलना में waterfall-style design document ज़्यादा प्रभावी रहा
  इस तरीके से मैंने पूरी vibe coding project को refactor करने या language बदलने का काम भी काफ़ी smoothly किया
  अभी ऐसा लगता है जैसे development फिर से 70–80 के दशक के flow में लौट आया हो

  • tests से भी यह किया जा सकता है, लेकिन अगर test modification agent पर छोड़ दी जाए, तो वह tests को ही बदल देने का जोखिम है
  • natural language specification को हमेशा code से लंबा होना ज़रूरी नहीं
    “TCP interface implement करो” जैसी line असली code से बहुत छोटी है
    अंततः अगर उसे clear schema में map किया जा सकता है, तो natural language भी काफ़ी compressive हो सकती है

• Spec → LLM दिशा inefficient और wasteful है
  बल्कि LLM → Spec ज़्यादा यथार्थवादी है
  अगर specification compilable रूप में मौजूद हो, तो LLM उस feedback को लेकर बेहतर code generate कर सकता है
  “validated English” बनाने की कोशिश उल्टा complexity बढ़ाती है
  अंततः महत्वपूर्ण चीज़ वही code है जो वास्तव में काम करे

• code specification की तुलना में कहीं अधिक चीज़ें समेटे होता है
  ज़्यादातर projects में 90% हिस्सा framework या infra code होता है, और सिर्फ़ 10% business logic
  specification language या framework की details को नहीं छूता, इसलिए वह कहीं अधिक concise होता है

  • लेकिन जो code सच में problem solve करता है, उसे business logic छोड़कर बाकी सब abstract कर देना चाहिए
    ऐसा करने पर code लगभग specification के स्तर तक पहुँच जाता है
    domain expert भी उसे पढ़ सकते हैं और test करना भी आसान हो जाता है
  • उदाहरण के लिए, MySQL को Postgres से बदल दें तो specification वही रहती है
    लेकिन वास्तविक code काफ़ी बदल जाता है

• specification को management tool की तरह देखने और engineering tool की तरह देखने के बीच का टकराव cognitive dissonance पैदा करता है
  manager specification को delegation ticket की तरह देखते हैं, जबकि developers उसे सोच को refine करने वाले thinking tool की तरह इस्तेमाल करते हैं
  कुछ developers सुविधा के लिए शुरुआत manager वाली mindset से करते हैं, लेकिन जल्द ही उन्हें समझ आ जाता है

  • चाहे जितना manage कर लो, अंत में खुद build करना ही पड़ता है
    hype या investor meetings के सहारे थोड़ी देर चला जा सकता है, लेकिन आख़िरकार users को वास्तविक product चाहिए

[savvykang]

अगली बार शायद ये लोग waterfall और agile को भी फिर से invent कर देंगे।

[jjw9512151]

C embedded डेवलपर के रूप में मैं Feature/Subfeature के लिए लगभग पूरे flow को chart में जाँच सकने लायक specification बनाता हूँ.

फिर specification की लंबे समय तक समीक्षा करके उसे अंतिम रूप देने के बाद,
मैं specification के साथ पूरी तरह 1:1 मेल खाने वाला code तैयार करके इस्तेमाल करता हूँ.
Specification के आधार पर review करने पर, code review की तुलना में readability कहीं बेहतर होती है.