Claude Code SkillsとCLAUDE.md設計・テンプレ

Claude Codeを使い始めるとき、最初に整理したいのはCLAUDE.mdとSkillsの役割分担です。
CLAUDE.mdはセッション開始時に読む永続コンテキスト、Skillsは特定タスクでだけ呼ぶ手順パッケージと切り分けるだけで、設定の迷子になりにくくなります。
私自身、/init 直後の雛形は少し情報を盛り込みすぎる前提で受け取り、あとから削って整える運用にしてから精度が安定しましたし、レビュー観点をSkillsへ分けたら会話が軽くなって誤読も目に見えて減りました。
Claude Code のベストプラクティス]やスキルで Claude を拡張するに沿って、/init の再現手順から用途別テンプレ、設計ルール、MCPとHooksの安全運用をまとめます。
さらにClaude料金ページと公式コスト情報を踏まえた目安まで、React/Next.js、Node.js API、Python、ドキュメント執筆向けの形で、迷わず始められる道筋を示します。
要点は、常設ルールをCLAUDE.mdに絞り込み、専門作業をSkillsへ逃がし、外部連携はMCP、強制自動化はHooksと役割を分けるということです。
その線引きができると、設定は短く保てて、運用も安全側に寄せられます。

Claude Code Skills と CLAUDE.md の違い

永続コンテキストとしての CLAUDE.md

最初に押さえたいのは、CLAUDE.md は「毎回読んでほしいことだけを書く場所」だという点です。
Claude Code の概要で説明されている通り、Claude Codeはコードベースを読み、編集し、コマンドを実行しながら作業するエージェント型の開発ツールです。
その前提条件になるプロジェクトの共通ルールを渡すのが CLAUDE.md です。
プロジェクトルートに置いた内容はセッション開始時に読まれるので、ここに入れるべきなのは常時有効である情報に絞られます。

初心者が最初に作る最小構成は、次の7項目で十分です。
たとえば「このリポジトリはNext.jsの管理画面とNode.js APIからなる」「主要技術は TypeScript、React、Prisma、Vitest」「よく使うコマンドは pnpm dev pnpm test pnpm lint」「コード規約は ESLint と Prettier、コンポーネントは PascalCase」「作業フローは実装前に関連ファイル確認、実装後にテストと lint」「禁止事項は本番DBへの直接更新、代替案はマイグレーション経由」「参照先は docs/architecture.md や @docs/testing.md のように書く」といった内容です。
これでClaudeは「このプロジェクトで何を守るべきか」を最初から把握できます。

長くしすぎない理由も明確です。
CLAUDE.md は永続コンテキストなので、レビュー観点、例外ルール、特定チームだけの運用まで詰め込むと、いつも読む情報が膨らみます。
すると本当に守ってほしい原則が埋もれます。
実際、私はレビュー観点を CLAUDE.md に書き込みすぎて、返答が毎回レビュー寄りに引っ張られたことがありました。
そこを Skills に分離したら、実装相談では実装に、レビュー時はレビューに焦点が合うようになり、会話の芯がぶれにくくなりました。

/init は出発点として有効ですが、そのまま完成品にせず削って整える運用が勧められています。
@path/to/import で別ファイルを参照できるので、本体は短く、補足資料は分離するのが素直です。

Claude Code の概要 - Claude Code Docs

Claude Code は agentic coding ツールで、コードベースを読み取り、ファイルを編集し、コマンドを実行し、開発ツールと統合します。ターミナル、IDE、デスクトップアプリ、ブラウザで利用できます。

code.claude.com

タスク特化の Skills

Skills は、常時読むルールではなく「この作業のときだけ使いたい手順」を束ねる仕組みです。
SKILL.md を中心に、必要なら補助スクリプトや参照ファイルを同じフォルダに置けます。
スキルで Claude を拡張するで案内されている通り、関連時に自動で呼ばれることもあれば、/skill-name で明示的に実行することもできます。

向いているのは、PRレビュー、テスト生成、障害調査、設計レビュー、ドキュメント整形のような専門手順です。
たとえば「PRレビュー用 Skill」なら、CLAUDE.md に書くのは「レビュー時は再現性・安全性・保守性を見る」までに留め、Skill 側に「差分確認→型エラー確認→危険なSQL確認→テスト不足確認→コメントテンプレ生成」という流れを持たせます。
こうすると普段の実装会話では余計なレビュー手順を背負わず、必要な場面だけ深い手順を呼べます。

SKILL.md の frontmatter では name と description が特に効きます。
name はスラッシュコマンド名になり、description は自動呼び出しの判断材料になります。
ここが長文すぎたり曖昧だったりすると、選ばれるべき場面で拾われなかったり、逆に意図しないタイミングで候補に出たりします。
スキルを増やすほど、短く具体的な説明の価値が上がります。
ルールファイルが増えすぎると、道具箱に似た形のドライバーが何本も入っている状態になり、どれを掴むかの判断ノイズが増えます。

なお、旧来の .claude/commands/ は後方互換として動きますが、新しく考えるなら Skills に寄せたほうが整理しやすく、構成も今の流れに沿います。

スキルで Claude を拡張する - Claude Code Docs

Claude Code でスキルを作成、管理、共有して Claude の機能を拡張します。カスタムコマンドとバンドルされたスキルが含まれます。

code.claude.com

外部接続の MCP

MCP は、CLAUDE.md や Skills と違って「外の道具につなぐための口」です。
MCP を使用して Claude Code をツールに接続するで説明されている通り、GitHub、Notion、Slack、データベースのような外部サービスをClaude Codeから扱うときに使います。
つまり、MCP はルールでも手順でもなく、ツール接続の層です。

ここを混同すると設計が崩れます。
たとえば「GitHub でPRを読む」は MCP の仕事ですが、「PRをどういう観点でレビューするか」は Skill の仕事です。
「このリポジトリでは main へ直接 push しない」は CLAUDE.md の仕事です。
役割を分けると、設定ファイルの置き場に迷いません。

MCP を使用して Claude Code をツールに接続する - Claude Code Docs

Model Context Protocol を使用して Claude Code をツールに接続する方法を学びます。

code.claude.com

決定論的自動実行の Hooks

Hooks は自然言語のお願いではなく、特定タイミングでスクリプトを必ず走らせる仕組みです。
ここが CLAUDE.md と決定的に違います。
CLAUDE.md に「編集後は lint を実行して」と書くことはできますが、それは指示です。
Hooks なら編集後やコマンド実行前などの所定のタイミングで、決めた処理を機械的に実行できます。

向いているのは、毎回必ず起こしたい処理です。
たとえば「保存後に pnpm lint --fix を走らせる」「危険なコマンドの前に確認スクリプトを挟む」「生成ファイルの整形を徹底する」といった用途です。
反対に、「状況を見て判断したいレビュー観点」まで Hooks に入れると、融通が利かず運用が窮屈になります。
Hooks は手順の記憶装置ではなく、自動化の発火装置だと考えると整理しやすくなります。

この4つを読み込まれ方で並べると、頭の中で一枚に収まります。
CLAUDE.md は永続、Skills はオンデマンド、MCP はツール呼び出し、Hooks は自動実行です。
同じ「設定」でも、読まれるタイミングが違えば置き場所も変わります。

いつ何を使う？5分でわかるクイック判断表

迷ったときは、「その情報は毎回必要か、特定作業だけか、外部接続か、自動実行か」で切り分けるとほぼ決まります。
初期設計では、常時適用のルールは CLAUDE.md、専門手順は Skills、毎回必ず起こしたい処理は Hooks、外部サービス連携は MCP に置くのが基準になります。

初心者向けの最小構成としては、まず CLAUDE.md に「このプロジェクトは何か」「何で動くか」「何を叩くか」「何を守るか」だけを書き、レビューやテスト作成のような専門作業は1つか2つの Skill に切り出す形が収まりやすいのが利点です。
MCP は本当に使う外部接続だけ、Hooks は毎回欠かせない処理だけに絞ると、全体が軽く保たれます。
これくらいの密度なら、読まれる情報と呼ばれる手順の境界がはっきりして、最初の導入で迷子になりません。

CLAUDE.md は何を書くファイルか

CLAUDE.md に書くべきなのは、そのプロジェクトで毎回ほぼ必ず必要になる共通ルールです。
CLAUDE.md は広く適用される内容に絞り、長い手順やたまにしか使わない知識は分ける考え方が示されています。
実際に運用すると、この線引きがあいまいなまま何でも詰め込んだファイルは、最初は便利でもすぐ読まれなくなります。
会話のたびに参照される前提のファイルなので、README の要約版ではなく「常時必要な最低限の運転ルール」と捉えると設計しやすくなります。

初回は /init で雛形を作る方法もありますが、そのまま完成版にするより、生成された内容から不要な説明を削っていくほうが収まりが良いです。
筆者も最初は「親切なほうが良いだろう」と背景説明まで入れていましたが、長い CLAUDE.md は結局ルールが埋もれます。
人間が見返したときにも要点が一目で追えたほうが修正しやすく、運用のぶれも減ります。

最小構成チェックリスト

初心者が最初に置くなら、項目は次の7つで十分です。ここでは本稿内で「何を書くか」だけでなく、「どこまで書くか」の温度感も合わせて押さえておくと迷いません。

• プロジェクト概要 / 目的

1〜3行で、このリポジトリが何を作っているかを書きます。
たとえば「Next.jsで構築したB2B向け管理画面」「FastAPI製の社内API」くらいで足ります。
歴史や背景を長く書くより、Claude が今の作業対象を誤解しないことを優先します。

• 技術スタック

言語、フレームワーク、パッケージマネージャ、テスト基盤、主要な周辺ツールを短く並べます。
例としては「TypeScript / Next.js / pnpm / Vitest / ESLint / Prettier」のような粒度です。
ここがあるだけで、提案されるコードやコマンドの方向がそろいやすくなります。

• よく使うコマンド

dev、lint、test、format の4つを中心に、日常で回すものだけを載せます。
実際の package.json にある名前へ合わせるのが前提です。
コマンド一覧を全部貼るのではなく、「変更後にまず何を打つか」が伝わる数に絞るのが判断材料になります。

• コード規約

命名、フォーマット、型の扱いを短く固定します。
たとえば「any は原則使わない」「React コンポーネントは PascalCase」「export は named export 優先」などです。
抽象的な「読みやすく書く」ではなく、修正時に判断できる文にします。

• ワークフロー

ブランチ命名、PR 前に通すテスト、コミット前の最低確認、リリース手順の入口だけを書きます。
ここも全文の手順書にしないほうが機能します。
「feature/* で作業」「PR 前に lint と test を通す」程度でも、Claude の動きは安定します。

• 禁止事項と代替案

「やってはいけないこと」だけで終えず、代わりに何を選ぶかまでセットで書きます。
筆者は以前、禁止事項だけを並べた CLAUDE.md を作ったことがありますが、代替案がないので結局守られませんでした。
「npm install は使わない。
pnpm add を使う」「console.log を残さない。
必要なら logger を使う」と DO / DON’T の対にすると、実務での迷いが消えます。

• 参照先の書き方

詳細は README.md、設計資料、外部規約へ逃がします。
たとえば「API 設計は @docs/api-guidelines.md」「画面設計は @docs/ui-rules.md を参照」のように書きます。
CLAUDE.md 本体に全文を貼るのではなく、入口だけ置く形にします。

この最小構成であれば、CLAUDE.md は1〜2画面に収まりやすく、見返したときにも全体像をすぐ把握できます。
Claude にとっても人間にとっても、短い規約は扱いやすいのではなく、「どのルールが常時有効か」を見失わずに済む、という効果があります。

短く保つための3テクニック

CLAUDE.md が長くなる最大の原因は、ルールと手順書と背景説明を1つに混ぜるということです。
短く保つには、削る技術を最初から前提にしたほうがうまく回ります。

1つ目は、本文には原則だけを書き、詳細は @path/to/import へ逃がすことです。
たとえばコーディング規約の要点だけ CLAUDE.md に書き、命名ルールの細則や例外は @docs/coding-standards.md に分離します。
これだと本体は薄いまま保てますし、詳細文書の更新も独立して進められます。

2つ目は、「毎回必要か」で選別することです。
たとえば PR レビューの詳細テンプレート、障害対応フロー、データ移行の特殊手順は、常時読むより必要時だけ呼ぶほうが筋が良い内容です。
そうした情報は Skills 側へ移したほうが、CLAUDE.md の役割がぶれません。
実際に使ってみると、情報量が多いファイルほど万能に見えて、肝心の基本ルールが薄まります。

3つ目は、大規模リポジトリでは階層ごとに分けることです。
モノレポや apps/ と packages/ で性格が分かれる構成では、ルートに全員向けの共通原則を書き、サブディレクトリにその領域だけの補足ルールを置く方法が有効です。
コミュニティの実践知でも、Claude はディレクトリ階層に沿って CLAUDE.md を読む運用が相性良いと整理されています。
見出し名も「Frontend rules」「API rules」のような英語ラベルより、apps/web 用ルール、packages/ui 用ルール のように対象をそのまま書いたほうが、どこ向けの追記か判別しやすくなります。

Claude Code のベストプラクティス - Claude Code Docs

環境設定から並列セッションでのスケーリングまで、Claude Code を最大限に活用するためのヒントとパターン。

code.claude.com

良い例/悪い例

良い CLAUDE.md は、読んだ瞬間に「このプロジェクトでどう振る舞うか」が決まります。
悪い CLAUDE.md は、情報量は多いのに行動へ落ちません。
ここは具体例で見ると差がはっきりします。

良い例は、短い文で判断基準が固定されている書き方です。

• プロジェクト概要が1〜2行で終わっている
• 技術スタックが実際の構成に沿って列挙されている
• pnpm dev / pnpm lint / pnpm test / pnpm format のように日常コマンドが明記されている
• 「型は厳格に保つ」「any を避ける」のように規約が具体的
• 「PR 前に lint と test を通す」のようにワークフローが短く定義されている
• 「DON’T: npm install を使う」「DO: pnpm add を使う」のように代替案まで書かれている
• 詳細は @README.md や @docs/architecture.md のように参照先が分離されている

悪い例は、親切そうに見えて常用には向かない書き方です。

• プロジェクトの背景説明が長く、今の開発対象が見えない
• 使わないコマンドまで全部並べてある
• 「きれいなコードを書く」「適切にテストする」のように抽象語が多い
• 禁止事項だけが並び、代わりに何をすべきか書いていない
• 設計資料や外部規約を全文貼り付けている
• 例外ケースや一時的な運用がそのまま残っている
• ルートの CLAUDE.md にモバイル、Web、バックエンド全部の細則を詰め込んでいる

初心者が最初に目指す形は、百科事典のような CLAUDE.md ではありません。
概要、スタック、コマンド、規約、ワークフロー、禁止事項と代替案、参照先が一目で追える状態です。
その枠を超えてきた内容は、別ファイルや Skills へ逃がしたほうが、プロジェクト全体の運用が安定します。

/init でスターター CLAUDE.md を作る手順

準備

前提として、ここでは最新版のClaude Codeを使います。
WinGetやHomebrewで入れている場合は自動更新されないので、/init が見当たらないときや新しい挙動に追従したいときは、先に更新しておくと話が早いです。

winget upgrade Anthropic.ClaudeCode
brew upgrade claude-code

スターターの CLAUDE.md は、最初から完璧な規約集を作る作業ではありません。
役割は、初心者が最初に必要な最小構成を素早く置くということです。
具体的には、プロジェクト概要、技術スタック、よく使うコマンド、コード規約、ワークフロー、禁止事項と代替案、参照先の7点が入っていれば出発点として十分です。
ここで長い歴史説明や設計思想の全文まで入れると、前のセクションで触れた通り、常時読むファイルとしては重くなります。
短く保つ理由は読みやすさだけではなく、更新が止まりにくく、古い運用が残りにくいからです。

あわせて、参照先の書き方も最初に決めておくと整えやすくなります。
詳細を本文へ貼り込むのではなく、@README.md、@docs/architecture.md、@docs/development.md のようにファイル参照で逃がす前提にすると、ルートの CLAUDE.md が説明書ではなく索引として機能します。

実行

作業はシンプルで、リポジトリ直下で claude を起動し、そのまま /init を実行するだけです。
/init は README や既存ドキュメントを読み取り、たたき台になる CLAUDE.md を生成してくれます。
まだコマンド体系に慣れていない段階なら、/help で使えるコマンド一覧を見ておくと全体像をつかみやすく、会話が散らかってきたら /clear で整理できます。
これらも /help から確認できます。

実際に触ってみると、/init は README の章見出しを広めに取り込むことが多く、初回生成の時点では少し説明過多になりがちです。
私自身は、生成直後に「残すべきルール」と「削るべき説明」をまとめて見分け、一気に短くしてから精度が安定しました。
とくに README 由来の背景説明やオンボーディング文は、そのまま残すより、プロジェクト固有の判断ルールだけに寄せたほうが効きます。
ここでのコツは、生成後に削る・直す前提で受け取るということです。
雛形は完成品ではなく、広めに拾うスキャナーのようなものだと捉えると扱いやすくなります。

初回の段階で入っていてほしい内容は、たとえば「このリポジトリは何を作るものか」「Next.jsTypeScriptpnpmのような技術スタック」「pnpm dev や pnpm test のような日常コマンド」。
次に「any を避ける、既存 ESLint 設定に従うといった規約」「ブランチ作業から lint・test・PR までの流れ」「禁止事項と、その代わりに使う方法」「詳細ドキュメントへの @ 参照」です。
この枠を外れる長文は、たいてい後で削る候補になります。

整形

生成後の見直しでは、文章のうまさより現場でそのまま使えるかを優先します。
最初に見るのは、コマンドが本当に今のリポジトリで動くかどうかです。
npm と書かれているのに実際は pnpm 運用だった、test スクリプト名が CI と違っていた、というズレは初回によく起きます。
次に、書かれているワークフローが現在の CI と一致しているかを確認します。
ローカルで pnpm lint を通す前提なのか、pnpm check まで必要なのかが曖昧だと、行動に落ちません。

禁止事項も、禁止だけで終わっていないかを見ます。
たとえば「本番 DB を直接変更しない」だけでは足りず、「マイグレーション経由で変更する」のような代替案まで置いておくと、Claude が次の一手を選べます。
ここが抜けると、ルールの形をしていても実務では効きません。

冗長な部分は、本文から消して参照へ寄せます。
README の要約を丸ごと残すより、@README.md や @docs/architecture.md のように分離したほうが、ルートの CLAUDE.md は締まります。
長い説明を抱え込むより、「この判断が必要になったらこのファイルを見る」と道筋だけ残すほうが運用が軽くなります。
私は /init 後のファイルを整えるとき、残す文はその場で判断に使う一文だけに絞り、説明は @import 的な参照に逃がす形へ寄せることが多いです。
そのほうが更新点も追いやすく、プロジェクト固有のルールが埋もれません。

用途別 CLAUDE.md テンプレート集

最初の1枚は、どの用途でも短く具体的に、理由を添える形にそろえておくと崩れにくくなります。
実務でもそのほうが更新が続きます。
逆に、背景説明や設計思想を詰め込み始めると、読むたびに必要な指示が埋もれます。
私自身、Next.js の案件で lint → typecheck → test の順を一文で固定してから、提案のブレが目に見えて減り、手戻りも減りました。

ここでは、初心者が最初に置くための最小構成に絞って、4種類の雛形を載せます。
どれも共通して、プロジェクト概要、技術スタック、よく使うコマンド、コード規約、ワークフロー、禁止事項と代替案、参照先を入れています。
詳細は @README.md や @docs/... に逃がし、ルートの CLAUDE.md は索引と判断ルールだけを持たせる前提です。

React/Next.js 用

フロントエンドの雛形では、日常コマンドの順番と PR 前の流れを先に固定すると効きます。
とくにNext.jsTypeScriptpnpmの組み合わせでは、lint と typecheck と test のどれを先に通すかが曖昧だと、Claude の提案も人間のレビューも揺れます。

# CLAUDE.md

## プロジェクト概要

- このリポジトリはNext.jsのWebアプリです。
- 主目的はUI実装、画面改修、フォーム改善、フロントエンドの不具合修正です。

## 技術スタック

- Next.js / React / TypeScript
- pnpm
- ESLint
- Vitest または Jest
- Playwright（ある場合のみ）

## よく使うコマンド

- 開発: `pnpm dev`
- lint: `pnpm lint`
- typecheck: `pnpm typecheck`
- test: `pnpm test`
- build: `pnpm build`

## コード規約

- TypeScript では `any` を安易に使わない。必要なら理由をコメントで残す。
- 既存の ESLint 設定と import 順を崩さない。
- UI は既存コンポーネントを優先して再利用する。
- サーバー/クライアント境界をまたぐ変更は影響範囲を明記する。

## ワークフロー

- 実装前に関連ファイルを読む。
- 変更後は `pnpm lint` → `pnpm typecheck` → `pnpm test` の順で確認する。
- PR では変更概要、影響範囲、確認手順を簡潔に書く。
- ビルドに影響する変更は `pnpm build` まで確認する。

## 禁止事項と代替案

- 禁止: デザイン差分を推測で埋める。
- 代替: `@docs/ui-guidelines.md` と既存画面を参照して合わせる。
- 禁止: 新しいUIライブラリを独断で追加する。
- 代替: 既存の依存で実装し、足りない場合だけ提案する。

## 参照先

- @README.md
- @docs/architecture.md
- @docs/ui-guidelines.md
- @docs/testing.md

• 使いどころ: Next.jsの管理画面、メディア、SaaS フロントエンドの初期設定に向いています。
• 編集ポイント: pnpm を npm や bun に置き換える、テストがないなら test を外す、Playwright の有無を実態に合わせる、PR ルールをチームのテンプレに寄せる、の4点から触ると整います。
• 削る候補: まだ E2E がない段階なら Playwright への言及、ビルド確認が不要な小規模案件なら pnpm build の行は削れます。

Node.js API 用

API では、エラーハンドリングと OpenAPI の基準を一言で決めておくと、実装のばらつきが減ります。
ExpressでもFastifyでも、レスポンス形式と例外の扱いが曖昧だと、Claude はファイルごとに違う流儀を持ち込みがちです。
CI のジョブ名まで書いておくと、ローカル確認とパイプラインの呼び方がそろいます。

# CLAUDE.md

## プロジェクト概要

- このリポジトリは Node.js ベースの API サービスです。
- 主な作業はエンドポイント追加、バリデーション、テスト、OpenAPI 更新です。

## 技術スタック

- Node.js
- TypeScript
- Express または Fastify
- OpenAPI
- Vitest または Jest

## よく使うコマンド

- 開発: `pnpm dev`
- lint: `pnpm lint`
- typecheck: `pnpm typecheck`
- test: `pnpm test`
- OpenAPI 検証: `pnpm openapi:lint`

## コード規約

- ルート、サービス、スキーマの責務を分ける。
- リクエスト/レスポンス型は明示する。
- エラーは共通ハンドラを通す。
- OpenAPI を実装と同時に更新する。理由は仕様と実装の差分を残さないため。

## ワークフロー

- 変更前に既存のエンドポイント実装を確認する。
- API を追加・変更したらテストと OpenAPI を更新する。
- ローカル確認後に `api-lint`、`api-test`、`api-build` の CI ジョブ名に合わせて説明を書く。

## 禁止事項と代替案

- 禁止: ハンドラ内で `try/catch` を乱立させる。
- 代替: 共通のエラーハンドリング規約に寄せる。
- 禁止: OpenAPI を後回しにする。
- 代替: 実装と同じPRで更新する。
- 禁止: 破壊的変更を黙って混ぜる。
- 代替: 互換性影響をPR説明に明記する。

## 参照先

- @README.md
- @docs/api-guidelines.md
- @docs/error-handling.md
- @openapi/openapi.yaml

• 使いどころ: BFF、社内 API、外部公開 API の共通土台として使えます。
• 編集ポイント: フレームワーク名をExpressかFastifyに固定する、OpenAPI の実ファイルパスを書く、CI ジョブ名を実際のワークフローに合わせる、エラー形式の名称をチーム規約に合わせる、といった修正が中心です。
• 削る候補: OpenAPI をまだ導入していない段階なら openapi:lint は外し、その代わり参照先だけ残す形でも始められます。

Python 用

Pythonはパッケージ開発とサービス開発で書くべき行が少し変わりますが、最初の骨格は共通です。
仮想環境の作法、テスト、静的解析、型方針を短く置くだけで、Claude が古い慣習と新しい慣習を混ぜにくくなります。
venvとpoetryのどちらを使うかも、最初に書いてあるだけで迷いが減ります。

# CLAUDE.md

## プロジェクト概要

- このリポジトリは Python のパッケージまたはサービスです。
- 主な作業は機能追加、バグ修正、テスト、型・Lint 修正です。

## 技術スタック

- Python
- venv または poetry
- pytest
- ruff
- mypy

## よく使うコマンド

- 仮想環境有効化: `source .venv/bin/activate`
- テスト: `pytest`
- lint: `ruff check .`
- format: `ruff format .`
- typecheck: `mypy .`

## コード規約

- 新規コードは型ヒントを付ける。理由は変更影響を追いやすくするため。
- 小さな関数を優先し、副作用を閉じ込める。
- 例外は握りつぶさず、呼び出し側で扱える形にする。
- 設定値は定数または設定モジュールに集約する。

## ワークフロー

- 変更前に対象モジュールと関連テストを読む。
- 変更後は `ruff check .`、`mypy .`、`pytest` を通す。
- パッケージ公開に関わる変更はバージョン影響を明記する。

## 禁止事項と代替案

- 禁止: 型なしの新規関数を増やす。
- 代替: 少なくとも引数と戻り値に型を付ける。
- 禁止: グローバル状態に依存した実装を増やす。
- 代替: 引数注入または設定クラスへ寄せる。
- 禁止: `print` ベースで恒久的なログを残す。
- 代替: 既存のロガーを使う。

## 参照先

- @README.md
- @docs/development.md
- @docs/testing.md
- @pyproject.toml

• 使いどころ: CLI ツール、バックエンド、社内バッチ、ライブラリの初期整備に向いています。
• 編集ポイント: venv運用なら有効化コマンドを残し、poetry運用なら poetry install や poetry run pytest に差し替える、mypy を導入していないなら型方針だけ残してコマンドを消す、が基本です。
• 削る候補: まだ型チェックを回していない古いプロジェクトでは mypy の行をいったん削り、まず pytest と ruff だけに寄せる形でも成立します。

ドキュメント執筆 用

非コード系のリポジトリでも CLAUDE.md は効きます。
記事制作、仕様書、ナレッジベースでは、トーン&マナー、見出し粒度、引用ルール、禁則を最初に決めておくと、文体の揺れを抑えられます。
コード規約の代わりに、文体規約と出典の扱いを置くイメージです。

# CLAUDE.md

## プロジェクト概要

- 主な作業は記事執筆、構成整理、リライト、要約、表記統一です。

## 技術スタック

- Markdown
- Docs-as-code 運用
- 必要に応じて Vale などの文書Lint

## よく使うコマンド

- プレビュー: `pnpm dev`
- 文書Lint: `pnpm lint:docs`
- ビルド: `pnpm build:docs`

## コード規約

- 文体は「です・ます調」で統一する。
- 見出しは1見出し1論点にする。
- 箇条書きは連続しすぎない。理由は流し読みで文脈が切れやすいため。
- 固有名詞・製品名は正式表記を優先する。

## ワークフロー

- 先に読者像と記事目的を確認する。
- 構成を作ってから本文を書く。
- 引用や数値は本文中に自然に埋め込む。

## 禁止事項と代替案

- 禁止: 断定の根拠がない言い切り。
- 代替: 事実、条件、根拠を同じ段落に置く。
- 禁止: 引用文の切り貼りだけで段落を作る。
- 代替: 自分の文で要点を再構成する。
- 禁止: 曖昧な宣伝表現や過度な誇張。
- 代替: 具体名、仕様、手順、比較軸で説明する。

## 参照先

- @README.md
- @docs/style-guide.md
- @docs/editorial-rules.md
- @docs/sources.md

• 使いどころ: オウンドメディア、技術ブログ、社内ドキュメント、仕様書管理に向いています。
• 編集ポイント: トーン&マナーの一文、見出し粒度の基準、引用と出典の書き方、禁則語と代替表現の4点を、その媒体の運用に合わせて差し替えるのが中心です。
• 削る候補: 文書Lint を導入していないならコマンド欄の lint:docs は削れます。プレビュー環境がない場合も、ビルドだけ残せば最小構成として十分です。

4つに共通しているのは、長く網羅することより、迷ったときの分岐だけを先に固定するということです。
CLAUDE.md は常設の総合マニュアルではなく、毎回最初に読む判断メモとして置くと効きます。
細かいレビュー観点や定型作業は、前述の通りSkillsやHooksへ分けたほうが、ルートの1枚が太りません。

Skills テンプレート集と作り方

SKILL.md の最小構成

Skillsは、特定タスクだけを切り出して再利用するための小さな作業手順書です。
基本形はシンプルで、SKILL.md の先頭に YAML フロントマターを書き、そこで name と description を定義します。
name は / で呼ぶコマンド名になり、description は自動呼び出しの判断材料になります。
本体は Markdown で、手順、観点、出力フォーマット、禁止事項を書く構成です。
この frontmatter が選択精度に直結する前提で説明されています。

最小構成なら、まずは次の形で十分です。

name: review-ts-security
description: TypeScriptの差分レビューでセキュリティ観点を最優先し、危険変更、認可漏れ、入力検証不足、秘密情報露出を重点確認する

# 目的
TypeScriptのPR差分をレビューし、重大な見落としを減らす。

# 入力

- git diff
- 変更対象ファイル
- 必要なら関連テスト

# 手順
1. まず差分を読み、変更の意図を要約する。
2. 破壊的変更、認可、入力検証、例外処理、ログ出力を確認する。
3. 既存実装との不整合があれば指摘する。
4. 指摘は「問題」「理由」「修正案」で返す。

# 出力形式

- 要約
- 指摘事項
- 追加で確認したい点

コピペで始めるなら、最初から凝った構成にしないほうが安定します。
私自身、description に「TypeScriptの差分レビューでセキュリティ観点を最優先」と明記したところ、一般論の長いレビューが減って、認可漏れや入力検証の見落としに寄るようになりました。
Skills は本文を長くするより、入り口の一文を研ぐほうが効く場面が多いです。

なお、旧 /.claude/commands/ は後方互換で動きますが、新規で増やすなら Skills に寄せる方針で考えるほうが整理しやすくなります。
レビュー、テスト生成、説明文作成のような再利用タスクは、1つずつ SKILL.md にまとめたほうが保守もしやすく、役割もぶれません。

個人スキルとプロジェクトスキルの置き場所

配置は、個人用と共有用を分けるのが基本です。
自分専用のレビュー観点や文体補助のようなスキルはホーム配下の ~/.claude/skills/ に置き、チーム全体で揃えたい手順はリポジトリ配下の .claude/skills/ に置きます。
Windows 環境では一般的にユーザープロファイル配下（例: C:\Users\\.claude\skills\、環境変数 %USERPROFILE% を基点にしたパス）に相当するディレクトリを置く運用例が多く報告されていますが、この表記はコミュニティの慣習例であり、公式ドキュメントが明示的に %USERPROFILE% を「公式表記」としているわけではありません。
記事では「POSIX 形式（~/.claude/skills/）を基本例として示し、Windows ではユーザープロファイル配下に同等の場所を使う実例がある」として扱うのが無難です。

プロジェクトスキルでは、チームで同名衝突を避ける意識も効きます。
たとえば review より review-node-api、pr-write-webapp のように対象を含めた名前にすると、個人用スキルと混ざったときでも迷いません。

テンプレA：レビュー

レビュー用スキルは、差分中心で読み、危険変更を先に拾う構成にしておくと安定します。
とくにReactNext.jsのように UI とサーバー処理が同居する構成では、見た目の変更に引っ張られて本質的な破壊変更を見落としやすいため、チェック順を固定しておく価値があります。

name: review-nextjs-pr
description: Next.jsとReactのPR差分をレビューし、破壊的変更、状態管理、認可、SSR境界、パフォーマンス劣化を重点確認する

# 目的
Next.js / React の差分レビューを、見た目ではなく変更影響から行う。

# 手順
1. 変更ファイルを pages, app, components, hooks, lib, api に分類する。
2. 差分の中心がUIか、データ取得か、認可かを先に特定する。
3. 次の観点で確認する。
   - 破壊的変更
   - props / state / hooks の整合性
   - Server Component と Client Component の境界
   - API呼び出しのエラーハンドリング
   - 認可漏れ、機密情報露出
   - 不要な再レンダリングや重い計算
4. 指摘は重大度ごとに整理する。

# 出力形式

- 変更要約
- Critical
- Major
- Minor
- 確認したい前提

使いどころは、フロントエンド中心の PR、設計変更を含む改修、表示崩れ以外の副作用が怖い変更です。
編集ポイントは、プロジェクトごとの注意点を 3〜5 個だけ追加するということです。
Next.jsなら Server Actions、キャッシュ、use client 境界、React単体なら props の肥大化や副作用フックの依存配列、TypeScriptなら型の後退を入れる、といった調整が効きます。
レビューの質を上げたいからといって観点を増やしすぎると、毎回同じ総花的な文章になりやすいので、優先順位を明示したほうが結果が安定します。

テンプレB：テスト生成

テスト生成スキルは、ユニットテストと結合テストを最初に切り分ける構成にすると、過剰なモックや役に立たない正常系の量産を防げます。
Node.js API やPythonの業務ロジックでは、この切り分けが曖昧だと、テストコードだけ増えて守れていない状態になりがちです。

name: generate-api-tests
description: Node.js APIまたはPythonバックエンドの変更に対して、ユニットテストと結合テストを切り分け、前提、モック、境界値、失敗系を含むテスト案を生成する

# 目的
変更差分に対応した、抜け漏れの少ないテスト案を作る。

# 手順
1. 対象コードの責務を整理する。
2. 純粋関数や分岐ロジックはユニットテスト候補にする。
3. DB, HTTP, queue, filesystem をまたぐ処理は結合テスト候補にする。
4. 各テストケースで次を明示する。
   - 前提データ
   - モック対象
   - 入力値
   - 期待結果
   - 境界値
   - 失敗系
5. 実装コードを出す前にケース一覧を先に出す。

# 出力形式

- テスト戦略
- ユニットテスト候補
- 結合テスト候補
- モック方針
- サンプル実装

使いどころは、ExpressやFastifyの API 追加、DjangoやFastAPIのロジック改修、入力検証や例外処理を触った変更です。
編集ポイントは、テストランナーに合わせるということです。
Node.jsなら vitest か jest、Pythonなら pytest 前提に書き換え、既存の fixture 命名や factory の有無を一文で添えると出力が揃います。
境界値の観点も、文字数、日付、空配列、null 相当、権限違反など、そのプロジェクトで事故になりやすいものへ寄せると役に立つテスト案になりやすくなります。

テンプレC：PR説明文

PR 説明文スキルは、変更要約だけで終わらせず、背景、テスト観点、影響範囲、リスクまで含めるとレビューの往復が減ります。
実装者には自明でも、レビュアーは差分だけでは意図を読み切れないことが多いためです。

name: write-pr-description
description: コード変更からPR説明文を作成し、変更要約、背景、テスト観点、影響範囲、リスク、未対応事項を簡潔に整理する

# 目的
レビュアーが短時間で変更意図と影響範囲を把握できるPR説明文を作る。

# 手順
1. 差分から何を変えたかを3行以内で要約する。
2. 背景として、なぜ変更が必要だったかを書く。
3. テスト観点を列挙する。
4. 影響範囲をUI、API、DB、運用、ドキュメントに分けて整理する。
5. リスクと未対応事項があれば分けて書く。

# 出力形式

{{related:claude-md-templates}}

{{related:hooks-and-tasks-examples}}

{{related:security-and-permissions-for-skills}}

## 概要
## 背景
## 変更内容
## テスト
## 影響範囲
## リスク・懸念点
## 補足

使いどころは、規模を問わずほぼすべての PR です。
特に複数レイヤーにまたがる変更や、見た目以上に影響が広い変更で効きます。
編集ポイントは、チームの PR テンプレートに寄せるということです。
GitHubのテンプレートに「スクリーンショット」「再現手順」「ロールバック方針」欄があるなら、その見出しを SKILL.md に合わせておくと流用しやすくなります。
長文を避けたい場合でも、「背景」と「リスク」を削らないほうがレビュー精度は落ちにくい設計です。

テンプレD：ドキュメント校正

非コード系でも Skills はよく効きます。
記事、仕様書、ナレッジベースの更新では、文法の直しより、用語統一や表記ゆれの除去のほうが成果につながることが多いです。
Markdown中心のリポジトリで、編集者ごとの癖を吸収したい場面に向いています。

name: proofread-docs-ja
description: 日本語ドキュメントを校正し、用語統一、表記ゆれ、冗長表現、出典表記、禁止語、見出し粒度を確認して修正案を返す

# 目的
ドキュメントの読み味と表記ルールを揃える。

# 手順
1. 固有名詞と製品名の表記を統一する。
2. 漢字とひらがなの揺れを確認する。
3. 同義語の混在を減らす。
4. 禁止語、誇張表現、曖昧表現を拾う。
5. 出典の置き方と見出し粒度を確認する。
6. 修正は原文を尊重し、書き換え理由も短く添える。

# 出力形式

- 総評
- 用語統一
- 表記ゆれ
- 言い換え提案
- 構成上の修正案

使いどころは、技術記事、プロダクトドキュメント、仕様書、社内 FAQ の整文です。
編集ポイントは、媒体固有のルールを本文に足すということです。
たとえば「API」は半角大文字で統一する、「ユーザー」と「利用者」はどちらかに寄せる、「禁止語」として断定しすぎる営業表現を避ける、リンク文言の書き方を固定する、などです。
ここは非コード系だからこそテンプレートの差が効きます。
文章のうまさを期待するより、直す観点を固定したほうが再現性が出ます。

descriptionを書き分ける

description は短い紹介文ではなく、Claude が「このスキルを使う場面か」を判断するためのルール文です。
対象言語、範囲、トリガー条件、期待出力を短く具体的に入れると精度が上がります。
逆に、「コードレビューを手伝う」「テストを作る」といった広すぎる説明だと、別のスキルとの違いが消えます。

悪い例は、次のようなものです。

description: コードレビューを行う
description: テストを作る
description: PRをいい感じにまとめる

これでは、何の技術スタックで、どんな入力に対し、何を返すのかが見えません。良い例は、対象と出力が入っています。

description: TypeScriptの差分レビューでセキュリティ観点を最優先し、認可漏れ、入力検証不足、秘密情報露出を指摘する
description: Node.js APIまたはPythonバックエンドの変更に対して、ユニットテストと結合テストを切り分けて生成する
description: コード差分からPR説明文を作成し、変更要約、背景、テスト、影響範囲、リスクを整理する
description: 日本語ドキュメントを校正し、用語統一、表記ゆれ、出典表記、禁止語を確認する

この書き分けをすると、自動呼び出しの精度が目に見えて変わります。
私の手元でも、レビュー系スキルに「TypeScript」「差分レビュー」「セキュリティ観点を最優先」と入れてから、設計論や命名論の一般論が減り、差分に即した指摘が増えました。
description は宣伝文ではなく検索キーに近いので、抽象語よりも技術名、作業対象、返してほしい形式を先に置くほうが噛み合います。

CLAUDE.md と Skills の設計ルール

このセクションで押さえたい設計原則はひとつです。
常時適用したいルールは CLAUDE.md、時々使う専門手順は Skills、毎回必ず起こしたい処理は Hooks、外部サービスやデータベース接続は MCP に置きます。
最初の構成では、この4つの役割を混ぜないだけで運用が安定します。

初心者が最初に作る CLAUDE.md は、前のテンプレートで見た最小セットだけで十分です。
つまり、プロジェクト概要、技術スタック、よく使うコマンド、コード規約、ワークフロー、禁止事項と代替案、参照先です。
ここに毎回読む価値がある共通知識だけを残し、長い手順書や特定作業専用の説明は外へ逃がします。
CLAUDE.md は短く人間可読に保つ方向が示されています。

長くしすぎない理由は明快です。
CLAUDE.md はセッション開始時に読まれるので、肥大化すると本当に効かせたい原則が埋もれます。
私も以前、CI のジョブ構成、失敗時の切り分け手順、運用上の例外まで CLAUDE.md に書いていましたが、会話の立ち上がりが重くなり、普段の実装相談でも CI の長文を毎回抱える形になりました。
そこから、普段必須の一文だけを CLAUDE.md に残し、CI 固有の詳細は @import で別ファイル参照に分ける形へ変えたところ、会話の見通しが戻りました。
大規模案件ほど CLAUDE.md をミニマルにして、専門知識は Skills や @import 側へ退避し、毎回の会話を軽く保つ設計が効きます。

判断フロー

迷ったときは、内容ではなく「いつ必要になるか」で置き場を決めるとぶれません。判断の順番は次のフローで足ります。

それは常に必要か？
├─ Yes → CLAUDE.md
└─ No → 決定論的に常時実行すべきか？
         ├─ Yes → Hooks
         └─ No → 外部接続が要るか？
                  ├─ Yes → MCP

それは常に必要か？ ├─ Yes → CLAUDE.md └─ No → 決定論的に常時実行すべきか？ ├─ Yes → Hooks └─ No → 外部接続が要るか？ ├─ Yes → MCP

それは常に必要か？
├─ Yes → CLAUDE.md
└─ No → 決定論的に常時実行すべきか？
         ├─ Yes → Hooks
         └─ No → 外部接続が要るか？
                  ├─ Yes → MCP
                  └─ No → Skills

比較の観点で見ると、CLAUDE.md は永続的なプロジェクト文脈と共通ルール、Skills は特定タスクの専門手順、MCP は外部ツール接続、Hooks は特定タイミングで必ず実行したい自動化です。
この主目的の違いをそのまま設計に落とすと、分割の良し悪しが見えます。

良い分割例は次のような形です。

• CLAUDE.md に「このサービスはNext.jsフロントエンドとGo API のモノレポ」「実行コマンドは pnpm dev と go test ./...」「API 変更時は OpenAPI と実装を同期」「直接 main へ push しない」を置く

悪い分割例も短く見ておくと判断しやすくなります。

• CLAUDE.md に PR テンプレート全文、CI 失敗時の全手順、障害対応手順まで詰め込む
• Skill に「このプロジェクトの概要」「採用技術」「禁止事項」を書く

とくに悪手になりやすいのは、CLAUDE.md を社内 wiki の縮小版にしてしまうということです。
毎回読むべき原則と、必要時だけ参照すればよい説明を分けないと、常駐メモリが膨らみます。
Skills 側も同じで、対象・入力・出力が曖昧な巨大 Skill を一本置くより、「PR 説明文」「レビュー」「テスト生成」のように役割で切ったほうが選択ノイズが減ります。
スキルが増えすぎると、ツール箱の中身が見えなくなる感覚に近く、必要なものを選ぶ前の迷いが増えます。

軽量化チェックリスト

大きな案件ほど、設計の巧拙は機能数ではなく「毎回読ませる量」で決まります。ここでは CLAUDE.md を軽く保つための確認項目を絞っておきます。

• CLAUDE.md に入っているのは、プロジェクト概要、技術スタック、よく使うコマンド、コード規約、ワークフロー、禁止事項と代替案、参照先の7要素までに収まっているか
• 頻度の低い長文手順を CLAUDE.md へ直書きしていないかどうか確認していますか。
• 特定作業専用の内容を Skill に逃がせるかどうか検討していますか。
• 毎回同じ条件で走る処理を Hooks に移せるかどうか検討していますか。
• 外部サービス接続の要件なのに手順書として抱え込んでいないかどうか確認していますか。
• 参照先の書き方が「どのファイルを見ればよいか」まで具体化されているかどうか確認していますか。
• CI、運用、障害対応の詳細を @import 先へ分離できているかどうか確認していますか。
• Skill 名と description が広すぎず、対象作業がひと目で分かるかどうか確認していますか。

参照先の書き方も軽量化に効きます。
「詳細はドキュメント参照」とだけ書くと、どこを見るべきか毎回探すことになります。
docs/api-guidelines.md、packages/web/README.md、docs/adr/ のように、場所まで書いておくと本文を増やさずに済みます。
共有ルールは短く、詳細は参照先へ寄せる形です。

この粒度にしておくと、最初に作るべき構成はシンプルです。
CLAUDE.md には全員共通の土台だけを載せ、頻出だが常時不要な作業は Skills、必須の自動処理は Hooks、外の世界と話す部分だけ MCP に分ける。
これだけで、導入直後の迷いの多くは消えます。

よくある失敗と改善方法

第三者MCPを無警戒で追加→信頼できるサーバーのみ、最小権限、レビュー体制を敷く

導入初期に起きがちな失敗は、役割分担の理解より先に「とにかく全部つなぐ」方向へ進んでしまうということです。
実務では、詰め込みすぎた CLAUDE.md、曖昧な Skills、掃除されない会話コンテキスト、増やしすぎた MCP が連鎖して、どこで精度が落ちているのか見えなくなります。
原因は個別でも、症状はまとめて出ます。
返答がぶれる、呼びたい Skill が出てこない、関係ない前提を引きずる、必要のないツール候補まで混ざる、といった形です。

まず多いのが、CLAUDE.md を親切心で長文化しすぎるケースです。
セッション開始時に毎回読む前提のファイルへ、PR テンプレート全文、CI 障害対応、運用手順、例外ルールまで一気に入れると、共通原則より細部が前に出ます。
こうなると「何を毎回守るべきか」が埋もれます。
短く保つ方針が示されている通り、ここは1〜2画面に収まる密度まで削るのが基準になります。
長い手順は要約し、詳細は別ファイルへ分け、必要なものだけ @import で参照する構成のほうが、判断の軸がぶれません。

禁止事項だけを書いて代替案を書かないのも、現場では失敗の定番です。
たとえば「main へ直接 push しない」「本番 DB を直接触らない」とだけ書くと、Claude は禁止は理解しても次の一手を持てません。
「機能開発はブランチを切って PR を作る」「検証はステージング DB かローカル seed を使う」まで並べると、禁止が行動ルールに変わります。
禁止はブレーキですが、代替案はハンドルです。
この2つがそろってはじめて提案の迷走が止まります。

Skills では description の曖昧さがボトルネックになります。
「レビューする」「コードを助ける」「開発を支援する」のような説明だと、何の場面で呼ぶべき Skill なのか判定材料が足りません。
description には、いつ使うのか、何を対象にするのか、どう返すのかを入れると効きます。
たとえば「TypeScript の PR 差分を読み、型安全性・命名・副作用の観点で懸念点と修正案を返す」のように具体化すると、発火条件と期待出力が一致します。
私自身、PRレビュー観点を Skill 化してからコード提案の揺れが減り、修正サイクルが1回減る感触がありました。
レビューの見る場所が固定されると、毎回ゼロから基準を思い出さなくて済むからです。

反対に、Skill を増やせば増やすほど良いわけでもありません。
名前や説明が似た Skill を大量に置くと、選択ノイズが増えます。
しかも旧 /.claude/commands/ に依存したまま運用すると、チーム内で「これはコマンド文化なのか Skill 文化なのか」が割れやすくなります。
後方互換で動いていても、今の整理軸は Skills です。
名称、説明、返却形式をそろえながら計画的に移していくほうが、呼び分けの混乱が減ります。
スキルで Claude を拡張するで説明されているように、現在は Skills を中心に設計したほうが全体の見通しを保てます。

精度低下を見落としやすいのが、会話コンテキストの汚れです。
前の相談で使った前提、途中で否定した方針、試しに投げた曖昧な依頼が残ったまま次の作業へ進むと、現在のタスクに不要な条件まで混ざります。
設計の切れ目、実装からレビューへの切り替え、別Issueへの移動といった節目では、/clear を挟んで会話を切るだけで挙動が整う場面が多いです。
コマンドを忘れたときはQuickstartにもある \/help で確認できます。
会話を引き継ぐこと自体が悪いのではなく、切るべき地点を決めずに延々と積み上げるのが問題です。

MCP まわりでは、第三者サーバーを無警戒で入れる運用がいちばん危険です。
便利そうだから、紹介記事で見たから、同僚が入れていたから、という理由だけで追加すると、権限も信頼境界も曖昧なまま外部接続が増えます。
MCP を使用して Claude Code をツールに接続するで前提になっている通り、つなぐ先は信頼できるサーバーに絞り、与える権限は最小限に留め、チームでレビューできる状態にしておくのが筋です。
誰が追加したか、何のために必要か、どの権限を持つかが説明できない MCP は、便利な拡張ではなく管理不能な入口になります。

加えて、MCP のツール定義そのものを入れすぎると、必要な作業に入る前から文脈を食います。
前述の通り、道具が増えるほど得になるわけではありません。
GitHub とNotionだけで足りるチームが、使わない DB やSlack連携まで常時抱えると、選択候補だけが増えて判断が鈍ります。
MCP は「接続できるものを全部載せる棚」ではなく、「今の運用で本当に触る外部面」を残す設計のほうが安定します。

このあたりを整えると、Claude の挙動は「賢いかどうか」より「設計が通っているかどうか」で変わると実感できます。
うまくいかないときほど個別の回答を責めたくなりますが、実際には CLAUDE.md が長すぎる、禁止だけで代替案がない、Skills の説明が曖昧、会話が汚れたまま、第三者 MCP を無造作に追加した、といった設計側のほころびが根にあります。
読ませる情報、呼ばせる条件、つなぐ範囲を絞るだけで、提案の筋が通りやすくなります。

安全に運用するためのチェックポイント

MCP追加時の最小権限チェック

MCP を足す場面では、「つながるか」より先に「何に触れられるか」を見るほうが事故を減らせます。
とくにGitHubNotionSlackのように業務情報が集まるサービスは、読み取りだけで足りるのか、書き込みまで必要なのか、特定のワークスペースやリポジトリに限定できるのかで危険度が変わります。
前述の通り、MCP は便利な拡張ですが、設定を1行追加するだけで信頼境界が広がるので、必要な操作を言葉で説明できない接続は残さないほうが運用が崩れません。

ここで押さえたい前提が、Anthropic は第三者の MCP サーバーの正確性や安全性を一つひとつ検証しているわけではない、という点です。
第三者サーバーは自己責任で扱う前提が読み取れます。
つまり、紹介記事で見かけた、社内の誰かが使っていた、といった理由だけでは足りません。
提供元が明確か、通信先が把握できるか、認証情報の保管方法が読めるかまで見て、信頼できるものだけ追加するのが基準になります。

未信頼のリポジトリを開くときに、私は作業を始める前に .mcp.json と .claude/ を先に読むようにしていますが、この順番にしてから意図しない外部サービスへの接続設定を事前に見つけて止められたことがありました。
コード本体より先に設定を見るだけで、見えない通信先や自動実行の気配がだいぶつかめます。

リモート MCP を運用するなら、トランスポートは HTTP を軸に考えるほうが設計を整理しやすいのが利点です。
ローカル実行よりも、ネットワークの到達性、TLS の終端位置、認証トークンをどこで注入するかを明文化しやすいからです。
サーバーを追加するときは、「社内ネットワークからどこまで到達できるか」「証明書の管理を誰が持つか」「キーやトークンを設定ファイルに直書きしていないか」まで含めて初めて運用設計になります。
接続先だけ決めて、認証と監査を後回しにすると、あとから切り分けも承認も難しくなります。

Hooksの安全実行チェック

Hooks は決定論的に動くぶん、再現性のある自動化に向いています。
ただし、実体は shell 実行です。
ここを見落とすと、「毎回同じ処理が走るから安心」と思っていたものが、毎回同じ破壊的操作を走らせる入口にもなります。
たとえば整形、lint、テストのような読み取り中心の処理と、ファイル削除、強制上書き、外部送信のような副作用を持つ処理は分けて考える必要があります。

安全側に倒すなら、Hooks にはまずガードを入れるのが定石です。
対象ディレクトリを限定する、想定外の引数なら終了する、変更対象を表示してから処理する、といった前置きがあるだけで、誤爆の範囲が絞れます。
加えて dry-run を用意しておくと、実運用に入れる前に「何が起きるか」をチームで確認できます。
決定論的という性質は便利ですが、それは安全を自動で担保してくれる意味ではありません。
むしろ挙動が固定されているからこそ、危ない処理も固定されます。

フックの中身が短い shell だからといって、レビューの目を通さずに済ませるのも避けたいところです。
数行の rm や curl のほうが、長いアプリケーションコードより直接的に事故へつながることがあります。
とくに標準入力や環境変数を受け取るフックは、何を前提に実行されるかをコメントで残しておかないと、書いた本人以外が読んだときに危険信号を拾えません。
保護のための Hook が、見えない副作用の温床になる構図は珍しくありません。

セキュリティレポートや脆弱性報告の窓口が整っているかも、導入判断の材料になります。
機能の多さより、問題が起きたときにどう報告され、どう修正されるかが見えるほうが、長く運用するときの安心材料になります。
Hooks はとくに小さく導入できるぶん、安易に増やすより、必要最小限のものを監査ログが残る形で回すほうが現場では扱いやすくなります。

設定ファイルのレビュー運用

設定ファイルはコードより軽く見られがちですが、Claude Code 周辺ではむしろ逆です。
.claude/ や .mcp.json は、モデルに何を読ませるか、どこへ接続するか、どの自動処理を走らせるかを決めるので、アプリケーション本体と同じ重さでレビュー対象に入れる必要があります。
実際、実装差分が小さくても設定差分が大きい変更は珍しくありません。

レビューでは、ファイルの存在だけでなく差分の意味を見ることが欠かせません。
新しい MCP サーバーが追加されていないか、既存サーバーの接続先や認証方式が変わっていないか、.claude/ 配下に新しい Hook や Skill が増えていないか、といった観点です。
設定変更がチーム承認なしで入ると、ある日から全員の Claude が別の外部面に触れ始める、という状態が起こります。
コードレビューが「関数の中身」を見る作業なら、設定レビューは「行動範囲の変更」を見る作業だと考えると整理しやすくなります。

承認フローも、アプリ本体とは少し分けておくと混乱が減ります。
たとえば機能追加の PR に設定変更が混ざる場合でも、.claude/ と .mcp.json の差分は別観点で見ます。
必要な接続か、権限が過剰でないか、ローカル専用にすべき内容が共有設定へ入っていないか、監査可能な形になっているか。
この視点がないと、動作確認だけ通って、運用上の穴が残ります。

設定ファイルをレビュー対象に含める文化が根づくと、Claude Code まわりの導入は「便利そうだから入れる」から「必要なものだけを説明可能な形で残す」へ変わります。
セキュリティ意識というと大げさに見えますが、実際に効くのはこうした地味な運用です。
コード、設定、外部接続を同じ変更管理の土台に乗せることで、不意な外部接続や見えない自動実行を早い段階で拾えるようになります。

CIへの組み込みの考え方

PRレビューとSkillsの連携の基本設計

CI にClaude Codeを組み込むとき、先に決めておきたいのは「毎回どこまで読ませるか」です。
ここを曖昧にしたまま PR レビューへつなぐと、CLAUDE.md も Skills も増えるほど文脈が膨らみ、レビューの焦点がぼけます。
設計の芯になるのは、PR の差分から対象ディレクトリを特定し、その階層で効く CLAUDE.md と、その変更内容に関係する Skills だけを読む流れです。
たとえば apps/web/ のフォーム改修なら、リポジトリ全体の運用メモや別プロダクト向け Skill まで渡すのではなく、apps/web/CLAUDE.md と PR レビュー用・UI 変更用・テスト観点用の Skill に絞る、という考え方です。

この分け方にしておくと、CLAUDE.md は「その場所で常に効いてほしい前提」、Skills は「今回の PR で呼び出したい観点」として役割がはっきりします。
前述の通り、CLAUDE.md は常時読む前提の情報、Skills はタスク単位の手順に向いています。
CI ではこの違いをそのまま活かし、全社共通ルールやモノレポ全域の説明を毎回投入するのではなく、差分に近い範囲へ寄せた文脈組み立てにしたほうが、レビューコメントの密度が安定します。

私自身、PR 時に Skills ベースのレビュー生成を試したとき、漠然と「精度が上がった」というより、指摘の観点が増えました。
たとえば API 変更の PR では互換性、テストの抜け、エラーハンドリング、ドキュメント反映といった切り口が別々に出るようになり、手元のレビュアーが見落としがちな論点を拾いやすくなりました。
自由文の長いプロンプトを毎回書くより、観点ごとに Skill 化したほうが、レビューの再現性も揃います。

このとき注意したいのは、「関連 Skills のみ」を本当に守るということです。
Skills は増やせますが、数を増やしすぎると選択ノイズも増えます。
description はコンテキスト予算の中で読み込まれる前提になっており、説明が長い Skill を大量に抱えると、自動選択の精度にも響きます。
Anthropicの Skills ドキュメントにある description 予算の考え方を踏まえると、CI 向けには「PR レビュー」「テスト観点」「マイグレーション確認」のように、差分種別と対応づけた少数の Skill へ寄せるほうが運用が軽くなります。
何でも Skill 化するより、レビューで繰り返し使う視点だけを残したほうが、モデルにとってもチームにとっても迷いが減ります。

将来的に運用を進めるなら、PR ラベルや変更ファイルのパターンで読む Skill を切り替える設計も相性がいいです。
schema/ を触ったら DB 変更用 Skill、docs/ を含んだらドキュメント整合性 Skill、.github/workflows/ を触ったら CI 設定確認 Skill、という具合です。
ここまでくると、レビュー本文を AI に丸投げするというより、チームが持っているレビュー観点を、CI 上で再利用可能な形にするという意味合いが強くなります。
この具体的なテンプレートや分岐設計は、後段の CI 統合を扱う記事で掘り下げる前提で、ここでは「対象を絞って読む」が骨格だと捉えると収まりがつきます。

Extend Claude with skills - Claude Code Docs

Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom commands and bundl

code.claude.com

CIでのCLAUDE.md/Skills検証の観点

PR レビューに使うなら、CLAUDE.md や SKILL.md 自体も CI で検証対象に入れておくと運用が崩れにくくなります。
発想としてはコードの lint に近く、内容の正誤をすべて機械判定するというより、体裁の乱れや明らかなアンチパターンを先に弾くイメージです。
たとえば CLAUDE.md なら必須セクションの有無、冗長な長文の混入、禁止語や曖昧な指示の検出、コマンド例の書式揺れなどが対象になります。
Skills 側では SKILL.md の frontmatter、description の長さ、役割が曖昧なタイトル、本文に手順がなく観点だけ並んでいる状態などを見ます。

SKILL.md が中心ファイルであり、frontmatter が選択精度に関わる前提で説明されています。
これを踏まえると、CI でまず見るべきなのは「ファイルが存在するか」ではなく、「選ばれるべき情報が短く明示されているか」です。
CLAUDE.md でも同じで、長い総論や背景説明より、コマンド、規約、禁止事項のような再利用される情報が前に出ているかを機械的に見たほうが運用に乗ります。

CLAUDE.md と Skills の CI 検証は、文章の採点ではなく「モデルが迷わない形になっているか」を見るものだと捉えると、ルールを作りすぎずに回せます。

実運用では、厳格な失敗条件と警告条件を分けておくと扱いやすくなります。
SKILL.md 不在、frontmatter 欠落、必須見出し不足のような構造エラーは失敗にし、description が長い、禁止語候補がある、1 ファイルに論点が詰まりすぎている、といったものは警告に留める構成です。
この線引きがあると、CI が毎回赤くなる状態を避けつつ、CLAUDE.md と Skills の品質を少しずつ揃えられます。
Hooks で決定論的なチェックを走らせ、PR 上では Skill ベースの観点レビューを重ねる形にすると、機械検査と文章レビューの役割がぶつかりません。

この周辺はテンプレート化の余地が大きく、リポジトリごとの差も出やすい領域です。
CI ジョブの組み方、検証ルールの粒度、自動レビューコメントの出し分けまで含めた実装論は、別記事で扱う CI 統合パターンのほうが整理して読めます。
ここでは、CLAUDE.md と Skills を「書いたら終わりの文書」ではなく、PR ごとに読み込まれ、CI で壊れていないか見張る運用資産として置くところまでを押さえておくと、導入後の手戻りが減ります。

既存リポジトリへの段階的導入

既存リポジトリに入れるときは、最初から理想形を目指すより、増やす前に削る順番で進めたほうが安定します。
私がうまくいった導入パターンも、まずClaude Codeの /init で雛形を作り、そのまま採用せずに「今のチームで毎回守っていることだけ残す」方針で短く削り、次にテンプレートを1つだけ選んで表現を揃え、そこから定型作業を1つだけ Skills に切り出す流れでした。
いきなり CLAUDE.md に全部を書き、同時に Skills も複数作ると、どこに何があるのか人間側が把握しきれなくなります。

導入の最初は「常設ルール」だけ残す

/init の直後は、プロジェクト説明、コマンド、規約、ワークフロー候補が一通り並ぶので、叩き台としては便利です。
ただし既存リポジトリでは、そこに昔の運用や一度しか使わない手順まで混ざることが多く、そのまま置くと密度が下がります。
先にやるべきなのは追加ではなく削減で、たとえば「開発サーバー起動」「テスト実行」「禁止している変更パターン」のように、毎回の作業で再利用されるものだけを残す形です。

この段階では、文書としてきれいに見せることより、モデルが迷わず読める状態に寄せるほうが効きます。
背景説明が長い CLAUDE.md より、短いコマンド一覧と明確な禁止事項がある CLAUDE.md のほうが、既存コードベースでは挙動が安定します。
前述の設計ルールと同じで、総論より反復作業に結びつく情報を前に出すのが基本です。

テンプレートは1つだけ採用して、差分を減らす

次にやることは、用途別テンプレートを複数混ぜることではなく、いちばん近い1枚をベースに決めるということです。
たとえば Web アプリ寄りなら Web アプリ用、ライブラリ中心ならライブラリ用、と起点をひとつに固定すると、あとから足す項目が「例外」だと分かります。
逆に複数テンプレートを継ぎ足すと、同じ意味の章が重複し、規約とワークフローの境目も曖昧になります。

既存リポジトリでは、この「どの型で管理するか」が曖昧なまま文章だけ増えることが多いです。
テンプレートを1つに絞るのは見た目の統一のためではなく、更新箇所を限定するためです。
変更が入ったときに、CLAUDE.md のどこを直すべきかがすぐ分かる構造なら、文書のメンテナンスが開発フローの邪魔になりません。

Skills は定型作業を1つだけ切り出す

CLAUDE.md を短くしたあとで、繰り返し発生する作業を1つだけ Skills に移します。
最初の題材として相性がいいのは、PR レビュー、テスト観点の洗い出し、変更説明の下書きのように、入力と出力の型が決まっている仕事です。
私がモノレポへ段階導入したときも、まずレビュー観点だけを Skills 化したところ、実装ルールやディレクトリ構成に触れずに始められたので、チーム内の摩擦がほとんど出ませんでした。

ここで欲張って「レビューも、調査も、実装計画も」と一気に増やすと、選択肢が増えたぶん運用のノイズも増えます。
スキルは数が増えるほど便利になるというより、似た役割のものが並ぶほど判別コストが上がります。
実務では、少数のスキルに絞ったほうが、必要な場面で呼ばれる確率も保ちやすいと感じます。
SKILL.md の frontmatter と description が選択精度に関わる前提で整理されていますが、導入初期はこの恩恵を活かすためにも、対象を一つに絞るのが無難です。
該当する詳細は各参照先のドキュメントを確認してください。

モノレポはディレクトリ単位で CLAUDE.md を分ける

大規模モノレポでは、ルートに全部書く構成は長続きしません。
基本パターンは、リポジトリ直下の CLAUDE.md には共通原則だけを書き、apps/web/CLAUDE.md、packages/ui/CLAUDE.md、infra/CLAUDE.md のようにサブディレクトリごとへ分割し、共通部分は @import で参照する形です。
Claude は上位階層の CLAUDE.md を読み、サブディレクトリの CLAUDE.md を必要に応じて読むので、モノレポではこの階層設計がそのまま運用設計になります。

たとえばルート側には「使用言語」「共通禁止事項」「レビュー時の基本方針」だけを置き、apps/web 側にはフロントエンド固有のコマンド、infra 側には Terraform やデプロイ周りの制約を書く、という分担です。
さらに、共通のコマンド集やレビュー原則を docs/claude/common-rules.md のような別ファイルへ逃がして @import しておくと、同じ文章を複数箇所で持たずに済みます。
モノレポで先にこれを決めておくと、あとからサービスが増えても、追記先が自然に定まります。

移行時の落とし穴は「残骸」と「重複」と「盛りすぎ」

移行で詰まりやすい点は、派手な失敗よりも小さな重複です。
旧来の .claude/commands や社内 Wiki の手順を残したまま Skills を足すと、どちらが現行手順なのか曖昧になります。
後方互換があるから残してよい、ではなく、役割が移ったなら片方を消すほうが事故は減ります。

二重管理も典型的です。
同じコマンド一覧を README、CLAUDE.md、オンボーディング資料の3か所に持つと、最初に古くなるのはだいたい CLAUDE.md ではなく周辺資料ですが、読む側からは差が見えません。
運用上の正本を一つに決め、残りはそこを参照する形に寄せたほうが崩れません。

規約の盛り込みすぎにも注意が要ります。
導入直後は「せっかく書くなら全部残したい」となりがちですが、例外だらけの細則を詰めるほど、守るべき核が埋もれます。
禁止事項は少数に絞り、例外運用は本当に頻出するものだけ残す、という引き算のほうが既存リポジトリでは機能します。

運用コストと料金の目安

平均コストと90%タイル

平均コストと90%タイル

運用コストの目安としては、公式ドキュメントの記載や運用報告を踏まえると、開発者1人あたりの目安は「1日で数ドル〜十数ドル」のレンジとなるケースが多いです。
料金プランの詳細や最新情報は公式 Pricing を参照してください。
また、機能や導入形態（対話型、API、Team/Enterprise）によりコスト構造が変わるため、導入前には Claude Code の公式ドキュメントで確認することを推奨します。
この記事の料金表記は 2026年3月18日時点の情報に基づいています。
私の手元でも、コストが気になり始めたタイミングで /stats を眺めるようにしてから、重いやり取りの傾向が見えました。
そこで CLAUDE.md の説明が長くなっていた箇所を削り、毎回読ませなくていい補足を整理したところ、日次コストが少し下がる感触がありました。
モデルそのものの料金だけでなく、常時読み込ませる文脈の量が積み上がるという意味で、設計の粗さがそのまま請求の重さに出る場面があります。
公式の料金情報は Anthropic の Pricing ページで必ず確認してください。
また、MCP や Claude Code の導入手順・仕様は公式ドキュメントを参照のうえ、導入前に最新版を確認することを推奨します。
この記事の料金表記は 2026年3月18日時点の情報に基づいています。

API を選ぶかどうかは、Claude を「対話相手」として使うのか、「開発フローの部品」として組み込むのかで見方が変わります。
CI や社内ツール、独自の自動化に組み込むなら API の柔軟性は魅力ですが、そのぶん呼び出し回数と入出力の積み上がりがそのままコストになります。
日常的なコード読解やレビュー補助が中心なら、まず対話型の利用で運用を固め、そのあと必要な部分だけ API に逃がすほうが、費用の見通しを立てやすくなります。

チーム導入では、プランの高低よりも無駄なコンテキストを常態化させていないかのほうが効いてきます。
前のセクションで触れた通り、CLAUDE.md に共通ルールを書き込みすぎたり、似た Skills を増やしたりすると、使い方の粗さがコストにも選択精度にも跳ね返ります。
料金表だけでなく、運用設計そのものを見直す前提でプランを選ぶと、後からの修正が少なくなります。

コスト最適化チェックリスト

コスト最適化は、モデルを変える前に何が無駄に読まれ、何が無駄に起動しているかを観察するところから始まります。
実務で効きやすい点を絞ると、見直しポイントは次の3つに集約されます。

• /cost や /stats で利用状況を見て、どの操作ややり取りが重いかを把握する
• CLAUDE.md の冗長な説明を削り、常時読ませる情報を短く保つ
• Skills の description を具体化して、関係ない場面での誤起動を減らす

この3つは別々の話に見えて、実際にはつながっています。
/stats で重いセッションを見返すと、長い指示文や、毎回不要なのに読まれている CLAUDE.md の記述が見つかることがあります。
そこを削るだけで、1回ごとの差は小さくても、日次では積み上がり方が変わります。
私自身も、CLAUDE.md に残していた補足説明を「本当に毎回必要な原則」だけに絞ってから、コストだけでなく応答の焦点も整いました。

Skills 側では、description が曖昧だと「使わなくていい場面でも呼ばれる」状態になりがちです。
たとえば PR レビュー用の Skill なのに、説明文が広すぎて一般的なコード相談にも反応するような書き方だと、選択ノイズが増えます。
必要な場面を短く明示した description に寄せると、誤起動が減り、結果として余計なやり取りも減ります。

まとめと次のアクション

次のアクション

常時読ませる土台は CLAUDE.md、専門手順は Skills、必ず通したい処理は Hooks、外部接続は MCP と分けて考えると、設計の迷いが減ります。
/init は完成形ではなく出発点として受け取り、不要な行を削って育てる前提で扱うと収まりがよくなります。
実際、まずはテンプレを1つだけ入れる運用から始めたチームでは、翌週にはレビューの観点がそろい始めました。

• Claude を起動して /init を実行する
• 不要な行を削り、テンプレを1つだけ編集して使い始める
• 定型作業を Skills 化し、MCP は信頼できるサーバーだけに絞る

深掘りは各詳細記事へ