はじめに
前回の記事で、AIを活用して画面表示までできるアプリを短時間で作成しました。「あやふやだった自分の知識を補完してもらいながら、ここまで爆速で開発できるのか！」と、AI協調型開発の凄さを身をもって実感しました。
しかし、作成されたソースコードをじっくり見返してみると、ある重大な問題に気がついたのです。
UIとビジネスロジックの混在
生成されたコードは、UI（見た目）とビジネスロジック（処理）が同じファイルに記述されていました。
これでは、プロトタイプとしては良くても、今後機能を拡張したり運用していく上で保守性が著しく低下してしまいます。
私が最初に「大雑把な指示」しか出さず、アーキテクチャの原則を明示していなかったため、AIは「最短で動くコード」として1ファイルにまとめてしまったのです。
そこで、「前提条件やルールをあらかじめAIに読み込ませておく必要がある」と考え、最近話題の CLAUDE.md を導入することにしました。
** CLAUDE.mdとは？**
Claude（特にClaude CodeなどのCLIツール）に、プロジェクトのコンテキスト、ビルド方法、開発ルールなどを事前学習させるための設定ファイルです。
CLAUDE.mdの導入と、ルールの構造化
調べてみると、GitHubで17万スターを獲得しているような構成（※記事執筆時点）や、Claudeの公式ガイドにあるベストプラクティスがあることを知りました。
また、CLAUDE.md自体にルールを100行以上書きすぎるのは推奨されない（コンテキストの効率化のため）とのことだったため、トピックごとにファイルを分割し、CLAUDE.mdから参照させる構成にしました。
1. ディレクトリ構成の整理
Claudeに「トピックごとに分割したMarkdownファイルを作成し、それをCLAUDE.mdに読み込ませたい」と依頼し、以下の構成を作成しました。
プロジェクトルート/
├── CLAUDE.md ← エントリーポイント
└── docs/
├── 01_ai_collaborative_design.md (AI協調型設計)
├── 02_architecture_patterns.md (アーキテクチャパターン)
├── 03_coding_standards.md (コーディング標準・依存関係管理)
├── 04_web_app_12factor.md (Webアプリ・12Factor App)
├── 05_testing_strategy.md (テスト戦略)
├── 06_quality_metrics.md (品質測定指標)
└── 07_tech_debt_improvement.md (技術債務・継続的改善)
2. デザインシステムの追加
今回は「勤怠管理アプリ」を作るため、きっちりしたトーン＆マナーにしたいと考えました。弊社のロゴ画像をClaudeに添付し、ブランドカラーに合わせたスタイルガイドを作ってもらいました。
自分: 「作りたいWebサイトは勤怠管理アプリなので、きっちりした感じでお願いします。完成したら
designbase.mdファイルを作成してください」
Claude: 「ロゴを確認しました。SpeedLink Japanのブランドに合わせた、きっちりしたデザインベースを作成します」
これで docs/designbase.md も無事に生成されました。
3. 完成した CLAUDE.md
最終的に、これら全てのルールを束ねる CLAUDE.md は以下のようになりました。
# CLAUDE.md
@AGENTS.md
# プロジェクト アーキテクチャガイドライン
このプロジェクトのソフトウェアアーキテクチャ原則は以下のファイルに分割されています。
## ドキュメント構成
@docs/01_ai_collaborative_design.md
@docs/02_architecture_patterns.md
@docs/03_coding_standards.md
@docs/04_web_app_12factor.md
@docs/05_testing_strategy.md
@docs/06_quality_metrics.md
@docs/07_tech_debt_improvement.md
## デザインシステム
@docs/designbase.md
よし、これで完璧！…と思いきや？
「これだけ厳密にルールを定義したのだから、次からは完璧な構成でコードを書いてくれるだろう！」と期待を胸に、新しい画面の作成を指示しました。
自分: 「勤怠一覧画面は登録された勤怠情報を見るだけの画面にしてください。日付ごとに登録ボタンを追加し、勤怠を登録する画面を作成してください」
Claude: 「実装完了です。変更内容をまとめます」
ワクワクしながら生成されたコードを確認すると……。
またUIとビジネスロジックが一緒のファイルになっていました。
なぜルールを無視されたのか？
最終的には、「UIとビジネスロジックは必ず分けて」と直接チャットで追加の指示を出すことで解決し、さらに「今の『分けて』というルールを CLAUDE.md（または構成ファイル）に明記して」とお願いしてルールをアップデートしてもらいました。
結論：CLAUDE.mdは「最初から完璧なもの」ではなく「自分で育てていくもの」
CLAUDE.md は、用意すれば魔法のように何でも思い通りにしてくれるツールではありません。プロジェクトを進めながら、AIの出力の癖を修正し、チームや自分に最適化させていく「秘伝のタレ」のようなものだと気づきました。
- 最初は大まかなガイドラインからスタートする
- AIが意図しないコードを書いたら、その都度ルールをアップデートする
- プロジェクト固有の「地雷」や「こだわり」をどんどん追記していく
このように、開発プロセスを通じて CLAUDE.md を一緒に育てていくことこそが、Claudeを上手に使いこなすための最大のコツだと言えます。
おまけ：CLIを使う時の大失敗とリカバリー
今回の開発では CUI（Claude Code）を使用していたのですが、コンテキスト（会話履歴）が肥大化してきたため、容量を節約しようと /compact コマンドを実行しました。
確かに履歴が圧縮されて容量問題は解決したのですが、今までの詳細な会話履歴がターミナル上から消えてしまいました！
これでは、Qiitaの記事を書くための振り返りができません……。
履歴の救出方法（Windowsの場合）
焦ってローカルを探したところ、以下のディレクトリにやり取りのログが残っているのを発見しました。
C:\Users\{ユーザー名}\.claude\projects
ただし、ここにあるデータはそのまま綺麗に見える形（GUIチャットのようなUI）では残っていないため、ログを掘り起こしてパースするのはかなり大変でした。
教訓:
コンテキストの圧縮は便利ですが、後から「記事を書きたい」「あの議論を振り返りたい」という可能性がある場合は注意が必要です。手軽に履歴を見返したい、ビジュアルで管理したいという場合は、GUI（ブラウザ版や各種IDEのプラグイン）を活用する方が一日の長があるかもしれません。プレイスタイルに合わせてCUIとGUIを使い分けていきましょう！