Communitygithub.com

AI States

AI機能やエージェントが良い回答以外に表示すべき状態(初回利用、作業中、未確認、不確か、拒否、失敗、修正、人への引き継ぎ、エージェントの委任における計画・許可・無人作業・手戻り・確認・取り消し・記憶など)を、正確なコピーと共に状態ボードとして設計し、仕様、テスト、指標まで含めて定義します。AI搭載機能の設計、レビュー、監査を行う際に使用します。

AI States とは?

AI Statesは、LLMやAIを搭載した機能(チャットボット、コパイロット、アシスタント、AI検索、要約ツール、「AIで生成」ボタン、ツールを使用するエージェントなど)において、正常応答以外のあらゆる状態を体系的に設計するためのスキルです。このスキルは、ユーザーが「AIが読み込み中に何を表示すべきか」「AIが知識を持たない場合、誤っている場合、拒否する場合、エラーが発生した場合の表示」「ソースや信頼度の表示方法」「エージェントに与える自律性の度合い」「承認を求めるタイミング」「実行結果の表示方法」などを尋ねたときに使用します。10の必須状態(スピナーの禁止、4種類の「ノー」の区別、部分回答の危険性など)と、エージェント向けの12の委任状態(計画、許可、無人作業、ハンドバック、取り消しなど)を網羅し、各状態のトリガー、表示、コピー、アクション、テスト、測定方法を仕様書形式で定義します。このスキルは、Claude Code、Cursor、CodexなどのAIエージェントツールで活用され、UI/UXデザイナー、プロダクトマネージャー、AIエンジニアが、信頼性の高いAI機能を設計・レビューする際に役立ちます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/milagrosgonzalezarguello-des/ai-states-skill/tree/HEAD/ai-states

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

AI States は何をしますか?

AI機能が正常に動作する瞬間以外の状態をデザインする。

チームはデモをデザインする。ユーザーが質問し、AIが答え、全員が拍手する。しかし実際にユーザーが使うと、AIができないことを質問したり、14秒かかって自信満々に誤った答えを返したり、接続が途切れたり、プロダクトがスピナーと「エラーが発生しました」と表示する。AIが「行動」するようになった今(送信、予約、編集などを無人で実行)、デザインされていない瞬間の影響はさらに深刻になる。AIが何かをしたのに、ユーザーはそれを把握できない。

だから仕事は「チャットをデザインすること」ではない。それは、あらゆる瞬間において、ユーザーがAIが何をしているか、それが何に基づいているか、次に何ができるかを理解していることであり、AIがユーザーの代わりに行動する場合は、何をしたか、どうやって取り消すかを理解していることである。

目標は調整された信頼(calibrated trust)である。つまり、ユーザーは機能をその価値に見合っただけ信頼し、ケースバイケースで判断する。どちらの方向に外れても失敗である。つまり、確認せずに受け入れることと、すべてを手動でやり直すことである。

すべてのAI機能が正しく備えるべきこと

これらを最初に確認する。これらが欠けているとユーザーは気づく。

  1. 裸のスピナー禁止。約2秒後には何が起きているかをユーザーに知らせ、10秒後には停止するか離脱する方法を示す必要がある。
  2. 4種類の「ノー」を区別する。「知らない」(情報がない)、「できない」(機能として備わっていない)、「しない」(許可されていない)、「壊れた」(システム障害)には異なる原因と次のステップがある。4つすべてに1つの汎用エラーを使うと、ユーザーは決して成功しない操作を繰り返し試行することになる。
  3. 「知らない」はエラーではなく、デザインされた状態である。「ドキュメント内でそれを見つけられませんでした」は良い回答である。それが他の回答の信頼性を高める。
  4. 不完全なものを完全に見せてはいけない。部分的結果が完全に見える状態は最も危険であり、誰も確認しなくなる。
  5. 制限は事前に明示する。ユーザーは最初の画面から、何ができて何ができないかを学ぶ。失敗してから学ぶのではない。
  6. すべての行き止まりに脱出経路があり、ユーザーが入力したものは失われない。つまり、入力テキスト、添付ファイル、選択内容、以前の結果は、どんな失敗の後でも保持される。
  7. 確認のコストはやり直しより低い。回答は、その根拠を、重要度に比例して表示する。つまり、主張の横にソース、カバーしたページ数、情報の最新日付など。確認が作業のやり直しと同じなら、その機能は何も節約していない。
  8. 行動する前に表示し、行動した後は取り消せる。送信、削除、支払い、変更を行うものにはプレビューを表示し、取り消し不可能な場合は確認を求める。すべてを確認する必要はない。すべてにプロンプトを出すと、ユーザーは読まずに承認する習慣がつく。
  9. 無人で行われた作業は「おめでとう」ではなく報告として返す。何が行われたか、何が行われなかったか、何が未検証か、どこを最初に見るべきか。
  10. システムが知っていることだけを言う。モデルが裏付けられない信頼度ラベル、何も確認していないのに「確認しました」、何も保存していないのに「記憶します」は避ける。

作業の進め方

  1. 何かを描く前に機能を理解する。必要なもの:AIが何を誰のために行うか;表面(references/surfaces.mdを読む。チャットが適切かどうかを含む);AIが読み取るものと変更できるもの;システムが実際に検出・公開できるもの(ストリーミング、ソース、拒否シグナル、検索スコア、エラータイプ、ステップイベント);人間によるフォールバックが存在するかどうか;言語と文体。ユーザーから与えられたものを読み、不足しているものを一度に質問する。質問できない場合(非対話実行、またはユーザーが離席中)、最も可能性の高い答えを仮定し、それに依存するすべてのトリガーに確認が必要とマークし、仮定をリストアップする。能力をでっち上げてはいけない。システムが検出できない状態は構築できない。これはチームが構築する必要があるシグナルとは異なる。つまり、必要な状態がまだシステムで公開されていないもの(エラータイプ、拒否フラグ)に依存する場合、その状態をデザインし、シグナルテーブルにシグナルを構築予定としてリストする。このテーブルはエンジニアリングチームが最も役立つと感じるものである。

  2. 重要度を設定する。重要度は各状態に必要なものを決定する。

    重要度例何が変わるか
    低ブレインストーミング、文の書き換え、カジュアルな質問軽いタッチ:再生成と編集がセーフティネット
    中ユーザーが行動の基にする要約、自分のアカウントや会社データに関する回答ソース、可視範囲、明確な「見つかりません」
    高お金、健康、法律、セキュリティ、他人に送信されたり不可逆的なもの行動前の確認、パス内の証拠、人間のルート、監査証跡

    重要度はユーザーが出力をどう使うかから決まる。AIが行動するかどうかではない。弁護士が依存する契約書の読み取り専用の要約は高重要度である。行動を取らない高重要度の機能では、「高」はパス内の証拠、可視範囲、人間のルートを意味する。確認するものはない。

  3. 失敗の仕方を確認する(references/failure-modes.md)。ほとんどは静かである:流暢な誤回答、省略、エージェントが要求以上に行うこと、文書に埋め込まれた指示。発生しうる各失敗に対して、それを防ぐ状態またはパターンを命名する。

  4. 状態マップを構築する。references/states.mdのすべての状態を確認し、マークする:

    • 適用 - はい、いいえ(理由付き)、または場合による(確認できなかったシグナルが存在する場合)。
    • 現状(既存のものをレビューする場合)- デザイン済み、不完全(存在するが重要度に必要なものが欠けている。その内容を述べる)、汎用(キャッチオールで処理されている)、欠落。

    場合によるの状態は、仕様ブロックとマップ内の行を取得し、カバレッジストリップでは合計ではなく「確認が必要」としてカウントされ、十分に可能性が高い場合のみカードとして描画される。

    AIが複数のステップを実行したり、ツールを自律的に使用したり、ユーザーが不在の間に作業する場合、references/delegation.mdの委任状態についても同様に行い、各アクションの種類に対して自律性レベルと許可テーブルを記入する。ユーザーが確認した後に1つのアクションを取るチャットはエージェントではない。状態5(「確認後」の画面と取り消し機能)と3列の許可テーブルでカバーされる。D1からD12を無理に当てはめない。ユーザーが単一の状態について質問した場合でもマップをスキップしない。どの他の状態が必要かを伝える。

  5. 適用される各状態を以下の形式で仕様化する。

  6. ボードを描画する。assets/template.htmlから始める。状態ごとに1つのカード。その状態の実際のコンポーネントを最終的なコピーと共に表示する。散文での状態のリストはうなずかれるだけで、ギャップが目に見えて欠けているボードは修正される。製品のルック&フィールが与えられている場合はそれを使用する(色、コンポーネント、スクリーンショット)。それ以外の場合はテンプレートの中立的なスタイルを維持し、そう述べる。機能の実際の表面を描画する。ボタンとパネルの機能には、チャットの吹き出しではなくパネルを描く。複数の画面が必要な状態(確認前と確認後)は、1つのカードにそれらの画面を表示する。新しいデザインの場合、テンプレートの発見ブロックとマップの「現状」列を削除し、カバレッジラインで適用される状態の数、適用されない状態の数、シグナルを待つ状態の数を示す。

  7. コピーを書く。references/copy.mdに従い、製品の言語と文体で書く。

  8. テストスクリプトと測定基準を書く(references/measure.md)。各状態を誘発する1つの入力と、そのためにログに記録する内容。

  9. レビューする。references/checklist.mdとreferences/anti-patterns.mdに照らして、レンダリングされたボード(ソースではなく)を見る。python scripts/screenshot.py board.html board.pngで画像にレンダリングし(アプリ内ブラウザはローカルファイルを拒否することが多い)、ボードが長い場合は--tile 1400を追加して読み取り可能なスライスで取得する。確認後にボードを変更した場合は、再度レンダリングする。

  10. 納品する。ボード、仕様、および仮定したことと回答が必要なことの短いリスト。確認したことと確認していないことを述べる。

読むべきもの。常に:states.md、copy.md、checklist.md、およびこの表面に関するsurfaces.mdのセクション。レビューの場合は、さらにfailure-modes.mdとanti-patterns.md。エージェント(複数ステップ、ツール、無人作業)の場合のみ:delegation.md。テストスクリプトを書くときはmeasure.md。

状態一覧

5つのモーメントにおける14の回答状態。詳細はreferences/states.mdにあり、ユーザーが必要とするもの、パターン、アンチパターン、コピーが記載されている。

モーメント状態ユーザーが尋ねていること
Before1. 初回利用これは何で、何を質問できるのか?
2. 編集中何が使われるのか?入力は適切か?
During3. 作業中何かしているのか?どのくらいかかるか?止められるか?
4. 確認が必要私に何が必要か?
5. 承認が必要これから何をしようとしているのか?
Answer6. 回答これは何に基づいているのか?何ができるか?
7. 部分回答どの部分が完了していて、どれが完了していないのか?
8. 不確かこれをどの程度信頼すべきか?
No9. 知らない答えがないのか、それとも正しい場所を探さなかったのか?
10. できない誰が、または何ができるのか?
11. しない私の問題か、ルールか?代わりに何を尋ねればいいか?
12. 壊れた作業は失われたのか?もう一度試すべきか?
After13. 修正された修正は反映されたか?再発するか?
14. 人に引き継ぎ誰が担当しているのか、何を知っていて、いつ返事が来るのか?

行動するAIのための12の委任状態。詳細はreferences/delegation.mdに記載。

状態ユーザーが尋ねていること
D1. 指示仕事とその制限を理解したか?
D2. 計画どのように実行するのか?変更できるか?
D3. 許可具体的に何に触れることを許可するのか?どのくらいの期間?
D4. 無人作業中順調か?監視する必要があるか?
D5. あなたが必要何を待っているのか?応答しないとどうなるか?
D6. 指示変更新しい指示は反映されたか?
D7. ハンドバック何をしたか、何をしなかったか、どこを最初に見るべきか?
D8. 大規模レビューこれら140の変更のうち、実際に確認する必要があるのはどれか?
D9. 取り消しと修復すべて、あるいはこれだけを取り消せるか?
D10. 不在中にエラーどれほど深刻か?どこで停止したか?
D11. 学習私について何を新たに仮定しているか?
D12. 他者への行動他の人にはどう見えるか?AIによるものだと分かるか?

バックグラウンドで会話なしで動作するエージェントの場合、いくつかの回答状態は、二重に描画するよりも委任状態に置き換えられる。つまり、「編集中」はD1「指示」に、「作業中」はD4に、「確認が必要」はD5に置き換える。マップでは回答状態に「いいえ - D4参照」とマークする。定期ジョブ(毎晩、毎週月曜)には、常設の指示と計画がある。D1とD2はユーザーが一度確認し、各実行前に確認できる設定である。そのようなボードでは、5つのモーメントではなく、時間順(開始前、作業中、ハンドバック時)にカードを配置してもよい。状態番号は維持すること。

製品自体がビジネス上の理由(残高不足、既に予約済みの日付)で拒否するアクションは、AIに関する4つの「ノー」のいずれでもない。状態5の画面として表示し、システムからの理由とユーザーが変更できる内容を示す。

4つの要素がすべての状態に横断的に影響し、ボードにメモとして追加される。割り込み、記憶、プロアクティブ(AIが最初に話す)、コスト(クレジット、クォータ、支出)。references/states.mdの末尾を参照。

5つだけデザインできる場合: 作業中、知らない、壊れた、部分回答、そして行動する場合は承認が必要(無人作業の場合はハンドバック)。これらは信頼が最も早く失われる場所である。

仕様形式

状態ごとに1ブロック。この順序で。開発者はトリガーから構築する。トリガーがなければ、その状態は願望である。

### 9. 知らない
- **トリガー:** 検索がしきい値以上のパッセージを返さない。(確認が必要:しきい値)
- **表示:** 回答バブル、ニュートラルスタイル(エラースタイルではない)。
- **コピー:** 「引越し休暇に関する情報を人事ポリシーで見つけられませんでした。」
- **アクション:** 言い換える · ポリシーを見る · 人事に質問する
- **保持:** 質問(編集可能)。
- **遷移先:** 2 編集中、または14 人に引き継ぎ。
- **テスト:** 「引越し休暇はありますか?」
- **測定:** `answer_not_found` クエリ付き。トピックごとの割合を監視。
- **未解決質問:** システムは「ドキュメントがない」と「ドキュメントは存在するがユーザーにアクセス権がない」を区別できるか?

ラベル(Trigger, Shows, Copy...)は、チームが別の言語で作業する場合は翻訳する。トリガー、表示、テキスト、アクション、保持、遷移先、テスト、測定、未解決質問。

保持はユーザーが失う可能性のあるものすべて。入力テキスト、添付ファイル、選択内容、以前の結果、エージェントが既に行っていた作業。

言語と文体

ユーザーが要求した言語で記述する。明示されない場合は、リクエストの言語と製品の言語を使用する。文体は製品の選択であり、デフォルトではない。製品が既にどのように話しているか(敬体、常体、丁寧か親しみやすいか)を調べ、すべての状態でそれを維持する。エラー状態は、チームが別のトーンに陥りやすい場所である。「完了しました!」と言う製品の中に「エラーが発生しました」というフォーマルな表現があると、別の会社のように見える。

2つの言語が関与する場合がある。コピー(描画された画面内のすべて)は製品の言語と文体で記述する。ボードとその周辺の仕様(状態名、見出し、仕様のラベル、メモ)は、チームが作業する言語で記述する。これはユーザーがあなたに書いてきた言語である。スペイン語を話すチームのボードにテンプレートの英語の見出しを残さないこと。リファレンスファイルの例はフォーマルなスペイン語と英語で書かれている。パターンを示しているので、製品の文体に書き換えてコピーしないこと。

AI自身の声:製品がAIに一人称で話させる場合、「やりました」(「見つけられませんでした...」、「3つのファイルを使いました」)を維持し、感情(「喜んでお手伝いします」)は使わない。機能にペルソナがない場合(ボタン、パネル)、製品の非人称的な声で書く(「ファイルを読み取れませんでした」)。

次に読むもの

  • references/states.md - 各状態の詳細な説明、パターン、アンチパターン、コピーの例。
  • references/delegation.md - エージェントの委任状態。
  • references/copy.md - 良いコピーの書き方。
  • references/checklist.md - 納品前の最終チェックリスト。
  • references/anti-patterns.md - 避けるべき一般的な間違い。
  • references/failure-modes.md - AI機能で発生する可能性のある様々な失敗モード。
  • references/surfaces.md - チャット以外のインターフェースオプション。
  • references/measure.md - テストスクリプトと測定基準の書き方。

関連スキル