エリシテーション

このスキルは、会話を通じて 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 ファイルの最初の行である必要があります。現在の言語バージョン番号を使用してください。

適切な抽象化レベルの発見

具体的すぎると実装を仕様化することになります。抽象的すぎると有用なことは何も言っていません。

「なぜ」テスト

すべての詳細について、「ステークホルダーはこれについて何を気にするのか?」と問い掛けます。

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

「異なる実装ができるか」テスト

「これは、同じシステムであっても異なる方法で実装される可能性があるか」と問い掛けます。

• はい の場合、それはおそらく実装の詳細です。抽象化してください。
• いいえ の場合、それはおそらくドメインレベルです。含めてください。

例:

• 「Slack 経由で通知を送信します」。メール、SMS など にできます。Notification.created(channel: ...) に抽象化します。
• 「インタビュアーは 3 時間以内に確認する必要があります」。この特定の期限はドメインレベルで重要です。期間を含めます。
• 「PostgreSQL を使用しています」。任意のデータベースにできます。含めません。
• 「コンプライアンスのために 7 年間データが保持されます」。規制要件です。含めます。

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

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

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

インスタンスがドメイン関心事である場合もあります。「Salesforce と特別に統合します」は競争力のある機能かもしれません。「正確にこれら 3 つの OAuth プロバイダーをサポートします」は設計スコープかもしれません。

不確かな場合は、ステークホルダーに質問してください:「これを変更したら、異なるシステムですか、それともただの異なる実装ですか?」

抽象化レベル

抽象的すぎる:        「ユーザーは物事をすることができます」
                              |
製品レベル:          「候補者は面接の招待を承認または辞退できます」
                              |
具体的すぎる:        「候補者がボタンをクリックして POST を /api/invitations/:id/accept に送信します」

抽象的すぎるサイン。 仕様はほぼすべてのシステムを説明できます。テスト可能なアサーションがありません。プロダクトオーナーが「でも それはキャプチャしていません...」と言います。

具体的すぎるサイン。 テクノロジー、フレームワーク、または API に言及しています。UI 要素 (ボタン、ページ、フォーム) を説明しています。実装チームが「なぜこの構築方法を指示しているのか?」と言います。

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

特定の値 (3 時間、7 日など) に遭遇したときは、以下を問い掛けます:

1. この値は設計決定ですか? それを含めます。
2. デプロイメントまたは顧客ごとに異なる可能性がありますか? それを設定可能にします。
3. 任意のものですか? それを含めるかどうかを検討します。

-- ハードコーディングされた設計決定
rule InvitationExpires {
    when: invitation: Invitation.created_at + 7.days <= now
    ...
}

-- 設定可能
config {
    invitation_expiry: Duration = 7.days
}

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

ブラックボックス

いくつかのロジックは重要ですが、異なるレベルに属しています:

-- ブラックボックス: それが存在することと何を検討するかはわかっていますが、方法はわかりません
ensures: Suggestion.created(
    interviewers: InterviewerMatching.suggest(
        considering: {
            role.required_skills,
            Interviewer.skills,
            Interviewer.availability,
            Interviewer.recent_load
        }
    )
)

仕様は、マッチングアルゴリズムが存在し、これらの入力を検討し、インタビュアーの提案を生成することを述べています。仕様は、マッチング方法、使用される重み、または特定のアルゴリズムは述べていません。

これは、アルゴリズムが複雑で進化し続けている場合、プロダクトオーナーが内部ではなく入出力を気にする場合、および必要に応じて詳細な仕様で対応できる場合に適切なレベルです。

初期プロンプトの読み取り

アプローチを選択する前に、ユーザーが提示しているものを評価します。初期プロンプトは、どこから開始するかを示します。

ユーザーがプロセスを説明します。 「採用パイプラインがあり、候補者が申請して、スクリーニングされて、インタビューを受けて、それから決定します。」 プロセスレベルで考えています。プロセスディスカバリーで開始 — フローを説明させ、仕様構成に整理するのを支援します。プロセスディスカバリー を参照してください。

ユーザーがエンティティを命名します。 「Order エンティティを仕様化する必要があり、状態と遷移があります。」 すでに構成レベルで考えています。プロセスディスカバリーをスキップして、スコープ定義に移動し、詳細を入力します。ルールとサーフェスを作業する際は、詳細エリシテーション を参照してください。

ユーザーは漠然とした考えを持っています。 「顧客サポートの管理用に何かを構築する必要があります。」 アイデアを仕様化する前に形作るのに支援が必要です。オープンな質問を使用してプロセスディスカバリーで開始します: 「顧客がヘルプについて連絡してきたときに何が起こるかを教えてください。」 プロセスディスカバリー を参照してください。

ユーザーが既存コードを持っています。 「支払いサービスがあり、それが何をするかをキャプチャしたいです。」 これはエリシテーション付きの蒸留です。ユーザーを distill スキルに指し示すか、または両方を組み合わせます: コードから構造を蒸留し、ステークホルダーから意図をエリシテーションします。

ユーザーが既存仕様を持っています。 最初に仕様を読みます。仕様の評価 を使用して、各エンティティが開発のどのレベルにあるかを判断します。仕様がすでにカバーしているフェーズをスキップします — すでにスコープコメントを持つ仕様に対してスコープの質問を再度尋ねたり、すでに遷移グラフを持つ仕様に対してプロセスを再発見しないでください。各エンティティが必要とするレベルで開始します: ライフサイクルがあるが規則がないエンティティについては詳細エリシテーション、規則があるが失敗パスがないエンティティについては障害エリシテーション。

エリシテーション方法論

フェーズ 0: プロセスディスカバリー

目標: 構成を識別する前に、システムがサポートするプロセスを理解します。

すべてのセッションがこのフェーズを必要とするわけではありません。ユーザーがすでにエンティティとライフサイクルを念頭に置いている場合は、フェーズ 1 にスキップしてください。プロセス説明または漠然とした考えで到着する場合は、ここから開始します。

Allium 構造を課す前に、ユーザーに自分の言葉でシステムを説明させてください。プロセス、アクター、成果をキャプチャし、構成に整理します。特定のテクニックについては プロセスディスカバリー を参照してください。

成果: プロセス名と成果。ステップのおおよそのシーケンス。識別されたアクター。エンティティ定義の粗い仕様 (遷移グラフと未解決の質問を含む) を書くのに十分です。

注視すること: エンティティ定義に早すぎるジャンプしたい衝動。フローが明確になるまでプロセスレベルにとどまる。

フェーズ 1: スコープ定義

目標: 何を仕様化しているのか、境界はどこにあるのかを理解します。

質問すること:

1. 「このシステムの根本的なテーマは何か? 1 文で?」
2. 「このシステムはどこで開始し、どこで終わるか? スコープ内対スコープ外は?」
3. 「ユーザーは誰か? 異なるロールがあるか?」
4. 「これが統合する既存システムはあるか? 彼らは何を処理するか?」

フェーズ 0 がスキップされた場合、また質問します: 「このシステムがサポートする主要なプロセスは何か? 各プロセスの成功は何のように見えるか?」 これはエンティティの識別を孤立した名詞の列挙ではなくプロセスに固定します。ユーザーがプロセスを表現するのに苦労する場合は、プロセスディスカバリー のテクニック — 過去時制の想起と結果最優先の質問 — を使用します。

成果: アクターとロールのリスト。コアエンティティのリスト (フェーズ 0 が実行された場合はプロセスから派生)。境界決定 (外部のもの)。1 文の説明。

注視すること: スコープクリープ (「それはまた X、Y、Z もします」と優しく焦点を再調整)。想定された知識 (「明らかに認証を処理します」。明示的にします)。ライブラリ仕様 (OAuth、支払い処理、メール配信など) ではなくアプリケーション固有のロジックを示唆する説明。

フェーズ 2: ハッピーパスフロー

目標: 開始から終了までのメインジャーニーをトレースします。

フェーズ 0 が walking skeleton を生成した場合 (プロセスディスカバリー を参照)、それを開始点として使用します。そうでない場合は、「このプロセスを 1 つのパスだけ構築できたら、それは何か?」 と質問します。skeleton を粗い仕様として記述し、ドメイン用語でユーザーに説明し直します (仕様の評価 を参照)。

その後、肉付けします: 「各ステップをトリガーするもの? 誰が関与するか? 何が変わるか?」 1 つのエンティティに沿ってそのライフサイクルをフォローし、状態遷移、アクター、トリガーをキャプチャします。

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

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

注視すること: エッジケースに早すぎるジャンプ (「でも、もし...」と記録しハッピーパスにとどまる)。実装の詳細が忍び込む (「API エンドポイント...」を結果へリダイレクト)。

仕様構成を記述した後、CLI が利用可能な場合は allium check を実行します。フェーズ 4 まで検証を待たずに、構造的な問題を修正します。

skeleton を確立した後、詳細エリシテーション を参照して、規則、サーフェス、フィールド、データ依存関係を埋める際のテクニックを参照してください。

フェーズ 3: エッジケースと失敗パス

目標: 何が悪くなる可能性があり、システムはどのように対応するかを発見します。

テクニックについては 障害エリシテーション を参照してください。主要なアプローチ:

• プリモーテムを使用します: 「このシステムが構築され失敗している状況を想像してください。何が悪くなったか?」
• 各ステップで: 「誰も何もしなかったら? 1 日後? 1 週間後?」
• 各ハンドオフで: 「誰が引き継ぐか? 彼らはそれが自分の番だと どうやって知るか? 何を見る必要があるか?」
• 各遷移で: 「前提条件が満たされていなかったら? これは反転できるか?」
• 外部依存関係について: 「この情報はどのようにシステムに入るか? 外部サービスが利用不可の場合はどうなるか?」

成果: 例外遷移。requires ガードを持つ時間トリガー。エスカレーションパス。端末エラー状態。不変式。

注視すること: 無限ループ (「その後リトライして、リトライして...」。端末状態が必要)。欠落したエスカレーション。最終的に人間が知る必要があります。

ステークホルダーがシステム全体のプロパティを述べるとき (「残高は決して負になりません」、「同じ候補者のため 2 つのインタビューが重複しません」)、これらはトップレベルの不変式の候補です。invariant Name { expression } 宣言としてキャプチャします。

規則と例外遷移を記述した後、CLI が利用可能な場合は allium check を実行します。次に進む前に問題を修正します。

フェーズ 4: リファインメント

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

テクニックについては 仮定チェック を参照してください。仕様が何を述べているかをドメイン用語で説明し、ユーザーの精神的モデルに対してテストします。具体的なシナリオを仕様全体でトレースします。順序の仮定をテストします。アクター割り当てを検証します。

Allium CLI が利用可能な場合は、allium check を実行し、診断を使用して構造的なギャップを識別します。allium analyse が利用可能で、仕様に規則とサーフェスがある場合は、それを実行して、プロセスレベルのギャップを見つけるために使用します。発見をドメインの質問に変換する方法については、発見のアクション化 を参照してください。

質問すること:

1. 「[エンティティ] を見ると、これらの状態は完全か? 他の状態にある可能性があるか?」
2. 「カバーしていないことはあるか?」
3. 「この規則は [X] を参照しています。それを定義する必要があるか、それとも外部か?」
4. 「この詳細はここで本質的か、それとも詳細な仕様に存在すべきか?」

テクニック: 具体的なシナリオを取り、仕様全体でトレースします。「Alice がシニアエンジニアの役職に応募したとしましょう。彼女の候補性を通して何が起こるかを説明してください。」

成果: 完全なエンティティ定義。文書化された未解決の質問。 延期された仕様が識別された。外部境界が確認された。

同じオブリゲーションパターン (例えば、シリアライゼーションコントラクト、決定的な評価要件) が複数のサーフェスに表示される場合は、再利用するために contract 宣言として抽出することを提案します。

エリシテーション原則

一度に 1 つの質問をする

悪い例: 「エンティティは何か、どの状態にあることができるか、誰がそれらを修正できるか?」

良い例: 「このシステムが管理する主な物は何か?」 その後: 「[Candidacy] を取りましょう。どの状態にある可能性があるか?」 その後: 「誰が候補性の状態を変更できるか?」

含意を通して機能する

選択が生じたときは、最初の答えを受け入れるだけではなく。 結果を探索する。

「48 時間後に招待が期限切れになると言いました。その後、何が起こるか?」 「そして、再試行後もまだ候補者が応答していない場合はどうなるか?」 「応答しない場合、この候補性は永遠に立ち往生しているか?」

これは、彼らがまだ下していない決定を明らかにします。

製品と実装を区別する

実装言語を聞いたときは、リダイレクトします:

彼ら言った	あなたはリダイレクトします
「API は 404 を返します」	「つまり、ユーザーは見つからないと通知されるか?」
「Postgres に保存します」	「どのような情報がキャプチャされるか?」
「フロントエンドはモーダルを表示します」	「ユーザーは確認を促されるか?」
「Cron ジョブを使用します」	「これはスケジュールで起こり、どのくらいの頻度か?」

曖昧さを明示的に表面化

仮定するよりも、未解決の質問を記録する方が良い。

「辞退すべき場合、候補者はプールに戻るべきか、それとも完全に退出すべきか確実ではありません。それを未解決の質問として記録しましょう。」

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

進んで反復する

以前の決定を修正するのは正常です。

「以前、すべての管理者がすべての通知を見ると言いました。しかし、今あなたはロール固有のダッシュボードについて説明しています。その決定を再検討すべきか?」

幅より深さを優先する

最も重要なエンティティを最初に完全に開発します。他のものは粗く、未解決の質問で残します。ユーザーは後のセッションでそれらを肉付けするために戻ることができます。同じ会話ですべてのエンティティを同じレベルに開発しようとすると、何も完成させずにコンテキスト疲労のリスクがあります。

停止する時期を知る

すべてを今仕様化する必要があります。

「これはマッチングアルゴリズムの動作方法に入っています。それを詳細な仕様に延期すべきか?」

「メインフローをカバーしました。報告ダッシュボードは別の仕様のように聞こえます。」

一般的なエリシテーション罠

「明らかに」の罠

誰かが「明らかに」または「当然」と言うとき、調査します。「管理者が承認することが明らかだと言いました。彼らが承認する必要がない場合はある? これは後で自動化される可能性があるか?」

「エッジケーススパイラル」の罠

すぐにすべてのエッジケースをカバーしたい人がいます。「それを未解決の質問としてキャプチャしましょう。今のところ主フローにとどまります。エッジケースに戻ります。」

「曖昧な合意」の罠

具体的なものなしで「はい」を受け入れないでください。「はいと言いました、候補者は再スケジュールできます。何回? 制限があるか? その後、何が起こるか?」

「欠落したアクター」の罠

明確なアクターのない アクションに注視します。 「スロットが解放されると言いました。誰または何がそれらをリリースしているか? それは自動的か、それとも誰かがそれをトリガーするか?」

「同等用語」の罠

異なるステークホルダー、既存コード、または関連する仕様から同じ概念の 2 つの用語を聞いたときは、続行する前にそれを解決します。

「『Purchase』と言いましたが、以前これを『Order』と呼びました。どちらの用語を使うべきか?」

2 つの用語が同等であることに注意するコメントは、解決ではありません。これは両方が実装に表示されることを保証します。1 つの用語を選択し、関連する仕様を相互参照し、すべての参照を更新します。古い用語を「参照」セクションにもどこにも残さないでください。

エリシテーションセッション構造

これらのタイミングは人間が促進するセッションに適用されます。LLM の会話では、クロックを見ているのではなく、フェーズ出力を使用して先に進むことを決定します。

開口部。 Allium を簡潔に説明します: 「ソフトウェアが何をするかをキャプチャしています。構築方法ではなく。」 このセッションのスコープに同意します。

スコープ定義。 アクター、エンティティ、境界を識別します。1 文の説明を取得します。

ハッピーパス。 メインフロー開始から終了までトレースします。 状態、トリガー、成果をキャプチャします。

エッジケース。 タイムアウトと期限。 失敗モード。 エスカレーションパス。

まとめ。 主要な決定を読み返します。 未解決の質問をリストします。 どのエンティティがまだ粗くて、次に何が必要かを名前付けします。 必要に応じて、次のセッションスコープを識別します。

エリシテーション後

仕様に対する既知の変更を行う場合、tend スキルを使用します。 新しい機能領域を追加する実質的な追加、複雑なエンティティ関係、不明な要件) には、仕様がすでに存在する場合でもエリシテーションが引き続き適切なツールです。 仕様と実装の間での整列チェックは、weed スキルに属しています。

リファレンス

• 言語リファレンス、完全な Allium 構文
• 仕様の評価、仕様の成熟度を評価し、分析の適切なレベルを選択する方法
• 発見のアクション化、チェッカー発見をドメインの質問に変換する
• プロセスディスカバリー、ユーザーがプロセスをまだ述べていない場合のテクニック
• 詳細エリシテーション、規則、サーフェス、データ依存関係を埋める際のテクニック
• 障害エリシテーション、失敗パス、タイムアウト、ハンドオフを探索する際のテクニック
• 仮定チェック、仕様がユーザーの精神的モデルと一致することを検証する際のテクニック
• ライブラリ仕様の機会を認識する、エリシテーション中にライブラリ仕様を識別するための信号、質問、意思決定フレームワーク