Using CDF with Claude Code

This guide was drafted by a Claude Code agent working inside a CDF-governed repository, describing the integration from first-hand experience of being governed by it.

Setup

1. Install the CDF plugin in VS Code and run CDF: Guided Setup (or CDF: Initialise Workspace) so the workspace has .cdf/config.yaml and steering files.
2. Run CDF: Register All Agent Bridges, or leave cdf.bridges.autoRegister enabled. This registers the shared cdf-governance MCP bridge that Claude Code discovers automatically.
3. Keep CDF: Sync AGENTS.md current. The generated AGENTS.md is what tells any agent, Claude Code included, the rules of the repository: required tools, artefact structures, review policy, and the workflow itself.

What a governed session looks like

From the agent’s seat, the flow is enforced rather than suggested:

1. Health first. The session must call cdf_tool_health before any other CDF tool; the bridge rejects everything else until it has. If health is degraded, the agent reports the remediation instead of improvising.
2. Classify before editing. cdf_begin_work decides whether the request is a simple change or a governed spec. There is no skipping this: working on code without an in-progress task is a governance violation the plugin detects.
3. Artefacts through tools. Requirements, design, tasks and implementation records are written with cdf_write_artefact, which validates required sections and stamps provenance (author, model, content hash). Editing an artefact directly invalidates its hash, and the phase gate catches it.
4. Gates need humans. cdf_check_phase_gate and cdf_advance_spec enforce review approvals. The bridge is strict about what approval means: replying “approved” to the surfaced review card counts; work-direction language such as “go ahead and build it” is refused as approval, verbatim.
5. Tasks are claimed and closed. cdf_claim_task_execution before starting, cdf_update_task_status immediately after finishing, with verification evidence in the note. The tasks file is the recovery point if a session dies.
6. Every call explains itself. Each CDF tool call carries a reasoning field that lands in the append-only audit journal, so a human can later read why the agent did what it did, not just what it did.

Practical notes for Claude Code specifically

• Claude Code parallelises tool calls; the CDF bridge is safe for that, but keep gate-adjacent calls sequential (record review, then advance, then check).
• Long sessions survive context compaction because the durable state lives in the repository: tasks.md, the audit journal and the spec artefacts are the memory, by design.
• If a gate refuses something that seems reasonable, the refusal is the product working. Surface the review card to the human rather than looking for a way around; there is a documented Break Glass procedure for genuine emergencies, and it is deliberately narrow.

The shape of the result

A governed Claude Code session produces the same evidence a governed human contributor would: classified intake, approved requirements, design and tasks, per-task claims with verification, provenance on every artefact, and an audit timeline with reasoning. The agent moves fast inside the gates, and the gates are real. That is the point.