メインコンテンツまでスキップ

92% が別の意味になる場合

プレーンテキストのインターフェースで、自ら文脈を語る文言を扱った UX ライティングのケーススタディです。

Sweepy はターミナルで動作する求職ツールです。インターフェースは罫線文字と色付きのテキストで描画し、キーボード入力を受け取ります。説明はテキストそのものの中に置くしかありません。ツールチップを表示する場所がないからです。ランチパッドはステータス行を折り返さず、枠の端で切り詰めます。文言は幅に収まって終わるか、末尾を失うかのどちらかです。

そこから一つのルールが生まれました。すべての文言が自らの文脈を語る。 スコアのラベルは、その数値を誰が書いたかを示します。ステータスの文言も同じ規律に従い、ランチパッドの最下行から各プロンプトの書式ヒントまで一貫しています。難しいのはスコアです。ツールがどう算出したかを読者が知っていてもいなくても、パーセントは情報を伝えているように見えるからです。

二つのパーセント、二つの問い​

Sweepy は求人を履歴書に対して二通りの方法で採点します。

一つ目は決定論的スコアラーで、すべてのスイープがこれを実行します。sweepy はランチパッドを開き、START SWEEP がスイープで見つかったすべてのカードを採点します。sweepy --run はウィザードを開かずに、最後に保存したプロファイルを再実行します。この処理は二つの文書を比較します。履歴書と求人の間で共有される語を数え、要件の重なりを 60%、キーワードの重なりを 40% で混ぜ合わせ、その結果を resume.keywords_weight で拡大縮小します。語は両側に現れたときだけ数えます。読者がその仕事をこなせるかどうかを、スコアラーが推論することはありません。

二つ目はエージェントによる評価で、Model Context Protocol(MCP)経由で利用できます。エージェントは解析済みの履歴書と求人を一緒に読み、読者がその職務にどれだけ合うかを推論します。そして submit_judgments で独自のパーセントを送信します。

共有語の数とエージェントの判断は、別の問いに答えます。共有語の数は重なりを測るもので、適合度ではありません。だからこそラベルは書き手を示す必要があります。数は履歴書と求人がどれだけテキストを共有しているかを報告します。エージェントは一人の人間が一つの仕事にどれだけ合うかを判断します。履歴書が求人を一言一句なぞっていても、弱い適合を述べていることがあります。別の語彙で書かれた履歴書が、強い適合を述べていることもあります。語数は前者を見つけて後者を取りこぼし、エージェントは両方を量れます。

カードが表示するスコアは一つです。最後に書いた側がそれを決め、評価が入るとレポートは新しい値の周りに再並べ替えされます。判断は決定論的スコアの隣に並ぶのではなく、置き換えます。数字だけを見せると、読者の手元にあるのがどちらなのかが隠れます。

文言は、読者が求人を開く前に、バッジ行の中で書き手を示さなければなりませんでした。インターフェースの残りの部分も同じルールに従っています。

ランチパッドから結果まで​

流れはランチパッド → 設定ウィザード → スイープ → 結果です。スイープがクライアントのツール呼び出し上限を超えると、実行が終わるまで稼働し続けるポーリング可能なステータスにハンドオフします。

カード 3 から 8 はその順序に従います。カード 2 はスコアを扱います。スコアはスイープが終わって初めて存在し、ページの残りが向かう先の事例です。カード 1 は問題を示し、カード 9 はその間のすべての文言の背後にある制約を示します。

枠の幅が長い文言を切り詰める​

条件を決めるのはターミナルです。何かを説明する層はテキストだけで、枠は長すぎるものを切り詰めます。エラーは問題と解決策を同じ文言の中で示さなければなりません。読者はその行を離れて別の行を読むことができません。

文言は自らの文脈の代価を払います。Could not parse salary %r. Enter a number like 65000, 65,000, or 65k. は何が失敗したかと代わりに何を入力するかを示し、%r は拒否された入力に置き換わります。Current profile: none loaded / build one to start はプロファイルがない場合に同じことをします。GUI ならどちらの文の後半もツールチップに置けます。ここでは一行が両方の半分を含みます。

唯一の説明としてのラベル​

スコアのラベルは、その数値を誰が書いたかを示します。ドキュメントはそれを率直に述べています。「MATCH のカードは判断を反映します。KEYWORD OVERLAP のカードは共有語を反映します。」一つのカードに、一つのスコアの隣に一つのラベルが印字されます。読者は求人を開く前に、どちらの主張を手にしているかを知ります。

それぞれの語は、どんな比較がその数値を生んだかも読者に伝えます。KEYWORD OVERLAP は二つの文書について報告します。MATCH は人と仕事について報告します。二つの数値が一致するはずだと思う読者は、どちらかを読み違えます。

ラベルはインターフェースではなく書き手に従います。エージェントはパーセントなしで判断を送信できます。そのカードも KEYWORD OVERLAP と表示されます。スイープがその数値を書いたからです。実行経路はカードの外にあります。レポートのファイル名は MCP の実行に mcp を付け、ログのヘッダーは実行方法を印字します。

タイルの命名も同じルールに従います。BUILD PROFILE は操作を示し、サブタイトルの Set up your job search は内部用語を捨てて読者の目標に置き換えます。LOAD PROFILE は Open a search you saved と表示し、そのタイルが何をするかを述べます。

何を書き、どう確かめたか​

役割: このケーススタディが引用する製品文言の唯一の書き手。ランチパッドのサブタイトルとウィザードのプロンプトを書き、続いて進捗のメッセージと検証の文言を書きました。スコアの出所を示すラベルと、クライアントが中継する MCP ハンドオフの message が最後です。リポジトリのエージェントガイドラインと CI の品質ゲートのもとで、Copilot と Gemini を使ってビルドを指揮しました。製品文言の文字列は Sweepy のソースコードと照合して確認しました。

信頼を調整し、それから行動する​

読者はスコアに基づいて行動する前に信頼を調整し、待っている間はシステムが何をしているかを知るべきです。インターフェースは、Sweepy がどう数値を出したかも、処理にどれだけかかるかも説明できません。ラベルとステータスの文言が、視覚的な手がかりなしでも機能する形で、最小限の語数でそれを説明します。

十五のプロンプトを順に​

ウィザードは 15 ステップで実行されます。十五の最上位プロンプトが順に現れ、はい・いいえの質問ははい/いいえのセレクターとして表示されます。

ウィザードのプロンプト
? What is your name?
>

? What job titles are you looking for?
(Separate multiple titles with a comma)
>

? Where do you want to work? (City, State):
>

? Do you want to see remote-only roles? (Y/n)

? Do you want to include hybrid roles? (Y/n)

? What is the path to your resume PDF?
>

? What is your minimum target salary? (Leave blank to skip):
>

? Which boards do you want to search? Pick from any engine; downloaded engines are labeled.

? Do you want to add custom platforms or ATS domains? (Y/n)

? Enter must-have skills or keywords to prioritize
(comma-separated, leave blank to extract from resume):
>

? What export formats do you want?
[x] PDF Report
[x] CSV Spreadsheet
[ ] JSON Data

? Add job-tracking columns to the CSV? (date applied, status, interview stage,
offer, follow-up date, contact, notes) (Y/n)

? Do you want to configure multiple resume tracks
(e.g. Tech Writer vs UX Writer)? (Y/n)

? Do you have a portfolio, writing samples, or case studies to submit
with applications? (Y/n)

? Enable debug logging? (Logs are saved under logs/ in the application
directory): (Y/n)

文言を確認する場所​