MDD workflow improvements from 5 weeks of daily use: TDD gates, block structure, parallel agents

[iKon85]

Context

We integrated MDD into a real product project on 2026-03-10 (based on the worktree-support version of /mdd) and have been using it daily for ~5 weeks on a test-management tool for SAP rollouts (React 19 + Express + Supabase, pnpm monorepo).

First: thank you. The workflow has genuinely changed how we build — docs-before-code stuck, and the .mdd/docs/ tree is now the living spec. We also noticed your recent additions on 2026-04-12 (scan / update / deprecate / reverse-engineer / graph modes + the data flow analysis phase) and plan to pull those into our fork. The proposals below are orthogonal to those additions — they came out of daily use on the parts of the workflow that existed on 2026-03-10.

Happy to send focused PRs for any of the below if useful — all are additive, no breaking changes.

---

Tier 1 — TDD loop gates (the strongest case)

These three fix concrete fail-modes we hit repeatedly before adding them.

1. Red Gate — verify skeletons actually fail before implementing

Problem. Phase 4 (skeleton generation) → Phase 6 (implement) currently has no check that the generated skeletons are actually red. We hit two fail-modes:

• A skeleton with no real assertion (e.g., an empty it that doesn't call expect.fail) passes vacuously — implementation "succeeds" against nothing.
• Pre-existing code occasionally already satisfies a skeleton, so the test passes green from the start and the "TDD" phase is fiction.

Fix. Add a mandatory Phase 4b between skeletons and implementation: run the new test file(s), assert that every new test fails, report 🔴 Red Gate: N/N failing (expected). Don't proceed until red.

Our implementation:

**Phase 3b — Red Gate (mandatory)**

Run all newly created test skeletons to confirm they fail:

    pnpm --filter backend run test -- <test-file-path>

Every single skeleton test MUST fail. If any test passes unexpectedly,
investigate — either the skeleton has no assertion or there's pre-existing
code that already satisfies it. Fix the skeleton or adjust scope.

Report:
    🔴 Red Gate: <N>/<N> tests failing (expected)
       All skeletons confirmed RED — ready to implement.

Do NOT proceed to Phase 4 until the Red Gate passes.

2. Green Gate — iterative diagnosis-first loop with a hard cap

Problem. Phase 6 runs pnpm typecheck + pnpm test:unit once. On failure there's no recovery strategy, which in practice becomes an uncapped blind-retry loop: the agent re-runs tests, tries a guess, re-runs, tries again, runs out of context.

Fix. A spec-driven loop capped at 5 iterations, each enforcing a diagnosis step before the fix:

1. Run feature tests + tsc --noEmit
2. Diagnose — exact error? Which implementation assumption was wrong? Known pattern (check .claude/learnings.md)? What is the one targeted fix?
3. Fix — adjust implementation, not the test. If the test seems wrong → re-read the doc. If the doc is wrong → pause, ask the user.
4. Report — one-line root cause + one-line fix summary per iteration.
5. Repeat until green.

Exit conditions:

• All feature tests + tsc green → proceed to regression check (full suite; failures count against the same 5-iteration budget).
• After 5 iterations still failing → stop, report remaining failures with diagnoses to the user. Do not keep trying.

This catches runaway loops and — importantly — forces the agent to state why each fix was chosen, which improves quality.

3. Integration happy-path hard gate before reporting "done"

Problem. Phase 7 treats unit tests green + typecheck clean as "MDD Complete". This is the biggest gap we hit — several times the full unit suite was green, but against the real DB / real external API the feature didn't actually work (classic mock/prod divergence, or the UI page never actually rendered the new data). The "✅ MDD Complete" report created false confidence.

Fix. Phase 7 must include an explicit integration step:

• Backend features: trigger the full flow against the real DB / API (not just individual endpoints). Actively watch backend logs during the run. Any rate anomaly or unexpected error pattern is an immediate log-check trigger.
• Frontend features: click through the actual user flow in the browser, open the target page, visually verify the expected data appears.
• DB features: check the rows actually written/read via SQL, not "insert returned no error".

Key rule: external conditions ("API offline", "slow", "missing test data") are not an excuse to mark the feature done. They are hypotheses that need to be empirically proven before being accepted as blockers. Default assumption on any external failure: my code is wrong until proven otherwise.

If integration is not verified, the report is not "✅ MDD Complete" — it's "⏸️ MDD Blocked on condition X" with a concrete next action for the user.

---

Tier 2 — Structural improvements

4. Block structure instead of flat steps (Phase 5)

Currently Phase 5 presents a flat Step 1 (Types), Step 2 (Handler), ... list. We replaced that with blocks — a block is a unit of work that satisfies three qualitative criteria:

1. Runnable end-state — after the block, code compiles, tests green, no half-open interfaces
2. Commit-worthy scope — a clear "why" for a standalone commit message
3. Own verification — a concrete test/check command that proves "done"

Each block is labeled small / medium / large as a sanity check. large requires a justification why no split is sensible (typically: shared type contract forces backend + frontend into one block). If the justification doesn't hold → split.

Each block also includes a handoff contract — the interface/assumption the next block depends on.

Benefit: better commit hygiene, better abort points for long features, much less "half-done" state mid-session. For very small features, the rule is "one block, don't over-structure".

5. Parallel agents with model-per-task routing

Currently the /mdd flow runs sequentially with an implicit single model. We get measurable speed-ups (and cost savings) by routing:

Task type	Model	Rationale
Research, scanning, reading docs	sonnet	Fast, cost-effective, information gathering
Architecture, doc writing (Phase 2)	opus	Deep reasoning about system design
Planning, build plan (Phase 4)	opus	Dependency analysis, risk assessment
Test skeletons	sonnet	Structured template work
Simple implementation (types, routing)	sonnet	Pattern-following
Complex implementation (business logic, multi-file)	opus	Deep reasoning, cross-file consistency
Typecheck, test runs, verification	sonnet	Command running + reporting

Rules for parallelization:

• Only parallelize tasks with no data dependencies between them
• Each agent gets a complete, self-contained prompt — all context it needs (file paths, feature description, project conventions)
• Agent results are collected and synthesized in the main conversation before presenting to the user

Concrete application: Phase 1 runs three Sonnet agents in parallel (context-rules, context-features, context-codebase). Phase 3 runs two Sonnet agents in parallel for unit + E2E skeletons.

6. Layered parallelization within implementation (Phase 6)

Within a block, we group steps into layers by dependency:

Layer 1 (no dependencies):     Types, shared interfaces
Layer 2 (depends on Layer 1):  Backend services, frontend components  ← parallel agents here
Layer 3 (depends on Layer 2):  Route wiring, integration points
Layer 4 (depends on all):      Test implementation, final wiring

Sequential layers, parallel agents within a layer when multiple steps are independent. If only one step in a layer → execute directly in main conversation (no agent overhead).

---

Tier 3 — Culture / ownership default

7. Ownership default when hitting external errors

Documented in our CLAUDE.md and referenced from Phase 7: "My code is wrong until proven otherwise. Not: the API has a problem."

Procedure on any anomaly (400/500/timeout/unexpectedly slow): (1) read backend logs, (2) run a minimal probe script against the real interface, (3) then form a root-cause hypothesis.

Even when an external cause is empirically confirmed, the feature is not "done with an asterisk" — it's "blocked on condition X". Status is "in progress", not "done".

This costs ~1 extra minute per incident but eliminates a class of wrong-attribution that otherwise sends the agent patching the wrong thing.

---

What we'd like to pull from you (for symmetry)

Not asking for anything here, just acknowledging — these are excellent and we'll be adopting them:

• Phase 2 data flow & impact analysis gate
• scan / update / deprecate / reverse-engineer / graph modes
• .mdd/.startup.md auto-context
• last_synced / status / phase frontmatter for drift tracking
• Tooling-task detection (skipping DB/API questions)

---

PR offer

If any of the above sounds useful, I'm happy to send focused PRs — one per proposal, small diffs, each additive with no breaking changes. Tier 1 would be three short PRs (~20–80 lines each). I can also port them to match your current Phase numbering (our fork is at your 2026-03-04 baseline, so the phases renumbered after your 2026-04-12 additions).

Let me know which (if any) you'd want, and whether you'd prefer them as separate PRs or one combined.

Thanks again for building this — it's genuinely shifted how I think about feature work.

[TheDecipherist]

Hey @iKon85 — thank you for this. Five weeks of daily production use and a writeup this detailed is exactly the kind of feedback that's hard to get and easy to act on.

We've implemented all seven proposals. Here's what landed:

Tier 1 — TDD Gates

All three, as you described:

• Red Gate (Phase 4b): Mandatory gate after skeleton generation — runs only the new test file(s), asserts every skeleton actually fails. If any passes (vacuous assertion or pre-existing code already satisfying it), it blocks and asks before proceeding. No skip condition.
• Green Gate (Phase 6b): 5-iteration cap, diagnosis required before each fix ("exact error, which assumption was wrong, one targeted fix"), one-line root-cause + fix summary per iteration. At iteration 5 it stops and presents remaining failures with diagnoses — doesn't keep trying. Regression check runs against the full suite after each block goes green, counted against the same budget.
• Integration Gate (Phase 7b/7c): Split Phase 7 into 7a (typecheck + unit tests), 7b (integration verification with a feature-type-aware checklist: backend/frontend/DB/tooling), and 7c (completion signal). ✅ MDD Complete only fires if integration is verified. If an external condition blocks it, the output is ⏸️ MDD Blocked: <condition> with evidence, a specific hypothesis, and a concrete next step — code is complete, feature is not done. Your ownership default language is in 7b verbatim: "My code is wrong until proven otherwise" with the 3-step probe procedure.

Tier 2 — Structural

• Block structure (Phase 5): Auto-sizes by feature complexity — simple features (<3 files, no API, no DB) keep flat steps, medium/large use blocks. Each block has runnable end-state, conventional commit scope, verification command, and handoff contract. Large blocks require a justification; unjustifiable ones trigger an auto-split suggestion. Blocks are annotated → main conversation or → parallel agents (N) based on a file-declaration gate and type-dependency gate run before the plan is presented.
• Parallel agents (Phase 5 + 6): Implemented with explicit safety constraints that address the bugs we'd hit before: (1) file declaration gate — every file each agent writes is listed upfront, any overlap falls back to sequential; (2) type dependency gate — if Block X creates types Block Y imports, Block X runs first; (3) max 2 parallel agents during implementation; (4) each agent prompt is fully self-contained with all Layer 1 output embedded, not referenced by path; (5) post-batch typecheck before the next layer starts; (6) agents never touch shared files (router, index, config) — those stay sequential. Phase 6 layered execution follows your dependency layer model (Types → Services/Components → Wiring → Tests).
• Layered parallelization (Phase 6a): Sequential layers, parallel agents within a layer when both safety gates pass.

Tier 3 — Ownership Default

In Phase 7b, applies to all feature types.

---

We also extended parallel agents to the other modes since the same pattern fits naturally:

• Audit Phase A2 — the most expensive phase. Features are batched (up to 3 parallel Explore agents), each reads its assigned source files and returns structured notes back to the main conversation, which is the single writer of the notes file. Single-feature audits stay sequential.
• Scan Phase SC2 — one Explore agent runs all git log drift checks in a single pass and returns a classification table (in_sync/drifted/broken/untracked). Eliminates the sequential bottleneck when you have many features.
• Reverse-Engineer Phase R2 — parallel agents for multi-file scopes (≤3 files stays in main conversation, 4+ files batched across up to 3 agents).

All six parallelization points use the same safety model: read-only agents, main conversation is single writer, max 3 agents active, self-contained prompts, silent fallback to sequential on failure.

---

On the PR offer — we went ahead and built it directly so it's already in, but we'd genuinely like you to test it on your fork and report back. The phase numbering shifted slightly (Phase 4b is new, Phase 7 is now 7a/7b/7c), but the logic maps directly to your proposals. If anything doesn't behave as you described from your production experience, open another issue or send the PR — real-world corrections to workflow behavior are exactly what improves this.

Thanks again for taking the time to write this up.

[iKon85]

Although I am currently facing challenges with Claude (and I firmly believe I'm not alone), your workflow and the fork I've built upon it have been genuinely helpful. I really enjoy diving deep into understanding the Claude workflow and diagnosing what went wrong.
I haven't yet identified the exact point where additional "rules" in claude.md and similar configurations become counterproductive, but I've observed something interesting: less is often more (as proven in recent academic research), and over-constraining the model can actually degrade quality (when I try to force it into a framework that doesn't fit). I'd be interested in your perspective on this.
Additionally, I've started working on campaign planning (for example, large greenfield implementations) to accommodate smaller context windows. If you're interested, I can have Claude document this approach. I believe the 3-Tier methodology I've developed could genuinely help break down large initiatives into manageable chunks.

[TheDecipherist]

The "less is more" observation is one we keep running into too. The instinct when something breaks is to add a rule, but past a certain point the file works against you. Rules compete for attention, and you get compliance theater: the rule is technically followed, the intent is missed. We try to keep CLAUDE.md to rules that have a concrete failure mode behind them. If we can't say "we got burned by X", it probably doesn't belong there.

On the 3-Tier methodology: that's exactly the structure you used in your original issue. We already implemented all of it. If you've got something beyond that for large greenfield work specifically, we'd like to see it.

Two other things that landed since your issue: /install-global mdd for pushing MDD updates to your global install without re-running the full setup, and mdd-tui on npm -- a terminal dashboard for your .mdd/ workspace (drift counts, doc browser, audit viewer). Might be useful given the scale you're working at.