Spec-Driven Development: Crash Course

13 concepts · what par agree karein, phir how generate karein

Aap AI se kuch build karne ko kehte hain. Woh aap ko code wapas deta hai jo dekhne mein sahi lagta hai. Aap usay run karte hain. Woh toot jata hai. Ya is se bhi bura: woh chal jata hai, lekin us problem ko solve karta hai jo aap ke zehan wali problem se thori si alag thi. Phir aap dobara explain karte hain. AI woh hissa fix karta hai aur khamoshi se koi aisi cheez undo kar deta hai jo do messages pehle sahi thi. Aik ghante baad aap ke paas code ka dhair hota hai jis par aap poori tarah trust nahin karte aur jise cleanly change nahin kar sakte.

Is loop ka naam hai: vibe coding. Aap AI ko vague idea dete hain aur umeed karte hain ke woh sahi guess karega. Throwaway prototype ke liye yeh theek hai. Lekin jis cheez ko aap keep, deploy, ya kisi aur ke hawale karne ka irada rakhte hain, us ke liye yeh trap hai.

Spec-Driven Development (SDD) is trap se nikalne ka tareeqa hai. Jo chahiye usay hopeful andaaz mein describe karne ke bajaye aap usay likhte hain, itna clear ke code banne se pehle aap aur AI dono agree kar lein. Yeh written agreement spec hai. Code woh cheez banta hai jo spec produce karti hai, ulta nahin.

Yeh course discipline ko end to end cover karta hai. Aakhir tak aap full spec-driven build khud teen tareeqon se run kar sakenge: claude.ai mein, yani web app aur yahan aap ka main tool; Claude Code mein; aur OpenCode mein. Wohi discipline teeno par transfer hoti hai.

SDD mein spec source of truth hai, aur code build output hai. Is course ka har concept behtar spec likhne, us par jaldi agree karne, ya project grow hote hue usay true rakhne ka tareeqa hai.

Practice mein agentic coding already isi tarah kaam karti hai

Is baat ko faith par lene ki zaroorat nahin. Anthropic ke 2026 analysis ne lagbhag 400,000 agentic coding sessions mein clear division of labor dekha: log zyada tar planning decisions karte hain, yani kya build karna hai; agent zyada tar execution decisions karta hai, yani kaise build karna hai. Aur session ki success ka strongest predictor coding skill nahin tha; domain expertise thi: insan ne work ko kitni precision se frame kiya, agent se kya verify karwaya, aur drift hone par usay wapas kaise steer kiya. SDD woh discipline hai jo aap ko us half mein acha banati hai jo aap ke paas rehta hai. Anthropic ki Agentic coding and persistent returns to expertise dekhein.

Lagbhag 400,000 sessions mein what/how split (Anthropic, 2026). SDD woh discipline hai jis se aap planning half mein behtar hote hain.

Prerequisite: AI Prompting in 2026

Us course ne aap ko AI se baat karna sikhaya: context dena, clear ask karna, work check karna. Yeh course sikhata hai ke kisi bhi ask se pehle kya karna hai: fuzzy idea ko aisi written spec mein kaise badalna hai jisse build kiya ja sake. Yeh Agentic Coding Crash Course ke saath naturally pair hota hai, jo coding tools ko depth mein samjhata hai.

Is ke liye programmer hona zaroori nahin​

SDD thinking discipline hai, coding skill nahin. Aap isay lagbhag poori tarah plain language mein, normal chat window mein practice karte hain. Output aik clearly written document hota hai, phir us se bana hua working result: app, script, report generator, ya automation. Agar aap capable colleague ke liye clear brief likh sakte hain, to spec likh sakte hain. (Yeh ab developer-only skill nahin rahi; is ke liye Code You Never Write dekhein.)

Study is baat ko concrete banati hai: coding background ne session success ko barely change kiya; domain expertise ne kiya. Aap se code likhne ko nahin kaha ja raha; aap se kaha ja raha hai ke apne problem ko itna achi tarah jaanein ke usay likh sakein: rules, edge cases, "done" ka matlab. Spec woh jagah hai jahan aap ki expertise jati hai. Woh accountant jo har reconciliation rule state kar sakta hai, us developer se behtar build karwata hai jo books nahin samajhta, kyun ke spec knowledge carry karti hai aur agent code supply karta hai.

---

Teen tools, aik discipline​

Neeche di hui har cheez teen tools mein kaam karti hai. Hum claude.ai se lead karte hain kyun ke isay install nahin karna parta, browser mein real spec-driven work aaj hi ho sakta hai, aur chat-and-document loop thinking ko visible banata hai. Wohi moves dono coding agents par cleanly map hote hain.

	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)

Yeh course kya cover karta hai​

Part	Topic	Aap kya seekhte hain
1	The Shift	Vibe coding kyun fail hoti hai, spec asal mein kya hai, SDD ke teen levels
2	The Method	Constitution, phir chaar phases: Research → Specify → Clarify → Build
3	The Three Ways	claude.ai, Claude Code, aur OpenCode mein loop run karna
4	A Complete Worked Example	Aik feature, start to finish, claude.ai phir Claude Code mein
5	Judgment	SDD kab worth it hai, kab overkill, aur spec ko alive kaise rakhna hai

15-minute spine (agar aap ke paas sirf chand minutes hain)

Agar aap naye hain aur time kam hai to Concept 1 (vibe coding kyun fail hoti hai), Concept 2 (spec product hai), Concept 7 (Clarify by interview), Part 2 ke aakhir ka four-prompt block, aur Part 4 ka worked example parhein. Yeh minimal viable read hai; baqi later deepen karta hai. Jab discipline waqai aap ki banani ho to aakhir ki Practice ladder par jayein. Yeh split khud SDD move hai: spine spec hai, baqi plan.

---

Part 1: The Shift​

Teen ideas AI ke saath kaam karne ka tareeqa reframe karte hain. Inhein samajh lein, baqi mechanics hai.

1. Vibe coding vs. spec-driven development​

Farq yeh hai ke aap thinking kab karte hain.

Vibe coding mein aap AI ke build karte hue sochte hain, yani jo woh deta hai us par react kar ke discover karte hain ke aap asal mein kya chahte the. Yeh fast mehsoos hota hai: screen par foran kuch aa jata hai. Magar har round trip thora context kho deta hai, AI gaps ko reasonable-but-wrong assumptions se fill karta hai, aur result aksar aap ke project ke baqi hisson se match nahin karta. Cost baad mein ek saath aati hai, jab aap cheez ko change ya trust karne ki koshish karte hain.

Spec-driven development mein aap pehle sochte hain aur usay likhte hain. AI build shuru nahin karta jab tak aap dono agree na kar lein ke "done" ka matlab kya hai. Build phir mostly mechanical hoti hai: yeh agreement execute kar rahi hoti hai, guess nahin.

Do loops: vibe coding prompt, code, aur "not quite" ke beech ghoomti hai; SDD pehle spec banata hai, phir us ke against short build-and-check loop chalata hai.

Yeh prompting mein seekhi hui same move hai (context first, then ask), magar stakes zyada hain: AI ab sirf question answer nahin kar raha, aap ke project mein code likh raha hai.

Rule of thumb: agar result phenkna aap ko annoying lage, to aap vibe coding ke safe point se aage nikal chuke hain. Spec likhein.

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

Yeh mental flip hai jis se SDD ko apna naam milta hai. Decades tak spec code ki khidmat karti thi: aap brief likhte, cheez banate, phir brief discard kar dete. SDD isay ulta karta hai. Spec woh durable artifact hai jise aap maintain karte hain; code us se generate hota hai, aur spec badalne par dobara generate hota hai. "Re-generated" ka matlab magic compile button dabana nahin: updated spec par build loop dobara chalana aur result review karna. Spec aik imperfect agent ko guide karti hai jise aap ab bhi supervise karte hain.

Inversion: purana tareeqa spec ko code ka scaffolding samajhta hai; SDD spec ko source of truth aur code ko re-derivable output banata hai.

Achi spec teen sawalon ka jawab deti hai, isi order mein:

1. Why: hum kaunsa problem solve kar rahe hain, aur kis ke liye? (Woh cheez jo zyada tar vibe sessions kabhi state nahin karte.)
2. What: done hone par kya true hona chahiye? Behaviours, inputs, outputs, rules, edge cases, aur explicitly kya out of scope hai.
3. What not to build: boundaries. Yeh single section zyada tar "is ne zyada kar diya / ghalat cheez kar di" failures ko rokta hai.

Notice karein kya missing hai: how. Spec behaviour describe karti hai, implementation nahin. "Users forgotten password ko 30 minutes mein expire hone wale emailed link se reset kar sakte hain" spec hai. "JWT aur Postgres tokens table use karein" implementation hai, aur plan mein aata hai, jo later phase hai. Dono ko bohat jaldi mix karna beginner ki sab se common mistake hai: aap behaviour agree karne se pehle technical choice lock kar dete hain.

Spec ki har line ka test

Poochhein: "Kya aik competent insan is line ko technically satisfy karte hue ghalat cheez build kar sakta hai?" Agar haan, line vague hai, usay tight karein. Spec tab finished nahin hoti jab add karne ko kuch na bache, balki tab hoti hai jab misread karne ko kuch na bache.

3. The three levels of SDD​

SDD all-or-nothing nahin. Teen levels hain, aur aap is basis par choose karte hain ke kaam kitna matter karta hai.

Level	Is ka matlab	Kab use karein
Spec-First	Spec aik dafa upfront likhein, phir us se build karein. Baad mein spec drift kar sakti hai.	Zyada tar features. Default.
Spec-Anchored	Spec source of truth rehti hai; behaviour badle to aap spec update karte hain aur us se re-derive karte hain.	Jo cheez months tak maintain karni ho.
Spec-as-Source	Spec the source hoti hai; code us se fully regenerated output hota hai, jise aap phir bhi re-run aur review karte hain.	Mature, high-discipline teams and tooling.

Is course ke liye, Spec-First se shuru karein aur Spec-Anchored mein grow karein. Spec-as-Source woh jagah hai jahan field ja rahi hai, lekin aap pehle do levels master kar ke usay earn karte hain. Discipline har level par identical hai; sirf yeh badalta hai ke aap spec ko sync mein kitni strictness se rakhte hain.

Part 2: The Method​

Workflow ki aik foundation hai (constitution) aur chaar phases hain (Research → Specify → Clarify → Build):

Method aik nazar mein: constitution chaar phases ke upar baithi hoti hai (Research, Specify, Clarify, Build), aur building ke dauran jo gap mile woh aap ko spec fix karne wapas bhejta hai.

4. The constitution: the rules above every spec​

Kisi bhi feature se pehle, aap sab ke liye persistent rules ka short document likhte hain: constitution. Coding agents mein yeh rules file hoti hai (CLAUDE.md / AGENTS.md); claude.ai mein aap ki Project instructions. Idea har jagah same hai: principles, constraints, aur conventions jinhein aap chahte hain ke har spec aur build follow kare.

Aik honest caveat, kyun ke yeh isay use karne ka tareeqa badalta hai: constitution persistent context hai, enforced law nahin. Agent har session mein isay load karta hai aur jitni specific aur concise ho utna reliably follow karta hai, lekin "loaded" ka matlab "guaranteed" nahin. Jo rules kabhi break nahin hone chahiye (production data touch mat karo, secrets commit mat karo), unhein sirf written rule par na chhorein; tests, pre-commit ya tool hooks, CI checks, tightened permissions, ya human diff review se back karein. Constitution intent set karti hai; woh mechanisms enforce karte hain.

Constitution principles hai, encyclopedia nahin. Yeh "yahan hamesha kya true hai?" ka jawab deti hai, "feature X kaam kaise karta hai?" ka nahin. Isay tight rakhein; AI isay baar baar read karta hai, is liye bloat expensive hai aur important rules daba deta hai. Achi constitution lines aisi hoti hain:

# 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.

Bohat strict constitution baad ki har cheez ko poison kar deti hai

Constitution baad ki har cheez ka tone set karti hai: agar weekend project ke liye enterprise-grade testing, performance budgets, aur heavy process demand kare, to har later phase woh weight inherit karta hai aur to-do app cathedral ban jati hai. Constitution ko stakes ke mutabiq rakhein; bar baad mein raise kar sakte hain.

Aap yeh hota dekh sakte hain. Weekend habit-tracker ko aisi constitution dein jo 90% test coverage, performance budget, aur har change ke liye written decision record maange, to pehla feature benchmark harness, abstraction ki teen layers, aur decision log ke saath ship hota hai: list mein row add karne wale button ke liye aik hafta process. Kisi ne yeh nahin manga; constitution ne manga, aur har phase ne us ka weight inherit kiya.

Lekin opposite failure bhi utna hi common hai: constitution itni vague ho ke kuch kehti hi nahin. Same project ki teen 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"

Har rule ka test spec line jaisa hi hai: kya isay hatane se AI mistake kar sakta hai? "Write clean code" fail hota hai, kyun ke AI pehle hi try karta hai; line kuch nahin karti. "Never touch published/" pass hota hai, kyun ke AI yeh apne aap nahin jaan sakta tha.

5. Phase 1: Research before you write​

Jis cheez ko aap samajhte nahin, us ki spec nahin likh sakte. Spec ki pehli line se pehle AI se territory map karwayein: problem, users, constraints, aur existing project ho to current code kaise kaam karta hai aur nayi cheez kahan fit hogi.

Yahan power move parallel research hai: aik lambi back-and-forth ke bajaye AI se kai sawalat ek saath investigate karwayein aur report wapas lein. Chat mein aap structured findings document maangte hain; coding agents mein literally subagents chalate hain, har ek apni context window mein aik area research karta hai aur summary wapas deta hai (main conversation clean rehti hai, wohi context discipline jo Agentic Coding Crash Course se aati hai).

Output code nahin aur abhi spec bhi nahin. Yeh short findings document hai: kya exists hai, options, unknowns, aur yeh spec ko feed karta hai. A prompt jo teeno tools mein kaam karta hai:

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)​

Ab research ki base par spec likhein. Blank page se start na karein: AI ke saath draft karein, phir usay precise banayein. Concept 2 ke teen sawal (why, what, aur what not to build) chhe concrete sections mein expand hote hain. Workable spec mein kam az kam yeh hota hai:

• Goal: why, do ya teen sentences mein.
• User scenarios: "jab user X karta hai, usay Y milta hai" walkthroughs.
• Functional requirements: testable musts, har aik itna specific ke ignore karne wali build fail ho.
• Edge cases & rules: input empty, huge, duplicate, malformed, unauthorized.
• Out of scope: yeh clearly kya nahin karta. Isay skip na karein.
• Acceptance criteria: checklist jo "done" batati hai (constitution ki project-wide definition of done upar apply rehti hai).

Spec ki anatomy: chhe sections jo behaviour describe karte hain aur jaan-boojh kar HOW nahin rakhte (woh plan mein hota hai).

Draft is prompt ke saath karein, phir haath se tighten karein:

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" ka matlab. Concept 2 ka precision test real work kar raha hai. Aik requirement dekhein jo AI ghalat satisfy kar sakta tha, phir wohi line jo sirf sahi cheez pass karne deti hai:

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."

Pehli line us build ko pass kar deti jo plaintext password kisi ko bhi email kar de. Doosri sirf wohi cheez pass kar sakti hai jo aap ka matlab tha. Har detail jo aap chhor dete hain, AI aap ke liye decide karta hai; is liye jo details matter karti hain woh yahin words mein decide karein.

Spec ko implementation-free rakhna hi aap ko later tooling ke bare mein mind change karne deta hai bina intent rewrite kiye.

Yeh discipline skip karein aur tool choice accident se requirement ban jati hai. Spec kehti hai "store uploads in S3"; plan aur code follow karte hain; aik month baad compliance deal company ke apne servers par storage maangti hai. Jo behaviour sab ko matter karta tha (uploads durable aur retrievable rehte hain) kabhi likha hi nahin gaya, sirf vendor likha gaya, to switch one-line plan change ke bajaye refactor ban jata hai.

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

Yeh highest-value, most-skipped step hai. Build se pehle sawal ulta kar dein: AI ko instruct karne ke bajaye us se aap ka interview karwayein taake spec ki ambiguity reveal ho. Aik prompt zyada tar kaam kar deta hai:

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.

Aap hairan honge ke kitni "obvious" cheezen kabhi actually state nahin hui thin. Har ambiguity jo aap yahan, words mein resolve karte hain, woh baad mein wrong code delete kar ke resolve nahin karni parti. Yeh poore process mein mistake fix karne ki sab se sasti jagah hai: spec mein fix ek sentence hai; implementation ke baad fix rebuild hai.

Isay skip karein aur sawalat phir bhi answer hote hain, bas later, code mein. Team spec karti hai "users can upload a profile photo," sab nod karte hain, aur ship ho jata hai. Aik din mein: koi 40 MB TIFF upload karta hai (size/type limit kabhi stated nahin), do users aik doosre ki photos overwrite kar dete hain (uniqueness rule nahin), broken file site bhar mein blank render hoti hai (fallback nahin). Teen unstated assumptions, har aik woh question jo interview aik sentence mein pooch leta, ab bug ban chuka hai.

8. Phase 4: Build from the spec​

Spec agreed hai. Ab aap us se build karte hain, aur process ka amount change ke size ke saath scale hota hai. Har dafa fixed pipeline chalana zaroori nahin: change jitni planning maangta hai utni karein, phir build ko spec ke against supervise karein.

• Aik change jo aik sentence mein describe ho sakta hai (typo, aik rule, aik new field): bas ask karein. Plan skip karein. One-line fix par heavy process force karna overkill ki same mistake hai.
• Aik change jahan approach uncertain ho, ya kuch files touch ho rahi hon: pehle plan. Agent se approach propose karwayein, code se pehle review karein.
• Multi-file ya architectural change: full loop, plan then build then verify, work ko small checkable steps mein tod kar.

Do cheezen har size par constant rehti hain: aap code se pehle approach review karte hain, aur result ko spec ke against check karte hain. Verify woh step kabhi nahin jo skip kiya jaye.

Work ko tasks mein kaun todta hai? Agent. Yeh woh hissa hai jo badal chuka hai. Aap hand-written task list nahin dete. Claude Code aur OpenCode plan karte hain, apni tracked checklist mein work decompose karte hain, aur har item done mark karte hue kaam karte hain. Aap ka job us breakdown ko review karna aur har step ko spec ke against check karna hai, list author karna nahin. (claude.ai mein, jahan task tool nahin, aap plan aur tasks ko khud Artifacts mein capture karte hain: wahi aik jagah purana "tasks file likho" ab bhi fit hota hai.)

Plan (jab change earn kare):

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 se plan karein, cheaper model se implement

Expensive thinking plan hai. Jab approach agreed ho, building "steps follow karo" hai, jo cheaper ya faster model achi tarah karta hai. Coding agents mein yeh aik setting hai; claude.ai mein aap planning apni most capable chat mein karte hain aur spec/plan ko handoff rakhte hain. (Wohi Plan/Execute split jo Agentic Coding Crash Course mein hai.)

Loop close karein: spec ke against verify

Code chalna aur code ka agreed kaam karna same cheez nahin. Apni acceptance criteria ko actual checks mein badlein (automated tests jahan likh sakte hain, manual run-through jahan nahin, ya review questions ki short list) aur har step ke baad run karein. Agar check is liye fail ho ke spec vague thi, code ghalat nahin, to pehle spec fix karein, phir code. Isay skip karein aur SDD khamoshi se us cheez mein degrade ho jata hai jise rokna tha: polished documentation ke paas unverified code.

Part 2 on one screen​

Poora method, copyable. Checklist ka screenshot lein; prompts ko snippet mein rakhein.

Kya meri spec done hai?

• Goal: why, 2-3 sentences mein
• User scenarios: "jab user X karta hai, usay Y milta hai"
• Functional requirements: har aik itna specific ke ignore karne se build fail ho
• Edge cases & rules: empty, huge, duplicate, malformed, unauthorized
• Out of scope: yeh clearly kya nahin karta
• Acceptance criteria: checklist jo "done" batati hai
• No HOW: no database, framework, ya file layout (woh plan hai)

Chaar prompts, order mein:

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, teen jagah jahan aap inhein run karte hain. Hum claude.ai se start karte hain (install kuch nahin), phir do coding agents.

Tools move karte hain; discipline nahin

Is part ki specific mechanics, keybindings (Shift+Tab, Tab), slash commands (/init, /undo), model names, aur product features (Projects, Artifacts, Canvas, Gems), June 2026 ke mutabiq current hain aur badal sakte hain. Jo four-phase discipline in par chalti hai, woh nahin badalti.

Aik discipline, teen homes: same loop claude.ai, Claude Code, aur OpenCode mein chalti hai; sirf spec ki jagah badalti hai.

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

Web app mein aap ke do building blocks hain: Projects (persistent workspace jisme custom instructions aur uploaded knowledge hoti hai) aur Artifacts (editable documents jo chat ke saath rehte hain). SDD in par directly map hoti hai.

Aik dafa setup, constitution:

1. Apne kaam ke liye Project banayein (for example "Smart Notes").
2. Project ki custom instructions mein constitution rakhein. Research, existing docs, ya screenshots ko Project knowledge mein upload karein taake project ki har chat unhein dekh sake.

Chaar phases run karein, har aik Artifact produce karta hai:

• Research → Claude se investigate karwa kar findings Artifact banwayein. (Web app mein subagents nahin, is liye kai sawalat aik structured document mein cover karwayein.)
• Specify → Claude se spec.md Artifact draft karwayein. Artifact panel mein directly edit karein jab tak sahi na ho.
• Clarify → Concept 7 ka interview prompt paste karein. Sawalat ka jawab dein; Claude se answers ko spec Artifact mein fold back karwayein.
• Build → plan.md Artifact, phir tasks.md Artifact, phir task by task implement. Har code file apna Artifact hoti hai jise aap preview aur download kar sakte hain.

Project kyun matter karta hai: constitution aur spec har chat mein loaded rehte hain, is liye implementation ke liye fresh conversation khol sakte hain bina project dobara explain kiye. Artifacts hi aap ki spec files hain; jab coding agent tak graduate karein to inhein repo mein copy kar lein.

ChatGPT aur Gemini bhi same discipline chala sakte hain

Agar aap kisi aur web assistant ko prefer karte hain, discipline transfer ho jati hai chahe mechanics different hon. ChatGPT: constitution ke liye Projects, editable spec/plan documents ke liye Canvas. Gemini: constitution ke liye Gem, documents ke liye Canvas. Loop (constitution, phir Research → Specify → Clarify → Build) same hai; sirf buttons aur "project" memory ki persistence badalti hai. claude.ai hamara default hai kyun ke Artifacts + Projects spec files par sab se cleanly map hote hain, lekin yahan kuch bhi Claude-only nahin.

Browser tool mein kuch paste karne se pehle

Chat window easy hai, aur risk bhi wahi hai. Private source code, customer data, secrets, credentials, ya confidential business material kisi web assistant mein upload na karein jab tak organization policy allow na kare. Sensitive work ke liye repo-based agent approved environment ke andar run karein aur sanitized fictional examples use karein (jaise neeche Smart Notes feature). Discipline same hai; data boundary nahin.

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

Jab project real software ho, Claude Code copy-paste hata deta hai: spec, plan, aur tasks repo files ban jate hain, code ke saath. Neeche native features hi kaafi hain, extra frameworks ki zaroorat nahin. Chat loop ke upar yeh har phase ke liye built-in machinery add karta hai:

• Constitution aik file hai jo Claude har session read karta hai. CLAUDE.md har conversation ke start par load hoti hai, to re-paste kuch nahin, lekin isay persistent guidance samjhein, hard guarantee nahin. Run /init, phir real rules tak trim karein.
• Plan mode aap ka Specify/Clarify gate hai, enforced. Shift+Tab se plan mode Claude ko read-only kar deta hai: woh code study kar sakta hai aur spec draft kar sakta hai, lekin approve hone tak line write nahin kar sakta. Yeh "agree before you build" ko tool-enforced banata hai.
• Subagents parallel research karte hain bina aap ka context pollute kiye. Har subagent aik area apni window mein investigate karta hai aur sirf summary wapas deta hai, is liye Phase 1 fast aur main session lean rehta hai.
• Agent apni task list maintain karta hai; aap supervise karte hain. Plan approve hone ke baad Claude work ko apni tracked checklist mein todta hai aur items done mark karte hue chalta hai. Aap list author nahin karte; breakdown review karte hain, phir har step ke baad spec ke against relevant checks chalate hain aur next se pehle commit karte hain, taake har step clean rollback point ho. Commit-after-each rhythm aap drive karte hain (aur constitution mein bake kar sakte hain); agar har dafa zaroori ho to hook se enforce karein.

Kyun ke chaaron artifacts plain files hain, spec ab version control mein hai: aap diff kar sakte hain, pull request mein review kar sakte hain, aur dekh sakte hain ke behaviour kab change hona tha. Yeh jump hai "aik spec jo maine likhi thi" se "spec jo repo govern karti hai" tak.

11. Way 3: OpenCode, any model​

Concept 10 ki har cheez OpenCode par bhi apply hoti hai: rules file (AGENTS.md) as constitution (OpenCode existing CLAUDE.md bhi read karta hai agar AGENTS.md na ho), Plan mode (Tab) as read-only gate, research ke liye subagents, aur build steps ke darmiyan git-backed /undo. Claude Code ki tarah agent apni task list self-track karta hai aur aap breakdown review karte hain, phir har step spec ke against check karte hain; approve karne ke baad Tab Build mode mein toggle karta hai. OpenCode ki extra cheez model choice hai, jo SDD ke natural split se pair hoti hai: spec aur plan phases strong reasoning model reward karte hain, jabke clear, agreed task list build karna cheap model jaise deepseek-v4-flash par theek chal jata hai. Aap decide karte hain har dollar ki "thinking" kahan jaye. (Dono agents ki setup details Agentic Coding Crash Course mein hain.)

---

Part 4: A Complete Worked Example​

12. One feature, start to finish, twice​

Chaliye poora loop aik chhote real feature par chalate hain: "weekly digest" jo har Monday har user ko us ke notes ka summary email karta hai. Yeh kai files touch karta hai (scheduled job, notes query, mailer), is liye Concept 8 ke right-sizing rule se full loop earn karta hai. Hum isay do dafa karte hain: pehle claude.ai mein, jahan thinking visible hai, phir Claude Code mein, jahan loop real files ke against repo mein chalta hai.

In claude.ai

Phase 0: Constitution (Project mein already set). Principles: plain language, existing libraries prefer karein, har feature spec ke saath ship ho, published/ kabhi touch na ho.

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 wapas deta hai. Aap skim karte hain; time-zone question woh cheez hai jo aap ne consider nahin ki thi.

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.

Aap ko spec Artifact milta hai. Woh acha hai, lekin kuch jagah generic hai.

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 woh decisions surface karta hai jo aap ne kabhi state nahin kiye: digests user ke local Monday par use hote hain, UTC par nahin; zero notes wala week empty email bhejne ke bajaye kuch nahin bhejta; unsubscribed users skip hote hain. Aap jawab dete hain; Claude har jawab spec Artifact mein fold kar deta hai. Yahi woh moment hai jahan SDD apna faida dikha deta hai: teen future bugs sentences ban kar mar gaye.

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.

Aap plan review karte hain (woh existing mailer reuse karta hai, constitution ke mutabiq), approve karte hain, phir task by task implement karte hain, har step ko spec ke against check karte hue aur save karte hue. Jab koi task dikhata hai ke spec kisi cheez par silent thi (maan lein email subject line), aap pehle spec update karte hain, phir continue karte hain. Spec true rehti hai.

Same feature, Claude Code mein

Same four phases, same prompts; badalta yeh hai ke har artifact file hota hai aur tool woh gates enforce karta hai jo browser mein aap ne khud impose kiye the.

• Research: aik findings doc ke bajaye subagents spin up karein, har area ke liye aik, taake main session lean rahe. Findings specs/weekly-digest/research.md mein land hoti hain.
• Specify: Shift+Tab se plan mode (read-only): "abhi build mat karo" rule, ab tool enforce karta hai, willpower nahin.
• Build: Claude kaam ko apni tracked task list mein plan karta hai aur through build karta hai; aap har step spec ke against review karte hain aur har step ke baad commit karte hain, to git log us task list jaisa parhta hai aur har step clean rollback point hai.

Aik real farq sirf yeh hai ke spec kahan jati hai: claude.ai mein woh Artifact thi jise aap copy forward karte hain; Claude Code mein woh specs/ mein rehti hai, code ke saath version-controlled. (OpenCode identical hai: CLAUDE.md ko AGENTS.md, aur Shift+Tab ko Tab se swap karein.)

Result sirf working code nahin; working code plus aik spec jo usay explain aur govern karti hai, ready for next person (ya next you) to change safely.

Artifacts ki shape dekhein: compact spec.md, plan.md, aur tasks.md

Method abstract rehta hai jab tak aap dekh na lein ke us se kya nikalta hai. Yahan teen artifacts ke trimmed versions hain, taake shape nazar aaye. claude.ai mein aap teeno ko Artifacts ke taur par banate hain; coding agent ke saath spec.md aur plan.md files hoti hain, jabke task list aam tor par agent ki apni hoti hai (yahan likh di gayi hai taake achi list visible ho). Real ones lambi hoti hain; shape matter karti hai.

# 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 karein: har task us requirement ko cite karta hai jise woh satisfy karta hai, aur final task verification hai, seedha acceptance criteria se derived.

---

Part 5: Judgment​

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

SDD aik discipline hai, aur discipline ki cost hoti hai: Specify aur Clarify tens of minutes ki thinking jaisa slow feel karenge jahan vibe coding pehle hi code dikhati hoti. Yahi trade hai. Beginners method ko us moment par chhor dete hain jab yeh sab se bura feel karta hai, bilkul us se pehle jab faida milta hai. Isay one-line fix par spend karna utna hi ghalat hai jitna payment system par skip karna. Skill yeh jaanne mein hai ke kaunsa kaam kaunsa hai.

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" ko full constitution-to-implement process se guzarna absurd hai. Lekin jis moment task state, permissions, data models, money, ya kisi aur ki expectations involve kare, structure pay karna shuru kar deta hai, aur jitni der cheez zinda rehti hai utna zyada pay karta hai.

Threshold jaan-boojh kar low hai: tiny throwaway kaam left par rehta hai, lekin zyada tar kaam jo aap keep karte hain right par land karta hai, jahan spec pay karta hai.

Anthropic session data mein aik aur payoff dikhta hai: jab build sideways gaya, least-experienced users ne troubled sessions ko baqi logon se kai guna zyada abandon kiya; experience ka main faida agent ko wapas track par steer karna tha. Agreed spec woh steering wheel hai: jab kuch toot jaye, aap ke paas vague memory ke bajaye fixed point hota hai jiske against debug kar sakein. Recovery move concrete hai: jab agent mid-build spec se drift kare, ignored requirement (FR) paste kar ke re-ground karein, task ko sirf us aik cheez tak shrink karein, phir acceptance criteria ki taraf point karein.

Spec ko alive rakhein (woh hissa jo sab bhool jate hain). Spec sirf tab source of truth hai jab true rahe. Behaviour badle (new rule, removed feature, fixed edge case), to pehle spec change karein, phir code re-derive karein. Yeh move Spec-First ko Spec-Anchored banata hai, aur spec ke waqt ke saath zyada valuable hone aur aik mahine mein repo ki jhoot ban jane ke beech ka farq hai.

Drift practice mein aisa dikhta hai: koi digest email ka subject directly code mein tweak kar ke ship karta hai. Spec ab bhi purana subject describe karti hai. Teen haftay baad new teammate spec read karta hai, code ko spec ke mutabiq "fix" karta hai, aur khamoshi se working cheez tod deta hai. Kisi ne jhoot nahin bola; spec sirf true rehna chhor gayi. Fix cheap aur boring hai: change spec.md mein code ke saath same commit mein jata hai, har dafa.

Jab specs bohat ho jayein to kya badalta hai. Aik spec document hai; dozens ka specs/ folder system hai. Puri directory ke saath live question "kya yeh spec clear hai?" se "kya yeh specs ab bhi agree karti hain?" ban jata hai. Features interact karte hain, is liye aik change doosron tak ripple kar sakta hai, aur jab do specs conflicting choices ki taraf point karein, constitution woh cheez hai jo isay settle karti hai. Specs ke poore set ko consistent rakhna hi real jump hai "I can spec a feature" se "I run a repo on SDD" tak.

---

Practice​

SDD parhna SDD seekhna nahin. Discipline tab aap ki banti hai jab aap full loop kisi real cheez par chala kar feel karein ke Clarify phase woh mistake pakar leta hai jo aap warna ship kar dete. Yeh exercises order mein karein. Har aik stakes raise karta hai, aur har aik deliberately "just vibe it" line ke par hai taake structure ko apni worth prove karni pade.

Har project ke liye same four artifacts produce karein (constitution, spec.md, plan.md, tasks.md) plus working result. Single success test Concept 2 wala hai: kya aik stranger sirf aap ki spec se sahi cheez build kar sakta hai, bina aap se aik bhi question pooche?

Warm-up: interview feel karein (claude.ai, ~30 min). Sab se chhoti real cheez choose karein jo aap banana chahte the: study planner, CSV-to-summary tool, habit tracker. Project banayein, three-line constitution paste karein, aur chaar phases run karein. Aik rule: Concept 7 skip na karein. Code se pehle Claude se interview karwayein. Count karein kitne decisions samne aaye jo aap ne state karne ka socha bhi nahin tha. Wahi number SDD ki wajah hai.

Project 1: real rules wala feature (claude.ai, ~1 hr). Smart Notes ke liye "tag and filter" feature spec aur build karein: users notes par tags add karte hain aur filter karte hain. Yeh trivial lagta hai jab tak spec na karein. Edge cases pin down karein: no tags? duplicate tags? filter with no matches? case sensitivity? tag rename while in use? Done jab aap ki spec in paanchon ka jawab implementation se pehle de.

Project 2: repo mein le jayein (Claude Code ya OpenCode, ~2 hrs). Project 1 ko chat window se nikal kar coding agent mein same loop chalayein. Constitution CLAUDE.md / AGENTS.md mein rakhein, spec.md, plan.md, aur tasks.md ko repo files banayein, aur plan mode ko specify/clarify gate banayein. Aik task at a time implement karein, har task ke baad commit. Done jab git log aik clean commit per task dikhaye aur spec code ke saath version control mein ho.

Project 3: spec ko alive rakhein (hard one, ~1 hr). Ab apna mind change karein. Project 2 mein new requirement add karein: tags colour-coded ho sakte hain, ya filtering "any of" aur "all of" modes support karti hai. Seedha agent se add karwane ki urge resist karein. Is ke bajaye: pehle spec.md edit karein, changed section par Clarify dobara run karein, plan aur tasks update karein, phir implement. Done jab spec.md diff aur code diff same story batayein.

Project 4: aisa code jise aap ne nahin likha (Claude Code ya OpenCode, ~2 hrs). Brand-new project easy case hai. Koi small open-source project clone karein jo aap ne nahin dekha, ya kisi aur ka repo uthayein, aur SDD se modest feature add karein. Is dafa Phase 1 weight carry karta hai: spec se pehle agent se research karwayein ke existing code kaise structured hai, feature kahan fit hoga, aur kin conventions ko respect karna hai; subagents use karein taake har area map ho. Spec mein "fits the existing system" section ho jo patterns name kare. Done jab feature codebase ka hissa lage, bolt-on nahin, aur spec explain kare kyun fit hota hai.

Project 5: SDD with no code at all (claude.ai, ~45 min). Apne aap ko prove karein ke yeh thinking discipline hai, coding nahin. Aik repeatable process choose karein, app nahin: weekly status report from raw notes, content-repurposing pipeline, inbox-triage routine, grading rubric. Same loop run karein (constitution, research, spec, clarify, build) jahan "build" process aur prompts produce karta hai, source code nahin. Done jab aap ya teammate process spec se chala kar consistent result le sakte hain, no improvisation.

Project 6: stranger test, for real (capstone, ~1.5 hrs). Ab tak aap khud check kar rahe the, jo weakest reviewer hai; aap jaante hain aap ka matlab kya tha. Apne aap ko hata dein. Feature ki spec likhein, phir fresh empty AI session (brand-new chat jise aap ki discussion ka context nahin) ya peer ko dein, aur zero questions allowed rakh kar build karwayein. Jahan woh ghalat cheez build kare, fault spec ka hai, un ka nahin: spec fix karein, code nahin, aur dobara try karein. Done jab cold reader first pass par wohi build kare jo aap ka matlab tha. Yeh pass kar lein to real skill aa gayi: intent itna precisely likhna ke woh aap ke head se nikal kar survive kare.

---

Where this leads​

Ab aap ke paas poori discipline hai: what par agree karein pehle, phir how generate karein; spec ko source of truth rakhein; aur constitution → Research → Specify → Clarify → Build loop us tool mein chalayein jo moment ke liye fit ho.

Yeh book ki baqi har cheez ke neeche thinking layer hai. Aap coding tools jo yeh loop chalate hain, Claude Code aur OpenCode, Agentic Coding Crash Course mein mil chuke hain, aur discipline ko Cowork Crash Course mein work karte dekh chuke hain; mechanics ke liye dono revisit karein. Yahan se Mode tracks is loop ko kaam par lagate hain: har build course, Python in the AI Era, Build AI Agents, AI Searchable Context, aur Building a Digital FTE, wahi loop hai, bas bigger systems par apply hota hua.

Poori book ki thesis yaad rakhein: General Agents build Custom Agents. Spec-Driven Development woh how hai jis se aap general agent ko hard problem par point karte hain aur guesses ke pile ke bajaye reliable system wapas lete hain.

---

Flashcards Study Aid

---

Test Your Understanding

Jo seekha hai usay test karein. Har session 18 questions ka fresh set dikhata hai, is liye har retake par naye questions milte hain.

Checking access...