テストは緑色なのに、マージするには引っかかる
AIコーディングエージェントに小さな変更を任せたところ、予想以上に多くのファイルが変わっていました。テストもリンターもすべて通過していますが、よく見ると既存のデータフローを迂回したり、依頼していない業務ルールまで変更したりしています。
このようなとき、一般的な自動チェックは構文エラーや型の問題を知らせてくれても、「チームで合意したプロダクトを今も作れているか？」には答えられないことがあります。コードが動作することと、プロダクトの意図に合っていると判断することは、別のレビューだからです。
Prelintはこの2つ目の問いに注目します。リポジトリ内のプロダクト仕様、ADR、業務ルールとPRの変更内容を照合し、スコープ逸脱や決定違反を見つけるプロダクト整合性レビューのレイヤーです。リンター、型チェッカー、セキュリティスキャナーを置き換えるツールではありません。
違いはバグ検出ではなく、レビュー基準にある
Prelintが見る基準は、コードの見た目ではなくコードが従うべきだった決定です。公式ドキュメントによると、プロダクト仕様違反、ADRへの準拠、業務ロジック、作業スコープの逸脱をレビューし、コードスタイルや一般的なセキュリティ脆弱性のチェックは専用ツールに任せます。
| レビュー層 | 問うこと | 主な根拠 |
|---|---|---|
| CI・静的解析 | ビルドでき、テストを通過するか？ | テスト、型、リンタールール |
| セキュリティ検査 | 既知の脆弱性や危険なパターンはあるか？ | セキュリティルール、依存関係データ |
| プロダクト整合性レビュー | 合意した要件と設計に従っているか？ | プロダクト仕様、ADR、業務ルール |
たとえば、ドキュメントに「すべての請求書のデフォルト支払期限は発行日から30日」と書かれているのに、PRがデフォルト値を60日に変えたとします。コードは正常に動くかもしれませんが、文書化された業務ルールとは衝突します。Prelintが捉えようとするのは、まさにこのような変更です。
インストールから始めず、ルール1つとPR1つで試しましょう
最初のレビューの目的は、リポジトリ全体を文書化することではありません。現在有効なルールを1つ入れ、そのルールに違反する小さなPRで根拠につながるfindingが出るかを確認すればよいのです。現在公開されている一般向けの開始経路はGitHub Appで、インストールを承認する組織またはリポジトリの権限が必要です。
- PrelintアプリでGitHub認証を行います。 GitHub Appをインストールするときは、組織全体ではなく試すリポジトリだけを選んでください。Prelintはレビューに必要なコードとPRデータを読み取りますが、リポジトリのコードを直接実行しません。
- 現在有効なルールを1つ、Markdownでリポジトリに追加します。 たとえば、
specs/billing.mdに「すべての請求書のデフォルト支払期限は発行日から30日である」と記録してください。最初のレビューに専用の設定ファイルは必須ではありません。 - デフォルト支払期限を60日に変える小さなPRを開きます。 別ブランチで変更し、ドラフトではないPRに切り替えてください。ドラフトPR、デフォルトで除外されるボットが作成したPR、関連ファイルの変更がないPRは、レビューがスキップされる場合があります。
- PRのcheck runサマリーとdiffのインラインコメントを確認します。 成功基準は、変更がドキュメントと衝突したとき、該当行に根拠につながるfindingが投稿されることです。衝突しない変更なら、現在のPRバージョンにアクティブなfindingがないという結果が表示されます。
- 指摘された値を修正し、新しいコミットをプッシュします。 更新された結果で既存のfindingが消えたかを確認してください。PRの作成、再開、ドラフト解除、新しいコミットのプッシュがレビューのきっかけになる場合があります。
- 試験を広げる前にBillingを確認します。 完了したレビューは1件あたり1ドルで、失敗・キャンセル・タイムアウトしたレビューには課金されません。登録時に10ドルのクレジットが提供され、公開リポジトリのレビューは無料ですが、新しいコミット後に完了した再レビューも別件として数えられます。自動チャージの状態と月間支出上限を先に確認してください。
最初の試験は、意図的に明確な衝突にしてください。
曖昧な設計原則より、「30日を60日に変更」のようにドキュメントとdiffの衝突を人がすぐ判断できるケースが適しています。結果がおかしいときに、ツールの判断の問題なのか、元のドキュメントが曖昧だったのかを区別しやすくなります。
文書を多く入れれば、よりよく見られるわけではない
Prelintはリポジトリ内のMarkdown仕様とADRを自動でインデックス化しますが、1回のレビューで構成されるコンテキストは最大80K文字です。組織・プロジェクト・リポジトリ文書などの優先順位に従ってコンテキストを構成し、上限を超えると優先度の低い資料が切り落とされることがあります。
そのため、過去の議事録をすべて入れるより、決定の状態を明確にするほうがよいでしょう。何を決めたのか、どの範囲に適用されるのか、今も有効なのか、例外は何かを短く明確に書いてください。互いに矛盾していたり、廃止されたかどうかが示されていなかったりする文書は、AIだけでなく人間のレビュー担当者も混乱させます。
レビューに含まれる文書とコードを先に確認してください。
Prelintはリポジトリのコードを実行しませんが、レビューのためにコードとPRデータを読み取り、AWS環境で処理します。機密ファイルがある場合は、リポジトリを接続する前にアクセス範囲、除外設定、組織のデータ処理基準を確認する必要があります。
36.6%は効果ではなく、レビュー範囲が変わったというシグナルです
Prelintの自社研究では、331の公開リポジトリにある56,706件のPRを、文書がある条件とない条件でそれぞれレビューしました。文書がない場合のフラグ率は13.3%、文書を含めた場合は36.6%でした。コンテキストがあったからこそ発見された項目は979件、逆にコンテキストによって不要な警告が抑制されたケースは232件と報告されています。
この結果は、文書がレビュー対象を変えうるという仮説を示しています。ただし、フラグ率が上がったからといって、実際の欠陥や障害が同じだけ減ったことを意味するわけではありません。 研究は製品ベンダーが実施し、モデル採点にはOpus 4.6を使用しており、リポジトリの抽出、人による検証手順、生の結果は独立した再現に十分なほど公開されていません。
チームで判断するときは、findingの数ではなく3点を見てください。findingが実際に有効だったか、人が見落としそうなプロダクト上の決定を指摘したか、修正後に同じ違反が消えたかです。この3点が確認されて初めて、プロダクト整合性レビューはコメントを増やすだけのツールではなく、マージ判断を助けるレイヤーになります。
導入するかどうかは、最初の5件で判断できます
Prelintの価値は、既存のコードレビューをなくすことではありません。テストとセキュリティ検査を維持したまま、文書化された意図を照合する問いを1つ加えることにあります。
最初からリポジトリ全体に適用せず、結論が明確なルールと小さなPRを5件から始めてみてください。各findingを有効な違反、文書の曖昧さ、誤った警告に分類すれば、次の行動が明確になります。有効な違反が繰り返されるなら適用範囲を広げ、文書の問題が多いならADRから整理し、誤った警告が多いなら自動マージゲートとして使わないほうが安全です。
さらに深く知りたいなら
Documentation - Prelint GitHub Appの接続、文書のインデックス化、最初のレビューに必要な公式の開始手順を確認できます。 prelint.com
How reviews work - Prelint PRイベントからコンテキスト構成、二次検証、インラインコメントの投稿まで、レビューのパイプラインを説明しています。 prelint.com
AI Code Pulse — 56,706 PRs Analyzed 文書の有無によるフラグ率と研究の範囲を原文で確認できます。ベンダー自身の研究である点も踏まえて読んでください。 prelint.com
