| name | ai-led-onboarding |
| context | fork |
| description | 生成AIが人間に対して行う作業開始時オンボーディング。AIが"説明係"ではなく"進行役"として、探索→仮説→検証→要約→未確定の明示を回し、人間が最小スキーマ（因果・境界・不変条件・壊れ方・観測）を短時間で再構築できる状態に導く。トリガー条件: 新しいタスクやコード変更に着手する前（「この機能を修正して」「このバグを直して」）、未知のコードベースを理解する必要がある時、「オンボーディングして」「作業開始の準備をして」「コードを理解したい」、複雑なタスクを始める前の文脈理解が必要な時、「作戦ブリーフを作成して」「安全に始められるようにして」、AIエージェント自身の着手前チェック（preflight、要件・境界・検証・観測のボトルネック解消、ready/partial/blocked判定）が必要な時。 |
AI-Led Onboarding
作業開始時に人間が「全部を知る」のではなく、意思決定が破綻しないだけの最小スキーマを短時間で再構築できる状態に導く。
合格条件（Onboarding Done）
オンボーディングが完了した状態とは、人間が以下6点を自力で説明できる（または根拠リンク付きでAIが提示し、人間が納得できる）状態:
| # | 項目 | 内容 |
|---|
| 1 | 目的 | この作業で何を成立させたいか（何が"成功"か） |
| 2 | 境界 | どこを触り、どこは触らないか（責務と依存の境界） |
| 3 | 不変条件 | 壊してはいけない条件（最大3つに圧縮） |
| 4 | 壊れ方仮説 | 起きやすい/致命的/気づきにくい の3種 |
| 5 | 観測・検証 | 壊れたらどこで検知し、着手前に何を確かめるか |
| 6 | 未確定リスト | まだ分かっていないことと、その解消手段 |
この6点が揃うとスキーマが立つ。大量のドキュメントを読んでも6点が揃っていなければ理解は成立していない。
ワークフロー
1. 契約確立 → 2. 意図抽出 → 3. 入口発見 → 4. 境界マップ → 5. 不変条件 → 6. 壊れ方仮説 → 7. 検証計画 → 8. 理解確認 → 9. ブリーフ生成
Step 1: オンボーディング契約の確立
オンボーディングを"雑談"ではなく"検査工程"として成立させる。
AIがやること:
- 合格条件（上記6点）を宣言し、タイムボックス（10〜15分）を固定
- 「根拠がない断言をしない」「不確実性は明示する」を先に約束
人間から受け取る最小入力:
- タスクの目的（1〜2文）
- 触る予定の入口（ファイル/クラス/関数名が1つでも）
- 参照してほしいドキュメント（あればリンク/ID）
Step 2: タスク意図の抽出
コード理解に入る前に「何のために触るのか」を固定。
AIがやること:
- 目的・成功条件・制約（期限、互換性、性能、セキュリティ）を短問で引き出す
- "要求"と"解決策"を分離して書き直す
出力:
- 目的（1文）
- 成功条件（最大3項目、可能なら数値）
- 制約（最大5項目）
Step 3: ソース・オブ・トゥルース選別
参照優先度を決め、誤誘導を避ける。
AIがやること:
- 参照優先度を明文化（例：仕様・設計→コード→テスト→運用ログ）
- ドキュメントの更新日・対象バージョンを確認し「古い可能性」を明示
- "意図（should）"と"現状（is）"を分けて記述
出力:
- 正本候補のリスト（最大3）と各信頼度
- ドリフト（ズレ）の疑い点
Step 4: 入口発見
AIがやること:
- 変更対象に近い"起点"を特定（エントリポイント、UseCase、Controller等）
- 「読む順番」を提示（最大5ステップ）
Step 5: 境界マップ作成
AIがやること:
- 対象モジュールの責務・依存先・外部I/F・副作用を列挙
- "触るべき境界"と"触らない境界"を区別
出力:
boundary_map:
in: 何が入力か
out: 何が出力か（副作用含む）
depends: 依存（DB/外部API/他モジュール）
owns: 自分が保証すること
Step 6: 不変条件の抽出
AIがやること:
- ドキュメント/テスト/コードから不変条件を候補として抽出
- 今回の作業に関係が深いものを3つまでに圧縮
- 各不変条件に「破ったときの症状」を添える
Step 7: 壊れ方仮説生成
AIがやること:
壊れ方を3種類に分類して提示:
- 起きやすい: 頻繁に発生しうる失敗パターン
- 致命的: 発生すると重大な影響がある失敗
- 気づきにくい: 検出が遅れやすい失敗
各壊れ方に「検知手段（テスト/ログ/メトリクス）」を1つ以上添える。
Step 8: 着手前の最小検証計画
AIがやること:
- 15〜30分以内でできる検証を設計
- 既存テストの実行範囲
- 代表入力での挙動確認
- 主要ログの確認
- "何が起きたら仮説を捨てるか"を明文化（反証条件）
Step 9: 人間の理解確認（問い返しテスト）
AIがやること:
- 人間に対して、合格条件に対応する短問を投げる
- 人間が詰まった箇所を"未知リスト"へ移し、検証計画に接続
Step 10: 作戦ブリーフ生成
合格条件の6点を1〜2画面にまとめる。詳細は references/briefing-template.md を参照。
ガードレール（絶対禁止事項）
- 根拠なしの断言をしない: 断言するならコード・テスト・ドキュメントの参照を必須に
- 不確実性を隠さない: 分からないことは未知リストへ送る
- 長文で安心させない: 長文は注意を散らす。簡潔に
- "正しい設計"を押し付けない: まず境界・不変条件・壊れ方を確定し、設計提案は後段に
- ドキュメント＝真実を前提にしない: DocDDでもドリフトは起こりうる。検証計画が必須
詳細は references/guardrails.md を参照。
ボトルネック別フォローアップ
未知リストの主なボトルネックに応じて、深掘りは既存スキルへ接続する。推奨は多くても3つまでに絞る。
| 主ボトルネック | 接続先 |
|---|
| 要件の曖昧さ | spec-observation, uncertainty-resolution |
| コンテキスト・入口の不明 | impact-analysis, ai-readability-analysis |
| 境界・依存・影響範囲の不確実性 | impact-analysis, dependency-observation, security-observation, concurrency-observation |
| 検証不足 | observation-minimum-set, boundary-observation |
| 観測不足 | operability-observation, observation-minimum-set |
エージェント向け準備ブリーフ
対象が人間ではなくAIエージェント自身の着手判断であるとき、Step 10のブリーフに以下を追加し、ready / partial / blocked を判定する。
boundary_map.avoid_touching: 触らない境界の明示validation_first_step.stop_if: 最初の検証で何が起きたら中断するか（反証条件の最短形）observation_first_step: 最初に見るログ/メトリクスと、それを見る理由
判定基準:
ready: 境界・不変条件・検証の初手が確定し、致命的な未確定がないpartial: 着手はできるが、1〜2項目に残件があるblocked: source of truth・境界・検証のいずれかが未確定で、誤実装や手戻りの確率が高い
スキル詳細
各ステップの詳細な実行方法と品質チェックは references/skills-catalog.md を参照。
使用例
User: src/auth/login.ts のバグを修正したい
Claude:
オンボーディングを開始します。
## オンボーディング契約
- 目標: 作業開始に必要な最小スキーマ（目的・境界・不変条件・壊れ方・観測・未確定）を10〜15分で構築
- 約束: 根拠のない断言はしません。不確実な点は明示します
## 確認させてください
1. このバグの具体的な症状は？（何が期待と異なるか）
2. 修正後の成功条件は？（どうなれば完了か）
3. 参照すべきドキュメントやIssueはありますか？
[回答を受けて、Step 2以降を進行...]
