CLAUDE.mdを分離しても読まれない問題をGitHub機能で解決した

前回の記事でCLAUDE.mdを273行から121行に削減した。テンプレートを別ファイルに分離し、ガードレール（Claudeが誤りやすい箇所）を優先する方針で整理した。

しかし、別のプロジェクトで同じアプローチを取ったところ、新たな問題が発生した。

分離しても結局読まれない

前回の方針に従い、以下のように情報を分散させた：

CLAUDE.md - 開発ルール、ガードレール
docs/claude/handover.md - 引き継ぎ情報
docs/claude/api-spec.md - API仕様
current-tasks.md - タスク管理

結果：

分離先も肥大化 - 引き継ぎ情報が時系列で蓄積し、handover.mdが数百行に
そもそも読まない - ファイルが増えるほど、Claudeは必要なファイルを見つけられない
二重管理 - タスクをローカルMDとGitHub Issuesの両方で管理する羽目に
古い情報が残る - 完了したタスクや解決済みの障害メモが削除されず蓄積

「終わったタスクはlog.mdに移動」という運用も試したが、今度はログファイルが肥大化する。検索時にノイズになり、結局邪魔になる。

「ファイルを分ければ解決」は幻想だった。ドキュメントが増えれば増えるほど、Claudeはそれを読まなくなる。

解決策：GitHub機能への委譲

ローカルMDに書くのではなく、GitHub の標準機能に役割を移すことにした。

情報の種類	Before	After
バグ・タスク	`current-tasks.md`	GitHub Issues
進捗管理	MDファイル手動更新	GitHub Projects
技術仕様	`docs/claude/` 内のMD	GitHub Wiki
障害教訓	引き継ぎMD内に蓄積	Issues（postmortemラベル）

なぜGitHubか

検索可能 - Issues/Wikiは全文検索できる。ローカルMDより探しやすい
構造化 - ラベル、マイルストーン、Projectで情報が整理される
自動化 - GitHub Actionsでラベルに応じた自動振り分けが可能
クローズ可能 - 完了したIssueはクローズされ、アクティブな情報だけが残る

特に「クローズ可能」が重要。ローカルMDは「追記」しかできないが、Issuesは「完了したら閉じる」という自然な流れがある。古い情報が自動的に視界から消える。

バイブコーディングで任せっぱなしにしているとき、この差が顕著に出る。MDへの追記だと「どこまで進んだか」「何が残っているか」が把握しづらいが、Issuesなら一覧で見える。

運用フロー

Plan modeで計画を立てさせる - Claudeに実装計画を作らせる
内容が良ければIssueに登録 - 計画をそのままIssue化
以降はIssueを引き継いで進める - セッションが変わってもIssueを見れば状況がわかる

Wikiにはバックエンドやフロントエンドの構造を総覧させて登録しておく。「この機能なんだっけ？」が人間にもAIにもわかる状態になる。

ちなみにClaude CodeにはLSP機能（関数検索）が追加されたので、まともに動くならそれでもいい。ただ、どのみち毎回検索するなら、人間にもわかりやすい形でドキュメント化しておいたほうが良い。

ドキュメント整理もClaudeに任せる

開発初期に整備したドキュメント群も、開発が進むにつれて100ファイル超え・重複発生となった。これをClaudeに整理させた：

現在の実装コードを総覧させる
既存ドキュメントと突き合わせる
重複・古い情報を削除
整理した内容をWikiに登録

ローカルMDだと「とりあえず追記」になりがちだが、Wiki化のタイミングで棚卸しできる。

コンテキスト消費の問題

ローカルMDの最大の問題は、読み込むだけでコンテキストを消費すること。タスク管理用のMDを読むだけで数パーセント消費、というのは馬鹿らしい。GitHub Issuesならgh issue listの結果だけで済む。

もちろんghコマンドでのアクセスは発生するが、MCPで専用ツールを作っても同様のアクセスは必要。この辺は好みの問題だと思う。

運用してみて「やっぱり遅い」となったら、ドキュメント検索用のMCPを作るかもしれないが、今のところGitHub標準機能で十分回っている。

個人的には、MCPはPlaywrightのような「そのツールで動かさないと意味がない」ものだけに絞りたい。E2Eテストやブラウザ操作は代替手段がないからMCPにする価値がある。ドキュメント検索程度ならghコマンドで十分。

実際の効果

この運用を試してみたところ、Claudeからの確認（Ask）が減った。調べるべき場所がまとまっているので、自分で情報を取りに行ってテストまで実行し、結果だけ返してくるようになった。

これが求めていた動作。こちらは仕様策定に集中できる。

実装例

1. ラベル体系

bug          - バグ報告
task         - タスク
handover     - 引き継ぎ事項
postmortem   - 障害教訓
frontend     - フロントエンド関連
backend      - バックエンド関連

handoverラベルを付けたIssueが、従来の引き継ぎMDの代わりになる。

2. GitHub Actionsで自動振り分け

# .github/workflows/auto-project.yml
name: Add to Project
on:
  issues:
    types: [opened, labeled]

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - name: Add to Project
        if: contains(github.event.issue.labels.*.name, 'frontend')
        uses: actions/add-to-project@v1.0.2
        with:
          project-url: https://github.com/users/YOUR_USER/projects/1
          github-token: ${{ secrets.PROJECT_TOKEN }}

特定のラベルが付いたIssueを自動でProjectに追加できる。

3. CLAUDE.mdの簡素化

CLAUDE.mdには以下だけを残す：

プロジェクト概要（10行程度）
ガードレール（誤りやすい箇所）
重要な注意事項（絶対守るルール）
リンク集（Wiki、Issues、Projectsへの導線）

詳細な仕様や手順はすべてWikiに移動。CLAUDE.mdは「入口」としての役割に徹する。

効果

指標	Before	After
CLAUDE.md	386行	197行
タスク管理場所	2箇所（MD + Issues）	1箇所（Issues）
引き継ぎ情報	MD内に蓄積	Issue化で検索可能
完了タスク	手動で削除 or 放置	クローズで自動整理

運用ルール

作業開始: gh issue listで現状把握
バグ発見: gh issue create --label bug
引き継ぎ事項: gh issue create --label handover
タスク完了: gh issue close 番号 --comment "対応内容"
技術情報追加: Wiki更新

Claude Codeはghコマンドが使えるので、このフローは自然に実行できる。

まとめ

ローカルMDへの分散は「肥大化の分散」でしかなかった
ドキュメントが増えるほどClaudeは読まなくなる
GitHub機能は検索可能・自動化可能・クローズ可能
CLAUDE.mdは「入口」に徹し、詳細はGitHubに委譲する

「ファイルを分ける」から「システムに委ねる」への発想転換が有効だった。