Claude Codeのrules・Skills設計術｜失敗しない書き方とチーム展開の進め方
Claude Codeを業務で使い込むと、必ずぶつかるのがCLAUDE.md（rules）とSkillsの設計です。「とりあえずCLAUDE.mdに何でも書いておけば従ってくれる」と思いきや、書きすぎるとむしろ精度が落ちます。Skillsも、命名と粒度を間違えると呼ばれずに無視される――。設計を誤るとAIが劣化したように見えるのが、このレイヤーの厄介さです。
本記事では、CLAUDE.mdとSkillsの役割分担、失敗しない書き方、社内展開（チームでの共有）の進め方を整理します。前提となる「rulesとskillsの基本機能」についてはClaude Codeで業務ツールを自作｜skills・rulesの活用法もあわせてご参照ください。
大前提: CLAUDE.mdとSkillsは役割が違う
もっとも見落とされがちな前提が、両者の読み込まれるタイミングが違うという点です。
- CLAUDE.md（rules）: すべてのセッションで毎回読み込まれる。プロジェクト全体に広く適用するルールを書く場所
- Skills: 起動時はメタデータ（名前と説明）だけが事前ロードされ、Claudeが「関連する」と判断したときに本文（SKILL.md）と追加ファイルが読まれる
この違いが意味するのは、CLAUDE.mdに書いた内容は常にコンテキストを消費するということです。逆にSkillsは「必要なときだけ呼ばれる」ため、量が増えても普段のコンテキストを圧迫しません。
原則1: CLAUDE.mdは「広く・薄く」
指示数の限界は150〜200
研究によれば、フロンティアLLMでも一度に安定して扱える指示数の実務的な上限は150〜200程度とされています。これを超えると、書いた指示が守られないことが増え、挙動がブレ始めます（出典: Zenn）。
「念のため書いておく」を続けると、CLAUDE.mdは数百行の巨大なルール集に育ち、結果的にClaudeが守れない状態になります。「これがないとプロジェクト全体が壊れる」レベルの指示だけに絞るのが正解です。
CLAUDE.mdに書くべきこと・書かないこと
判断基準は「全セッションで本当に必要か」です。
- 書く: コーディング規約、必須の禁止事項（force pushしない等）、デプロイ手順の前提、機密扱いのルール、プロジェクトの基本構造
- 書かない: 特定機能の実装手順、業界知識、特定タスク向けのワークフロー、たまに使う細かいテクニック
後者はSkillsに分離するのが正解です。
WHY/WHAT/HOWで構造化する
CLAUDE.mdは1セクションに詰め込むのではなく、次の3層で整理すると守られやすくなります。
- WHY: プロジェクトの目的・背景（短く）
- WHAT: 何を作っているか・何をしてはいけないか
- HOW: コーディング規約・作業手順
LLMは毎回「初見」でコードベースに向き合う前提なので、この3層を最初に渡しておくことで、その後の判断の足場になります。
原則2: Skillsは「狭く・深く・命名で呼ばれる」
1スキル1責務
Skillsは1つの責務に絞るのが基本です。「フロントエンド全般」のような広いスキルを作ると、Claudeはどの場面で呼べばよいか判断できません。「Reactのフォームバリデーション設計」のように具体的なシナリオに紐づく粒度にします。
SKILL.mdは500行以下
Anthropic公式のベストプラクティスでは、SKILL.mdは500行以下に保つことが推奨されています。長くなる場合は、SKILL.md本体を要約版にして、詳細は外部スクリプトや別ファイルに切り出します。
Claudeは関連するときにスキル本文を読み、必要に応じて追加ファイルだけを読み込めるため、500行以下を保つことで読み込み時のコンテキスト消費を抑えられます。
命名と説明文が呼ばれるかを決める
もっとも盲点なのが、起動時に事前ロードされるのはメタデータ（name と description）だけという点です。Claudeはこのメタデータを見て「いまこのスキルを呼ぶべきか」を判断します。
つまり、説明文（description）が曖昧だと、本文がどれだけ良くてもスキルは呼ばれません。「いつ・どんな場面で・何のために使うスキルか」を15〜30字で表現するのが、設計の最重要ポイントです。
原則3: スクリプトはコンテキスト消費なしで実行できる
Claude Code公式のもう一つのベストプラクティスが、SKILL.mdの中で参照する外部スクリプトは、本文を読まずに実行できる形にすることです。
- 定型的な処理はShellスクリプトやPythonスクリプトに切り出す
- SKILL.mdには「このスクリプトを実行する」と書くだけ
- スクリプト本文はClaudeが読まなくても実行可能
これにより、複雑な処理を含むスキルでも、コンテキストを大きく消費せずに使えます。とくに毎回同じ処理を行うチェッカー類・デプロイ補助・データ整形は、スクリプト化が効きます。
典型的な失敗パターンと修正案
失敗1: 何でもCLAUDE.mdに書く
「過去に発生したミスを全部CLAUDE.mdに追記する」運用にしていると、半年で数百行の巨大なルール集になります。古くなったルール・特定タスク用の指示・たまにしか発生しない例外対応はSkillsに分離します。
失敗2: スキル名が抽象的すぎる
「frontend-helper」「backend-utils」のような汎用名のスキルは、Claudeがいつ呼べばよいか判断できず、結局呼ばれません。「react-form-validation」「postgres-migration-checker」のように、具体的シナリオを命名に含めます。
失敗3: スキル本文に背景説明を詰め込む
SKILL.md本文に「このスキルが必要になった経緯」「過去の失敗」を書きすぎると、500行をすぐ超えます。本文は手順とチェックリストに集中し、背景は最小限に留めます。
失敗4: ルールに矛盾を含める
「テスト駆動で書く」と「即動かして確認する」のように、運用が分かれているルールが両方残っていると、Claudeはどちらを優先すべきか迷います。定期的にルールを通読して矛盾を整理する習慣が必要です。
チームで使う: 社内展開のステップ
ステップ1: 個人で使えるrules集を作る
最初は1人の開発者が自分のCLAUDE.mdとSkillsを整えて、効果を実感する段階です。この時点で「自分にとって本当に効くルールは何か」がわかってきます。
ステップ2: チームで共通のCLAUDE.mdを版管理
個人で効いたルールのうち、プロジェクト共通で必要なものをチームのCLAUDE.mdに集約します。Gitで版管理し、変更はPRレビューを通す運用にすると、属人化を防げます。
ステップ3: 共通Skillsライブラリを整備
チーム全員で使うスキル（コードレビュー観点・テスト設計・デプロイ手順など）を、共通リポジトリに集約します。各メンバーがそのリポジトリを取り込めば、AI支援の質が個人差なく揃います。
ステップ4: 月次でルール棚卸し
ルールは放っておくと膨らみ続けます。月次で30分、ルールを通読して古いものを削る・矛盾を解消する会を入れるだけで、長期的な精度が大きく変わります。
「劣化」を感じたらまずCLAUDE.mdを疑う
Claude Codeが最近賢さを失ったように感じるとき、まず疑うべきはモデルではなくCLAUDE.mdの肥大化です。指示数が150〜200を超えていれば、それだけで体感は劣化します。詳しくはClaude Codeが劣化したと感じた時の対処法もご参照ください。
まとめ: ルールは資産、肥大化は負債
Claude CodeのCLAUDE.mdとSkillsは、適切に設計すれば業務知識を蓄積する資産になります。一方、放置すればAIの精度を落とす負債に変わります。本記事のポイントを整理します。
- CLAUDE.mdは全セッションで毎回読まれる。広く・薄く・150〜200指示以内
- Skillsはメタデータだけ事前ロード。命名と説明文の精度が呼ばれるかを決める
- SKILL.mdは500行以下、定型処理はスクリプトに切り出してコンテキスト節約
- WHY/WHAT/HOWの3層でCLAUDE.mdを構造化
- チーム展開はGitで版管理し、月次で棚卸しする
株式会社Sei San Seiでは、中小企業向けにClaude Code を含む生成AIの社内活用設計と、CLAUDE.md / Skills の設計レビューも含めた運用ご支援を行っています。「現場で使われるrulesを整備したい」「チーム全員のAI支援品質を揃えたい」といった課題があれば、お気軽にご相談ください。