Spec-Driven Development with Claude Code: From Markdown to Production

Netsujo Inc. · Published May 31, 2026

Since March 2026, Netsujo Inc. has put Claude Code, Anthropic's agentic coding tool, at the centre of how it runs multiple products and client projects in parallel. The practice that makes this work is what we call spec-driven development: decisions and rules live in Markdown specification files rather than in conversation, and Claude Code re-reads those files on every task. Five components make up the pipeline. Sub-Agents split exploration, implementation, and review into separate contexts so they can run in parallel without polluting each other's context. MCP (Model Context Protocol) connects the agent to external systems such as Google Workspace and Search Console. Hooks run automated checks at fixed points (session start, tool use, session stop) so quality doesn't depend on a human remembering to check. Skills package recurring workflows into reusable commands. This article covers why we adopted the approach, how each component is used, a worked example of a month-long parallel implementation, our review-gate design, and failures we have had to fix along the way.

Why spec-driven development

A pure conversation-to-code flow has a ceiling: instructions drift, interpretation gets fuzzy, and review can't keep up, especially once several projects run in parallel. Netsujo operates multiple repositories at once — its corporate site, its own media property, client projects, and internal products — and re-explaining what had already been decided, every session, was an expensive habit. So we moved decisions out of conversation and into Markdown files that Claude Code reads before acting. A specification file carries the same weight as source code: it has git history, it can be reviewed as a diff, and simply pointing Claude Code at the right file changes the quality of what it produces. In practice, specs are still often first drafted with ChatGPT, with Claude Code handling essentially all of the implementation that follows.

Five components that make it work

Specification files

A single, git-tracked place for house style, quality-gate order, and the production-approval flow, so the same rule never has to be repeated to the agent twice

Sub-Agents

Split exploration, implementation, and review into separate contexts that can run in parallel

MCP

Lets Claude Code operate external systems (Google Workspace, Search Console, and others) directly

Hooks

Run fixed checks at session start, tool use, or session stop, independent of human attention

Skills

Package a recurring workflow into a reusable, one-command package

Sub-Agent roles and when to force parallelization

• Main agent — owns overall orchestration: reading the spec, deciding how to split work, and doing the final review
• Exploration sub-agent — cross-file investigation, retracing past cases, grep-based mapping, always given an explicit budget (e.g. "200 lines maximum, summary only, no quoting")
• Implementation sub-agent — handles an independent implementation task in parallel, working in an isolated git worktree so it never touches the parent repository directly, then opens a pull request when done
• Review sub-agent — gathers independent perspectives in parallel; when the perspectives are genuinely independent (design, editorial, legal, management), several agents are launched in a single message

A written protocol forces work into a sub-agent once any of these thresholds is crossed: exploration needing 3 or more files, a single task expected to take over 30 minutes, remaining context below 50%, or a need for 2 or more independent review perspectives. One recurring failure was a sub-agent attempting to edit a file it had not read first; the fix was to require every sub-agent instruction to state "read before you edit," with a hook now checking for recurrences.

MCP, Hooks, and the review-gate pipeline

Netsujo runs MCP servers for Google Workspace (Docs/Sheets/Slides/Gmail/Calendar/Drive automation, used for things like a weekly GA4 report generated straight into a Doc and posted to Discord), Search Console (performance, URL Inspection, and sitemap status, used to auto-detect quick wins), Chrome DevTools (Lighthouse audits and network analysis), Memory (persisting entities and relations across sessions), and Notion/Canva (document and design-asset integration). One concrete example: a GSC weekly audit script now runs automatically every Monday at 09:00 JST via GitHub Actions, checking sitemap status, URL Inspection, search analytics, canonical mismatches, and CTR drops, and posting the results to Discord — replacing a passive "only check when asked" habit with a standing weekly audit.

On top of that, Hooks run a Stop hook that posts a session summary to Discord automatically, an always-on security-review plugin that scans every edit, commit, and push, and a CI check in GitHub Actions that flags any leftover merge-conflict markers. Implementation then passes through a review-gate pipeline: automated security review, a design review for any UI change, a customer-facing-UX check, a security review for anything touching auth, a technical (CTO-level) review for anything touching the database, deployment, or environment variables, and a final build/lint/test and production-URL check before an owner report. Public-facing content (blog posts, social copy, landing pages, press releases) goes through an additional gate — editorial, fact-check, legal, and management review, followed by a shared draft and the owner's explicit sign-off before publishing.

A worked example: one month, 200+ commits

Netsujo's corporate site went through more than 200 commits of changes in a single month — three new case studies, 17 SEO fixes, GA4 instrumentation, a knowledge hub, and a design audit, all inside one sprint — run by one person. That density was possible because of the spec-plus-Sub-Agent-plus-MCP-plus-Hooks combination working together: a site-wide design audit delegated to a sub-agent acting as a designer, which produced a prioritized list a human then approved and reviewed by pull request; a bulk SEO fix rollout applied through GSC/GA4 data pulled via MCP; a multi-CMS schema expansion (new Strapi collections, generated together with their TypeScript types and front-end fetchers, then deployed and revalidated end to end); and parallel exploration of several design directions at once using isolated git worktrees, rather than exhausting a single direction before trying another.

Review-gate discipline, approval wording, and failures

• No "good enough, it is a small issue" pass is allowed — a single unmet criterion sends work back
• Any rejection must include concrete, file- and line-level instructions for what to change
• Extra scrutiny goes to areas AI is weaker at: design, copy, tone, and points of UX friction
• The agent that generates work and the agent that evaluates it always run as separate agents or separate sessions

Approval wording is treated just as strictly: "go ahead," "OK," and "continue" mean keep working, not permission to merge to production — only an explicit "merge it" or "ship it" does. One incident in 2026 arose from reading "go ahead" as merge approval, resulting in several pull requests being merged to production without that explicit sign-off; the fix was adding an explicit instruction-keyword table to the specification to prevent a repeat. A separate failure came from a Strapi API token expiring after an environment change on Railway, silently blocking production writes; the fix — a documented token-refresh procedure, checked before any token-touching work — is now recorded as a standing lesson learned.

None of the five components alone explains the result. Together, a specification file, Sub-Agents, MCP, Hooks, and Skills let one person run several projects in parallel without a drop in review quality — because the specification is effectively the organisation's source code for how it wants its AI agent to behave, and every lesson learned gets written back into it rather than repeated informally the next time.