AIの出力を人間が読める状態にする2つのHooks

Claude Code のプランモードでファイルを作らせたあと、しばらくして見返しに行きました。ファイル名は squishy-wondering-mango.md です。

ふにゃふにゃで不思議そうなマンゴーじゃねえんだよ。

何を実装するプランだったのか、ファイル名から一切わかりません。開いても同じでした。ファイルパスが大量に並んでいて、「何を実装するのか」が最後まで読み取れません。
エージェント向けの指示と人間向けの説明がごちゃ混ぜになっています。そのプロジェクトに無い専門用語まで出てきます。

この読みにくさは我慢する問題ではなく、改善できる問題でした。2つの Hook で解決します。

なぜプランは読める状態でないといけないか

社内フレームワークやドメイン固有のモジュールなど、モデルの学習データに十分含まれていない領域では、プランを人間がレビューした方がよいです。方向を間違えたまま実装が進むと、手戻りに最も時間を取られます。

しかし、プランの認知負荷が高くて読めませんでした。
原因は、概論から各論の流れになっていないことです。「どこを見れば理解できるのか」を一発で把握できて、そのあとに補足が続く構成でないと、日本語として読めても内容を理解しながら読み進められません。
読み手が違えば書き方も変わるのに、「同じ日本語だから問題ないよね？」と思っていましたが、全然問題ありました。

読めないなりに図解化して理解しようとしましたが、元の文章が読みにくければ良くない図解ができあがるだけです。
レビューが機能していませんでした。

モデルの性能は上がっていますが、それは主に英語での話です。日本語の出力品質がそのまま改善されるとは限りません。
読める状態にするチューニングは自分でやるしかありませんでした。

文体を改善するHook

EnterPlanMode¹ ツールの実行時に発火する Hook で、文体指針を Claude に注入します。
「過剰な形容詞・感嘆・誇張を削除」「断定する」「同じことを二度書かない」といった指示を自動で渡します。

gist.github.com

Claude Code Hooks: プランの文体改善 + プランファイルへのシンボリックリンク自動生成。command のパスは環境に合わせて変更してください。

Claude Code Hooks: プランの文体改善 + プランファイルへのシンボリックリンク自動生成。command のパスは環境に合わせて変更してください。 - create-plan-link.ts

文体の指示はプランモードでしか使いません。会話全体に影響する CLAUDE.md ではなく、Hooks で動的に注入する方が適しています。

この Hook の着想は、あるツイートから得ました。

「編集レイヤーを分ける」という考え方を、Hook で仕組み化しました。

プランファイルにシンボリックリンクを貼るHook

squishy-wondering-mango.md のような意味不明なスラグ名に対して、プランファイルのH1見出しから 2026-06-18_Hookで開発体験を底上げする.md のような読みやすい名前でシンボリックリンクを .claude/plan-links/ に自動生成します。

原本は移動も改名もしません。Claude Code が内部で参照しているファイルパスを壊さないためです。
人間が見返すときだけ、読みやすい名前でアクセスできます。

gist.github.com

Claude Code Hooks: プランの文体改善 + プランファイルへのシンボリックリンク自動生成。command のパスは環境に合わせて変更してください。

Claude Code Hooks: プランの文体改善 + プランファイルへのシンボリックリンク自動生成。command のパスは環境に合わせて変更してください。 - create-plan-link.ts

離席して戻ったときや、並行して計画だけ作らせていたときに「あのプランどれだっけ」とならずに済みます。

まとめ

• AIの出力が読みにくいのは「仕方ない」ではなく、チューニングできる余地がある
• 文体の指示は CLAUDE.md にも書けるが、プランモード専用なら Hooks で動的に注入する方が適している
• プランの認知負荷が高いとレビューが機能しない。読める状態にするチューニングは自分でやるしかない

おまけ

参考