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 はその間のすべての文言の背後にある制約を示します。
一つのスコア枠に二人の書き手
スコア枠は一つで、書き手は二人あり得ます。どのスイープも決定論的な重なりの数で各カードを採点します。しかし MCP の評価は、その数値を独自の推論で上書きします。ラベルにはっきりした違いがなければ、読者はどちらの書き手がスコアを設定したのか分からず、信頼を調整できません。内容面の課題は、数語のスペースしかないバッジ行の中で書き手を区別することでした。
数と判断を見分ける
同じプロファイル、同じ数値、二人の書き手。1 枚目はエージェントが設定したので 92% MATCH と表示されます。2 枚目は決定論的スコアラーが設定したので 92% KEYWORD OVERLAP と表示されます。ラベルが書き手を特定します。92% だけを見た読者には、二つを区別する手段がありません。数と判断は別の問いに答えるため、評価は同じ枠の中で重なりのスコアを上書きします。
92% KEYWORD OVERLAPは、履歴書と求人を比べた共有語の数を意味します。92% MATCHは、読者がその職務にどれだけ合うかを推論してエージェントが到達した数値を意味します。
スイープは、ターミナルで始まっても MCP 経由の run_sweep で始まっても、生成する各カードにこの数を書き込みます。MATCH に置き換えるのは、送信された match_pct だけです。
PDF の順位行はラベルを角かっこで繰り返します。#1 // COMPANY | [92% MATCH] または [92% KEYWORD OVERLAP] です。CSV は match_value を match_kind の隣に書き出し、同じ事実を機械可読な形で読者に渡します。マッチのスコアの隣に三つ目のスコアが現れることもあります。[88% PORTFOLIO FIT] が独自のラベルを印字するのも同じ理由です。あなたの作品例は履歴書とは別の問いに答えるからです。
応募のバッジはテキストで先に読み、色は二番目です。[STANDARD / QUICK APPLY] は標準の応募を示し、[EXTENDED RESPONSES REQUIRED] は執筆サンプルを求める職務を示します。3 枚目のカードは、履歴書トラックも並ぶ順位行に [EXTENDED RESPONSES REQUIRED] を印字します。どちらのラベルも色なしで機能します。これはアクセシビリティにも、色を描画しないターミナルにも重要です。
一行で示す身元、範囲、準備状況
Current profile: none loaded / build one to start は、欠けている状態と次の操作を一行で示します。Current profile: Alex Rivera / 4 titles / Ready は、最初の枠で名前を、最後の枠で準備状況を確認します。各スラッシュが一つの答えと次の答えを区切り、行は折り返さず枠の端で切り詰められます。保存済みプロファイルに履歴書のパスがないときは、Resume missing が Ready に代わります。
ターミナルでは、ステータス行が唯一の持続的な文脈です。見出しであり、同時に準備状況の指標として読まれます。
動詞、目的語、そして読者の目標
START SWEEP は Run your job search now と対になります。各タイルは二行を印字します。名前と、Enter が何をするかを読者の言葉で言い換えたサブタイトルです。SWEEP SETTINGS は Ranking, cards, tracking と表示します。SWEEPY'S TOOLBOX は Edit profile, logs, help と表示します。EXIT SWEEPY は Save changes and close と表示し、作業を保存することを約束します。
操作タイルは動詞とその目的語から始まります。それ以外は場所か終了を示します。サブタイトルは内部用語を平易な言葉で説明します。二桁の番号はグリッドの順序ではなく、各タイルを識別します。上段は 01 と 04 を組み合わせます。タイルは他を振り直さずにグリッドへ加わります。移動は矢印キーと Enter で行います。
プロンプトの中の書式ヒント
プロンプトは問いを一行に保ち、書式が重要なときはルールをその下にインデントして置きます。
What job titles are you looking for?
(Separate multiple titles with a comma)
給与のプロンプトは、スキップできることを質問そのものの中に示します。
What is your minimum target salary? (Leave blank to skip):
ルールは判断が起きる行に現れます。読者は同じ画面にとどまります。ターミナルには頼れるツールチップがありません。
ウィザードを再実行せずに回答を編集する
ウィザードは 15 ステップで、Esc は一問ずつ戻ります。確認画面には 11 項目が並びます。← Back、次に Submit profile、そして九つの操作です。Edit an answer は Submit profile のすぐ下にあります。修正は送信から一行しか離れていません。回答を変えたい読者は、すべてのプロンプトをやり直す必要がありません。
五つのステップのステージラベル
コマンドラインの実行は五つの番号付きステージを刻み、それぞれが作業内容を示します。
[1/5] Loading profile...
[2/5] Discovering roles...
[3/5] Validating URLs...
[4/5] Scoring against resume...
[5/5] Generating reports...
ログ行はステージ番号を示します。MCP の進捗ペイロードは項目名を示します。四つの職務名のうち最初のものについて、total 4 の step 1 と表示し、ラベルは Discovering roles: Paralegal です。Scoring roles は、スコアラーが処理する間の候補リストを報告します。読者は実行がどこにあり、何が残っているかを見ます。プログレスバーは、ツールが知り得ない所要時間をほのめかしてしまいます。
ジョブ ID を返す待機
ライブのスイープは 1 分以上かかることがあります。MCP モードでは、ツール呼び出しはスイープ全体を待たずに実行中の状態を返します。これにより呼び出しはクライアントのタイムアウト内に収まり、呼び出し元に作業が続いていることを伝えます。
run_sweep は既定で 45 秒待機します。wait_seconds がその待機時間を設定し、0 から 600 に制限されます。SWEEPY_MCP_WAIT_SECONDS は、制限が厳しいホストで上限を下げます。実行中の状態には job_id、progress オブジェクト、elapsed_seconds の値、message が含まれます。
{
"status": "ok",
"sweep_status": "running",
"job_id": "<job id>",
"progress": { "step": 3, "total": 5, "label": "Validating URLs" },
"elapsed_seconds": 41.2,
"debug_log": "<path>",
"message": "The sweep is still running. Call get_sweep_status to wait for it, then continue with get_jobs."
}
クライアントは sweep_status が "completed" になるまで、job_id を添えて get_sweep_status をポーリングします。Sweepy はクライアントが接続を保っていてもいなくても、このハンドオフを越えて作業を続けます。文言はタイムアウト内に収まり、後から再接続するクライアントにも正しく読まれなければなりません。これは進捗を報告する実行中の状態です。
45 秒は製品の既定値で、_DEFAULT_WAIT_SECONDS が設定し、_MAX_WAIT_SECONDS が上限を定めます。progress と elapsed_seconds は実行ごとに変わり、debug_log も同様です。message は、呼び出し元がすでに持っている数値を繰り返すのではなく、次のツール呼び出しを示します。
弱い文言を隠す場所はない
インターフェースはテキストだけに頼り、枠は長すぎるものを切り詰めます。ラベルは自己完結している必要があります。画面のほかの何もそれを説明しないからです。ステータスメッセージは、頼れるスピナーなしで、読者がどこにいるかを示します。
命名ルールはそこから導かれます。START SWEEP、LOAD PROFILE、BUILD PROFILE は操作から始まります。サブタイトルはそれを読者の目標として言い換えるので、「プロファイル」という内部的な考えを知らなくても次に何が起きるか分かります。スコアのラベルは同じルールを数値に適用します。KEYWORD OVERLAP は決定論的な数に、MATCH はエージェントの判断に付けます。
枠の幅が長い文言を切り詰める
条件を決めるのはターミナルです。何かを説明する層はテキストだけで、枠は長すぎるものを切り詰めます。エラーは問題と解決策を同じ文言の中で示さなければなりません。読者はその行を離れて別の行を読むことができません。
文言は自らの文脈の代価を払います。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)