AIが作った変更の履歴を残す:コミット・PR・メモに何を書くかの記録ルール

まず決める:何を、どこに残すか

履歴を読む場面は、不具合の原因をたどるときと、レビューや監査で経緯を聞かれるときが中心です。その場面で答えが必要になる項目を、置き場所別に整理します。

• 変更の要点と理由、コミット：◎、PR説明：○、メモ(docsなど)：
• 使ったAIツール名、コミット：◎(1行)、PR説明：○、メモ(docsなど)：
• 依頼の要約(目的・制約)、コミット：△(1行)、PR説明：◎、メモ(docsなど)：
• 人が確認した内容(テスト、目視)、コミット：、PR説明：◎、メモ(docsなど)：
• AIの提案を採用しなかった判断、コミット：、PR説明：○、メモ(docsなど)：◎(長い場合)
• プロンプト全文・長い対話、コミット：×、PR説明：×、メモ(docsなど)：△(必要時のみ)
• 秘密情報・個人情報・認証情報、コミット：×、PR説明：×、メモ(docsなど)：×

◎は必ず、○は書けるときに、△は条件付き、×は書かない、という意味です。プロンプトに社内の固有名やキーが混じることは珍しくないため、全文保存はルールにしないほうが安全です。残す場合も、機密を説明用の値に置き換えてからにします。

ツールが自動で付ける記録を把握する

自分で書く前に、使っているツールがすでに何を残しているかを確認してください。

• Claude Code: コミットとPR説明に付く帰属表示は、設定の attribution(commit と pr のキー)で変更または非表示にできます。旧キー includeCoAuthoredBy は非推奨で、attribution を使うよう案内されています。設定ファイルの階層は設定ファイルの解説、各キーは設定リファレンスにあります。既定の文言は、私が確認した範囲では記載を読み取れませんでした。実際のコミットで確かめてください。
• Cursor: Cloud Agentのコミットは、依頼した人ではなくエージェント名義で作られると公式ヘルプにあります。同ページは、Co-authored-by トレーラーはすべてのエージェントのコミットに付くわけではないとも述べています。つまり、author欄やトレーラーの有無だけでAI関与の有無を判定する運用は危険です。

チームで決めておきたいのは、自動の表示を残すか消すかです。消す設定を許すなら、その分は手書きの記録で補う必要があります。逆に自動表示を残すなら、手書きは「何を頼んだか」と「何を確認したか」に集中できます。

コミット文のテンプレート

コミットは、後から git log や git blame で見る人のために、短く固定の形にします。

<種別>: <変更の要点を1行で>

理由: <なぜ必要だったか。チケット番号があれば併記>
AI: <ツール名>(<モデル名または「不明」>)/ 関与: <下書き|実装|テスト生成|レビューのみ>
確認: <実行したテストや目視確認。未実施なら「未確認」>

ポイントは3つです。

1. 「関与」を区分で書く。 下書き、実装、テスト生成、レビューのみ、の4択程度に絞ると、後で検索しやすくなります。
2. 「確認」は未実施でも空欄にしない。 「未確認」と書いてあれば、後の人は注意して読めます。
3. モデル名は分かる範囲で。 画面に出ていない場合は「不明」で構いません。推測で書くと記録の信頼性が下がります。

ツール名を機械的に拾いたい場合は、AI: ... のような独自の行をトレーラー風に末尾へ並べる方法が使えます。なお Co-authored-by は、GitHubの説明では Co-authored-by: 名前 <メール> の形で本文末尾に空行を挟んで書き、貢献として数えるにはGitHubアカウントに紐づくメールが必要とされています。AIツールの記録に流用するかは、自組織の運用方針で決めてください。

説明用の例

以下は架空の例で、実際のリポジトリやツールの出力ではありません。

fix: 注文一覧の金額が税抜で表示される問題を修正

理由: 表示用関数が税込計算を通っていなかった(#123)
AI: Claude Code(モデル名不明)/ 関与: 実装
確認: 金額計算の単体テスト3件を手元で実行。画面表示は未確認

PR説明のテンプレート

PR説明は、レビューする人が「どこを重点的に疑えばよいか」を判断する場です。GitHubでは、リポジトリ直下、docs/、.github/ のいずれかに pull_request_template.md を置くと、PR本文に自動で内容が入ります。複数テンプレートも使えますが、テンプレートの作成手順にあるとおり、他の人に効くのはデフォルトブランチにマージされた後です。

## 変更の目的
<1〜2文。チケットへのリンク>

## AIの利用
- ツール/モデル:
- 関与範囲: (下書き / 実装 / テスト生成 / レビューのみ / 不使用)
- 依頼の要約: <例:「既存のAPI形式を変えずに〜を追加。依存追加は禁止」>
- 渡した情報: <ファイル名、仕様書の名称など。機密は書かない>

## 人が確認したこと
- [ ] 差分を最後まで読んだ
- [ ] テストを実行した(コマンド/結果):
- [ ] 画面や挙動を確認した(未実施なら理由):
- [ ] 不要な変更・依存追加がない

## レビューで特に見てほしい点
<AIの提案を採らなかった箇所、自信のない箇所>

## 補足メモ
<長い経緯を置いたファイルへのパス。なければ「なし」>

「渡した情報」の欄は、後から「なぜそう実装したか」を推測するときに役立ちます。ただし書くのは名称までにして、中身の転載はしません。

AIに下書きさせるときの依頼文

コミット文やPR説明の下書きはAIに任せられます。ただしAIが知っているのは差分と会話だけなので、理由と確認結果は人が入力して渡す のが前提です。

次の差分から、コミット文とPR説明の下書きを作ってください。
形式は下のテンプレートに従います。
- 「理由」は私が書いた文をそのまま使い、補完しないでください。
- 「確認」は私が書いた内容だけを記載し、実行していないテストを実行済みと書かないでください。
- 差分から読み取れない点は「不明」と書いてください。

【理由】(ここに自分の言葉で記入)
【実施した確認】(ここに記入。なければ「なし」)
【テンプレート】(上記を貼る)
【差分】(git diff の出力)

出力されたら、人が次の3点を見ます。理由が自分の意図と合っているか、確認欄に実行していない内容が混ざっていないか、差分に含まれない機能の説明が紛れていないか、です。

運用ルールとして決める項目

最後に、チームで一度決めておく項目です。READMEやCONTRIBUTINGに数行で書けば足ります。

1. 自動付与の帰属表示を残すか、消すか(消す場合は手書きで補う)
2. 「関与」の区分(下書き/実装/テスト生成/レビューのみ)
3. プロンプトを保存する条件と、機密を含めない規則
4. 「確認: 未確認」のままマージしてよいか(例:ドキュメントのみの変更は可、など)

このテンプレートは未実行の提案です。導入時は小さなリポジトリで数件試し、書きにくい欄があれば削ってください。欄が多すぎると形だけ埋める運用になり、記録の価値が下がります。