MDD - Manual-Driven Development

Why MDD

The Problem

Most people prompt Claude Code like this: fix the bug in my auth system. Claude reads 40 files, burns through context, produces something that technically compiles but misses the bigger picture. The model is spending most of its budget on orientation - figuring out what your project even is - rather than solving your actual problem.

The Solution

MDD flips this. Write structured documentation first. Claude reads one doc instead of 40 files - 200 tokens instead of 20,000. Every invocation of /mdd starts with a clear, human-authored map of the feature, the data flow, the test plan, and the acceptance criteria. Claude never needs to guess.

How It Works

MDD is installed as a Claude Code slash command. When you run /mdd, the router reads the first argument and loads only the command file that handles that mode. The full instruction set spans 28,000 tokens - none of it is loaded unless it is needed.

Lazy-Loading Architecture

The /mdd command is split across 7 focused files. The router dispatches to exactly one file per invocation:

This design means your context window stays clean. Claude Code enters each mode with a fresh, focused instruction set rather than carrying the weight of every other mode it will never use in this session.

Installation

MDD installs globally via npm. One command puts /mdd in every Claude Code session on your machine.

npm install -g @thedecipherist/mdd
mdd install

mdd install copies mdd.md to ~/.claude/commands/ (so /mdd appears as a slash command) and the six mode files to ~/.claude/mdd/ (so they don't clutter the command picker). It also injects a guidance block into ~/.claude/CLAUDE.md. After that, /mdd is available in any project, any directory, any session.

Options

mdd install

mdd install --dir /path/to/claude/commands

npm update -g @thedecipherist/mdd
mdd install

Claude Automatically Suggests MDD

mdd install injects a guidance block into ~/.claude/CLAUDE.md that teaches Claude to recognise when you're in an MDD project and suggest the right workflow — even when you don't type /mdd.

Whenever Claude detects a .mdd/ directory in the current project it evaluates your request before responding:

• Existing feature match — scans .startup.md tags and flags overlap: "This looks related to 02-user-auth. Want to use /mdd update 02?"
• Ops / infrastructure — deploy, CI/CD, Docker, commit hooks, cron: "Want to document this as a runbook with /mdd ops?"
• Initiative-scale — 3+ independent concerns: "Want to plan this with /mdd plan-initiative?"
• Single feature — "Want me to use /mdd <description> to build this with docs and tests first?"

Claude always asks — never auto-invokes. Tag-based detection means no full docs are loaded into context: just the compact tag list in .startup.md.

Branch Guard — Never Work on main

mdd install also registers a Claude Code PreToolUse hook — a shell script that fires before every file write in any MDD project. If the current branch is main or master, the hook blocks the operation:

⛔  MDD BRANCH GUARD

    File modification is blocked on branch 'main'.
    MDD never writes files directly on main or master.

    Create a feature branch, then re-run your /mdd command:
      git checkout -b feat/<feature-name>

Unlike instruction-based checks, hooks fire at the OS level on every tool call — they cannot be compacted away or forgotten by Claude. MDD instructions and the hook work together: instructions guide Claude's decisions, the hook enforces the rule even if earlier context is lost.

All 24 Modes

MDD organises its 24 modes into 6 groups. Each group is loaded independently - running a manage command never loads the build pipeline, and running a plan command never loads the audit system. Pick the mode that matches what you need right now.

Build Mode

Build mode is the core of MDD. When you run /mdd <feature description>, Claude Code enters a structured 7-phase pipeline. No code is written until documentation, data flow, and tests exist. Three mandatory gates enforce this.

The Pipeline

The Three Gates

Key Highlights

• Parallel context agents - the Understand phase uses multiple agents to read the codebase simultaneously, preserving the main session's context budget
• Documentation-first enforcement - the Red Gate physically prevents implementation until docs and failing tests exist
• Root-cause-first diagnosis - the Green Gate loop diagnoses the deepest root cause before touching code
• Real environment verification - the Integration Gate runs against a live environment, not mocks

Audit Mode

/mdd audit reviews your entire codebase using parallel sub-agents. Agent count scales automatically with the size of the project. Every file gets a full, uncontaminated context budget.

Agent Scaling

Manifest System

MDD tracks audit progress using a manifest file written to .mdd/audit/. Each file's status is tracked with a single character:

• [ ] - pending, not yet reviewed
• [~] - in progress, agent currently reading
• [x] - complete, no significant findings
• [!] - findings recorded, needs attention
• [e] - error, agent failed to read this file

If an audit is interrupted - by a timeout, a crash, or a manual stop - MDD automatically detects the incomplete manifest on the next run and resumes from where it left off. No work is lost.

Finding Severity Levels

Real Results

The Claude Code Mastery Starter Kit ran a full MDD audit on itself - 57 source files, end to end. Here are the numbers.

From Starter Kit to Standalone

Dashboards

MDD ships with two companion dashboards for exploring your .mdd/ workspace. Both are available as standalone packages today and will soon be merged directly into the mdd package — launchable via the mdd command without a separate install.

npm install -g mdd-tui
mdd-tui

npm install -g mdd-dashboard
mdd-dashboard
# Dashboard running at http://localhost:7321

Coming soon: Both dashboards will be merged into the mdd package — launch either directly from the mdd CLI, no separate install needed.

Companion Tools

MDD is one part of a broader ecosystem. These tools are designed to work alongside it - each independently useful, each better in combination.