AIDive

वीडियो पैक

Git में AI specs और plans का governance: पांच नियम, drift gate, स्रोत और checklist

11 मिनट पढ़ें

TL;DR

  • AI से लिखे specs और plans को commit करें। हर tool यह पहले से default में करता है; असली सवाल governance का है।
  • हर squad को एक folder और एक CODEOWNERS लाइन दें, ताकि spec बदलने पर कोड के owners से review मांगा जाए।
  • हर साझा spec पर ADR-शैली का header लगाएं: status, superseded-by, owner, छुए गए paths, review की तारीख। accepted spec को कभी नए फैसले में दोबारा न लिखें।
  • CI में drift gate चलाएं: हर accepted spec के लिए, अगर उसमें नामित कोई path अब मौजूद नहीं है तो build fail करें।
  • CLAUDE.md में एक bold imperative लाइन से output path बदलें, निजी plans CLAUDE.local.md और .git/info/exclude में रखें, और branch पर लिखें, main पर कभी नहीं।
  • Spec सिर्फ उस काम के लिए बनाएं जो squad की सीमा पार करता है या 90 दिन में दोबारा पढ़ा जाएगा। Spec-driven runs में लगभग दोगुना समय और तीन गुना tokens लगते हैं।

स्रोत क्या कहते हैं

Defaults: सब commit करते हैं

Superpowers का writing-plans skill plans को docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md में सहेजता है, और नीचे एक लाइन कहती है कि plan की जगह पर user की पसंद इस default को override करती है s1। Brainstorming skill validated design को docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md में लिखता है और "Commit the design document to git" पर खत्म होता है s2। Spec Kit specs/[branch-name]/ बनाता है जिसमें spec.md, plan.md और tasks.md होते हैं, 001, 002 क्रमांक के साथ, और memory/constitution.md में एक constitution s6। Kiro .kiro/specs/ रखता है, हर feature के लिए एक folder, और teams को "collaborate with team members on different features simultaneously" का न्योता देता है s8। Anthropic का playbook साफ है: "Every stage commits an artifact the next stage can read", "Commit the approved plan as plan.md", और "When implementation departs from the plan, update plan.md in the same commit" s5।

इनमें से कोई दस्तावेज़ नहीं बताता कि committed spec का मालिक कौन है या वह कब सच नहीं रहता। तीनों दर्ज विफलताएं इसी खाली जगह में होती हैं।

विफलता 1: सार्वजनिक leak

Issue 1690, 2026-06-05 को खुला, बताता है कि default docs/superpowers/ जगह Sphinx और Read the Docs के ज़रिए internal plans को प्रकाशित documentation में leak कर सकती है s15। प्रभावित प्रोजेक्ट okama था, 273 stars वाली एक Python library। उसके fix commit ने 5 plans और 3 specs वापस जोड़े, एक .gitignore लाइन हटाई और लिखा "track superpowers plans/specs in git, excluded from the Sphinx build" s21। docs/conf.py की लाइन 84 में अब exclude_patterns = ["_build", "Thumbs.db", "superpowers"] है s22। आज folder में 8 plans और 6 specs हैं s15। टीम ने practice रखी और build ठीक किया।

विफलता 2: main पर plans

Issue 1246, 2026-04-22 को खुला और अभी भी खुला है, पूछता है कि development branch बनने से पहले plan क्यों commit होता है। एक user लिखता है "I'm getting 10 to 15 commits"; दूसरा: "Yes please, no plans and specs on main branch!" s16। Plugin कोई branch नियम लागू नहीं करता; नीचे की checklist करती है।

विफलता 3: जो overrides model छोड़ देता है

Issue 337 2026-03-10 को बंद हुआ, maintainer के नोट के साथ कि v5.0 से plugin अपने defaults से ऊपर आपके प्रोजेक्ट के CLAUDE.md को मानता है, उदाहरण लाइन: "Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17। v5.0.6 पर Issue 939 सीमा दिखाता है: CLAUDE.md की "Output Paths" तालिका अनदेखी हुई और specs docs/superpowers/specs/ में ही गिरते रहे। जो workaround चला वह तालिका के नीचे एक bold imperative लाइन थी: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18। Pull request 1020, जिसने निर्देश का क्रम बदला, बिना merge के बंद हुआ s19। Override एक prompt है, setting नहीं: हर plugin release के बाद दोबारा जांचें। Plugin की अपनी scratch files के लिए, issue 1780 v6.0.3 से बंद हुआ, एक self-ignoring .superpowers/sdd/ folder के साथ जो * वाली अपनी .gitignore खुद रखता है s20।

निजी बनाम साझा

Claude Code यह बंटवारा दर्ज करता है: "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed" s3। हर directory की CLAUDE.md फाइलें ज़रूरत पर load होती हैं, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file", और claudeMdExcludes setting monorepo में दूसरी teams की फाइलें छिपाती है s4। Git तीन ignore परतें देता है, $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude और .gitignore s24; बीच वाली परत साझा फाइल को छुए बिना निजी plans folder छिपाती है। CODEOWNERS स्वामित्व का हिस्सा संभालता है: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23।

Lifecycle, ADRs की तरह

Michael Nygard का 2011 का पोस्ट टेम्पलेट है: एक फैसला "may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement", और "If a decision is reversed, we will keep the old one around, but mark it as superseded" s9। Thoughtworks spec के उपयोग को spec-first (काम के लिए एक बार लिखा), spec-anchored (feature के विकास के लिए रखा गया) और spec-as-source (सिर्फ spec संपादित होता है) में बांटता है, और इसके लेखक जोड़ते हैं: "I'd rather review code than all these markdown files" s10। Superpowers spec-first फाइलें लिखता है और उन्हें हमेशा रखता है: default रूप से drift।

Drift और gate

arXiv पेपर समस्या को "silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair" नाम देता है और "a drift gate that makes spec-code divergence a blocking merge condition" सुझाता है s11। Spec Kit की अपनी guide चेताती है: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7। TrueFoundry governance का तर्क सीधे रखता है: "forty-one specs and nine agent files aren't a tidiness problem", वे "forty-one unversioned behavior inputs and nine competing standing policies" हैं, और drift "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable"। वही पोस्ट प्रति spec लगभग 300 लाइनें और 150 से 200 standing instructions का बजट सुझाता है s13। एक practitioner manual संस्करण बताता है: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26।

इसकी कीमत

प्रयोग नतीजा स्रोत
आज की तारीख दिखाने वाले feature पर Spec Kit 8 फाइलें और 1,300 लाइनें टेक्स्ट s14
OpenSpec bake-off, वही requirements, spec tool बनाम सादा Claude Code OpenSpec ने 3 और gaps पकड़े; 50% ज़्यादा कोड और 50% ज़्यादा cyclomatic complexity; दोगुना समय और तीन गुना लागत s12
महीनों तक spec-driven development चलाने वाली टीम "two to three times as many tokens and take about twice as long"; कोड बेहतर होने का कोई सबूत नहीं s25

Bake-off एक ही प्रयोग है और इसका लेखक खुद यह कहता है, पर तीनों में दिशा एक ही है। तो: architectural रास्ते का spec बनाएं, सीमित रास्ते को सीमित रखें, और practitioners की दोहराई जाने वाली दो बातें मानें, "don t spec too big / read the generated specs" s26।

सोमवार को यह करें

  • हर squad के लिए docs/specs/<squad>/ बनाएं और हर folder के लिए उस squad के reviewers की ओर इशारा करती एक CODEOWNERS लाइन जोड़ें।
  • प्रोजेक्ट के CLAUDE.md में एक bold imperative लाइन जोड़ें: plans और specs MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/। एक brainstorm चलाएं और देखें फाइल कहां गिरी।
  • निजी plans को .git/info/exclude में दर्ज folder में ले जाएं और हर developer की पसंद CLAUDE.local.md में रखें, जो खुद भी ignored हो।
  • हर साझा spec पर header लगाएं: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by।
  • Drift gate लिखें: status: accepted वाले हर spec के लिए, उसमें नामित paths निकालें और कोई गायब हो तो pull request fail करें। लगभग पंद्रह लाइनों का shell या Python।
  • Branch नियम जोड़ें: pull request के बाहर कोई spec या plan commit main पर न उतरे।
  • अगर repo Sphinx या ऐसे किसी tool से docs प्रकाशित करता है, तो specs folder को आज ही exclude_patterns में जोड़ें।
  • आकार का बजट तय करें: spec लगभग 300 लाइनों का रहे, और सिर्फ वही काम spec पाए जो squad की सीमा पार करता है या 90 दिन में दोबारा पढ़ा जाएगा।

आगे पढ़ें

  • Header योजना चुनने से पहले spec के तीन उपयोग वर्ग (spec-first, spec-anchored, spec-as-source) पढ़ें; lifecycle सिर्फ spec-anchored फाइलों के लिए मायने रखता है s10।
  • arXiv पेपर path जांच से आगे पूरी drift-enforced architecture तक जाता है; तब काम का जब पंद्रह लाइन का gate मोटा लगने लगे s11।
  • Spec Kit की guide विकास के तीन flows (Flow-Forward, Living Spec, Flow-Back) बताती है जो same-commit नियम से मेल खाते हैं s7।
  • Playbook plan और diff को sync रखने के लिए hook सुझाता है; उस पर Reddit thread में 43 points और field reports वाले 27 comments हैं s5, s27।
  • TrueFoundry का तर्क कि spec बदलना policy बदलना है, इसलिए उसे run metadata वाले eval gate के पीछे होना चाहिए, CI path जांच के बाद का अगला कदम है s13।
  • दो खुले issues, 1246 (main पर plans) और 939 (अनदेखे overrides), पर नज़र रखें; जब इनमें से कोई बंद होगा, इस pack का एक नियम plugin का default बन जाएगा s16, s18।
  • Marmelab का पूरा लेख समझाता है कि 1,300 लाइनें क्यों बनीं और Spec Kit कहां सचमुच काम आता है s14।

स्रोत

  • Superpowers writing-plans skill, GitHub. क्यों पढ़ें: सटीक default path और वह एक लाइन का override clause जिस पर आप निर्भर हैं।
  • Superpowers brainstorming skill, GitHub. क्यों पढ़ें: specs कहां गिरते हैं और उन्हें commit करने वाला कदम।
  • Claude Code memory, Anthropic. क्यों पढ़ें: निजी पसंद के लिए CLAUDE.local.md मान्य जगह है।
  • Claude Code: working in large codebases, Anthropic. क्यों पढ़ें: monorepos के लिए हर directory की फाइलें, owners और claudeMdExcludes।
  • The AI-native SDLC playbook, Anthropic. क्यों पढ़ें: vendor की ओर से audit-trail का तर्क और same-commit नियम।
  • Spec Kit repository, GitHub. क्यों पढ़ें: प्रति-squad layout से तुलना के लिए प्रति-branch spec layout।
  • Spec Kit: evolving specs, GitHub. क्यों पढ़ें: इस बात का सबसे साफ बयान कि spec और कोड में मतभेद नहीं होना चाहिए।
  • Kiro specs best practices, Kiro. क्यों पढ़ें: समानांतर squads के लिए बना feature-folder layout।
  • Documenting architecture decisions, Michael Nygard. क्यों पढ़ें: header जो status शब्दावली उधार लेता है।
  • Spec-driven development: the tools, Thoughtworks. क्यों पढ़ें: spec-first बनाम spec-anchored का फर्क जो तय करता है क्या रखना है।
  • The Spec Growth Engine, arXiv. क्यों पढ़ें: blocking drift gate का औपचारिक तर्क।
  • OpenSpec bake-off discussion, GitHub. क्यों पढ़ें: अगल-बगल लागत के इकलौते आंकड़े, लेखक की अपनी चेतावनियों के साथ।
  • Spec-driven development for AI agents, TrueFoundry. क्यों पढ़ें: versioned policy के रूप में specs, और 300 लाइन का बजट।
  • Spec-driven development: waterfall strikes back, Marmelab. क्यों पढ़ें: एक मामूली feature के लिए 1,300 लाइनों का spec कैसा दिखता है।
  • Superpowers issue 1690, GitHub. क्यों पढ़ें: leak की रिपोर्ट, कदम दर कदम।
  • Superpowers issue 1246, GitHub. क्यों पढ़ें: main branch की शिकायत, अभी खुली।
  • Superpowers issue 337, GitHub. क्यों पढ़ें: maintainer का बयान कि v5.0 से CLAUDE.md जीतता है।
  • Superpowers issue 939, GitHub. क्यों पढ़ें: जो override नाकाम रहा और जो शब्दावली चली।
  • Superpowers pull request 1020, GitHub. क्यों पढ़ें: fix की कोशिश, बिना merge बंद।
  • Superpowers issue 1780, GitHub. क्यों पढ़ें: plugin अपना scratch folder खुद कैसे ignore करता है।
  • okama fix commit, GitHub. क्यों पढ़ें: एक असली टीम जिसने specs रखे और उन्हें build से बाहर किया।
  • okama docs/conf.py, GitHub. क्यों पढ़ें: कॉपी करने लायक एक लाइन का Sphinx exclusion।
  • About code owners, GitHub Docs. क्यों पढ़ें: review-request तंत्र जिस पर स्वामित्व नियम टिका है।
  • gitignore documentation, Git. क्यों पढ़ें: info/exclude वह निजी ignore परत है जिसे ज़्यादातर developers भूल जाते हैं।
  • We tried spec-driven development for months, Reddit r/SpecDrivenDevelopment. क्यों पढ़ें: टीम-स्तर की लागत रिपोर्ट, पीछे कोई vendor नहीं।
  • Does spec-driven development actually work for you?, Reddit r/ClaudeCode. क्यों पढ़ें: रोज़ के users से आकार और spec पढ़ने की सलाह।
  • Has anyone tried Anthropic's AI-native SDLC playbook?, Reddit r/ClaudeCode. क्यों पढ़ें: असली repos में playbook की field reports।

FAQ

क्या पहले दिन से पांचों नियम चाहिए?

नहीं। CLAUDE.md का redirect और Sphinx exclusion दस मिनट का काम हैं। CODEOWNERS और header तब जोड़ें जब कोई spec पहली बार squads के पार जाए, और drift gate तब जब कोई accepted spec एक sprint पुराना हो जाए।

Drift gate क्या चूक जाता है?

बदला हुआ व्यवहार। वह सिर्फ देखता है कि नामित path अब भी मौजूद है, इसलिए उलटी condition निकल जाती है। इसे same-commit नियम और review के साथ जोड़ें।

बस folder को gitignore क्यों न कर दें?

क्योंकि बाद में spec पढ़ने वाले agent को उसकी ज़रूरत होती है, और audit trail तभी चलता है जब बीच की कड़ियां versioned हों। okama टीम ने gitignore आज़माया और build exclusion के साथ commit करने पर लौट आई।