yytypescript PR・コミットメッセージ作成ガイド
このドキュメントは、Pull Request（PR）とコミットメッセージを一貫した品質で作成するためのAIエージェント向け指示書です。
1. このスキルの役割
このスキルは、コミットタイトル/本文、PRタイトル/本文を「提案する」ことが目的です。
やること
- 変更内容を分析し、適切なタイトルと本文を提案する
- 提案内容をユーザーに提示する
やらないこと
git commitの実行- PRの作成
- その他のGit操作
コミットやPRの実行は、ユーザーが提案内容を確認・承認してから行ってください。
2. 品質目標
- PRやコミットを見ただけで変更の意図と価値が伝わるようにする
- Issueを読まなくてもPRだけで内容を理解できるようにする
- 誰が書いても同じ品質のPR・コミットメッセージになるようにする
3. 対象者の分類
変更が誰に影響するかを明確にします。
| 対象者 | 説明 | 例 |
|---|---|---|
| 📖 読者 | 本書を読んでTypeScriptを学ぶ人 | コンテンツ追加・改善、誤り修正、サイトUI |
| ✍️ 執筆者 | 本書の執筆・改善に貢献する人 | 開発環境、執筆ガイド、ビルド設定、依存関係更新 |
4. コミットタイトル/PRタイトル
4.1. 形式
[変更の要約]（日本語、「〜しました。」形式）
4.2. ルール
- 50文字以内を目安にする
- 「〜しました。」形式で書く（体言止めは使わない、末尾に「。」をつける）
- 何をしたかが一目で分かるようにする
- 対象者が推測できる表現を使う
4.3. 良い例・悪い例
| ❌ 悪い例 | ✅ 良い例 | 理由 |
|---|---|---|
| Update docs | 「型ガード関数」のサンプルコードを改善しました。 | 具体性がある |
| Fix bug | Prettierチュートリアルでコメントが表示されない問題を修正しました。 | 何を修正したか分かる |
| Add feature | 「オブジェクトのスプレッド構文」ページを追加しました。 | 何を追加したか分かる |
| Refactoring | 開発環境をBun + Devboxに刷新しました。 | 技術的な変更内容が分かる |
4.4. 対象者別のタイトル例
| 対象者 | タイトル例 |
|---|---|
| 📖 読者 | 「オブジェクトのスプレッド構文」ページを追加しました。 |
| 📖 読者 | 「型ガード関数」のサンプルコードから declare を除去しました。 |
| 📖 読者 | JSXページにてReact固有の説明であることを明記しました。 |
| ✍️ 執筆者 | コードブロックの言語指定ガイドラインを追加しました。 |
| ✍️ 執筆者 | 開発環境をBun + Devboxに刷新しました。 |
5. コミット本文/PR本文
5.1. テンプレート
コミット本文とPR本文は、どちらもこのテンプレートに沿って書きます。 コミット本文だけを読んでも変更の意図と価値が分かるように、コミット本文でも対象者、Problem、Solution、Value、Issueの関連付けを省略しないでください。
## 対象者
- [ ] 📖 読者
- [ ] ✍️ 執筆者
## Problem
<!-- 何が問題だったか / 何が不足していたか / どんな課題があったか -->
## Solution
<!-- その問題をどう解決したか -->
## Value
<!-- この変更によって、対象者にどんなメリットがあるか -->
---
Close #xxx
5.2. 各セクションの書き方
対象者
該当するものにチェックを入れます。複数該当する場合は複数チェックしてOKです。
Problem（問題）
以下の観点で記述します：
- 何が問題だったか？
- 何が不足していたか？
- どんな課題があったか？
- 読者/執筆者がどんな困りごとを抱えていたか？
書き方のコツ:
- ですます調で書く
- 「〜でした」「〜がありませんでした」「〜できませんでした」という過去形で書く
- 具体的な状況を説明する
- 可能であれば影響を受ける人の視点で書く
Solution（解決策）
具体的に何をしたかを記述します：
- ですます調で書く
- 何を追加/変更/削除したか？
- どのファイルを変更したか？（大きな変更の場合）
- Before/Afterがあると分かりやすい
Value（価値）
この変更によって対象者が得られるメリットを記述します：
- ですます調で書く
- 「〜できるようになります」「〜が分かるようになります」という形式
- 対象者の視点で書く
Issueの関連付け
必ず Close #xxx または Closes #xxx でIssueを関連付けます。
これによりPRマージ時にIssueが自動でクローズされます。
5.3. 具体例
例1: コンテンツ追加（読者向け）
## 対象者
- [x] 📖 読者
## Problem
配列のスプレッド構文は紹介されていましたが、オブジェクトのスプレッド構文が紹介されていませんでした。実務ではオブジェクトのスプレッド構文も頻繁に使用されるため、読者が網羅的に学べない状態でした。
## Solution
「オブジェクトのスプレッド構文」ページを新規追加しました。
- オブジェクトの作成・コピー・マージ
- 浅いコピーの注意点
- 分割代入と残余パターン
- 配列のスプレッド構文ページとの相互リンク
## Value
読者がオブジェクトのコピーやマージの実践的なパターンを体系的に学べるようになります。
---
Close #828
例2: 分かりやすさ改善（読者向け）
## 対象者
- [x] 📖 読者
## Problem
「型ガード関数」のサンプルコードで `declare const input: number | string;` を使用していました。`declare` は本書の後半で解説される構文であり、初心者がこのページを読んだ時点では未学習のため、コード例の意図が理解しづらい状態でした。
## Solution
`declare` を使わず、関数引数として `input: number | string` を受け取る形式に変更しました。
```ts
// Before
declare const input: number | string;
if (isString(input)) { ... }
// After
function example(input: number | string) {
if (isString(input)) { ... }
}
```
Value
読者が declare を学習していなくてもコード例を理解でき、コピペして動作確認もできるようになります。
Close #1068
#### 例3: 開発環境改善（執筆者向け）
```markdown
## 対象者
- [x] ✍️ 執筆者
## Problem
- 依存関係のインストール（Yarn）に時間がかかっていました
- 環境構築手順が複雑で、新規コントリビューターが参加しにくい状態でした
- CIワークフローが複数に分散しており、メンテナンスしづらい状態でした
## Solution
開発環境を刷新しました。
- YarnからBunへ移行（インストール高速化）
- Devbox導入（環境構築の簡素化）
- GitHub Actionsを1つのワークフローに統合
## Value
- 執筆者の開発体験が向上します（高速なビルド、簡単な環境構築）
- 新規コントリビューターが参加しやすくなります
---
Close #1047
例4: バグ修正（読者向け）
## 対象者
- [x] 📖 読者
## Problem
「Prettierの自動整形を無効にする」セクションで、`// prettier-ignore` コメントの使い方を説明していますが、肝心の `// prettier-ignore` がブラウザ上で表示されていませんでした。これは `@typescript/twoslash` パッケージがこのコメントを自動削除する仕様によるものです。
## Solution
- コードブロックから `twoslash` を削除しました
- Prettierによる自動整形を防ぐためHTMLコメントを追加しました
## Value
読者が `// prettier-ignore` の正しい書き方を確認できるようになります。
---
Close #1062
6. 注意事項
6.1. チケット駆動を忘れずに
このプロジェクトはチケット駆動が原則です。PRを作成する前に：
- Issueを作成する
- Issueで話し合う
- 着手の合意を得る
- PRを作成する
唐突なPRはマージされずにクローズされる可能性があります。
6.2. 本文は自己完結させる
- Issueを読まなくても理解できるように書く
- Problem/Solution/Valueを明確にする
- 「詳細はIssueを参照」だけで終わらせない
6.3. 対象者を意識する
- 読者向けの変更は読者目線で価値を説明する
- 執筆者向けの変更は執筆者目線で価値を説明する
- 技術的な詳細より「誰にとって何が嬉しいか」を重視する