📑 目次

1. 質問1：プロジェクトってどうやって管理したらいい？
2. 質問2：なぜ Claude から先に質問してもらった方がいいの？
3. 質問3：最初に作っておくと良いファイルって何？
4. 質問4：プログラムってどうやって開発・管理していくの？
5. まとめ

俺は Claude Code でいくつかプロジェクトを作ってきたが、毎回「次はもっと整理して始めたい」と思いながら、結局その場の勢いで始めてしまっている。今日は思い切って、Claude にプロジェクト管理の基本について聞いてみることにした。同じことを何度か聞いているうちに、答えがだんだん具体的になってきたので、そのやりとりをそのままここに残しておく。マニュアルにもなるし、自分用のメモにもなるはずだ。

質問1：プロジェクトってどうやって管理したらいい？

ケンタ：プロジェクトを始めるとき、いつもファイルがどんどん散らかっていって、後で見返すと「これ何だっけ」が増える。そもそもプロジェクトってどうやって管理したらいいんだ？

Claude：まず原則を1つ。1プロジェクト = 1ディレクトリ。これだけ守れば半分解決する。複数のプロジェクトのファイルを1つのフォルダに混ぜると、後で必ず後悔する。

ディレクトリ構造は、Python ならこれで十分だ。

my_project/
├── src/          # 動くコード
├── tests/        # テスト
├── docs/         # ドキュメント
├── experiments/  # 試したけど本番に入れていないもの
├── README.md
├── CLAUDE.md
├── .gitignore
├── .env
├── .env.example
└── requirements.txt

「動くもの」と「動かないもの」はディレクトリで分ける。src/ に入れるのは今動いているコードだけ。試作や実験は experiments/ に放り込む。そうすると「これ本番用？」という混乱がなくなる。

それと、git は最初に init する。「動くものができてから」では遅い。動く前にやる。理由は後で話す。

ケンタ：なるほど。じゃあ Claude Code を使って始めるとき、最初に何から手をつければいい？ 具体的な順番が知りたい。

Claude：この順番で打てばいい。

mkdir my_project
cd my_project
git init
claude

Claude Code が起動したら、最初のプロンプトはこれだ。

README.md と .gitignore（Python用）と .env.example を作って。
プロジェクトの目的は〇〇。

コードを1行も書く前に、この3ファイルを置く。これがスタートラインだ。

ちなみに、俺が最初に作った whisper_proj（日本語音声をタガログ語に変換するやつ）は git init していなかった。途中でファイルが壊れたとき、戻れなくて2時間かかった。あれは本当に無駄だった。

質問2：なぜ Claude から先に質問してもらった方がいいの？

ケンタ：最近、Claude に何か作ってほしいときに、最初に Claude から質問してもらうほうが結果がいい気がする。なんでだろう？

Claude：人間は「自分の考えていることはすべて言語化できている」と思いがちだが、実際には半分も言語化できていない。頭の中に「なんとなくこういうもの」があるだけで、細部は決まっていない。

質問されることで「あ、そこは決めてなかった」が浮かび上がる。よく抜け漏れるのはこのあたりだ。

• 想定ユーザーは自分だけ？複数人？
• 「完成」の条件は何か
• 失敗したときの挙動（エラーを出す？ログに残す？）
• 扱うデータ量（100件？100万件？）
• 性能要件（1秒以内に返す必要があるか）
• どこで動かすか（ローカル？サーバー？）

5分の質問が、5時間の手戻りを防ぐ。「実装を始める前に、不明点を3つ質問して」と頼むだけで、アウトプットの質が変わる。

ケンタ：具体的にどんな質問されると効くの？

Claude：実際に効果が出た質問パターンはこの3つだ。

• 「このデータは今後どれくらい増えますか？」→ DB 設計が変わる
• 「同時に複数人が使いますか？」→ 排他制御の必要性が変わる
• 「失敗時はどうリカバリしますか？」→ エラーハンドリングの深さが変わる

これを聞かれないまま実装すると、後で「あ、そこ考えてなかった」が必ず出る。

質問3：最初に作っておくと良いファイルって何？

ケンタ：プロジェクトを始めた直後、まだコード1行も書いていない段階で、何を先に置いておくと後が楽？

Claude：この順番で置く。

• CLAUDE.md — Claude Code がセッションをまたいで読んでくれる。プロジェクト固有の文脈と運用ルールをここに書く
• README.md — 人間向け。目的・起動方法・主要ファイルの説明
• .gitignore — Python なら __pycache__/, *.pyc, venv/, .env は必須。テンプレートをそのまま使えばいい
• requirements.txt または pyproject.toml — 依存関係はコードを書き始める前から記録する
• .env.example — 必要な環境変数のテンプレ。実値は書かない
• .env — 実値を書く。.gitignore で除外する

ケンタ：CLAUDE.md って具体的に何を書く？

Claude：最低限、この4項目を書けば十分だ。

# プロジェクト概要
このプロジェクトは〇〇をするツール。ターゲットは自分一人。

# 主要ファイル
- src/main.py     : エントリーポイント
- src/converter.py: 変換処理のコア
- .env            : API キーなど（git 管理外）

# 起動コマンド
python src/main.py --input sample.wav

# 運用ルール
- 外部 API を叩くときは必ずエラーハンドリングを入れる
- テストを書かずに src/ にコードを追加しない

Claude Code はセッションが変わっても CLAUDE.md を読む。「前回どこまでやったっけ」の時間が減る。最近、aigeek.biz の記事管理プロジェクトで初めてちゃんと書いてみたが、2週間前の自分が何を考えていたかをすぐ思い出せた。これは効いた。

質問4：プログラムってどうやって開発・管理していくの？

ケンタ：最後に大きな質問なんだけど、プロジェクトを作り始めた後、それをどう育てていくの？俺はいつも勢いでガーッと作って、後でぐちゃぐちゃになる。

Claude：「動かしながら作る」スタイルを取る。最初から完璧な設計を求めない。動かない完璧な設計より、動く不完全なコードの方が価値がある。

進め方はこのループだ。

• 機能を1つ決める
• それだけを実装して動かす
• 動いたらコミットする（1機能 = 1コミットを目安に）
• CLAUDE.md を更新する
• 次の機能へ

詰まったら Claude に「今こういう構造で、こうしたい、こう詰まっている」と状況を整理して投げる。状況の整理自体が問題解決の半分だ。

動かなくなったら git で戻る。だから最初に git init が必要だ。

リファクタは「動いてから」やる。動いていないコードを綺麗にしようとすると永遠に終わらない。

ドキュメント（CLAUDE.md）は実装と一緒に更新する。「後でやろう」と思ったら一生やらない。

ケンタ：コミットメッセージってどう書けばいい？毎回「update」とか「fix」だけになってしまう。

Claude：この3パターンを使い分ければ十分だ。

• feat: 音声ファイルの入力バリデーションを追加 — 新機能
• fix: 空ファイルを渡したときのクラッシュを修正 — バグ修正
• docs: CLAUDE.md に起動コマンドを追記 — ドキュメント更新

短くていい。「何を変えたか」だけ書く。「なぜ」は CLAUDE.md に書く。「update」だけのコミットは、1週間後の自分には何も伝わらない。

まとめ

結局、何もない状態で勢いで始めるより、最初に5分だけ整える時間を取ったほうが、後の数時間が楽になる、ということだった。当たり前のことを言われた気もするが、当たり前のことを言ってもらえる相手がいる、というのが Claude Code の強さなのかもしれない。次のプロジェクトはこの順番で始めてみる。

---

関連記事

• Claude Code に「妻に音声を翻訳して聞かせたい」と打ち込んだら、本当にできた話（whisper_proj の体験記。git init していなかった代償もここに）
• Claude Code で AI ニュースサイトを作って運営してみた｜3週間の全記録