開発mdx-playground

きっかけ

朝、X のタイムラインで Anthropic 公式ブログの "How Claude Code works in large codebases: best practices and where to start" が流れてきた。Claude Code を毎日触っているのに、公式が想定しているベストプラクティスを一度も腰を据えて読んでいなかった。読んだうえで、自分のセットアップとの差分を Claude Code に洗い出させる、というのを朝の作業に決めた。

WebFetch は1秒で諦めた

まず WebFetch で取りに行った。返ってきたのはタイムアウトと SSL のエラーで、本文がひとつも降ってこない。グローバルルールに「WebFetch が失敗したら即座に agent-browser に切り替える」と書いてあるので、迷う余地もなく次のコマンドに移った。

agent-browser open "https://www.anthropic.com/engineering/claude-code-best-practices"
agent-browser wait --load networkidle
agent-browser eval 'document.body.innerText'
agent-browser close

自分のログイン済み Chrome を踏ませる方式が一発で本文を吐き出した。WebFetch でユーザーに「コピペして渡してください」と頼みかける癖が以前あったが、それを禁じてからのフォールバック動線が今日もそのまま機能した。

差分を Claude Code に列挙させる

本文を渡したあと、Claude Code に「この記事の主張と、自分の ~/.claude/ と mdx-playground/.claude/ の現状とで、ズレている箇所だけ列挙して」と依頼した。返ってきたのは A〜F の6項目で、それぞれに「やるべき理由」がついていた。一つずつ「やる/やらない」を自分で決めて、やると決めたものだけ Claude Code に実装させた。

A案: CLAUDE.md の階層化

公式の主張は「CLAUDE.md は短く、作業ディレクトリに近い場所に置け」。一方こちらは、モノレポルートの CLAUDE.md に Nuxt 固有のコマンドや検証チェックリストまで全部詰め込んでいた。apps/api/ 配下で作業するときも、関係ない Nuxt の話が毎回コンテキストに乗ってくる構造だった。

やったこと:

  • モノレポルートの CLAUDE.md を「全体で守るべき critical warning とルール所在マップ」だけにダイエット
  • apps/web/CLAUDE.md を新設して、Nuxt のコマンド・Chrome DevTools MCP の使い方・ディレクトリ構成の要点を移動
  • 実装後チェックリスト、アーキテクチャ詳細、windows.md などは .claude/rules/ 配下に切り出してポインタで参照

結果、apps/web/ 配下で作業を始めると、ツリーを遡って2枚の CLAUDE.md が自動でロードされる。apps/api/ で作業しているときは Nuxt 側の情報が混ざらない。

B案: permissions.deny で機密ファイルを物理的に遮断

公式ブログには「リスクのある操作は permissions.deny で禁止せよ」と書いてあった。こちらは .env の読み取り禁止を CLAUDE.md の文章で約束させていただけで、設定ファイルでブロックしていなかった。文章のルールはモデルが疲れてくると守られなくなる可能性がある。

settings.json の permissions.deny に .env 系のファイル読み取りパターンを追加した。「読まないでね」のお願いから、「そもそも実行できない」への昇格。プロンプトインジェクションで .env を読まされる攻撃面も塞がる。

C案: 学びを CLAUDE.md に貯める仕組み

公式が一番面白かったのはここで、「Stop Hook で会話の最後に毎回、今回の学びを CLAUDE.md 追記候補として吐かせる」という運用が紹介されていた。ただ Stop Hook で完全自動化すると、未検証の追加が CLAUDE.md に流れ込んで肥大化するリスクがある。

そこで手動版に降ろした:

  • /reflect-session というスラッシュコマンドを新設
  • セッションを振り返り、CLAUDE.md / Skill / Hook に昇格すべき学びの候補を抽出する
  • 出力先は memo/claude-md-candidates/{YYYY-MM-DD}.md に蓄積するだけで、本体には書き込まない
  • 翌朝なりに候補を読み返して、本当に常時持たせるべきものだけ手で昇格させる

実際に今日のセッションで /reflect-session を叩いて、当日2件の候補が抽出された。1つは「WebFetch 失敗時の agent-browser フォールバックは既に習慣化しているのでルール化済み」と確認できて、もう1つは「/reflect-session 自体の運用ルール」だった。後者は明日の自分が判断する。

Stop Hook で自動化するかは、しばらく手動運用してみてから決める。

D案: モデル固有の指示を隔離する

公式の指針には直接書かれていなかったが、Claude Code に「自分の CLAUDE.md を読んで気になる点」を聞いたときに出てきた指摘がここ。今の Claude Opus 4.7 向けに「応答が短くなりがちなので詳細出力を明示」「サブエージェント生成を抑制する傾向があるので並列化したい場面では明示」といった対話戦術が ~/.claude/CLAUDE.md 本体に混ざっていた。

モデルが上がるたびに、この戦術は古くなる。一方で本体の CLAUDE.md に書いてしまうと、消し忘れが発生する。

~/.claude/rules/opus-4.7-tactics.md に切り出して、ファイル冒頭に「Claude Opus 4.8 以降に上がったら、その時点での挙動を観察してから内容を見直す（または丸ごと削除する）」と明記した。本体 CLAUDE.md からはポインタで参照するだけ。次にモデルが上がったとき、このファイルを開けば「これは旧モデル向け」と一目でわかる。

E案: Skill にパス制約を加える

公式ブログは Skill の使い方そのものには深く触れていなかったが、自分の環境を見直すと、関係ない作業中に Skill が誤発火する場面が増えていた。たとえば apps/web/ のテストを書いているのに、cf-worksheet-repair のような特定パス専用の Skill が「精算表」というキーワードに反応して候補に上がってくる。

プロジェクト Skill の description に TRIGGER: と SKIP: の行を追加した:

  • TRIGGER: に発火対象の具体的なパス（例: apps/web/public/data/cashflow-worksheet/sheets/Q3-*.json）を書く
  • SKIP: に発火させない条件（無関係な JSON・他ディレクトリ）を明記

cf-worksheet-repair, data-generation, vue-pages の3つに適用した。Claude Code がスキル選択時にこの行を読んで、無関係な作業では発火しないようになる。

F案: AGENTS.md をポインタに変える

モノレポルートに AGENTS.md と CLAUDE.md の両方が置いてあり、内容がほぼ重複していた。Codex CLI が AGENTS.md を読み、Claude Code が CLAUDE.md を読むため、両方を維持していたが、片方を更新してもう片方を忘れる事故が何度かあった。

AGENTS.md を CLAUDE.md への薄いポインタに置き換えた。Codex 側で読まれたときに「メインの指示は CLAUDE.md にある」と誘導できる。二重管理が消えた。

ついでに片付けたこと

coverage/ ディレクトリが .gitignore に入っておらず、毎回ステージング候補に出てきていたのを修正した。これは公式ブログとは関係ないが、.claude/ まわりを整理するついでに気になっていた汚れを一緒に拭いた格好。

最後に作業記録を残す

memo/2026-05-18/claude-code-best-practices-alignment.md に、A〜F それぞれの「やる/やらない判断」「実施内容」「次のアクション」を書き残した。後日「あのとき D案でどう判断したっけ」と聞かれたときの参照元になる。

今日わかったこと

  • 公式ブログを読む → 自環境の差分を Claude Code に列挙させる → やる/やらないを自分が決める、というワークフローは1時間で6項目を捌けた
  • 文章のルール（「.env は読まないでね」）と設定ファイルのルール（permissions.deny）は別物。後者に昇格させられるものは昇格させる
  • 学びの自動採取は、まず候補ファイルに溜める手動運用から始める。Hook での自動化はその後で判断
  • モデル固有の対話戦術は別ファイルに隔離しておくと、モデルが上がったときに削除しやすい

公式の主張をそのまま写経するのではなく、自分のセットアップに照らして取捨選択する、というのが Claude Code を毎日使う側の責務だと改めて感じた。判断は自分、調査と実装は Claude Code、という分担が今日も機能した。