指示書は、現場ではない

作業を始めるとき、まず自分の盲点を把握する。コードベースの新しい領域で機能を書くときや、デザインを反復して詰めていくような不慣れな作業を Claude に手伝ってもらうときは、未知の未知が大量にあるはずだ。何を質問すべきか、何が「良い」のか、過去にどんな経緯があったか、どんな落とし穴を避けるべきか——それすら分からない。

そこで Claude に「未知の未知を見つけて説明して」と頼む。“blindspot pass” や “unknown unknowns” という言葉をそのまま使うのがコツ。自分が誰で、何を知っているかのコンテキストも添える。

「見れば分かるのに、先に言葉にできない」——そんな基準(未知の既知)が多い領域では、Claude と一緒にブレストと試作をする。この手の未知は、実装中に発覚すると(相対的に)高くつく。仕様のほんの小さな変更がコードでは大改修になり、エージェントが以前の変更を巻き戻すのも難しくなるからだ。だからこそ、試作の段階で早めに言語化しておく価値が大きい。

たとえば、バックエンドの配線や状態管理を作り込む前に「フレームにボタンを足したらどう見えるか」だけを確かめたい、というように。ビジュアルデザインは特に「言葉にしづらいが、見れば分かる」の典型で、そういうときは 1 つのアーティファクトに複数のデザイン案を出してもらう。

筆者はほぼ毎回のコーディングセッションを探索・ブレストのフェーズから始めるという。こうすると、プロジェクトのスコープを意図を持って決めた状態でスタートできる。Claude は自分では思いつかなかった高価値なアプローチを見つけてくれることが多く(逆に木を見て森を見ずになることもある)、ブレストのおかげでスコープを狭すぎず・広すぎず設定できる。

十分ブレストしても、未知は残る。そこで今度は、曖昧な点について Claude に自分をインタビューしてもらう。質問の的を絞れるよう、問題のコンテキストを渡しておくとよい。

欲しいものを言葉で細かく説明できないこともある。語彙がなかったり、説明にとても時間がかかったり。そういうときの最善手はリファレンス(参照物)を渡すこと。図や資料や画像でもいいが、最強のリファレンスはソースコードだ。

望む挙動を実装しているライブラリや、気に入っているデザインコンポーネントがあるなら、そのフォルダを Fable に指して「これを見て」と言えばいい。別の言語で書かれていても構わない。Claude Design も同じ仕組みで動いている。ファイルを手渡す必要はなく(もちろん渡してもいい)、気に入ったウェブサイトのモジュールを指させれば、スクリーンショットではなくその下にあるコードを読んでくれる。マークアップや構造、そのコンポーネントが実際にどう組み立てられているかまで、ずっと豊かな情報が手に入る。

実装の準備ができたと思ったら、レビュー用の実装計画を作ってもらう。ポイントは、変わる可能性が高い部分——データモデル、型インターフェース、UX フロー——を先頭に置いてもらうこと。自分が実際に手を入れるべき箇所を Claude が浮かび上がらせてくれる。

計画に満足したら、新しいセッションを立ち上げ、スペックやプロトタイプなどのアーティファクトをプロンプトに渡して実装してもらう。しかし、どれだけ計画しても未知の未知は必ず潜んでいる。エージェントは作業中に、コードで見つけたエッジケースのせいで別の進路を取る必要に迫られるかもしれない。

そこで Claude Code に、一時的な implementation-notes.md(.html でも)を持たせ、下した判断を記録してもらう。次の挑戦への学びになる。

何かを世に出すうえで最も重要な工程のひとつが、周囲の理解と承認を得ること。ピッチ資料・説明資料を成果物に添えると、(1) あなたと同じ未知からスタートするレビュアーの理解が速くなり、(2)「想定すべき未知や典型的な失敗点をちゃんと考慮したか」を見たい専門家の承認も速くなる。

長い作業セッションの後、Claude は自分が思っていた以上のことを成し遂げているかもしれない。コードの差分を読むだけでは浅い理解しか得られない——挙動の多くは既存のコードパスに依存しているからだ。

そこで、まず変更にまつわるコンテキストをたっぷり説明してもらったうえで、その内容について自分にクイズを出してもらう。筆者は、クイズに満点で合格するまでマージしないという。