From 68cb7eb36d1b6546a3b7a3a10b0a6a79531b8045 Mon Sep 17 00:00:00 2001
From: suin <suinyeze@gmail.com>
Date: Fri, 15 May 2026 20:49:01 +0900
Subject: [PATCH] =?UTF-8?q?Claude/Codex=E5=90=91=E3=81=91=E3=81=AEPR?=
 =?UTF-8?q?=E3=83=BB=E3=82=B3=E3=83=9F=E3=83=83=E3=83=88=E6=96=87=E9=9D=A2?=
 =?UTF-8?q?=E4=BD=9C=E6=88=90=E3=82=B9=E3=82=AD=E3=83=AB=E3=82=92=E8=BF=BD?=
 =?UTF-8?q?=E5=8A=A0=E3=81=97=E3=81=BE=E3=81=97=E3=81=9F=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 対象者

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

## Problem

PR作成前にコミットメッセージとPR本文を提案する手順が、Claude/Codexから参照できるスキルとして用意されていませんでした。また、コミット本文だけでは変更の意図や価値が分かりづらくなる可能性がありました。

## Solution

Claude/Codex向けに `write-commit-for-pr` スキルを追加しました。

- `.claude/skills/write-commit-for-pr/SKILL.md`
- `.codex/skills/write-commit-for-pr/SKILL.md`

コミット本文とPR本文の両方で、対象者、Problem、Solution、Value、Issueの関連付けを書くように明記しました。

## Value

PR本文だけでなく、コミット履歴からも変更の背景と価値を確認できるようになります。

---

Close #1117
---
 .claude/skills/write-commit-for-pr/SKILL.md | 297 ++++++++++++++++++++
 .codex/skills/write-commit-for-pr/SKILL.md  | 297 ++++++++++++++++++++
 2 files changed, 594 insertions(+)
 create mode 100644 .claude/skills/write-commit-for-pr/SKILL.md
 create mode 100644 .codex/skills/write-commit-for-pr/SKILL.md

diff --git a/.claude/skills/write-commit-for-pr/SKILL.md b/.claude/skills/write-commit-for-pr/SKILL.md
new file mode 100644
index 00000000..f4c3bcf9
--- /dev/null
+++ b/.claude/skills/write-commit-for-pr/SKILL.md
@@ -0,0 +1,297 @@
+---
+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の関連付けを省略しないでください。
+
+```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. 対象者を意識する
+
+- 読者向けの変更は読者目線で価値を説明する
+- 執筆者向けの変更は執筆者目線で価値を説明する
+- 技術的な詳細より「誰にとって何が嬉しいか」を重視する
diff --git a/.codex/skills/write-commit-for-pr/SKILL.md b/.codex/skills/write-commit-for-pr/SKILL.md
new file mode 100644
index 00000000..f4c3bcf9
--- /dev/null
+++ b/.codex/skills/write-commit-for-pr/SKILL.md
@@ -0,0 +1,297 @@
+---
+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の関連付けを省略しないでください。
+
+```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. 対象者を意識する
+
+- 読者向けの変更は読者目線で価値を説明する
+- 執筆者向けの変更は執筆者目線で価値を説明する
+- 技術的な詳細より「誰にとって何が嬉しいか」を重視する