「さっき言ったよね？」が止まらない

Anthropic公式では「まずプランモードを使え」がベストプラクティス。
実際プランモードでは多くのサブエージェントをつかいプロジェクトを網羅的に検索してより深い考察をしてくれます。当然、提案してくれたプランはその深い考察を反映させたもの……と思いがちですが、実はそうでもありません。

"Yes, clear context and auto-accept edits"の罠

Claude Code v2.1.15あたりから導入された、プラン作成完了時の実装確認プロンプトの一番上、お気づきでしょうか。見たまんま/clearしてからプラン内容の実装を始める新モードです。
プラン作成のための調査で余計な情報が溢れたコンテクストで実装を始めるより、一旦リフレッシュした状態でプランのコンテクストのみで実装したほうがキレイなコードになる、っていうAnthropicの判断だと思います。それはわかる。

ただし、『指示がプランに正しく反映されている場合は』という条件付きです。

だめな例１：相談形式のプロンプト

多少誇張を含みます。実際にはコードベースで現実装を調べて提案してくれます

フロントを静的サイトにするかReactにするか悩んでいます。
SEO的には静的サイトが理想的ですが、どちらがいいでしょうか

→ CC「SEO目的のLPならSPAより静的サイトがいいですね」
→ 静的サイトを提案
→ clean and accept → 静的サイトで実装

やはりコンポーネントで動的にコンテンツを再利用できるようにしたいです。
良いやり方はないでしょうか？

→ CC「それならReactで再構築しましょう。」
→ ワイ「いやさっきSEO的にはよくない言うたやん？」

本来ならAstroなど静的サイトジェネレータをおすすめしてほしいところなんですけど、『SEOを優先して静的サイトを選んだ』という記憶は宇宙の彼方へさあ出発だ！してしまいました。

だめな例２：方針のコンフリクト

多少誇張を含みます。実際にはコードベースで現実装を調べて提案してくれます

宇宙っぽい未来チックなLPを制作してください
フロント全体のスタイリングはTailwindで統一してください。

→ CC「了解、Tailwindを使ってモダンなダークテーマで実装します。」
→ clear and accept → Tailwindで実装

（何セッションか後で）

ダッシュボードにグラフを追加したいです。

→ CC「ではd3.jsをつかいますね。」
→ インラインスタイルまみれのSVGが爆誕💥

これも『Tailwindで統一』を覚えていれば Chart.js などの選択肢があったはず。コンテキストが失われた結果の悲劇です。

話の流れでは出てきたが、確認プロンプトでは聞かれなかったもの
ClaudeCodeがPlan作成中にユーザが補足したプロンプトの内容

これらは高確率でプランに含まれていません。「プランに含まれなかった指示」は、1の"clear context and ..."では確実にスルーされます。
2番に格落ちした "Yes, auto-accept edits" はある程度会話の履歴を参照して提案できますが、"crear context and ..."が一番上に来ているということは……こちらを今後のスタンダードにするというAnthropicの方針なのではないかと推測します。

プランに捕捉したい場合はプラン完成まで待って、"No"でTabを押してプロンプトを入れるとプランの再構築をしてくれます。

対策法はありますけどプランファイルをじっくり読んで、うーんここ修整で、またしばらく待ってじっくり読んで……と、人間側の負担が小さくないやり方。

それなら自動で出来る対策を考えるまでです。

ADRという死文化：Decision と Constraint

2010年頃、アジャイル開発が普及するに伴い、変更の頻度が重要しされるように。開発頻度を上げるためにドキュメント更新の優先度は最低限になり、 「なぜこの変更をしたのか」 をチームメンバー誰も覚えてない問題が発生しました。

今のAIコーディングが抱える問題と似てますね。

ADRの様式はチームごとにさまざまだと思いますが、こんな感じのMarkdown形式で書きます。

# ADR-051: notification/event-bus-pattern
Value: Use in-process EventEmitter for MVP, migrate to Redis Pub/Sub for horizontal scaling
Layer: business
Tags: notification, event-bus, scaling
Rationale: Starting with Node.js EventEmitter avoids premature infrastructure complexity. The event interface is designed to be backend-agnostic so migration to Redis Pub/Sub requires only swapping the transport layer without changing business logic.
Alternatives: RabbitMQ, Apache Kafka, AWS SNS/SQS
Tradeoffs: EventEmitter limits to single-process which is sufficient for MVP but cannot scale horizontally. Redis Pub/Sub is the natural next step that balances simplicity with multi-instance support.
Created: 2026/1/27 10:56:13

「何を」「どういう理由で」変更や制限したのか、「トレードオフにしたもの」「検討対象」「今も有効か」という最低限の記録をMarkdownで残すことで、後から「Why?」を探せますし、ADRをみれば新規アサインメンバーのオンボーディングにもなるという、画期的な手法のはずでしたが……。

書くの忘れた
何書いたらいいのかわからない
調べたけど更新されてない
そもそも調べてない
何百ファイルも見てられない

そう、人類には早すぎる手法だったのです。

沼

人類にはムリ、ならばAIなら？

「ClaudeCodeが直接書けばいいじゃない！」
そう思ったのが沼の入口でした。以下は真似しなくていいです、解決策だけ知りたい方はsqlewの説明に飛んでください。

CLAUDE.mdにADRを書いたらいいのでは？

ClaudeCodeが一番重視しているのはユーザのプロンプトでも、Planでもなく、CLAUDE.mdです。コンテキストの最初に読み込まれ、自動コンパクトでも潰されずにセッション終了まで残ります。ということはここに書いたら最強では？と思い、

コードを変更する際は目的・理由をADRの形式でCLAUDE.mdに追記してください。

これで勝利確定！と思いきや……

リザルト

独りスクラムを3週間ほど続けてADRは200件程度に。あっという間にCLAUDE.mdが肥大化し、2000行を超えてしまいました。ClaudeCode起動直後に /contextを打ったら、システムプロンプトだけでコンテキストの30％使用していたのは衝撃的でした。。。

また、「似ている記録があったのでマージしておきました」「同様の記録を最新の情報に更新します」に気づかず、ADRの履歴情報が2割くらい消されたのもあり、この作戦はお蔵入り。

rulesに書いたらいいのでは？

CLAUDE.mdに生き残ったADRたちを、どうやったら守れるか。ぼんやりClaudeCodeのドキュメントを見ていたら
.claude/rulesを見つけました。

これぞ求めていた機能……！1ファイルずつ書かせれば最悪Gitでrevertもできるし！勝確！と思いきや……

リザルト

rulesフォルダ内のMarkdownって、結局全部読み込まれるんですよ。ファイルが分かれている分のオーバーヘッドもあるようで、起動時のシステムプロンプトのコンテキスト使用量が32％に増えていました。また、勝手にマージや更新の問題も変わらず。

CLAUDE.mdやrules/*.mdは、毎ターン全文読み込まれてプロンプトの前に挿入され、その全文がAPIへ送られてトークン消費します。つまり2ターンでコンパクトが走る、最悪中の最悪手でした。

お作法通り `docs/adr/` に作成してみた

システムプロンプトにADRを挿入するのはよくない事を身を持って知りました。
ClaudeCodeへのルール強制力は落ちてしまいますが、ADRの一般的な方法で、docs/adr/051-Use-JWT.mdのように、専用フォルダに1記録1ファイルで書いていきます。

プランのたびにこのフォルダを調べ、実装前に連番でADR文書を作成するようにCLAUDE.mdに記載しました。

リザルト

一見うまくいっているようだったんですけど、使っていくうちに課題がたくさん見えてきました。

言われないと読まない
- お前は人間か
FindやGrepなので探しきれてない
- お前は人間か
Markdown好きすぎて要らないのも全部読もうとする
- お前は試験前の人間か
しこたま読んだうえで、コンパクトが走って忘れる
- 人間か

問題は読み込みだけでなく、

内容重複したADR文書が作られる
やっぱり似た内容のバージョン違いをマージしちゃう
過去のADRと矛盾する内容も書いてしまう

最後の1個はADRとしては致命的です。

Skillsで頑張ってみた

そうしてるうちに、ClaudeにSkillsの仕組みが導入されました。

必要なときだけ読み込まれる → 読み込み地獄から解放される……？
プロンプトとして実行される → Markdownと違って忘れられない……？

ひょっとしてADRを1つずつをSkillにしたらいけるか？と試してみましたが、

作成したSkillsはClaudeCodeを再起動しないと認識されない
Skillsが使われるかどうかは確実ではない
- ADR-authenticate-method などのSkill名だと「認証したい時に使うんだな」と思われる模様
プロンプトを入れても無視されがち
- 呼び出し元エージェントがSkillで何をしていたかをあまり見ていない（投げっぱなし）
- サブエージェントの一種として捉えられている？
ADRの重複・矛盾はやっぱり起こる

リザルト

.claudeフォルダが汚くなっただけでした。
この辺でClaudeCode純正機能ではどうにもならない問題と思いましたので、MCPでADRの仕組みを作ることに方針転換しました。

本題：ClaudeCodeをわからせする

ClaudeCodeでADRをうまく扱えなかった原因は

Markdownだと要らないものも全部読もうとする
- 必要なものだけ検索で取得できたら……
  - RDBでいけるのでは？
必要なタイミングで強制的に読ませたい
- システムプロンプト以外は強制力が無い
  - テンプレだけシステムプロンプトに書いたらいいのでは？
  - テンプレをHooksで抽出したらいいのでは？

それで出来たのがこちらです。

動作説明は省きます、ソース見てね♥

インストールは簡単3ステップです。

npm i -g sqlew

claude plugin marketplace add sqlew-io/sqlew-plugin
claude plugin install sqlew

Planモードで自動わからせ

sqlewはフツーのMCPとしてADRを1個ずつ登録することもできますが、ClaudeCodeのPlanモードで真価を発揮します。
いつも通りPlanモードで何か指示をしてみてください。

サブディレクトリ内でclaude、あとはREADMEのプロンプトを実行してみてください。

まずプロンプトの内容からキーワードを類推し、関連しそうなADRをサジェストさせるフックが走ります。

その内容を参考に、Planツールくんがあたりをつけてからコードベースで実装調査。

Planファイル上部に関連ADRと、 📌Decisions / 🚫Constraints が挿入されていれば成功。Planファイルをフックが解析・抽出してデータベースに登録、自動的にプロジェクトのナレッジベースが育っていきます。

次回以降、Planモードを使えば自動でサジェストが走り、重複実装や矛盾をAIが自発的に気づいてくれる、というたてつけです。

※自動ADR機能はいまのところClaudeCode専用です

sqlewでわからせたClaudeCodeの実力

検索が速い

通常のPlanモードでもコードベースで実装を調べてくれますけど、ある程度実装が進んだプロジェクトだと、標準のFindやGrepだと数分待たされることもしばしば。
ADRが与えられているとExploreエージェントくんが「だいたいこのへんかな」で探してくれるようになるので、速いです。

漏れが少ない

「完全に漏れがない」とまではいかないんですけど、「関連ADRにこういう設計情報があリます。新しく実装する機能の中間レイヤーも作りますか？」など、気の利いた確認プロンプトを投げてくれるようになります。

カブリが無い（重要）

サンプルプロジェクトで後述しますけど、重複実装はほんとに減ります。無駄なリファクタリングや手戻りが減るので、トータルで見るとトークンも時間もかなり節約できます。

動作例

MCP Directory登録用に作成したサンプルリポジトリ↓を試してみてください。

サンプルプロジェクト01 ADR手動登録

プロンプトで決定事項をsqlewに登録し、次に矛盾した内容でPlanを作らせるテストです。

指示はこうですけど、sqlewのADRではこう書いています。
既存のADRの内容で作りますか？それともADRを更新しますか？

と、質問プロンプトを投げてきます。

サンプルプロジェクト02 ADRドリブン

ADRが既にいくつか入っているデータベースだけがある空のプロジェクトです。そこへ、ざっくりな要件定義書を与えるテストです。
登録済みADRを調べて以下の5個がサジェストされ、実装計画に反映されます。

サンプルプロジェクト03 DRY厳守

重複実装を指示しているパターンです。
こんなに分かりやすく2連続で重複する事は現実にはないでしょうけど、1週間後だったら？1ヶ月後だったら？稀によくありますよね。
sqlewからのサジェスト内容を読んで、ClaudeCodeが「もうこの機能ありますけど、再利用する？共通ユーティリティ作る？」と確認プロンプトを秒で出してきます。
プロジェクトが大きくなってくるとコードベースで調べるだけで5分くらいかかるので、かなりの時短になります

サンプルプロジェクト04 技術負債

これがADRの真骨頂。

レガシーの保守なんかをやってると、こんな意味不明なコードにぶち当たる事があります。

public int sumPrices(String prices)

ふるーい外部システムと連携する必要があったりして、こういう実装も稀によくあります。人間にも意味がわからない設計ですけど、AIにとっては

AI「アイエエエエ！ナンデ？prices文字列ナンデ？複数形ナンデ？」
⇩
AI「引数を整数型配列にリファクタリングしました」
⇩
無事死亡

このパターンの修整はけっこう時間がかかります。ClaudeCodeは「コードベースでは間違っていない、外部システム側を調べて」の一点張り。それができれば苦労はしねぇ！！

人間のチームだと生きる仕様書みたいなシニアがいて、
「あーこれは、昔Accessで作ったマスターがあって、そこから文字列で出力されるマクロがあるんだよ。それがまだ生きてるからこうせざるをえないんだよね」
と説明されたりして終わりですけど、AI相手には毎回説明しないといけないですよね。

このサンプルプロジェクトは、過去の実装時にsqlewでADRが記録されているという想定で、データベースにDecisionを登録しています。

sumPricesが何をする関数なのかsqlewで調べて

明示的にこうしてもいいですし、もちろんPlanモードでprice関連を変更しようとした時には自動サジェストでこうなった理由が提示されますので、ClaudeCodeも慎重な扱いをしてくれます。

より強い強制

sqlewでは方針の決定であるDecisionに加えて、「これはしてはいけない」「これは必ずしろ」の誓約としてConstraintも追加できます。
例えば「インラインスタイル禁止」とsqlewに記録してのように直接追加もできますし、Planモードのプロンプトで〇〇の代わりに□□を使ってというような表現もConstraintに置き換えられて自動登録されてます。
もちろんConstraintもDecision同様、Planモードで自動サジェストされます。

重複ADRを防ぐ

サジェストの機能ではタグやキーワードでの一致度チェックで閾値を超えた項目を提示していますが、登録時にも同様のチェックを行っています。
重複の可能性が高いADRは一旦JSONで保存され、実装終了時にsqlew.queueアクションで登録の是非をAIが判断するように指定しています。

チームで使うsqlew

お手軽に試してもらいたかったので、sqlewはデフォルトではプロジェクトフォルダにSQLiteファイルを作成し、そこへデータ集積していきます。
これだとチーム利用には若干不便なので、セルフホストのMySQL・MariaDB・PostgreSQLでも運用できるようにしています。詳しくはドキュメントを見てくださいね。

SaaSバックエンドもあります

もっと気軽に＆監査機能もついたSaaSバックエンドを始めました。（露骨な宣伝）

ADRの関連ノードグラフ可視化などもできます。

OSS版で気に入られましたらぜひぜひ！