バイブコーディングの感動体験記はよく見かける。具体的な手法の紹介や、企業の成功事例も増えてきた。でも、感動体験からその先に至るまでに何があったのか、という話はあまり見ない。今回はその「間」の話を書く。
何を作っているの？
Windows向けのコマンドライン型ランチャーアプリで「Snotra」
まず仕様書（SPEC.md）を書いてから実装に入るやり方を採用した。
Claude Code と Spec駆動開発の威力
最初にざっくりやりたいことをまとめた SPEC.md を Claude Code に深掘りしてもらうと、やりたいことが具体的になった SPEC.md が出来上がる。
この SPEC.md をもとに実装して、というとあっという間に動くものができた。機能は最低限、増やしていけばいい。
最初の壁、そして壁越え
最初は確かにざくざく作れて楽しかったのだが、機能が増えてきてから、こちらを直すとあちらが壊れるといったことが増え始めた。
ここでバイブコーディングやSpec駆動開発がダメだ、というつもりはない。人間が実装してもこの問題は起きる。むしろ、月単位や年単位あとの問題に早く遭遇できたのはいいことだ。
軽量のSpec駆動開発はプロトタイプを作る場面に有効そうだ。実際に触ってみて、欲しい機能が揃っているのか、もっと欲しい機能はあるか。逆に要らないものは何かを考えるきっかけになる。実際に触って評価できるのはとても強い。
仕様だけ抽出して一から作り直す方法もあったが、今回はプロトタイプを改良する方法を選んだ。綺麗な設計から綺麗な実装が生まれると考えると、手間も難易度も多いのだが学びも多いだろう、と期待して。
壁の正体
一つのカバンに会社の書類も学校の教科書もお出かけの着替えも突っ込んでいた。着替えを入れ替えたら書類がぐちゃぐちゃになる。書類を整理したら教科書が出てこない。
シンプルに考えたらカバンをわければいい。
テスト自動化
実装中に壊れたことにそもそも気が付けないのがまずい。
コマンドライン型ランチャーなので検索するときはファイル名やフォルダ名を入力する。
頭を抱えたのが
- C と入力すると検索結果に C:\Windows が表示される
- C: と入力すると検索結果に何も出てこない
- C:\ と入力すると検索結果に C:\Windows が表示される
という不具合。
原因は検索クエリの正規化が足りてなかったこと。
想定されるパターンをClaudeと相談しながら修正した。普段、使わないようなパターンも出てくる。
CLAUDE.md にもテストファーストで作る、と明記してから、Claudeがテストを書き、テストにこけたら原因を調査しコードを直す。テストで想定していた条件そのものが誤りの場合、テストコードを修正する。
テストができない部分に関しては人力のテストを依頼してきた。PRにテストのチェックリストが付与されたり、デバッグ中に「10回試してください。100回あると平均とりやすいです」と提案してきたり。*1
仕様の把握
自分が頼んでおいてあれだけど、細かい仕様を把握しきれていなかった。
SPEC.md に片っ端から書き出し、漏れや矛盾がないかClaudeやCodexを使ってあーでもないこーでもないいいながら整理した。
Mermaid記法の状態遷移図は人間にも生成AIにも読みやすい。図を見ながら「この処理は過剰では？」「条件分岐が多すぎないか？」と判断がしやすくなったのはかなり大きい。
調査 -> 計画 -> 実装 -> 振り返り -> ネクストアクション
Claudeと一緒にスクラムをすることにした。
How I Use Claude Code | Boris Tane をベースにスクラムの概念を融合させた形。
調査、計画、実装は詳細はBorisさんの記事を参照してほしい。今なら翻訳する手段がたくさんあるから大丈夫。
Phase 1: 調査（Research）
まずはコードを調査させ、その結果をファイルに出力させるフェイズ。
不具合修正したい時は
アプリ起動から初期表示までのフローを詳細に理解してください。それが終わったら学習内容と発見事項の詳細なレポートを research.md に出力してください。
といった感じで調べている。
ここは人間が読んで理解する意味合いが強い。
Phase 2: 計画(plan)
設定ウィンドウを開いたら、設定ウィンドウが最前面。検索ウィンドウを背面に表示したいです。実装する方法の概説をした詳細な plan.md を作成してください。
出力された内容を人間が見て内容が妥当か確認、時には指摘やより良い方法のアドバイスをファイルに書き込む。
Planモードとの違いはファイルとして扱えること。コンテクスト圧縮の影響を受けにくいし、他の生成AIにレビューを頼んだりもできるのが強い。
レビューしたら
ドキュメントにメモを追加しました。全てのメモに対処して、ドキュメントを更新してください。実装はしないでください
これで plan.md が最新になるので、改めてレビューする。
Borisさんの記事だとここのサイクルは最大6回まで回すという。
最後にTODOリストの作成を依頼して計画は終わり。
Phase 3: 実装（Implement）
plan.md の TODO に基づいて実装する。
実装からコードレビュー、テストまで含まれている。
コードレビュー
レビューで問題があれば review.md に貼り付けている。
Codex CLI などでコードレビューした指摘事項や実際に動かしてみてイメージと違う点を書き込む。
ここで対処が必要なら「実装」まで戻る。
振り返り
一連の作業のファイルから今回は何がよくて、何がいまいちだったのかを考えるフェイズ。
一連の作業と research.md plan.md review.md を全て読み込み、分析し、得られた洞察を retrospective.md に出力してください
ここで気がつく伸び代は結構ある。
例1
retrospective.md 見ながらの会話。
「レビューで指摘事項たくさんあったけど、どうやったら早く気がつける？」 『メソッド間のつながりがわからずに変更して壊してしまった』 「ドキュメント拡充すると良い？」 『〜のドキュメント更新するといいと思います』 「採用で」
例2
『コマンドの実行エラーがたくさん』 「Windows環境とmacOS環境で開発しているから？」 『それです。環境ごとに手順を分けます』 「ちょっと待って」
ネクストアクション
retrospective.md をもとに次に何をすればいいのか考えるフェイズ。
retrospective.md で得られた洞察をもとによりよくするにどうすればいいのか考え next_action.md に出力してください
調査不足で不具合が増えるなら、調査の時間を増やす、資料を増やす、など考える。
最終的にはCLAUDE.mdやSPEC.md、ナレッジに反映される。
出てきた洞察を取り入れる
テスト自動化セクションで書いた実機テストを繰り返して気がついた。
確かに品質担保の観点では重要なんだけど、都度実機での操作をするのは手間だ。ここで不具合がわかると、実装からやり直しになってしまう。
仕事では手間がかかると後回しになりがちなE2Eテストを導入することにした。これがかなり効果的で実機で確認する時の不具合がかなり減った。
ログを見ていると、Claudeが計画時や実装時にパターンを考え拡充してくれている。
コード固有の知識をナレッジファイルにする
Claude CodeはサブディレクトリのCLAUDE.mdを自動で読み込んでくれる。
例えばこのような構成にして、それぞれのCLAUDE.mdに固有のルールや知識を書いておく。
- snotra-core/CLAUDE.md
- src-tauri/CLAUDE.md
- ui/CLAUDE.md
例によってClaudeと相談しながら書いてもOK。
コードコメントに意図を残す
CLAUDE.md で目標とルール、SPEC.md で仕様、コードコメントでコードの意図を伝える。
コードにコメント不要という話もあるけど、やむを得ない理由で特殊実装するケースもある。
- 採用しているライブラリの最新版に不具合があるので古いものを使っている
- 原則、同じコードは書かないようにしているがパフォーマンスのためにここでは同じコードを書いている
こういった背景はコードから読み解けない。ドキュメントに残す手もあるがコードとの距離が遠くて参照が難しいだろう。少なくとも人間には難しかったし、Claudeにタスクに集中してもらうためにもすぐ読める時にあるのが望ましい。
まだ導入段階だけど、手応えはある。
ひらめいたこと
Claude Codeは既存のコードを参考にして新しいコードを書く。これを逆手に取れないかと考えた。
SPEC.mdの構造がそのままコードの構造になるなら、仕様の章立てが整理されていれば、自然と役割の明確なコードが生まれるはずだ。
加えて、最初のひとつをきちんと作っておく。
- 小さくてもいいからひとつ使える機能を作る
- ちゃんと動くか、自動テストは十分か検証する
- コードをリファクタリングし、テストの自動化を強化する
この「最初のお手本」が整っていれば、次の機能を作るときにClaude Codeがそれを参考にする。お手本の品質がプロジェクト全体の品質を底上げしてくれる。
完全に今思いついたものだけど、やれそうだという確信がある。次作る時に試すしかない。
雑感
やってみて思ったのはプロダクトオーナー兼スクラムマスターだ。
- プロダクトオーナー: 欲しいものは何か、やって欲しいことは何かを言語化し伝えること
- スクラムマスター: 自分たちはこれから何を作るのか計画を立て、Claude Codeが最大効率で開発できるよう障害を取り除くこと
振り返ってみれば全部、Claudeが迷わず走れる道を作る作業だった。
自分にとって良いか悪いかの判断が必要なものなら、どこかで人間が「こうしたい」「こうやると良くなる」と伝えるフェイズは必要不可欠だと思う。いずれ、生成AIがパーソナリティを理解し、最適に近づけてくれるかもしれない。
少なくとも自分の今欲しいものは自分だけが知っている。それをいかに伝えるのかが重要なのだと思う。
*1:100回あるといい、といってきたのはCodex
