n8n:human-like-code-review

人間らしいコードレビュー

コードレビューの観点で GitHub のプルリクエストをレビューし、コピー＆ペーストしやすい Markdown 形式のフィードバックファイルを作成します。まずコンテキストを把握します。差分を評価する前に、問題、意図された解決策、周辺のアーキテクチャを理解してください。主な焦点は指摘事項です。アーキテクチャ、過度な複雑さ、バグ、リグレッション、セキュリティ上のエッジケース、テスト不足を優先してください。ユーザーが明示的に依頼しない限り、コードは変更しないでください。

入力

ユーザーは GitHub プルリクエストの URL（例：https://github.com/n8n-io/n8n/pull/1234）を指定する必要があります。

指定されていない場合は、作業を進める前に URL を尋ねてください。

URL から PR 番号とリポジトリを抽出し、gh CLI を使って PR の差分とメタデータを取得します。

ワークフロー

1. PR の URL を解析して、オーナー、リポジトリ、PR 番号を取得します。
2. PR の差分を取得します：gh pr diff <number> --repo <owner>/<repo>
3. PR のメタデータを取得します：gh pr view <number> --repo <owner>/<repo>
4. 既存のレビューコメントを取得します：gh api repos/<owner>/<repo>/pulls/<number>/comments
5. PR の説明に Linear の課題が記載されている場合は、レビュー前に n8n:linear-issue でチケットのコンテキストを取得します。チケットの説明、コメント、リンクされた GitHub の課題や PR、メディア、関連する課題、対象ノードの利用状況、工数見積もりをレビューのコンテキストとして使用します。このスキルを利用できない場合は、現在有効な Linear MCP を通じて同じ Linear のコンテキストを取得するか、作業を続ける前にユーザーにチケットの詳細を提供してもらいます。
6. 簡潔なコンテキストモデルを作成します。解決しようとしている問題、期待される動作、影響を受けるパッケージやシステム、PR の説明、Linear のチケット、リンクされた課題、仕様、既存コードに由来する制約を把握します。
7. 批判的なコードレビューの観点で、差分を徹底的にレビューします。
8. リポジトリで Git に無視される tmp/ フォルダー内に、review-<repo>-<number>.md という名前の新しい .md ファイルを作成します。tmp フォルダーは .gitignore に記載されているため、このファイルがコミットされることはありません。必要に応じてフォルダーを作成し（mkdir -p tmp）、tmp/review-<repo>-<number>.md に書き込みます。完了したら、ユーザーがファイルを開けるよう、パスを表示します。
9. 既存の PR コメントですでに指摘されている点については、現在も有効か確認します。解決済みであれば修正されたことを確認し、未解決であれば、繰り返すのではなく、説明を補足するか追加のコンテキストを加えます。
10. 完了する前に、レビュー中に作成した一時ファイルを削除します。このスキルの実行によって tmp/ に残るファイルは、最終的なレビュー用ファイル tmp/review-<repo>-<number>.md だけにしてください。

一時ファイルの管理

追加のファイルを作成するより、gh の出力を直接読む方法を優先してください。複雑なレビューのために一時ファイル（たとえば、保存した差分や抽出したファイルの内容）が必要な場合は、完了前に削除してください。tmp/pr-*.diff、抽出したソースファイル、空の一時ファイルを残さないでください。

コンテキスト優先のレビュー

変更行だけを見てレビューを始めないでください。まず、解決しようとしている問題、PR／チケット／仕様で約束されている具体的な動作、それを担うべきアーキテクチャ層、適合すべき既存のパターンやヘルパー、重要なエッジケースを把握してください。重要なエッジケースには、セキュリティ、権限、不正な入力、互換性、永続化、並行処理、ロールバック動作が含まれます。

コンテキストが不足している、または矛盾している場合は、その不確実性を明示したうえで差分をレビューし、その旨を ## General に記載してください。要件を推測して作り上げないでください。

優先事項

指摘事項を最優先とし、重大度の高い順に並べてください。

1. アーキテクチャとの適合性 - 誤ったパッケージ／レイヤーに配置された動作、所有権の重複、漏れのある契約、サービスの迂回、認可境界の欠如、またはシステム全体に適合しない変更。
2. 解決策の複雑さ - 問題に対してコードが多すぎること、先を見越しすぎた抽象化、既存のヘルパー、API、またはよりシンプルな方法で解決できるのに独自のロジックを実装していること。
3. バグと動作のリグレッション - ロジックエラー、境界値の誤り、null／undefined の処理、不正な条件、デフォルト値の変更、出力形式の変更、または既存のワークフローの破損。
4. セキュリティ上のエッジケース - インジェクション、認証／認可の不備、安全でない入力処理、シークレットの露出、SSRF／パストラバーサルのリスク、権限昇格、リソース使用量の無制限化、信頼境界での検証不足。
5. コード品質 - 不明瞭な契約、壊れやすい結合、弱い型付け、不要な型キャスト、コードの重複、失敗を隠すエラー処理、または既存のパターンからの逸脱。
6. テスト不足 - 実際の変更、重要なエッジケース、または PR／チケットで約束された動作に対するカバレッジの不足。

スタイル、命名、軽微な指摘は最後に扱い、本当に重要な場合にのみ取り上げてください。

アーキテクチャと複雑さの確認

重要な変更については、近接する実装や共有ユーティリティと比較してください。 その動作がノード、コントローラー、サービス、リポジトリー、フロントエンドストア、共有 API 型、または既存のワークフローユーティリティのどこに属するのかを確認してください。100 行のコードを妥当に 10 行にできるのであれば、よりシンプルな構成と、それがより安全または保守しやすい理由を説明してください。差分が大きいという理由だけで複雑さを指摘しないでください。追加のコードがリスク、動作の重複、または回避可能な保守コストを生む場合に指摘してください。

下位互換性

特にノードを変更する場合、既存ユーザーのワークフローの下位互換性を損なわないか確認してください（名前の変更／削除されたパラメーター、デフォルト値の変更、出力形式の変更、同じ入力に対する動作の違いなど）。

下位互換性が損なわれるリスクがある場合は、ノードのバージョン管理を検討し、そのリスクをコメントに含めてください。既存の動作をそのまま変更するのではなく、新しいノードバージョン（またはバージョン管理されたデフォルト値）を提案してください。

レビューチェックリスト

レビュー時はこのチェックリストを使用してください。各カテゴリについて必ず指摘する必要はありませんが、よくある問題がないか差分を確認してください。

メモリーリーク

• 追加したイベントリスナー／サブスクリプションに、対応する削除／登録解除がない
• タイマー（setInterval、setTimeout）がクリアされない
• 大きなオブジェクトを保持するクロージャーが、スコープを抜けた後も残る
• キャッシュや Map が、追い出しの仕組みなしに増加する
• エラー経路を含むすべての経路で、ストリームやファイルハンドルが閉じられない
• dispose()／destroy() で null 化すべき参照をクラスフィールドが保持している
• ストリーム：.write() の戻り値を無視している（drain の待機がない）、pipeline() の代わりに .pipe() を使用している、終了処理に AbortSignal がない、highWaterMark が調整されていない objectMode ストリーム、非対称なバッファー制限がない Transform ストリーム。

エッジケース

• null／undefined の入力 - ガードされているか、事前条件として文書化されているか
• 空のコレクション - [] と {} を処理できるか
• ループやスライスの境界値の誤り
• 並行／再入呼び出し - 非同期メソッドを実行中に 2 回呼び出しても安全か
• 可変状態、カーソル、ロック、ポーリング、またはバックグラウンドタスクを共有する非同期操作間の競合状態
• 数値フィールドの整数オーバーフロー／精度損失
• 複数ステップの操作における部分的な失敗 - 状態の整合性が保たれるか
• Union 型に対する switch 文に default がない

永続化 / API 契約

• マイグレーション、外部キー、ロールバックの動作、エンティティのフィールドが一致している
• リソースの所有権とプロジェクト/ユーザーのスコープが、ルートだけでなくサービス層でも適用されている
• 認証済みのコントローラールートが @ProjectScope または @GlobalScope を使用している
• パッケージの境界が守られている。cli や n8n 固有の概念が汎用 SDK パッケージに漏れ出してはいけない

可読性

• メソッド名がメソッドの実際の動作と一致していない
• 呼び出し側の意図を不明瞭にする真偽値パラメーター(オブジェクトやオーバーロードを推奨)
• 深いネスト(3 レベル超) - アーリーリターンや抽出が助けになる
• 名前付き定数のないマジックナンバー / マジック文字列
• なぜを説明するのではなくコードを言い換えているだけのコメント
• 同じファイルやモジュール内で一貫性のない命名規則
• 型ガードではなく過剰な型アサーション

メソッド / 関数のサイズ

• 約 100 行を超えるメソッドはすべてリファクタリング提案の対象としてフラグを立てる
• 複雑化しつつあるメソッドをフラグする: パラメーターが多い(4 個超)、深くネストした条件、複数の抽象化レベルが混在している
• 責務ごとの抽出を提案する: セットアップ、コアロジック、ティアダウン - それぞれを適切に命名したヘルパーにできる
• 複雑な switch/if チェーンについては、将来の拡張を簡素化できる箇所でディスパッチテーブルやストラテジーパターンを提案する

重大度と優先度の定義

重大度	意味
Critical	本番環境で発生するデータ損失、クラッシュ、セキュリティホール、リソースリーク
High	現実的な入力でバグやサイレント障害を引き起こす可能性が高い
Medium	堅牢性を低下させる、またはコードの成長に伴い問題を引き起こす
Low	スタイル、可読性、軽微な改善

優先度	意味
P1	マージ前に必ず修正
P2	この PR 内または直ちにフォローアップとして修正すべき
P3	あると望ましい、タスクとして起票可能

出力形式

Markdown ファイルには以下を含める必要があります:

• PR のタイトル、URL、レビュー日を含むヘッダー。
• ## Hints for a reviewer セクション(下記参照)。
• ## General セクション(下記参照)。
• 以下の形式のレビューコメント一覧を含む ## Comments セクション:

file name + line number + comment

• レビューの最後にプレーンテキストの ## Issue Summary セクション(問題のない カテゴリは省略)。

コメントはコピー/ペーストしやすいようにしてください。コメントを > で引用しないでください - そのまま直接書いてください。

行コメントがなくてもまったく問題ありません。何か言うためだけに指摘を無理に作ったり、 些細なことを指摘したりしないでください。そのような場合は、空のコメントリストと短い前向きな ## General コメントを優先してください。

コメントが別のものを提案する場合は、それを正確に述べてください。実際のコード変更(著者が直接適用できる短いスニペットや suggestion ブロック)を提案するか、完全なスニペットが現実的でない場合は、漠然としたヒントではなく具体的な方向性(どの関数/値/アプローチを使うか)を述べてください。「これはもっとクリーンにできる」のような、実行可能な次のステップのないコメントは避けてください。

問題のサマリー

文章によるレビューの後は、必ずプレーンテキストの ## Issue Summary セクションで締めくくってください。カテゴリに問題がない場合は、空の見出しを追加するのではなく、そのカテゴリをスキップしてください。

次の形式を使用してください:

## Issue Summary

1. Critical / P1 / Memory leak
   Location: `path/to/file.ts:42`
   `setInterval` in constructor is never cleared.

2. High / P2 / Edge case
   Location: `path/to/service.ts:100`
   No guard for empty array - crashes on `arr[0].id`.

3. Medium / P3 / Method size
   Location: `path/to/handler.ts:buildFoo()`
   80-line method mixes validation, mapping and I/O; suggest splitting into three helpers.

Hints for a reviewer

ヘッダーの直後に、人間のレビュアーが diff を読む前に状況を把握できるよう、## Hints for a reviewer セクションを含めてください:

• PR が作成された短い理由(解決する問題や目標)。
• 解決策を説明するいくつかの簡単な言葉。過度に複雑にしないこと。
• コミュニティ PR の場合は、簡単に言及してください。これは通常、authorAssociation や random-fork-owner:fix-node-option のようなフォーク接頭辞付きブランチから見分けられます。

数文に留めてください。詳細な記述ではなく、レビュアーの時間を節約することが目的です。

全体的な概要コメント

行ごとのコメントの前に、レビューの概要として貼り付けられる ## General セクションを追加します。人間らしく自然な表現にしてください。変更内容にふさわしければ、「こんにちは、いい仕事ですね」のような短く親しみやすい言葉で始めてもかまいません。その後、特定の行には当てはまらない、PR 全体に関するフィードバックを追加します。たとえば、設計やアーキテクチャ上の懸念、ファイル間で暗黙的または型安全でない契約、繰り返し使われているパターン、変更の範囲、実際の変更に対するテストカバレッジの不足などです。

• 短く、会話調にします。個々の行コメントをここで繰り返したり、要約したりしないでください。
• 例外として、解決策全体に大きな設計上の問題がある場合、つまりアプローチ全体が誤っている、または構造的な問題がある場合は、個々のコメントに分散させず、ここで全体的な考え方を説明してください。
• PR 全体に関して指摘することが本当に何もない場合は、短く肯定的なレビューの概要を書いて次に進みます。内容を無理に引き延ばさないでください。

行番号のルール

行番号には、diff のハンク内の位置ではなく、PR ブランチ上のファイルの実際の行番号（diff の新しい側／右側）を必ず使ってください。

正しい行番号を取得するには、@@ のハンクヘッダー（例：@@ -19,10 +19,9 @@）を確認します。+19 は、新しいファイルが19行目から始まることを示します。そこから、コンテキスト行（ ）または追加行（+）ごとに数えます。削除行（-）は新しいファイルには存在しないため、数えません。

例：ハンクが @@ -10,5 +10,6 @@ で、削除行を除いて3行目にコメントしたい場合、行番号は10 + 2 = 12です。

行番号を推測してはいけません。必ずハンクヘッダーから計算してください。

一貫性の確認

命名、構造、スタイルのパターンについて変更を提案する前に、同じパターンがコードベース内や類似するノード／ファイルで使われているか確認してください。確立された慣例であれば、指摘しないでください。既存のパターンから実際に逸脱している場合にのみコメントしてください。

書式ルール

• 長いダッシュや em ダッシュは使わないでください。代わりに - を使います。
• コメントはできるだけ短くしてください。理想は1文です。
• 行コメントでは、「いいですね！」、「素晴らしいです！」、「よくできています！」のような中身のない言葉を避け、具体的な提案や質問をしてください。

トーン

親しみやすい人間のレビュアーのように、自然な表現でレビューコメントを書いてください。

次のような表現を使ってもかまいません。

• 〜するのはどうでしょうか？
• 〜かどうか気になります。
• 皆さんはどう思いますか？

ときどき絵文字を入れてもかまいません 🙂

批判的な表現や、「間違えましたね」のような非難する言葉は避け、協力的なトーンを保ってください。

重要

ユーザーから明示的に依頼されない限り、コードを変更してはいけません。このスキルでは修正ではなく、レビューを行います。

返信の最後の文は、ユーザーがエージェントのチャットからすぐに開けるレビュー用ファイルへのクリック可能な Markdown リンクにしてください。次の形式を使います：[tmp/review-<repo>-<number>.md](tmp/review-<repo>-<number>.md)。 リンクの後には何も書かないでください。