個人サイトを作ろうという考えは、ずっと頭の中にあった。
テンプレートを使って適当に作っては公開するようなサイトではなく、自分の作品や経験、考えを余すところなく表現できる場所です。問題は、「作りたい」という気持ちから「実際に作り始める」までの間に、たいてい長い迷いの期間があることです。どんな形にするか、どの技術を選ぶか、この時間をかける価値があるかどうか、すべてが定まらないからです。
このシリーズでは、私がどのようにしてその迷いを乗り越え、Claude Codeと数々のAIツールチェーンを駆使して、ゼロからこのサイトを構築したかを記録していきます。
出発点：AIと対話して原型を形作る
当初、私にはいくつかの漠然としたアイデアしかありませんでした。「ポートフォリオが必要」「記事を書けるようにしたい」「多言語対応が必要」といったものです。しかし、これらはあまりにも大雑把すぎて、いきなり着手すれば途中で方向性が間違っていると気づくことになるでしょう。
そこで、Claude Codeの「brainstorming skill」を使って要件を絞り込みました。このツールの仕組みは興味深いものです。一度に大量の質問を投げかけるのではなく、毎回1つの質問を投げかけ、できるだけ選択式で尋ねてくるのです。
例えば、次のような質問をしてきます：
このウェブサイトの主な目的は何ですか？(A) 純粋なポートフォリオ (B) ブログが主 (C) 両方を兼ね備える
対応する言語はいくつ必要ですか？(A) 中国語のみ (B) 中国語と英語の2言語 (C) 3言語以上
管理画面にはどの程度の機能が必要ですか？(A) コードを直接編集 (B) シンプルなCMS (C) 完全な管理画面
このようにやり取りを重ね、十数問ほど質問した後には、当初漠然としていたアイデアが具体的な要件リストへと形作られます。このプロセスの利点は、実際に手を動かす前に、あらゆる側面について考え抜くことを強制してくれる点にあります。多くの場合、自分は考え抜いたつもりでも、具体的な質問をされて初めて、実は何も考えていなかったことに気づくものです。
要件から設計書へ
ブレインストーミングが終わった後、次のステップはすぐにコードを書くことではなく、設計書（spec）を作成することです。
この仕様書はプロジェクトの docs/superpowers/specs/ ディレクトリに保存され、以下を網羅しています：
アーキテクチャの選定：どのフレームワークやデータベースを使用するか、その理由
データモデル：どのようなモデルがあり、それらはどのように関連しているか
ページ構成：フロントエンドにはどのようなページがあり、バックエンドにはどのような機能があるのか
多言語対応：翻訳データの保存方法、切り替え方法、主要言語はどれか
仕様書は論文のように分厚く書く必要はありませんが、それぞれの決定には根拠が必要です。例えば、なぜ Pages Router ではなく Next.js App Router を選んだのか、なぜ Drizzle ではなく Prisma を使うのかといった点です。これらは、後の実装段階で何度も参照することになります。
仕様書が完成したら、私に一度レビューしてもらい、抜けや誤解がないか確認します。このステップは重要です。なぜなら、仕様が決まれば、その後の実装計画はそれに従って進められるからです。
設計から実施計画へ
仕様書が確定したら、次に plan skill を使って、実行可能な実施計画に分解します。
計画は docs/superpowers/plans/ ディレクトリに保存され、明確な完了条件を持つタスクのリストという形式をとります。各タスクは極めて具体的です：どのファイルを変更するか、どのようなテストを書くか、完了後に何を検証するか。
例えば、「多言語対応の実装」という項目だけでも、次のように細分化されます：
i18n設定ファイルの設定（zh-TW、en、jaをサポート）
translation group の Prisma モデルを作成する
ロケール切り替え用ミドルウェアの実装
フロントエンドページへの翻訳コンテンツの組み込み
管理画面に言語切り替えのUIを追加する
各ステップは独立して検証可能——1ステップ完了ごとに動作確認ができ、すべて完了してからどこかがうまく連携していないことに気づく、といった事態を回避できます。
このプロセスが解決した課題
振り返ってみると、「構想 → 仕様書 → 計画」というプロセス最大の価値は、一行のコードも書く前に、プロジェクト全体を一度通して確認できる点にあります。
以前、私がサイドプロジェクトを行う際の習慣は、思いついたことをすぐに書き始め、途中でアーキテクチャが間違っていると気づいては破棄し、最初からやり直すというものでした。それを何度か繰り返すうちにやる気を失い、諦めてしまうことがよくありました。今回違ったのは、仕様書と計画書があったおかげで、作業開始後はチェックリストに従って一歩ずつ進めることができ、大きな方向性を後から修正することがほとんどなかった点です。
もちろん、計画ですべての状況を完璧に予測することは不可能であり、実装の過程で調整が必要な箇所に遭遇することもあります。しかし、この基盤があるおかげで、調整の幅は小さく抑えられ、「半分まで進んだところで方向性が完全に間違っていたことに気づく」といった事態は起こりません。
次回は、デザインとビジュアルプロトタイプについてお話しします。cinematic-uiのようなツールを使って、大量の機能要件を実際に目に見えるインターフェースに変えていく方法についてです。