Vibe-CodingにADRを導入して「理解」と「自分で作った感」を取り戻す
この記事は個人ブログで公開した内容を再編集したものです。
ClaudeでRust製ウィンドウマネージャーを開発する中で、「コードを理解しないまま開発が進む」「自分で作った実感が薄い」という違和感を覚えました。
この記事では、ADR（Architecture Decision Records）を導入することで開発体験がどう変わったかを紹介します。
この記事で分かること
- Vibe-Codingで感じた3つの違和感
- ADRを導入した具体的なプロセス
- 導入後の変化と効果
開発したもの
Rustile - RustとClaudeで作ったX11向けタイル型ウィンドウマネージャー
Vibe-Codingとは
最近、ClaudeやGeminiといったAIに様々なアプリケーションを作ってもらっています。「こういうものが欲しい」と伝えるだけで、それなりに動くものを仕上げてくれるのは驚きです。
世の中ではこのような開発スタイルをVibe-Codingと呼んでいるようです。
学習目的もかねて、RustileというRust製のX11向けタイル型ウィンドウマネージャーを、Vibe-Codingで開発してみました。
開発で気になった3つのこと
開発を進める中で、いくつか気になることがありました。
1. 理解が追いつかないまま開発が進む
要件や設計をよく理解していない状態で、AIが出力したコードを雰囲気でレビューしてしまうことが何度もありました。もちろん、これは雰囲気でレビューした自分の問題なのですが、そういう対応が積み重なると「よくわからない部分」がどんどん大きくなっていきます。
その結果、追加の開発は既存のコードをベースとするので、徐々に難しくなっていきました（仕事でも経験したことあるなぁ）。
試したこと:
設計や技術的な詳細を説明するドキュメントをAIに書かせることを試してみました。ただ、特に開発初期はコードを頻繁に変更するので、ドキュメントがすぐに陳腐化してしまいます。開発の度にそれらを更新するのは、コストに見合わないので続きませんでした。
2. 書いてみて・試してみてわかることがある
これまでの開発なら、作りたい機能について実装方法をあれこれ検討したり、アイデアをちょっと試したりする過程があったと思います。でもVibe-Codingだと、その過程を飛ばして一気に成果物が出てきます。
実際に手を動かして試す中で初めてわかることって結構あると私は思います。それをコードにフィードバックする機会がないまま進めてしまうことに違和感を覚えました。
また、完成したコードを見てフィードバックするのと、自分で検討や試行錯誤をした後にフィードバックするのでは、質も量も全然違うなと思います。
3. 達成感・成長実感を得にくい
AIがまるっと作ってしまうので、自分であれこれ考えながら解決策を探る、そういう主体的なプロセスが抜け落ちていると感じました。プログラミングの楽しさは、こういう部分にもあると私は思います。
自分で作った実感が薄いと、達成感も成長実感も得にくいです。これは、自分がコードベースをどれだけ理解できているか、作るのに苦労したのかという話とも関係していると思います。
解決策: ADRの導入
こういった違和感を解消して開発体験をより良くするために、**Architecture Decision Records（ADR）**をVibe-Codingのプロセスに組み込んでみることにしました。
ADRとは
ADRは、ソフトウェア開発での重要な設計判断を記録するドキュメントです。「なぜその設計を選んだのか」という意思決定のプロセスと根拠を残すことで、後から見返したときに背景を理解できるようにします。
導入の流れとワークフロー
まず、全体像を説明します。
ADRを使った開発フロー:
0. 新機能についてふわっと言語化する
- ADR（Proposed）の草案作成 ← AIに書かせてレビュー
- 実装方針の検討とブラッシュアップ ← レビュー・試行錯誤
- 実装開始 ← AIに書かせてレビュー
- ADRをAcceptedに更新 ← 実装完了後
重要なのは、いきなり実装に進まず、Proposedステータスで実装方針を検討する段階を踏むことです。
ADRテンプレート
ADRテンプレートはこのような構成にしました。
# [タイトル]
## Status
- Proposed (YYYY-MM-DD)
- Accepted (YYYY-MM-DD)
## Context
背景情報、解決したい課題
## Decision
採用した設計判断の詳細説明
### Examples
具体例
## Consequences
メリット・デメリット
## References
- 関連するADR
- 関連するissue
実際のADR例
Window Rotation機能の実装で実際にADRをAIに書いてもらいました。ポイントを抜粋すると
## Context
BSPレイアウトで「ウィンドウを回転させる」とは何かを定義する必要があった。
3つのアプローチを検討。
## Decision
親ノードの分割方向を反転させるアプローチを採用。
フォーカスしているウィンドウの親ノードの分割方向を反転。
Alt+r → 親分割ノードを見つける → Horizontal ⇔ Vertical反転
## Consequences
Good 予測可能、シンプル、可逆的
Bad ルート回転時は全ウィンドウに影響、直感的でない
このように、AIに草案を書かせた後、自分でレビューして内容を詰めていきます。その過程で実装方針の理解が進みます。
導入後の変化
ADRを導入したことで、いくつか良い変化がありました。
| Before | After |
|---|---|
| いきなり実装開始 | 実装方針を検討してから実装 |
| 「なぜこうなっているか」が不明 | 背景を明文化して理解しながら開発 |
| AIが全部やって達成感が薄い | 試行錯誤のプロセスで達成感を得られる |
| 追加開発が難しくなる | 設計判断が記録され、後から理解しやすい |
まず、「なぜそのようなコードになっているのか」という背景を明文化することで、前よりも理解しながら開発を進められるようになったと感じています。
また、Proposedというステータスを用意したことで、いきなり実装に進まず、実装方針を検討する段階を踏めるようになりました。
結果として、試行錯誤のプロセスもある程度取り戻せたし、自分が作ったという感覚も前よりは得られるようになったと思います。
類似アプローチ
私と同じようなことを感じている人をXや他の記事で見かけます。実際、Vibe-Codingを段階的に進めるためのツールも登場してきています。
Amazon Kiro - Spec-Driven Development
AmazonがKiroというVS CodeベースのAI IDEをリリースしています。**Spec-Driven Development（仕様駆動開発）**というアプローチを採用していて、プロンプトから仕様（要件・設計・タスク）を生成し、その仕様を詰めた上でAIが実装するという流れで開発を進めるのが特徴です。
cc-sdd - ClaudeでSDD
ClaudeでKiroと同様の仕様駆動開発を実現することを目指したcc-sddというツールもあります。要件定義（Requirements）→設計（Design）→タスク分解（Tasks）→実装（Implementation）という4段階のワークフローで開発を進めます。
cc-sddは今後試してみたいと思っています。このADRベースの開発とどう違うのか、あるいは統合することでより良い開発体験にならないか、試してみたいです。
まとめ
Vibe-Codingは雰囲気でそれなりのソフトウェアを作ってくれます。でも私の場合は、以下のような違和感もありました。
- 理解が追いつかないまま開発が進む
- 書いてみて・試してみてわかることをフィードバックできない
- 自分で作った実感が薄く、達成感や成長実感を得にくい
ADRの導入は、私が感じた違和感を解消する方法の一つになりました。設計判断を明文化して段階的に開発を進めることで、理解しながら開発を進められるようになったし、試行錯誤のプロセスも取り戻せたと感じています。
Kiroやcc-sddといった仕様駆動開発のツールの登場や広がりを見ていると、Vibe-Codingを段階的に進めることの重要性が認識されてきているのかもしれません。
もしVibe-Codingで同じような違和感を覚えた方がいたら、参考事例の一つとして、ADRの導入や仕様駆動開発を試してみるのも良いかもしれません。
参考リンク
この記事が役立ったら、LIKEやコメントで教えてください！
他の技術記事や開発記録は私のブログでも公開しています。
Discussion