AIエージェントに仕事を任せた後、人間がやるべきことは可視化です

エージェントにマイクロサービス全体のリファクタリングを任せたことがあります。PRが上がってきたとき、サービス間の呼び出しフローが頭の中でまったく描けませんでした。ログを一行ずつ追って確認する時間が、コーディングそのものより長くなっていました。可視化を導入してようやくコードの流れが一目で掴めるようになり、同僚への説明時間も半分に縮まりました。ここでは、実際に効果のあった5つのツールを紹介します。

ターミナルのASCII出力をブラウザに移すだけで全体像が見える

エージェントが吐き出すターミナル上のASCII図は、その場では便利でもSlackやドキュメントには貼りにくいものです。visual-explainerは、そのASCII出力をMermaidダイアグラムを含むHTMLページに変換してくれます。ダークモード対応、ズーム・パン操作が標準搭載で、ビルド工程は不要です。

• /diff-reviewモード: コード差分とアーキテクチャ比較を1画面で並べて確認できます。PRレビュー時に変更の影響範囲を視覚的に把握するのに適しています。
• /project-recapモード: プロジェクトに久しぶりに戻る際のコンテキスト復旧スナップショットを生成します。休暇明けや担当変更時に重宝します。
• /generate-slidesモード: 技術説明をスライドデッキに変換します。社内勉強会やチーム共有の準備工数が大幅に減ります。
• テーブル自動変換: 4行以上のテーブルはHTML形式へ自動変換されます。エージェントが出力する比較表がそのまま見やすいドキュメントになります。

チャット画面の中でリアルタイムにダイアグラムを描く

設計の議論中に「ちょっと図を描いて」と言いたくなる場面は多いはずです。Excalidraw MCPは、MCPサーバーアドレスを1つ登録するだけで使えるダイアグラムツールです。ローカルへのインストールは不要で、手描き風のスタイルが「これは確定仕様ではなくスケッチです」という雰囲気を自然に伝えてくれます。

• 動作環境: Claude DesktopとVS Codeの両方で動作します。環境を選ばないのは地味に大きな利点です。
• ビューポート自動調整: 図の規模に応じてビューポートが自動調整され、フルスクリーン編集にも対応しています。
• インタラクティブ編集: チャットの会話フローの中で図を直接編集できます。「この矢印を逆にして」といった指示がそのまま反映されます。

正直に言うと、複雑なシーケンスダイアグラムにはMermaidのほうが向いています。Excalidrawの強みはアーキテクチャの概要やコンポーネント間の関係性を素早くスケッチする場面にあります。万能ではないことを理解した上で使い分けるのが現実的です。

Mermaidダイアグラムを実用レベルのビジュアルに仕上げる

Mermaidの記法は書きやすいですが、デフォルトの見た目はドキュメントに載せるには素朴すぎます。beautiful-mermaidは、背景色と前景色の2色を指定するだけで残りの配色を自動で導出してくれるスタイリングライブラリです。15種類のテーマがプリセットされています。

• SVG同期レンダリング: ReactのuseMemo()内で使ってもちらつきが発生しません。UIに組み込む際の安定性が高いです。
• ASCII/Unicode出力: CLIツールへの組み込みにも対応しています。ターミナルから離れたくないエンジニアにとっては見逃せない機能です。
• DOM非依存: DOMへの依存がないため、サーバーサイドレンダリングとの互換性があります。ドキュメント生成パイプラインにそのまま組み込めます。
• Shiki連携: VS Codeのテーマをそのまま適用できます。コードブロックとダイアグラムの色調が揃うと、資料全体の統一感が格段に上がります。

エージェントにコードだけでなく解説書まで書かせる仕組み

コードを生成させるだけでは、そのコードが「なぜそうなっているのか」は残りません。Zara Zhangが公開した「Claude Teacher」プロンプトは、CLAUDE.mdに1段落を追加するだけで機能します。プロジェクトの区切りごとにFOR[名前].mdというファイルにナレッジを整理させる仕組みです。

• アーキテクチャとコードベースの接続: 全体構造と個別ファイルの関係を明示的に記述させます。
• 技術スタック選択の理由: 「なぜこのライブラリを選んだのか」「他の候補と比較して何が決め手だったのか」を記録します。
• バグ、解決策、落とし穴: 遭遇した問題とその対処法を、再発防止の観点でまとめさせます。
• エンジニアとしての思考プロセス: 判断の分岐点や設計上のトレードオフを、比喩やエピソードを交えて記述します。

出来上がるドキュメントは、新メンバーのオンボーディング資料としてそのまま使えるレベルです。エージェントに「教える」という役割を与えることで、暗黙知が形式知に変わります。

コードを生成したら、説明もセットで求めるべきです

エージェントにコードを書かせて、動作確認して、終わり。このワークフローには落とし穴があります。コードは動くのに構造が理解できない状態が積み重なっていくのです。Boris Chernyが紹介している設定のヒントでは、/configでExplanatory/Learningスタイルを選択することで、エージェントの出力に説明レイヤーを追加できます。

• 従来のフロー: コード生成、動作確認、しかし構造は理解できないまま次のタスクへ進む。
• 改善後のフロー: コード生成、可視化と説明の出力、構造の体得、そして応用へ展開する。

この差は短期的には小さく見えますが、数週間後のコードベースの把握度に決定的な違いを生みます。

AIに仕事を任せるだけの段階は過ぎました。可視化させること、説明させること、そしてその出力を人間が理解すること。視覚は人間が最も速く情報を処理できるチャネルです。エージェントの出力を「見える形」にする習慣が、コードの理解と共有の質を根本から変えていきます。