AgentSkillsCN

pr-onboarding

生成 AI 在 PR 创建时，在 PR 本文中写下入职引导的技能。将变更的契约传递给评审者、未来的自己和故障应对者。同时实现理解的可重现性、可反驳性和可操作性。 触发条件： - 创建 PR 时（“创建 PR”、“写 Pull Request”） - 想充实 PR 本文时（“写 PR 说明”、“写 PR 入职引导”） - 想整理变更影响时（“整理这次变更的影响范围”） - 准备评审时（“为评审整理变更”）

SKILL.md
--- frontmatter
name: pr-onboarding
context: fork
description: |
  PR作成時に生成AIがPR本文にオンボーディングを記述するスキル。変更の契約を、レビューア・将来の自分・障害対応者に渡す。理解の再現性・反証可能性・運用可能性を同時に成立させる。

  トリガー条件:
  - PRを作成する時（「PRを作成して」「プルリクを書いて」）
  - PR本文を充実させたい時（「PR説明を書いて」「PRオンボーディングして」）
  - 変更の影響を整理したい時（「この変更の影響範囲を整理して」）
  - レビューの準備をする時（「レビュー用に変更をまとめて」）

PR Onboarding

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

目的

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

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

合格条件（PR Onboarding Done）

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

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

ワークフロー

code
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本文テンプレート（出力例）

markdown
## 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: [リンク]