CLAUDE.md Template

A governance contract between Claude Code and your project.

The CLAUDE.md template is what makes GDD operational for AI agents. Drop it into your project root, point it to your .gdd/ directory, and Claude Code will:

• Read the governed constraint set before every implementation pass
• Surface [UNKNOWN] and [CONFLICT] items before generating dependent code
• Trace every governed output back to its constraint ID
• Stop at the Synthesis Gate when ambiguity cannot be resolved without human input

Step zero

The CLAUDE.md is step zero — separable from the ICR cycle. Even with an empty .gdd/CONSTRAINTS.md, it makes the agent governance-aware and establishes the behavioral contract for when constraints are added.

The Template

Copy this file to your project root as CLAUDE.md:

# CLAUDE.md

> This project uses Governance-Driven Design (GDD).
> This file instructs you on how to operate within the GDD governance layer.
> Read this file completely before taking any action in this project.

---

## What GDD Is

Governance-Driven Design is a pre-execution discipline that formalizes
intent before any artifact is produced. This project maintains a `.gdd/`
directory that contains the Governed Constraint Set — the ground truth
for what this system must hold true, must not violate, and has not yet
resolved.

Your job is to build within that constraint set — not around it.

Reference: https://github.com/semanticintent/governance-driven-design

---

## Before You Generate Anything

Before writing any implementation code, any schema, any configuration,
or any test — read the GDD layer:

  1. Read .gdd/CONSTRAINTS.md       — the governed constraint set
  2. Read .gdd/RESIDUE.md           — open items requiring human decision
  3. Read .gdd/GATES.md             — human decisions already made

Then ask yourself:

  → Does any [UNKNOWN] or [CONFLICT] item in RESIDUE.md
    affect what I am about to generate?

    If YES  — surface it to the human before proceeding.
    If NO   — proceed, noting which constraints govern your output.

---

## Constraint Status Reference

  [RESOLVED]   — implement exactly as stated
  [ASSUMED]    — implement, add: // GDD:ASSUMED — verify before production
  [UNKNOWN]    — do not implement; surface to human first
  [CONFLICT]   — do not implement either side; surface both for resolution

---

## While You Generate

Trace governed outputs back to their constraint:

  // GDD:CONSTRAINT-001 — DTI threshold is regulatory floor, not policy
  // Resolution: CCO confirmed 43% immutable (2026-06-26)
  if (dtiRatio >= 0.43) {
    return decline(REASON.DTI_EXCEEDED);
  }

---

## When You Encounter New Unknowns

Surface as a proposed residue item:

  I've encountered an assumption not in the GDD constraint set:

    Statement: [what you are about to assume]
    Stress: this breaks if [what would make it wrong]
    Proposed status: [ASSUMED / UNKNOWN]
    Affects: [what you cannot safely generate without a decision]

  Should I add this to .gdd/RESIDUE.md and pause, or proceed?

---

## What You Must Never Do

  ✗ Do not implement logic that depends on an [UNKNOWN] item
  ✗ Do not resolve a [CONFLICT] by picking a side silently
  ✗ Do not reinterpret a [RESOLVED] constraint for elegance
  ✗ Do not delete or modify .gdd/ files — append only
  ✗ Do not proceed past a Synthesis Gate without human confirmation

## What You Should Always Do

  ✓ Read .gdd/ before every implementation pass
  ✓ Trace every governed output back to its constraint
  ✓ Surface new unknowns immediately — before generating
  ✓ Name tests after the constraints they protect
  ✓ Ask: "is there a constraint that governs this?" before assuming

Generating Tests for Governed Logic

When writing tests for a governed constraint, name the test after the constraint:

describe('CONSTRAINT-001: DTI threshold is regulatory floor', () => {
  it('declines when DTI equals 43%', ...)
  it('declines when DTI exceeds 43%', ...)
  it('does not decline when DTI is 42.99%', ...)
})

A test that does not reference the constraint it protects is a test that can be silently deleted without anyone knowing what governance it was enforcing.

---

See the full .gdd/ folder structure → Structure