Claude Codeに渡すプロジェクトフォルダの整え方

はじめに

Claude Code に「このコードを修正してください」と頼む前に、プロジェクトフォルダを整えておくことが、成功の鍵です。本記事では、整理方法を解説します。

理想的なフォルダ構成

my-app/
├─ .git/              ← Git リポジトリ
├─ .gitignore         ← 除外ファイル指定
├─ README.md          ← プロジェクト説明
├─ NOTES.md           ← 作業メモ
├─ src/
│  ├─ main.py
│  ├─ utils.py
│  └─ ...
├─ tests/
│  ├─ test_main.py
│  └─ ...
├─ docs/              ← ドキュメント
└─ node_modules/      ← 外部パッケージ（gitignore 対象）

準備1：README.md の整備

README に書くべき内容

# プロジェクト名

## 目的
このプロジェクトの目的を 1 行で述べる

## 現在の状態
- ✅ 完成した機能
- 🚧 進行中の機能
- ⏳ 予定している機能

## 技術スタック
- Python 3.10
- Flask 2.0
- SQLite

## セットアップ
git clone ...
pip install -r requirements.txt
python main.py

## テスト
pytest tests/

## 注意点
- DB は SQLite を使用
- 環境変数 API_KEY が必須

なぜ必要か

Claude Code は README から目的と構造を理解します。良い README があれば、より正確な修正が可能です。

準備2：NOTES.md（作業メモ）

NOTES.md に書く内容

# Claude Code への作業指示メモ

## タスク 1：関数 A の最適化

【目的】
処理時間を 50% 削減

【対象ファイル】
src/utils.py の function_a()

【入力】
int, list

【出力】
dict（形式は変わらないこと）

【テスト】
tests/test_utils.py::test_function_a を実行

【注意点】
- 既存の呼び出し元との互換性を保つ
- コメント は日本語で統一
- 副作用がないこと

---

## タスク 2：テストケース追加

【目的】
エッジケースをカバー

【対象ファイル】
tests/test_main.py

【追加するテスト】
- 空の入力
- None の入力
- 型が違う場合

なぜ必要か

NOTES.md があれば、Claude Code が「何をやればいいか」を正確に理解できます。

準備3：対象ファイルの明確化

.gitignore の確認

確認内容：
□ node_modules/ は除外
□ __pycache__/ は除外
□ .env / .env.local は除外
□ 本当に除外したいファイルだけ

修正対象外のファイルを整理

❌ 修正してほしくない：
- package.json（パッケージマネージャー設定）
- requirements.txt（Python 依存関係）
- .github/ （CI/CD 設定）
- config/ （本番環境設定）

✅ Claude Code が修正可能：
- src/ （実装コード）
- tests/ （テストコード）
- docs/ （ドキュメント）

準備4：前提知識の提示

context.md（オプション）

# プロジェクト背景情報

## アーキテクチャ
MVC パターンを採用
- Model: ORM は SQLAlchemy
- View: Jinja2 テンプレート
- Controller: Flask ルート

## 命名規則
- 関数：snake_case
- クラス：PascalCase
- 定数：UPPER_SNAKE_CASE

## 使用しているライブラリのバージョン
- Flask 2.3
- SQLAlchemy 2.0
- Pytest 7.0

## 実装で避けるべきパターン
- グローバル変数
- 超長い関数（50行以上）
- 未使用のインポート

準備5：実行確認環境

重要なコマンド

Claude Code に教える：

# セットアップ
pip install -r requirements.txt

# テスト実行
pytest tests/

# ビルド
npm run build

# ローカルサーバー
python main.py

準備チェックリスト

□ Git でリポジトリ初期化済み
□ README.md で目的が明記されている
□ NOTES.md で具体的なタスクが書かれている
□ .gitignore で不要なファイルを除外
□ 修正対象ファイルが明確
□ テスト実行コマンドが記載
□ 前提知識が context.md に記載
□ 環境依存情報が書かれている

全てチェック → Claude Code に任せる準備完了！

よくある失敗

❌ 失敗例1：説明なしで Claude Code に任せる

「このフォルダを修正してください」
  ↓
Claude Code が何をやればいいか不明
  ↓
斜め上の修正
  ↓
役に立たない

✅ 改善例

README + NOTES で指示を明確に
  ↓
Claude Code が正確に理解
  ↓
期待通りの修正

まとめ

Claude Code に渡す前の準備：

5 つの準備：

1. README.md の整備（目的・構造）
2. NOTES.md の作成（具体的なタスク）
3. 対象ファイルの明確化
4. 前提知識の提示（オプション）
5. 実行確認環境の整備

プロジェクトフォルダの整理が、Claude Code の成功を左右します。

Claude Codeで安全に作業するためのGit準備と合わせることで、効率的で安全な開発が実現します。