Claude Code और Codex इस्तेमाल करने से पहले तीन Spec Files बनाएँ

AI coding agents को रोज़ाना लगभग एक साल तक इस्तेमाल करने के बाद, hallucinated code या गलत APIs से ज़्यादा inconsistency ने परेशान किया। वही task, थोड़ी अलग phrasing के साथ, एक दिन clean output देता और अगले दिन गड़बड़ी। लंबी sessions में यह और बिगड़ता जाता क्योंकि agent बीस messages पहले की गई agreements भूल जाता था।

असली वजह structural थी। Sessions के बीच agent को intent communicate करने का कोई framework नहीं था, इसलिए हर conversation zero से शुरू होती थी और unpredictable directions में भटक जाती थी।

तीन layers जिन्होंने result बदल दिया

Instructions को तीन files में बाँटना, हर एक के अलग role के साथ, consistency की problem लगभग रातोरात fix हो गई।

Layer 1, CLAUDE.md हर session में automatically load होता है। इसमें project-level constants होते हैं: build commands, tech stack versions, folder structure, coding conventions, और behavioral boundaries (हमेशा X करो, Y से पहले पूछो, Z कभी मत करो)।

Layer 2, SPEC.md किसी specific feature का क्या और क्यों capture करता है। Purpose, requirements, success criteria, technical constraints, और scope boundaries। Implementation details का कोई ज़िक्र नहीं।

Layer 3, plan.md एक spec को दो-से-पाँच मिनट के executable tasks में तोड़ता है, explicit file paths, test-first ordering, और commit checkpoints के साथ।

सब कुछ एक file में ठूँसने से काम क्यों नहीं चलता

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

Role के हिसाब से अलग करने से यह solve हुआ। Agent Layer 1 से universal rules, Layer 2 से feature intent, और Layer 3 से execution steps पढ़ता है। हर file इतनी छोटी रहती है कि model उस पर पूरा ध्यान दे सके।

CLAUDE.md तब बेहतर काम करता है जब lean रहे

चूँकि यह file हर session में load होती है, इसमें सिर्फ वही होना चाहिए जो universally apply हो। Build commands, stack versions, folder layout, naming conventions। एक three-tier boundary add करें: हमेशा करने वाली चीज़ें, पहले पूछने वाली चीज़ें, कभी न करने वाली चीज़ें।

जो approach काम आई वो थी minimal से शुरू करना और हर बार जब agent कोई गलती दोहराए तो rules incrementally add करना। Upfront comprehensive CLAUDE.md लिखने की कोशिश ने bloat पैदा किया जिसने वही compliance drop trigger किया जिससे बचने की कोशिश थी।

कुछ specific traps: API keys या code snippets यहाँ मत डालें क्योंकि ये जल्दी stale हो जाते हैं। Linter जो rules already enforce करता है उन्हें duplicate मत करें। और single feature के लिए specific कुछ भी Layer 2 में move कर दें।

Spec Files का focus “क्या” और “क्यों” पर हो, “कैसे” agent पर छोड़ें

Traditional PRD से फ़र्क यह है कि ये specs agent consumption के लिए structured होती हैं। पाँच sections काफी हैं: purpose, requirements, success criteria, technical constraints, और boundaries।

Implementation decisions agent पर छोड़ें। वो existing codebase analyze कर सकता है और सही approach चुन सकता है। जब मैंने “कैसे” dictate करने की कोशिश की, तो agent या तो blindly follow करते हुए existing patterns से conflict में फँस गया, या फिर पूरी तरह ignore कर दिया।

Manually specs लिखने का एक alternative: agent से interview करवाएँ। दो rules set करें — एक समय में एक सवाल और जब भी possible हो multiple-choice। इस तरह बनी specs में खुद से scratch पर लिखी specs से कम gaps थे।

Completed specs को docs/specs/YYYY-MM-DD-topic.md में save करें और Git में commit करें। इससे agent को git diff के ज़रिए spec change history तक access मिलती है, और reviewers को code changes के पीछे की intent का record मिलता है।

Session Separation सबसे ज़्यादा overlooked practice है

Spec लिखते वक्त brainstorming और Q&A context window का बड़ा हिस्सा खा जाते हैं। उसी session से सीधे implementation में कूदना मतलब agent धीरे-धीरे earlier context तक access खोता जाता है।

मैंने तीन sessions में restructure किया: Session 1 SPEC.md बनाता है, Session 2 plan.md create करता है, Session 3 से tasks एक-एक करके execute होते हैं। पहले हफ्ते के अंदर accuracy improvement नज़र आई।

तीन habits जिन्होंने यह काम करवाया: हर task में explicit file paths लिखना ताकि agent guessing बंद करे, TDD ordering (test first, implement, verify, commit) को plan.md में lock करना, और जब भी context usage लगभग 50% हो जाए नई session शुरू करना।

Maturity Model Spec-as-Source की तरफ इशारा करता है

Martin Fowler की team ने हाल ही में agent-based software development के लिए तीन levels का maturity model define किया। Level 1: spec लिखो, implement करो, spec फेंक दो। Level 2: spec को code के साथ living document के रूप में maintain करो। Level 3: spec single source of truth बन जाती है, और code एक generated artifact होता है।

मेरी जान-पहचान के ज़्यादातर teams और लोग अभी Level 1 तक नहीं पहुँचे हैं। वो one-shot prompts भेजते हैं और बेहतर की उम्मीद रखते हैं।

Level 1 से Level 2 तक जाने के लिए एक habit चाहिए: spec files को Git में commit करें। Level 2 से Level 3 का मतलब है code बदलने से पहले spec update करना। आज आप जो सबसे छोटा कदम उठा सकते हैं वो है अपने project के लिए CLAUDE.md बनाना और अगली feature से पहले SPEC.md लिखना।