write-commit-for-pr

name	write-commit-for-pr
description	このリポジトリで、PR作成前に変更内容に合ったコミットメッセージや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の関連付けを省略しないでください。

## 対象者

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

## 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を作成する前に：

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

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

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

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

6.3. 対象者を意識する

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