新しいリポジトリでClaude Codeを使い始める前のチェックリスト8項目

このTipsでできること

新しいリポジトリ(自分のプロジェクト / 仕事のclone / OSSへの貢献等)でClaude Codeを使い始めるとき、最初に整える8項目を整理しました。後からでもセットできますが、最初に入れておくと生産性と安全性が大きく変わる項目です。

チェックリスト8項目

☐ 1. リポジトリルートに CLAUDE.md を作る

最低限書くべきもの:

• プロジェクトの目的(1〜2行)
• 主要技術スタック / フレームワーク
• テスト・ビルドコマンド
• コミット規約 / ブランチ命名

ゼロから書く必要はありません。Claude Code内で /init を実行すると、コードベースを解析して、ビルドコマンド・テスト手順・規約を含む CLAUDE.md のたたき台を自動生成します。既存の CLAUDE.md がある場合は上書きせず、改善案を提案する挙動です。生成された土台に、Claudeが自力で気づけない方針(運用ルールや禁則)を手で足していく流れが楽です。

/init

公式ドキュメントは CLAUDE.md を200行以内に収めることを目安として挙げています。長くなりすぎると読み込むトークンが増え、指示への追従が下がるためです。肥大化してきたら .claude/rules/ 配下にトピック別ファイルとして切り出す方法があります。詳細な書き方はメモリ三層構造を参照。

☐ 2. .claude/settings.json を作る

最低限のhookを1つ仕込んでおく:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{ "type": "command", "command": "echo edited >&2" }]
    }]
  }
}

これだけでも「Claude Codeが編集したら何かが走る」感触を持てる。後からHooks実例カタログで本格的なhookに拡張。

☐ 3. .gitignore にClaude関連を追加

機密情報の漏洩防止:

# Claude Code
.claude/settings.local.json
.env
.env.local

.claude/settings.json 自体はgit管理してチームで共有、.local.json は個人秘密用に分離します。なおClaude Codeは .claude/settings.local.json を作成するときに、gitがそのファイルを無視するよう自動で設定します。個人の方針を書く CLAUDE.local.md(プロジェクトルートに置けて CLAUDE.md と同じように読み込まれる)も、/init で個人用オプションを選べば .gitignore への追加までやってくれます。手元のsandbox URLやテストデータの場所など、チームに共有しない設定はこちらへ書くと安全です。

☐ 4. テスト・ビルドが走ることを確認

Claude Codeが「動作確認のためにテストを走らせていいか」判断するための前提条件。

npm install
npm test
npm run build

これらが手元で通る状態にしておく。失敗するとエージェントが間違った前提で動く。

☐ 5. 主要ディレクトリのroleをCLAUDE.mdに書く

## ディレクトリの役割
 
- `src/lib/` — 共通ユーティリティ
- `src/components/` — React コンポーネント
- `src/app/` — Next.js App Router
- `tests/` — Jest テスト

これがあるだけで、Claude Codeが「どこに何を書くか」を毎回迷わなくなる。

☐ 6. 禁則事項を明文化

「触ってほしくない」項目をCLAUDE.mdに書く:

## 禁則
 
- `package-lock.json` は手動編集しない(npm install 経由のみ)
- migrations/ 配下は人間レビュー必須
- API key を含むファイルは絶対にコミットしない

期待通りに動かない10シナリオシナリオ4(危険コマンド)もここでカバー。

☐ 7. 認証情報の最小権限化

• ~/.aws/credentials 等をClaude Codeから見えないようにする
• 開発用と本番用のprofileを分離
• 本番接続は別シェル / 別コンテナで実行

詳細はDevContainer / Sandbox完全実装を参照。

☐ 8. 「最初の依頼」を考えておく

Claude Codeを初めて起動した際の最初の依頼で、「コードベースの理解度」を測ります。

• 「このリポジトリの主要モジュール5つを1行ずつ要約して」
• 「テストカバレッジが薄い領域を特定して」
• 「開発環境のセットアップ手順をREADMEから抽出して」

これらの応答精度で、Claude CodeがCLAUDE.md / ディレクトリ構造をどう理解したかが分かります。

チェックリストの順序と優先度

8項目を全部一度にやる必要はありません。手間と効果から優先度を付けると、次の早見表のようになります。

順序の目安は1 → 2 → 4 → 5が最初の必須(Day 1)、3 → 6 → 7は当日中に追加(Day 1〜2)、8は実際に使い始めるときです。1と2は /init でほぼ自動化できるため、実質的に時間がかかるのは4(テスト・ビルドが通る状態の確認)と7(認証情報の分離)の2つだと考えると着手しやすくなります。

詳しい長期ロードマップはClaudeを学ぶ1週間ロードマップを参照してください。

新規リポジトリと既存リポジトリでの違い

8項目の重みは、対象が「自分でゼロから作るリポジトリ」か「cloneしてきた既存リポジトリ / OSS」かで変わります。

• 新規リポジトリ: テスト・ビルドがまだ無いことが多いため、項目4は「動く状態を作ること」自体が作業になります。CLAUDE.mdも /init の解析対象が少ないので、目的や規約を手で書く比重が上がります。
• 既存リポジトリ / clone: コードが揃っているので /init の自動生成が効きやすく、項目1・5の土台はほぼ自動で埋まります。一方で、見慣れないコードベースに対する項目7(認証情報の最小権限化)と項目6(触ってほしくない領域の明文化)の重要度が上がります。
• OSSへの貢献: リポジトリの CLAUDE.md は基本的に変更せず、個人方針は CLAUDE.local.md(gitignore対象)に書いて、本体のコミットに混ざらないようにする使い分けが向いています。

セットアップでよくあるつまずき

• CLAUDE.mdが長すぎて効きにくい: 公式は200行以内を目安としています。1ファイルに詰め込みすぎると追従が下がるため、トピック別に .claude/rules/ へ切り出すと読み込みが軽くなります。
• CLAUDE.mdが読み込まれていない: 反映されないときは /memory で、現在のセッションに読み込まれている CLAUDE.md / CLAUDE.local.md の一覧を確認できます。一覧に出ていなければ、置き場所が読み込み対象外の可能性があります。
• 指示がときどき守られない: CLAUDE.mdは強制ではなく文脈として渡る仕組みのため、必ず実行させたい処理(コミット前のlintなど)はCLAUDE.mdではなくHooksで固定するのが確実です(項目2のHooks実例を参照)。
• AGENTS.mdを置いているのに読まれない: Claude Codeが読むのは CLAUDE.md です。すでに AGENTS.md を使っているなら、CLAUDE.md から @AGENTS.md で取り込むと両方のツールが同じ指示を共有できます。

まとめ

新しいリポジトリでClaude Codeを使い始めるとき、最初の1時間で本記事8項目のうち4〜5個を整えるだけで、その後の生産性が大きく変わります。項目1(CLAUDE.md)が最重要で、それ以外は段階的に入れていけば大丈夫です。