Claude Code グリーンフィールドワークフロー：空のリポジトリから最初のスライスへ

グリーンフィールド開始で避けたいこと

空のリポジトリから始めるのは自由に見えますが、多くの場合は混乱に変わります：生成されたファイルが散らかり、ビルドは半分しか動かず、次の変更をどこに置くべきか分からなくなる。Claude Codeのグリーンフィールドワークフローの目的は、最初の一週間のカオスを避けることです。

繰り返し起きる失敗はいくつかあります：

• セットアップがスクリプトではなく誰かの記憶にあるため「自分のマシンでは動く」コード。\n- フォルダ構成がアプリをどう成長させるかではなく、作った順を反映している。\n- 新しいプロンプトが前の選択を上書きしてしまい、何も安定しないループ。

初期の決定は後で取り消すのが大変です。すべてがその上に積み重なるので、混乱した構造が強化され続けます。手作業のビルドは十通りのセットアップに分岐します。シンプルな dev コマンドを早期に固定しなければ、変更がアプリを壊したのか環境を壊したのか判別できません。

この投稿で「動くアプリ」と言うときは、特定の意味があります：プロジェクトを起動する単一コマンドがあり、予測可能な出力を表示し、何か足りないときには明確に失敗すること。ローカルインストールを削除してリポジトリをクローンし、そのコマンドを実行すれば同じ結果が得られるべきです。

「バーティカルスライス」とは、アプリが現実に動くことを証明する最小のエンドツーエンド機能です。UI モックではなく、単体のデータテーブルでもありません。画面のフォーム、データを保存する API エンドポイント、データベースの書き込みと読み取り、画面に戻る結果といったシステム全体を貫く薄い一本線です。

1つのコマンドでアプリを実行し、1つのバーティカルスライスを出荷できれば、推測なしに反復できる基盤ができます。

何も生成する前に最初のスライスを決める

明確な最初のスライスはリポジトリを整然と保ち、プロンプトの焦点を絞ります。ここで決めるべきは、最終的にどんな製品にしたいかではなく、最初にエンドツーエンドでデモしたいことです。

UI、データ、そして1つの実際のアクションに触れる最小のユーザーストーリーを選んでください。例：「ユーザーとして、タスクを追加し、リフレッシュ後にリストに表示される」。小さいですが、ルーティング、バリデーション、保存、基本スクリーンを強制します。

週1は1つのターゲットプラットフォームに絞りましょう。Webで始めるならWebだけにする。モバイル画面を「念のため」に追加しないでください。後でKoder.aiのようなプラットフォームを使う予定があっても、最初のスライスは1つのレーン（React Web、Go API、またはFlutter）に留めた方が良い結果が出ます。

「週1で完了」の意味を具体的に定義してください：

• 新しいクローンから単一コマンドでローカル実行できる\n- クリックして辿れる1つの動作する機能がある\n- エラーはスタックトレースではなく人間向けのメッセージを表示する\n- データはどこかに単純に永続化される（ローカルDBでも可）

次に、スコープを守るための3つの非目標を紙に書いておきます。例：認証なし、テーマシステムなし、バックグラウンドジョブなし。

これらの決定を書き留めれば、生成プロンプトは厳密にできます：スライスをサポートするものだけを作り、他はTODOのままにする。

手戻りを防ぐためのいくつかの決定

Claudeに何か生成させる前に、いくつかのデフォルトを固定しておきましょう。小さく見えても、後で「全部リネーム」する手間を防ぎます。

まずアプリの形を決めます。ブラウザUIとバックエンドの両方が必要なら、フロントエンド + API の2つに分け、契約（API型や簡単なスキーマ）の共有場所を用意します。サーバー側で完結する単一のアプリなら、ローカル開発をシンプルにするために1つのコードベースにまとめます。

次に設定ルールを決めます。ローカルは.envファイルを使い、gitには入れず、代わりに安全なプレースホルダと短いコメントを付けたテンプレート（例：.env.example）をコミットします。これでオンボーディングが楽になり、シークレット漏洩が減ります。

デフォルトの開発ポートを決め、それを安定させます。ポートはスクリプトやドキュメント、エラーメッセージに入り込み、後で変更するのは面倒です。フォルダ名、サービス名、パッケージ名も一貫した命名規則にします。完璧さよりも一貫性が重要です。

シンプルな出発点の決定例：

• アプリ形状：単一アプリ or frontend + API\n- 設定：ローカルは.env、.env.exampleをコミット\n- ポート：web用1つ、API用1つ、DB用1つ（必要なら）\n- 名前付け：フォルダやサービス名は一つのキャメル（あるいはケバブ）スタイルに統一\n- シークレット：コミットしない、露出したらローテーションする

例：webを3000、apiを8080に決める。envテンプレートに API_URL=http://localhost:8080 と DATABASE_URL=... を入れておけば、後でClaudeがスクリプトやドキュメントを生成しても全体が整合します。

Claude Codeに構造を守らせるためのプロンプトの作り方

まず、実行可能なスキャフォールド（骨組み）を要求します。「アプリ全体を作って」ではなく、まず動く土台を作るのが近道です。機能を先に要求するとファイルの置き場がなくなり、散らかりやすくなります。

構造を明確に指定してください。どのフォルダに何が入るか、何を入れないか短くコメントをつけたフォルダレイアウトを要求すると、ファイル配置の判断が前倒しになります。

厳格にするためのルール例：

• 最小の実行可能なスケルトンをまず生成（helloページ、ヘルスエンドポイント、または1画面）\n- フォルダ構造を提案し、各フォルダを1文で説明\n- 新しいマシンで動くスクリプトを追加（install, dev, test, build）と前提条件の明記\n- 変更はPRサイズにまとめ、作成・編集するファイル一覧を明記\n- スキャフォールディング後に停止して「ran it」の確認を待つ\n 再利用できるプロンプト例：

You are working in an empty repo. Create a minimal runnable skeleton.

Constraints:
- Keep it small: no real features yet.
- Propose a clear folder structure and add brief comments in each folder’s README.
- Add scripts for: setup, dev, test, build. They must work on a fresh machine.
- Tell me exactly how to run it, and what output I should see.
- After generating, stop and wait for my “ran it” confirmation.

Output:
1) File tree
2) Key files (only)
3) Run instructions

ループを短く保ちます。五つの変更を一度に頼まないでください。小さな変更を1つ生成→実行→実行結果（エラーや成功）を貼る→最小修正を頼む、というリズムがプロジェクトを予測可能にし、構造のブレを防ぎます。

ステップバイステップ：空のリポジトリから実行可能なスケルトンへ

まず一つの約束を守ってください：誰でもリポジトリをクローンして1つのコマンドで何か動くものが見られること。これができれば、AIに本格的な機能追加を頼む前の安定した土台になります。

リポジトリを作り、まだ全てが新しいうちに小さなREADMEを書きます。実用的に：前提条件、唯一のdevコマンド、テストの実行方法（テストが空でも可）を書きます。

次に、選んだアプリ形に合わせたトップレベルレイアウトを決めます。

複数のデプロイ可能なパーツ（例：frontend + API）を作るなら、workspace構成が便利です：

/
  apps/
  packages/
  scripts/
  docs/
  README.md

単一アプリなら、必要になるまで余計な階層は避けてシンプルに保ちます。

次にコードの一貫性を保つための最低限のガードレールを追加します。フォーマッタとリンタを1つずつ決め、デフォルトを受け入れて1つの設定ファイルだけ追加します。目標は差分をきれいにすることで、初日から完璧なルールを求める必要はありません。

開発体験を予測可能にするため、リポジトリルートから常に動く1つのコマンドを用意します。単純な形の例：

{
  "scripts": {
    "dev": "echo \"start dev server here\"",
    "build": "echo \"build here\"",
    "test": "echo \"tests here\"",
    "lint": "echo \"lint here\""
  }
}

それを最初に実行して、クリーンに終了するか（またはプレースホルダサーバーが起動するか）を確認してから、スキャフォールディングだけを含む最初のコミットを作ります。チームメンバー（あるいは未来の自分）がゼロから再現できれば、最初のスライスの作業に進めます。

アプリが成長しても保てるフォルダ構成

良いグリーンフィールド構成は2つのことを満たします：コードを素早く見つけられること、そしてClaudeが変更のたびに新しいパターンを発明する余地を減らすこと。目標は完璧ではなく安定性です。

単一アプリ（または apps/<name>/ の中）でのシンプルな内部レイアウトは長持ちします：

• src/ アプリコード（機能、共有パーツ、エントリポイント）\n- config/ シークレットでない設定\n- tests/ ユーザービヘイビアのように読める上位のテスト\n- scripts/ ヘルパースクリプト（devセットアップ、DBリセット、リリース作業）\n- docs/ 維持する短いメモやチェックリスト

src/ の中では、変更パターンに基づいて機能コードと共有コードを分けます。機能コードは頻繁に変わるので近くに置き、共有コードは退屈で再利用可能にします。

実用的なルール：UIスクリーン、ハンドラ、機能固有のロジックは src/features/<featureName>/... に置く。ロギング、APIクライアント、デザインシステムのコンポーネント、汎用ユーティリティは src/shared/... に置く。ヘルパーが1つの機能のためだけに意味を持つなら、見た目が再利用可能に見えてもその機能に置いておき、2つ目の本当の利用が出てから移動する。

フォルダ名は技術ではなく目的を表すべきです。features と shared はスタックが変わっても意味を保ちます。misc や new のような名前は避けてください。

docs/ は小さく保ちます。良いスターターは docs/checklists.md だけで十分です：実行方法、テスト方法、新しい機能フォルダの追加方法、そして「完了」の定義。

プロジェクトを予測可能にするビルドスクリプト

誰でも同じコマンドを実行して同じ結果が得られると、リポジトリは「本物」に感じられます。スクリプトはガードレールです：推測を減らし、変更を小さくし、何かが壊れたときに分かりやすくします。

最初は小さなコマンドセットにして退屈に保ちます。新しい人が入っても（あるいは2週間後のあなたが戻ってきても）特別なフラグや隠し手順はいらないようにします。

任意のスタックに適応できるシンプルなベースラインの例：

{
  "scripts": {
    "dev": "node ./scripts/dev.js",
    "build": "node ./scripts/build.js",
    "test": "node ./scripts/test.js",
    "test:quick": "node ./scripts/test.js --quick",
    "test:full": "node ./scripts/test.js --full",
    "format": "node ./scripts/format.js",
    "lint": "node ./scripts/lint.js",
    "smoke": "node ./scripts/smoke.js"
  }
}

dev スクリプトをハッピーパスにします。アプリを起動し、どこで動いているかを表示し、ログを読みやすく保つ。サーバーが起動できない場合は、環境変数の不足、ポートの競合、データベース未接続など一つの明確なメッセージで速やかに失敗させます。

build スクリプトは常にクリーンな出力ディレクトリを作るべきです。古い出力をまず削除してから新しいアーティファクトを生成します。昨日のファイルが残っていると奇妙なバグの原因になります。

テストは速いチェックと遅いチェックに分けます。速いテストは変更ごとに走らせる（ユニットテスト、型チェック）。フルテストは統合テストを含み、マージ前に走らせます。

スタイルは1つのコマンドで統一します。単純なルール：フォーマットは自動で直し、リンタは問題を指摘する。

最後に、無駄なデバッグを避けるためのスモークチェックを追加します：

• 必要な env 変数が設定されている（空でないこと）\n- 選んだポートが空いている\n- アプリが起動して簡単なリクエストに応答する\n- データベース接続（使う場合）が動作する\n- build 後に出力が存在する

最初のバーティカルスライスを作る

最初のバーティカルスライスはUIが見た目だけでなく、エンドツーエンドで動くことを証明するべきです。つまり画面、ロジック、何らかの保存が伴う小さな機能を選びます。保存が一時的でも構いません。

退屈で実用的なものを選びます。「ノートを追加」や「タスクを作る」のようなものが良い。1回の作業で終えられる小ささでありながら、状態が変わることが確認できる十分さが必要です。

良いスライスは4つの要素を持ちます：ルートまたは画面1つ、フォーム1つ、保存アクション1つ、表示1つ。例：タイトル入力と保存ボタンがある「New Task」ページ、保存関数を呼び、保存されたタスクがリストに表示される。

高速に作るためにプレースホルダのストアを使ってください。インメモリアレイ、ローカルJSONファイル、シンプルなスタブインターフェースで十分です。重要なのは境界を作ることです。今日 taskRepository.save(task) を呼ぶ設計にしておけば、後で本物のDBに差し替えるのは小さな変更で済みます。

UIは素朴で良いです。デザインシステムの議論や空状態、アニメーションはスキップします。

2分でできる受け入れチェック：

• ページがエラーなく開く\n- 値を入力して Save を押せる\n- 新しいアイテムが即座に表示される\n- リロードで期待通り（本物の永続化なら保持、偽ストアならリセット）\n- 不正な入力は弾かれる（空のタイトルはメッセージを出して保存しない）

反復できるくらい安定させる

実行可能なスケルトンと1つのバーティカルスライスができたら、目標は：壊れたときに分かりやすくし、修正を素早くすることです。多くのグリーンフィールド開始がここで破綻します。機能が難しいからではなく、小さな変更で予期せぬことが起きるからです。

スライスを追加するたびに満たす小さな安定基準を設定します：

• アプリが起動し、主要ルート/スクリーンがレンダリングされることを確認するスモークテスト1つ\n- スライスのエンドツーエンドを確認するスモークテスト1つ（テスト用DBでも可）\n- 正しいユーザー向けの短いエラーメッセージ（スタックトレースではない）\n- 開発ログは何が起きたかを説明し、シークレットを出さない\n- 依存を最小限にし、バージョンを固定し、アップグレードは意図的に行う

具体例：最初のスライスでユーザーが「Project」を作成してリストで見る機能があるとします。サーバーを起動し、createエンドポイントを呼び、リストを取得して新しい項目があることを確認するテストを追加します。失敗したら「Create Project endpoint returned 500」のような一つの分かりやすいメッセージで大きく失敗するべきで、膨大な出力で埋もれてはいけません。

エラーハンドリングは少数の一貫したレスポンスに絞ります。バリデーションエラーは短いメッセージ（「Name is required」）とフィールド名を返し、予期せぬエラーは「問題が発生しました。もう一度試してください。」と返す。詳細はログに保存します。

ログは「どのリクエスト、どのユーザー（または匿名）、何が失敗したか、どこで」という問いに答えることが有用です。開発ではリクエストIDや処理時間を含めても良いですが、トークンやパスワード、APIキー、ペイロード全体をデフォルトで出力しないでください。

小さなヘルスチェックを追加します。Webなら /health エンドポイントが ok を返すだけで十分です。モバイルならバックエンドに到達できなければ「Offline」に切り替わる簡単な接続状態で良いです。デバッグの前に間違った対象を追いかけるのを防げます。

AIを使ったグリーンフィールドでのよくある罠

グリーンフィールド開始を無駄にする最速の方法は、モデルに「アプリ全部を作って」と頼み、後でようやく実行することです。大きな生成は小さなミスを隠します：依存関係の欠落、間違ったインポートパス、ツールを前提としたスクリプトなど。出力は数分で実行できるものとして扱ってください。

もう一つの罠は、機能がないうちに完璧なアーキテクチャを設計してしまうことです。フォルダ名の議論は生産的に見えますが、本当のスライスがないとどこが不便か分かりません。1つの動くパスを支えるシンプルな構造の方が、まだテストしていない巧妙な構造より価値があります。

コマンドの分岐もよくあります。AIがサーバー起動の別の方法を追加し、さらにテスト用に別の方法を追加し、すぐに誰も「これが実行方法だ」と言えなくなります。クローンした人が「どうやって動かすの？」と聞くようなら、既に利息を払っている状態です。

最も手戻りを生むミス：

• 実行可能なパスを1つ作る代わりに複数のサービスや画面、設定を一気に生成する\n- 最初の機能がエンドツーエンドで動く前に認証、支払い、複雑なスタイリング、完全なデータモデルを取り込む\n- セットアップ手順をチャットに置きっぱなしにしてスクリプトやREADMEに入れない\n- クリーンなenvテンプレートを忘れて、次のマシンが推測なしに起動できない

単純な例：ログイン、テーマ、請求を備えた「完全な」アプリを生成したが、初回起動で秘密鍵がないため失敗し、.env.exampleがない。結局最初の機能が有用かを確かめる代わりにセットアップ修正に1時間を費やす羽目になります。

誠実にやりましょう：1つの実行コマンド、1つの小さな機能、1つのenvテンプレート、そして拡張。

反復を始める前の簡単チェックリスト

「もう一つ機能を追加する」前に、明日でも他人でも拾いやすいプロジェクトか確認してください。速さだけが目的ではありません。予測可能性が目的です。

• ワンコマンド実行： 新しい開発者が env テンプレートをコピーし、必要な値を設定して単一コマンドでアプリを起動できる。DBセットアップやマイグレーションが必要ならそれもスクリプトにまとめる。\n- スクリプトが基本をカバー： dev, test, build と速いスモークチェックの明確なコマンド。\n- 分かりやすい構成： レイアウトが物語を語る（アプリコード、設定、スクリプト、テスト）ので、コード全体を読み回さなくても分かる。\n- バーティカルスライスのデモ経路： デモを一文で説明できる（例：「項目を作成してリストで見る、リフレッシュしても残っている」）。\n- ロールバックポイント： 大きな変更前に戻せる安全点（クリーンなコミット、タグ、スナップショットやロールバック機構）を確保する。

どれかがダメなら今直してください。リポジトリが小さいうちにスクリプトや命名を整えるのは安い投資です。

次のステップ：ワークフローを繰り返せる習慣にする

グリーンフィールド開始が価値を生むのは、それを繰り返せるときです。最初のバーティカルスライスがエンドツーエンドで動いたら、良い部分を小さなテンプレートに凍らせます：同じフォルダパターン、同じスクリプト名、UI/API/データをつなぐ同じやり方。

最初のスライスをリファレンス実装として扱います。スライス#2を始めるときはコードではなく形をコピーします。スライス#1にルート、ハンドラ、データアクセス層、基本テストがあれば、スライス#2も同じ道筋を辿るべきです。

計画は軽めに保ちます。次の2〜3スライスのための1ページメモで十分です：各スライスの目標とユーザーアクション（1文）、必要なデータ、「完了」チェック、初期にテストすべきリスク。

維持作業を習慣にします。週に1回、短いクリーンアップを行う：スクリプトを締め、READMEに新しいセットアップ手順を追記し、env例ファイルを更新してオンボーディングを簡単に保つ。

チャット中心のビルドループを好むなら、Koder.ai (koder.ai) のような選択肢があります。計画モード、スナップショット、ロールバックをサポートし、必要に応じてソースコードをエクスポートできます。

目標は考えずに回せるワークフロー：2〜3スライスを計画し、1つのスライスを作り、安定化し、繰り返す。