解決したい問題
Claude Codeで開発を進めていく中で、プロジェクト特有のコンテキストや規約が肥大化・複雑化してきたため、一度立ち止まって設定と構造を見直すことにしました
1. 設計の重要なところが会話に載っていない
- 症状: 過去の設計判断や docs の内容を踏まえずに提案 / 説明する
- 発端: docs/features/{feature}/design.md と docs/principles/ を task 開始時に読んでいない
- 根拠: task_routing.md に 「タスク種別ごとに必読 md」 が既に整理されているが、 私が守っていない
- 波及: 設計書の語彙 / 概念と提案の語彙が乖離するので、 説明が浮く
2. 説明・計画の日本語が難しい
- 症状: ジャーゴンの羅列、 blog 風の短文、 「わかって当然」 の書き方
- 発端: 「短く」「技術用語で」「blog 調 NG」 の feedback rule が同時に効いて、 読者への橋渡しが削られている
- 波及: 新人 / 来週の自分が読めない、 issue や plan が判断材料として機能しない
- 補足: 実は問題 1 と繋がっている。 設計書を読まないから語彙が揃わず、 前提を渡せず、 blog 的短文で誤魔化す
3. memory ディレクトリの肥大
- 症状: 89 file (feedback 77 / project 7)、 index 21KB
- 発端: 同テーマの feedback が分裂して積み上がる、 陳腐化した rule が消えない
- 波及: rule 同士が矛盾しても気付きにくい、 検索性が下がる
Claude設定ファイルの理解
Claudeのカスタマイズファイルは、「自動で読み込まれるか（常時有効）」「呼び出し時に読まれるか（遅延読み込み）」というタイミングと、「チーム共有か」「個人専用か」のスコープで整理すると非常にすっきり理解できます。
1. 自動読み込みファイル（セッション開始時に常時適用）
セッション開始時に自動的にシステムプロンプトへ組み込まれる、規約や前提知識のためのファイルです。
| ファイル名 | 配置場所 | 共有範囲 | 用途・キャラクター |
CLAUDE.md | <repo>/CLAUDE.md | チーム共有（Commit） | プロジェクトの基本規約、アーキテクチャ、命名規則など。 |
CLAUDE.md (入れ子) | <repo>/{subdir}/CLAUDE.md 等 | チーム共有（Commit） | サブディレクトリでの作業時、その親階層までの規約も追加で自動読み込み。 |
CLAUDE.md (user) | ~/.claude/CLAUDE.md | 個人グローバル | 全プロジェクトで共通して適用したい、自分専用の個人指示。 |
rules/*.md | .claude/rules/*.md(project または user) | 配置による | CLAUDE.md と同格の追加規約。本体ファイルを汚さずカテゴリごとに分割したい時に便利。 |
MEMORY.md | ~/.claude/projects/<slug>/memory/MEMORY.md | 個人（Commit外） | オートメモリのインデックス。 リンクされた個別メンバファイルも文脈に応じて自動でReadされる。 |
2. 遅延読み込みファイル（必要なタイミングで呼び出し）
最初からすべてを読み込むのではなく、ユーザーの入力や必要性に応じて動的に読み込まれるファイルです。
| ファイル名 / ディレクトリ | 配置場所 | 共有範囲 | 読み込みのトリガー・用途 |
commands/*.md | .claude/commands/(project または user) | 配置による | カスタムスラッシュコマンド。 ユーザーが /foo のようにコマンドを打った瞬間に読み込まれる。 |
agents/*.md | .claude/agents/(project または user) | 配置による | カスタムサブエージェント定義。 Agent tool が呼び出された際に読み込まれる。 |
skills/<name>/SKILL.md | .claude/skills/(project または user) | 配置による | カスタムスキル定義。 Skill tool が機能（invoke）した際に読み込まれる。 |
memory の個別 *.md | ~/.claude/projects/<slug>/memory/*.md | 個人（Commit外） | 上述の MEMORY.md を経由して、Claudeが関連性があると判定した際に Read tool で自動で開く。 |
3. 環境・挙動設定ファイル
Claudeの挙動そのものや、実行権限などをシステム側に解釈させるための設定ファイルです。
| ファイル名 | 配置場所 | 共有範囲 | 用途・設定内容 |
settings.json | .claude/settings.json(project または user) | 配置による (project側はCommit) | 権限（permissions）、フック（hooks）、環境変数（env）、使用モデル（model）の制御。 |
settings.local.json | .claude/settings.local.json(project内) | 個人（gitignore） | プロジェクト共通設定（settings.json）を、開発者個人の環境で上書き（override）したい時（APIキー許可など）。 |
keybindings.json | ~/.claude/keybindings.json | 個人グローバル | キーバインド設定（ユーザー専用）。 |
優先順位
- 同じキーがぶつかった時: project local > project shared > user global
- rules / agents / commands / skills / memory は “重ねて” 読まれるので、 上書きではなく併存
運用の勘所
- CLAUDE.md はチーム共有、 変更に議論を伴う → 規約級
- .claude/rules/ は CLAUDE.md を短く保ちたい時の分割先 → 規約級
- MEMORY.md は Claudeが会話から蓄積するメモ、 user 個人スコープ → 個人 note 級
方針
- 今回の問題 (「設計を読まない」) は CLAUDE.md か .claude/rules/task-start.md に書けば全員 (将来の共同開発者含む) に効くし、 個人だけで済ませたければ ~/.claude/CLAUDE.md
- に書く選択もある。
ルール見直し：設計を読ませる, 文章の難しさの解消
- CLAUDE.md の整理
- .claude/rules/task-start.md の整備
- .claude/rules/writing-style.md の整備
memory整理：memoryディレクトリの肥大化の解消
- MEMORY.mdの整理
- memory/*.mdの整理
バックアップ
作業前にgitで管理してないファイルのバックアップを取る
cp -R ~/.claude/projects/{project}/memory \
~/.claude/projects/{project}/memory.backup-$(date +%Y%m%d-%H%M)実行
- .claude/rules/coding-style.md 整備
- .claude/rules/writing-style.md 整備
- .claude/rules/task-start.md 整備
- memoryファイルの一部をwriting-style rule に統合し、削除
- memoryファイルの一部をcoding-style rule に統合、削除
- memoryファイルの一部をマージ（plan用、issue用、test用、）