メインコンテンツへスキップ
見出し画像

Claude Codeが別物になった ― 個人開発者の私が最初に書く「CLAUDE.md」を全文公開します

    個人でアプリを作っていて、Claude Code を使い始めた人に一番伝えたいことがあります。

    「CLAUDE.md を書くかどうか」で、Claude Code は半分別のツールになります。

    大げさに聞こえるかもしれませんが、私は実際にそうでした。今回は、私がいま開発中の個人アプリ(地図上で地点の訪問を記録する小さなアプリ)で実際に使っている CLAUDE.md を、ほぼ丸ごと公開します。コピペで使える形なので、自分のプロジェクトに合わせて持って帰ってください。

    CLAUDE.md を書く前の私

    最初、私は CLAUDE.md を書かずに Claude Code を使っていました。何が起きていたかというと、こうです。

    • 毎回「このプロジェクトは Expo で TypeScript で…」と前提を説明し直す

    • 設計だけ相談したかったのに、気づいたら実装まで勝手に書き始めている

    • ちょっと放っておくと、頼んでいないログイン機能や凝った設計を提案してくる

    • 「念のため確認します」と言ってコードベース全体を読み始め、トークンがどんどん溶ける

    • 昨日の続きをやらせようとしても、まず状況把握からやり直しになる

    要するに、毎セッションが「はじめまして」からスタートしていました。優秀なメンバーが毎朝記憶を失って出社してくる、みたいな状態です。

    CLAUDE.md を整えてから、これがほぼ消えました。前提説明は不要になり、脱線は止まり、再探索でトークンを溶かすこともなくなった。差は想像以上でした。

    CLAUDE.md とは

    CLAUDE.md は、Claude Code が毎セッションの最初に自動で読み込むプロジェクト用のメモです。プロジェクトのルートに置いた CLAUDE.md というただのMarkdownファイル。

    ここに「どう動かすか」「何を守るか」「やってほしくないこと」を書いておくと、Claude はコードからは読み取れない前提を、毎回ゼロから推測せずに済みます。要するにプロジェクトの記憶です。

    理屈はこれだけ。あとは中身が全てなので、実物を見てもらった方が早いです。

    私の CLAUDE.md(全文)

    実際に使っているものから、アプリが特定される情報だけ伏せて貼ります。構造と考え方はそのままです。

    markdown

    # CLAUDE.md — 地点訪問記録アプリ(個人開発)
    
    このファイルは毎セッションのコンテキスト基点。ここと docs/roadmap.md を読めば
    現状が分かるよう維持すること。広範な再探索でトークンを溶かさない。
    
    ## あなたの役割
    本プロジェクトの PM 兼 PdM 兼 PL(シニアスペシャリスト)。各セッションで:
    - PdM: 要件の優先順位付け・スコープ管理・受け入れ基準の明確化。スコープ外を守る。
    - PM:  マイルストーン計画と進捗管理。docs/roadmap.md を常に最新に保つ。
    - PL:  設計判断、実装の品質・一貫性の担保。規約を守る。
    
    進め方は「マイルストーン承認型」: 各マイルストーン着手前に要点だけ提示して承認を取る。
    内部の細部は自律実行。重大な後戻りコストのある判断のみ都度確認する。
    
    ## プロダクト概要
    地点の訪問を「楽しく・ゆるく」記録する個人向けアプリ。
    ソーシャル機能なし、完全ローカル、Android(Google Play)配信。
    要件の正典は docs/requirements.md。本ファイルと差異があれば本ファイルを更新する。
    
    ## 技術スタック(確定)
    | 領域       | 採用 |
    |------------|------|
    | フレームワーク | Expo (SDK 54+) + expo-router |
    | 言語       | TypeScript |
    | 永続化     | expo-sqlite |
    | 状態管理   | zustand |
    | 図形描画   | react-native-svg |
    | 地図       | MapLibre + OSM ラスタータイル(APIキー・課金登録を避けるため採用) |
    | 広告       | react-native-google-mobile-ads(AdMob バナー) |
    - バックエンドなし(要件: オフライン動作・ローカル保存)。
    
    ## データモデル(SQLite)
    - places   -- 地点マスタ(初回起動時にシード)。無効化は物理削除せず is_active=false で残す
    - visits   -- id PK, place_id FK, visited_at(ISO), memo(nullable)
    - 地点別の訪問回数 = visits を place_id で COUNT
    - 都道府県別集計 = visits × places.prefecture
    - 訪問済み判定 = その地点の visits が 1 件以上
    
    ## スコープ外(PdMとして死守)
    ユーザー間シェア・ランキング / 写真添付 / バッジ・実績 / 経路案内・ナビゲーション。
    → 実装提案・着手はしない。要望が来たら「スコープ外」と明示して合意を取る。
    
    ## トークン消費を抑える運用規約(最優先の作法)
    1. 再探索しない: 現状は本ファイル+docs/roadmap.md が真実。まずこの2つを読む。
       「念のため」のコードベース全体スキャンをしない。
    2. 大きいファイルを全文読まない: 統計は `python -c` / `jq` で算出、スキーマは先頭数件のみ。
    3. 狙い撃ち検索: Glob / Grep をピンポイントで。広い Read より範囲指定 Read。
    4. 編集は Edit: 既存ファイルは full rewrite せず差分で。
    5. 独立呼び出しは並列: 依存のないツール呼び出しは1メッセージにまとめる。
    6. 進捗は roadmap.md に追記: コードから再導出せず、チェックボックスを更新して引き継ぐ。
    7. サブエージェントは原則使わない: コールドスタートで文脈再構築するため高コスト。
    8. 計画は簡潔に: マイルストーン承認は要点を箇条書きで。長文設計書を都度生成しない。
    9. セッション終了時: 変更点と次アクションを docs/roadmap.md に1〜数行で残す。
    
    ## デザインシステム
    新規画面・機能を作るときは必ず docs/design-system.md を読み、
    src/theme/tokens.ts のトークンを使う(色・余白を画面にハードコードしない)。
    共通アトムは src/components/。タブ構成は確定(変更時は要承認)。
    
    ## ディレクトリ規約
    src/app/            expo-router ルート(Stack → Tabs)
    src/theme/tokens.ts デザイントークン
    src/components/      共通UI
    src/db/             expo-sqlite スキーマ・シード・クエリ
    src/store/          zustand ストア
    assets/             同梱データ・アイコン・スプラッシュ
    
    ## コマンド
    npm start         # 開発起動
    npm run android   # Android 実機/エミュ
    npx tsc --noEmit  # 型チェック
    現在のフェーズ・残タスクは docs/roadmap.md を参照。

    これで全部です。短いでしょう? 長く詳しく書くほど良い、というものではありません(これは後で理由を書きます)。

    なぜこう書いたか ― 効いている3つのポイント

    全部を解説すると長くなるので、特に効いている3つだけ。

    1. コマンドを一番上のほうに置く

    「どう動かすか」(起動・ビルド・型チェック)は、Claude Code が最も頻繁に参照する情報です。ここの精度が、そのまま作業効率に直結します。

    逆にここが曖昧だと、Claude は存在しないコマンドを叩こうとしたり、間違ったやり方でビルドしようとしたりします。一番参照されるものを、一番わかりやすく書く。 地味ですが、いちばんコスパの良い投資です。

    2. 「やらないこと」を明記する

    個人開発の CLAUDE.md で、私がいちばん効くと思っているのがこれです。

    Claude は親切なので、放っておくと「ログイン機能つけましょうか?」「ランキング機能あると盛り上がりますよ」と、こちらの設計思想に反する提案を善意でしてきます。 それ自体は悪気のない優秀さなのですが、個人開発では脱線が一番のコスト。

    だから「スコープ外」を明示しておく。シェア・ランキング / 写真添付 / バッジ・実績 … と書いておくだけで、提案ごと止まります。「完全ローカルでシンプルに完結させる」という思想はコードからは読み取れないので、ここに言葉で残す価値が高い。

    3. lint で済むことは書かない/とにかく短く保つ

    CLAUDE.md は毎セッション読み込まれます。つまり長いほど、1行あたりの効き目が薄まる。

    「インデントは2スペース」みたいな、Prettier や ESLint が機械的に守れることを CLAUDE.md に書くのは無駄です。フォーマッタに任せればいい。AI にやらせると遅くて不正確だし、なにより肝心のルールが埋もれます。

    私が毎回やっている取捨選択の基準はこれです。

    「この1行を消したら、Claude がミスするか?」

    ミスしないなら消す。これだけで CLAUDE.md は引き締まります。実際、私のファイルが短いのはこの基準で削り続けているからです。

    実体験:「設計だけして」が、なかなか通じなかった

    CLAUDE.md の役割定義の中に、こっそりこう書いてあります。

    進め方は「マイルストーン承認型」: 各マイルストーン着手前に要点だけ提示して承認を取る。

    これは、私の実体験から生まれたルールです。

    CLAUDE.md を整える前、私がいちばん困っていたのが、「設計だけ相談したい」のに、Claude が勝手に実装まで走り出してしまうことでした。「この画面の構成どう思う?」と聞いただけのつもりが、気づいたらファイルが何個も作られていて、コードが書き上がっている。方向性が違ったら全部やり直し、という手戻りが何度もありました。

    優秀すぎて手が早い、とも言えるのですが、個人開発では「手戻り」が一番のコストです。

    そこで「マイルストーン承認型」を明記しました。着手前に要点だけ出して、私の承認を取ってから動く。 細かい実装は任せるけれど、方向を決める所では必ず一度止まる。これを入れてから、「設計だけのつもりが、実装が走っていた」が起きなくなりました。

    ポイントは、これも結局「やってほしくないこと(=勝手に進めないこと)」を言語化しているだけ、ということです。AI は、止め方を教えないと止まりません。

    おまけ:地図ライブラリを MapLibre に変えた話

    スタックの表に、さらっと「地図 = MapLibre + OSM(APIキー・課金登録を避けるため採用)」と書いてあります。これ、個人開発者には地味に刺さる話だと思うので少しだけ。

    最初は素直に Google Maps 系のライブラリを入れていました。でも個人開発でやってみると、APIキーの発行や課金情報の登録が地味にハードルになる。「無料枠で足りるとはいえ、カード登録したくないな…」というやつです。

    そこで、APIキー不要・課金登録不要の MapLibre + OpenStreetMap タイルに途中で差し替えました。こういう「個人開発だからこその技術選定」も、CLAUDE.md に理由ごと残しておくと、後から Claude が「やっぱり Google Maps に戻しましょうか」と蒸し返してこなくなります。判断は理由とセットで記憶させる。

    これは、私の「型」の一部です

    ここまで読んでくれた人なら気づいたかもしれませんが、この CLAUDE.md は単体で完結していません。何度も docs/roadmap.md が出てきます。

    実は、CLAUDE.md は私がアプリを最後まで作り切るための「型」の入口の一部品にすぎません。本当に効いているのは、

    • CLAUDE.md(プロジェクトの記憶)

    • roadmap.md(セッションをまたいで進捗を引き継ぐ仕組み)

    • マイルストーン承認型の進め方(AI に長丁場を走らせるやり方)

    この3つの組み合わせです。CLAUDE.md だけ真似しても、たぶん途中で迷子になります。

    この「型」全体の話は、別の記事「アプリ開発は専門知識より『進め方』だった ― AIと作る私の型」に書いています。専門知識より進め方が効く、という私の実感の話です。あわせて読んでもらえると、この CLAUDE.md がなぜこの形なのかが腑に落ちると思います。

    おわりに

    CLAUDE.md は、凝ったものを作る必要はありません。むしろ短く、削って、「この1行は本当に要るか?」を問い続けるほうが効きます。

    まずは自分のプロジェクトでも、npm start などのコマンドと「やらないこと」を数行書くところから始めてみてください。それだけで Claude Code の挙動が変わるのが体感できるはずです。

    開発の過程は X でも build in public で発信しています。AIと一緒に個人開発を進める様子をリアルタイムで流しているので、よければのぞいてください。

    X: @matsu_ai_proc


     
     

    matsu

     
     
    本業のかたわら、AIを相棒にReact Nativeでアプリを開発し、Google Play公開・収益化に挑戦中。「AIがあれば専門外でも個人開発は形になる」を実証していきます。進捗・失敗談・売上を公開中🌲 X→@matsu_ai_proc

    あなたへのおすすめ