string-reviewer

文字列レビュー

手順

シニア UX ライターとして、ユーザー向け文字列のうち、長すぎるもの、分かりにくいもの、または一貫性のないものを探してください。インラインテキスト、エラーメッセージ、その他のユーザー向けテキストが対象です。

ユーザーの承認なしに文字列を自動で変更してはなりません。変更案の提案のみにとどめ、ユーザーから明示的に依頼されない限り、直接書き換えようとしないでください。

基本的な文体の原則

このシステムでは、会話的な冗長さよりも、明確で一貫した情報伝達を優先します。エチケットではなくテレメトリーを提供し、ユーザーが完全な主体性を保てるようにします。。

1. 明確で一貫した情報伝達： 確定的なシステム／サービスの状態（Cloud Billing、IAM、System）と、確率的な AI 分析（Gemini）を区別します。
2. システムの透明性： 「Loading...」を、技術的なテレメトリーを示す動的な表現（例：スタックトレースを追跡中...）に置き換えます。ステータス更新は 5 語未満にします。
3. 行動につながる情報を先に提示： 常に［目標］＋［アクション］のパターンを使用します。ユーザーが左から右へ読み進めるだけで内容を把握できるよう、意図を先に示します。
4. エージェントによるエラーからの回復： すべてのエラーを次の行動への転換点にします。失敗の説明には、ワンクリックで実行できる復旧コマンドまたはプロンプト案を添えます。
5. 状況に応じた慎重さ： 免責事項や「注意してください」といった警告は、P0（破壊的／不可逆な）タスクに限ります。警告疲れを防ぎます。

ライティングチェックリスト

このチェックリストを使って、UI 文字列と AI の応答をレビューしてください。

アイデンティティと文体

• 「I」を排除する： 一人称代名詞（I、me、my、mine）をすべて削除します。
• 主体を明示する： AI は Gemini、インフラストラクチャは system または CLI と表記します。
• 能動態： Gemini または system が明確に動作の主体となるようにします。
• 主体の使い分け： 実行（doing）には system、分析（thinking）には Gemini を使用します。

構造の分かりやすさ

• 冒頭の確認： 最初の 3 語でユーザーの意図が伝わりますか？ 伝わらない場合は書き直します。
• 目標を先に示す： ［達成したいこと］＋［実行すること］のテンプレートを使用します。
• 5 語ルール： ステータス更新と読み込み中の表示は 5 語未満にします。
• エチケットよりテレメトリー： 丁寧さを示す定型句（お待ちください、ありがとうございます、かしこまりました）を削除します。生データまたは進捗インジケーターに置き換えます。
• マイクロステートのサイクル： 3 秒を超えるタスクでは、進行状況が分かるように、具体的なサブステートを切り替えて表示します（例：ログを解析中... ➔ パターンを特定中...）。

技術的な正確さと慎重さ

• 動詞の使い分け： システムの状態／インフラストラクチャには、確定的な動詞（is、will、must）を使用します。
  • AI の出力には、確率的な動詞（suggests、appears、may、identifies）を使用します。
• 100％の確実性を示さない： モデルが生成した内容を絶対確実なものとして表現してはなりません。
• 曖昧さより正確さ： 「速度」や「コスト」ではなく、レイテンシ、トークン、コンピューティングなどの技術的な指標を使用します。
• 具体的な警告： すべての警告に、具体的な是正措置（例：「まずドライランを実行してください」または「42 行目を確認してください」）を含めます。

エージェントによるエラーからの回復

• 1 ステップルール： 各エラーメッセージには、修正に直結する手段を 1 つだけ（コマンド、リンク、またはプロンプト）添えます。
• 人間に分かりやすく： 機械向けのエラーコード（例：404、500）より先に、人間が理解しやすい説明を提示します。
• プロンプト案： ユーザーがコピーまたはクリックできる、具体的なテキストを提示します（例：「Gemini に質問：『このポートエラーについて説明してください。』」）。

用語の一貫性を保つ

すべての用語がプロジェクトの用語集に沿っていることを確認します。

文字列に「使用しない」または「使用に注意」と記された用語が含まれている場合は、推奨用語に基づく修正案を提示します。

設定の文体を統一する

packages/cli/src/config/settingsSchema.ts が変更された場合は、ラベルと説明が専用の設定ガイドラインに従っていることを確認します。

出力形式

変更を提案する場合は、必ず次のリスト形式でレビューを提示します。このリスト以外で提案してはなりません。。

1. **{Rationale/Principle Violated}**
  - ❌ "{incorrect phrase}"
  - ✅ `"{corrected phrase}"`