AIDiveदस developers, एक docs फ़ोल्डर
Superpowers एक Claude Code plugin है (286,000 GitHub stars) जिसके skills specs और implementation plans को markdown फ़ाइलों के रूप में लिखते हैं और उन्हें repository में कमिट कर देते हैं। डिफ़ॉल्ट रूप से इन सभी फ़ाइलों का ठिकाना एक ही फ़ोल्डर होता है, docs/superpowers/। जून में, Python finance library Okama के maintainers को पता चला कि एक एजेंट ने वहाँ जो आठ implementation plans लिखे थे — ठीक उसी तरह कमिट किए गए जैसा plugin चाहता है — वे Read the Docs पर public web pages के रूप में render हो गए थे। उन्हें यह बात release के बाद पता चली।
अब इसे बड़े पैमाने पर सोचें: दस developers की एक front-end टीम, चार squads, एक repository, और हर developer इन फ़ाइलों को generate कर रहा है। लीड के डेस्क पर तीन सवाल आ जाते हैं। हम असल में version किसे करते हैं? क्या drift कोई समस्या है जब कोई spec ऐसे path का नाम लेता है जो दो sprint पहले डिलीट हो चुका है? और फ़ोल्डर को कौन govern करता है? Okama का leak कमिट करने की वजह से नहीं हुआ था। यह एक rule के बिना कमिट करने की वजह से हुआ था। यह लेख आपको पाँच rules देता है।
हर टूल फ़ाइलें कमिट करता है
Superpowers कभी नहीं पूछता कि कमिट करना है या नहीं। इसके planning skill की लाइन 18 हर plan को docs/superpowers/plans/ के नीचे, तारीख़ के साथ, प्रति feature एक फ़ाइल के रूप में सेव करती है। brainstorming skill design document लिखता है और उसे उसी क़दम में कमिट कर देता है, इससे पहले कि आपने plan देखा भी हो।
यह Superpowers की कोई अजीब आदत नहीं है। हर बड़ा spec-driven टूल यही चुनाव करता है:
| Tool | Publisher | Where specs live |
|---|---|---|
| Superpowers (286,000 stars) | obra | docs/superpowers/, one folder for everything |
| Spec Kit (136,000 stars) | GitHub | one numbered folder per feature, on that feature's branch |
| Kiro | Amazon | .kiro/specs/, one folder per feature |
| AI-native SDLC playbook | Anthropic | one committed artifact per stage: intent, spec, plan, diff, review findings, incident record |
Kiro प्रति-feature फ़ोल्डर को इस तरह बेचता है कि साथी एक साथ अलग-अलग features पर collaborate कर सकें। अगस्त में प्रकाशित Anthropic का playbook और आगे जाता है: हर stage एक artifact कमिट करती है जिसे अगली stage पढ़ सकती है। तो सवाल कभी यह नहीं था कि कमिट करना है या नहीं, और कहाँ करना है इसका जवाब हर टूल पहले से देता है। फ़ाइल का मालिक कौन है, और वह कब मर चुकी है, यह तय नहीं है। यही वह ख़ाली जगह है जिसे पाँच rules भरते हैं।
यह ग़लत होने के तीन तरीक़े
कमिट किए गए plans तीन अलग तरीक़ों से नाकाम होते हैं।
नाकामी 1: docs generator। एक documentation build जो docs/ के नीचे हर markdown फ़ाइल को render कर देता है, चाहे table of contents में उसका नाम हो या न हो, plans फ़ोल्डर को मैनुअल के साथ ही भेज देता है। Okama के साथ ठीक यही हुआ था।
नाकामी 2: branch। Superpowers issue 1246 बताता है कि brainstorm plan को सीधे main पर कमिट कर देता है। एक user हर session में 10 से 15 कमिट गिनता है, हर कुछ बदलावों पर एक नई कमिट। थ्रेड की माँग एक लाइन में समा जाती है: main branch पर कोई plans और specs नहीं।
नाकामी 3: drift। Spec drift वह ख़ामोश नाकामी है: code आगे बढ़ता है और spec नहीं बढ़ता। Thoughtworks की Birgitta Böckeler spec-driven development के तीन स्तर बताती हैं:
| Level | Meaning |
|---|---|
| Spec-first | Written, used once |
| Spec-anchored | Kept and maintained for the feature's life |
| Spec-as-source | The human only ever edits the spec |
Superpowers spec-first दस्तावेज़ लिखता है और उन्हें हमेशा के लिए रखता है। डिफ़ॉल्ट रूप से आपको first-draft रखरखाव के साथ spec-anchored storage मिलता है: कोई फ़ाइल को अपडेट नहीं करता, और एक एजेंट अगली तिमाही उसे सच मानकर पढ़ लेता है। TrueFoundry इसे साफ़ शब्दों में कहता है: drift, spec-first practice में अनिवार्य है और spec-anchored practice में संभाला जा सकता है, लेकिन तभी जब divergence पहचाना जा सके।
41 specs और 9 agent फ़ाइलों को रखने वाली repository को साफ़-सफ़ाई की समस्या नहीं है। उसके पास 41 अनवर्ज़न्ड behavior inputs हैं। Böckeler की अपनी प्रतिक्रिया: वे इन सारे markdown फ़ाइलों की बजाय code review करना पसंद करेंगी। एक plan जिसे कोई फिर से नहीं खोलता, बस अव्यवस्था है। एक plan जिसे कोई एजेंट खोलता है, वह एक instruction है, और एक पुराना पड़ चुका instruction ग़लत instruction होता है।
Rule 1: हर squad का एक घर, owners के साथ
Rule 1: फ़ोल्डर का एक owner होता है, और owner एक squad है, plugin नहीं। Version 5 से, Superpowers आपके project के CLAUDE.md की instructions को अपने डिफ़ॉल्ट से ऊपर मानता है। बता दें कि plans कहाँ जाएँगे, और वे वहीं जाएँगे।
हालाँकि सिर्फ़ paths की एक table काफ़ी नहीं है। issue 939 में, एक user ने output-paths की table लिखी, और model ने skill में दिए गए ठोस path को माना और table को नज़रअंदाज़ कर दिया। skill का अपना override नोट एक parenthesis भर है। एक बोल्ड, आदेशात्मक लाइन ने पहली ही कोशिश में इसे ठीक कर दिया: specs यहाँ सेव होने चाहिए, वहाँ नहीं, जिसमें डिफ़ॉल्ट को साफ़ तौर पर टालने वाली चीज़ के रूप में नाम दिया गया हो।
लेआउट है: प्रति squad एक फ़ोल्डर (checkout, search, accounts, design-system), हर एक के अपने specs और plans के साथ। एक monorepo में, यह लाइन package के अपने CLAUDE.md में डालें। Claude Code किसी subdirectory की फ़ाइल को तभी लोड करता है जब वह वहाँ पढ़ता है, और documentation कहती है कि हर directory की अपनी फ़ाइल को आम तौर पर उसका owner बनाए रखता है। जिन engineers ने plugin कभी install ही नहीं किया, उन पर कोई असर नहीं पड़ता: यह लाइन तभी असर करती है जब कोई skill यह पूछता है कि सेव कहाँ करना है।
फिर platform को ownership लागू करने दें। हर squad फ़ोल्डर के लिए एक CODEOWNERS लाइन, और हर spec review उन लोगों तक पहुँचती है जिन्हें उसके साथ रहना है। एक चेतावनी: यह override एक prompt है, setting नहीं। हर plugin release के बाद पहला spec ज़रूर जाँचें।
Rule 2: निजी बनाम साझा
Rule 2: हर plan एक टीम artifact नहीं होता। Superpowers से configurable location माँगने वाले पहले व्यक्ति (issue 337) ने इसे सबसे अच्छे शब्दों में कहा: plan फ़ाइलें project artifacts की बजाय निजी working documents हो सकती हैं।
निजी हिस्से के लिए एक फ़ाइल बनी हुई है। CLAUDE.local.md साझा फ़ाइल के पास ही रहता है, उसके बाद लोड होता है, और documentation कहती है कि इसे आप ख़ुद git-ignore करें। अपने निजी फ़ोल्डर की तरफ़ redirect वहीं रखा जाता है और इसे कोई और नहीं देखता। फ़ोल्डर के लिए ही, Git के पास एक ignore फ़ाइल है जो साझा tree को कभी नहीं छूती: .git/info/exclude प्रति clone होती है, कभी कमिट नहीं होती, और इसके लिए किसी pull request की ज़रूरत नहीं। plugin अपने ही scratch स्पेस के लिए यह पहले से करता है: version 6.0.3 से इसकी working directory अपने भीतर * वाली एक .gitignore गिरा देती है, इसलिए वह किसी tracked फ़ाइल को छुए बिना अपने-आप को ignore कर लेती है।
साझा हिस्सा वह है जो brainstorm द्वारा पहले से चलाए जाने वाले review gate को पार कर गया: spec लिखा गया, review माँगा गया, किसी दूसरे व्यक्ति ने approve किया। Approve होने पर, वह squad फ़ोल्डर में चला जाता है। Approve न होने पर, वह निजी ही रहता है। दोनों एक branch पर लिखे जाते हैं, main पर कभी नहीं। साझा CLAUDE.md में दो लाइनें यह कर देती हैं: specs और plans को feature की शुरुआत मानें, और उन्हें लिखने से पहले worktree बनाएँ।
एक सीमा: एक git-ignore की गई plan साथ नहीं चलती। Okama के maintainers ने पहले फ़ोल्डर को ignore करने की कोशिश की और फिर पलट गए, क्योंकि plans मशीनों और एजेंट्स के बीच sync होना बंद हो गए थे। निजी मतलब निजी।
Rule 3: एक lifecycle, ADRs जैसा
Rule 3: एक spec की एक status होती है, और एक मर चुका spec यह बता देता है। यह विचार 15 साल पुराना है। Michael Nygard ने 2011 में architecture decision records (ADRs) को repository में रखने का सुझाव दिया, हर एक अपनी नंबर वाली फ़ाइल में। एक decision proposed होता है, फिर accepted। जब कोई बाद की record उसे बदलती है, तो पुरानी record को उसके replacement के reference के साथ deprecated या superseded मार्क कर दिया जाता है। अगर कोई decision पलट दिया जाता है, तो पुरानी record रखी जाती है पर superseded मार्क की जाती है।
specs पर लागू करें तो, हर साझा spec एक पाँच-लाइन header से खुलता है जिसे एजेंट पहले से पढ़ता है:
| Field | Purpose |
|---|---|
| status | proposed, accepted, superseded |
| superseded-by | the replacing spec |
| owner | the squad |
| touches | the paths the spec makes claims about |
| review date | when it was last checked |
एक accepted spec को कभी किसी दूसरे decision में एडिट न करें। अगला वाला लिखें, उसे पीछे point करें, और history सच्ची रहती है। एक अपवाद, Anthropic के playbook में बताया गया: जब implementation plan से हट जाए, तो उसी कमिट में plan को अपडेट करें। plan उस diff के साथ चलता है जिसने उसे तोड़ा, और एक hook इसे लागू कर सकता है।
Spec Kit एक spec के जीने के तीन तरीक़े बताता है। Flow-forward: प्रति feature एक नया फ़ोल्डर, पुराने history के रूप में रखे जाते हैं। Living spec: spec ही contract है और बाक़ी सब regenerate होता है। Flow-back: build spec को दोबारा आकार देता है। उनका rule यह है कि tasks या code में कोई बदलाव तब न छोड़ें जब spec अब भी कुछ अलग कहता हो। यह जान-बूझकर spec-anchored चुनना है।
सीमा यह है: status एक metadata है जिसे एक इंसान सेट करता है। एजेंट अपने ही spec को superseded मार्क नहीं करेगा जब तक आपका CLAUDE.md उसे न कहे, और तब भी review को यह नोटिस करना पड़ता है।
Rule 4: CI में एक drift gate
Rule 4: एक spec जो tree के बारे में झूठ बोलता है, build को fail कर दे। जिस paper ने इस समस्या को नाम दिया, जून में प्रकाशित, इसे silent spec-code drift कहता है: code आगे बढ़ता है, specification नहीं, और divergence तब तक अदृश्य रहता है जब तक उसे ठीक करना महँगा न हो जाए। इसका जवाब है एक drift gate, एक blocking merge condition।
check सुनने में जितना बड़ा लगता है, उतना है नहीं। हर वैसे spec के लिए जिसका header accepted कहता है, उसमें नाम लिए गए paths निकालें — backticks में या touches लाइन में — और जाँचें कि हर एक मौजूद है। ग़ायब path, फ़ेल होता build, log में spec के नाम के साथ। Superseded और proposed फ़ाइलें छोड़ दी जाती हैं: सिर्फ़ accepted specs tree के बारे में दावे करते हैं, तो सिर्फ़ accepted specs जाँचे जाते हैं। TrueFoundry इसे post-incident archaeology की बजाय एक scheduled diff के रूप में देखता है: एक spec scaffold है, और एक spec बदलाव एक policy बदलाव है।
लोग पहले से ही इसका मैनुअल version चला रहे हैं। एक commenter ने Claude से spec फ़ाइलों की codebase से तुलना करवाई और जो कुछ गायब था उसके लिए tickets फ़ाइल किए। यह script हर pull request पर वही काम मुफ़्त में करता है।
दूसरा गार्ड वही है जो Okama ने shipped किया: फ़ोल्डर को docs build से exclude करें। Sphinx configuration में एक लाइन फ़ाइलों को Git में रखती है पर HTML से बाहर।
सीमा: path check डिलीट हुई फ़ाइलों को पकड़ता है, बदले हुए behavior को नहीं। एक spec हर मौजूद फ़ाइल का नाम ले सकता है और फिर भी एक ऐसे API का वर्णन कर सकता है जो अब है ही नहीं। यही वजह है कि review और same-commit rule ज़रूरी हैं।
Rule 5: एक size budget, और लागत
Rule 5: ज़्यादातर काम को spec की ज़रूरत नहीं होती। spec-driven overhead के सबूत लगातार एक ही बात कहते हैं:
| Experiment | Result |
|---|---|
| Marmelab, Spec Kit on a feature that shows the current date | 8 files, 1,300 lines of specification text |
| OpenSpec bake-off, same requirements with a spec tool vs Claude Code alone | 50% more code, 50% more cyclomatic complexity, twice as long, three times the cost |
| A team running spec-driven development for months | 2 to 3 times the tokens, about twice as long, large coordination cost for changes that needed none; no proof the code improved |
bake-off एक experiment है, कोई benchmark नहीं, और इसके लेखक ख़ुद यह कहते हैं। पर दिशा वही रहती है। तो rule यह है: spec तब लिखें जब काम किसी squad boundary को पार करे या 90 दिनों में फिर से पढ़ा जाएगा। बाक़ी सब एक prompt है।
Superpowers पहले से हर request को तीन रास्तों में बाँट देता है: spike, bounded, architectural। सिर्फ़ architectural रास्ता spec लिखता है। bounded रास्ते को bounded ही रखें, और spec को लगभग 300 लाइनों के पास रखें। Practitioners दो लाइनें और जोड़ते हैं: spec को बहुत बड़ा न बनाएँ, और generate हुए specs को पढ़ें।
सीमा दोनों तरफ़ काटती है। उसी bake-off ने तीन gaps पाए जो plain run से छूट गए थे। spec coverage ख़रीदता है, speed नहीं। इसका भुगतान वहाँ करें जहाँ coverage मैटर करती है।
फ़ैसला: कमिट करें, फिर govern करें
लीड के तीन सवालों पर वापस। हम क्या version करते हैं: approved specs और plans, एक branch पर, squad के फ़ोल्डर में। Drift: एक status header और एक CI gate। Governance: owners और एक size rule।
पाँच rules, और इनमें से किसी को आज कोई टूल लागू नहीं करता। override वाला issue खुला है। main-branch वाला issue खुला है। जिस pull request ने instruction को दोबारा क्रम में रखा था, वह merge हुए बिना बंद कर दिया गया। जो टीम burn हुई थी उसने practice को बनाए रखा: 8 plans और 6 specs, कमिट किए गए, docs build से exclude किए गए।
Böckeler की आपत्ति अब भी खड़ी है। एक status header और एक size budget के साथ, आप सिर्फ़ accepted specs पढ़ते हैं, और उनमें से कम। जो आप वापस पाते हैं वह वही है जिसे Anthropic का playbook audit trail कहता है: किसने क्या माँगा, एजेंट ने क्या बनाया, और किसने approve किया।
यह process है, tooling नहीं: एक CLAUDE.md फ़ाइल, एक CODEOWNERS फ़ाइल, एक header, और एक पंद्रह-लाइन script। और अगर टीम एक CODEOWNERS request को review नहीं करेगी, तो वह एक spec को भी review नहीं करेगी। उस स्थिति में, .gitignore ही ईमानदार चुनाव था।
