From dfdc809a45178217bbc4fa18fefe7e264c3bc1ab Mon Sep 17 00:00:00 2001 From: Masakuni Kato <7091+mackato@users.noreply.github.com> Date: Wed, 3 Jun 2026 23:20:42 +0900 Subject: [PATCH 1/3] =?UTF-8?q?Copilot=20=E3=83=AC=E3=83=93=E3=83=A5?= =?UTF-8?q?=E3=83=BC=E7=94=A8=E3=82=AB=E3=82=B9=E3=82=BF=E3=83=A0=E3=82=A4?= =?UTF-8?q?=E3=83=B3=E3=82=B9=E3=83=88=E3=83=A9=E3=82=AF=E3=82=B7=E3=83=A7?= =?UTF-8?q?=E3=83=B3=E3=82=92=E8=BF=BD=E5=8A=A0=E3=81=97=20README=20?= =?UTF-8?q?=E3=81=AB=20Good=20Practice=20=E5=8F=82=E7=85=A7=E5=85=88?= =?UTF-8?q?=E3=82=92=E6=98=8E=E8=A8=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR レビューが収束しない（指摘の小分け・後出し・重箱の隅つつき）課題に対し、 GitHub Copilot のカスタムインストラクションを導入する。言語・ツール非依存の 汎用ルールに限定し、重箱の隅をつつかない方針と初回レビューでの網羅・圧縮を中心に据える。 あわせて本リポジトリを他プロジェクトの Good Practice 参照先と位置づける旨を README に追記する。 Co-Authored-By: Claude Opus 4.8 --- .github/copilot-instructions.md | 54 +++++++++++++++++++++++++++++++++ README.md | 7 +++++ 2 files changed, 61 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..079b8fb --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,54 @@ +# GitHub Copilot カスタムインストラクション + +本ファイルは GitHub Copilot が本リポジトリの PR をレビューする際の指示。`@copilot` へのレビュー依頼・コード補完にも適用される。プロジェクト固有の原則・仕様はここに複製せず、下記を一次情報として参照する（DRY）。 + +## 参照ドキュメント + +- [`../README.md`](../README.md) — リポジトリの概要・構成 +- [`../CLAUDE.md`](../CLAUDE.md) — プロジェクト全体の原則・運用ルール + +これらに書かれた内容は本ファイルに複製しない。詳細が必要なら README の目次から関連ドキュメントを辿る。 + +## レビューの進め方 + +- 初回レビューで PR の全変更を対象に、下記の全観点を一度で確認する。レビューを後続ラウンドに小分けにしない。 +- 重大度の高い問題を優先し、瑣末な指摘に終始しない。ただしセキュリティ・法的要件・明らかなパフォーマンス劣化は些細に見えても見逃さない。 + +## 集中すべき観点 + +PR を通すうえで実害があるものに絞って指摘する。 + +- **バグ・ロジック誤り** — 条件分岐漏れ、オフバイワン、意図と実装の齟齬。 +- **セキュリティ** — 入力検証不備、認可・認証の欠落、シークレット露出、既知の脆弱性パターン、ログへの機微情報流出、CI 等の権限（`permissions`）過剰付与。 +- **破壊的変更** — 公開インターフェイス（CLI 契約・API・データ形式）への非明示な非互換変更。 +- **明らかなパフォーマンス劣化** — N+1、ホットパスでの不要な処理など、測定せずとも明らかなもの。微細な最適化の提案は不要。 +- **YAGNI 違反** — 仮想的な将来要件のための抽象化・設定項目・フォールバック・防御コード、タスク範囲外のリファクタや周辺整理。 +- **DRY 違反** — 同じ事実・定義・設定を複数箇所に書く変更。ただし構造が似ているだけで意味が異なる処理の無理な共通化は求めない。 +- **ドキュメント追従** — 仕様・挙動を変える変更で、関連する README / CLAUDE.md / 配下ドキュメントが同じ変更内で更新されているか。 + +## 重箱の隅をつつかない（厳守） + +レビューコメントの想定読者は開発者・ステークホルダーである。文脈で意図が伝わる内容への、厳密性だけを理由とした指摘を**固く禁止する**。判断基準は「読者がこの PR（差分とその説明）を読んで誤解・手戻り・リスクが生じるか」であり、生じないなら指摘しない。次は指摘しない。 + +- 個人の好みに基づくスタイル・命名・表記ゆれ・言い回しの指摘、挙動に影響しない微小なリファクタ提案。 +- Lint / Formatter / 型チェックで機械的に検出できる事項。 +- 網羅的な null / 例外チェックの追加や、冗長なコメント・docstring の追加提案。 +- 機能的に等価な書き換え提案（「こう書くほうが簡潔」「三項演算子のほうがスマート」等）。 +- 「将来策定予定」「別途定める」等と文脈で分かる事項について、参照先・配置先が現時点で存在しないこと自体を問題とする指摘。 +- 設計・要件ドキュメントに対して、実装コードと同等の網羅性・厳密性・参照完備を求める指摘。 +- 日本語を含む Markdown テーブルの行頭 `||` 誤検知（全角文字を含む表で行頭が `||` と誤認される既知の挙動）。`grep -n '^||' ` が該当なしであれば指摘しない。 + +## 指摘の網羅性と圧縮 + +レビューが収束しない主因は、同種の指摘を小分けにして後続ラウンドへ先送りすることである。次を守る。 + +- 同種の問題は 1 回のレビューで全該当箇所を網羅する。段階的（1 箇所 → 後から他箇所を追加指摘）にしない。 +- 同一カテゴリの問題は代表 1 箇所を suggestion 付きで指摘し、他の該当箇所は note でまとめて列挙する。個別コメントに分割しない。 +- ある原則を 1 箇所で適用したら、同じ原則が当てはまる他箇所もその回で全て確認する。 +- 本 PR 内で既に合意・適用されたルールは、後続ラウンドで自動的に全箇所へ展開チェックする。新たに見つけた同種の残存も同じラウンドで一括指摘する（残存を 1 件ずつ追加ラウンドに分けない）。 + +## 出力ルール + +- レビューコメント・提案コード内のコメントはすべて日本語で書く。 +- 何が・なぜ問題か・どう直すかが伝わるよう簡潔に書く。 +- 指摘事項がなければ（または全て解消されたら）、その旨を明示する。 diff --git a/README.md b/README.md index 744cdef..d466607 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,12 @@ org 横断で共有する汎用 dev ツールの集約リポジトリ。各利用 repo はここを参照するだけにし、コピペを撲滅（DRY）してツールの版を固定する。 +## 参照用 Good Practice + +本リポジトリは汎用ツールの集約に加え、設定・運用の実例を**他プロジェクトが Good Practice として参照する場所**でもある。言語・ツールに依存しない汎用ルールをここで枯らし、各プロジェクトは下敷きにして固有の参照ドキュメントを足して使う。 + +- [`.github/copilot-instructions.md`](.github/copilot-instructions.md) — GitHub Copilot のレビュー用カスタムインストラクション。YAGNI / DRY の徹底、重箱の隅をつつかない、初回レビューでの網羅と圧縮を中心に、レビューの収束を早める汎用ルール。 + ## 採用方式 Nix flake × devbox。言語非依存でツールを PATH へ配布し、`flake.lock` / `devbox.lock` で版とコンテナ build を再現可能に固定する。利用側 repo は同一の flake 参照を `devbox.json` の `packages` に足すだけでよい。 @@ -13,6 +19,7 @@ flake.nix # packages / checks (test・lint) / formatter を公開 devbox.json # 開発環境（Nix の test/lint ツール）と自己 dogfooding .env.template # env-init 用テンプレートの書式例（本 repo の dogfood でも使用） .github/ghas.yml # ghas-setup 用ポリシー（本 repo の dogfood 兼・書式例） +.github/copilot-instructions.md # Copilot レビュー用カスタムインストラクション（汎用 Good Practice） pkgs/ env-init/ # 各 pkg の構成は pkg 内 README を参照 ghas-setup/ From f655bba37f876f6a650b61db1c313c821d345753 Mon Sep 17 00:00:00 2001 From: Masakuni Kato <7091+mackato@users.noreply.github.com> Date: Wed, 3 Jun 2026 23:52:49 +0900 Subject: [PATCH 2/3] =?UTF-8?q?copilot-instructions:=20=E9=81=A9=E7=94=A8?= =?UTF-8?q?=E5=85=88=E3=81=AE=E8=A8=98=E8=BF=B0=E3=82=92=E5=AE=9F=E6=85=8B?= =?UTF-8?q?=E3=81=AB=E5=90=88=E3=82=8F=E3=81=9B=E3=81=A6=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `.github/copilot-instructions.md` が参照されるのは Copilot のコードレビュー時で、 コード補完は対象外（GitHub 公式ドキュメント）。誤った運用を招かないよう 「コード補完にも適用」を削除し、レビュー依頼の表現も「Copilot をレビュアーに追加」に改める。 Co-Authored-By: Claude Opus 4.8 --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 079b8fb..0b0fa6d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,6 +1,6 @@ # GitHub Copilot カスタムインストラクション -本ファイルは GitHub Copilot が本リポジトリの PR をレビューする際の指示。`@copilot` へのレビュー依頼・コード補完にも適用される。プロジェクト固有の原則・仕様はここに複製せず、下記を一次情報として参照する（DRY）。 +本ファイルは GitHub Copilot が本リポジトリの PR をレビューする際の指示。Copilot をレビュアーに追加したとき（自動・手動とも）に参照される。プロジェクト固有の原則・仕様はここに複製せず、下記を一次情報として参照する（DRY）。 ## 参照ドキュメント From 552c6be24020a433cb9207fc40db6a7adf432749 Mon Sep 17 00:00:00 2001 From: Masakuni Kato <7091+mackato@users.noreply.github.com> Date: Thu, 4 Jun 2026 00:21:25 +0900 Subject: [PATCH 3/3] =?UTF-8?q?copilot-instructions:=20=E5=8F=82=E7=85=A7?= =?UTF-8?q?=E5=B0=8E=E7=B7=9A=E3=81=AE=E8=A1=A8=E7=8F=BE=E3=82=92=20README?= =?UTF-8?q?=20=E3=81=AE=E5=AE=9F=E6=A7=8B=E6=88=90=E3=81=AB=E5=90=88?= =?UTF-8?q?=E3=82=8F=E3=81=9B=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README に「目次」は存在しないため、「目次から辿る」は誤解を招く。 「該当セクションやそこからのリンクで辿る」に改める。 Co-Authored-By: Claude Opus 4.8 --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0b0fa6d..aeae20b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,7 +7,7 @@ - [`../README.md`](../README.md) — リポジトリの概要・構成 - [`../CLAUDE.md`](../CLAUDE.md) — プロジェクト全体の原則・運用ルール -これらに書かれた内容は本ファイルに複製しない。詳細が必要なら README の目次から関連ドキュメントを辿る。 +これらに書かれた内容は本ファイルに複製しない。詳細が必要なら README の該当セクションやそこからのリンクで関連ドキュメントを辿る。 ## レビューの進め方