🗂️

毎日の判断は CLAUDE.md、深掘り学習は docs/rules/ ― カオスなドキュメントを最小構成で回してみた

に公開
Claude
Claude Code
zennfes2025free
idea

はじめに

README、Wiki、Notion、ドキュメント…
プロジェクトが走り出すと「とりあえず書く」ことが増え、気づけばこんな状態になっていませんか？

  • どこに何を書いたのか思い出せない
  • 新人が資料を探して迷子になる
  • 毎回コマンドを探すのに時間がかかる

私のチームもまさにそうでした。
そこで試したのが 「最小構成で文書を回す」 という整理法です。
キモになるのは CLAUDE.md と docs/rules/ の役割分担。

  • CLAUDE.md = 毎日の判断を支える即時参照
  • docs/rules/ = 腰を据えて学ぶ深掘り参照

この2つに整理するだけで、文書がスッキリと回り始めました。

CLAUDE.md に置くべきもの

CLAUDE.md は「迷わないための即時ガイド」。
以下のような 即判断が必要な情報 に絞ります。

  • 実行直前の判断に必要なもの

    • 実行前のチェックリスト
    • 何を優先すべきか
    • どの条件で止めるか
    • エラー発生時の即応方法

  • 毎回必ず使うもの

    • 品質チェックコマンド
    • プロジェクト固有のルール

実例

uv run ruff format .
uv run ruff check . --fix
uvx ty check
uv run pytest

logger.info("start", extra={"job_id": job_id})
logger.error("fail", extra={"job_id": job_id, "error": str(e)})

👉 これが手元にあれば、考え込まずにすぐ実行できます。

docs/rules/ に分けるべきもの

逆に、すぐに判断に使わない知識は docs/rules/ に分離。

  • 実装 How-to

    • 具体的なコードパターン、ベストプラクティス集

  • 低頻度・専門知識

    • 月1回程度しか見ない仕様
    • 新規メンバーの学習用資料

実例

  • Python typing の詳細パターン
  • FastAPI JWT 認証の実装例
  • エラーハンドリングのベストプラクティス

👉 一度理解すれば十分なものや、学習寄りの情報はこちら。

CLAUDE.md と docs/rules/ の違い

両者を整理するとシンプルです。

項目 CLAUDE.md docs/rules/
目的 即時判断 実装・学習
内容 Why / When How
役割 判断支援 作業支援
参照 毎日見る 時々見る

クイックチェックリスト

  • 思考を止めずに見たい？ → CLAUDE.md
  • 毎日使う？ → CLAUDE.md
  • プロジェクト固有？ → CLAUDE.md
  • 一度学べば十分？ → docs/rules/
  • 技術 How-to？ → docs/rules/

実践ステップ: ドキュメントを整理してみる

  1. 現在のルール・資料をリストアップ
  2. 上のチェックリストで仕分け
  3. CLAUDE.md には「最小限・即判断」情報を残す
  4. docs/rules/ に「詳細・学習」情報を集約

👉 これだけで CLAUDE.md は薄く鋭く、docs/rules/ は深く体系的に。

即試せる！AI 仕分けテンプレート

「仕分け作業を自動化したい」という人向けに、そのままコピペで試せるプロンプトを用意しました。
まずは自分のREADMEやWikiをAIに突っ込んでみてください。

# 役割: ドキュメント仕分けアシスタント
以下の項目を読み、次の基準で分類してください:

- CLAUDE.md → 即時判断・毎日使用・プロジェクト固有の情報
- docs/rules/ → 実装How-to・低頻度/学習的な情報

出力フォーマット:
- CLAUDE.md に残す項目
- docs/rules/ に移す項目
- 分類理由

**入力例**

1. 品質チェックコマンド
2. FastAPI JWT 認証実装例
3. プロジェクト固有エラーコード規則
4. Python typing ジェネリックパターン集

**出力例**

[CLAUDE.md]
- 品質チェックコマンド (毎日実行)
- プロジェクト固有エラーコード規則 (即判断が必要)

[docs/rules/]
- FastAPI JWT 認証実装例 (How-to, 学習用途)
- Python typing ジェネリックパターン集 (低頻度参照)

👉 入力例をそのまま試すだけで、自分のチーム用にすぐカスタマイズできます。

まとめ

  • CLAUDE.md = 毎日の判断を止めないための即時ガイド
  • docs/rules/ = 深掘りと学習のためのリファレンス

プロジェクトのドキュメントがカオスになっているなら、ぜひこの最小構成で整理してみてください。
「迷わないドキュメント」になるだけで、開発のリズムはぐっと軽くなります。

Discussion