iTranslated by AI
Putting AI-Driven Development into Practice: Managing Dependencies Between Design Specs and Code with AI-DLC and CoDD
Summary
To address the common software development challenge where design documents quickly diverge from code, I redesigned the development workflow with AI-DLC at its core, incorporated CoDD's concept of maintaining consistency between documents and code, and added Graphify to visualize dependencies in a way that is easy for humans to understand.
The key is that this is organized as a workflow that allows you to handle design documents, code, and graphs continuously in sync, rather than just generating documents.
Introduction
As you can see from my past posts, I am a huge AWS enthusiast.
- Data processing at the edge with AWS IoT Greengrass & transfer to IoT SiteWise - Part 1
- I designed and built container operations using AWS Fargate and ECS. ~Building Fargate + ECS~
Recently, I've been using Claude Code heavily, and I've been thinking, "If I'm developing with AI, why can't I formalize it into a proper flow?"
That's when I became interested in the concept of AI-DLC (AI-driven Development Lifecycle) advocated by AWS. The idea is to manage requirements definition, code generation, and testing through a consistent phase management approach. While this is great, the issue that always bothered me was the "divergence problem between documentation and code."
Specifically, this happens:
- Immediately after writing the code, it matches the design document.
- A month later, you fix the code for a bug.
- No one updates the design document.
- Before you know it, the design document becomes "false documentation."
I have built serverless architectures on AWS many times, and when the dependencies between Lambda, DynamoDB, and API Gateway become complex, questions like "Which table did this Lambda touch?" or "Is this design document still correct?" really occur. Every time that happens, you have to read the code again... everyone has experienced this, I'm sure.
While looking for a good way to solve this, I encountered the concept of CoDD (Coherence-Driven Development).
What is CoDD (Coherence-Driven Development)?
For CoDD, please check this Zenn article. It is highly educational and worth a read.👀
In short, it is a "development methodology that continuously verifies and maintains the consistency between documentation and code."
Key concepts include:
- Wave Layers (L1–L6): A hierarchical structure of design documents that refine concrete details in the order of requirements definition → architecture → detailed design → code.
-
CoDD frontmatter: Metadata embedded in each Markdown document. It declares dependencies between documents and between documents and code, such as
node_id,depends_on, andsource_files. - CoDD CLI: A CLI that parses frontmatter to build dependency graphs, check consistency, and measure coverage.
---
codd:
node_id: "design:showcase-service"
type: design
depends_on:
- {id: "req:showcase-platform", relation: "depends_on"}
source_files:
- "source/backend/showcase-service/app/router.py"
- "source/backend/showcase-service/app/repository.py"
confidence: 0.9
---
Just by writing a YAML block at the top of a document like this, the CoDD CLI builds a dependency graph between documents. Running codd validate checks whether the source files referenced by the document actually exist, and whether the parent documents specified in depends_on exist.
By integrating the flow of extracting the latest state with codd extract and checking consistency with codd validate into your CI, you can catch the moment a document becomes "untrue."
AI-DLC × CoDD × Graphify 3-Layer Architecture
While AI-DLC and CoDD are powerful on their own, I have reorganized the development flow in my own way. I put the AI-DLC procedures at the core, incorporated the CoDD concept of maintaining consistency, and further organized it into a 3-layer architecture visualized in a way that is easy for humans to follow using Graphify.
Layer 1: AI-DLC Workflow Engine
-
CLAUDE.md← Orchestrator (phase management, approval gates, audit trails) -
.aidlc-rule-details/← Detailed rules for each phase
Layer 2: CoDD Document Engine
-
codd CLI← Design document generation, frontmatter management, change propagation codd scan/validate/measure/extract/propagate
Layer 3: Graphify Knowledge Graph
-
graphify CLI← A singlegraphify-out/graph.json- AST (deterministic edges) + LLM semantic analysis (inferred edges)
- Leiden community detection
The point is the design that "Graphify is the only graph tool for users." The internal CoDD index (.codd/scan/) is for internal processing like codd impact and codd propagate, while the canonical graph shown to users is always just graphify-out/graph.json.
Graphify is Interesting
Here is what Graphify does:
- AST Edges (EXTRACTED): Statically analyzes source code import statements to generate deterministic dependency edges.
- Semantic Edges (INFERRED): Edges estimated by an LLM that "this class is semantically related to this document" (confidence 0.7–0.9).
- Ambiguous Edges (AMBIGUOUS): Lower confidence relationships (confidence 0.4–0.6).
- Leiden Community Detection: Detects "natural module boundaries" through graph clustering → candidates for Units of Work.
- God Nodes: Nodes with many connections = architectural hubs. Classes or functions with the greatest impact range when modified.
Moreover, the depends_on entry in the CoDD frontmatter acts as an EXTRACTED edge in Graphify, serving as a bridge. Since dependencies written in the design document are reflected directly in the graph, no special integration code is required.
Three-Way Coherence Closure
The highlight of this system is the three-way coherence closure after code generation:
# Step 1: Import the latest code into CoDD (CoDD = the master of truth for design)
codd extract
# Step 2: CoDD internal consistency check (major gate)
codd validate
# Step 3: Synchronize derived graphs
/graphify --update
# Step 4: Consistency check query
/graphify query "Summarize coverage, missing links, and major risks"
By executing these four steps every time you write code, you confirm that "the design document, code, and graph are all consistent." Combining this with human approval gates (HITL: Human in the Loop) prevents accidents where the AI runs wild and you fail to notice it generated code that is completely different from the design document.
Reverse Engineering a Self-Made Dance Management App
Seeing is believing, so I tried reverse engineering a dance and stage composition management app (a dance showcase platform) that I built.
App Architecture
This is truly a "serverless architecture built by a huge AWS enthusiast":
- Frontend: React + TypeScript + Vite → Distributed via CloudFront
- Backend: Python FastAPI × Lambda
- Auth: Amazon Cognito (PKCE flow)
- Data: DynamoDB (UsersTable / ShowcasesTable / TracksTable / SharesTable)
- Storage: S3
- Infrastructure: AWS CDK (TypeScript)
The Graphify Results Were Interesting
Graph Statistics
- 377 nodes · 572 edges · 72 communities
- EXTRACTED: 69% · INFERRED: 31% · AMBIGUOUS: 0%
Automatically Named Communities (Unit Candidates)
Graphify's Leiden detection automatically names the communities:
| # | Community Name | Node Count | Description |
|---|---|---|---|
| 0 | Showcase Data Models | 38 | Data models in general |
| 1 | Showcase CRUD Repository | 27 | Repository layer + tests |
| 2 | Auth Dependencies | 20 | JWT validation / IDOR prevention |
| 3 | Frontend API Client | 19 | Frontend API calling layer |
| 4 | Cognito PKCE Auth | 18 | Cognito auth flow |
| 5 | User Service | 15 | Entire user service |
| 6 | RE Design Documents | 17 | Generated design documents |
| 7 | Animation Controller | 3 | Touch operations / zoom |
| 8 | Animation Engine | 4 | Keyframe interpolation |
Just by looking at this list without reading the code, you can immediately understand "what this app is made of." Furthermore, as Community 6, "RE Design Documents," the design documents generated by AI-DLC are themselves nodes in the graph, placing code and design documents on the same graph.
God Nodes (Architectural Hubs)
- UserRepository — 21 edges
- Showcase — 18 edges
- SharedTrackInfo — 15 edges
- apiFetch() — 15 edges
- Point — 14 edges
- Stage — 14 edges
It makes sense that UserRepository is 1st with 21 edges. Since both showcase-service and media-service reference user information for authentication, it acts as a bridge across three services.
Graphify provides insights like "You might not have noticed, but this node is super important":
Why does UserRepository connect User Service to Showcase Data Models, Showcase CRUD Repository, Auth Dependencies?
High betweenness centrality (0.041) - this node is a cross-community bridge.
Nodes with high betweenness centrality have the maximum impact range when modified. If you know this in advance, you can judge that "when making changes to UserRepository, I have to test all three services" without having to read the repositories.
Generated Design Documents
Documents generated via reverse engineering:
aidlc-docs/inception/reverse-engineering/
├── business-overview.md ← Business context diagram + 12 business transactions
├── architecture.md ← System architecture diagram + component descriptions
├── code-structure.md ← Directory structure / module relationships
├── api-documentation.md ← List of all endpoints (equivalent to OpenAPI)
├── component-inventory.md ← Component catalog
├── technology-stack.md ← Technologies used / versions
├── dependencies.md ← External dependencies
├── interaction-diagrams.md ← Sequence diagrams (Presigned URL flow, etc.)
├── code-quality-assessment.md ← Security rules / code quality assessment
└── technology-stack.md
Graph After codd validate
-
codd scan→ 105 nodes, 165 edges (18 frontmatter documents registered) -
graphify --update→ 377 nodes, 572 edges, 72 communities
When updating the graph after running RE, the design document group is automatically added to the graph as the "RE Design Documents" community. A state where code and design documents share dependency relationships on the same graph has been achieved.
Highlights
✅ Code and documentation are on the same graph
codd validate checks document consistency, and Graphify provides visualization across code and documents. You create a mechanism that can detect in CI situations where "the design document is lying."
✅ Graphify's community detection serves as a reference for unit decomposition
When adding new features, you can see at a glance which community is affected. If you look at God Nodes, you can immediately tell which "files are dangerous to touch."
✅ Application to Brownfield is realistic
By simply running codd extract --ai on existing code, a 6-layer design document is automatically generated. No need to write from scratch.
✅ The flow from codd extract --ai to Reverse Engineering is smooth
With a two-phase design (Phase 1: tree-sitter static analysis + Phase 2: AI), the AI phase fills in the gaps even if static analysis finds nothing.
Conclusion
I used to think that the "divergence between documentation and code" was an eternal struggle in software development, but it seems quite manageable in reality if you use this mechanism.
I still need to incorporate things like Neo4j to make it applicable to large-scale projects and organize it into a form that multiple people can develop with before it would be accepted within the company.👀
Discussion