Design Doc Generator

One command in Claude Code. A polished design doc — Markdown and HTML, both saved straight into your repo.

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