はじめに
こんにちは！株式会社 Hacobu で Vista というプロダクトのフロントエンドエンジニアをしている cho です。
最近、チームで面白い議論になったことがあります。Claude Code や Cursor みたいな AI 開発ツールを使っていると、どうしても設定ファイルが増えてしまいますよね。
うちのチームも例外ではありませんでした。
- まず Notion でコーディング規約を管理
- Cursor 導入で
.cursor/rules/に AI 用設定を追加 - Claude Code 登場で
CLAUDE.mdも作成
気がついたら、同じような内容が 3 箇所に散らばってる… という状況に 😅
そんな時、チームでふと疑問が浮かびました
「人が読むドキュメントと AI が読むドキュメントって、本当に分ける必要あるの？」
この素朴な疑問から始まった改善で、意外とシンプルな解決策が見つかりました。
結果的に
- 人間もAI エージェントも同じドキュメントを見る仕組みができた
- 情報の管理がめちゃくちゃ楽になった
- おまけで 728 行もコード削減できた
同じような悩みを抱えているチームの参考になれば嬉しいです 🙌
何が問題だったのか
最初は Notion で十分だった
元々、コーディング規約とかプロジェクト情報はNotionで管理してたんですよね。人間が見る分には全然問題なくて、必要な時にサクッと確認できて便利でした。
AI ツールが増えるたびに設定ファイルも増える
ところが、AI 開発ツールを導入し始めると話が変わってきました。
Cursor を入れた時
「AI にもプロジェクト情報を教えなきゃ」ってことで、.cursor/rules/に設定ファイルを作成。Notion の内容をベースに、AI 向けに書き直しました。
Claude Code を入れた時
今度はCLAUDE.mdが必要に。また同じような内容を書くことに…
この辺りで「あれ？」って思い始めました 🤔
- 同じ LLM なのに、なんでツールごとに違うルールが必要なの？
- 新しい AI ツールが出るたびに、また同じ内容を書き直すの？
気がついたら情報が散らばってる
結果的に、こんな状況になってました
プロジェクト管理/
├── Notion (人間向け)
│ ├── コーディング規約
│ ├── プロジェクト概要
│ └── テスト指針
└── リポジトリ (AI向け)
├── .cursor/rules/ (Cursor用)
│ ├── 0000-project-overview.mdc
│ ├── 0001-coding-rule.mdc
│ ├── 0002-testing.mdc
│ └── 0003-storybook.mdc
└── CLAUDE.md (Claude Code用)
└── プロジェクト設定情報
3 箇所に同じような情報が… これはヤバい 😱
ふと思ったこと
ここで疑問が浮かんだんです
「これらのドキュメント、人間が読んでも普通に理解できるよね？」
考えてみると
- 人間 → Notion を見る
- AI → コード内の設定ファイルを見る
でも、AI が読んでる設定ファイルって、人間が読んでも全然分かる内容なんですよね。
だったら同じドキュメントを共有した方が、情報の一貫性も保てるし、メンテナンスも楽になるんじゃない？と思ったわけです。
どうやって解決したか
基本的な考え方
結論から言うと、「docs/ディレクトリを情報の大元にして、AI 設定ファイルはそこを参照するだけ」 という方式にしました。
docs/ディレクトリに情報を統合
まずやったのは、散らばってた情報をdocs/ディレクトリに統合することでした。
Notion から移行
- プロジェクト概要 →
docs/project-overview.md - コーディング規約 →
docs/coding-rule.md
Cursor の rules から移行
- テスト指針 →
docs/testing.md - Storybook 運用ガイド →
docs/storybook.md
「一箇所に集めて、そこを参照するようにしよう」 って方針にしたんです 💡
AI 設定ファイルをスリム化
今まで AI 設定ファイルに大量のコンテンツを直接書いてたのを、docs/配下のファイルを参照するだけに変更しました。
実際どう変わったか
変更前：docs の内容を全部ベタ書き
# .cursor/rules/0000-project-overview.mdc (240 行！)
# プロジェクト概要
このプロジェクトは TypeScript、React、pnpm workspace ベースの...
## プロジェクト構造
- **Monorepo**: Turborepo + pnpm workspace 使用
- **パッケージ構造**:
- `apps/`: アプリケーション...
- `libs/`: 共通ライブラリ...
[... さらに 200 行以上続く]
変更後：参照するだけ
# .cursor/rules/0000-project-overview.mdc (37 行)
# Project Overview
TypeScript, React, pnpm workspace-based monorepo project.
## Documentation Reference
Always refer to the detailed project overview:
`./docs/project-overview.md`
## Key Development Commands
[最低限の情報だけ]
240 行 → 37 行になりました 🎉
ちなみに、AI 設定ファイルは日本語から英語に変更しました。
- トークン数を少しでも減らしたかった - 英語の方が一般的にトークン効率が良い
- AI 設定ファイルは人間が読まない - どうせ人間が直接見ることはないので、AI が理解しやすい形式を優先しました
Claude Code はちょっと工夫が必要だった
CLAUDE.mdも同じ考え方で作ったんですが、Claude Code は Cursor みたいに細かい設定ができないので、もう少し明示的に指示する必要がありました
# Claude Local Configuration
## Project Documentation
Always refer to these core documents:
- **Project Overview**: `./docs/project-overview.md`
- **Coding Rules**: `./docs/coding-rule.md`
Additional guides (request when needed):
- **Testing Guide**: `./docs/testing.md`
- **Storybook Guide**: `./docs/storybook.md`
Cursor と Claude Code の違い
-
Cursor:
Rule Typeで自動的に制御できる -
Claude Code:
Always referとかrequest when neededで明示的に優先度を伝える必要がある
結果：みんな同じところを見るように
この方式で、人間も AI も同じ docs/配下のファイルを見るようになりました。
-
人間 → 直接
docs/*.mdを見る -
Cursor →
.cursor/rules/*.mdc経由でdocs/*.mdを見る -
Claude Code →
CLAUDE.md経由でdocs/*.mdを見る
つまり、情報の大元は一箇所になったってことですね 👍
やってみてどうだったか
一番よかったこと
人間と AI が同じ情報を見るようになった
これが一番大きかったです。今まで別々だった情報が統一されたことで
- 更新が楽: 一箇所直せば、人間も AI も最新情報を見れる
- 情報の食い違いがなくなった: 複数箇所で管理してた時は、どこかの更新を忘れることがあった
- ドキュメントの品質が上がった: 一元管理だと、自然と情報の正確性を意識するようになる
新しい AI ツールに対応しやすくなった
これも予想外の効果でした。新しい AI ツールが出ても、既存の docs/ディレクトリを参照するだけで済むので、「また同じ内容を書き直すのか…」 っていう憂鬱がなくなりました 😊
他にもこんな効果が
新しいメンバーのオンボーディングが楽になった
新しく入ったメンバーに「AI の設定とプロジェクトの情報、両方同じところにあるよ」って言えるのは結構便利でした。
チーム内の認識のズレが減った
人間と AI が同じドキュメントを見てるので、「AI はこう理解してるけど、人間はこう思ってる」みたいな食い違いがなくなりました。
数字で見るとこんな感じ
コード削減効果
- 削除: 728 行
- 追加: 92 行
- 差し引き: 636 行削減
- 削減率: 約 88%
ファイル別の変化
-
.cursor/rules/0000-project-overview.mdc: 240 行 → 37 行 (85%削減) -
.cursor/rules/0001-coding-rule.mdc: 282 行 → 29 行 (90%削減) -
.cursor/rules/0002-testing.mdc: 120 行 → 33 行 (73%削減) -
.cursor/rules/0003-storybook.mdc: 219 行 → 34 行 (84%削減)
トークン使用量について
正直に言うと、path 参照なので AI は最終的に docs/ファイルを読み込むため、実際のトークン使用量への影響は限定的かもしれません。
ただ、情報の整理ができたことで、AI が必要な情報にアクセスしやすくなったのは確実です。
他のプロジェクトでも使えそう
基本的な手順
同じようなことをやりたい場合は、こんな感じで進めるといいかも。
- docs/ディレクトリを整理 - 既にあるなら活用、なければ作成
- AI 設定ファイルを path 参照形式に変更 - 大量のコンテンツを参照に置き換え
- 重複してるドキュメントを統合 - 同じ内容があちこちにあるのを整理
AI 専用の指示はどうするか
人間には不要だけどAI にだけ必要な指示は、各 AI 設定ファイル内で管理するのがよさそうです。
-
Cursor 専用:
.cursor/rules/*.mdcファイル内 -
Claude Code 専用:
CLAUDE.mdファイル内
共通の docs/は人間と AI が共有する情報、AI 専用指示は各ツールの設定ファイルで、という役割分担が大事だと思います。
今後、AI 開発ツールがもっと標準化されれば、さらに効率的な管理方法が生まれそうですね 🚀
まとめ
「人間と AI のドキュメントって分ける必要あるの？」という素朴な疑問から始まった今回の取り組み。path 参照での一元管理というシンプルなアプローチで、予想以上に良い結果が得られました。
学んだこと
- 情報の重複は悪じゃない場合もある - でも一元管理の方が結果的に品質が上がった
- 設定ファイルは軽くていい - 大量の情報をべた書きするより、適切な参照の方が管理しやすい
- AI ツールは今後も増える - だからこそ、既存の知識ベースを活用できる仕組みが大事
おわりに
AI 開発ツールがどんどん増えてる今、「どう使うか」だけじゃなくて「どう管理するか」も大事な課題ですよね。
今回の経験が、同じような悩みを抱えてるチームの参考になれば嬉しいです！
プロジェクトによって最適解は違うと思いますが、人間と AI の情報共有を意識した設計って観点は、今後ますます重要になりそう。
みなさんのプロジェクトでも、ぜひ試してみてください 🙌
Discussion