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

このTipsでできること

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

チェックリスト8項目

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

最低限書くもの:

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

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

/init

/init には対話型の別ルートがあります。環境変数 CLAUDE_CODE_NEW_INIT を 1 にして実行すると、CLAUDE.md・スキル・フックのどれを整えるかを先に聞かれます。そのあとサブエージェントがコードベースを調べ、追加の質問を経て、書き込み前に確認できる提案が出ます。変数は /init の動き方だけを変えるので、設定したままで構いません。

export CLAUDE_CODE_NEW_INIT=1
claude

/init は、CLAUDE_CODE_NEW_INIT が無くても .cursor/rules/ と .github/copilot-instructions.md の内容を取り込みます。OpenAI CodexやGemini CLIの設定がリポジトリにあるときは、/import で引き継ぐ案内も出ます。

サイズの目安は1ファイル200行以内です。長いと読み込むトークンが増え、指示への追従が下がります。肥大化したら、特定のファイルを触るときだけ読み込まれる .claude/rules/ 配下のパス限定ルールに切り出せます。書き方はメモリ三層構造に譲ります。モノレポで他チームのCLAUDE.mdを読ませたくないときはclaudeMdExcludesで除外できます。

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

プロジェクト直下の .claude/settings.json はコミットして、チーム全員が同じ権限・フック・プラグインを使えるようにします。個人の上書きは各自の .claude/settings.local.json に置きます。

最初のフックには、編集したファイルを自動整形する例が向いています。Edit|Write のあとだけ走るので、他のツール呼び出しには影響しません(jq とPrettierが必要です)。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

フックが成功しても会話には何も表示されません。動作確認は、シングルクォートの文字列を含む行をClaudeに追加させ、Prettierの既定でダブルクォートに直るかを見ます。セッション内で /hooks を開くと、登録されたフックの一覧も見られます。本格的なフックはHooks実例カタログで拡張できます。

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

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

.claude/settings.json はgit管理でチーム共有、.local.json は個人用に分けます。Claude Codeが settings.local.json を書き込むのは、権限プロンプトで「Yes, and don't ask again」を選んだ最初のときなどです。そのとき、gitリポジトリのignore設定になければ、グローバルのgit除外ファイルに **/.claude/settings.local.json を足します。リポジトリの .gitignore は書き換えません。ファイルを手で作った場合は、自分で .gitignore に足します。

CLAUDE.local.md は個人用の指示ファイルで、プロジェクトルートに置くと CLAUDE.md と同じように読み込まれます。.gitignore への追加は手作業ですが、上の対話型 /init で個人用オプションを選ぶと追加まで済みます。手元のサンドボックスURLやテストデータの場所など、チームに共有しない内容の置き場です。

プロジェクトに .claudeignore というファイルを置いても効果はありません。中身は Read のdenyルールに移します。

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

テストやビルドが手元で通る状態にしておくと、Claudeが変更を自分で確かめられます。

npm install
npm test
npm run build

失敗する状態のままだと、エージェントが間違った前提で動きます。

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

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

「どこに何を書くか」を毎回迷わなくなります。ただし、名前から役割が読み取れるディレクトリまで並べる必要はありません。/doctor のCLAUDE.md整理機能(v2.1.206以降)は、コードベースから導ける内容を削る提案をします。対象はディレクトリ構成・依存関係の一覧・アーキテクチャ概要です。落とし穴・理由・ツール既定と異なる規約は残します。名前だけでは分からない役割(legacy/ は新規コード禁止、など)に絞って書くと、あとで削られにくくなります。

指示ファイルが溜まってきたら、/doctor prompt-audit(v2.1.283以降)でCLAUDE.md・スキル・ルールの古い指示や矛盾を洗い出せます。

☐ 6. 禁則事項を明文化

「触ってほしくない」項目をCLAUDE.mdに書きます。

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

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

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

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

最初の1つは、.claude/settings.json のdenyルールで書けます。

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Read(~/.aws/**)"]
  }
}

~/ は Read(~/Documents/*.pdf) のようにホームからの相対パスを表します。Readルールは、GrepやGlobなど、ファイルを読む組み込みツールにも最善努力で適用されます。ルールはdeny、ask、allowの順に評価され、denyに当たるとallowで例外を作れません。denyルールはBashの cat や head、リダイレクト先にも効きます。ただし、grep -r のようにファイル名を書かないコマンドや、自分でファイルを開くスクリプトは通り抜けます。すべてのプロセスから閉じたいなら、サンドボックスを有効にします。詳細はDevContainer / Sandbox完全実装にあります。

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

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

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

応答の精度で、Claude CodeがCLAUDE.mdとディレクトリ構造をどう受け取ったかが分かります。

どの順に進めるか

8項目を一度にやる必要はありません。項目1は /init でほぼ自動化できます。項目2のフックも、対話型の /init で選べます。

詳しい長期ロードマップはClaudeを学ぶ1週間ロードマップにあります。

新規・既存・OSSで効く項目が違う

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

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

• CLAUDE.mdが長すぎて効きにくい: 200行を超えると、起動時と /status に警告が出ます。ルールファイルと @path インポートも1ファイルずつ数えられ、各ファイルが範囲内でも合計が上限を超えると警告されます。
• CLAUDE.mdが読み込まれていない: /context を実行し、Memory filesの一覧にCLAUDE.mdとCLAUDE.local.mdがあるかを見ます。無ければ、Claudeには見えていません。/memory は読み込みの確認ではなく、場所の一覧と編集の入口で、まだ無いCLAUDE.mdの項目も並びます。
• 指示がときどき守られない: CLAUDE.mdは強制ではなく文脈として渡る仕組みです。必ず実行させたい処理(コミット前のlintなど)は、項目2のHooksで固定します。
• AGENTS.mdを置いているのに読まれない: v2.1.277以降のClaude Codeは、AGENTS.md を直接読みます。ただし、作業ディレクトリとその上位に CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md が1つも無いときに限ります。どれか1つでもあれば CLAUDE.md 系だけが読まれます。この3つ以外は数えられません。~/.claude/CLAUDE.md、組織のmanaged CLAUDE.md、.claude/rules/ は、AGENTS.md と並んで読まれます。両方を読ませるには、CLAUDE.md の先頭に @AGENTS.md を書きます。/config のProject instructionsを claude-md-and-agents-md にしても同じです。
• CLAUDE.local.mdを足したらAGENTS.mdが読まれなくなった: CLAUDE.local.md も「CLAUDE.md系」に数えられるためです。AGENTS.md だけに頼っているリポジトリで個人用ファイルを足すと、AGENTS.md が読まれなくなります。上の @AGENTS.md か claude-md-and-agents-md の設定で両立できます。AGENTS.md だけが読まれると、起動時に会話へ no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md の形で1行が出ます。v2.1.280より前は /memory と /context が直接読み込んだ AGENTS.md を一覧に出さないため、確認は会話で指示内容を尋ねる形になります。

まとめ

既存のリポジトリなら、/init の土台を直し、テストが通ることを確かめるところから始めます。認証情報の線引き(項目7)は、最初の依頼を出す前に済ませます。