last-20-percent

最後の 20%

エージェントは、ソリューションの最初の 80％、つまりデータ取り込み、エンドポイント、スキーマ、パイプラインは確実に作り上げます。しかし、人が心から気に入るものにするための 20％は、ひっそりと飛ばしてしまいます。エンタープライズ向けのナレッジウィキを求められると、エージェントはクローラー、埋め込み、LLM の統合レイヤーを構築しますが、ウィキのページはどんな「読み心地」であるべきか、どのページがあるべきか、初日から誰かがどうやって答えを見つけるのかを一度も尋ねません。その結果はコンパイルでき、テストに通り、デモも問題ありませんが、公開した時点で使いものになりません。

このスキルは、その 20％を見つけ、配管部分と同じくらい具体的に仕様化して、仕上げるためのものです。

なぜ 20％が抜け落ちるのか

失敗は構造的なものなので、対策も構造的でなければなりません。

1. タスクは名詞から生まれます。「ウィキ」を分解すると、データ取り込み、ストレージ、検索、生成になります。ウィキを使う体験は、その分解に現れません。そのためタスクにならず、実行もされません。
2. **「完了」は確認できるもので定義されます。**テストでは 200 レスポンスを確認できますが、「このページは最初の段落で質問に答えている」とは確認できません。完了基準のない作業は、いつの間にか計画から消えてしまいます。
3. **センスを問うのは越権行為に感じられます。**ページをどのような読み心地にするかを決めるのは、プロダクト上の判断です。モデルは判断を避けます。「柔軟な」仕組みを構築し、実際の判断をすべてユーザーに委ねます。しかしユーザーは、まさにその判断をしてほしくて依頼したのです。
4. **20％は最後に予定され、最後のものは削られます。**体験に関する作業に名前が付いていたとしても、計画の末尾に置かれます。まさにそこで、コンテキスト、予算、注意力が尽きます。

以下の各フェーズは、これらの問題のいずれかに対処します。

基本原則

**エンドユーザーと同じように出力を使い、そのマジックモーメントが実現するまでは、ソリューションを完了と呼んではいけません。**自分のコードを読むことは、出力を使うことではありません。テストに通ることも、出力を使うことではありません。ウィキを開いて、初見の状態で 3 ページ読みましょう。レポートを実行して、レポートを読みましょう。ダッシュボードを読み込んで、それを使って実際の質問に答えてみましょう。

フェーズ 1：マジックモーメントを書く

何かを分解する前に、具体的な場面を 1 つ書きます。実在する名前の人物、実際のタスク、その人の目に入るもの、そして後で同僚に話したくなる理由を含めてください。

悪い例（機能）：「ユーザーはウィキを検索できます。」 良い例（場面）：「法務部の Sarah が『data retention』と入力すると、自分の実際の疑問に最初の段落で答えているページにたどり着き、元になったポリシー文書へのリンクも見つかります。彼女は Slack で尋ねるのをやめます。」

この場面が、これ以降のすべての目的地になります。書けない場合、その不足こそが欠けている 20％です。いったん立ち止まり、まず解消してください。候補となる場面を 2～3 個、推奨案とともに提示しましょう。ユーザーに空白のページを埋めさせてはいけません。

フェーズ 2：名詞だけでなく、場面を分解する

次の 2 つのリストを作成します。

• **名詞リスト（80％）。**成果物の名前を分解して得られる項目です。データ取り込み、認証、スキーマ、API、デプロイなどです。エージェントはこのリストを自動的に作成するため、支援は必要ありません。
• **場面リスト。**マジックモーメントを一つずつたどり、それが起きるために必要な条件をすべて書き出します。Sarah は何に入力し、どうやってそこへたどり着くと知ったのでしょうか。ページの読み込み時に、どんな見た目だったのでしょうか。なぜ答えが最初の段落にあり、そのリンクはどこから来たのでしょうか。データ取り込みが完了する前の初日に、彼女の目には何が映ったでしょうか。

**最後の 20％とは、場面リストから名詞リストを差し引いたものです。**この残りはランダムではありません。コンテンツと文体、情報アーキテクチャ、初回利用時と空の状態、意見を反映したデフォルト、ゴールデンパス、失敗時の体験、命名とマイクロコピーという、繰り返し現れるカテゴリーに分類されます。領域別の調査質問と実例を含む全カタログは、references/last-20-catalog.md にあります。見落としを拾い上げるため、場面リストを照らし合わせてください。

フェーズ 3：配管の精度で、最後の 20％を仕様化する

シーンリストの各項目に、「エンドポイントが 200 を返す」のように具体的な完了条件を設定します。曖昧な品質目標は、この作業を頓挫させる原因です。すべて確認可能な形に変えましょう。

• 「ページは読みやすくあるべき」→「すべてのページで、詳細に入る前に 2～4 文の直接的な回答を示す。セクション見出しには、読者が実際に尋ねる質問を使う。すべての主張に、出典ドキュメントへのリンクを付ける。」
• 「適切な空状態」→「検索結果が 0 件の場合、最も近いページを 3 件表示し、ワンクリックで使える『このページをリクエスト』アクションを提示する。単に『結果なし』と表示することは決してしない。」

ゴールデンアーティファクト

システムがアーティファクト（Wiki ページ、レポート、メール、ダッシュボード、生成コードなど）を作る場合は、ジェネレーターを構築する前に、最良の実例を手作業で作成してください。 実際のコーパスにある実際のトピックについて、理想的な Wiki ページを自分で書きます。そのゴールデンアーティファクトは、同時に 3 つの役割を果たします。仕様（出力がどうあるべきか）、テストフィクスチャ（生成結果との比較対象）、品質基準（これに近づけないジェネレーターは完成していない）です。

ゴールデンアーティファクトなしにジェネレーターを作ると、ありきたりな内容に収束します。お手本がない状態で「Wiki ページを生成する」とは、「あらゆる Wiki ページの統計的な平均を出力する」という意味だからです。また、ゴールデンアーティファクトにダミーテキストや仮の内容を使わないでください。偽の内容では、構成が実際に機能するかどうかが分からなくなります。

フェーズ 4：先回りして組み込み、後回しにしない

構築モードでは、最後の 20％を最後に回す計画を拒否してください。体験のレイヤーが確実に残るよう、計画の順序を組み立てます。

1. まずゴールデンアーティファクトを作ります。それを生み出す仕組みより先に作成します。
2. 体験に関する決定（ページの種類、デフォルト、文体、ナビゲーション）は、構築全体を通じて組み込みます。「仕上げの週」にまとめて決めるのではなく、関連する配管を作るタイミングで決定します。
3. シーンリストを、計画やトラッカー内で完了リストとして見える状態に保ち、各項目に完了条件を付けます。完了リストの未チェック項目は、テスト失敗と同じように扱います。すべて成功するまで、ビルドは赤のままです。

フェーズ 5：実際に使ってみる

ビルドが完了したとされたら、内部事情を何も知らないエンドユーザーになってください。マジックモーメントを文字どおり実行します。Sarah が行く場所に行き、Sarah が入力する内容を入力し、Sarah が読むものを読み、最後まで進めます。

見つけたものを、ゴールデンアーティファクトと完了リストに照らして評価します。そして、実際に使ってみた体験とシーンの間にあるギャップをすべて書き出します。内容が薄いページ、初回利用時の手応えのなさ、製品が決めるべきことをユーザーに決めさせてしまうデフォルトなどです。修正して、もう一度使ってみます。このループは、次のいずれかの状態で終了します。

• 実際に使ってみてマジックモーメントが実現する → そう伝え、証拠（実際に読んだページ、実際にたどったフロー）を示して終了します。
• 残るギャップの解消に、人による製品上の判断が必要 → 推奨案をそれぞれ添えて、判断事項として明示的に列挙し、そこで終了します。

モード

• 計画モード — 構築の依頼が届いた直後です。名詞リストの作業の前か並行して、フェーズ 1～4 を実施して計画を形にし、完了を宣言する前にフェーズ 5 を実施します。
• 監査モード — すでにソリューションが存在します（「これは本当に完了しているか？」「なぜデモのように感じるのか？」）。まずフェーズ 5 で実際に使って証拠を集め、マジックモーメントとシーンリストを後から補います（フェーズ 1～2）。次にギャップを仕様化して解消し（フェーズ 3～4）、もう一度実際に使ってみます。

境界

• 最後の 20％は、コアシーンを掘り下げるためのものであり、範囲を広げるためのものではありません。 機能の追加は、仕上げのふりをした正反対の失敗です。マジックモーメントに貢献しないアイデアは、いつかやることリストに入れます。
• 明確な見解を示してください。 理由を添えて、デフォルト、ページ構成、文体を提案します。本当に取り消せない決定、または本当に事業戦略上重要な決定に限って質問してください。それでも、推奨案を添えます。
• 配管を過剰に磨き上げないでください。 このスキルの予算は、動作している基盤を内部的により美しく作り直すことではなく、体験に残る細部に使います。
• ソリューションは合格として構いません。 実際に使ってマジックモーメントが実現するなら、「これで完了です」と伝えて終了します。徹底しているように見せるためにギャップをでっち上げるのも、一種の雑な仕事です。