こんにちは、とまだです。
最近、Claude Code で開発をしていて「指示書が肥大化しすぎて管理が大変...」と悩んだことはありませんか？
また、適当に実装をさせても、あまり期待通りの結果が得られないことも多いですよね。
Claude Code では /init コマンドを使ってプロジェクトの指示書を生成することができますが、あくまで基本的な指示書しか作成されません。
また、プロジェクトが大きくなるにつれて、指示書がどんどん膨らんでしまい、Claude 君も混乱してしまうことが多いです。
今回は、その問題を解決するために試している「観点別ディレクトリ構造」について、途中経過ではありますが、ノウハウをシェアしたいと思います！
Claude Code って何？
Claude Code は、Anthropic 社が提供する AI エージェントツールです。
簡単に言うと、「プログラミングの相棒」みたいなもので、コードの生成から修正、レビューまで幅広くサポートしてくれます。
特に/initコマンドを使うと、現在のディレクトリや実装をもとに、プロジェクトの基本的な指示書を自動で作成してくれるので便利です。
特に嬉しいのは 定額制 で使い放題なところですね。
私は Claude Max プランを使っていますが、Pro プランでも十分に使えます。
従来の問題：指示書の肥大化
先述の通り、Claude Code ではプロジェクトの指示書を生成することができます。
一通りの指示は確かに書いてくれるんですが、プロジェクトが進むにつれて以下のような問題が出てきてしまいます。
- 指示書が長すぎて、Claude 君が情報を把握しきれない
- デザインとエンジニアリングの指示が混在して分かりにくい
- 必要な情報を探すのに時間がかかる
- 新しい観点を追加するたびに、既存の指示と矛盾が発生
例えば、「デザインを統一してください」と指示しても、SEO の観点やアクセシビリティの観点が混在していると、Claude 君も「どれを優先すればいいの？」と迷ってしまうわけです。
解決策：観点別ディレクトリ構造
そこで思いついたのが、「役割ごとに指示書を分ける」という方法です。
実際の開発現場でも、デザイナーとエンジニアとプロジェクトマネージャーはそれぞれ違う観点で作業しますよね。
同じようなことは Cursor や GitHub Copilot でもやっていたので、Claude Code でも同じように「観点別」に指示書を分割してみることにしました。
実際のディレクトリ構造
現在試している.claudeディレクトリの構造がこちらです。
関係ないものも含まれていますが、それはそれで参考になると思うので、公開しますね。
.claude
├── architecture.md # システム全体のアーキテクチャに関するドキュメント
├── perspectives # 実装中に考慮すべき観点をまとめたもの
│ ├── design-system.md # デザインシステム
│ ├── designer.md # デザイン・UI/UX 観点
│ ├── engineer.md # エンジニアリング観点
│ ├── product-manager.md # プロジェクトマネージャー観点
│ └── seo-specialist.md # SEOスペシャリスト観点
├── project # プロジェクト固有の戦略・観点・要件をまとめたもの
│ ├── business-strategy.md # ビジネス戦略
│ ├── content-strategy.md # コンテンツ戦略
│ ├── development-phases.md # 開発フェーズ
│ └── technical-requirements.md # 技術要件
├── structured_data # 公式ドキュメントから構造化データの仕様をまとめたもの
│ ├── ARTICULE_STRUCTURED_DATA.md
│ ├── BASIC_STRUCTURED_DATA.md # 共通仕様
│ ├── BREADCRUMB_STRUCTURED_DATA.md
│ ├── COURSE_STRUCTURED_DATA.md
│ ├── EDUCATIONAL_QUESTION_STRUCTURED_DATA.md
│ ├── FAQ_STRUCTURED_DATA.md
│ ├── ORGANIZATION.md
│ ├── PAYWALL_STRUCTURED_DATA.md
│ ├── PRODUCT_STRUCTURED_DATA.md
│ ├── PROFILE_STRUCTURED_DATA.md
│ ├── QA_STRUCTURED_DATA.md
│ ├── QUIZ_STRUCTURED_DATA.md
│ └── SOFTWARE_STRUCTURED_DATA.md
├── better_auth # 認証周りの改善に関するドキュメント
│ ├── AUTH_README.md
│ └── STRIPE_README.md
├── president-instruction.md # Claude Code への指示を書いて渡すもの (プロンプトに近い)
├── settings.local.json
└── task-list.md # 次に達成したい目標をまとめたもの
この構造のポイントは、役割ごとに明確に分離していることです。
特に効果的だった「perspectives」アプローチ
中でもperspectivesディレクトリの効果が絶大でした。
これは「実装中に考慮すべき観点」をそれぞれの専門家の視点でまとめたものです。
例えば、新しいページを作るときには以下のような指示を Claude 君に出します。
以下のステップに従って、ページを実装してください。
1. プロダクトマネージャー観点で、ページの目的と要件を確定する
2. デザイナー観点で、UI/UX デザインを作成する
3. SEO スペシャリスト観点で、SEO 対策を考慮する
4. エンジニア観点で、実装を行う
5. デザイナー観点で、実装後のデザインレビューを行う
6. SEO スペシャリスト観点で、実装後の SEO チェックを行う
7. プロダクトマネージャー観点で、全体の品質を確認する
それぞれの観点については、以下のファイルを参照してください。
- [デザイナー観点](./claude/perspectives/designer.md)
- [エンジニア観点](./claude/perspectives/engineer.md)
- [プロダクトマネージャー観点](./claude/perspectives/product-manager.md)
- [SEO スペシャリスト観点](./claude/perspectives/seo-specialist.md)
1 機能作るごとにそれなりにステップが多いですが、これにより各専門家の観点で段階的に指示を出すことができます。
実際、人間の開発現場でも、プロジェクトマネージャー、デザイナー、エンジニアがそれぞれの役割で協力して進めますよね。
このアプローチにより、Claude 君も「今回はどの観点で回答すればいいか」が明確になり、期待通りの結果が得られることが増えた気がします。
比較したわけではないのであくまで体感ですが、実装後の修正が減り、品質が向上したと感じています。
デザイナー観点の具体例
実際に使っている「デザイナー観点」の一部をご紹介します。
デザイナー観点の例（一部抜粋）
# デザイナー観点
UI 設計、ビジュアルデザイン、デザインシステム、UX、アクセシビリティの統合観点から考えるためのフレームワークです。
## 🎨 UI 設計原則
### 視覚的階層
👁️ 情報の重要度は視覚的に明確に表現されているか？
📏 適切なサイズ・コントラストで差別化されているか？
🎯 ユーザーの視線の流れは意図した通りか？
⚡ 主要なアクションは一目で認識できるか？
### レイアウト設計
📐 グリッドシステムに基づいた整列はできているか？
📱 レスポンシブ対応で全デバイスで適切に表示されるか？
⚖️ 要素間のバランスは取れているか？
🖼️ 適切な余白（ホワイトスペース）が確保されているか？
## ♿ アクセシビリティ
### 視覚的アクセシビリティ
👁️ 色覚異常のユーザーでも情報を判別できるか？
📏 フォントサイズは十分に大きいか？
⚡ コントラスト比は 4.5:1 以上を満たしているか？
🔍 拡大表示時にレイアウトが崩れないか？
このように、チェックリスト形式で具体的な項目を列挙することで、Claude 君も「何をチェックすればいいか」が明確に分かるようになりました。
実感している効果
この構造にしてから、以下のような改善を実感しています。
デザインの品質向上
デザイナー観点を独立させることで、UI/UX の一貫性が大幅に改善されました。
以前は「なんとなくそれっぽいデザイン」だったものが、プロのデザイナーが作ったような統一感のあるデザインになったんです。
SEO 対策の精度アップ
SEO スペシャリスト観点を分けたことで、構造化データの実装やメタタグの設定なども漏れなく対応できるようになりました。
技術的な実装と SEO 対策を分けて考えることで、どちらも高い品質を保てています。
開発効率の向上
「今日はデザインに集中したい」「今日は SEO 対策をメインにしたい」というように、その日の作業に応じて参照する観点を選べるようになりました。
結果として、Claude 君への指示も明確になり、期待通りの結果が得られることが増えました。
観点を分けることで、Claude 君も「今回は何の専門家として回答すればいいか」が明確になるようです
今後の展望
まだ試行錯誤の段階ですが、以下のような観点も追加予定です。
QA エンジニア観点
テストの観点や品質保証のチェックリストを独立させて、バグの少ない実装を目指したいと思っています。
現状は engineer.mdに含めていますが、QA 専門の観点を設けることで、より精度の高いテストが可能になると考えています。
さらなる分割
現在の構造でも効果は感じていますが、プロジェクトが大きくなればさらに細分化が必要になるかもしれません。
例えば、インフラエンジニア観点やセキュリティ専門家観点など、役割ごとに分けることで、より専門的な指示が可能になるでしょう。
あとは、「レビュアー」として、全く独立した観点を設けることで、コードレビューやドキュメントレビューを専門に行うことも検討しています。
まとめ
Claude Code の指示書を観点別に分割してみたことで、それなりに効果を実感しています。
まだ模索段階ですが、特にデザインや SEO 対策の精度が上がっているのを実感しています。
もし Claude Code の指示書で悩んでいる方がいれば、ぜひ「観点別の分割」を試してみてください！
今後も継続して検証を続けて、続報をお伝えしていきますね。
何か質問や「こんな観点も追加してみては？」「こんなこともやってるよ」というアイデアがあれば、ぜひコメントで教えてください！
X（Twitter）でも開発の様子を発信しているので、よかったらフォローしてください！