Update Coding Guidelines

Update Coding Guidelines

直近N日（デフォルト1日）のPRレビューコメントを収集し、繰り返し指摘されているかつ対応すべきと判断できる観点をリポジトリルートのCODING_GUIDELINES.mdに集約するスキルです。Instructionsに従って、収集→クラスタリング→ガイドライン更新→PR作成まで一貫して実行してください。

このスキルがやること・やらないこと

やること:

• 直近N日に更新されたPRのレビューコメント・会話コメントを横断収集（解決済みも含む）
• 同種の指摘を意味的にクラスタリングし、2回以上出現するものを抽出
• 「実際に修正すべき」と判断できる観点だけをルール化対象とする
• リポジトリルートCODING_GUIDELINES.mdへの追記・既存ルールとの統合・圧縮
• commit-push skillで変更をコミット・push（必要なら専用feature branchへ切替）
• create-pr skillでPRを作成し、PR URLを返却
• 編集差分のサマリ報告

絶対にやらないこと:

• レビューコメントへの返信・Resolve・既存PRへの編集（読み取りのみ）
• CODING_GUIDELINES.md以外のソースコードへの修正
• 単発（2回未満）の指摘のルール化（ノイズ防止）
• スタイル好み・命名の主観・スコープ外提案など「対応不要寄り」の項目のルール化
• 既存ルールと意味重複する項目の別ルールとしての追加（必ず統合・圧縮する）
• デフォルトブランチ上での直接コミット（必ずfeature branchに切り替えてからcommit-pushを呼ぶ）

Instructions

実行モードの制約: サブエージェント・サブスキル・Bashをバックグラウンド実行しないこと

本スキルは commit-push → create-pr の順に同期完了を保証しなければならない（push 未完了のまま PR 作成に進むとリモート未反映を前提に走って破綻する）。本スキル内部で呼び出す Agent / Skill / Bash を絶対にバックグラウンド実行しないこと。

• Agent ツールは既定が run_in_background: true（バックグラウンド）。呼び出しごとに 必ず run_in_background: false を明示指定 し、フォアグラウンドで同期的に結果を受け取ってから次の処理に進む
• Skill に run_in_background: true を指定しない（既定は同期）。特に commit-push / create-pr は返却完了を確認してから次のステップに進む
• Bash にも run_in_background: true を指定しない。gh や git は同期完了を stdout で確認してから次のステップへ進む

!pwd

フェーズ0: 事前チェック・引数パース

• カレントディレクトリがgitリポジトリのルートであることを確認する（git rev-parse --show-toplevelの出力と一致するか）。一致しない場合は呼び出し元に「リポジトリルートで実行してください」と返して終了する
• 既存のCODING_GUIDELINES.mdがあれば全文をReadで読み込み、現在のルール構成・項目数・トーンを把握する

引数パース

$ARGUMENTSを空白区切りで最大2トークンに分解する。

• 1番目: 期間（日数）。省略時または非数値の場合は1
• 2番目: 関連Issue番号（任意）。#プレフィックスは除去して数値部分のみ保持

例:

• /update-coding-guidelines → 日数=1, Issue番号=なし
• /update-coding-guidelines 7 → 日数=7, Issue番号=なし
• /update-coding-guidelines 7 123 → 日数=7, Issue番号=123
• /update-coding-guidelines 7 #123 → 日数=7, Issue番号=123

Issue番号はフェーズ5でcreate-prに渡す。指定なしの場合はPR本文のCloses #N行を省略する。

完了条件: リポジトリルートにいることが確認でき、既存CODING_GUIDELINES.mdがあれば内容を把握済みで、日数と任意Issue番号が確定していること。

フェーズ1: レビューコメント収集

以下のスクリプトで、直近N日に更新されたPRのレビューコメント・会話コメントを一括取得する。

bash ${CLAUDE_SKILL_DIR}/scripts/fetch-recent-review-comments.sh <フェーズ0で確定した日数>

第1引数には日数のみを渡す（$ARGUMENTSをそのまま渡すとIssue番号トークンが余計な引数として渡ってしまう）。引数なしの場合はスクリプト側のDAYS="${1:-1}"でデフォルト1日が使われる。

返却されるJSONの構造:

• period_since: 収集起点のISO8601タイムスタンプ
• repo: owner/name
• pr_count: 対象PR数
• prs[]:
  • pr_number / pr_title / pr_url / pr_author
  • review_comments[]: コード行に紐づくレビューコメント（path / line / is_resolved / is_outdated / author / body / url / created_at）
  • conversation_comments[]: PRのConversationタブに投稿されたコメント（author / body / url / created_at）

pr_countが0の場合は「対象期間に新規レビューコメントなし」と報告して終了する（CODING_GUIDELINES.mdは更新しない）。

ノイズ除外

スクリプト側でisMinimized: trueの会話コメントは除外済みだが、以下もルール化対象から外すこと（クラスタリング対象には含めるが、抽出条件の判断時に除外する）:

• PR作成者自身のコメント（セルフコメント・進捗報告）
• ボット起動コマンド（/gemini review等）やCIの自動投稿
• 「LGTM」「マージしてOK」等の承認のみのコメント
• 雑談・ねぎらい・絵文字のみのコメント

完了条件: スクリプトの実行結果が手元にあり、ルール化判断の対象となる「人間レビュアーからの修正要求コメント」が抽出できていること。

フェーズ2: クラスタリングと対応要否判定

収集したコメント群を意味ベースでクラスタリングする。字面が違っても同種の指摘は同じクラスタにまとめる:

• 「nullチェックが漏れている」「undefinedの可能性がある」「optional chainingを使うべき」 → 「null/undefined安全性」クラスタ
• 「テストが足りない」「エッジケースが未検証」「異常系のテストを追加して」 → 「テストカバレッジ」クラスタ
• 「any型を使うな」「型を明示して」「ジェネリクスで縛るべき」 → 「型安全性」クラスタ

クラスタ採用基準（両方を満たすもののみ採用）

1. 繰り返し出現: 同種の指摘が2回以上（異なるPR / 異なるレビュアー / 異なる箇所）出現している

   • 同一PRで複数行に同じ指摘がある場合は「1回」として扱う（同一作者の同種指摘の重複は1カウント）
   • 異なるPR・異なるレビュアー間で発生していれば確実に2回以上とみなす

2. 対応すべき類型: 以下のいずれかに該当する

   • バグ・正確性: ロジックエラー・不正動作・欠落エッジケース
   • セキュリティ脆弱性: 認証バイパス・XSS・SQLi・データ漏洩
   • 型安全性: 型エラー・unsafeキャスト・nullable処理漏れ
   • 破壊的変更・後方互換性: APIコントラクト違反・マイグレーション抜け
   • テストカバレッジ: 重要分岐の未テスト・モック過多
   • パフォーマンス: N+1・無限ループ可能性・重い同期処理
   • データ整合性: レースコンディション・バリデーション漏れ
   • Lint/ビルドブロッカー: パイプライン失敗を招く違反

採用しないもの

• 純粋なスタイル好み（フォーマット・改行・空白）
• 主観的な命名提案（既存規約に従っていれば）
• まだ必要のない抽象化提案（過剰設計）
• スコープ外のリファクタ提案
• 既存規約と矛盾する提案

完了条件: クラスタごとに「何の問題か」「何回出現したか」「採用/不採用とその理由」「代表的なコメントURL（2件まで）」が言語化できていること。

フェーズ3: CODING_GUIDELINES.md の生成・更新

既存ファイルがない場合

以下のテンプレートでリポジトリルートに新規作成する。

# Coding Guidelines

このドキュメントは、過去のPRレビューで繰り返し指摘された観点をルール化したものです。
新規コード作成・既存コード修正時の自己レビューチェックリストとして参照してください。

## 更新ルール

- 同種の指摘が2回以上出現した場合のみルール化する
- ルールは「やるべきこと」を肯定形で書く
- 似た項目は統合し、ドキュメント全体のサイズを抑える
- 各ルールには代表的なPRコメントへのリンクを1〜2件添える

---

## <カテゴリ名>

### <ルールタイトル>

<ルール本文。1〜3行で簡潔に。「なぜ」を含める>

参考: [<PR番号 or 簡潔な説明>](<コメントURL>)

既存ファイルがある場合

採用クラスタごとに以下のいずれかを行う:

1. 既存ルールと意味重複: 既存ルールの本文を一般化して内包させる。本文を書き換え、参考リンクを追記する。新規ルールとして追加しない
2. 既存カテゴリに収まる新規ルール: 該当カテゴリの末尾に新ルールを追加する
3. 新規カテゴリが必要: ファイル末尾に新カテゴリを追加し、その下に新ルールを書く

サイズ圧縮ルール（毎回必ず適用）

更新後に以下をチェックし、必要なら整理する:

• 全体行数: 300行を超えたら最も似ているルール同士を統合する（具体的な指摘より「何を守るべきか」を抽象化する方向で）
• 重複表現: 同一カテゴリ内に「Aすべき」「Aを忘れない」「Aし忘れていないか」のような表現重複があれば1つにまとめる
• 参考リンク: 1ルールあたり最大2件まで。古い順に削って2件に絞る
• 使われなくなった指摘: 直近6ヶ月のレビューに同種の指摘が出現していなくても「廃止候補」の目印を付けずそのままにする（削除判断は別スキルの責務）

書き方の原則

• ルール本文は肯定形（「〜してください」「〜を必ず行う」）。「〜しないでください」より「代替を〜する」と書く方が行動につながる
• ルール1つにつき1段落・最大3行。長い場合はサブセクションに分割する
• 「なぜ」を含める: 機械的な禁止ではなく、回避したい問題を1行で示す。例: 「null可能性を放置するとランタイムクラッシュを招くため、optional chainingまたは早期returnで処理する」
• コード例は最小限: 必要な場合のみ3〜5行で示す。長い例はリンク参照に留める

完了条件: CODING_GUIDELINES.mdが更新されており、追加/変更したルール、統合・圧縮した既存ルール、ファイル全体の行数が把握できていること。

git statusで差分が発生していなければ「ガイドライン更新差分なし」と報告してこのスキルを終了する（フェーズ4以降のコミット・PR作成は実行しない）。

フェーズ4: feature branch への切替

commit-pushはカレントブランチにコミット・pushするため、デフォルトブランチ上で実行すると本番ブランチに直コミットが入る。これを避けるため、PR作成用のfeature branchに必ず切り替える。

DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

• CURRENT_BRANCH = DEFAULT_BRANCHの場合: 新しいfeature branchを作成して切り替える
  • ブランチ名はchore/update-coding-guidelines-$(date +%Y%m%d-%H%M%S)形式で、git checkout -b <ブランチ名> で作成
  • 既に同名ブランチが存在する場合は末尾にサフィックスを足してユニーク化
• CURRENT_BRANCH ≠ DEFAULT_BRANCHの場合: そのまま使用する（既に作業ブランチ上にいると判断）

切替後にもう一度git statusでCODING_GUIDELINES.mdが変更ファイルとして見えていることを確認する（ブランチ切替で差分が消えていないこと）。

完了条件: デフォルトブランチではない、かつCODING_GUIDELINES.mdの差分が見えるブランチ上にいること。

フェーズ5: commit-push + create-pr

5-1. commit-push skillの呼び出し

Skillツールでcommit-push skillを引数なしで呼び出す（commit-push側がカレントブランチの差分とコミット履歴を自分で確認して戦略を選ぶ）。

5-2. create-pr skillの呼び出し

Skillツールでcreate-pr skillを呼び出す。create-prはcontext: forkのサブエージェントとして起動され本スキルの会話文脈は引き継がれないため、引数として渡せるのはIssue番号文字列のみ。

• フェーズ0でIssue番号が指定されていた場合: そのIssue番号を引数として渡す（$0に展開され、PR本文にCloses #<Issue番号>が記載される）
• Issue番号が指定されていない場合: 引数なしで呼び出す。ただしcreate-prのテンプレートは無条件でCloses #$0を本文に入れるため、空展開で生成されたCloses #行が本文に残る。これは5-3で後処理する

PR作成後、create-prが返却するPR URLを記録しておく。

5-3. Issue番号なしのケースの後処理（Issue番号が未指定の場合のみ実行）

create-prが残したCloses #（数字なし）行をgh pr editで削除する。

PR_NUMBER=$(gh pr view --json number --jq '.number')
gh pr view "$PR_NUMBER" --json body --jq '.body' \
  | sed -E '/^Closes #[[:space:]]*$/d' \
  | gh pr edit "$PR_NUMBER" --body-file -

• sed -E '/^Closes #[[:space:]]*$/d': 数字なしのCloses #行（末尾に空白が混じるケースを含む）を削除する
• 数字付きのCloses #123が誤って削除されないよう、正規表現は必ず行末（$）まで#の後ろに数字がないことを確認する

Issue番号が指定されていたケースでは正常なCloses #<Issue番号>が入っているのでこのステップはスキップする。

完了条件: PRが作成されており、PR URLが手元にあり、Issue番号未指定ケースでは本文のCloses #空行が削除されていること。

フェーズ6: 出力

呼び出し元に以下を構造化して返す。

## 収集結果
- 期間: <SINCE> 〜 現在
- 対象PR数: <n>
- 抽出した指摘クラスタ数: <m>（うち採用 <k> 件）

## CODING_GUIDELINES.md 更新サマリ
- ファイル: <新規作成 / 既存更新>
- 追加ルール: <n>件
  - <カテゴリ>: <ルールタイトル>（出典PR: #<num1>, #<num2>）
- 統合・圧縮した既存ルール: <n>件
  - <旧ルールタイトル> ← <新指摘> として一般化
- 更新後の総行数: <n>行（前回: <n>行）

## 採用しなかったクラスタ（参考）
- <クラスタ名>: <理由（出現1回のみ / スタイル好みのため 等）>

## PR
- ブランチ: <feature branch名>
- PR URL: <URL>
- 関連Issue: #<num>（指定なしの場合は「なし」）

注意事項

• クラスタリングは意味ベース: 同じキーワードでも文脈が違えば別クラスタ、表現が違っても本質が同じなら同一クラスタ
• 採用基準は厳密に: 出現1回の指摘は重要そうでも採用しない（再発時に改めて拾う）。「対応すべき類型」に含まれない繰り返し指摘も採用しない
• 既存ルールへの統合を優先: ルール数の単調増加はドキュメントを死蔵させるため、意味重複があれば必ず統合する
• 編集対象はCODING_GUIDELINES.mdのみ: 他のソースコード・設定ファイル・別ドキュメントを編集しない
• デフォルトブランチでの直コミット禁止: commit-pushを呼ぶ前にフェーズ4で必ずfeature branchへ切り替える
• 差分なしならPR作成スキップ: フェーズ3完了時点で差分がなければフェーズ4以降を実行しない（空コミット・空PRを作らない）
• 作業対象はリポジトリルートのみ: worktreeで実行する場合、対象は当該worktreeのルートにあるCODING_GUIDELINES.mdとする