# Write Commit For Pr

> このリポジトリで、PR作成前に変更内容に合ったコミットメッセージやPR文面を提案するときに使います。

- Skill: `yytypescript/write-commit-for-pr` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yytypescript/write-commit-for-pr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yytypescript/write-commit-for-pr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yytypescript (https://skillmd.com/u/yytypescript)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yytypescript/write-commit-for-pr

---


# 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の関連付けを省略しないでください。

```markdown
## 対象者

- [ ] 📖 読者
- [ ] ✍️ 執筆者

## Problem

<!-- 何が問題だったか / 何が不足していたか / どんな課題があったか -->

## Solution

<!-- その問題をどう解決したか -->

## Value

<!-- この変更によって、対象者にどんなメリットがあるか -->

---

Close #xxx
```

### 5.2. 各セクションの書き方

#### 対象者

該当するものにチェックを入れます。複数該当する場合は複数チェックしてOKです。

#### Problem（問題）

以下の観点で記述します：

- 何が問題だったか？
- 何が不足していたか？
- どんな課題があったか？
- 読者/執筆者がどんな困りごとを抱えていたか？

**書き方のコツ**:

- **ですます調**で書く
- 「〜でした」「〜がありませんでした」「〜できませんでした」という過去形で書く
- 具体的な状況を説明する
- 可能であれば影響を受ける人の視点で書く

#### Solution（解決策）

具体的に何をしたかを記述します：

- **ですます調**で書く
- 何を追加/変更/削除したか？
- どのファイルを変更したか？（大きな変更の場合）
- Before/Afterがあると分かりやすい

#### Value（価値）

この変更によって対象者が得られるメリットを記述します：

- **ですます調**で書く
- 「〜できるようになります」「〜が分かるようになります」という形式
- 対象者の視点で書く

#### Issueの関連付け

必ず `Close #xxx` または `Closes #xxx` でIssueを関連付けます。
これによりPRマージ時にIssueが自動でクローズされます。

### 5.3. 具体例

#### 例1: コンテンツ追加（読者向け）

```markdown
## 対象者

- [x] 📖 読者

## Problem

配列のスプレッド構文は紹介されていましたが、オブジェクトのスプレッド構文が紹介されていませんでした。実務ではオブジェクトのスプレッド構文も頻繁に使用されるため、読者が網羅的に学べない状態でした。

## Solution

「オブジェクトのスプレッド構文」ページを新規追加しました。

- オブジェクトの作成・コピー・マージ
- 浅いコピーの注意点
- 分割代入と残余パターン
- 配列のスプレッド構文ページとの相互リンク

## Value

読者がオブジェクトのコピーやマージの実践的なパターンを体系的に学べるようになります。

---

Close #828
```

#### 例2: 分かりやすさ改善（読者向け）

````markdown
## 対象者

- [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: バグ修正（読者向け）

```markdown
## 対象者

- [x] 📖 読者

## Problem

「Prettierの自動整形を無効にする」セクションで、`// prettier-ignore` コメントの使い方を説明していますが、肝心の `// prettier-ignore` がブラウザ上で表示されていませんでした。これは `@typescript/twoslash` パッケージがこのコメントを自動削除する仕様によるものです。

## Solution

- コードブロックから `twoslash` を削除しました
- Prettierによる自動整形を防ぐためHTMLコメントを追加しました

## Value

読者が `// prettier-ignore` の正しい書き方を確認できるようになります。

---

Close #1062
```

## 6. 注意事項

### 6.1. チケット駆動を忘れずに

このプロジェクトは**チケット駆動**が原則です。PRを作成する前に：

1. Issueを作成する
2. Issueで話し合う
3. 着手の合意を得る
4. PRを作成する

唐突なPRはマージされずにクローズされる可能性があります。

### 6.2. 本文は自己完結させる

- Issueを読まなくても理解できるように書く
- Problem/Solution/Valueを明確にする
- 「詳細はIssueを参照」だけで終わらせない

### 6.3. 対象者を意識する

- 読者向けの変更は読者目線で価値を説明する
- 執筆者向けの変更は執筆者目線で価値を説明する
- 技術的な詳細より「誰にとって何が嬉しいか」を重視する