Claude-Driven Development (CDD)

CDD (Claude-Driven Development) is a human-in-the-loop workflow for building software with Claude Code. The idea is simple: let AI agents do as much of the work as possible, and automate everything you can, but keep a developer around for the decisions that matter. You're not watching an agent free-run. You're steering it through a disciplined lifecycle where you get to approve things before anything consequential happens.

A big part of what makes it work is being careful with context. When a single conversation tries to cover planning, implementation, review, and everything in between, all that mixed-together detail becomes a distraction and the quality of the results starts to suffer. So instead, every step gets its own fresh session with a single job and just the context it needs. The session doing the implementation isn't carrying the baggage of the planning discussion, and the one opening a PR isn't cluttered with half-finished exploration. It turns out that a handful of small, focused sessions tend to go a lot further than one giant one.

The other half is checking in often. One-shotting a whole task is a bit utopian: today's models don't handle it all that gracefully yet, and no agent can read your mind and know exactly what you want. Frequent, low-stakes check-ins fix that. Each time you approve a plan or review a change, you get a chance to nudge things back on course before they drift too far, so the end result lands much closer to what you actually wanted.

It also tries to bake in good engineering habits rather than hoping you'll remember them. The workflow reviews its own code and writes specs before it builds, and it looks after the hygiene that usually slips first when you're moving at AI speed: running tests, keeping documentation in sync, linting, formatting. The discipline is built into the lifecycle instead of taped on at the end.

Documentation gets the same care, and not just for your benefit. A structured knowledge base keeps the project's memory durable across all these throwaway sessions, and it's exactly what a coding agent needs to understand how things work and what to do next. It all comes back to the same goal: giving each session exactly the context it needs, and keeping you in control at every gate.

How it works

One full turn around the cycle:

1. Select a task — one, or several to run in parallel.
2. Write the handoff and create a git worktree for the task, isolated from your main checkout.
3. Plan the task. The worktree opens on /cdd-plan: it explores, shows you a short digest, and on your approval writes the plan to a file and stops. Read or edit that file if you want to.
4. Implement it. Open a fresh session in the same worktree and run /cdd-implement. It builds from the plan — not from the exploration that produced it — so you know what to expect, because you approved the plan.
5. Merge from the base branch if it moved while you were working, approving the merge plan.
6. Let an agent review the code before the PR opens — this is also where tests run and the docs are checked, linted, and formatted. It opens the PR at the end.
7. Review the PR and ask the agent to address your feedback.
8. Merge the PR, delete the worktree, pull the changes into your main worktree — and start over.

The process document describes the full lifecycle, the artifacts, the edit rules, and the reasoning behind every gate. Read it first if you want to understand what CDD is and why.

Quick start

CDD's front door is its guided commands. Here's the shortest path from zero to your first task:

git clone https://github.com/drabaioli/cdd.git && cd cdd
claude

Then, from inside that Claude Code session:

1. Run /cdd-bootstrap and start a new project. It walks you through defining the project and drafting a real roadmap through conversation, then scaffolds everything in one go — overview, CLAUDE.md, engineering-practices contract, and roadmap already filled in.
2. cd into your freshly created project and launch claude there.
3. Run /cdd-next-step to scope your first task.
4. Lift off — you're now running the task cycle above.

Other entry points, run the same way from a session inside this repo:

• Bring CDD to a project you already have: run /cdd-retrofit. It installs CDD into an existing codebase, or upgrades a project already running CDD, preserving your local customizations along the way.
• Produce a one-off deliverable that doesn't warrant a whole project (a single script plus a README, no roadmap or project substrate): run /cdd-quick-create.

Prefer to script it? The non-interactive tools/bootstrap-cdd-project.sh does the same scaffolding without the guided conversation.

Three objectives

CDD is built around three goals, in tension and balanced on purpose.

Automate everything except the decisions that matter. Everything between the human gates is automated; the gates, picking the task, approving the plan, approving a base-branch merge that has anything to decide, merging the PR, never are.

Bake in engineering best practices. Tests, linting, formatting, CI, and living documentation aren't bolted on at the end. The workflow expects them at every step, so quality and context don't erode as the project grows.

Improve the workflow as you use it. CDD is meant to be turned on itself. Friction surfaced in a session folds back into the process and the template, so the workflow gets sharper over time.

Command reference

CDD ships ten slash commands, all prefixed cdd- so they autocomplete as a group.

Per-task cycle, shipped into every CDD project via the template:

Command	What it does
/cdd‑next‑step	Scope the next task and write a handoff for a fresh plan session. Three front-ends: the next roadmap item, a typed task prompt (off-roadmap), or a tracker issue — whatever matches the resolved adapter's ref_pattern, plus the issue keyword to browse.
/cdd‑plan	Auto-started by cdd-worktree: explore, take plan approval, write the plan file, stop. Touches nothing in the repo.
/cdd‑implement	Started by hand in the same worktree: build from the plan file, update the docs, commit locally. Stops and reports rather than improvising when reality contradicts the plan.
/cdd‑small‑change	The small-change lane, in place of plan + implement: for a task whose finished diff you can state in one sentence. Takes its own approval of the concrete change, makes it, commits — or hands back to /cdd‑plan if the task turns out not to be small.
/cdd‑merge‑base	Integrate the base branch into a feature branch when the base has advanced under you (dry-run first, then apply).
/cdd‑pre‑pr	Pre-PR checklist: the project's check runner (the one command CI runs, so a green run here means a green CI), code review, and doc/roadmap reconciliation; ends with an opt-in step to open the PR.
/cdd‑process‑pr	Triage and address the open PR's review feedback, reply in-thread, and commit and push.

CDD-repo-only, run from a session inside this repo; they operate on a target, so the template ships no copy:

Command	What it does
/cdd‑bootstrap	Guided greenfield: define the project and draft a roadmap through conversation, then scaffold it.
/cdd‑retrofit	Install or upgrade CDD in an existing project.
/cdd‑quick‑create	Produce a one-off self-contained deliverable (script + README), no project substrate.

cdd-worktree (and its companions cdd-worktree-done, cdd-worktree-list, cdd-worktree-resume, and cdd-worktree-gc) is a shell helper, not a slash command. It's a single project-independent script — a machine-global toolchain dependency, like git or gh — that you install once and that then works in every CDD project. From a CDD repo checkout: tools/cdd-worktree.sh install. On a fresh machine with only a downstream project (no CDD repo), one command fetches and installs it:

curl -fsSL https://raw.githubusercontent.com/drabaioli/cdd/main/tools/cdd-worktree.sh \
  --create-dirs -o ~/.cdd/tools/cdd-worktree.sh \
  && bash ~/.cdd/tools/cdd-worktree.sh install

CDD's scripts need bash >= 4; macOS ships 3.2, so install Homebrew bash first (brew install bash). On an older bash the helper refuses to load, with a one-line message.

Either form wires ~/.bashrc and ~/.zshrc (idempotent); open a new shell afterwards. A project whose .cdd/ binds a tracker or code host also needs the adapter library at ~/.cdd/tools/adapters/: the checkout form installs it, while the curl form fetches only the helper and prints the one-line fetch for each adapter (see template/BOOTSTRAP.md). The checkout form keeps itself current: a pull of the checkout's default branch reinstalls the helpers when they changed, and open shells pick up the new code on their next command. Without a checkout, bash ~/.cdd/tools/cdd-worktree.sh update brings the helpers and the adapter library up to date with upstream main. It spins up and tears down the per-task git worktree that a task's plan and implementation sessions run in, and cdd-worktree-resume [<branch>] recreates that worktree on a second machine — tracking the existing remote branch — so a task started elsewhere can be picked up to run /cdd-implement, /cdd-process-pr, /cdd-merge-base, or /cdd-pre-pr. The task's handoff, plan file and state record ride along too, synced through a per-task git ref (advisory — resume still works without them). cdd-worktree-gc periodically reaps the handoff, plan file, state record, and synced ref of tasks whose PR has merged (dry-run unless --force), so those artifacts don't accumulate across machines. Once a task's PR has merged, cdd-worktree-done (or, as backstop, cdd-worktree-gc) also closes the issues the task was sourced from, through the tracker, and links the merged PR on each it closes.

Questions?

The fastest way to understand CDD is to ask it directly: launch claude on your local clone of this repo and ask away. The process doc, the template, and these docs are all right there for it to read.

Contributing

At this stage CDD accepts GitHub issues only; pull requests aren't open yet. Bug reports, suggestions, and questions about the workflow are very welcome: please open an issue. Have a change in mind? Raise it as an issue first and we can discuss it there. Direct PRs aren't being accepted for now. That will change as the project opens up.

Status

Currently in active development and working quite well. See doc/knowledge_base/roadmap.md for what's done and what's next.

License

MIT © Diego Andres Rabaioli.