cdd — Comprehension-Driven Development

Spec-Driven Development gives the AI context before it writes code. Comprehension-Driven Development makes sure you understand the code after it does.

AI coding agents now write plausible code faster than any human can understand it. Tests pass, PRs merge, and nobody can explain how the system works — that's comprehension debt, and it's the technical debt your dashboard isn't measuring.

cdd is a comprehension gate: no change merges until a human can explain it.

npx cdd init          # scaffold the gate + install the git hook

How it works — two layers

1. Continuous (the cure). A git pre-commit hook runs cdd check on each commit: one targeted question about the riskiest part of your diff (failure modes, money, concurrency, security). You answer it — that's the point, you learn the code while it's cheap. Anything you can't explain becomes a COMPREHENSION_DEBT marker pinned to file:line.

2. Merge audit (the backstop). At the PR, cdd audit --ci doesn't re-quiz anything — it just blocks the merge if any COMPREHENSION_DEBT is still open.

git commit  →  cdd check   (understand this diff now)
   …
open PR     →  cdd audit   (verify nothing unexplained is merging)

Commands

| Command | What it does | Needs a model? | | --- | --- | --- | | cdd init [dir] [--strict] | scaffold the gate + install the git hook | no | | cdd check [--staged] | per-commit micro-check; records the ledger | optional | | cdd debt [--module m] | list open COMPREHENSION_DEBT with file:line | no | | cdd audit [--ci] | merge gate — fails if debt is open | no | | cdd report [--name n] | generate the HTML dashboard for leads | no | | cdd uninstall | remove the git hook (keeps your files) | no |

Modes. cdd init asks which mode you want, with a one-line explanation of each:

• warning — records comprehension gaps but lets the commit through (recommended to start).
• strict — a wrong answer blocks the commit until you understand/fix it.

Switch anytime in .comprehension/config.json, or skip the prompt with --strict / --warning (useful in CI). Skip the gate once with git commit --no-verify. The tool is not a background process — it only runs during git commit.

Minimal footprint. By default cdd init only adds .comprehension/ (two small JSON files) plus the git hook — it won't clutter your repo. Want the extras (Claude Code /understand skill, a CI workflow, and CLAUDE.md conventions)? Run cdd init --full.

No API key required. The quiz grades using whatever you already have, in this order:

1. An installed agent CLI (Claude Code, Gemini) used headlessly — it borrows the login you already have. This is the default; nothing to configure.
2. ANTHROPIC_API_KEY, only if you choose to set one.
3. Manual mode — records your answer without grading. Never a crash, never blocks.

Inside Claude Code, the /understand skill runs the whole gate using the agent itself.

The COMPREHENSION_DEBT marker

// COMPREHENSION_DEBT(AC-2): fail-open vs fail-closed when the processor is down
//   -> src/payments/queue.mjs:34 · owner: heric · opened: 2026-07-01

Greppable, CI-countable, resolved by making the code explainable (a test, a comment, a refactor) and then removing the marker — never by deleting the marker alone.

For engineering leaders

cdd report turns the committed ledger into a project-level dashboard: comprehension coverage, debt by module, and comprehension-orphaned files. It's aggregated — no per-developer data — so it measures project risk, not people.

Zero dependencies

Node ≥ 18, nothing else. It's a CLI, a git hook, a JSON ledger in your repo, and a GitHub Action. No backend, no service.

Prior art

Builds on Spec-Driven Development, GitHub Spec Kit, and igoruehara/spec-driven; adds the comprehension gate. See ATTRIBUTION.md. MIT licensed.