CLAUDE.mdをそろそろ見直す時期かも ── Claude 5世代向けの最適化手順・スキル・プロジェクト種類別の例

要点

• Anthropic は 2026年7月24日のブログで、Claude Opus 5 / Fable 5 向けに Claude Code のシステムプロンプトを 80% 以上削り、社内コーディング評価で性能低下が測定できなかったと公表しました。
• 理由は「制約の多くは最悪のケース回避のために入れたもので、今のモデルは周囲の文脈から判断できる」からです。
• 私たちの CLAUDE.md にも同じことが言えます。旧世代向けに積んだ禁止ルール・手順の全文・使い方の例示は、判断の邪魔になったり、互いに矛盾したりしている可能性があります。
• この記事は、既存の CLAUDE.md を見直す7ステップ、それを実行可能なワークフローに組み替えたスキルのコード、全体用1つとプロジェクト種類別6つの CLAUDE.md 例を載せます。
• 削ってはいけないものもあります。不可逆な操作の確認ゲートと、リポジトリを見ても分からない罠です。

はじめに

対象は、CLAUDE.md が 100 行を超えて「何を書いたか自分でも把握できない」と感じている方です。Claude Code の CLAUDE.md・スキル・メモリの存在は知っている前提で書きます。

前提環境は次の通りです。

• Claude Code v2.1.206 以降（/doctor に CLAUDE.md の見直し提案が入った版）
• Claude 5 世代のモデル（Claude Opus 5、Claude Fable 5 など）

筆者の CLAUDE.md も数百行に膨らんでいます。この記事は自分向けの手順書でもあります。

なぜ今、見直すのか

Anthropic 自身が 80% 以上削った

Anthropic の Thariq Shihipar 氏は、ブログ記事「The new rules of context engineering for Claude 5 generation models」で、Claude Code のシステムプロンプトを 80% 以上削除しても性能低下が測定できなかったと述べています。中心的な知見は、「システムプロンプト・CLAUDE.md・スキルのすべてで Claude を過度に制約していた」ことでした。

矛盾した指示が同居していた

社内の利用記録を点検すると、1つのリクエストの中に「必要に応じてドキュメントを残す」と「コメントを追加してはならない」が同居している例が見つかったそうです。Claude は意図をくみ取って正しい答えに至れますが、矛盾を調停する分だけ余計な検討が要ります。

長く育てた CLAUDE.md でも同じことが起きます。数か月前の「テストは必ず先に書く」と、先週足した「小さな修正ではテストを省略してよい」が、両方生きている状態です。

制約は「最悪のケース」のためだった

制約は元々、ファイル削除のような最悪のケースを避けるために入れたものでした。Anthropic は、その多くは今では削除でき、モデルの判断に任せられるとしています。加えて、メモリ・アーティファクト・スキルが揃った今、ガイダンスの置き場所として CLAUDE.md に頼る必要も薄れました。

Claude 5 世代で変わった6つの常識

ブログ記事が挙げる6つの変化を、CLAUDE.md への含意とあわせて整理します。

#	従来	現在	CLAUDE.md への含意
1	ルールを与える（「コメントを書かない」）	判断に任せる（「周囲のコードのコメント密度・命名・イディオムに合わせる」）	禁止の列挙を判断基準に書き直す
2	ツールの使い方を例で示す	インタフェース設計で伝える（状態を pending / in_progress / completed の列挙型にするだけで使い方が伝わる）	長い使い方の例を減らし、ツール側の設計に寄せる
3	全部を最初に一括で渡す	段階的開示。手順はスキルへ移し、必要な場面で呼ぶ	手順書はスキルへ。CLAUDE.md には参照だけ残す
4	同じ指示を繰り返す	重複を排除し、ツールの使い方はツールの説明文にだけ書く	同じ内容の行を1つにまとめる
5	# ホットキーで CLAUDE.md に手書きメモ	自動メモリ	個人的な覚え書きを CLAUDE.md から外す
6	計画や仕様を Markdown で渡す	HTML アーティファクト・テスト・移植元コード・ルーブリックを参照させる	仕様の本文を貼らず、参照先を示す

例として、旧来の TodoWrite ツールの説明は約 9,100 文字ありましたが、短いインタフェース定義に置き換わっています（ブログ掲載図より）。

これらの知見は /doctor にも組み込まれています。公式ドキュメントによると、v2.1.206 以降の /doctor は、チェックイン済みの CLAUDE.md からコードベースを見れば分かる記述を削る提案と、常時読み込みの手順をスキルや下位 CLAUDE.md へ移す提案を行います。診断を先に示し、変更前に確認を求めます。ターミナルの claude doctor は読み取り専用のインストール診断で、この提案は行いません。

見直しの7ステップ

各ステップは独立しています。時間がなければ手順1〜3だけでも効果があります。

手順1. 棚卸しする

量と構成を把握します。

wc -l -m CLAUDE.md CLAUDE.local.md .claude/CLAUDE.md ~/.claude/CLAUDE.md 2>/dev/null
grep -nE '^#{1,3} ' CLAUDE.md

これは主要4ファイルの概算です。下位ディレクトリの CLAUDE.md や .claude/rules/ まで含めた棚卸しは、後述のスキルに同梱したスクリプトが行います。

公式ドキュメントの目安は、1ファイル 200 行未満です。長いほど指示への追従が落ちます。

セッション内では /context でコンテキストの内訳と最適化提案を見て、/doctor のトリム提案を控えます。この時点では読むだけにし、削る判断は以降の手順で行います。

見出しごとに次の5分類を付けます。

分類	例	扱い
A. 目的	何のサービスか	短く残す
B. 環境の注意点	npm install に --legacy-peer-deps が要る	残す（最も価値が高い）
C. 禁止ルール	「コメントを書くな」「必ず〜せよ」	判断基準に書き直す。不可逆操作のガードだけ残す
D. 手順・チェックリスト	レビュー手順、リリース手順	スキルへ移す
E. 覚え書き・仕様の本文	「前回こう決めた」「API 仕様はこう」	メモリ・参照ファイルへ移す

手順2. 自明な記述を削る

ブログ記事の指針は「軽量に保ち、トークンの大半はコードベース内の注意点に充てる。ファイルシステムを見れば分かることは書かない」です。/doctor も同じ線引きで、ディレクトリ構成・依存一覧・アーキテクチャ概要を削り、罠・理由・ツール既定と異なる規約を残します。

削る候補は、技術スタックの列挙、ディレクトリ構成、リンターが強制している規約です。残すのは、「legacy/ は移行中で触らない」のような背景と、ツールの罠です。

手順3. 禁止ルールを判断基準に書き直す

ブログ記事の実例をそのまま借ります。

Before

- 複数段落の docstring や複数行のコメントブロックを決して書かない。
- 既定ではコメントを書かない。

After

- 周囲のコードと同じ読み味になるように書く。コメントの密度・命名・イディオムを周囲に合わせる。

Before は、公開 API のようにコメントが必要な場所でも黙ってしまいます。After なら既存コードに合わせる判断をモデルに委ねられます。

禁止形で残すのは、少なくとも次の2種類です。不可逆な操作（削除、履歴の書き換え、本番反映、外部送信、課金）と、組織・契約上の制約です。Anthropic も「多くは削除できる」と言っており、「すべて」とは言っていません。

ただし CLAUDE.md の指示は行動を誘導するもので、強制ではありません。確実に止めたい操作は、CLAUDE.md に書くことに加えて、permission 設定の deny や PreToolUse フックで機械的に遮断します。

手順4. 手順をスキルへ移す

ブログ記事は、検証手順は検証スキルに切り出し、CLAUDE.md からは参照だけ残す形を勧めています。スキルは .claude/skills/<名前>/SKILL.md に置き、description に発火条件を書きます。

.claude/skills/verify-before-done/SKILL.md

---
name: verify-before-done
description: コード変更を完了と報告する前の検証手順。実装が一区切りついて「完了」を宣言する直前に使う。
---

# 完了前の検証手順

1. 変更したパッケージのテストを実行し、出力を確認する。
2. lint と型チェックを実行する。
3. 画面や API に触れる変更なら、実際に起動して1回は操作する。
4. 実行ログを報告に含める。「たぶん動く」で完了にしない。

CLAUDE.md（抜粋）

## 検証
完了を報告する前に `verify-before-done` スキルを通す。

特定のディレクトリだけの規約は、スキルより paths 付きの .claude/rules/*.md が向いています。Claude が一致するファイルを読んだときだけ読み込まれます。下位ディレクトリの CLAUDE.md も同様に、Claude がそのディレクトリ内のファイルを読んだときに読み込まれます。

.claude/rules/api-design.md

---
paths:
  - "src/app/api/**/*.ts"
---

# API ハンドラの規約
- エラー応答は `{ code, message }` の形に揃える。
- 入力はスキーマで検証してから処理に渡す。

手順5. 覚え書きと仕様を分ける

個人的な好みや一時的な学びは、自動メモリに任せます。ただし自動メモリは Claude が保存対象を選び、保存先はマシンローカルです。チームの正式な決定事項は仕様書や ADR に残し、毎回読ませたいものだけ CLAUDE.md に置きます。

仕様の本文は別ファイルにし、タスクのプロンプトで @path/to/file と指定して渡します。CLAUDE.md の中に @path を書くと起動時にインポートされ、削減になりません。参照はコードの形（テスト、移植元）が最も忠実で、デザインは HTML モックが文章やスクリーンショットより良い結果になります。

手順6. 矛盾を洗い出す

grep -rniE "絶対|必ず|禁止|決して|しないこと|never|always|must not|do not|don't" \
  CLAUDE.md CLAUDE.local.md .claude/CLAUDE.md \
  .claude/rules .claude/skills ~/.claude/CLAUDE.md 2>/dev/null

ヒットした行で、同じ対象に肯定と否定が両方あるか、同じ内容が2か所以上にあるか、「必ず」に実は例外があるかを見ます。下位ディレクトリの CLAUDE.md まで含めたいときは、後述のスクリプトが同じ条件で検出します。

手順7. 効果を確認する

見直し前後で同じタスクを1〜2本流し、出力の品質、以前のルールで押さえていた挙動の再発、/context の使用量を比べます。Anthropic の「性能低下なし」は Claude Code 本体の結果です。自分の CLAUDE.md で同じことが言えるかは、1リポジトリで小さく試して確かめます。

7ステップをスキルにする

手順は毎回追うより、スキルにしておくほうが楽です。/claudemd-tune と打つと棚卸しレポートが自動生成され、Claude が分類と提案書の作成まで進めます。

スキル側の番号は本文と少し違います。矛盾の洗い出し（本文の手順6）はレポートに含まれるため手順1に統合し、空いた手順6を「提案書を書いて止まる」に充てています。承認を挟む位置を手順として明示するためです。

.claude/skills/claudemd-tune/
├── SKILL.md
└── scripts/
    └── inventory.sh

SKILL.md

.claude/skills/claudemd-tune/SKILL.md

---
name: claudemd-tune
description: 既存の CLAUDE.md を Claude 5 世代向けに見直す7ステップのワークフロー。棚卸し（矛盾・重複の検出を含む）→自明な記述の削除→禁止ルールの判断基準化→手順のスキル化→メモリ/参照の分離→提案書の作成→承認後の反映と効果確認を進める。CLAUDE.md は提案書の承認後にだけ書き換える。手動起動専用（/claudemd-tune [プロジェクトルート]）。
argument-hint: "[プロジェクトルート]"
disable-model-invocation: true
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/inventory.sh *)
---

# CLAUDE.md の見直し（Claude 5 世代向け）

対象ルート: `$ARGUMENTS`（空ならカレントディレクトリ）

## 棚卸しレポート（自動生成）

!`${CLAUDE_SKILL_DIR}/scripts/inventory.sh "$ARGUMENTS"`

## 進め方

CLAUDE.md は本人の承認なしに書き換えない。まず提案書を作り、承認を受けてから反映する。

### 手順1. 棚卸しを読み、矛盾と重複を洗い出す

上のレポートの「見出し一覧」を、次の分類で埋める。

- A: リポジトリの目的
- B: 環境固有の注意点（見ても分からない罠）
- C: 禁止ルール・行動規範
- D: 手順・チェックリスト
- E: 覚え書き・仕様の本文

「強い語を含む行」と「重複している行」はこの時点で目を通し、矛盾している組（例: ドキュメントを残す／コメント禁止）に印を付ける。

### 手順2. 自明な記述を削除候補にする

A・B 以外で、設定ファイルや `ls` で分かる内容（技術スタックの列挙、ディレクトリ構成、リンターが強制している規約）は削除候補にする。
B（罠・理由・ツール既定と異なる規約）は残す。

### 手順3. C を判断基準に書き直す

各 C 行について「なぜ入れたか」を推定し、書き直し案を作る。
禁止形のまま残すのは、不可逆な操作（削除・履歴の書き換え・本番反映・外部送信・課金）と、組織や契約上の制約だけ。

### 手順4. D を移す

手順・チェックリストは `.claude/skills/<名前>/SKILL.md` へ、特定ディレクトリだけの規約は `paths` 付きの `.claude/rules/*.md` へ移す案を作る。
CLAUDE.md 側には「いつ何を使うか」の1行だけ残す。

### 手順5. E を分ける

個人的な好み・一時的な学びは自動メモリに任せる（削除候補）。
チームの正式な決定事項は仕様書や ADR へ。仕様の本文は別ファイルにし、タスク時に `@path` で渡す（CLAUDE.md 内の `@path` は起動時インポートになるので削減にならない）。

### 手順6. 提案書を書く

以下の形式で `claudemd-tune-proposal.md` をプロジェクトルートに書き出し、ここで一度止まって承認を待つ。

```markdown
# CLAUDE.md 見直し提案

## 削除（自明・重複）
| ファイル:行 | 現在の記述 | 理由 |

## 書き直し（ルール → 判断基準）
| ファイル:行 | 現在 | 提案 |

## 移動（スキル / rules / 参照ファイル / メモリ）
| ファイル:行 | 現在 | 移動先 | 移動後に CLAUDE.md に残す1行 |

## 残す（禁止形のまま）
| ファイル:行 | 記述 | 残す理由 |

## 矛盾の組
| 行A | 行B | どちらを正とするか（本人判断） |

## 見直し後の CLAUDE.md（全文案）
```

### 手順7. 承認後の反映と確認

承認された項目だけを反映する。反映後に次を実行して報告する。

1. `inventory.sh` を再実行し、行数と強い語の件数を前後で比較する。
2. `/context` の CLAUDE.md 使用量を控える。
3. 直近のタスクを1本、見直し後の CLAUDE.md で流し、以前のルールで押さえていた挙動が再発しないかを確認する。

## 補助ファイル

- `scripts/inventory.sh`: 棚卸しレポート生成（読み取り専用）。手動で実行する場合は `bash .claude/skills/claudemd-tune/scripts/inventory.sh <ルート>`。

フロントマターと本文の要点は4つです。

• disable-model-invocation: true: Claude が勝手に起動しないようにし、/claudemd-tune と打ったときだけ動かします。この設定では description は自動発火の判断には使われず、一覧表示の説明として働きます。
• スラッシュコマンド名は name ではなくディレクトリ名 claudemd-tune/ から決まります。name は一覧上の表示名です。
• allowed-tools: 同梱スクリプトを、このスキルを呼び出したターンの間だけ事前承認します。ツールの制限ではなく、指定しないツールは通常の permission 設定に従います。
• 本文の !`...` 行: Claude がスキルを読む前にコマンドが実行され、出力がその場に差し込まれます（動的コンテキスト注入）。引数は空白を含むパスに備えて "$ARGUMENTS" と引用しています。

scripts/inventory.sh

読み取り専用で、CLAUDE.md は書き換えません。プロジェクトルート・.claude/CLAUDE.md・CLAUDE.local.md・~/.claude/CLAUDE.md・下位ディレクトリの CLAUDE.md（深さ制限なし。node_modules と .git は除外）を集め、サイズ、見出し一覧、強い語を含む行、重複行、rules と skills の本数を Markdown で出します。macOS（bash 3.2）と Debian 12 の Docker コンテナ（bash 5.2）で、空白を含むパスと引数なしの両方の実行を確認しています。

scripts/inventory.sh の全文（約110行）

.claude/skills/claudemd-tune/scripts/inventory.sh

#!/usr/bin/env bash
# CLAUDE.md の棚卸しレポートを Markdown で標準出力に出す（読み取り専用。ファイルは変更しない）。
# 使い方: inventory.sh [プロジェクトルート]   省略時はカレントディレクトリ
set -u

root="${1:-.}"
root="${root%/}"
limit_lines=200

# 1. 対象ファイルを集める（起動時読込＋下位ディレクトリのオンデマンド読込）
candidates=$(
  for f in "$root/CLAUDE.md" "$root/CLAUDE.local.md" "$root/.claude/CLAUDE.md" "$HOME/.claude/CLAUDE.md"; do
    [ -f "$f" ] && printf '%s\n' "$f"
  done
  find "$root" -mindepth 2 \
    \( -name node_modules -o -name .git -o -name dist -o -name build \) -prune -o \
    -type f \( -name CLAUDE.md -o -name CLAUDE.local.md \) -print 2>/dev/null
)
files=$(printf '%s\n' "$candidates" | awk 'NF' | sort -u)

if [ -z "$files" ]; then
  echo "CLAUDE.md が見つかりませんでした（探索先: $root と ~/.claude）。"
  exit 0
fi

echo "# CLAUDE.md 棚卸しレポート"
echo
echo "対象ルート: \`$root\`  目安: 1ファイル ${limit_lines} 行未満"
echo

# 2. サイズ一覧
echo "## 1. ファイルとサイズ"
echo
echo "| ファイル | 行数 | 文字数 | 目安 |"
echo "|---|---:|---:|---|"
total_lines=0
while IFS= read -r f; do
  lines=$(wc -l < "$f" | tr -d ' ')
  chars=$(wc -m < "$f" | tr -d ' ')
  total_lines=$((total_lines + lines))
  if [ "$lines" -ge "$limit_lines" ]; then mark="超過"; else mark="範囲内"; fi
  echo "| \`$f\` | $lines | $chars | $mark |"
done <<< "$files"
echo
echo "合計 ${total_lines} 行"
echo

# 3. 見出し一覧（分類 A〜E を書き込む欄つき）
echo "## 2. 見出し一覧（分類欄: A 目的 / B 環境の注意点 / C 禁止ルール / D 手順 / E 覚え書き・仕様）"
echo
while IFS= read -r f; do
  echo "### \`$f\`"
  echo
  echo "| 行 | 見出し | 分類 |"
  echo "|---:|---|---|"
  grep -nE '^#{1,3} ' "$f" | sed -E 's/^([0-9]+):(#{1,3}) (.*)$/| \1 | \2 \3 |  |/'
  echo
done <<< "$files"

# 4. 強い語（禁止・必ず系）の行
echo "## 3. 強い語を含む行（矛盾・重複・例外の点検対象）"
echo
pattern='絶対|必ず|禁止|決して|しないこと|never|always|must not|do not|don'\''t'
hits=0
while IFS= read -r f; do
  while IFS= read -r line; do
    [ -n "$line" ] || continue
    echo "- \`$f:${line%%:*}\` ${line#*:}"
    hits=$((hits + 1))
  done < <(grep -niE "$pattern" "$f" | sed -E 's/^([0-9]+):[[:space:]]*/\1:/')
done <<< "$files"
[ "$hits" -eq 0 ] && echo "- 該当なし"
echo
echo "合計 ${hits} 行"
echo

# 5. 重複行（複数ファイル・複数箇所に同じ文がある）
echo "## 4. 重複している行（20文字以上・見出し以外）"
echo
dups=$(
  while IFS= read -r f; do
    grep -vE '^\s*(#|$)' "$f"
  done <<< "$files" | sed -E 's/^[[:space:]]+//; s/^[-*] +//; s/[[:space:]]+$//' | awk 'length($0) >= 20' | sort | uniq -d
)
if [ -n "$dups" ]; then
  printf '%s\n' "$dups" | sed 's/^/- /'
else
  echo "- 該当なし"
fi
echo

# 6. 周辺の読込物
echo "## 5. 常時読込・オンデマンド読込の周辺ファイル"
echo
rules_dir="$root/.claude/rules"
skills_dir="$root/.claude/skills"
if [ -d "$rules_dir" ]; then
  total_rules=$(find "$rules_dir" -name '*.md' -type f | wc -l | tr -d ' ')
  scoped_rules=$(find "$rules_dir" -name '*.md' -type f -exec grep -lE '^paths:' {} + 2>/dev/null | wc -l | tr -d ' ')
  echo "- .claude/rules: ${total_rules} 本（うち paths 限定 ${scoped_rules} 本。残りは起動時に常時読込）"
else
  echo "- .claude/rules: なし"
fi
if [ -d "$skills_dir" ]; then
  echo "- .claude/skills: $(find "$skills_dir" -name SKILL.md -type f | wc -l | tr -d ' ') 本（本文は呼び出し時のみ読込）"
else
  echo "- .claude/skills: なし"
fi
echo
echo "次の手順: このレポートの見出しごとに分類 A〜E を埋め、C は判断基準への書き直し、D はスキルまたは paths 限定ルールへの移動、E はメモリまたは参照ファイルへの移動を検討してください。"

使い方

chmod +x .claude/skills/claudemd-tune/scripts/inventory.sh
# スクリプト単体で棚卸しだけ見る
bash .claude/skills/claudemd-tune/scripts/inventory.sh .

セッション内で /claudemd-tune を実行すると、Claude は提案書 claudemd-tune-proposal.md を書き出したところで止まります。承認した項目だけを反映させます。削る判断は人が握る作りです。

Claude 5 世代向けの CLAUDE.md 例

見直しの到達点として、最初から Claude 5 世代向けに書いた例を載せます。全体用1つと、プロジェクトの種類別に6つです。種類別の6つは「環境の注意点」「判断の基準」「実行前に確認を取る操作」「必要時に読むもの」の4節に揃え、40 行未満に収めています。すべて架空の例です。

全体用（~/.claude/CLAUDE.md）

全プロジェクト共通の作業スタイルだけを書きます。

~/.claude/CLAUDE.md

# 作業スタイル

## 応答
- 日本語で、結論から書きます。前置きと段階報告は省きます。
- 事実と推測を分けます。確認できていないことは「未確認」と明示します。

## 判断の基準
- 既存のコードや文書の流儀に合わせます。私の好みより、そのリポジトリの一貫性を優先します。
- 迷ったら、選択肢と推奨を1つ示して止まります。

## 実行前に確認を取る操作
- 削除、履歴の書き換え、本番環境への反映、外部への送信・公開、課金が発生する操作。
- 上記以外は確認なしで進めて構いません。

## 覚え書き
- 私の好みや繰り返し出す訂正は自動メモリに任せます。ここには書きません。

開発プロジェクト（Web アプリケーション）

CLAUDE.md

# 予約管理サービス

会員向けの予約管理 Web アプリです。構成・依存・コマンドは設定ファイルを見てください。以下は見ても分からない点だけです。

## 環境の注意点
- 依存のインストールは peer 依存の競合があるため、`--legacy-peer-deps` が必要です。
- テスト用 DB はポート 5433 で待ち受けています。本番と同じ 5432 ではありません。
- `src/legacy/` は旧システムからの移行中です。新規コードは `src/app/` 側に書いてください。

## 判断の基準
- 周囲のコードと同じ読み味になるように書きます。コメントの密度・命名・イディオムは既存コードに合わせてください。
- API のエラー応答は `{ code, message }` の形に揃えています。
- 日時は DB には UTC で保存し、表示層でタイムゾーンを当てます。

## 実行前に確認を取る操作
- `prisma/migrations/` の既存ファイルは編集しません。変更は新しいマイグレーションで行います。
- `contracts/` 配下は外部システムとの合意事項です。変更が必要なら人に確認してください。
- 本番反映、履歴を書き換える強制 push、データ削除は実行前に確認を取ってください。

## 必要時に読むもの
- 完了報告の前に `verify-before-done` スキルを通してください。
- リリース作業は `release-runbook` スキルに従ってください。
- API ハンドラの規約は `.claude/rules/api-design.md` にあり、該当ファイルを読むと自動で読み込まれます。

ライブラリ・公開パッケージ

外部の利用者がいるため、互換性と公開手順が罠になります。

CLAUDE.md

# 日付フォーマットライブラリ

npm で公開している日付フォーマット用ライブラリです。API 一覧と使い方は README と `docs/` を見てください。

## 環境の注意点
- ビルドは ESM と CommonJS の両方を出します。片方だけ通っても他方が壊れることがあるので、両方のテストを実行してください。
- Node.js の対応範囲は `package.json` の `engines` が正です。それより新しい構文を使わないでください。

## 判断の基準
- 公開 API は後方互換を最優先します。破壊的変更が必要なら、まず非推奨の警告を入れる案を出してください。
- 公開関数には利用者向けの docstring を書きます。内部関数は周囲に合わせます。
- 依存の追加は、標準ライブラリで代替できないかを先に検討してください。

## 実行前に確認を取る操作
- `CHANGELOG.md` の既存エントリは書き換えません。追記のみです。
- バージョン番号の変更、タグの作成、`npm publish` は人が行います。提案までで止めてください。

## 必要時に読むもの
- リリース手順は `release` スキルにあります。
- 互換性の判断に迷ったら `docs/compat-policy.md` を読んでください。

調査・リサーチプロジェクト

成果物が調査メモとレポートのリポジトリです。出典の扱いが中心になります。

CLAUDE.md

# 市場調査リポジトリ

競合や技術動向の調査メモとレポートを蓄積しています。ディレクトリの意味は `README.md` を見てください。

## 環境の注意点
- `raw/` は取得したままの一次資料です。編集しないでください。要約や抜粋は `notes/` に書きます。
- 過去の調査は `notes/` に日付付きで残っています。同じテーマを調べる前に既存メモを検索してください。

## 判断の基準
- 事実には出典（URL と取得日）を添えます。出典が示せないことは「推測」と明記します。
- 一次情報（公式発表・原文・データ）を二次情報（記事・まとめ）より優先します。二次情報しかない場合はその旨を書きます。
- 数値には取得日と単位を添えます。

## 実行前に確認を取る操作
- `reports/` 配下の完成レポートは上書きせず、新しい版を作ってください。
- 外部への共有（メール・公開）は人が行います。

## 必要時に読むもの
- 調査メモの書式は `research-note` スキルにあります。
- レポートの構成は `report-template` スキルにあります。

執筆プロジェクト（技術記事・ブログ）

文体の一貫性と、公開の不可逆性が関心事です。

CLAUDE.md

# 技術記事リポジトリ

技術ブログの記事原稿を `posts/` 配下の Markdown で管理しています。公開の仕組みと画像の置き場所は `README.md` を見てください。

## 環境の注意点
- フロントマターは公開ツールが読みます。`title` と `tags` 以外のキーを足すと公開時に失敗します。
- 画像はローカルパスでは表示されません。`README.md` の画像ホスティング手順に従ってください。

## 判断の基準
- 文体はです・ます調で統一し、既存記事の語調に合わせてください。
- 断定は事実に限り、意見には前提を添えます。他者や他技術には、向く場面と向かない場面を並べる書き方をします。
- 出典は原典（公式ブログ・公式ドキュメント）を示します。二次記事は出典にしません。

## 実行前に確認を取る操作
- 公開済み記事の本文変更は、変更点を示して確認を取ってから行います。
- 記事の公開・更新の実行は人が行います。原稿を整えるところまでで止めてください。

## 必要時に読むもの
- 執筆前と公開前のチェックは `article-review` スキルにあります。
- 避ける表現の一覧は `docs/phrasing.md` にあります。文章を書くときに読んでください。

インフラ・運用プロジェクト（IaC）

本番環境に直結するため、確認ゲートが最も厚くなります。

CLAUDE.md

# インフラ構成リポジトリ

本番・ステージング環境の構成をコードで管理しています。ツールと環境の一覧は `README.md` を見てください。

## 環境の注意点
- 環境ごとの変数は `envs/<環境名>/` にあります。本番は `envs/prod/` です。ファイル名が似ているので、編集前にパスを確認してください。
- このリポジトリの `plan` は実環境に変更を適用しません。`apply` は実環境を変えます。外部コマンドや副作用のあるデータ取得を含む構成では、`plan` でも事前に確認してください。
- 秘密情報は外部のシークレット管理から注入されます。リポジトリ内に値を書かないでください。

## 判断の基準
- 変更は最小の差分にとどめます。関係のないリソースの整形や名前変更は、別の変更に分けます。
- 新しいリソースは、既存リソースと同じタグ付けとネーミングを踏襲します。

## 実行前に確認を取る操作
- `apply` や `destroy` に相当する、実環境を変える操作すべて。
- 本番環境の変数ファイルの編集。
- ファイアウォール・認可・ネットワーク境界に関わる変更。

## 必要時に読むもの
- 変更を出す前の手順は `infra-change` スキルにあります。plan の読み方と、確認を取るときの提示形式が書いてあります。
- 障害時の手順は `incident` スキルにあります。

AI エージェント運用プロジェクト

スキルやサブエージェントの定義を育てるリポジトリです。CLAUDE.md が最も膨らみやすい種類なので、担当表や手順は外に出し、判断の骨子だけを置きます。

CLAUDE.md

# 作業アシスタント

Claude Code 上で動く自分用の作業アシスタントの定義を管理しています。担当者（サブエージェント）の一覧と役割は `.claude/agents/` の各定義を見てください。ここには繰り返しません。

## 環境の注意点
- スキル・エージェント定義・フックは同じリポジトリにあり、1つ直すと他に波及します。変更したら参照している側を検索してください。
- 委譲先の最終メッセージが空で返ることがあります。重要な委譲は成果物のファイル保存を指示し、返り値ではなくファイルを正としてください。

## 判断の基準
- 委譲するか自分で行うかは、成果物の最終形で決めます。調べて書くなら調査担当から執筆担当へ渡します。
- 完了は、検証の実行ログか実物の確認が添えられている状態です。テストが緑というだけで完了にしません。
- 同じ失敗が2回目なら、その場で直すだけでなく `learnings/` に1行残します。

## 実行前に確認を取る操作
- 外部への送信・公開、コミットとプッシュ、削除、課金が発生する操作。
- 定義ファイル（CLAUDE.md・エージェント定義・フック）の削除。

## 必要時に読むもの
- 委譲の作法は `delegate` スキルに、コードのレビュー体制は `multi-review` スキルにあります。
- 担当者の追加・削除は `hr` スキルの手順に従ってください。

6つの例に共通する骨組み

節	書くこと	書かないこと
冒頭	何のリポジトリか。構成はどこを見れば分かるか	技術スタックやディレクトリの列挙
環境の注意点	見ても分からない罠と回避策	設定ファイルに書いてあること
判断の基準	何に合わせるか、何を優先するか	「〜するな」の列挙
実行前に確認を取る操作	不可逆な操作と、組織・契約上の境界	スタイルに関する禁止
必要時に読むもの	どの場面でどのスキル・ルールを使うか	手順の本文

種類で変わるのは、「環境の注意点」の中身と「実行前に確認を取る操作」の厚みです。インフラのように失敗が不可逆な領域では確認ゲートが増え、調査や執筆では出典と公開の記述が中心になります。

やりすぎないための注意点

• チーム共有の CLAUDE.md では、ある人の「自明」は別の人の自明ではありません。削る前に、その行が入った経緯を確認してください。
• 旧世代のモデル（Claude 4 系など）も併用している場合、判断に任せる書き方では従来ほど従わない可能性があります。同じ指示で両世代の挙動を比べてから削るか、Claude 5 世代に統一してから見直すのが無難です（筆者の提案です）。
• 安全に関わる禁止事項（本番反映・削除・外部送信・課金）は残します。制約は「最悪のケースを避けるため」に入れたものであり、最悪のケース自体はなくなっていません。ただし CLAUDE.md は誘導であって強制ではないので、確実に止めたい操作は permission 設定や PreToolUse フックでも防いでください。

「7ステップ」「5分類」「例の骨組み」は、ブログ記事を私なりに手順化した解釈です。自分の環境に合わせて組み替えてください。

まとめ

Anthropic は Claude 5 世代向けに Claude Code のシステムプロンプトを 80% 以上削り、性能低下は測定できませんでした。背景にあるのは「制約の多くは最悪のケース回避のためで、今のモデルは文脈から判断できる」という認識です。

私たちの CLAUDE.md も同じです。残すのは「見ても分からない罠」と「不可逆な操作のガード」、移すのは「手順」「覚え書き」「仕様の本文」、削るのは「設定ファイルで分かること」と「矛盾する禁止ルール」です。

まず /context と /doctor で現状を測り、/claudemd-tune スキルで棚卸しから始めてください。1リポジトリで小さく試すのが安全です。

参考

• Thariq Shihipar, "The new rules of context engineering for Claude 5 generation models", Anthropic, 2026年7月24日
  https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models
• Claude Code 公式ドキュメント「How Claude remembers your project」（CLAUDE.md・自動メモリ・.claude/rules/）
  https://code.claude.com/docs/en/memory
• Claude Code 公式ドキュメント「Extend Claude with skills」（SKILL.md のフロントマター・動的コンテキスト注入）
  https://code.claude.com/docs/en/skills
• Claude Code 公式ドキュメント「Slash commands」（/context・/doctor・/memory）
  https://code.claude.com/docs/en/commands