elicit

Elicitation

このスキルでは、会話を通じて Allium 仕様を作成する方法を説明します。目標は、曖昧さを明らかにし、実装方法を指定することなく、ソフトウェアの動作を捉えた仕様を作成することです。

仕様のスコープを定める

詳細に踏み込む前に、何を仕様化するのかを明確にします。すべてを1つの仕様にまとめる必要はありません。

最初に尋ねる質問

「この仕様の境界はどこですか？」 システム全体ですか？単一の機能領域ですか？より大きなシステムの中の1つのサービスですか？対象に含めるものと含めないものを明確にしてください。

「意図的に対象外とすべき領域はありますか？」 サードパーティとの連携は、ライブラリの仕様として扱う場合があります。レガシー機能は、仕様化する価値がないかもしれません。一部の機能は、別の仕様に分けたほうがよい場合があります。

「これは新しいシステムですか、それともすでにコードが存在しますか？」 コードが存在する場合、聞き取りを伴う抽出を行います。既存のコードによって、現実的に仕様化できる内容が制約されます。

スコープの決定事項を記録する

各仕様の冒頭に、スコープを記録します。

-- allium: 3
-- interview-scheduling.allium

-- Scope: Interview scheduling for the hiring pipeline
-- Includes: Candidacy, Interview, Slot management, Invitations, Feedback
-- Excludes:
--   - Authentication (use oauth library spec)
--   - Payments (not applicable)
--   - Reporting dashboards (separate spec)
-- Dependencies: User entity defined in core.allium

バージョンマーカー（-- allium: N）は、すべての .allium ファイルの1行目に記述する必要があります。現在の言語バージョン番号を使用してください。

適切な抽象度を見つける

具体的すぎると実装を仕様化することになります。抽象的すぎると、役に立つ情報が何も示されません。

「なぜ」テスト

詳細ごとに、次のように尋ねてください。「ステークホルダーは、なぜこれを重視するのでしょうか？」

詳細	なぜ？	含める？
「ユーザーは Google OAuth でログインします」	認証が必要です	場合によります。「ユーザーは認証します」で十分かもしれません
「Google と Microsoft の OAuth をサポートします」	ユーザーがプロバイダーを選択します	はい。その選択はドメインレベルの事項です
「セッションは24時間後に期限切れになります」	セキュリティ／UX に関する決定です	はい。ユーザー体験に影響します
「セッションは Redis に保存されます」	パフォーマンスのためです	いいえ。実装の詳細です
「パスワードは12文字以上でなければなりません」	セキュリティポリシーです	はい。ユーザーに影響します
「パスワードは bcrypt でハッシュ化されます」	セキュリティの実装方法です	いいえ。何をするかではなく、どのようにするかです

「別の方法でも可能か」テスト

次のように尋ねてください。「これを別の方法で実装しても、同じシステムであり続けますか？」

• はいの場合、実装の詳細である可能性が高いです。抽象化してください。
• いいえの場合、ドメインレベルの事項である可能性が高いです。含めてください。

例：

• 「Slack 経由で通知を送信する」。メールや SMS などに置き換えられます。Notification.created(channel: ...) のように抽象化してください。
• 「面接担当者は3時間以内に確認しなければならない」。この具体的な期限はドメインレベルで重要です。期間を含めてください。
• 「PostgreSQL を使用する」。どのデータベースでも構いません。含めないでください。
• 「コンプライアンスのため、データを7年間保持する」。規制上の要件です。含めてください。

「テンプレートかインスタンスか」テスト

これは物事のカテゴリですか、それとも特定のインスタンスですか？

インスタンス（実装）	テンプレート（ドメインレベル）
Google OAuth	認証プロバイダー
Slack	通知チャネル
15 minutes	リンクの有効期限（設定可能）
Greenhouse ATS	外部候補者ソース

場合によっては、インスタンス自体がドメイン上の関心事です。「Salesforce と特定の連携を行う」ことが競争上の機能である可能性もあります。「この3つの OAuth プロバイダーだけをサポートする」ことが設計スコープである可能性もあります。

判断に迷ったら、ステークホルダーに尋ねてください。「これを変更したら、別のシステムになりますか、それとも実装が変わるだけですか？」

抽象度のレベル

Too abstract:          "Users can do things"
                              |
Product level:         "Candidates can accept or decline interview invitations"
                              |
Too concrete:          "Candidates click a button that POST to /api/invitations/:id/accept"

抽象的すぎる場合の兆候。 ほとんどどのシステムにも当てはまる仕様になっています。テスト可能な主張がありません。プロダクトオーナーから「でも、それでは……が表現されていない」と言われます。

具体的すぎる場合の兆候。 技術、フレームワーク、API に言及しています。UI 要素（ボタン、ページ、フォーム）について説明しています。実装チームから「なぜ作り方まで指定するのですか？」と言われます。

設定とハードコーディング

特定の値（3 時間、7 日など）に遭遇したら、次の点を確認します。

1. この値は設計上の決定事項ですか？ 含めます。
2. デプロイ環境や顧客によって異なる可能性がありますか？ 設定可能にします。
3. この値に根拠はありませんか？ そもそも含める必要があるか検討します。

-- Hardcoded design decision
rule InvitationExpires {
    when: invitation: Invitation.created_at + 7.days <= now
    ...
}

-- Configurable
config {
    invitation_expiry: Duration = 7.days
}

rule InvitationExpires {
    when: invitation: Invitation.created_at + config.invitation_expiry <= now
    ...
}

ブラックボックス

重要なロジックでも、別のレベルで扱うべきものがあります。

-- Black box: we know it exists and what it considers, but not how
ensures: Suggestion.created(
    interviewers: InterviewerMatching.suggest(
        considering: {
            role.required_skills,
            Interviewer.skills,
            Interviewer.availability,
            Interviewer.recent_load
        }
    )
)

仕様には、一致アルゴリズムが存在し、これらの入力を考慮して面接担当者の候補を提示することが記載されています。マッチングの仕組み、使用する重み付け、具体的なアルゴリズムについては記載されていません。

アルゴリズムが複雑で進化し続けている場合、プロダクトオーナーが内部の仕組みよりも入力と出力を重視する場合、また必要に応じて別の詳細仕様で扱える場合には、これが適切な詳細度です。

最初のプロンプトを読む

アプローチを選ぶ前に、ユーザーがどのような情報を提示しているかを評価します。最初のプロンプトから、どこから始めるべきかがわかります。

ユーザーがプロセスを説明する場合。 「候補者が応募し、選考を受け、面接を経て、その後に採否を決定する採用パイプラインがあります。」ユーザーはプロセスのレベルで考えています。プロセスの発見から始め、流れを説明してもらってから、それを仕様の構成要素として整理します。プロセスの発見を参照してください。

ユーザーがエンティティを挙げる場合。 「状態と遷移を持つ Order エンティティの仕様を作成したいです。」ユーザーはすでに構成要素のレベルで考えています。プロセスの発見は省略し、スコープの定義に進んでから詳細を詰めます。ルールやインターフェースを検討する際は、詳細の聞き出しを参照してください。

ユーザーのアイデアが漠然としている場合。 「カスタマーサポートを管理する何かを作る必要があります。」仕様を作成する前に、アイデアを具体化する手助けが必要です。「お客様がサポートを求めて連絡してきたとき、どのようなことが起きるのか教えてください」など、自由回答式の質問を使ったプロセスの発見から始めます。プロセスの発見を参照してください。

ユーザーに既存のコードがある場合。 「決済サービスがあり、その機能を文書化したいです。」これは聞き出しを伴う抽出作業です。distill スキルを案内するか、両方を組み合わせます。コードから構造を抽出し、関係者から意図を聞き出します。

ユーザーに既存の仕様がある場合。 まず仕様を読みます。仕様の評価を使って、各エンティティの開発段階を判断します。仕様ですでに網羅されているフェーズは省略します。スコープのコメントがある仕様についてスコープの質問を再度したり、遷移グラフがある仕様についてプロセスを再発見したりしないでください。各エンティティに必要な段階から始めます。ライフサイクルはあるがルールがないエンティティには詳細の聞き出しを、ルールはあるが失敗経路がないエンティティには障害の聞き出しを行います。

聞き出しの方法論

フェーズ 0：プロセスの発見

目標： 構成要素を特定する前に、システムがサポートするプロセスを理解します。

すべてのセッションでこのフェーズが必要なわけではありません。ユーザーがエンティティとライフサイクルをすでに想定している場合は、フェーズ 1 に進みます。プロセスの説明や漠然としたアイデアから始まる場合は、ここから始めます。

Allium の構造を当てはめる前に、ユーザー自身の言葉でシステムを説明してもらいます。プロセス、関係者、成果を把握してから、構成要素として整理します。具体的な手法については、プロセスの発見を参照してください。

成果物： プロセスの名称と成果。大まかな手順の流れ。特定された関係者。遷移グラフを持つエンティティと未解決の質問を含む、粗い仕様を作成するために必要な情報。

注意点： 早い段階でエンティティの定義に飛びつきたくなること。流れが明確になるまでは、プロセスのレベルにとどまります。

フェーズ 1：スコープの定義

目標： 何を仕様化するのか、境界がどこにあるのかを理解します。

質問例：

1. 「このシステムの本質は何ですか？ 一文で説明すると？」
2. 「このシステムはどこから始まり、どこで終わりますか？ スコープに含まれるものと含まれないものは何ですか？」
3. 「ユーザーは誰ですか？ 異なる役割がありますか？」
4. 「連携する既存のシステムはありますか？ それらは何を担当していますか？」

フェーズ 0 を省略した場合は、次の質問もします。「このシステムがサポートする主要なプロセスは何ですか？ それぞれで、何をもって成功としますか？」これにより、名詞を個別に列挙するのではなく、プロセスを基準にエンティティを特定できます。ここではプロセスの発見の手法も活用できます。ユーザーがプロセスをうまく説明できない場合は、過去形で思い出してもらい、結果を先に尋ねてください。

成果物： アクターと役割の一覧。コアエンティティの一覧（フェーズ 0 を実施した場合は、プロセスから導出）。境界に関する判断（外部となるもの）。一文での説明。

注意点： スコープの拡大（「さらに X、Y、Z も行います」など。やんわりと話題を戻します）。暗黙の了解（「当然、認証も処理します」など。明確にするよう促します）。アプリケーション固有のロジックではなく、ライブラリ仕様を示唆する説明（例：OAuth、決済処理、メール配信）。

フェーズ 2：正常系のフロー

目標： 開始から終了までの主要な流れをたどります。

フェーズ 0 でウォーキングスケルトン（プロセスの発見を参照）が作成されている場合は、それを出発点にします。そうでない場合は、「このプロセスを通る経路を一つだけ構築できるとしたら、どの経路ですか？」と尋ねます。スケルトンを大まかな仕様として書き、ドメイン用語を使ってユーザーに説明します（仕様の評価を参照）。

その後、詳細を詰めます。「各ステップのきっかけは何ですか？ 誰が関わりますか？ 何が変わりますか？」一つのエンティティのライフサイクルを追い、状態遷移、アクター、トリガーを記録します。

Candidacy:
  applied -> screening -> interviewing -> deciding -> hired | rejected

成果物： 主要なエンティティの遷移グラフ。主要なトリガーとその結果。各ステップのアクターの割り当て。

注意点： 早い段階でエッジケースに飛びつくこと（「でも、もし……」など。記録して、正常系の流れに戻ります）。実装の詳細に踏み込むこと（「API エンドポイントが……」など。結果に話題を戻します）。

仕様の構成要素を書いた後、CLI が利用できる場合は allium check を実行します。続行する前に構造上の問題を修正してください。検証をフェーズ 4 まで待たないでください。

スケルトンを確立した後、ルール、サーフェス、フィールド、データ依存関係を補う手法について、詳細の引き出しを参照してください。

フェーズ 3：エッジケースと失敗経路

目標： 何が問題になりうるか、またシステムがそれをどう処理するかを明らかにします。

手法については障害要因の引き出しを参照してください。主なアプローチは次のとおりです。

• プレモーテムを行います。「このシステムが構築され、失敗していると想像してください。何が問題だったのでしょうか？」
• 各ステップで尋ねます。「ここで誰も何もしなかったらどうなりますか？ 1 日後は？ 1 週間後は？」
• 各引き継ぎで尋ねます。「誰が引き継ぎますか？ 自分の番だとどうすればわかりますか？ 何を確認する必要がありますか？」
• 各遷移で尋ねます。「前提条件が満たされていなかったらどうなりますか？ 元に戻せますか？」
• 外部依存関係について尋ねます。「この情報はどのようにシステムに入りますか？ 外部サービスが利用できなかったらどうなりますか？」

成果物： 例外遷移。requires ガードを持つ時間的トリガー。エスカレーション経路。終端エラー状態。不変条件。

注意点： 無限ループ（「その後、再試行して、また再試行して……」など。終端状態が必要です）。いずれ人間が把握する必要があるのに、エスカレーションが欠けていること。

ステークホルダーがシステム全体に関わる特性（「残高は決してマイナスにならない」「同じ候補者の面接が重複することはない」など）を述べた場合、これらはトップレベルの不変条件の候補です。invariant Name { expression } 宣言として記録します。

ルールと例外遷移を書いた後、CLI が利用できる場合は allium check を実行します。詳細化に進む前に、問題を修正してください。

フェーズ 4：詳細化

目標： 仕様を検証し、完成させます。

手法については前提条件の確認を参照してください。仕様に記載されている内容をドメインの用語で説明し、ユーザーのメンタルモデルと照らし合わせて検証します。具体的なシナリオを仕様に沿って追跡します。順序に関する前提を検証します。アクターの割り当てを確認します。

Allium CLI が利用できる場合は、allium check を実行し、診断情報を使って構造上の不足を特定します。allium analyse が利用でき、仕様にルールとサーフェスがある場合は、これを実行して、プロセスレベルの不足を明らかにするために結果を活用します。結果をドメインに関する質問へと変換する方法については、結果への対応を参照してください。

次のような質問をします。

1. 「[entity]を見てください。状態はこれですべてですか？ほかの状態になることはありますか？」
2. 「ほかに、まだ取り上げていないことはありますか？」
3. 「このルールは[X]を参照しています。これを定義する必要がありますか？それとも外部のものですか？」
4. 「この詳細はここで必要ですか？それとも詳細仕様に記載すべきですか？」

手法： 具体的なシナリオを取り上げ、仕様に沿って追跡します。「たとえば、Alice がシニアエンジニア職に応募するとします。Alice の候補者情報に何が起こるか、順を追って説明してください。」

成果物： 完全なエンティティ定義。文書化された未解決の質問。特定された保留中の仕様。確認済みの外部境界。

同じ義務のパターン（たとえば、シリアライズの契約や決定論的な評価要件）が複数のサーフェスに現れる場合は、再利用できるように contract 宣言として切り出すことを提案します。

ロジックと同じくらい結果の形式も明確にする

結果の形式は、最も抜け落ちやすい判断事項です。省略されたり、半端な形でしか記録されなかったり、さらにはスコープ外にされたりします。中核となる手法と同じ深さまで掘り下げて確認します。

• 結果の形式を、フィールドごとに直接確認します。「これは正確には何を返し、何を報告する必要がありますか？すべてのフィールドを教えてください。」代表例ではなく、完全な一覧を確認します。
• 算出とは異なる基準で導出、開示、または報告される数値には、中核となる手法と同等の確認が必要です。 正確な定義、基準、精度、特殊なケースでの挙動を明確にし、曖昧さがなくなるまで追加の質問をします。ここでの一行だけの回答には、見落としやすい要件が隠れています。たとえば、発生時とは異なる日数計算基準で開示される利率や、システム内で保持する値とは異なる顧客向けの数値などです。
• 結果の形式は、デフォルトでスコープに含まれます。 システムが返す、または開示する必要のある内容を、決してスコープ外にしないでください。出力を除外する場合は、黙って省略するのではなく、運用担当者に確認すべき判断事項です。

終了する前に：網羅性の確認

インタビューは、主要な流れがまとまったと感じた時点では、まだ終わっていません。実際には、その時点で終えるのは早すぎます。その感覚だけで終わりと判断しないでください。会話が完了したとみなす前に、運用担当者が話した内容すべてに照らして、次の判断事項を一つずつ確認してください。このシステムに関係する各項目について、実際に回答を得ているか確認します。回答がなければ、今すぐ具体的で答えやすい質問をし、関連するすべての項目について質問し、回答を得る（または対象外であることを明確にする）まで続けてください。一度も尋ねていない項目は「想定済み」ではなく、単に未質問です。要件に記載がないことは、推測してよいという意味ではなく、質問すべきだという合図です。

• 主要な方式またはルール。 結果を計算、導出、決定する際に、認められた方式や規約が複数ある場合、この組織ではどれを採用しますか？一般的な既定値を前提にしないでください。
• 単位と精度。 数量の測定単位、その精度、およびより細かい値の扱い方。
• 丸めまたは切り捨て。 値を単位に合わせる際、どちらの方向に処理するか、端数がある場合はどこに反映するか。
• 順序と優先順位。 複数の項目を適用または処理する際の順序と、同順位の場合の優先方法。
• しきい値と上限・下限。 最小値、最大値、上限、許容差、およびそれを下回った場合に免除、無視、またはゼロとして扱われる値。
• タイミングと適用日。 何かが効力を生じる時点と記録される時点、過去の日付への遡及、過去の時点における再計算、および締め切り時刻。
• 同時実行と順序付け。 2つの処理が同時または短時間の間に発生した場合の順序と、同順位の場合の決定方法。
• 境界となる入力値。 ゼロ、負の値、空、欠損、重複、範囲外のそれぞれについて、拒否、無視、処理のどれを行うか、またレコードを保持するかどうか。
• 余剰と不足。 余ったものや不足したものをどう扱うか（保留、返却、繰り越し、エスカレーションなど）、また次に何に対して適用するか。
• 対象範囲の境界。 このシステムが担うものと、上流システムまたは外部システムが提供するもの。対象外とすることは、黙って省略するのではなく、確認すべき判断です。
• 出力とレポートの形式。 結果に含める必要があるすべての項目、および計算方法や保存方法とは異なる基準で報告または開示する数値。
• 作成時だけでなく、ライフサイクル全体。 作成され通常どおり進行することにとどまらず、対象がその全期間に経験するあらゆるイベント（早期終了またはキャンセル、期間中の変更または修正、一時停止または中断、更新または延長、取り消し、移転、満了、終了または段階的な廃止など）と、それぞれについて何を再計算し、残っているものをどう扱うか。この項目は特に見落とされがちです。対象となるエンティティについて、これらを一つずつ挙げ、該当するか尋ねてください。

上記の関連項目に、未質問のまま想定されているものが一つでもある限り、まだ終わりではありません。

情報を引き出すための原則

質問は一度に一つ

悪い例：「どのようなエンティティがあり、それぞれどのような状態になり、誰が変更できますか？」

良い例：「このシステムが管理する主なものは何ですか？」 続けて：「[Candidacy] について見てみましょう。どのような状態になり得ますか？」 続けて：「候補者の状態を変更できるのは誰ですか？」

影響を掘り下げる

選択肢が出てきたら、最初の回答をそのまま受け入れず、結果を掘り下げてください。

「招待の有効期限は48時間とのことですが、その後はどうなりますか？」 「再試行しても候補者から返答がない場合はどうなりますか？」 「まったく返答がなかった場合、この候補者は永久にこの状態のままになりますか？」

こうすることで、まだ決められていないことが明らかになります。

プロダクトと実装を区別する

実装についての言い回しが出てきたら、話題を戻します。

相手の発言	話題の戻し方
「API が 404 を返します」	「つまり、見つからないことがユーザーに伝わるのですね？」
「Postgres に保存しています」	「どのような情報を記録するのですか？」
「フロントエンドにモーダルを表示します」	「ユーザーに確認を促すのですね？」
「cron ジョブを使っています」	「これは定期的に実行されるのですね。どのくらいの頻度ですか？」

あいまいさを明示する

決めつけるより、未解決の質問として記録するほうがよいです。

「辞退された場合、候補者を候補者プールに戻すのか、完全に除外するのか、まだはっきりしません。未解決の質問として記録しておきます。」

open question "When candidate declines, do they return to pool or exit?"

ためらわずに反復する

以前の決定を見直すのは普通のことです。

「以前は、すべての管理者にすべての通知が表示されると言っていました。しかし今は、役割ごとに異なるダッシュボードについて説明されています。その点を見直しますか？」

幅広さより深さを優先する

まず、最も重要なエンティティを十分に掘り下げます。ほかのエンティティは、未解決の質問を残したまま大まかに扱います。ユーザーは後のセッションで詳しく検討できます。1 回の会話ですべてのエンティティを同じレベルまで掘り下げようとすると、何も完了しないままコンテキストを使い切るおそれがあります。

いつ切り上げるかを見極める

今すぐすべてを仕様化する必要はありません。

「マッチングアルゴリズムの仕組みに話が及んでいます。詳細な仕様に回しますか？」

「主要なフローは確認できました。レポート用ダッシュボードは別の仕様にしたほうがよさそうです。」

よくある聞き取りの落とし穴

「当然」 trap

誰かが「当然」や「もちろん」と言ったら、詳しく尋ねます。「管理者が承認するのは当然だと言いましたね。承認が不要な場合はありますか？後で自動化できるでしょうか？」

「エッジケースの深掘り」 trap

すべてのエッジケースをすぐに検討したい人もいます。「それは未解決の質問として記録し、ひとまず主要なフローを続けましょう。エッジケースには後で戻ります。」

「あいまいな同意」 trap

具体的な内容を確認せずに「はい」を受け入れてはいけません。「候補者は日程を再調整できるとおっしゃいましたね。何回までですか？上限はありますか？その後はどうなりますか？」

「アクターの欠落」 trap

実行者が明確でないアクションに注意します。「『枠が解放される』と言いましたね。誰が、または何が解放するのですか？自動ですか、それとも誰かが実行しますか？」

「同義語」 trap

異なるステークホルダー、既存のコード、関連する仕様で、同じ概念に対して 2 つの用語が使われていることに気付いたら、先に進む前に立ち止まって解決します。

「『Purchase』と言いましたが、先ほどは『Order』と呼んでいました。どちらの用語を使うべきですか？」

2 つの用語が同じ意味だと記すだけでは、解決になりません。そうすると、実装で両方が使われることになります。用語を 1 つ選び、関連する仕様を相互参照して、すべての参照箇所を更新します。「関連項目」などの注記も含め、古い用語をどこにも残さないでください。

聞き取りセッションの構成

以下の所要時間は、人が進行するセッションを想定しています。LLM との会話では、時間を気にするのではなく、各フェーズの成果をもとに次へ進むか判断してください。

開始。 Allium について簡潔に説明します。「ソフトウェアの仕組みではなく、ソフトウェアが何をするかを記録します。」このセッションの範囲について合意します。

範囲の定義。 アクター、エンティティ、境界を特定します。一文で説明できるようにします。

正常系。 主要なフローを開始から終了まで追います。状態、トリガー、結果を記録します。

エッジケース。 タイムアウトと期限。障害モード。エスカレーション経路。

まとめ。 重要な決定を読み返します。未解決の質問を列挙します。大まかなままのエンティティと、次に必要な内容を明らかにします。必要に応じて、次回セッションの範囲を決めます。

聞き取りの後

すでに実現したい内容がわかっている、対象を絞った変更には tend スキルを使用します。構造化された調査が必要な大規模な追加（新機能領域、複雑なエンティティ間の関係、不明確な要件）では、すでに仕様が存在していても、引き続き適切なツールは elicit です。仕様と実装の整合性確認には weed スキルを使用します。

参考資料

• 言語リファレンス、Allium の構文全般
• 仕様の評価、仕様の成熟度を評価し、適切な分析レベルを選択する方法
• 調査結果への対応、チェッカーの調査結果をドメインに関する質問に変換する方法
• プロセスの発見、ユーザーがまだプロセスを明確に説明できていない場合の手法
• 詳細の引き出し、ルール、対象範囲、データ依存関係を補足する手法
• 障害要因の引き出し、失敗経路、タイムアウト、引き継ぎを検討する手法
• 前提の確認、仕様がユーザーのメンタルモデルと一致しているかを検証する手法
• ライブラリ仕様の機会を見極める、引き出しの過程でライブラリ仕様を特定するための兆候、質問、判断フレームワーク