Sunday Coffee & Code: Spec Driven Development in Claude Code Web - Part 2, Actually Running It

Last week I got Spec Kit installed into a real repo and working with Claude Code’s web client - no terminal, just a browser. This week I ran the whole pipeline against a brownfield repo with three deployables.

Constitution → spec → plan → tasks → analyze → implement → converge - all of it.

𝗢𝗻𝗲 𝗽𝗵𝗮𝘀𝗲 𝗽𝗲𝗿 𝘀𝗲𝘀𝘀𝗶𝗼𝗻

The workflow enforces one phase per session, it felt slow but it isn’t. Every session ends with a committed, reviewable artifact, and each new session starts with a preflight that reads the repo and knows exactly where things stand. The repo 𝗶𝘀 the state.

𝗧𝗵𝗲 𝗴𝗮𝘁𝗲 𝘁𝗵𝗮𝘁 𝗮𝗿𝗴𝘂𝗲𝗱 𝗯𝗮𝗰𝗸

In a brownfield repo the constitution’s job is mostly archaeology - writing down principles the code already lives by. But two decisions Claude refused to make for me (linting mandate and testing strictness), and one gate argued back.

𝗦𝗽𝗲𝗰𝗶𝗳𝘆𝗶𝗻𝗴 𝘁𝗵𝗲 𝗿𝗶𝗴𝗵𝘁 𝘁𝗵𝗶𝗻𝗴

Claude surveyed what was actually built, picked a feature, compared it against the design specs, and found the clearest gap: no search endpoints at all. Feature 001 became Search and Navigation - a search plus ”𝘸𝘩𝘢𝘵’𝘴 𝘵𝘩𝘦 𝘣𝘭𝘢𝘴𝘵 𝘳𝘢𝘥𝘪𝘶𝘴 𝘪𝘧 𝘐 𝘤𝘩𝘢𝘯𝘨𝘦 𝘵𝘩𝘪𝘴 𝘧𝘪𝘦𝘭𝘥?” impact analysis.

𝗜𝗺𝗽𝗹𝗲𝗺𝗲𝗻𝘁 𝗮𝗻𝗱 𝗮𝗻 𝗵𝗼𝗻𝗲𝘀𝘁 𝗹𝗲𝗱𝗴𝗲𝗿

Implementation ran task by task, test by test. A few things stood out. The API contract said referenced-by lived under /catalogue/fields/... but the actual routes were /fields, Claude followed the real codebase and flagged the deviation. The four tasks it couldn’t do were deferred with reasons recorded in tasks.md - ”… 𝘵𝘩𝘦 𝘳𝘦𝘮𝘢𝘪𝘯𝘪𝘯𝘨 𝘸𝘰𝘳𝘬 𝘪𝘴 𝘣𝘳𝘰𝘸𝘴𝘦𝘳-𝘭𝘦𝘷𝘦𝘭 / 𝘧𝘶𝘭𝘭-𝘴𝘵𝘢𝘤𝘬 𝘷𝘦𝘳𝘪𝘧𝘪𝘤𝘢𝘵𝘪𝘰𝘯 𝘵𝘩𝘢𝘵 𝘵𝘩𝘪𝘴 𝘪𝘮𝘱𝘭𝘦𝘮𝘦𝘯𝘵 𝘴𝘦𝘴𝘴𝘪𝘰𝘯 𝘤𝘰𝘶𝘭𝘥 𝘯𝘰𝘵 𝘳𝘶𝘯 𝘣𝘦𝘤𝘢𝘶𝘴𝘦 𝘪𝘵 𝘳𝘦𝘲𝘶𝘪𝘳𝘦𝘴 𝘢 𝘭𝘪𝘷𝘦 𝘕𝘦𝘹𝘵.𝘫𝘴 + 𝘍𝘢𝘴𝘵𝘈𝘗𝘐 𝘴𝘵𝘢𝘤𝘬.“.

𝗖𝗼𝗻𝘃𝗲𝗿𝗴𝗲: 𝘁𝗵𝗲 𝗽𝗵𝗮𝘀𝗲 𝗜 𝗱𝗶𝗱𝗻’𝘁 𝗸𝗻𝗼𝘄 𝗜 𝗻𝗲𝗲𝗱𝗲𝗱

Converge audits the actual code state against the spec, plan, and tasks - then appends every gap as a traceable task. It found the four known e2e gaps (no criticals, nothing contradicting the spec, nothing built that wasn’t asked for).

The PR against main is the whole run in miniature: 8 commits, one per phase. The reviewer doesn’t just get code - they get the constitution, the spec, the plan, the analysis, and the known gaps, in order.

𝗧𝗮𝗸𝗲𝗮𝘄𝗮𝘆𝘀

• Gate that argues with you is a gate that’s working. Satisfy it honestly; don’t route around it.
• Deferred-with-reasons is a feature of the workflow, not a failure of it.
• The best output isn’t just the code - it’s the paper trail in the repo.

Next week, Part 3: making all of this portable.

𝗕𝗮𝗰𝗸 𝘁𝗼 𝘁𝗵𝗲 𝗰𝗼𝗳𝗳𝗲𝗲 - 𝗿𝗲𝗺𝗲𝗺𝗯𝗲𝗿: 𝗧𝗵𝗶𝗻𝗸. 𝗠𝗼𝗱𝗲𝗹. 𝗔𝗰𝘁.