Commit and Draft PR

進捗チェックリスト

作業開始時にこれをコピーして進捗を管理する:

• 1. 変更とブランチを確認（main・detached HEAD・既にマージ済みのブランチなら feature ブランチを作成、worktree の仮ブランチ名ならリネーム）
• 2. テスト/リンタ/型チェックの状態を確認（当セッションで検証済みなら再実行せずスキップ、未検証なら実行して全て通す）
• 3. 必要な変更のみステージング
• 4. 規約に沿ったメッセージでコミット
• 5. push
• 6. PR 反映（下記「PR 反映の分岐」に従う。ユーザーが「push のみ／PR 不要」と指示した場合はスキップ）

事前確認

• git status と git diff で変更を把握する。diff は中身まで読み、意図した変更と一致するか確かめる（ツールの副作用でファイルが空洞化しても git status では M としか出ない）
• git log --oneline -5 で直近の履歴を把握する
• git branch で現在ブランチを確認する
• main・detached HEAD・既にマージ済みのブランチ上の場合は feature ブランチを作成する（マージ済みブランチ上に変更がある場合は git stash -u → 最新 main を fetch → 新ブランチ作成 → git stash pop で移す）
• ブランチ名が worktree の仮名のまま（worktree ディレクトリ名と同名、または bright-running-fox のような自動生成名）の場合は、対象リポジトリの AGENTS.md と既存ブランチの命名規約を確認し、作業内容を表す名前へ git branch -m <名前> でリネームしてから進める。prefix の有無は対象リポジトリの規約を優先する
• マージやコンフリクト解消の途中なら、git status に未解決（UU）が残っていないことを確認する
• 複数セッションや並行実装の形跡がある場合は、同じ変更領域・目的の open PR が別ブランチに無いか確認する。ブランチが予期せず切り替わっていた場合は git reflog で経緯を確認し、無関係な変更を操作する前にユーザーへ判断を求める
• 変更が無い（diff が空）場合は中断して報告する

検証

• 当セッションで実装→検証を済ませた直後なら再実行しない
• 未検証、または文脈が不明な場合は、対応するテスト・リンタ・型チェックを実行して全て通す
• 失敗したら根本原因を修正し、再実行する（抑制やスキップはしない）
• コマンドが不明な場合は package.json / Makefile / pyproject.toml 等の設定ファイルを確認する

ステージング

• 今回の変更の意図に沿うファイルだけ git add する
• 次は原則除外する: 一時/デバッグ用ファイル、ローカル設定、秘密情報（.env 等）、生成物・ビルド成果物
• add 後に git status --short と git diff --cached で、対象ファイルと内容を確認する。秘密情報・PII・生成物が含まれないことも確認する（git status は --cached を取らない）
• 変更を複数 PR へ分割する場合は、各 PR が単独で成立し、未収録ファイルへのリンクや参照を残していないことを確認する
• add したはずのファイルが staged に現れない場合は git check-ignore -v <パス> で除外理由を確認する。ai-agents/skills/*/observations/ のような意図的な除外は force-add せず、除外した旨をコミット本文に書く

コミット

• 形式は <type>: <summary>
• タイトルは命令形・72文字以内
• 本文には次を含める:
  • 変更内容（何を変更したか）
  • 変更理由（なぜ変更したか）
  • 技術的な詳細（どのように変更したか）
  • 注意事項（影響範囲、レビュー時の確認ポイント）
• type 一覧:
  • feat: 新機能
  • fix: バグ修正
  • refactor: 挙動を変えない改善
  • docs: ドキュメント
  • test: テスト
  • chore: 雑務（CI・設定など）
• マージコミットも <type>: <summary> に揃え、既定の Merge branch ... は使わない。type は取り込んだ内容ではなくマージの目的で選ぶ（コンフリクト解消なら chore:）
• コミット前に本文を読み返し、下書きの断片や diff と矛盾する記述が残っていないか確認する

コミットメッセージ例

変更内容 → メッセージの対で、実際の変更に合わせて調整する。

例1 変更内容: トークン認証で期限切れトークンが弾かれていなかったバグを修正 メッセージ:

fix: 期限切れトークンを拒否するよう認証を修正

検証時に有効期限を確認していなかったため、失効済みトークンでも
認証が通っていた。検証ロジックに exp チェックを追加した。

例2 変更内容: PDF抽出ライブラリを pdfplumber に切り替え メッセージ:

feat: PDFテキスト抽出を pdfplumber に切り替え

表組みを含むPDFで抽出精度が低かったため。pages 単位の抽出に変更し、
既存の呼び出し側インターフェースは維持した。

プッシュ

• push 前に対象ブランチを再確認する
• git push -u origin <ブランチ名>
• リモートに同名ブランチがある場合は --force-with-lease を検討する

ドラフトPR作成

PR 反映の分岐

push 後、まず対象ブランチの open PR を確認する: gh pr list --head <ブランチ名> --state open

• ユーザーが「push のみ／PR 不要」と指示: このステップをスキップする（引数を最優先）
• 既存の open PR がある: 新規作成せず push 追従で反映する（重複作成を回避）。あわせて次を確認する:
  • PR 本文が現在の diff と食い違っていないか gh pr view <番号> で確認する。記述した実装を削除した・前提が実測で覆った・設計方針が変わった場合は gh pr edit <番号> --body で本文を直す（コンフリクト解消や方針変更を伴う追従 push では本文が失効しているのが普通）
  • そのブランチを base にした子 PR が無いか gh pr list --base <ブランチ名> --state open で確認する。あれば下流へ順にマージして伝播させ、それぞれ push する
• open PR が無い: 以下の手順で新規ドラフト PR を作成する
• 複数リポジトリを対象にする場合は、リポジトリごとにチェックリスト全体を独立して実行する。関連 PR が揃ったら、各 PR 本文に相互リンクとマージ順序・前提条件を記載する

新規ドラフト PR 作成

• gh pr create --draft --base main --head <ブランチ名> --title "<タイトル>" --body "<本文>" --assignee hodanov

• PR作成時は必ず --assignee hodanov を付けて自分をassignする

• タイトルはプリフィックスは英語、内容は日本語で記述する: 例 fix: トークン認証のバグを修正

• 本文は以下のテンプレートに従い、実際の変更内容に合わせて記述する（該当しない項目は省略可）:

  ## 実装経緯の説明
  
  <変更の背景と目的を簡潔に説明>
  
  ## チケット
  
  <チケットURL（無ければ省略）>
  
  ## 補足
  
  ### 主な変更内容
  
  - <変更点1: 具体的な説明>
  - <変更点2: 具体的な説明>
  
  ### 確認事項
  
  デプロイ後や動作確認時のチェックポイント
  
  - <確認項目1>
  - <確認項目2>
  

• ## 補足 はレビューを始めるのに必要な最小限に絞る。テンプレートに無い見出し（### 技術的な詳細、### 検証 等）を追加しない

• ### 主な変更内容 は最大 3 項目。変更が多い場合は特に重要なものだけを選ぶ。1 項目 1〜2 行に収め、ネストした子箇条書きは使わない

• ### 確認事項 はこれから確認することだけを書く。lint / test が通った等の実施済みの検証結果は書かない（CI とコミットで分かる）

• 実装の詳細・設計の背景はコミット本文（「コミット」節）とプラン文書に書き、PR 本文では繰り返さない

• ## 補足 全体で 20 行程度を上限の目安とする

注意

• gh が未ログインの場合は gh auth status を確認し、必要ならログインする
• 既存のPRテンプレートがある場合は適宜整形する