shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

pr-onboarding

When creating a PR, the generated AI has the skill to describe onboarding in the body of the PR. It passes the contract of changes to reviewers, future selves, and incident responders. It simultaneously ensures reproducibility, falsifiability, and operability of understanding. Trigger conditions: - When creating a PR ("Create a PR", "Write a pull request") - When wanting to enrich the body of the PR ("Write PR description", "Onboard for PR") - When wanting to organize the impact of changes ("Organize the impact scope of this change") - When preparing for a review ("Summarize changes for review")

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

PR Onboarding

PR作成時に「説明」ではなく「変更の契約」を記述し、理解負債の蓄積を防ぐ。

目的

PRオンボーディングの目的は、以下3つを同時に成立させること:

  1. 理解の再現性: 他者が同じ理解に到達できる
  2. 反証可能性: 正しさの根拠（テスト・観測・仕様）が提示され、間違いなら突ける
  3. 運用可能性: 壊れたときに検知でき、戻せる（戻せないなら明記）

合格条件（PR Onboarding Done）

PR本文（＋リンク先）を読むだけで、レビューアが以下を答えられる状態:

| # | 項目 | 内容 | |---|------|------| | 1 | What | 何が変わったか | | 2 | Why | なぜそう変えたか（代替案含む） | | 3 | Invariants | 何を壊してはいけないか | | 4 | Blast Radius | どこに影響するか（境界・波及） | | 5 | Failure Modes | どう壊れうるか | | 6 | Evidence | どう確かめたか（検証・根拠） | | 7 | Rollback | どう戻すか（または戻せない条件） |

ワークフロー

1. 契約確立 → 2. 変更理解 → 3. 意図抽出 → 4. 境界特定 → 5. 不変条件 → 6. 失敗モード → 7. 検証証拠化 → 8. リリース戦略 → 9. レビュー誘導 → 10. DocDD同期 → 11. 不確実性管理

入力（AIに渡すもの）

  • PR差分（diff）と変更ファイル一覧
  • 関連チケット/設計ID（あれば）
  • テスト結果（CIログ or 実行コマンド）
  • DocDDの正本リンク（あれば）

Step 1: オンボーディング契約の確立

PR本文が長文化・散逸しないよう、"出力の契約"を確立。

出力:

  • PR本文に載せる項目（中核6〜8項目）
  • 詳細はリンクに逃がす方針（1〜2画面制限）

Step 2: 変更の意味理解

行数差分ではなく、振る舞い・責務・契約の変化を抽出。

出力:

  • 変更の中心（トップ3）
  • "振る舞いが変わった点"と"変わっていない点"

Step 3: 目的・意図の抽出

Why（設計意図）を、作文ではなく意思決定の記録として残す。

出力:

  • 目的（Goal）
  • 採用理由（Reason）
  • 捨てた代替案（Alternative）と棄却理由

Step 4: 境界と波及（Blast Radius）の特定

出力:

  • 影響範囲（呼び出し元/先、データ、外部I/F）
  • 互換性（後方互換が壊れる条件、移行の必要性）

Step 5: 不変条件の抽出と明文化

出力:

  • Must stay true（最大3つ）
  • 破ったときの症状

Step 6: 失敗モード分析

出力:

  • 壊れ方トップ3（起きやすい/致命的/気づきにくい）
  • 各壊れ方に検知手段を紐づけ

Step 7: 検証の証拠化

出力:

  • 実施した検証（自動/手動）
  • 再現手順（必要なら）
  • 根拠リンク

Step 8: リリース戦略

出力:

  • ロールアウト手順
  • ロールバック手順
  • ロールバック不能条件（あれば）

Step 9: レビュー誘導

出力:

  • レビュー観点
  • 重点ファイル（最大3〜5）
  • 議論すべき論点

Step 10: DocDD同期

出力:

  • 参照した正本へのリンク
  • 更新が必要なドキュメントの指摘
  • 更新内容の差分案

Step 11: 不確実性管理

出力:

  • 未確定事項リスト（最大5）
  • 解消手段
  • マージ条件 or フォローアップの区別

ガードレール（絶対禁止事項）

  1. 根拠なしの断言: もっともらしい説明ほど危険
  2. 未実施の検証の捏造: 信用を一撃で破壊する（最重要）
  3. 長文化で安心させる: 読み手の注意を散らし重要点が埋もれる
  4. 影響範囲の過小評価: 特にデータ、権限、外部I/F、並行性
  5. "問題ないはず"の楽観: 不確実なら不確実として扱い検証へ落とす

詳細は references/guardrails.md を参照。

スキル詳細

各ステップの詳細な実行方法と品質ゲートは references/skills-catalog.md を参照。

評価ルーブリック

PRオンボーディングの品質評価基準は references/evaluation-rubric.md を参照。

PR本文テンプレート（出力例）

## Summary
[変更の中心を1〜3文で]

## Why
- **Goal**: [目的]
- **Reason**: [採用理由]
- **Alternatives**: [検討した代替案と棄却理由]

## What Changed
- [振る舞いが変わった点1]
- [振る舞いが変わった点2]

## Blast Radius
- **Affected**: [影響範囲]
- **Compatibility**: [互換性への影響]

## Invariants (Must Stay True)
| 条件 | 根拠 | 破ったときの症状 |
|------|------|-----------------|
| [条件1] | [コード/テスト] | [症状] |

## Failure Modes
| 種類 | パターン | 検知手段 |
|------|---------|---------|
| 起きやすい | [説明] | [テスト/ログ] |
| 致命的 | [説明] | [テスト/ログ] |
| 気づきにくい | [説明] | [テスト/ログ] |

## Evidence
- [x] 自動テスト: `npm test` 全パス
- [x] 手動検証: [手順]
- 根拠: [リンク]

## Rollout & Rollback
- **Rollout**: [手順]
- **Rollback**: [手順]
- **Cannot rollback if**: [条件があれば]

## Review Focus
- [ ] [重点ファイル1]: [観点]
- [ ] [重点ファイル2]: [観点]

## Unknowns
| 項目 | 解消手段 | ブロッカー? |
|------|---------|-----------|
| [未確定事項] | [手段] | Yes/No |

## Related
- Issue: #XXX
- Docs: [リンク]