Claude Code या Codex को काम सौंपने से पहले तीन स्पेक फ़ाइलें बनाएं

अगर आपने AI coding agents को एक हफ़्ते से ज़्यादा use किया है, तो यह situation ज़रूर देखी होगी: सोमवार को एक task का output बिल्कुल clean और सही आता है, मंगलवार को वही task फिर से देते हैं और नतीजा पूरी तरह अलग होता है। Prompt लगभग वैसा ही था। Codebase में कोई बदलाव नहीं था। फिर भी result बदल गया।

मैंने करीब एक साल इस समस्या के पीछे भागते हुए बिताया। बेहतर prompts लिखे, ज़्यादा detailed instructions दिए, अलग-अलग models try किए। कुछ भी काम नहीं आया क्योंकि असली समस्या यह नहीं थी। असली समस्या यह थी कि मेरे पास intent communicate करने का कोई structured तरीका नहीं था। मैं सारा बोझ एक prompt पर डाल रहा था, जिसमें project rules भी थे, feature requirements भी, task steps भी, coding conventions भी। एक single input इतना वज़न नहीं उठा सकती।

हल निकला instructions को तीन अलग-अलग layers में तीन files में बांटने से। यह बदलाव करने के बाद sessions के बीच quality का फ़र्क लगभग खत्म हो गया।

एक ही File क्यों Fail होती है

LLM instruction-following पर हुई research में एक pattern सामने आता है जिसे “Curse of Instructions” कहते हैं। जैसे-जैसे एक ही context में directives की संख्या बढ़ती है, हर individual directive का compliance तेज़ी से गिरता जाता है। मैंने इसे खुद test किया: जब मैंने project rules, feature specs और task lists सब कुछ एक ही CLAUDE.md file में भर दिया, तो agent ने file के आखिरी हिस्से की करीब आधी instructions को ignore कर दिया।

यह समझ में आता है अगर आप सोचें कि attention कैसे काम करती है। Mixed concerns से भरा एक लंबा document model को real time में यह decide करने पर मजबूर करता है कि क्या ज़रूरी है। वह गलत trade-offs करता है। Solution यह है कि information को role के हिसाब से अलग करें ताकि हर layer focused रहे।

Layer 1: CLAUDE.md एक Project Constitution की तरह

CLAUDE.md (या आपके agent का equivalent) हर session में automatically load होती है। इसीलिए यह feature-specific instructions रखने की सही जगह नहीं है। इसमें सिर्फ वही चीज़ें होनी चाहिए जो पूरे project में हर जगह सच हों:

• Build commands और tech stack versions
• Folder structure और naming conventions
• Behavioral rules की तीन categories: “हमेशा करो,” “पहले पूछो,” और “कभी मत करो”

मैंने सीखा कि इस file को शुरू से ही सब कुछ से नहीं भरना चाहिए। बजाय इसके, मैंने देखा कि agent कहाँ-कहाँ बार-बार गलतियाँ कर रहा है, और rules को धीरे-धीरे incrementally add किया। यह approach किसी भी upfront specification से बेहतर काम आई।

CLAUDE.md में क्या नहीं रखना चाहिए: API keys (वे stale हो जाते हैं), code snippets (वे real code से drift हो जाते हैं), style rules जो कोई linter पहले से enforce करता है, और किसी single feature से जुड़ी कोई भी चीज़। ये सब अगली layer में जाते हैं।

Layer 2: SPEC.md, क्या और क्यों के लिए

एक spec file एक feature को describe करती है। वह बताती है कि feature क्या करती है, क्यों exist करती है, success criteria क्या हैं, technical constraints क्या हैं, और boundaries कहाँ हैं। बस यही। पाँच sections।

Traditional PRD से यह critical difference है: spec files human review meetings के लिए नहीं बल्कि agent consumption के लिए structured होती हैं। और इनमें जानबूझकर “how” को छोड़ दिया जाता है। Agent को implementation existing codebase analyze करके खुद निकालनी चाहिए, spec में दिए गए step-by-step coding instructions से नहीं।

अच्छी spec लिखने के दो तरीके हैं। पहला: ऊपर बताई गई five-section structure use करके खुद draft करें। दूसरा: agent से खुद interview करवाएं। Interview approach surprisingly अच्छा काम करती है अगर आप दो rules enforce करें: एक बार में एक ही question, और open-ended की जगह multiple-choice prefer करें। इस तरह बनी spec में वे edge cases भी cover हो जाते हैं जो अकेले लिखते वक्त छूट जाते।

Complete specs को docs/specs/YYYY-MM-DD-topic.md में save करें और commit करें। इससे एक trail बनती है जिसे agent git diff से follow कर सकता है, और code reviewers को पता चलता है कि कौन सा decision intentional था और कौन सा accidental।

Layer 3: plan.md, Executable Tasks के लिए

Plan file सबसे narrow layer है। यह spec को ऐसे tasks में तोड़ती है जो हर एक दो से पाँच मिनट में पूरे हों, explicit file paths के साथ और एक fixed execution order में। मैं हर plan को एक TDD cycle से anchor करता हूँ: पहले test लिखो, उसे pass करने के लिए minimum code implement करो, confirm करो कि test pass हुआ, फिर commit करो।

Explicit file paths उससे कहीं ज़्यादा मायने रखते हैं जितना मैंने सोचा था। उनके बिना agent खुद अंदाज़ा लगाता है कि files कहाँ जानी चाहिए, और वे अंदाज़े sessions के बीच बदलते रहते हैं। Paths को pin करने से यह variance खत्म हो जाती है।

वह Session Split जिसने सब कुछ काम कराया

यह वह हिस्सा है जो मुझे महीनों तक नहीं समझ आया। तीन clean files होने के बावजूद quality तब भी गिरती थी जब मैं spec लिखना और implementation एक ही session में करता था। कारण सीधा है: spec लिखते वक्त brainstorming और Q&A context window का एक बड़ा हिस्सा खा जाते हैं। Implementation शुरू होते-होते agent पहले के decisions भूलने लगता है।

हल सरल है। Session 1: SPEC.md लिखो और save करो। Session 2: spec से plan.md generate करो। Session 3 से आगे: एक-एक task execute करो। मैं तब भी नया session शुरू करता हूँ जब context window लगभग आधा भर जाती है। इससे accuracy में जो सुधार आया वह तुरंत दिख गया।

यह सब कहाँ जा रहा है

Agile Manifesto की team ने agent-based software development के लिए एक maturity model publish किया है जो इस layered approach से मेल खाता है:

• Level 1: एक spec लिखो, implement करो, फिर spec को discard कर दो।
• Level 2: Spec को एक living document की तरह रखो जो code के साथ evolve होती रहे।
• Level 3: Spec single source of truth बन जाती है, और code एक generated artifact।

जितने developers से मेरी बात होती है उनमें से ज़्यादातर Level 1 तक भी नहीं पहुंचे। वे अभी भी उस mode में काम कर रहे हैं जहाँ prompt ही एकमात्र input है और code एकमात्र output। छोटे tasks के लिए यह चल जाता है, लेकिन जैसे-जैसे complexity बढ़ती है यह system टूट जाता है।

Level 1 से Level 2 का transition सिर्फ एक habit है: अपनी spec files को Git में commit करो। Level 2 से Level 3 का transition एक workflow change है: जब code modify करना हो, पहले spec update करो और फिर regenerate करो।

आज से शुरू किया जा सकता है। एक CLAUDE.md बनाओ अपने project की basics के साथ, अपने अगले feature के लिए कोई भी code लिखने से पहले एक SPEC.md लिखो, और देखो क्या होता है। फ़र्क तेज़ी से compound होता है।