code-review-and-quality

code-review-and-quality skill の概要

code-review-and-quality skill でできること

code-review-and-quality skill は、マージ前のコードを確認するための構造化されたレビュー手順です。単に「この PR をレビューして」と伝えるのではなく、変更内容を正確性、可読性、アーキテクチャ、セキュリティ、パフォーマンスの5つの観点で評価するよう促します。断片的なコメントではなく、判断に使えるレビューがほしいときに向いています。

どんな人に向いているか

最適なのは、すでに PR ベースでコードを出荷していて、再現可能な品質ゲートを欲しいエンジニア、テックリード、AI 支援コーディング利用者です。特に、別のエージェントが書いたコードを確認するとき、バグ修正に回帰チェックが必要なとき、リファクタリングが一見きれいでも正確性や設計上の劣化を含んでいそうなときに価値があります。主にスタイルの lint チェックをしたいだけなら、これはそれより広い用途です。

利用者が本当に気にするポイント

code-review-and-quality skill を評価する多くの人が気にするのは、実際のリスクを拾えるか、厳しすぎて止めすぎないか、普通のリポジトリで使えるか、の3点です。この skill の強みは、コードの健全性が明確に改善されるなら、完璧でなくても承認するという判断基準にあります。そのため、個人の好みを過度に重視するレビュー指示よりも実務的です。

代替できないもの

この skill は、静的解析ツール、テストランナー、ポリシーエンジンそのものではありません。レビューの質は上がりますが、最終的にはあなたが与えるコード、diff、タスク文脈、テスト、命名や実装規約に依存します。想定動作、影響ファイル、既知の制約を渡さないと、レビューの信頼性はこの workflow が示すほど高くなりません。

code-review-and-quality skill の使い方

導入時の文脈と最初に読む場所

code-review-and-quality install では、skills 対応環境に親の skill repo を追加してから、まず skills/code-review-and-quality/SKILL.md を開いてください。この skill は自己完結型に見えます。skill フォルダ内に追加の rules/、resources/、補助スクリプトはなく、主要ドキュメント自体が実装です。軽く呼び出す前に、概要、使うタイミング、5軸レビューのセクションを読んでおくと理解しやすくなります。

よいレビューのために必要な入力

code-review-and-quality usage の品質は入力に強く左右されます。以下を渡してください。

• diff か変更済みファイル
• 元のタスク、issue、受け入れ条件
• 言語 / フレームワーク
• テスト状況や失敗ケース
• 後方互換性、レイテンシ予算、セキュリティ要件など、見落としやすい制約

弱いプロンプトは: “Review this code.”
より強いプロンプトは: “Use the code-review-and-quality skill to review this auth PR. Focus on correctness, security, and regression risk. Here is the diff, expected login behavior, known edge cases, and current test output. Separate must-fix issues from non-blocking suggestions.”

ざっくりした目的を、実用的なプロンプトにする

よい code-review-and-quality guide プロンプトは、指摘事項とマージ推奨の両方を求めるべきです。使いやすいテンプレートは次の要素を含みます。

• 何が変わったか
• なぜ変えたか
• あるべき正しい動作は何か
• 5軸のどこを優先するか
• 出力形式: ブロッカー、警告、提案、承認推奨

例:
“Use code-review-and-quality for Code Review on this payment retry change. Review across correctness, readability, architecture, security, and performance. Prioritize correctness and idempotency. Check whether tests cover retry limits and duplicate charge prevention. Return: 1) blockers, 2) non-blocking improvements, 3) approve / approve with changes / do not approve.”

実務での進め方と出力のコツ

この skill は、問題が起きてからではなく、実装後・マージ前に使うのが基本です。実用的な workflow は次の通りです。

1. diff、タスク仕様、テスト結果を集める。
2. 軸の優先順位を指定して skill を呼び出す。
3. ブロッカーがあればフォローアップ質問をする。
4. コードを修正する。
5. 更新後の diff に同じレビュー prompt を再度当てる。

各指摘に対して、ファイルパス、関数、エッジケース、不足テストを挙げるよう依頼すると品質が上がります。そうすることで、ふわっとしたレビューを防ぎ、実際の PR でそのまま使えるコメントになります。

code-review-and-quality skill の FAQ

code-review-and-quality は通常のレビュー prompt より優れているか？

レビューの深さが安定しないのが問題なら、たいていは yes です。価値の本質は魔法のような解析ではなく、レビュー対象のカバレッジが強制される点にあります。一般的な prompt は、スタイルや、いちばん突っ込みやすい部分に偏りがちです。code-review-and-quality skill は、正確性、保守性、セキュリティ、パフォーマンスをバランスよく見たいときに強みがあります。

初心者にも向いているか？

はい。ただし条件があります。初心者ほど、想像している以上に文脈を渡す必要があります。受け入れ条件や期待動作がないと、レビューは自信ありげでも、ドメイン固有の問題を見落とすことがあります。ジュニアチームでは、この skill は単独の最終承認者というより、チェックリスト付きのレビュー担当として使うのが最も有効です。

どんなときに不向きか？

整形レベルのフィードバック、単一観点の監査、あるいは自動ポリシーチェックだけが必要なら、code-review-and-quality は使わなくてよいでしょう。また、明確な仕様がない巨大変更にも相性はよくありません。タスク自体が曖昧だとレビュー品質が落ちるからです。その場合は、先に変更を小さく分割して、レビュー可能な単位にしてください。

複数の言語や repo でも使えるか？

はい。フレームワークが言語固有ではなく、概念ベースだからです。ただし、エコシステムごとの前提は重要です。React アプリ、Go サービス、Python のデータパイプラインでは、求められるアーキテクチャの考え方が違います。repo の規約を多く伝えるほど、一般論ではなくローカルな標準に沿ったレビューになります。

code-review-and-quality skill を改善する方法

形容詞を増やすより、根拠を増やす

最大の改善は、入力をよくすることです。code-review-and-quality では、「丁寧に見て」と頼むより、次のような情報を渡すほうが効果的です。

• 変更された正確なファイル
• 期待される出力
• 既知のエッジケース
• 追加されたテスト、または不足しているテスト
• 重要なプロジェクト規約

誤検知を減らしたいなら、意図的に対象外にしている部分を明示してください。より深いレビューがほしいなら、並行処理、認可、マイグレーション、キャッシュ、外部 API ハンドリングのようなリスクの高い領域を指定してください。

よくある失敗パターンを防ぐ

典型的な失敗は予測できます。たとえば、スタイルへの偏り、ドメイン制約の見落とし、浅いセキュリティコメント、既存パターンを無視した提案です。これを避けるには、skill に次の区別をさせます。

• 客観的な欠陥 vs 好み
• マージを止める問題 vs 片付け提案
• ローカルなコード臭 vs システム全体のアーキテクチャリスク

この整理は、skill の「完璧さを追うのではなく、コードベースを改善する」という思想と一致しています。

1回目のレビュー後に反復する

最初の1回で終わらせないでください。初回の code-review-and-quality usage の出力が一般論ばかりなら、次のように追加で聞きます。

• “Which findings are most likely to cause production bugs?”
• “Which concerns are unsupported by the diff?”
• “What test cases would prove or disprove your top two blockers?”
• “Re-review after these fixes and tell me what risk remains.”

こうすると、この skill はチェックリストではなく、レビューのループになります。

チームに合わせて承認基準を調整する

code-review-and-quality skill を改善するには、承認のしきい値をチームの実際のマージポリシーに合わせてください。この skill の判断の核は妥当です。完璧ではなくても、コードの健全性を実質的に改善するなら承認する、という考え方です。最終判断を3段階で求めると、それをさらに活かせます。つまり、マージしてよい、修正後にマージ、設計から見直し、の3つです。そうすれば、レビュー出力が延々としたコメントではなく、実際の出荷判断に役立つものになります。