記事

CLAUDE.mdをチームのナレッジベースとして育てる方法

CLAUDE.mdを単なるAI向け設定ファイルから、チームの意思決定・失敗事例・暗黙ルールを残すナレッジベースへ育てる運用法を整理します。更新ルール・分割設計・検索性・肥大化対策・AGENTS.mdとの併用までを具体例つきで扱います。

Claude CodeのCLAUDE.mdは、当初「AIに守らせるルール集」として始まることが多いものですが、半年も運用すると**「過去の意思決定の根拠」「ハマったポイント」「やめた手段とその理由」**が溜まってきます。これを単なる設定ファイルではなく、チームのナレッジベースとして育てると、新人オンボーディングからAIの精度向上まで一気にレバレッジが効きます。この記事では、CLAUDE.mdを腐らせず・肥大化させず・検索可能な形で育てる運用法を整理します。

結論：CLAUDE.mdは「ルール集 → 意思決定ログ → ナレッジベース」と育てる

CLAUDE.mdは段階的に役割を増やしていけます。

ルール集（最初の月）：禁止事項・確認コマンド・命名規則
意思決定ログ（半年〜）：「なぜこのライブラリを選んだか」「なぜこのパターンをやめたか」
ナレッジベース（1年〜）：失敗事例・ハマりポイント・暗黙ルールの形式知化

ただし1ファイルで全部を抱えると肥大化して読まれなくなるので、@インポートと.claude/rules/分割で構造化します。CLAUDE.mdの基本テンプレは「CLAUDE.mdテンプレート完全版」を参照してください。

ナレッジベースとして書くべき4カテゴリ

通常のルール集に追加して書くと効くのは次の4カテゴリです。

1. 過去の意思決定の根拠（Decision Log）

「なぜこの技術を選んだか」を残します。AIだけでなく、3か月後の自分や新人メンバーも読み返すセクションです。

## Decisions

- **状態管理**: Zustand を採用（2026-02）。Redux Toolkit との比較で、コード量とボイラープレートの少なさを優先。
- **ORM**: Prisma → Drizzle に移行中（2026-04）。マイグレーション速度とエッジ環境対応のため。
- **CSS**: Tailwind CSS を採用。コンポーネントライブラリは社内 UI Kit を優先。

Decisionsセクションは、AIに「勝手に別ライブラリを提案させない」効果も持ちます。

2. やめた手段とその理由（Anti-patterns）

「過去に試して問題が起きた」記録を残します。同じ穴に落ちないようにするためのセクションです。

## Anti-patterns

- ❌ `src/utils/` ディレクトリへの新規追加は禁止。ドメイン単位で `src/domain/<bounded-context>/` に置く
- ❌ React Server Component から `'use client'` コンポーネントを直接 import しない（ストリーミングの妨げになる）
- ❌ DB マイグレーションは本番に即適用しない。`shadow database` で検証後に PR を分ける

❌絵文字や明示的なNEVERを冒頭に置くと、AIが読み流しにくくなります。

3. ハマりポイント集（Gotchas）

「2時間溶かしたバグの教訓」を1〜2行で残します。

## Gotchas

- Next.js の `revalidatePath` はサーバーアクション内でしか効かない（Route Handler では `revalidateTag` を使う）
- `pnpm` のワークスペース内で `npm install` を実行するとロックが壊れる
- `pg` の `idle_in_transaction_session_timeout` が未設定だと、長時間接続でロック競合が起きる

4. 暗黙ルールの形式知化

「先輩エンジニアが暗に守っていること」を言語化します。新人がCLAUDE.mdを読むだけで真似できる状態にします。

## Implicit Rules

- ログのレベル分け: ユーザー操作起因のエラーは `warn`、システム異常は `error`。`info` を本番でつけない
- 新しいページ追加時はメタデータ（OG画像・title・description）を必ず設定する
- 環境変数を増やすときは README とデプロイドキュメントの両方を更新する

肥大化対策：`.claude/rules/`への分割

CLAUDE.md本体は200行以内に保つのが公式の推奨です。ナレッジベースを盛り込むと早晩超えるので、テーマごとに.claude/rules/へ分割します。

.claude/
└─ rules/
   ├─ decisions.md      # Decision Log
   ├─ anti-patterns.md  # やめた手段
   ├─ gotchas.md        # ハマりポイント
   ├─ frontend.md       # フロントエンド固有
   ├─ backend.md        # バックエンド固有
   └─ db.md             # DB・マイグレーション

CLAUDE.md側には@インポートで読み込みます。

# CLAUDE.md

## プロジェクト概要
（省略）

## 共通ルール
- @.claude/rules/decisions.md
- @.claude/rules/anti-patterns.md
- @.claude/rules/gotchas.md

## レイヤー別ルール
- フロントエンドを触るとき: @.claude/rules/frontend.md
- バックエンドを触るとき: @.claude/rules/backend.md
- DB・マイグレーション: @.claude/rules/db.md

pathsフロントマターを使うと「特定ディレクトリを触るときだけロードする」設定にもできます。コンテキスト消費を抑える設計の全体像は「Claude Codeに必要な情報だけ渡すコンテキスト設計」で扱っています。

検索性を上げる5つの工夫

見出しを動詞で揃える：### Choose ...、### Avoid ...、### Always ...のように検索しやすく
日付タグ：(2026-04)のようにつけ、古い意思決定の見直しを促す
キーワードを冒頭に置く：「ORMはDrizzle」「ロギングはPino」のように、@参照やrg検索でヒットしやすくする
シンボル統一：✅採用／❌不採用／⚠️注意のように記号で意味づけ
DOSとDON’Tペア：「やる」「やらない」を対で並べると新人が短時間で読める

更新ルール：誰がどのタイミングで書くか

ナレッジベース化が失敗する最大の理由は「書く人が決まっていない」ことです。次の3つを合意します。

PRレビューで指摘した規約違反は、ナレッジベースに反映するまでがレビュー：再発防止のため
障害ポストモーテムの再発防止策のうちコード規約に関わるものは.claude/rules/に反映
月1回、decisions.mdを見直して古い意思決定をアーカイブする

git log --since="3 months ago" -- .claude/rules/で更新頻度を可視化できます。

git log --since='3 months ago' --oneline -- .claude/rules/

更新が止まっているファイルは「もう古い」「分割しすぎ」のサインです。

AGENTS.mdとの併用

OpenAI Codex CLI など他のAIコーディングツールが採用するAGENTS.md規約とCLAUDE.mdを両立させたいケースもあります。CLAUDE.md公式の@インポートは、別ファイルを読み込むだけのシンプルな機構なので、AGENTS.mdを作って共通ルールを集約し、CLAUDE.md側からインポートする運用が現実的です。

# CLAUDE.md

## チーム共通ルール
- @AGENTS.md

## Claude Code 固有の設定
- 確認コマンドは `npm run verify`（lint・型・テストを順に実行）
- Plan Mode を使う条件: 複数ファイル変更、依存追加、マイグレーション

逆方向（AGENTS.mdからCLAUDE.mdをインポート）は、ツール依存のシンタックスが混ざるので避けます。

失敗パターンと回避策

症状	原因	対処
誰も書かない	担当が決まっていない	PRレビュー指摘の反映を必須化
古い情報が放置	更新トリガーがない	月1回見直し・アーカイブ
探したい情報が見つからない	見出しがバラバラ	動詞統一・シンボル統一
200行を超えて読み込まれない	1ファイル運用	`.claude/rules/`に分割＋`@`インポート
個人の好みが混ざる	チーム合意なし	`CLAUDE.local.md`に個人ルールを分離