Claude.md運用で何を書き何を書かないか
『実践Claude Code入門——現場で活用するためのAIコーディングの思考法』を読んで最初に手を動かしたのが、urisol.com と urinosuke.com のリポジトリに置く Claude.md の整備だった。
本書の第3章「Claude.mdによるプロジェクト固有知識の注入」で示されているのは、プロジェクトのコンテキスト・制約・設計方針を1つのファイルに集約し、Claude Code が毎回それを読み込む前提で会話を始められるようにする仕組み。単体ツールとしてClaude Codeを使う段階から、チーム開発・複数プロジェクト並走・長期メンテナンスを見据えた設計に移行するための橋渡しとなる概念だった。
Claude.md に何を書くかは、プロジェクトの性質によって変わる。本書では「技術スタック・ディレクトリ構造・命名規則・禁止事項」を軸に構成する例が示されていたが、私の場合は urinosuke.com が「個人発信のブログ」であり、技術的制約よりも「著者の立場・発信スタンス・書いてはいけないこと」の明文化が優先された。
実装した Claude.md の構成は次の3層になった。
- 技術スタック層：Astro 5.2 + Cloudflare Pages + TailwindCSS という構成と、Content Collections のスキーマ定義
- 発信スタンス層：著者事実台帳（年齢・キャリア・事業構造・資格）と、書いてはいけないこと（年齢の断定禁止・未実施収入の事実化禁止・製油所名の特定禁止など）
- 運用制約層：記事生成スクリプト（generate-post.py）が読み込む前提の設計であること、アフィリエイトリンクのテンプレート、読了書籍リストからの引用必須ルール
本書の指摘通り、Claude.md は「プロンプトの前提」として機能するため、ここに書いた内容は毎回の会話で自動的に参照される。逆に、ここに書かなかった情報（例：最新の投稿タイトルリスト、テーマバランスの集計結果）は、スクリプト側で動的に生成してプロンプトに差し込む設計にした。
Claude.md に「すべて」を書こうとすると肥大化してコンテキストを圧迫するため、「毎回必ず参照する不変の前提」だけをClaude.mdに置き、「実行ごとに変わる変数」はスクリプト側で注入する分離設計が有効だった。
失敗事例の言語化が設計改善の鍵になる
本書の第5章「失敗から学ぶClaude Code導入」で最も参考になったのは、著者たちが実際に遭遇した失敗を「なぜ起きたか」「どう回避するか」の構造で言語化している点だった。
特に印象に残ったのは「コンテキスト不足によるハルシネーション」と「指示の曖昧さによる意図しない実装」の2つ。前者は Claude.md や参照ファイルの不備、後者はプロンプト設計の甘さが原因だが、どちらも「事前に構造を整えれば防げた」失敗だという指摘が、自分の運用設計を見直すきっかけになった。
私が遭遇した具体的な失敗は次のようなものだった。
- 未読書籍の捏造紹介：記事生成時に「読了書籍リスト」を参照する仕組みを作る前、Claude Code が記事テーマに合わせて「読んだことにして」書籍を紹介するケースが数回発生した。著者事実台帳に「ここに載っていない書籍は記事で引用・紹介してはいけない」と明記し、generate-post.py が毎回リストを読み込んでプロンプトに差し込む設計に変更した。
- 数値設定の改変：「38歳・FI目標50歳・年間配当200万円」という著者の現在地を、記事都合で「45歳リタイア」「60歳目標」等に勝手に改変されるケースがあった。Claude.md に「著者事実台帳の数値設定を記事都合で改変しない」と禁止事項として書き、さらに「50歳ゴール・12年スパン」のフレームを守ることを必須条件に追加した。
- 存在しないURLの捏造：参考リンクとして「公式サイトの深い階層のPDF」を推測で書かれるケースがあった。Claude.md に「存在しないURLを参考リンクとして書かない。確実なものだけ書く」と明記し、公式サイトのトップ階層に留める方針に変更した。
本書が繰り返し強調しているのは、「失敗を記録し、なぜ起きたかを言語化し、Claude.md や運用ルールに反映する」サイクルを回すことの重要性だった。私の場合、失敗が発生するたびに著者事実台帳の「書いてはいけないこと」セクションを更新し、generate-post.py の入力検証（未読書籍チェック・数値整合性チェック）を追加していった。
この「失敗→言語化→ルール化」のサイクルは、本書の第6章「評価とフィードバックループ」で示されている継続的改善の考え方と一致していた。
チーム導入を見据えた設計の実務論点
本書の後半（第7章・第8章）は、Claude Code を個人ツールから「チームで使う前提」に移行するための実務論点が中心になっている。私は現在、個人事業＋法人併営で実質一人で回しているため、「チーム導入」は直接的には該当しないが、将来的に外注ライター・編集者・エンジニアと協働する可能性を考えると、今の段階で「再現可能な設計」にしておく意味は大きかった。
本書が指摘する「チーム導入の障壁」は次の3つに整理されていた。
- コンテキスト共有の難しさ：個人の暗黙知に依存した会話では、他のメンバーが同じ結果を再現できない
- 品質のばらつき：プロンプト設計が属人化すると、出力の品質が人によって変わる
- 運用ルールの不在：「どこまでClaude Codeに任せるか」「人が必ず確認する箇所はどこか」が明文化されていないと、責任の所在が曖昧になる
これらを回避するために、本書が推奨しているのが「Claude.md + サブエージェント設計 + 評価指標の明文化」の3点セットだった。
私が実装したのは次のような設計。
- サブエージェント化：記事生成（generate-post.py）・画像生成（将来実装予定）・校正（将来実装予定）をそれぞれ独立したスクリプトとして分離し、各スクリプトが固有の Claude.md セクションを参照する構造にした。本書の第4章「サブエージェント設計パターン」で示されている「責務の分離」を意識した設計。
- 評価指標の明文化：記事生成の成功条件を「1,500〜2,500文字・H2見出し3〜5個・読了書籍リストから1冊以上引用・アフィリエイトリンク併記・禁止事項違反ゼロ」として Claude.md に書き、generate-post.py の出力検証関数がこれを機械的にチェックする設計にした。
- 運用ルールのドキュメント化：「記事の最終確認は必ず人が行う」「公開前に著者事実台帳との整合性を目視確認する」「アフィリエイトリンクの形式を自動テストで検証する」といった運用フローを README.md に明記した。
本書の第8章「スケーラブルな運用設計」で強調されているのは、「個人で使っているうちに設計を固めておくと、チーム導入時の移行コストが下がる」という点だった。現時点では一人運用だが、将来的に外注ライター・編集アシスタント・エンジニアと協働する際に、「Claude Code + generate-post.py」の仕組みをそのまま渡せる状態にしておくことで、引き継ぎコストを下げられる。
本書を読んで得た最大の学びは、「Claude Code は単体ツールではなく、プロジェクトの設計思想を反映するインターフェース」だという視点だった。Claude.md・サブエージェント・評価指標の3層を整備することで、個人の暗黙知に依存しない再現可能な発信基盤を作れる。