Spec-Driven Development: Crash Course

13 concepts · what पर agree करें, फिर how generate करें

आप AI से कुछ build करने को कहते हैं। वह आपको ऐसा code लौटाता है जो देखने में सही लगता है। आप उसे run करते हैं। वह टूट जाता है। या उससे भी बुरा: वह चलता है, लेकिन आपके मन वाली problem से थोड़ी अलग problem solve करता है। फिर आप दोबारा explain करते हैं। AI वह हिस्सा fix करता है और चुपचाप कोई ऐसी चीज़ undo कर देता है जो दो messages पहले सही थी। एक घंटे बाद आपके पास code का ढेर होता है जिस पर आप पूरी तरह trust नहीं करते और जिसे cleanly change नहीं कर सकते।

इस loop का नाम है: vibe coding। आप AI को vague idea देते हैं और उम्मीद करते हैं कि वह सही guess करेगा। Throwaway prototype के लिए यह ठीक है। लेकिन जिस चीज़ को आप keep, deploy, या किसी और को hand off करना चाहते हैं, उसके लिए यह trap है।

Spec-Driven Development (SDD) इस trap से बाहर निकलने का रास्ता है। आप जो चाहते हैं उसे hopeful अंदाज़ में describe करने के बजाय लिखते हैं, इतना clear कि code बनने से पहले आप और AI दोनों agree कर लें। यह written agreement spec है। Code वह चीज़ बनता है जो spec produce करती है, उलटा नहीं।

यह course discipline को end to end cover करता है। अंत तक आप full spec-driven build खुद तीन तरीकों से run कर पाएँगे: claude.ai में, यानी web app और यहाँ आपका main tool; Claude Code में; और OpenCode में। वही discipline तीनों पर transfer होती है।

SDD में spec source of truth है, और code build output है। इस course का हर concept बेहतर spec लिखने, उस पर जल्दी agree करने, या project grow होने पर उसे true रखने का तरीका है।

Practice में agentic coding already इसी तरह काम करती है

इस बात को faith पर लेने की ज़रूरत नहीं। Anthropic के 2026 analysis ने लगभग 400,000 agentic coding sessions में clear division of labor पाया: लोग ज़्यादातर planning decisions करते हैं, यानी क्या build करना है; agent ज़्यादातर execution decisions करता है, यानी कैसे build करना है। और session की success का strongest predictor coding skill नहीं था; domain expertise था: इंसान ने work को कितनी precision से frame किया, agent से क्या verify कराया, और drift होने पर उसे वापस कैसे steer किया। SDD वह discipline है जो आपको उस half में अच्छा बनाती है जो आपके पास रहता है। Anthropic की Agentic coding and persistent returns to expertise देखें।

लगभग 400,000 sessions में what/how split (Anthropic, 2026). SDD वह discipline है जिससे आप planning half में बेहतर होते हैं।

Prerequisite: AI Prompting in 2026

उस course ने आपको AI से बात करना सिखाया: context देना, clear ask करना, work check करना। यह course सिखाता है कि किसी भी ask से पहले क्या करना है: fuzzy idea को ऐसी written spec में कैसे बदलना है जिससे build किया जा सके। यह Agentic Coding Crash Course के साथ naturally pair होता है, जो coding tools को depth में समझाता है।

इसके लिए programmer होना ज़रूरी नहीं​

SDD thinking discipline है, coding skill नहीं। आप इसे लगभग पूरी तरह plain language में, normal chat window में practice करते हैं। Output एक clearly written document होता है, फिर उससे बना हुआ working result: app, script, report generator, या automation। अगर आप capable colleague के लिए clear brief लिख सकते हैं, तो spec लिख सकते हैं। (यह अब developer-only skill नहीं रही; इसके लिए Code You Never Write देखें।)

Study इस बात को concrete बनाती है: coding background ने session success को barely change किया; domain expertise ने किया। आपसे code लिखने को नहीं कहा जा रहा; आपसे कहा जा रहा है कि अपनी problem को इतना अच्छी तरह जानें कि उसे लिख सकें: rules, edge cases, "done" का मतलब। Spec वह जगह है जहाँ आपकी expertise जाती है। वह accountant जो हर reconciliation rule state कर सकता है, उस developer से बेहतर build कराता है जो books नहीं समझता, क्योंकि spec knowledge carry करती है और agent code supply करता है।

---

तीन tools, एक discipline​

नीचे दी गई हर चीज़ तीन tools में काम करती है। हम claude.ai से lead करते हैं क्योंकि इसे install नहीं करना पड़ता, browser में real spec-driven work आज ही हो सकता है, और chat-and-document loop thinking को visible बनाता है। यही moves दोनों coding agents पर cleanly map होते हैं।

	claude.ai (main)	Claude Code	OpenCode
What it is	The web/desktop chat app	Anthropic's coding agent (terminal/IDE)	Open-source coding agent, any model
Where the spec lives	An Artifact (an editable doc beside the chat) in a Project (a saved workspace)	Files in your repo (CLAUDE.md, specs/)	Files in your repo (AGENTS.md, specs/)
Best for	Thinking, drafting, non-coders, getting started	Building real software, end-to-end	Same, with model choice and cost control
Alternatives	ChatGPT (Projects + Canvas) and Gemini (Gems + Canvas) run the same discipline	(none)	(none)

यह course क्या cover करता है​

Part	Topic	आप क्या सीखते हैं
1	The Shift	Vibe coding क्यों fail होती है, spec असल में क्या है, SDD के तीन levels
2	The Method	Constitution, फिर चार phases: Research → Specify → Clarify → Build
3	The Three Ways	claude.ai, Claude Code, और OpenCode में loop run करना
4	A Complete Worked Example	एक feature, start to finish, claude.ai फिर Claude Code में
5	Judgment	SDD कब worth it है, कब overkill, और spec को alive कैसे रखना है

15-minute spine (अगर आपके पास सिर्फ़ कुछ minutes हैं)

अगर आप नए हैं और time कम है तो Concept 1 (vibe coding क्यों fail होती है), Concept 2 (spec product है), Concept 7 (Clarify by interview), Part 2 के आखिर का four-prompt block, और Part 4 का worked example पढ़ें। यह minimal viable read है; बाकी later deepen करता है। जब discipline सच में आपकी बनानी हो तो आख़िर की Practice ladder पर जाएँ। यह split खुद SDD move है: spine spec है, बाकी plan।

---

Part 1: The Shift​

तीन ideas AI के साथ काम करने का आपका तरीका reframe करते हैं। इन्हें समझ लें, बाकी mechanics है।

1. Vibe coding vs. spec-driven development​

फर्क यह है कि आप thinking कब करते हैं।

Vibe coding में आप AI के build करते हुए सोचते हैं, यानी वह जो देता है उस पर react करके discover करते हैं कि आप असल में क्या चाहते थे। यह fast लगता है: screen पर तुरंत कुछ आ जाता है। लेकिन हर round trip थोड़ा context खो देता है, AI gaps को reasonable-but-wrong assumptions से fill करता है, और result अक्सर आपके project के बाकी हिस्से से match नहीं करता। Cost बाद में एक साथ आती है, जब आप चीज़ को change या trust करने की कोशिश करते हैं।

Spec-driven development में आप पहले सोचते हैं और उसे लिखते हैं। AI build शुरू नहीं करता जब तक आप दोनों agree न कर लें कि "done" का मतलब क्या है। Build फिर mostly mechanical होती है: वह agreement execute कर रही होती है, guess नहीं।

दो loops: vibe coding prompt, code और "not quite" के बीच घूमती है; SDD पहले spec बनाता है, फिर उसके against short build-and-check loop चलाता है।

यह prompting में सीखी हुई same move है (context first, then ask), लेकिन stakes ज़्यादा हैं: AI अब सिर्फ़ question answer नहीं कर रहा, आपके project में code लिख रहा है।

Rule of thumb: अगर result फेंकना आपको annoying लगे, तो आप vibe coding के safe point से आगे निकल चुके हैं। Spec लिखें।

2. The spec is the product; code is a build output​

यह mental flip है जिससे SDD को अपना नाम मिलता है। दशकों तक spec code की सेवा करती थी: आप brief लिखते, चीज़ build करते और brief discard कर देते। SDD इसे उलट देता है। Spec वह durable artifact है जिसे आप maintain करते हैं; code उससे generate होता है, और spec बदलने पर फिर generate होता है। "Re-generated" का मतलब magic compile button दबाना नहीं: updated spec पर build loop फिर चलाना और result review करना। Spec एक imperfect agent को guide करती है जिसे आप अब भी supervise करते हैं।

Inversion: पुराना तरीका spec को code का scaffolding मानता है; SDD spec को source of truth और code को re-derivable output बनाता है।

अच्छी spec तीन सवालों का जवाब देती है, इसी order में:

1. Why: हम कौन सी problem solve कर रहे हैं, और किसके लिए? (वह चीज़ जो ज़्यादातर vibe sessions कभी state नहीं करते।)
2. What: done होने पर क्या true होना चाहिए? Behaviours, inputs, outputs, rules, edge cases, और explicitly क्या out of scope है।
3. What not to build: boundaries. यह single section ज़्यादातर "इसने बहुत ज़्यादा कर दिया / ग़लत चीज़ कर दी" failures रोकता है।

Notice करें क्या missing है: how. Spec behaviour describe करती है, implementation नहीं। "Users forgotten password को 30 minutes में expire होने वाले emailed link से reset कर सकते हैं" spec है। "JWT और Postgres tokens table use करें" implementation है, और plan में आता है, जो later phase है। दोनों को बहुत जल्दी mix करना beginner की सबसे common mistake है: आप behaviour agree करने से पहले technical choice lock कर देते हैं।

Spec की हर line का test

पूछें: "क्या कोई competent person इस line को technically satisfy करते हुए ग़लत चीज़ build कर सकता है?" अगर हाँ, line vague है, उसे tight करें। Spec तब finished नहीं होती जब add करने को कुछ न बचे, बल्कि तब होती है जब misread करने को कुछ न बचे।

3. The three levels of SDD​

SDD all-or-nothing नहीं। तीन levels हैं, और आप इस आधार पर choose करते हैं कि काम कितना matter करता है।

Level	इसका मतलब	कब use करें
Spec-First	Spec एक बार upfront लिखें, फिर उससे build करें। बाद में spec drift कर सकती है।	ज़्यादातर features. Default.
Spec-Anchored	Spec source of truth रहती है; behaviour बदले तो आप spec update करते हैं और उससे re-derive करते हैं।	जो चीज़ months तक maintain करनी हो।
Spec-as-Source	Spec the source होती है; code उससे fully regenerated output होता है, जिसे आप फिर भी re-run और review करते हैं।	Mature, high-discipline teams and tooling.

इस course के लिए, Spec-First से शुरू करें और Spec-Anchored में grow करें। Spec-as-Source वह जगह है जहाँ field जा रही है, लेकिन आप पहले दो levels master करके उसे earn करते हैं। Discipline हर level पर identical है; सिर्फ़ यह बदलता है कि आप spec को sync में कितनी strictness से रखते हैं।

---

Part 2: The Method​

Workflow की एक foundation है (constitution) और चार phases हैं (Research → Specify → Clarify → Build):

Method एक नज़र में: constitution चार phases (Research, Specify, Clarify, Build) के ऊपर बैठती है, और building में मिला gap आपको spec fix करने वापस भेजता है।

4. The constitution: the rules above every spec​

किसी भी feature से पहले, आप सब के लिए persistent rules का छोटा document लिखते हैं: constitution. Coding agents में यह rules file होती है (CLAUDE.md / AGENTS.md); claude.ai में आपकी Project instructions. Idea हर जगह same है: principles, constraints, और conventions जिन्हें आप चाहते हैं कि हर spec और build follow करे।

एक honest caveat, क्योंकि यह उसे use करने का तरीका बदलता है: constitution persistent context है, enforced law नहीं। Agent हर session में इसे load करता है और जितनी specific और concise हो उतना reliably follow करता है, लेकिन "loaded" का मतलब "guaranteed" नहीं। जो rules कभी break नहीं होने चाहिए (production data touch मत करें, secrets commit मत करें), उन्हें सिर्फ़ written rule पर न छोड़ें; tests, pre-commit या tool hooks, CI checks, tightened permissions, या human diff review से back करें। Constitution intent set करती है; वे mechanisms enforce करते हैं।

Constitution principles है, encyclopedia नहीं। यह "यहाँ हमेशा क्या true है?" का जवाब देती है, "feature X कैसे काम करता है?" का नहीं। इसे tight रखें; AI इसे बार-बार read करता है, इसलिए bloat expensive है और important rules दबा देता है। अच्छी constitution lines ऐसी होती हैं:

# Constitution — Smart Notes

## Principles

- Plain language over cleverness. A new contributor should understand any file in 5 minutes.
- Prefer well-established libraries over custom code. Research before reinventing.
- Every feature ships with its spec in `specs/`. The spec is the source of truth.

## Constraints

- Stack: keep it to what's already here. Propose, don't add, new dependencies.
- Never touch `published/` or anything in `src/generated/`.

## Definition of done

- Behaviour matches the spec, edge cases included.
- A human has reviewed the diff against the spec before merge.

बहुत strict constitution उसके बाद सब कुछ भारी कर देती है

Constitution बाद की हर चीज़ का tone set करती है: अगर weekend project के लिए enterprise-grade testing, performance budgets, और heavy process demand करे, तो हर later phase वह weight inherit करता है और to-do app cathedral बन जाती है। Constitution को stakes के हिसाब से रखें; bar बाद में raise कर सकते हैं।

आप यह होता देख सकते हैं। Weekend habit-tracker को ऐसी constitution दें जो 90% test coverage, performance budget, और हर change के लिए written decision record माँगे, तो पहला feature benchmark harness, abstraction की तीन layers, और decision log के साथ ship होता है: list में row add करने वाले button के लिए एक हफ़्ता process. किसी ने यह नहीं माँगा; constitution ने माँगा, और हर phase ने उसका weight inherit किया।

लेकिन opposite failure भी उतना ही common है: constitution इतनी vague हो कि कुछ कहती ही नहीं। Same project की तीन versions:

Too light (useless)	Too strict (suffocating)	Just right
"Write clean code. Be consistent. Use best practices."	12 rules on test coverage %, performance budgets, commit-message format, and review steps, all for a weekend app	The 6–8 lines above: principles the AI can't infer, constraints that actually bite, one clear "done"

हर rule का test spec line जैसा ही है: क्या इसे हटाने से AI mistake कर सकता है? "Write clean code" fail होता है, क्योंकि AI पहले ही try करता है; line कुछ नहीं करती। "Never touch published/" pass होता है, क्योंकि AI यह अपने आप नहीं जान सकता था।

5. Phase 1: Research before you write​

जिस चीज़ को आप समझते नहीं, उसकी spec नहीं लिख सकते। Spec की पहली line से पहले AI से territory map कराएँ: problem, users, constraints, और existing project हो तो current code कैसे काम करता है और नई चीज़ कहाँ fit होगी।

यहाँ power move parallel research है: एक लंबी back-and-forth के बजाय AI से कई सवाल एक साथ investigate कराएँ और report वापस लें। Chat में आप structured findings document माँगते हैं; coding agents में literally subagents चलाते हैं, हर एक अपनी context window में एक area research करता है और summary वापस देता है (main conversation clean रहती है, वही context discipline जो Agentic Coding Crash Course से आती है)।

Output code नहीं और अभी spec भी नहीं. यह short findings document है: क्या exists है, options, unknowns, और यह spec को feed करता है। A prompt जो तीनों tools में काम करता है:

Research what's involved in building [feature]. Investigate these separately and report each on its own: (1) how this kind of thing is usually done, (2) the main approaches and their trade-offs, (3) anything in our existing project it has to fit, (4) the failure modes and edge cases I should worry about. Give me a one-page findings doc: what exists, the options, and what's still unknown. Don't propose a final design or write any code yet.

6. Phase 2: Write the spec (the what and why, never the how)​

अब research की base पर spec लिखें। Blank page से start न करें: AI के साथ draft करें, फिर उसे precise बनाएँ। Concept 2 के तीन सवाल (why, what, और what not to build) छह concrete sections में expand होते हैं। Workable spec में कम से कम यह होता है:

• Goal: why, दो या तीन sentences में।
• User scenarios: "जब user X करता है, उसे Y मिलता है" walkthroughs।
• Functional requirements: testable musts, हर एक इतना specific कि ignore करने वाली build fail हो।
• Edge cases & rules: input empty, huge, duplicate, malformed, unauthorized।
• Out of scope: यह clearly क्या नहीं करता। इसे skip न करें।
• Acceptance criteria: checklist जो "done" बताती है (constitution की project-wide definition of done ऊपर apply रहती है)।

Spec की anatomy: छह sections जो behaviour describe करते हैं और जान-बूझकर HOW नहीं रखते (वह plan में होता है)।

Draft इस prompt से करें, फिर हाथ से tighten करें:

Using the research above and our constitution, draft spec.md for [feature]. Include: goal (the why), user scenarios, functional requirements, edge cases & rules, out-of-scope, and acceptance criteria. Describe behaviour only, no databases, frameworks, or file layout. Make each requirement specific enough that a build which ignored it would visibly fail.

"Tighten by hand" का मतलब। Concept 2 का precision test real work कर रहा है। एक requirement देखें जो AI गलत satisfy कर सकता था, फिर वही line जो सिर्फ़ सही चीज़ pass करने देती है:

Before: "Users can reset their password."

After: "A signed-out user can request a password reset by email. The link works once, expires after 30 minutes, and a used or expired link shows a 'request a new link' message. The response never reveals whether an email is registered."

पहली line उस build को pass कर देती जो plaintext password किसी को भी email कर दे। दूसरी सिर्फ़ वही चीज़ pass कर सकती है जो आपका मतलब था। हर detail जो आप छोड़ देते हैं, AI आपके लिए decide करता है; इसलिए जो details matter करती हैं उन्हें यहीं words में decide करें।

Spec को implementation-free रखना ही आपको later tooling पर mind change करने देता है बिना intent rewrite किए।

Discipline skip करें और tool choice accident से requirement बन जाती है। Spec कहती है "store uploads in S3"; plan और code follow करते हैं; एक month बाद compliance deal company के अपने servers पर storage माँगती है। जो behaviour सबको matter करता था (uploads durable और retrievable रहें) कभी लिखा ही नहीं गया, सिर्फ़ vendor लिखा गया, तो switch one-line plan change के बजाय refactor बन जाता है।

7. Phase 3: Clarify by interview (make the AI ask you)​

यह highest-value, most-skipped step है। Build से पहले सवाल उलटा कर दें: AI को instruct करने के बजाय उससे आपका interview कराएँ ताकि spec की ambiguity reveal हो। एक prompt ज़्यादातर काम कर देता है:

Before we build anything, interview me about this spec. Ask one question at a time, focusing on ambiguities, missing edge cases, and unstated assumptions. Keep going until you could hand this spec to a stranger and trust they'd build exactly what I mean. Don't write any code yet.

आप हैरान होंगे कि कितनी "obvious" चीज़ें कभी actually state नहीं हुई थीं। हर ambiguity जो आप यहाँ, words में resolve करते हैं, वह बाद में wrong code delete करके resolve नहीं करनी पड़ती। यह पूरे process में mistake fix करने की सबसे सस्ती जगह है: spec में fix एक sentence है; implementation के बाद fix rebuild है।

इसे skip करें और सवाल फिर भी answer होते हैं, बस later, code में। Team spec करती है "users can upload a profile photo," सब nod करते हैं, और ship हो जाता है। एक दिन में: कोई 40 MB TIFF upload करता है (size/type limit कभी stated नहीं), दो users एक-दूसरे की photos overwrite कर देते हैं (uniqueness rule नहीं), broken file site भर में blank render होती है (fallback नहीं)। तीन unstated assumptions, हर एक वह question जो interview एक sentence में पूछ लेता, अब bug बन चुका है।

8. Phase 4: Build from the spec​

Spec agreed है। अब आप उससे build करते हैं, और process का amount change के size के साथ scale होता है। हर बार fixed pipeline चलाना ज़रूरी नहीं: change जितनी planning माँगता है उतनी करें, फिर build को spec के against supervise करें।

• एक change जिसे एक sentence में describe किया जा सकता है (typo, एक rule, एक new field): बस ask करें। Plan skip करें। One-line fix पर heavy process force करना overkill की same mistake है।
• एक change जहाँ approach uncertain हो, या कुछ files touch हो रही हों: पहले plan। Agent से approach propose कराएँ, code से पहले review करें।
• Multi-file या architectural change: full loop, plan then build then verify, work को small checkable steps में तोड़कर।

दो चीज़ें हर size पर constant रहती हैं: आप code से पहले approach review करते हैं, और result को spec के against check करते हैं। Verify वह step नहीं है जिसे skip किया जाए।

Work को tasks में कौन तोड़ता है? Agent. यह वह हिस्सा है जो बदल चुका है। आप hand-written task list नहीं देते। Claude Code और OpenCode plan करते हैं, अपनी tracked checklist में work decompose करते हैं, और हर item done mark करते हुए काम करते हैं। आपका काम उस breakdown को review करना और हर step को spec के against check करना है, list author करना नहीं। (claude.ai में, जहाँ task tool नहीं, आप plan और tasks को खुद Artifacts में capture करते हैं: वही एक जगह पुराना "tasks file लिखो" अब भी fit होता है।)

Plan (जब change earn करे):

Based on the agreed spec, propose a technical plan: stack, structure, and the key decisions, each with its trade-off. Match our constitution and reuse what already exists rather than adding new dependencies. Don't write code yet; I'll review the plan first.

Build (supervised):

Implement the agreed plan in small, checkable steps. Do one step at a time, and after each, check it against the spec and stop for me to confirm before the next. Commit after each so every step has a clean rollback point.

Strong model से plan करें, cheaper model से implement

Expensive thinking plan है। Approach agreed हो जाए तो building "steps follow करें" है, जो cheaper या faster model अच्छी तरह करता है। Coding agents में यह एक setting है; claude.ai में आप planning अपनी most capable chat में करते हैं और spec/plan को handoff रखते हैं। (वही Plan/Execute split जो Agentic Coding Crash Course में है।)

Loop close करें: spec के against verify

Code चलना और code का agreed काम करना same चीज़ नहीं। अपनी acceptance criteria को actual checks में बदलें (automated tests जहाँ लिख सकते हैं, manual run-through जहाँ नहीं, या review questions की short list) और हर step के बाद run करें। अगर check इसलिए fail हो कि spec vague थी, code गलत नहीं, तो पहले spec fix करें, फिर code। इसे skip करें और SDD चुपचाप उस चीज़ में degrade हो जाता है जिसे रोकना था: polished documentation के पास unverified code।

Part 2 on one screen​

पूरा method, copyable. Checklist का screenshot लें; prompts को snippet में रखें।

क्या मेरी spec done है?

• Goal: why, 2-3 sentences में
• User scenarios: "जब user X करता है, उसे Y मिलता है"
• Functional requirements: हर एक इतना specific कि ignore करने से build fail हो
• Edge cases & rules: empty, huge, duplicate, malformed, unauthorized
• Out of scope: यह clearly क्या नहीं करता
• Acceptance criteria: checklist जो "done" बताती है
• No HOW: no database, framework, या file layout (वह plan है)

चार prompts, order में:

RESEARCH:  Research what's involved in building [feature]. Investigate separately and
           report each on its own: (1) how this is usually done, (2) the main approaches
           and trade-offs, (3) what in our existing project it must fit, (4) failure modes
           and edge cases. One-page findings doc. No design or code yet.

SPECIFY:   Using the research and our constitution, draft spec.md for [feature]: goal,
           user scenarios, functional requirements, edge cases & rules, out-of-scope,
           acceptance criteria. Behaviour only — no tech choices. Make each requirement
           specific enough that a build ignoring it would visibly fail.

CLARIFY:   Before we build anything, interview me about this spec, one question at a
           time — ambiguities, missing edge cases, unstated assumptions — until there's
           nothing left to misread. No code yet.

BUILD:     Right-size it. Tiny change: just ask. Otherwise: have the agent propose a
           plan and review it, then let it build in small steps, checking each against
           the spec and committing as you go. Turn acceptance criteria into checks.

---

Part 3: The Three Ways​

Same constitution, same four phases, तीन जगह जहाँ आप इन्हें run करते हैं। हम claude.ai से start करते हैं (install कुछ नहीं), फिर दो coding agents।

Tools move करते हैं; discipline नहीं

इस part की specific mechanics, keybindings (Shift+Tab, Tab), slash commands (/init, /undo), model names, और product features (Projects, Artifacts, Canvas, Gems), June 2026 के हिसाब से current हैं और बदल सकते हैं। जो four-phase discipline इन पर चलती है, वह नहीं बदलती।

एक discipline, तीन homes: same loop claude.ai, Claude Code, और OpenCode में चलती है; सिर्फ़ spec की जगह बदलती है।

9. Way 1: claude.ai, the main method​

Web app में आपके दो building blocks हैं: Projects (persistent workspace जिसमें custom instructions और uploaded knowledge होती है) और Artifacts (editable documents जो chat के साथ रहते हैं)। SDD इन पर directly map होती है।

एक बार setup, constitution:

1. अपने काम के लिए Project बनाएँ (for example "Smart Notes").
2. Project की custom instructions में constitution रखें। Research, existing docs, या screenshots को Project knowledge में upload करें ताकि project की हर chat उन्हें देख सके।

चार phases run करें, हर एक Artifact produce करता है:

• Research → Claude से investigate कराकर findings Artifact बनवाएँ। (Web app में subagents नहीं, इसलिए कई सवाल एक structured document में cover कराएँ।)
• Specify → Claude से spec.md Artifact draft करवाएँ। Artifact panel में directly edit करें जब तक सही न हो।
• Clarify → Concept 7 का interview prompt paste करें। सवालों का जवाब दें; Claude से answers को spec Artifact में fold back कराएँ।
• Build → plan.md Artifact, फिर tasks.md Artifact, फिर task by task implement। हर code file अपना Artifact होती है जिसे आप preview और download कर सकते हैं।

Project क्यों matter करता है: constitution और spec हर chat में loaded रहते हैं, इसलिए implementation के लिए fresh conversation खोल सकते हैं बिना project दोबारा explain किए। Artifacts ही आपकी spec files हैं; जब coding agent तक graduate करें तो इन्हें repo में copy कर लें।

ChatGPT और Gemini भी same discipline चला सकते हैं

अगर आप किसी और web assistant को prefer करते हैं, discipline transfer हो जाती है चाहे mechanics different हों। ChatGPT: constitution के लिए Projects, editable spec/plan documents के लिए Canvas. Gemini: constitution के लिए Gem, documents के लिए Canvas. Loop (constitution, फिर Research → Specify → Clarify → Build) same है; सिर्फ़ buttons और "project" memory की persistence बदलती है। claude.ai हमारा default है क्योंकि Artifacts + Projects spec files पर सबसे cleanly map होते हैं, लेकिन यहाँ कुछ भी Claude-only नहीं।

Browser tool में कुछ paste करने से पहले

Chat window easy है, और risk भी वही है। Private source code, customer data, secrets, credentials, या confidential business material किसी web assistant में upload न करें जब तक organization policy allow न करे। Sensitive work के लिए repo-based agent approved environment के अंदर run करें और sanitized fictional examples use करें (जैसे नीचे Smart Notes feature). Discipline same है; data boundary नहीं।

10. Way 2: Claude Code, the discipline in your repo​

जब project real software हो, Claude Code copy-paste हटा देता है: spec, plan, और tasks repo files बन जाते हैं, code के साथ। नीचे native features ही काफ़ी हैं, extra frameworks की ज़रूरत नहीं। Chat loop के ऊपर यह हर phase के लिए built-in machinery add करता है:

• Constitution एक file है जो Claude हर session read करता है। CLAUDE.md हर conversation के start पर load होती है, तो re-paste कुछ नहीं, लेकिन इसे persistent guidance समझें, hard guarantee नहीं। Run /init, फिर real rules तक trim करें।
• Plan mode आपका Specify/Clarify gate है, enforced. Shift+Tab से plan mode Claude को read-only कर देता है: वह code study कर सकता है और spec draft कर सकता है, लेकिन approve होने तक line write नहीं कर सकता। यह "agree before you build" को tool-enforced बनाता है।
• Subagents parallel research करते हैं बिना आपका context pollute किए। हर subagent एक area अपनी window में investigate करता है और सिर्फ़ summary वापस देता है, इसलिए Phase 1 fast और main session lean रहता है।
• Agent अपनी task list maintain करता है; आप supervise करते हैं। Plan approve होने के बाद Claude work को अपनी tracked checklist में तोड़ता है और items done mark करते हुए चलता है। आप list author नहीं करते; breakdown review करते हैं, फिर हर step के बाद spec के against relevant checks चलाते हैं और next से पहले commit करते हैं, ताकि हर step clean rollback point हो। Commit-after-each rhythm आप drive करते हैं (और constitution में bake कर सकते हैं); अगर हर बार ज़रूरी हो तो hook से enforce करें।

क्योंकि चारों artifacts plain files हैं, spec अब version control में है: आप diff कर सकते हैं, pull request में review कर सकते हैं, और देख सकते हैं कि behaviour कब change होना था। यह jump है "एक spec जो मैंने लिखी थी" से "spec जो repo govern करती है" तक।

11. Way 3: OpenCode, any model​

Concept 10 की हर चीज़ OpenCode पर भी apply होती है: rules file (AGENTS.md) as constitution (OpenCode existing CLAUDE.md भी read करता है अगर AGENTS.md न हो), Plan mode (Tab) as read-only gate, research के लिए subagents, और build steps के बीच git-backed /undo. Claude Code की तरह agent अपनी task list self-track करता है और आप breakdown review करते हैं, फिर हर step spec के against check करते हैं; approve करने के बाद Tab Build mode में toggle करता है। OpenCode की extra चीज़ model choice है, जो SDD के natural split से pair होती है: spec और plan phases strong reasoning model reward करते हैं, जबकि clear, agreed task list build करना cheap model जैसे deepseek-v4-flash पर ठीक चल जाता है। आप decide करते हैं हर dollar की "thinking" कहाँ जाए। (दोनों agents की setup details Agentic Coding Crash Course में हैं।)

---

Part 4: A Complete Worked Example​

12. One feature, start to finish, twice​

चलिए पूरा loop एक छोटे real feature पर चलाते हैं: "weekly digest" जो हर Monday हर user को उसके notes का summary email करता है। यह कई files touch करता है (scheduled job, notes query, mailer), इसलिए Concept 8 के right-sizing rule से full loop earn करता है। हम इसे दो बार करते हैं: पहले claude.ai में, जहाँ thinking visible है, फिर Claude Code में, जहाँ loop real files के against repo में चलता है।

In claude.ai

Phase 0: Constitution (Project में already set). Principles: plain language, existing libraries prefer करें, हर feature spec के साथ ship हो, published/ कभी touch न हो।

Phase 1: Research. Prompt:

Research what's involved in a "weekly digest email" for our notes app. Cover: how we'd select which notes to include, scheduling options, email-sending approaches, and the main failure modes (no notes that week, send failures, time zones). Give me a one-page findings doc. Don't propose a final design yet.

Claude findings Artifact वापस देता है। आप skim करते हैं; time-zone question वह चीज़ है जो आपने consider नहीं की थी।

Phase 2: Specify. Prompt:

Using those findings and our constitution, draft spec.md for the weekly digest. Include goal, user scenarios, functional requirements, edge cases, out-of-scope, and acceptance criteria. Describe behaviour only, no tech choices yet.

आपको spec Artifact मिलता है। वह अच्छा है, लेकिन कुछ जगह generic है।

Phase 3: Clarify. Prompt:

Before we plan anything, interview me about this spec, one question at a time, until there's nothing left to misread.

Interview वे decisions surface करता है जो आपने कभी state नहीं किए: digests user के local Monday पर use होते हैं, UTC पर नहीं; zero notes वाला week empty email भेजने के बजाय कुछ नहीं भेजता; unsubscribed users skip होते हैं। आप जवाब देते हैं; Claude हर जवाब spec Artifact में fold कर देता है। यही वह moment है जहाँ SDD अपना फ़ायदा दिखा देता है: तीन future bugs sentences बनकर मर गए।

Phase 4: Build.

Now write plan.md: the technical approach for this spec, given our existing stack. Then tasks.md: an ordered, checkable task list.

आप plan review करते हैं (वह existing mailer reuse करता है, constitution के मुताबिक), approve करते हैं, फिर task by task implement करते हैं, हर step को spec के against check करते हुए और save करते हुए। जब कोई task दिखाता है कि spec किसी चीज़ पर silent थी (मान लें email subject line), आप पहले spec update करते हैं, फिर continue करते हैं। Spec true रहती है।

Same feature, Claude Code में

Same four phases, same prompts; बदलता यह है कि हर artifact file होता है और tool वह gates enforce करता है जो browser में आपने खुद impose किए थे।

• Research: एक findings doc के बजाय subagents spin up करें, हर area के लिए एक, ताकि main session lean रहे। Findings specs/weekly-digest/research.md में land होती हैं।
• Specify: Shift+Tab से plan mode (read-only): "अभी build न करें" rule, अब tool enforce करता है, willpower नहीं।
• Build: Claude काम को अपनी tracked task list में plan करता है और through build करता है; आप हर step spec के against review करते हैं और हर step के बाद commit करते हैं, तो git log उस task list जैसा पढ़ता है और हर step clean rollback point है।

एक real फर्क सिर्फ़ यह है कि spec कहाँ जाती है: claude.ai में वह Artifact थी जिसे आप copy forward करते हैं; Claude Code में वह specs/ में रहती है, code के साथ version-controlled। (OpenCode identical है: CLAUDE.md को AGENTS.md, और Shift+Tab को Tab से swap करें।)

Result सिर्फ़ working code नहीं; working code plus एक spec जो उसे explain और govern करती है, ready for next person (या next you) to change safely.

Artifacts की shape देखें: compact spec.md, plan.md, और tasks.md

Method abstract रहता है जब तक आप देख न लें कि उससे क्या निकलता है। यहाँ तीन artifacts के trimmed versions हैं, ताकि shape दिखे। claude.ai में आप तीनों को Artifacts के रूप में बनाते हैं; coding agent के साथ spec.md और plan.md files होती हैं, जबकि task list आम तौर पर agent की अपनी होती है (यहाँ लिखी गई है ताकि अच्छी list visible हो)। Real ones लंबी होती हैं; shape matter करती है।

# spec.md — Weekly Digest

## Goal

Email each user a once-a-week summary of their own notes so they
re-engage without opening the app. Reduce silent churn.

## User Scenarios

- A user with notes this week gets a Monday-morning digest listing them.
- A user with no notes this week gets nothing (not an empty email).
- An unsubscribed user gets nothing, ever.

## Functional Requirements

FR-1 Digest sends on the user's local Monday at 8:00am.
FR-2 Include only notes created or edited in the prior 7 days.
FR-3 Zero qualifying notes → no email is sent.
FR-4 Unsubscribed users are skipped.
FR-5 A send failure is retried once, then logged; it never blocks others.

## Edge Cases & Rules

- Time zone missing → fall back to UTC.
- 50+ notes → list the 10 most recent, then "and N more."

## Out of Scope

- Digest customization, frequency options, non-email channels.

## Acceptance Criteria

- [ ] A user in Asia/Karachi receives the digest at their local Monday 8am.
- [ ] An empty week sends no email (verified in logs).
- [ ] Unsubscribed users receive nothing.
- [ ] One simulated send failure retries once, then logs, others still send.

# plan.md — Weekly Digest

## Approach

Reuse the existing mailer service (constitution: prefer what exists).
A scheduled job runs hourly, selects users whose local time is Mon 08:00,
builds the digest from the notes query, and hands it to the mailer.

## Key Decisions

- Scheduling: hourly cron + per-user timezone check (no per-user timers).
- Templating: reuse existing email template system.
- Failure handling: wrap each send; retry-once lives in the job, not the mailer.

## Touch Points

- new: jobs/weekly_digest.\* | reuse: services/mailer, models/note
- no schema change required

# tasks.md — Weekly Digest

1. Note-selection query: notes per user from the last 7 days. [FR-2]
2. Eligibility check: local Monday 08:00 + subscribed. [FR-1, FR-4]
3. Digest builder: top 10 + "and N more"; skip if empty. [FR-3, edge]
4. Wire to mailer with retry-once + logging. [FR-5]
5. Tests for each acceptance criterion. [Verify]

Threads notice करें: हर task उस requirement को cite करती है जिसे वह satisfy करती है, और final task verification है, सीधे acceptance criteria से derived।

---

Part 5: Judgment​

13. When SDD pays off, and when it is overkill​

SDD एक discipline है, और discipline की cost होती है: Specify और Clarify tens of minutes की thinking जैसा slow feel करेंगे जहाँ vibe coding पहले ही code दिखा रही होती। यही trade है। Beginners method को उस moment पर छोड़ देते हैं जब यह सबसे बुरा feel करता है, ठीक उससे पहले जब फ़ायदा मिलता है। इसे one-line fix पर spend करना उतना ही ग़लत है जितना payment system पर skip करना। Skill यह जानने में है कि कौन सा काम कौन सा है।

Reach for SDD when…	Skip it (just vibe) when…
The work touches multiple files, modules, or data	It is a one-off script or a tiny tweak
Someone else (or future-you) will maintain it	You will throw the result away today
Getting it wrong is expensive (money, data, trust)	The cost of a wrong guess is "press undo"
Requirements are fuzzy and need to be pinned down	The task is fully clear in one sentence
Several people need to agree on what "done" means	You are exploring to learn what you even want

"Make this button blue" को full constitution-to-implement process से गुज़ारना absurd है। लेकिन जिस moment task state, permissions, data models, money, या किसी और की expectations involve करे, structure pay करना शुरू कर देता है, और चीज़ जितनी देर ज़िंदा रहती है उतना ज़्यादा pay करता है।

Threshold जान-बूझकर low है: tiny throwaway काम left पर रहता है, लेकिन ज़्यादातर काम जो आप keep करते हैं right पर land करता है, जहाँ spec pay करता है।

Anthropic session data में एक और payoff दिखता है: जब build sideways गया, least-experienced users ने troubled sessions को बाकी लोगों से कई गुना ज़्यादा abandon किया; experience का main फ़ायदा agent को वापस track पर steer करना था। Agreed spec वह steering wheel है: जब कुछ टूटे, आपके पास vague memory के बजाय fixed point होता है जिसके against debug कर सकें। Recovery move concrete है: जब agent mid-build spec से drift करे, ignored requirement (FR) paste करके re-ground करें, task को सिर्फ़ उस एक चीज़ तक shrink करें, फिर acceptance criteria की तरफ point करें।

Spec को alive रखें (वह हिस्सा जो सब भूल जाते हैं). Spec सिर्फ़ तब source of truth है जब true रहे। Behaviour बदले (new rule, removed feature, fixed edge case), तो पहले spec change करें, फिर code re-derive करें। यह move Spec-First को Spec-Anchored बनाता है, और spec के time के साथ ज़्यादा valuable बनने और एक महीने में repo की झूठ बन जाने के बीच का फर्क है।

Drift practice में ऐसा दिखता है: कोई digest email का subject directly code में tweak करके ship करता है। Spec अब भी पुराना subject describe करती है। तीन हफ़्ते बाद new teammate spec read करता है, code को spec के मुताबिक "fix" करता है, और चुपचाप working चीज़ तोड़ देता है। किसी ने झूठ नहीं बोला; spec सिर्फ़ true रहना छोड़ गई। Fix cheap और boring है: change spec.md में code के साथ same commit में जाता है, हर बार।

जब specs बहुत हो जाएँ तो क्या बदलता है। एक spec document है; dozens का specs/ folder system है। पूरी directory के साथ live question "क्या यह spec clear है?" से "क्या ये specs अब भी agree करती हैं?" बन जाता है। Features interact करते हैं, इसलिए एक change दूसरों तक ripple कर सकता है, और जब दो specs conflicting choices की तरफ़ point करें, constitution वही है जो उसे settle करती है। Specs के पूरे set को consistent रखना ही real jump है "I can spec a feature" से "I run a repo on SDD" तक।

---

Practice​

SDD पढ़ना SDD सीखना नहीं। Discipline तब आपकी बनती है जब आप full loop किसी real चीज़ पर चलाकर feel करें कि Clarify phase वह mistake पकड़ लेता है जो आप वरना ship कर देते। ये exercises order में करें। हर एक stakes raise करता है, और हर एक deliberately "just vibe it" line के पार है ताकि structure को अपनी worth prove करनी पड़े।

हर project के लिए same four artifacts produce करें (constitution, spec.md, plan.md, tasks.md) plus working result. Single success test Concept 2 वाला है: क्या कोई stranger सिर्फ़ आपकी spec से सही चीज़ build कर सकता है, बिना आपसे एक भी question पूछे?

Warm-up: interview feel करें (claude.ai, ~30 min). सबसे छोटी real चीज़ choose करें जो आप बनाना चाहते थे: study planner, CSV-to-summary tool, habit tracker. Project बनाएँ, three-line constitution paste करें, और चार phases run करें। एक rule: Concept 7 skip न करें। Code से पहले Claude से interview कराएँ। Count करें कितने decisions सामने आए जो आपने state करने का सोचा भी नहीं था। वही number SDD की वजह है।

Project 1: real rules वाला feature (claude.ai, ~1 hr). Smart Notes के लिए "tag and filter" feature spec और build करें: users notes पर tags add करते हैं और filter करते हैं। यह trivial लगता है जब तक spec न करें। Edge cases pin down करें: no tags? duplicate tags? filter with no matches? case sensitivity? tag rename while in use? Done जब आपकी spec इन पाँचों का जवाब implementation से पहले दे।

Project 2: repo में ले जाएँ (Claude Code या OpenCode, ~2 hrs). Project 1 को chat window से निकालकर coding agent में same loop चलाएँ। Constitution CLAUDE.md / AGENTS.md में रखें, spec.md, plan.md, और tasks.md को repo files बनाएँ, और plan mode को specify/clarify gate बनाएँ। एक task at a time implement करें, हर task के बाद commit. Done जब git log एक clean commit per task दिखाए और spec code के साथ version control में हो।

Project 3: spec को alive रखें (hard one, ~1 hr). अब अपना mind change करें। Project 2 में new requirement add करें: tags colour-coded हो सकते हैं, या filtering "any of" और "all of" modes support करती है। सीधे agent से add करवाने की urge resist करें। इसके बजाय: पहले spec.md edit करें, changed section पर Clarify दोबारा run करें, plan और tasks update करें, फिर implement। Done जब spec.md diff और code diff same story बताए।

Project 4: ऐसा code जिसे आपने नहीं लिखा (Claude Code या OpenCode, ~2 hrs). Brand-new project easy case है। कोई small open-source project clone करें जो आपने नहीं देखा, या किसी और का repo उठाएँ, और SDD से modest feature add करें। इस बार Phase 1 weight carry करता है: spec से पहले agent से research कराएँ कि existing code कैसे structured है, feature कहाँ fit होगा, और किन conventions को respect करना है; subagents use करें ताकि हर area map हो। Spec में "fits the existing system" section हो जो patterns name करे। Done जब feature codebase का हिस्सा लगे, bolt-on नहीं, और spec explain करे क्यों fit होता है।

Project 5: SDD with no code at all (claude.ai, ~45 min). अपने आप को prove करें कि यह thinking discipline है, coding नहीं। एक repeatable process choose करें, app नहीं: weekly status report from raw notes, content-repurposing pipeline, inbox-triage routine, grading rubric। Same loop run करें (constitution, research, spec, clarify, build) जहाँ "build" process और prompts produce करता है, source code नहीं। Done जब आप या teammate process spec से चलाकर consistent result ले सकें, no improvisation।

Project 6: stranger test, for real (capstone, ~1.5 hrs). अब तक आप खुद check कर रहे थे, जो weakest reviewer है; आप जानते हैं आपका मतलब क्या था। अपने आप को हटा दें। Feature की spec लिखें, फिर fresh empty AI session (brand-new chat जिसे आपकी discussion का context नहीं) या peer को दें, और zero questions allowed रखकर build कराएँ। जहाँ वह गलत चीज़ build करे, fault spec का है, उनका नहीं: spec fix करें, code नहीं, और दोबारा try करें। Done जब cold reader first pass पर वही build करे जो आपका मतलब था। यह pass कर लें तो real skill आ गई: intent इतना precisely लिखना कि वह आपके head से निकलकर survive करे।

---

Where this leads​

अब आपके पास पूरी discipline है: what पर agree करें पहले, फिर how generate करें; spec को source of truth रखें; और constitution → Research → Specify → Clarify → Build loop उस tool में चलाएँ जो moment के लिए fit हो।

यह book की बाकी हर चीज़ के नीचे thinking layer है। आप coding tools जो यह loop चलाते हैं, Claude Code और OpenCode, Agentic Coding Crash Course में मिल चुके हैं, और discipline को Cowork Crash Course में work करते देख चुके हैं; mechanics के लिए दोनों revisit करें। यहाँ से Mode tracks इस loop को काम पर लगाते हैं: हर build course, Python in the AI Era, Build AI Agents, AI Searchable Context, और Building a Digital FTE, वही loop है, बस bigger systems पर apply होता हुआ।

पूरी book की thesis याद रखें: General Agents build Custom Agents. Spec-Driven Development वह how है जिससे आप general agent को hard problem पर point करते हैं और guesses के pile के बजाय reliable system वापस लेते हैं।

---

Flashcards Study Aid

---

Test Your Understanding

जो सीखा है उसे test करें। हर session 18 questions का fresh set दिखाता है, इसलिए हर retake पर नए questions मिलते हैं।

Checking access...