CoDD — Coherence-Driven Development

日本語 | English | 中文

pip install codd-dev

# Inside your project root
codd init --suggest-lexicons --llm-enhanced   # AI picks the lexicons that fit
codd elicit                                    # AI finds gaps in your requirements
codd dag verify --auto-repair --max-attempts 10  # AI fixes coherence violations

That's it. Three commands, three feedback loops, one coherent project.

Real-world: dogfooded against a Next.js + Prisma + PostgreSQL LMS. See Case study.

flowchart LR
    R["Requirements (.md)"] --> E["codd elicit"]
    E -->|gap findings| H{HITL: approve / reject}
    H -->|[x]| L["project_lexicon.yaml + requirements TODOs"]
    H -->|[r]| I["ignored_findings.yaml"]
    L --> V["codd dag verify --auto-repair"]
    V -->|violation| AR["LLM patch propose → apply"]
    AR --> V
    V -->|SUCCESS| D["✅ deploy gate passes"]
    AR -->|max attempts| P["PARTIAL_SUCCESS: unrepairable surfaced honestly"]

Brownfield path:

flowchart LR
    Code["Existing codebase"] --> X["codd extract"]
    X --> DIFF["codd diff (drift)"]
    DIFF --> EL["codd elicit (coverage gaps)"]
    EL --> H{HITL gate}
    H --> Apply["codd elicit apply"]
    Apply --> V["codd dag verify"]

A Next.js + Prisma + PostgreSQL multi-tenant LMS (≈30 design docs, 12 DB tables, RLS-enforced isolation):

The full pipeline change is zero lines of CoDD core changes per project — every project-specific concern lives in project_lexicon.yaml or in codd_plugins/ (Generality Gate, Layer A / B / C).

"Write only functional requirements and constraints. Code is generated, repaired, and verified automatically."

Most "AI-assisted dev" tools focus on the generation side. CoDD focuses on the constraint side: the LLM is most useful when it has a precise picture of what must be true. CoDD provides that picture as a DAG that links every artifact, plus a plug-in surface that lets industry standards (BABOK / WCAG / OWASP / PCI / ISO …) supply the constraints mechanically.

When something breaks the DAG, an LLM proposes a patch, the loop re-verifies, and either reaches SUCCESS or surfaces what is structurally unrepairable — honestly.

This is what lets CoDD ship one core that works for Next.js, Django, FastAPI, Rails, Go services, mobile apps, ML model cards — and that lets contributors add a lexicon without touching the core.

• v2.10.0 (current) — Lexicon-driven completeness, 38 plug-ins, LLM-enhanced init, scope/phase filter, auto-repair across the full DAG.
• v2.11.0 (next) — Sprint-less codd implement (--design <path> --output <dir> directly; implementation_plan.md parser removed). See migration guide.

CoDD is shaped by the following people:

• @yohey-w — Maintainer / Architect
• @Seika86 — Sprint regex insight (PR #11)
• @v-kato — Brownfield reproduction reports (Issues #17 / #18 / #19)
• @dev-komenzar — source_dirs bug reproduction (Issue #13)

External issues, PRs, and lexicon proposals are welcome — see Issues.

• CHANGELOG.md — every release with quality metrics
• docs/ — architecture notes
• codd --help — full CLI reference

CoDD ships hook recipes for editor and Git workflows:

• Claude Code PostToolUse hook recipe for running CoDD checks after file edits
• Git pre-commit hook recipe for blocking commits when coherence checks fail

Recipes live under codd/hooks/recipes/.

MIT — see LICENSE.

• PyPI
• GitHub Sponsors — support development
• Issues

When code changes, CoDD traces the impact, detects violations, and produces evidence for merge decisions.