---

❌ Without it

• Real work gets done. The design doc doesn't — it gets skipped, or rushed into a note nobody reads.
• Diagrams get left out because drawing them takes longer than the fix did.
• Three months later, nobody remembers why it was built that way. Not even you.

✅ With it

• Run /design-doc. Claude turns the session you just had into a structured, professional doc.
• Two diagrams, generated and styled automatically. Nobody drags a single box.
• The reasoning gets captured while it's fresh — not reconstructed from memory later.

---

What you get

Output	Where
Markdown file	docs/<title>.md in your project
Interactive HTML	Same folder, docs/<title>.html — light/dark theme, sticky nav

Both are always saved, every time — nothing to opt into.

Every doc includes:

• Abstract, problem statement, architecture and flow diagrams, key decisions and trade-offs, risks — irrelevant sections are dropped, never padded
• At least two Mermaid diagrams wherever the session supports them: a static architecture view and a runtime sequence view, sized and styled automatically
• An auto-inserted table of contents
• Two more doc shapes, detected automatically: a root-cause/bug-investigation report, and a comparison doc for "which approach" decisions

How it works

Install

npx design-doc-generator-mcp init

Run once, inside the project you want to document — registers the MCP server and installs the /design-doc skill. Restart Claude Code, do real work, then run:

/design-doc

Usage

Flag	What it does
(none)	Drafts the default design doc for whatever was just discussed
--activate YOUR-KEY	Activates a Pro license key
--help	Shows usage help

Running it again on the same topic updates the same files — it never creates a duplicate.

Your code never leaves your machine

This tool never reads your source files. It never calls an LLM itself. It only reads lightweight git metadata — branch, git status, a git diff --stat summary, your last 15 commit messages. Claude drafts the document inside your own session, on your own account.

Two things ever reach a network: the section template request when drafting (a mode string, plus your license key if you've activated one), and your license key itself when you run --activate. Pro status is always verified against that key server-side, never assumed from anything the client claims.

Free vs. Pro

	Free	Pro
Design docs	5 / day	Unlimited
Content depth	Full	Full
HTML export	Included	Included
Signup required	No	No

Pro removes the daily cap. That's the only difference.

License

Elastic License 2.0 — free to install and use for drafting your own design docs. You may not resell it as a hosted service, or bypass its license-key checks.