CursorのカスタムスラッシュコマンドでGitHub IssueやPull Requestを品質の高いドキュメントとして自動作成する
リテールアプリ共創部 マッハチームのるおんです。
マッハチームでは小売業界のお客様に向け、新規アプリ開発の立ち上げを専門に行っています。新規開発の立ち上げ時には、短期間で高品質なアプリケーションを開発することが求められます。
これまで、マッハチームのメンバーで「開発速度向上」や「共創」をテーマにしたブログリレーを実施してきました。
そして今回はソフトウェアの"品質"に関する知見を共有するブログの連載を始めました。私からは第2弾として カスタムスラッシュコマンドを使ったIssueやPR、コミットメッセージのドキュメント化 についてご紹介します。
メンバーによる過去投稿も是非読んでみてください！
はじめに
今回のテーマは 「品質」 です。
ソフトウェアにおける品質とは
ソフトウェアにおける品質と言っても、様々な観点があります。西田さんの記事では 稼働率、バグの少なさ、セキュリティ、パフォーマンス といった観点から品質について紹介されていました。
今回は、それとは別の切り口として納品物の中に含まれる 「ドキュメントの品質」 という観点から考えてみたいと思います。
ドキュメントも「品質」の対象
「品質」というと、動くソフトウェアやコードそのものを想像しがちですが、ドキュメントも納品物の一部 になることがあり、それも品質の対象になりうることを忘れてはいけません。
特に受託開発や業務システムの現場では、設計書や仕様書が納品物として求められることがあります。また、引き継ぎや保守運用のフェーズでは、ドキュメントが引き継ぎメンバーのオンボーディング資料としても利用されることがあり、それが運用保守や追加開発の一環として重要な役割を果たします。
つまり、ドキュメントの品質を担保することは、ソフトウェア全体の品質を担保すること につながるのです。
ドキュメントの追従問題
しかし、皆さんの現場ではドキュメントをどのように管理していますか？コードのファイルや関数、APIごとに詳細なドキュメントを書くことを求められる現場もあるかもしれません。しかし、コードの変更に追従してドキュメントを更新し続けるのは非常に難しいですよね。
ドキュメントは書いた瞬間から陳腐化が始まります。コードが変更されてもドキュメントが更新されないまま放置され、いつの間にか「嘘のドキュメント」になってしまう。これは多くの現場で共通する課題ではないでしょうか。
「ソースコード自体がドキュメントになるようにすべき」という意見もあります。これは否定しませんし、必要な観点です。可読性の高いコード、適切な命名、コメントの整備は重要です。
しかし、人間が読み理解できる仕様書やドキュメントは依然として必要 だと考えています。コードだけでは「何をしているか」は伝えられますが、「なぜそうしたのか」「どのような経緯でこの設計になったのか」は伝えにくいですし、納品物としては 非エンジニアでもわかるようなドキュメント が求められることもあります。
一方で、繰り返しになりますが、完全な仕様書やドキュメントを別途作成・維持しようとすると、追従が難しく、陳腐化しやすい こともあり、メンテナンスコストも高くなります。
では、どうすればいいのでしょうか？
GitHub Issue/PRをドキュメントとして機能させる
「なぜこの変更をしたのか」「どのような手順で実装したのか」という情報は、後からコードを読む人にとって非常に重要です。では、どこにその情報を残すべきでしょうか？
私は、最もドキュメントとして機能するのはGitHubのIssueやPR だと考えています。コードと一緒にバージョン管理され、コミットログとして変更の経緯が残り、レビューのコンテキストも含まれる。これ以上のドキュメントはありません。
今回は、CursorおよびClaude Codeの カスタムスラッシュコマンド を使って、コミットメッセージを生成し、PRとIssueをドキュメントとして機能させる 仕組みを構築してみました。
3つのカスタムスラッシュコマンド
カスタムスラッシュコマンドとは
Claude CodeやCusor使える機能で、再利用可能なプロンプトを作成し、チームで共有できるようになりました。特定のディレクトリ（.cursor/commands/ や .claude/commands/ など）にMarkdownファイルを配置するだけで、Agentの入力フィールドで / を入力してコマンドを実行できます。
今回は、このカスタムスラッシュコマンドを使って、コミットとPR作成、Issue更新のワークフローを標準化してみました。
今回作成したカスタムコマンド
今回は以下の3つのカスタムスラッシュコマンドを作成しました。
| 実現できること | 効果 |
|---|---|
/structured-commits |
作業内容を回想し、意味のある手順単位でコミットを作成する |
/create-pull-request |
自動でPRを作成し、やったことに対してコミット履歴を紐づける |
/update-issue |
実装内容との乖離を検出し詳細化し、既存のIssueを更新する |
特に重要なのは、AIエージェントが「これまでの作業を回想する」というプロセスを踏むことで、単なる差分の羅列ではなく、意味のあるコミット単位 で変更を整理してくれる点です。
これらの3つのカスタムコマンドを 同一セッション内 で使うことで、作業単位でのコミット作成 → 手順書化されたPR作成 → より正確なIssue内容に更新 という流れで、整備されたドキュメントとしてのIssue・PR を作成することができます。。
/structured-commits → /create-pull-request → /update-issue
(コミット作成) (PR作成) (Issue更新)
今回はこれをCursorを使って試してみました。
また、前提としてGitHub上のIssueやPRの操作にはghコマンド（GitHub CLI）が必要です。また、これら3つのコマンドは、同一セッション内で実行することを想定しています。
1. /structured-commits - 構造化されたコミット作成
# Structured Commits
これまでの作業内容を回想し、コミットメッセージ群自体がPRを見た時の変更履歴となるようにコミットを作成します。
## 実行手順
### Phase 1: 作業の回想
1. **これまでのやり取りを回想**: 会話の中であなた（AI）が行った変更を思い出す
2. 変更した内容をリストアップ
### Phase 2: 差分の確認
1. `git diff` と `git status` を実行して、実際の変更内容を確認
2. **回想と実際の差分を照合**: 抜け漏れがないか確認
- **あなたが行っていない変更が含まれている場合は「人間による変更」として認識**
3. **変更のグループ化**: 関連する変更をコミット単位でまとめる
### Phase 3: 作業手順の整理
1. **手順をリスト化**: Phase 1-2で整理した内容を、コミット予定の順番でリストとして出力
2. ユーザーに確認を促す（必要に応じて調整）
### Phase 4: コミットの作成
1. **グループ単位でコミット**: 関連する変更をまとめてコミット
2. **ステージング**: 関連するファイルのみを `git add` でステージング
3. **コミットメッセージ作成**: `.github/.COMMIT_TEMPLATE` に従って作成
- **1行に収まるようにする**
- Prefix: `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `test:`, `chore:`
- 形式: `<Prefix>: 変更内容の要約を現在形で記載`
4. `git commit -m "<message>"` でコミット作成
5. すべてのグループについて、2-4を繰り返す
### Phase 5: 確認
1. `git log --oneline -n <コミット数>` で作成したコミットを確認
2. コミットメッセージ群を見て、作業の流れが理解できるか確認
## 重要な制約
- エラーが発生しているファイルはcommitしない
- リモートへのpushは**行わない**
- commitメッセージにAIの署名は**追加しない**
- **コミットメッセージ群がPRの手順書として読めることを意識する**
- コミットメッセージに（👤人間による変更）という文言は不要です
- ghコマンドが使用できない場合は、`gh`コマンドの有無の確認と`gh auth login`コマンドの実行を促す
## 出力例
---
コミット作成完了:
1. feat: 会員証発行APIのエンドポイントを追加
2. feat: 会員証発行のビジネスロジックを実装
3. test: 会員証発行APIのユニットテストを追加
4. docs: 会員証発行APIのREADMEを更新
---
.github/.COMMIT_TEMPLATE
すでにアプリケーションのソース内に、コミットテンプレートを設定していたので、それを参照させています。
# =============== Commit Messages ===============
# ==================== Format ====================
# <Prefix>: 変更内容の要約を現在形で記載する
# ==================== Prefix ====================
# Semantic Commit Messagesを採用(https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716)
# feat: ユーザーのための新機能追加や変更
# fix: バグ修正
# docs: ドキュメンテーションの変更
# style: フォーマット、Lintエラー修正
# refactor: リファクタリング
# test: 足りないテストの追加、テストのリファクタリング
# chore: ビルドプロセスの変更など機能開発以外の変更
このコマンドのポイントは、「作業の回想」 というフェーズを設けていることです。AIエージェントがこれまでの会話で行った変更を思い出すことで、単なるファイル差分ではなく、意味のある単位 でコミットをグループ化できます。
実際に、このコマンドを使って見ると以下のような挙動をします。これは、AWS CDKでVPC Lambdaを構築する際にを作成したときのものです。
このように、作業内容の回想とdiffの確認、複数のコミットを実行してくれます。
2. /create-pull-request - PR作成
次に、これらのコミットメッセージを元にPRを作成します。
# Create Pull Request
今回のやったことの回想からPRの内容を作成。以下のテンプレートに従って作成してください。
## PRテンプレート
---
## 課題へのリンク
<!-- * 課題へのリンクは？ -->
## やったこと
<!-- * このプルリクで何をしたのか？ -->
## できるようになること
<!-- * 何ができるようになるのか？（あれば。無いなら「無し」でOK） -->
## できなくなること
<!-- * 何ができなくなるのか？（あれば。無いなら「無し」でOK） -->
## 動作確認
<!-- * どのような動作確認を行ったのか？ 結果はどうか？ -->
## その他
<!-- * レビュワーへの参考情報（実装上の懸念点や注意点などあれば記載） -->
---
## 実行手順
### Phase 1: 情報収集
1. ブランチ名やコミットメッセージから関連Issue番号を特定
2. 今回のやったことの回想からPRの内容を作成。何も情報がない場合は、commitのログを元に作成。
3. テンプレートに従って作成。
### Phase 2: PR本文の作成
「やったこと」セクションには、**各項目にコミットハッシュを付けて記載**する。
#### 「やったこと」の記載例
---
## やったこと
1. 設定ファイルの追加 abc1234
2. DBスキーマの変更 def5678
3. 会員証発行APIのエンドポイント追加 ghi9012
4. ユニットテスト追加 jkl3456
---
※ GitHubではコミットハッシュが自動的にリンクになる
### Phase 3: PR作成
1. 未プッシュのコミットがある場合、**ユーザーにプッシュしてよいか確認する**
2. 確認後、`git push -u origin {branch-name}` でリモートにプッシュ
3. `gh pr create` でPRを作成
4. 作成したPRのURLを表示
## 重要な制約
- PRの本文は**日本語**で作成
- AIの署名は**追加しない**
- ghコマンドが使用できない場合は、`gh`コマンドの有無の確認と`gh auth login`コマンドの実行を促す
- 想定外の作業が発生したり、エラーが見つかった場合はユーザーに相談
このコマンドのポイントは、コミットハッシュを「やったこと」に紐付ける ことです。GitHubではコミットハッシュが自動的にリンクになるため、PRを見た人がすぐに具体的な変更箇所にアクセスできます。
例えば、以下は先ほどの変更内容を元に、このカスタムスラッシュコマンドを使って作成したPRです。
「やったこと」の内容にコミットハッシュが紐づいており、手順とそのコミット内容がすぐに参照できるようになっています。
3. /update-issue - Issue更新
# Update Issue
作業内容（コミット・PR作成または、単純にローカルの変更のみ）後に、Issueの内容と実際の実装内容を比較し、乖離がある場合にIssueを更新してより詳細なドキュメントにします。
**対象Issue番号**: `$ARGUMENTS`
## 実行手順
### Phase 1: 情報収集
1. **対象Issue番号の確認**
- `$ARGUMENTS` でIssue番号が指定されている場合はそれを使用
- 指定がない場合は、ブランチ名（`feature/#123-xxx` 形式）から取得、または `gh issue list` で一覧を表示してユーザーに確認
2. **Issueの現在の内容を確認**: `gh issue view [issue番号]`
3. **PRの内容を確認**: `gh pr view` で作成したPRの内容を確認
4. **PRがない場合は、作業を振り返り、必要に応じてコミットログやdiffを確認**
### Phase 2: 乖離の分析
Issueの記載内容と実際の実装内容を比較し、乖離がある場合にIssueを更新してより詳細なドキュメントにします。
### Phase 3: Issue更新案の作成
乖離がある場合、以下の観点でIssueを詳細化する更新案を作成：
- **実装した内容の詳細**: Issueには記載されていない内容や、具体的な実装内容の詳細。
- **関連PR**: 作成したPRへのリンク
### Phase 4: ユーザー確認と更新実行
1. **更新案をユーザーに提示**: 変更前後の差分がわかるように説明
2. **承認を得てから更新**: `gh issue edit [issue番号] --body "更新後の本文"`
3. **更新完了の確認**: `gh issue view [issue番号]` で反映を確認
## 重要な制約
- Issueの内容は**日本語**で記載
- AIの署名は**追加しない**
- **既存の内容を大幅に変更する場合は、必ずユーザーに確認を取ってから実行**
- ghコマンドが使用できない場合は、`gh`コマンドの有無の確認と`gh auth login`コマンドの実行を促す
- 想定外の作業が発生したり、エラーが見つかった場合はユーザーに相談
このコマンドのポイントは、Issueと実装内容の乖離を検出し、Issueをより詳細なドキュメントに更新する ことです。開発を進める中で、当初のIssueに書いていなかった詳細が明らかになることはよくあります。それを自動的にIssueに反映することで、Issueが「生きたドキュメント」として機能し続けます。
なぜこのアプローチが品質向上につながるのか
1. 適切な単位でのコミットメッセージ作成が可能
AIエージェントがエンジニアとのやりとりや作業内容を「回想」することで、意味のある変更単位 でコミットをグループ化できます。単純に git diff の結果をそのままコミットするのではなく、「この変更はAPI追加」「この変更はバリデーション」「この変更はテスト」といった形で、論理的なまとまりでコミットが作成されます。
後からこの変更を理解しようとする人は、コミットログを上から順に読むだけで、実装の流れを追体験できます。
2. PRが「手順書」になる
PRの「やったこと」セクションにコミットハッシュが紐づいていることで、PRが実装の手順書として機能します。
- 「何をどの順番で実装したか」が一目でわかる
- コミットハッシュをクリックすれば、具体的な変更内容にすぐアクセスできる
- レビュワーが変更の意図を理解しやすくなる
3. Issueが「正確なドキュメント」になる
/update-issue によって、実装後のIssueには以下の情報が記録されます：
- 実装した内容の詳細：当初のIssueには書かれていなかった具体的な実装内容
- 関連PRへのリンク：どのPRでこのIssueが実装されたか、そしてそこではどのような手順で実装されたか（コミット内容から判断可能）
これにより、後から「この機能の仕様は？」「この機能はどう実装されたのか？」という質問に対して、Issueを見て辿ることができるようになります。
おわりに
ソフトウェアにおける「品質」は多面的な概念ですが、今回は ドキュメントの品質 という観点から、IssueとPR、コミットメッセージ等を品質の高いドキュメントとして機能させるアプローチを紹介しました。
特に重要なのは以下の点です：
- コミットが適切な単位で作成される：AIの回想により意味のあるまとまりでグループ化
- PRが手順書になる：コミットハッシュの紐付けで実装の流れが追える
- Issueが正確なドキュメントになる：実装内容との乖離を検出して自動更新
コードと一緒にバージョン管理され、変更の経緯が自然と記録される。これこそが、追従コストを最小限に抑えた 「生きたドキュメント」 だと考えています。
LLMとAIエージェントが進化する中で、AIの精度を上げるにはいかにコンテキストやデータを整理するか はこれまで以上に重要になってくると思います。
整理されたコミットメッセージ、構造化されたPR、正確なIssue。これらは人間が読むためだけでなく、AIエージェントが正確に文脈を理解するため にも役立ちます。
今回紹介したアプローチは、人間とAIの両方にとって価値のある「整理されたドキュメント」を自然と生成する仕組みだと言えるかもしれません。
正直なところ、今回紹介した方法はまだまだ模索中です。もっといいやり方、もっと効率的なカスタムコマンドの設計があるかもしれません。
「うちではこうしている」「こういう工夫をしている」といったアイデアがあれば、ぜひ教えていただけると嬉しいです。
カスタムスラッシュコマンドは、チームの開発プラクティスを標準化し、品質を向上させる強力なツールです。ぜひ皆さんのチームでも試してみてください。
以上、どなたかの参考になれば幸いです。
お知らせ
クラスメソッドのリテールアプリ共創部 マッハチームではエンジニアを募集しております。
マッハチームではClaude CodeやCursor等のAIエージェントを導入してプロジェクト開発を高速に実現してます。
AI駆動開発がしたい人、モダン技術を用いてフロントエンドもサーバーサイドもインフラ周りもTypeScriptでフルスタックに開発したい人、プリセール・顧客折衝も要件定義も開発も全部やりたい人、AI時代に価値提供し続けられるエンジニアになりたい人は是非以下のブログを見てご応募いただけると幸いです。
参考
