Claude Code × Tsumiki で挑んだ SDD、その失敗談と学び

今回、社内で使用する請求チェックツールを AI駆動開発支援フレームワークの Tsumiki と Claude Code を用いて、仕様駆動開発 (SDD: Specification-Driven Development) のアプローチで進めました。
しかし実装フェーズで思いの外 手戻りが多発 し、工数が膨らんでしまいました。

本記事ではその経緯と、そこから得た学びを共有します。

スムーズに進んだ前半フェーズ

• 要件定義 → 設計 → フロー図作成 → タスク分解 までは非常にスムーズに進行
• 成果物のクオリティも高く、レビュー時点での指摘も少なかった

ここまでは「SDDならではの進めやすさ」を実感できました。

実装フェーズでの問題

しかし、いざ実装フェーズに入ると次のような問題が発生しました。

• 大まかな要件には沿っていたが、詳細な仕様が反映されていなかった
• コードレビューで大幅な修正が必要となり、レビュー工数が膨大に

結果として、せっかくの SDD の恩恵を受けきれず、かえって工数増加を招きました。

失敗原因の分析

振り返ってみると、主な原因は ドキュメントの分離方法と命名規則 にありました。

実装フェーズで仕様が反映されなかった原因

今回、計算ロジックが複雑だったため、生成AIの提案に従いロジックや既存DB参照方法を別ファイルに分離しました。
例:

• docs/design/billing-calculation-spec.md
• docs/spec/account-table-spec.md

しかし、Tsumiki の標準フローで参照されるのは以下の 2 系統のみです：

• docs/spec/{要件名}-requirements.md
• docs/design/{要件名}/architecture.md

また、独自に命名したファイル（例: docs/spec/calculation-spec.md、docs/design/**-table-spec.md）は Tsumiki の期待する命名規則に合致せず、参照・集約されませんでした。

→ つまり、分離や命名のルールを守らないと、仕様として存在していても「読まれない仕様」と同じ扱いになる

学び

今回の失敗から得られた学びは以下の通りです：

• 生成AIフレームワークの想定フローを正しく把握することが最重要
• 独自の工夫でファイルを分離・命名する場合は、参照対象に含まれるか確認 する必要がある
• 特に Tsumiki のように「ファイルパス/命名」に強く依存する仕組みでは、規約遵守が実装品質に直結 する