CLAUDE.mdをAnthropic公式ベストプラクティスに沿って再構成した記録

著者: ClaudeMix Team |

毎回の会話でフロー実行時専用の詳細指示までロードしていたCLAUDE.mdを、Anthropic公式が推奨するWHAT/WHY/HOWの3要素へ再構成し、詳細ルールを外部ドキュメントへポインタ化することでコンテキスト消費量を削減した。

① やったこと

Before: 独自形式のCLAUDE.mdに、特定のフロー実行時にしか使わない詳細な手順(進捗ログの更新手順など)が本文中に直接書かれていた。

## 🥇 1. 最上位行動原則 (マスター・ルール)

- 唯一の規範: 開発フローは以下の2層で定義されています。
  - Lv1: フロー骨格(開発フロー簡略図)
  - Lv2: フロー詳細(各フロー定義書)
- ドキュメントの更新: 作業完了時、またはステータス変更時、必ず関連する進捗ログを正確に更新し、進捗を人間と共有してください。

毎回の会話でこの詳細手順までロードされ、本来毎回参照すべき「プロジェクト固有の常識」を圧迫していた。CLAUDE.md全体は行数にして肥大化しており、トークン換算で概算約4,200トークンをこの1ファイルが占めていた。

After: 本文をWHAT(概要)・WHY(設計思想)・HOW(検証コマンド)の3要素に絞り、フロー実行時専用の指示は外部ドキュメントへの参照(ポインタ)に置き換えた。

# ClaudeMix Project Context

## Project Overview (WHAT)
- Stack: Remix, TypeScript, Cloudflare Pages (Workers, D1, KV).

## Design Philosophy (WHY)
- Single Source of Truth (SSoT): All literal values must be in `*-spec.yaml`.

## Verification Commands (HOW)
- `npm run build` - Static build.
- `npm run typecheck` - Run TypeScript validation.

## Detailed Documentation
- Architecture Rules: @docs/architecture/YAML_REFERENCE_GUIDE.md

再構成後、CLAUDE.mdがロードするコンテキスト量は約2,600トークンまで減った。

② 設計判断

  • 【優先した価値】: 毎回の会話でロードされる情報を「常に必要な地図と思想」だけに絞ること
  • 【犠牲にした価値】: フロー実行時の詳細手順を外部ドキュメントへ分散させたことで、CLAUDE.md単体を読むだけでは運用ルールの全体を把握できなくなった。参照先を辿る一手間が増えた

③ 技術的負債

  • 【解消した負債】: 毎回の会話でロードされるコンテキスト量。実測: 約4,200トークン → 約2,600トークン(約1,600トークン削減)
  • 【新たに生まれた負債】: 詳細ルールが複数の外部ドキュメントに分散したため、あるルールを変更した際にCLAUDE.md側のポインタが指す先が古い記述のままになっていないか、整合性を維持する運用コストが生まれた

④ 経営翻訳

新入社員に配る業務マニュアルに、特定の月次業務でしか使わない詳細な作業手順まで書き込んでいたため、日常業務の要点が埋もれていた状況に相当する。特定業務の詳細手順は別冊のマニュアルに切り出すことにした。

実際にはマニュアルの分量が約38%減り、約4,200トークンから約2,600トークンになった。日常業務に必要な要点だけが残り、新入社員が迷う場面が減った。

CLAUDE.mdの「ポインタ化」と同じ「AIに言わなくていいことを増やす」思想を物理的な設計レイヤーに適用したのがリポジトリ分離という設計判断である。コンテキストの整理はドキュメントだけでなくアーキテクチャでも実現できる。

新入社員に配る業務マニュアルに、特定の月次業務でしか使わない詳細な作業手順まで書き込んでいたため、 日常業務の要点が埋もれていた。特定業務の詳細手順は別冊のマニュアルに切り出すことにした。

新入社員が毎日目を通す業務マニュアルの分量: 約4,200トークン