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 26 Modes

MDD organises its 26 modes into 8 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.

Projects Built with MDD

Every project listed here was built start to finish using this exact workflow - not "used MDD for some features," but spec first, feature docs second, code third. The same seven phases, the same gates, every time.

How It Gets Built

These projects all came out of the same process. The spec-import path - spending a few hours filling out a spec template with Claude Desktop before writing a line of code - is the one I keep coming back to. Here's exactly how it works:

/mdd import-spec ./MDs/spec-name.md

/mdd feature-doc-name

Why this works: The spec conversation is where the hard thinking happens - not while writing code. Feature docs are the source of truth because code drifts and docs don't; if something changes, you update the doc and rebuild from it. The gates (Red Gate, Green Gate, Integration Gate) enforce correctness at every step - there's no "I'll test it later" path through the workflow.

This is not "one prompt and done." If you skip the spec work, skip the feature docs, or shortcut the gates, you'll get roughly what you'd get from any AI coding tool - something that looks right but breaks in ways you don't discover until production. The workflow is what makes the difference.

The Projects

Here's everything built with this workflow since March 2026:

Many more in the pipeline, including MDDv2 - a full rewrite built on MarkdownAI that in early tests runs significantly faster than the current version. MDDv2 will ship as its own package when it's ready.