logo
Search

Follow me!

AI

仕様書を「渡す」からCLAUDE.mdを「育てる」へ — Claude Codeの使い方が変わった話

#claude code #Prompt Engineering #Context Engineering
Apr 2nd 2026
仕様書を「渡す」からCLAUDE.mdを「育てる」へ — Claude Codeの使い方が変わった話

Claude Codeを使い始めたとき、私は仕様書のMarkdownを丸ごとコピペして「この通りに実装して」と指示していた。結果は散々だった。いま最も手をかけているプロジェクトでは、CLAUDE.mdが146行、ルールファイル12本、スキル31個にまで育っている。仕様書を「渡す」から、CLAUDE.mdを「育てる」に切り替えたことで、Claude Codeの使い勝手がまるで変わった。

CLAUDE.mdの基本をおさらいする

本題に入る前に、CLAUDE.mdの基本を簡単に振り返る。

CLAUDE.mdはClaude Codeがセッション開始時に自動で読み込む設定ファイルである。プロジェクトルートに置くだけで、毎回のセッションで自動的にコンテキストとして注入される。

読み込みには3つの階層がある。

  • グローバル（~/.claude/CLAUDE.md）: 全プロジェクトに共通する個人の好み
  • プロジェクト（プロジェクトルート/.claude/CLAUDE.md）: リポジトリ固有の文脈
  • サブディレクトリ（各ディレクトリのCLAUDE.md）: 領域固有の設定

新しいチームメンバーに渡す「業務マニュアル」のようなものだ。これがないと、Claude Codeは毎回ゼロからプロジェクトを理解しようとする。

ここまでは入門レベルの話で、すでに解説記事も多い。この記事で書きたいのはその先、CLAUDE.mdを「完成させるもの」ではなく「育てるもの」として扱う考え方についてである。

仕様書丸投げが失敗する構造的な理由

Claude Codeに仕様書Markdownを丸ごと貼り付けて「この通りに実装して」と指示すると、3つの構造的な問題が起きる。

1. コンテキスト過負荷で重要部分が埋もれる

LLMのコンテキストウィンドウには物理的な上限がある。1万行の仕様書を渡した場合、モデルの注意が全体に散らばる。人間なら「ここが重要」と読み飛ばせるが、LLMにはその取捨選択が難しい。仕様書の後半に書いた制約条件が実装に反映されない、というのはよくある話だ。

2. 既存コードのパターンを無視する

仕様書を「正」として渡すと、Claude Codeは既存のコーディングパターンより仕様書の記述を優先する。プロジェクトではcamelCaseを使っているのに、仕様書にsnake_caseの例が含まれていればそちらに引きずられる。既存コードとの一貫性が崩れるのは、だいたいこれが原因だ。

3. 複数ファイルの整合性が崩れる

仕様書は往々にして複数の機能を横断的に記述している。「認証フロー」の仕様にはフロントエンド・バックエンド・DB設計が混在する。Claude Codeはこれを一度に処理しようとして、ファイル間の依存関係を見失う。型定義とAPIレスポンスの不整合、importの漏れ、テストとの乖離が生まれる。

プロンプトの書き方が悪いのではない。仕様書を丸ごと渡すこと自体に無理がある。

「渡す」と「育てる」は何が違うのか

仕様書を「渡す」とは、セッションのたびにコンテキストを入れ直す作業だ。セッションが終われば消える。次のセッションではまた同じ説明。チームで使っていれば、人によって渡す内容がバラバラになり、出力の品質もバラつく。

CLAUDE.mdを「育てる」とは、プロジェクトの前提知識をファイルに残していくことだ。一度書けば全セッションで勝手に読み込まれる。gitに入れておけばチーム全員が同じ前提で作業できる。プロジェクトが進むにつれて、CLAUDE.md自体も一緒に育っていく。

要するに、**仕様書は「その場限りの指示書」、CLAUDE.mdは「育つ業務マニュアル」**だ。

実践: 「間違えたら追加」ルール

では、CLAUDE.mdをどうやって「育てる」のか。

Claude Codeの開発に携わるBoris Chernyのチームは、約100行のCLAUDE.mdをgit管理し、「Claudeが間違えたらCLAUDE.mdに追加する」をチームルールにしているらしい。このやり方がシンプルで強い。

私もこのアプローチを採用した。具体的なプロセスはこうなる。

  1. Claude Codeに作業を依頼する
  2. 出力が期待と異なったら、「何が足りなかったか」を特定する
  3. その情報をCLAUDE.mdに追加する
  4. 次のセッションから同じ間違いが起きなくなる

例を挙げる。初期のCLAUDE.mdにはディレクトリ構造しか書いていなかった。あるとき、Claude Codeが新しいファイルをcontent/articles/直下に作成した。実際にはcontent/articles/drafts/に置くべきだった。そこで「コンテンツの成長フロー」をCLAUDE.mdに追加した。

## コンテンツの成長フロー

brainstorm → ideas → notes → articles
（ブレスト  → 思いつき → 学習・整理 → 公開記事）

これ以降、Claude Codeはファイルを正しい場所に配置するようになった。

別の例。Claude Codeがレビューで毎回同じ観点を見落としていた。「セキュリティレビューが必要なのはauth関連のファイル変更時」「パフォーマンスレビューが必要なのはDB関連の変更時」。こういう判断基準をルールファイルとして追加した。

このプロセスのポイントは、CLAUDE.mdの完成形を最初に設計しようとしないことだ。実際に間違いが起きてから追加する。必要なものだけが残る。

育てるCLAUDE.mdの3つの原則

使い続ける中で、意識するようになったことが3つある。

原則1: 「コードを読めばわかるか？」で判断する

何を書いて何を書かないか。判断基準はひとつ、「この情報はコードを読めばわかるか？」だ。

  • Yes → 書かない: 技術スタック、ライブラリのバージョン、関数の引数仕様。これらはコードから読み取れる
  • No → 書く: なぜこの技術を選んだか、どんなワークフローで運用しているか、ファイルの命名規則。これらはコードに表現されていない

例えば「React + Next.jsのプロジェクト」はpackage.jsonを見ればわかる。書く必要はない。一方「週次レビューはNotionからJSON抽出して/weekly-reviewスキルで生成する」はコードのどこにも書かれていない。CLAUDE.mdに書く価値がある。

原則2: 仕様書はチケット単位で渡す

仕様書を全廃する必要はない。「渡し方」を変えればよい。

仕様書をGitHub IssuesやLinearのチケット粒度に分解する。1チケット = 1機能。各チケットには「何を」「なぜ」「受け入れ基準」だけ書く。実装方法は書かない。既存のコードパターンに合わせるかどうかはCLAUDE.mdが教えてくれる。

# チケット: ログイン画面にパスワードリセット機能を追加

## 何を
パスワードリセットのフローを追加する

## なぜ
ユーザーサポートへのパスワードリセット依頼が月50件ある

## 受け入れ基準
- メールアドレス入力 → リセットリンク送信 → 新パスワード設定の3ステップ
- リセットリンクの有効期限は24時間
- 既存の認証フローと同じUIコンポーネントを使用する

「どう実装するか」はClaude Codeがコードベースとルールファイルから判断する。

原則3: 薄く保ち、分離で拡張する

CLAUDE.mdは薄く保つ。100行を超えたら分離を検討する。

Claude Codeは.claude/rules/ディレクトリに置いたMarkdownファイルを自動で読み込む。コーディング原則、レビューポリシー、外部ツール連携の設定。関心事ごとにファイルを分けて、CLAUDE.md自体はプロジェクトの概要とワークフローに絞る。

繰り返し使うワークフローは.claude/skills/としてスキル化もできる。「週次レビューを生成する」「SEO記事を書く」「YouTube台本を作る」。こういったものを個別ファイルに切り出していくと、CLAUDE.mdはスキル一覧表のように簡潔に保てる。

あるプロジェクトでCLAUDE.mdが育った過程

最も手をかけている個人プロジェクトの変遷を例に出す。

初期（20行）: プロジェクト概要とディレクトリ構造だけ。「このプロジェクトは個人のデジタルガーデンです」「content/以下にarticles, notes, ideasがある」程度。

60行: コンテンツの成長フロー（brainstorm → ideas → notes → articles）を追加。情報収集の日次/週次/月次サイクルを定義。ファイル命名規則も追加。きっかけは、Claude Codeがファイル名を統一的に付けてくれなかったこと。

478行に膨張: スキルの定義、レビューポリシー、外部CLI連携の設定を全てCLAUDE.mdに書き込んだ。やりたいことが多く、あれもこれもと詰め込んだ結果こうなった。毎セッションのコンテキストウィンドウを大量に消費していた。

146行に圧縮 + 分離: さすがに限界を感じて整理した。478行を146行に圧縮し、残りを.claude/rules/（12ファイル）と.claude/skills/（31スキル）に分離。CLAUDE.mdはプロジェクト概要・ワークフロー・スキル一覧だけを保持する「目次」になった。

現在: CLAUDE.mdは146行で安定。新しいルールやスキルが必要になれば、CLAUDE.mdではなく専用ファイルに追加する。ルールファイルやスキルファイルは日常的に更新しているが、CLAUDE.md自体はたまにしか触らない。

振り返って思うのは、膨張は通過点だったということ。最初から分離設計する必要はない。まずCLAUDE.mdに全部書いて、大きくなったら分ける。この順番が結局いちばん自然だった。

もうひとつ、行数はそのままメンテナンスコストになる。478行のCLAUDE.mdは、何がどこに書いてあるか把握しきれなかった。146行なら一読で全体像がつかめる。

まとめ: CLAUDE.mdは「完成」しない

CLAUDE.mdは完成しない。プロジェクトが続く限り、育ち続ける。

仕様書を毎回渡すのは、セッションごとにリセットされる繰り返しだ。CLAUDE.mdを育てていけば、プロジェクトの知識がファイルに残り続ける。

やることはシンプルだ。

  1. 今日から始める: CLAUDE.mdがなければ、プロジェクト概要を10行書くところから
  2. 間違いを燃料にする: Claude Codeが期待と異なる出力をしたら、足りなかった情報をCLAUDE.mdに追加する
  3. 膨張したら分離する: 100行を超えたら.claude/rules/への切り出しを検討する
  4. チケット単位で渡す: 仕様書を丸ごと渡さず、「何を」「なぜ」「受け入れ基準」に分解する

CLAUDE.mdは「渡すファイル」ではない。プロジェクトと一緒に育てていくものだ。

関連記事

Comments