Claude CodeのCLAUDE.mdスターターテンプレート：既存コードで効く最小ルール集

CLAUDE.mdは「毎回の説明」を減らすための作業メモ

Claude Codeを既存コードベースで使い始めると、最初に困るのはモデルの賢さではなく、プロジェクト固有の前提を毎回説明し直すことです。ビルドコマンド、触ってよい範囲、レビューで見てほしい観点、完了条件が会話だけに残っていると、次のセッションで同じミスが戻ってきます。

その再説明を減らす最小のファイルがCLAUDE.mdです。公式のClaude Code memory docsでは、CLAUDE.mdはセッション開始時に読まれる永続的な指示として説明されています。ただし、強制設定ではなく「文脈」です。削除禁止や危険コマンドの制限まで本当に守らせたい場合は、settingsやsecurityの権限設計と組み合わせる必要があります。

この記事では、Masaが既存のAstroサイトと小さなSaaSリポジトリで使っている型を、コピペして始められる形にしました。harnessという言葉を使うなら、ここでは「エージェントが安全に動くための足場」という意味です。巨大な社内規約を作る前に、まずは足場を小さく置くのが実務では効きます。関連する全体設計はCLAUDE.mdテンプレート集、権限まわりはClaude Code権限ガイドも合わせて確認してください。

コピペで始めるCLAUDE.mdテンプレート

最初のCLAUDE.mdは長くしすぎないほうが守られます。公式ドキュメントでも、具体的で短い指示のほうが従われやすいと説明されています。まずはプロジェクト概要、コマンド、作業境界、完了条件、報告形式だけを書きます。

# CLAUDE.md

## Project snapshot
- Product: content site and paid template store
- Stack: Astro, TypeScript, MDX, npm
- Main app: site/
- Source articles: site/src/content/blog*/
- Owner voice: practical, evidence-based, no hype

## Commands
- Install dependencies: cd site && npm install
- Start local dev server: cd site && npm run dev
- Build check: cd site && npm run build
- Search fast: rg "keyword" site/src
- Inspect git state: git status --short

## Working rules
- Read existing files before editing.
- Keep changes scoped to the requested slug or feature.
- Do not edit .env, dist, generated reports, or unrelated locale files.
- Preserve pubDate, category, tags, author, lang, and heroImage unless they are broken.
- Ask before destructive git operations, production deploys, or secret rotation.

## Article quality
- Japanese canonical articles should be 4000-6000 characters excluding code.
- Include at least three real use cases.
- Include concrete pitfalls and how to avoid them.
- Include runnable code or config examples, not pseudocode.
- Check official docs when the topic may have changed.

## Definition of done
- The requested files are edited.
- Code fences and JSON/YAML examples are valid.
- Links to internal pages and official docs are present.
- Verification commands have run or skipped checks are explained.
- Remaining risks are stated in the final message.

このまま置くなら、プロジェクトルートのCLAUDE.mdに保存します。チームで共有するならGit管理に含め、個人だけのメモはCLAUDE.local.mdへ分けます。公式ドキュメントでは、CLAUDE.local.mdは個人用のプロジェクト固有メモとして扱う例が示されています。会社全体のルールまで配る場合は管理ポリシー側のCLAUDE.mdやsettingsを検討しますが、個人開発や小さなチームならまずこの1ファイルで十分です。

settings.local.jsonで危険操作を別管理する

CLAUDE.mdは行動の希望を書けますが、強制力は限定的です。たとえば「本番デプロイしないで」と書いても、ユーザーが許可すればツールは動きます。危険なBashコマンドや編集範囲は.claude/settings.local.jsonに分けると、指示文と実行制御を混ぜずに済みます。

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(site/src/content/blog/**)",
      "Bash(rg:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(git reset:*)",
      "Bash(git checkout --:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)",
      "Edit(reports/**)"
    ]
  }
}

このJSONは「Claudeに読ませるメモ」ではなく、作業環境の設定です。共有すべきチーム標準なら.claude/settings.json、個人の安全網なら.claude/settings.local.jsonにします。リポジトリによってはsettingsの扱いが違うので、最新の項目名は公式のsettings documentationで確認してください。

3つの実務ユースケース

ユースケース	CLAUDE.mdに書くこと	効果
多言語記事の更新	対象slug、10言語、frontmatter維持、文字数、CTA、検証方法	英語本文の混入や更新日の漏れを減らす
既存SaaSの小さな修正	触ってよいディレクトリ、テストコマンド、DB変更時の承認条件	余計なリファクタや危険なマイグレーションを避ける
チームのレビュー補助	レビュー観点、優先度、再現手順、最終報告の形式	「なんとなく良さそう」ではなく確認可能なレビューになる

1つ目の多言語記事では、site/src/content/blog-en/だけを直して他言語を放置する事故が起きやすいです。requireAllLocalesの意味、対象ディレクトリ、descriptionの上限、内部リンクの言語別パスをCLAUDE.mdに書いておくと、最初の探索が安定します。

2つ目のSaaS修正では、Claude Codeが親切に周辺ファイルまで改善しようとすることがあります。小さなバグ修正なのに認証基盤や課金ロジックまで触られると、レビューコストが一気に上がります。Edit(src/components/**)のように作業面を狭くし、DBや本番環境は承認制にするのが現実的です。

3つ目のレビュー補助では、severity, file, line, reproduction, test gapのような出力形式を先に決めます。これにより、レビュー結果をIssueやPRコメントに転記しやすくなります。Claude CodeのCLI referenceも確認して、ワンショット実行と対話実行を使い分けると運用しやすくなります。

具体的な落とし穴

最初の落とし穴は、CLAUDE.mdを長い願望リストにすることです。「品質を高く」「安全に」「良い感じに」という指示は読めても検証できません。「npm run buildを実行する」「reports/を編集しない」「descriptionは120文字以内」のように、Yes/Noで確認できる形に変えます。

2つ目は、指示と設定を混同することです。CLAUDE.mdに「git push禁止」と書くだけでは弱いです。重要な禁止事項はsettingsのdeny、CIの保護ルール、GitHubのブランチ保護で支えます。CLAUDE.mdは判断の補助、settingsは実行制御、CIは最終検査という役割分担にします。

3つ目は、古いルールを残し続けることです。Next.jsからAstroへ移行したのにnext buildが残っている、Jestをやめたのにnpm testだけが書いてある、という状態ではClaude Codeも人間も迷います。月1回でよいので、失敗した作業の直後にルールを1行だけ更新します。

4つ目は、秘密情報を書いてしまうことです。APIキー、顧客名、内部URL、未公開の売上データはCLAUDE.mdに置かないでください。必要なら「秘密情報は.envにあり、内容は表示しない」と書くだけにします。公開リポジトリで共有する前提のファイルだと考えると判断しやすくなります。

小さく導入して育てる手順

導入は4段階で十分です。まず/initや手動メモで現在の構成を棚卸しします。次に上のテンプレートを30行程度に削ります。その後、最初の3タスクだけで使い、Claude Codeが見落とした点を1つずつ追記します。最後に、settingsやCIで本当に守るべき境界を固定します。

記事サイトなら、最初の3タスクは「1記事の更新」「1つの内部リンク修正」「1つのOGP確認」で試します。アプリなら「小さなUI文言」「単体テスト追加」「ログ改善」から始めます。いきなり全面リファクタを任せるより、足場の効き方が見えます。

公開前レビューでは、CLAUDE.md自体も記事と同じように点検します。まず、コマンドが今のリポジトリで本当に動くかを見ます。次に、禁止対象が広すぎないかを確認します。たとえばEdit(site/src/content/**)は便利ですが、今回のように他workerが別slugを触っている状況では広すぎます。Edit(site/src/content/blog/**/target-slug.mdx)のように、作業単位に合わせて狭められるなら狭めます。

また、完了条件には「何をしないか」も書きます。ビルドをしない、deployしない、reportを生成しない、commitしない、という制約がある仕事では、禁止事項を会話だけに残すと事故が起きます。Claude Codeは前向きに作業を終わらせようとするので、スコープ外の親切を抑える文面が必要です。

最後に、更新履歴を1行だけ残す運用も有効です。2026-06-03: locale記事の品質監査向けに文字数、CTA、公式リンク確認を追加のような短いメモがあれば、次に読む人が「なぜこの規則があるのか」を理解できます。理由が分かるルールは削られにくく、形だけの規約になりにくいです。

もう1つの工夫は、レビュー用の短いプロンプトをCLAUDE.mdの最後に置かないことです。毎回読むべきルールと、必要な時だけ使うレビュー文面は役割が違います。レビュー文面が長い場合は.claude/commands/や別のテンプレート記事へ分け、CLAUDE.mdには「レビュー時は重大度、ファイル、行、再現手順、テスト不足を出す」とだけ書きます。これで普段のコンテキスト消費を抑えつつ、必要な品質基準は残せます。

迷ったときは、次の担当者が30秒で判断できるかを基準にします。読んでも行動が変わらない一文は削り、検証や承認に直結する一文だけ残します。

CTAも同じです。読者が個人なら商品一覧のテンプレートやチェックリストで十分です。チームで権限、レビュー、研修、導入ルールまでそろえるならClaude Code研修・導入相談のほうが早いです。無料の入口はチートシートに置き、実務で繰り返す部分だけ有料教材や相談へ進めると自然です。

この記事で紹介した内容を実際に試した結果、効果が大きかったのは「完璧な規約」ではなく「触ってはいけない場所」「検証コマンド」「完了条件」の3行でした。Masaのサイト更新では、これだけで他slugの誤編集、descriptionの長文化、CTAリンクの消し忘れが減りました。CLAUDE.mdは百科事典ではなく、次のセッションを迷わせないための薄い作業板として育てるのが一番続きます。