10
17

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@bakuchiku

AI駆動開発を“実運用化”：設計書/コード間の依存関係を管理するAI-DLC × CoDD開発手法

10
Last updated at Posted at 2026-04-21

Zennに移行検討中です...

要約

設計書とコードがすぐに乖離してしまうという、ソフトウェア開発でありがちな課題に対し、AI-DLC を主軸に開発フローを再設計し、CoDD のドキュメントとコードの整合性を維持する考え方を取り入れ、さらに Graphify で依存関係を人にも見やすく可視化する 形にまとめました。

単なるドキュメント生成ではなく、設計書・コード・グラフを継続的に同期しながら扱えるワークフローとして整理したのがポイントです。

はじめに

過去の投稿を見てもらえばわかる通り、自分はかなりのAWS大好き人間です。

最近Claude Codeをガッツリ使うようになって「せっかくAIと一緒に開発するなら、もっとちゃんとフロー化できないか」とずっと考えていました。

そこで気になってたのがAWS様が提唱するAI-DLC（AI-driven Development Lifecycle）という概念です。要件定義からコード生成・テストまでを一貫したフェーズ管理でやろうという考え方で、これ自体はいいんですが、自分的にずっと引っかかっていたのが 「ドキュメントとコードの乖離問題」 でした。

具体的にはこういう状況です：

  • コードを書いた直後は設計書と合ってる
  • 1ヶ月後にバグ修正でコードを直す
  • 設計書は誰も更新しない
  • 気づくと設計書が「嘘のドキュメント」になっている

AWSでサーバーレス構成を何度も作ってきましたが、Lambda・DynamoDB・API Gatewayの依存関係が複雑になってくると、「このLambdaってどのテーブル触ってたっけ？」「この設計書ってまだ正しい？」みたいなことが本当に起きる。そのたびにコードを読み直す…これ、全員経験あると思います。

何かいい方法ないかと調べていたら、CoDD（Coherence-Driven Development） という考え方に出会いました。

CoDD（Coherence-Driven Development）とは

CoDDについては こちらのZenn記事 を確認ください。そもそもめっちゃ勉強になるの読むべき👀
一言で言うと 「ドキュメントとコードの整合性を継続的に検証・維持する開発手法」 です。

キーコンセプトはこんな感じ：

  • Wave 階層（L1〜L6）: 要件定義→アーキテクチャ→詳細設計→コードの順に段階的に具体化する設計書の階層構造
  • CoDD frontmatter: 各Markdownドキュメントに埋め込むメタデータ。node_id・depends_on・source_files など、ドキュメント間・ドキュメントとコード間の依存関係を宣言する
  • codd scan / validate / measure: frontmatterを解析して依存グラフを構築し、整合性チェックやカバレッジを計測するCLI
---
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
---

こんな感じでドキュメントの先頭にYAMLブロックを書くだけで、CoDD CLIがドキュメント間の依存グラフを構築してくれます。codd validate を実行すると「このドキュメントが参照しているソースファイルが実在するか」「depends_on で指定した親ドキュメントが存在するか」などをチェックしてくれる。

コードを変更したら codd extract で最新状態を抽出、codd validate で整合性確認、という流れをCIに組み込めば、ドキュメントが「嘘」になった瞬間に気づけるわけです。

AI-DLC × CoDD × Graphify の3層アーキテクチャ

AI-DLCやCoDD単体でも強力ですが、今回は自分なりに開発フローを組み直し、AI-DLCの手順を主軸に据えつつ、CoDDの整合性維持という考え方を取り入れ、さらにGraphifyで人間にも追いやすい形に可視化した 3層アーキテクチャとして整理しました。

Layer 1: AI-DLC Workflow Engine

  • CLAUDE.md ← オーケストレーター（フェーズ管理・承認ゲート・監査証跡）
  • .aidlc-rule-details/ ← 各フェーズの詳細ルール

Layer 2: CoDD Document Engine

  • codd CLI ← 設計書生成・frontmatter管理・変更伝播
  • codd scan/validate/measure/extract/propagate

Layer 3: Graphify Knowledge Graph

  • graphify CLI ← 単一の graphify-out/graph.json
    • AST（確定的エッジ）+ LLM意味解析（推定エッジ）
    • Leidenコミュニティ検出

ポイントは「Graphify が唯一のユーザー向けグラフツール」 という設計です。CoDDの内部インデックス（.codd/scan/）は codd impact・codd propagate のための内部処理で、ユーザーに見せる正規グラフは常に graphify-out/graph.json 一本。

Graphifyが面白い

Graphify が何をやっているかというと、こういうことです：

  • ASTエッジ（EXTRACTED）: ソースコードの import 文を静的解析して確定的な依存エッジを生成
  • 意味エッジ（INFERRED）: LLMが「このクラスはこのドキュメントと意味的に関連する」と推定したエッジ（信頼度 0.7〜0.9）
  • 曖昧エッジ（AMBIGUOUS）: 低確信度の関係（信頼度 0.4〜0.6）
  • Leidenコミュニティ検出: グラフクラスタリングで「自然なモジュール境界」を検出 → Unit of Work の候補になる
  • God Nodes: 接続数が多いノード = アーキテクチャハブ。変更時の影響範囲が最大のクラスや関数

しかも CoDD frontmatter の depends_on エントリが Graphify の EXTRACTED エッジになる というブリッジ設計になっています。設計書に書いた依存関係がそのままグラフに反映されるので、特別な連携コードは不要です。

Three-Way Coherence Closure

このシステムの目玉がコード生成後の 三方向整合性クロージャー です：

# Step 1: 最新コードをCoDD に取り込む（CoDD = 設計の正本）
codd extract

# Step 2: CoDD内部整合性チェック（主要ゲート）
codd validate

# Step 3: 派生グラフを同期
/graphify --update

# Step 4: 整合性確認クエリ
/graphify query "カバレッジ・欠落リンク・主要リスクをまとめて"

コードを書くたびにこの4ステップを実行して「設計書・コード・グラフの3つが整合しているか」を確認する。これを人間の承認ゲート（HITL: Human in the Loop）と組み合わせることで、AIが暴走して設計書と全然違うコードを生成したことに気づかない、という事故を防げます。

自作ダンス管理アプリをリバースしてみた

百聞は一見にしかず、ということで自分が作ったダンス・舞台の構成管理アプリ（ダンスショーケースプラットフォーム）でリバースエンジニアリングを試してみました。

アプリの構成

これはまさに「AWS大好き人間が作ったサーバーレス構成」です：

  • フロントエンド: React + TypeScript + Vite → CloudFront配信
  • バックエンド: Python FastAPI × Lambda
  • 認証: Amazon Cognito（PKCEフロー）
  • データ: DynamoDB（UsersTable / ShowcasesTable / TracksTable / SharesTable）
  • ストレージ: S3
  • インフラ: AWS CDK（TypeScript）

Graphify の結果が面白かった

グラフ統計

  • 377 ノード · 572 エッジ · 72 コミュニティ
  • EXTRACTED: 69% · INFERRED: 31% · AMBIGUOUS: 0%

image.png

自動命名されたコミュニティ（Unit候補）

Graphify の Leiden 検出が自動でコミュニティに名前をつけてくれます：

# コミュニティ名 ノード数 説明
0 Showcase Data Models 38 データモデル全般
1 Showcase CRUD Repository 27 リポジトリ層 + テスト
2 Auth Dependencies 20 JWT検証・IDOR防止
3 Frontend API Client 19 フロントエンドAPI呼び出し層
4 Cognito PKCE Auth 18 Cognito認証フロー
5 User Service 15 ユーザーサービス全体
6 RE Design Documents 17 生成された設計書群
7 Animation Controller 3 タッチ操作・ズーム
8 Animation Engine 4 キーフレーム補間

コードを読まずにこのリストを見るだけで「このアプリは何で出来ているか」が一発でわかります。しかも Community 6「RE Design Documents」 として、AI-DLCが生成した設計書自体もグラフのノードになっていて、コードと設計書が同一グラフ上に乗っている。

God Nodes（アーキテクチャハブ）

  1. UserRepository — 21 エッジ
  2. Showcase — 18 エッジ
  3. SharedTrackInfo — 15 エッジ
  4. apiFetch() — 15 エッジ
  5. Point — 14 エッジ
  6. Stage — 14 エッジ

UserRepository が 21 エッジで1位というのは腑に落ちます。showcase-service も media-service も認証のためにユーザー情報を参照しているので、3サービスをまたぐブリッジになっているわけです。

Graphify はこういう「あなた気づいてないかもしれないけどこのノード超重要です」という指摘をしてくれます：

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.

betweenness centrality（媒介中心性）が高いノードは変更時の影響範囲が最大。これを事前に知っておけば「UserRepositoryに手を入れるときは3サービス全部テストしないといけない」という判断がリポジトリを読まずにできます。

生成された設計書

リバースエンジニアリングで生成されたドキュメント：

aidlc-docs/inception/reverse-engineering/
├── business-overview.md        ← ビジネスコンテキスト図 + 12のビジネストランザクション
├── architecture.md             ← システムアーキテクチャ図 + コンポーネント説明
├── code-structure.md           ← ディレクトリ構造・モジュール関係
├── api-documentation.md        ← 全エンドポイント一覧（OpenAPI相当）
├── component-inventory.md      ← コンポーネントカタログ
├── technology-stack.md         ← 使用技術・バージョン
├── dependencies.md             ← 外部依存関係
├── interaction-diagrams.md     ← シーケンス図（Presigned URLフローなど）
├── code-quality-assessment.md  ← セキュリティルール・コード品質評価
└── technology-stack.md

codd validate 後のグラフ

  • codd scan → 105 ノード, 165 エッジ（18 frontmatter ドキュメント登録済み）
  • graphify --update → 377 ノード, 572 エッジ, 72 コミュニティ

RE実行後にグラフを更新すると、設計書群が自動的に "RE Design Documents" コミュニティとしてグラフに追加されています。コードと設計書が同じグラフ上で依存関係を持つ状態が実現できました。

よかった点

✅ コードとドキュメントが同一グラフ上に乗る

codd validateでドキュメントの整合性チェック、Graphifyでコードとドキュメントを横断した可視化。「設計書が嘘をついている」状況をCIで検出できる仕組みができます。

✅ Graphifyのコミュニティ検出がUnit分解の参考になる

新機能追加時に「どのコミュニティに影響するか」がグラフで一目瞭然。God Nodesを見れば「触ったらヤバいファイル」がすぐわかる。

✅ Brownfieldへの適用が現実的

既存コードに codd extract --ai を実行するだけで6層設計書が自動生成される。ゼロから書く必要がない。

✅ codd extract --ai → Reverse Engineeringの流れがスムーズ

Phase 1（tree-sitter静的解析）+ Phase 2（AI）の2フェーズ設計で、静的解析が0件でもAIフェーズが補完してくれる。

おわりに

「ドキュメントとコードの乖離」はソフトウェア開発の永遠の悩みだと思っていましたが、この仕組みを使えばかなり現実的に管理できそうかなと。
大規模案件で適応できる形にしないと社内で認めてもらえないのでNeo4j活用したり、複数人で開発できる形に整えなければって感じ👀

10
17
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
10
17

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?