codd-dev 0.4.0

CoDD: Coherence-Driven Development — cross-artifact change impact analysis

CoDD — Coherence-Driven Development
Keep AI-built systems coherent when requirements change.

日本語 | English

---

Harnesses tell agents how to work. CoDD keeps artifacts coherent.

pip install codd-dev

Public Alpha — init / scan / impact are stable; validate is alpha.

---

Why CoDD?

AI can generate code from specs. But what happens when requirements change mid-project?

• Which design docs are affected?
• Which tests need updating?
• Which API contracts broke?
• Did anyone forget to update the database migration?

Spec Kit and OpenSpec answer "how do I start?" CoDD answers "how do I keep going when things change?"

How It Works

Requirements (human)  →  Design docs (AI)  →  Code & tests (AI)
                              ↑
                    codd scan builds the
                     dependency graph
                              ↓
            Something changes? codd impact tells you
             exactly what's affected — automatically.

The Three Layers

Harness (CLAUDE.md, Hooks, Skills)   ← Rules, guardrails, workflow
  └─ CoDD (methodology)              ← Coherence across changes
       └─ Design docs (docs/*.md)    ← Artifacts CoDD manages

CoDD is harness-agnostic — works with Claude Code, Copilot, Cursor, or any agent framework.

Core Principle: Derive, Don't Configure

Architecture	Derived test strategy	Config needed?
Next.js + Supabase	vitest + Playwright	None
FastAPI + Python	pytest + httpx	None
CLI tool in Go	go test	None

Upstream determines downstream. You define requirements and constraints. AI derives everything else.

Quick Start

pip install codd-dev
mkdir my-project && cd my-project && git init

# Initialize — pass your requirements file, any format works
codd init --project-name "my-project" --language "typescript" \
  --requirements spec.txt

# AI generates design docs (wave_config auto-generated)
codd generate --wave 2

# Build dependency graph → analyze impact
codd scan
codd impact

5-Minute Demo — See CoDD in Action

We'll build TaskFlow, a task management app. Write requirements in plain text, let CoDD + AI handle everything else.

Step 1: Write your requirements (any format — txt, md, doc)

# TaskFlow — Requirements

## Functional Requirements
- User auth (email + Google OAuth)
- Workspace management (teams, roles, invites)
- Task CRUD with assignees, labels, due dates
- Real-time updates (WebSocket)
- File attachments (S3)
- Notification system (in-app + email)

## Constraints
- Next.js + Prisma + PostgreSQL
- Row-level security for workspace isolation
- All API endpoints rate-limited

Save this as spec.txt. That's it — no special formatting needed.

Step 2: Initialize CoDD

pip install codd-dev
mkdir taskflow && cd taskflow && git init
codd init --project-name "taskflow" --language "typescript" \
  --requirements spec.txt

CoDD adds frontmatter (node_id, type, dependency metadata) automatically. You never touch it.

Step 3: AI generates design docs

codd generate --wave 2   # System design + API design
codd generate --wave 3   # DB design + Auth design
codd generate --wave 4   # Test strategy

wave_config is auto-generated from your requirements. Each design doc gets frontmatter and depends_on declarations — all derived, nothing manual.

Step 4: Build the dependency graph

codd scan

Frontmatter: 7 documents in docs
Scan complete:
  Documents with frontmatter: 7
  Graph: 7 nodes, 15 edges
  Evidence: 15 total (0 human, 15 auto)

7 docs, 15 dependency edges. Zero config written by hand.

Step 5: Change requirements mid-project

Your PM asks for SSO and audit logging. Open docs/requirements/requirements.md and add:

## Additional Requirements (v1.1)
- SAML SSO (enterprise customers)
- Audit logging (record & export all operations)

Save the file and ask CoDD what's affected:

codd impact    # detects uncommitted changes automatically

Changed files: 1
  - docs/requirements/requirements.md → req:taskflow-requirements

# CoDD Impact Report

## Green Band (high confidence, auto-propagate)
| Target                  | Depth | Confidence |
|-------------------------|-------|------------|
| design:system-design    | 1     | 0.90       |
| design:api-design       | 1     | 0.90       |
| detail:db-design        | 2     | 0.90       |
| detail:auth-design      | 2     | 0.90       |

## Amber Band (must review)
| Target                  | Depth | Confidence |
|-------------------------|-------|------------|
| test:test-strategy      | 2     | 0.90       |

## Gray Band (informational)
| Target                  | Depth | Confidence |
|-------------------------|-------|------------|
| plan:implementation     | 2     | 0.00       |

2 lines changed → 6 out of 7 docs affected. Green band: AI auto-updates. Amber: human reviews. Gray: informational. You know exactly what to fix before anything breaks.

Wave-Based Generation

Design docs are generated in dependency order — each Wave depends on the previous:

Wave 1  Acceptance criteria + ADR       ← requirements only
Wave 2  System design                   ← req + Wave 1
Wave 3  DB design + API design          ← req + Wave 1-2
Wave 4  UI/UX design                    ← req + Wave 1-3
Wave 5  Implementation plan             ← all above

Verification runs bottom-up (V-Model):

Unit tests        ← verifies detailed design
Integration       ← verifies system design
E2E / System      ← verifies requirements + acceptance criteria

Frontmatter = Single Source of Truth

Dependencies are declared in Markdown frontmatter. No separate config files.

---
codd:
  node_id: "design:api-design"
  depends_on:
    - id: "design:system-design"
      relation: derives_from
    - id: "req:my-project-requirements"
      relation: implements
---

codd/scan/ is a cache — regenerated on every codd scan.

Config Directory Discovery

By default, codd init creates a codd/ directory. If your project already has a codd/ directory (e.g., it's your source code package), use --config-dir:

codd init --config-dir .codd --project-name "my-project" --language "python"

All other commands (scan, impact, generate, etc.) automatically discover whichever config directory exists — codd/ first, then .codd/. No extra flags needed.

Brownfield? Start Here

Already have a codebase? codd extract reverse-engineers design documents from your source code. No AI required — pure static analysis.

cd existing-project
codd extract

Extracted: 13 modules from 45 files (12,340 lines)
Output: codd/extracted/
  system-context.md     # Module map + dependency graph
  modules/auth.md       # Per-module design doc
  modules/api.md
  modules/db.md
  ...

Philosophy: In V-Model, intent lives only in requirements. Architecture, design, and tests are structural facts — extractable from code. codd extract gets the structure; you add the "why" later.

# Review generated docs, promote confirmed ones
mv codd/extracted/modules/auth.md docs/design/
# Then build the dependency graph
codd scan
codd impact

Commands

Command	Status	Description
codd init	Stable	Initialize CoDD in any project (--config-dir .codd for projects where codd/ exists)
codd scan	Stable	Build dependency graph from frontmatter
codd impact	Stable	Change impact analysis (Green / Amber / Gray)
codd validate	Alpha	Frontmatter integrity & graph consistency check
codd generate	Experimental	Generate design docs in Wave order
codd plan	Experimental	Wave execution status
codd verify	Experimental	V-Model verification
codd implement	Experimental	Design-to-code generation
codd extract	Alpha	Reverse-engineer design docs from existing code

Claude Code Integration

CoDD ships with slash-command Skills for Claude Code. Instead of running CLI commands yourself, use Skills — Claude reads the project context and runs the right command with the right flags.

Skills Demo — Same TaskFlow App, Zero CLI

You:  /codd-init
      → Claude: codd init --project-name "taskflow" --language "typescript" \
                  --requirements spec.txt

You:  /codd-generate
      → Claude: codd generate --wave 2 --path .
      → Claude reads every generated doc, checks scope, validates frontmatter
      → "Wave 2の設計書を確認しました。Wave 3に進みますか？"

You:  yes

You:  /codd-generate
      → Claude: codd generate --wave 3 --path .

You:  /codd-scan
      → Claude: codd scan --path .
      → Reports: "7 documents, 15 edges. No warnings."

You:  (edit requirements — add SSO + audit logging)

You:  /codd-impact
      → Claude: codd impact --path .
      → Green Band: auto-updates system-design, api-design, db-design, auth-design
      → Amber Band: "test-strategyが影響を受けています。更新しますか？"

Key difference: Skills add human-in-the-loop gates. /codd-generate pauses between waves for approval. /codd-impact follows the Green/Amber/Gray protocol — auto-updating safe changes, asking before risky ones.

Hook Integration — Set It Once, Never Think Again

Add this hook and you never run codd scan manually again. Every file edit triggers it automatically — the dependency graph is always current, always accurate, zero mental overhead:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "codd scan --path ."
      }]
    }]
  }
}

With hooks active, your entire workflow becomes: edit files normally, then run /codd-impact when you want to know what's affected. That's it. The graph maintenance is invisible.

Available Skills

Skill	What it does
/codd-init	Initialize + import requirements
/codd-generate	Generate design docs wave-by-wave with HITL gates
/codd-scan	Rebuild dependency graph
/codd-impact	Change impact analysis with Green/Amber/Gray protocol
/codd-validate	Frontmatter & dependency consistency check

See docs/claude-code-setup.md for complete setup.

Comparison

	Spec Kit	OpenSpec	CoDD
Spec-first generation	Yes	Yes	Yes
Change propagation	No	No	Dependency graph + impact analysis
Derive test strategy	No	No	Automatic from architecture
V-Model verification	No	No	Unit → Integration → E2E
Impact analysis	No	No	codd impact
Harness-agnostic	Copilot focused	Multi-agent	Any harness

Real-World Usage

Battle-tested on a production web app — 18 design docs connected by a dependency graph. All docs, code, and tests generated by AI following CoDD. When requirements changed mid-project, codd impact identified affected artifacts and AI fixed them automatically.

docs/
├── requirements/       # What to build (human input — plain text)
├── design/             # System design, API, DB, UI (AI-generated)
├── detailed_design/    # Module-level specs (AI-generated)
├── governance/         # ADRs (AI-generated)
├── plan/               # Implementation plan
├── test/               # Acceptance criteria, test strategy
├── operations/         # Runbooks
└── infra/              # Infrastructure design

CoDD Manages Its Own Development

CoDD dogfoods itself. The .codd/ directory contains CoDD's own config, and codd extract reverse-engineers design docs from its own source code. The full V-Model lifecycle runs on itself:

codd init --config-dir .codd --project-name "codd-dev" --language "python"
codd extract          # 15 modules → design docs with dependency frontmatter
codd scan             # 49 nodes, 83 edges
codd verify           # mypy + pytest (127/127 tests pass)

If CoDD can't manage itself, it shouldn't manage your project.

Roadmap

• Semantic dependency types (requires, affects, verifies, implements)
• codd extract — reverse-generate design docs from existing codebases (brownfield support)
• codd verify — language-agnostic verification (Python: mypy + pytest, TypeScript: tsc + jest)
• Multi-harness integration examples (Claude Code, Copilot, Cursor)
• VS Code extension for impact visualization

Articles

• Zenn (Japanese): CoDD deep-dive
• dev.to (English): What Happens After "Spec First"

License

MIT