コードレビュー後の改善を整理する Codex スキルを作った

コードレビューでは、「そこまで対応する必要あるかな」と思う指摘が出ることがあります。とはいえ、全部対応すればいいわけでもありません。整理した結果、橋渡しするだけのクラスが増えたり、「これ本当に良くなった？」となってしまうのは避けたいところです。

気になる指摘を Codex と一つずつ検討するのもいいのですが、毎回やるとなかなか疲れます。そこで、未確定の任意改善を Codex に選別してもらい、今回実装する内容だけを開発者へ渡す skill-review-handoff を作りました。

レビューと実装の間に挟む#

このスキルは、コードレビュー自体には使いません。

レビュー後に気になる指摘を議論し、最後に今回対応する内容をまとめてもらうために呼び出します。 対応するか決まっていない任意改善が残っていれば、この時点で実装する価値があるかも判断してもらいます。

レビューとその後の議論が終わったら、次のように呼び出しています。

$skill-review-handoff 開発者向けにまとめて

実際に使っているスキル#

現在使っている SKILL.md は次のようになっています。

---
name: skill-review-handoff
description: >
  レビュー後の議論とユーザーの最終判断を優先し、未確定の任意改善は実装価値を選別して、
  今回実装する項目だけを開発者向けの簡潔な Markdown の対応指示へ変換する。
  コードレビュー自体には使用しない。
---

# Review Handoff

レビューと検討を終えた後の、開発者向け最終ハンドオフを作成する。

## 基本方針

- 現在の会話にあるレビュー結果と議論をもとに、ユーザーの最終判断を優先する。
- 合意済みの必須修正と、ユーザーが選んだ任意改善は採用する。
- 対象や判断に必要な情報が不足している場合は、ユーザーに確認して停止する。
- 禁止: レビューにない指摘の追加、ファイル編集、コマンド実行、実装を行う。

## 未確定の任意改善

レビューで提示された項目のうち、次を満たすものだけを採用する。

- リポジトリの規約・既存パターン、または一般的な書き方に沿っている。
- 小さな変更で、可読性、保守性、安全性を明確に改善する。
- 改善効果に対して複雑化が大きくない。

## 出力形式

- 厳守: 対応項目があるセクションだけを、単一の `markdown` コードブロックで出力する。
- 対応項目がない場合は「対応項目はありません。」と返す。

```markdown
## 必須対応

- `<対象ファイル>`
  - `<具体的な変更>`を実施する。

## 対応してほしいリファクタ

- `<対象ファイル>`
  - `<具体的な変更>`を実施する。
```

未確定の任意改善は Codex に選別してもらう#

このスキルを作った理由として、一番大きいのが 未確定の任意改善 の部分です。

まだ対応するか決めていない任意改善については、レビューで出た案に限って、実装する価値があるものを Codex に選別してもらいます。

単に「良さそうなら採用する」ではなく、

• 既存の規約やパターンなどに沿っているか
• 小さな変更で明確な改善があるか
• 改善に対して複雑になりすぎないか

といった基準をスキルに書いています。

新しい改善案を出してもらうためのスキルではありません。あくまで既出の案を対象に選別し、採用された項目は最後に自分でも確認します。

最後は実装する内容だけにする#

選別が終わったら、開発者へ渡す内容には今回実装するものだけを残します。

対応しないと決めたものや、撤回した指摘、保留したもの、将来対応にしたものは含めません。これらはすでに判断済みなので、開発者には今回実装する内容だけを渡した方が、余計な判断を挟まずに済みます。

たとえば、最終的には次のような内容が返ってきます。

## 必須対応

- `app/services/user_import_service.rb`
  - CSV の読み込みに失敗した場合に処理を中断し、エラーを返すようにする。

- `spec/services/user_import_service_spec.rb`
  - CSV の読み込みに失敗した場合のテストを追加する。

## 対応してほしいリファクタ

- `app/services/user_import_service.rb`
  - 重複しているユーザー検索処理を既存の `find_user` メソッドにまとめる。

対応しないと判断した指摘や、その判断理由はここには残しません。開発者には今回対応する内容だけを渡して、そのまま実装に進んでもらいます。

作ってみてよかったこと#

レビューで指摘されると、「よっしゃ全部対応したるわ！」と思ってしまいがちです。ただ、指摘が多いほど「これ本当に必要？」を一つずつ判断することになり、それだけで疲れてしまうこともありました。

そこで、明らかに不要だと思うものや、自分なりに「こうした方がいい」と思うものだけ Codex と議論して、残った任意改善の選別はスキルに任せるようにしました。

使っている感覚では、Codex が不要と判断したものは自分でも納得して見送れることが多いです。一方で、「一般的にはそうかもしれないけど、このプロジェクトには合わない」「この書き方だと読みにくい」といった、プロジェクト固有の事情や自分の感覚が関わるところは自分で判断します。

一般的な基準で選別できるところを Codex に任せたことで、自分で判断する量を減らせました。

追記（2026/09/02）#

スキルの内容を見直しました。

あらためて見てみると、不要なルールや少し過剰になっている部分があったため、簡潔になるように整理しています。

今のところは問題なく、以前と同じように使えています。何かあればまた追記します。

参考#

• Build skills | OpenAI