review-feedback-schema

レビューフィードバックのスキーマ

目的

コードレビューの結果を記録するための構造化形式です。このデータにより、次のことが可能になります。

1. 誤検出を引き起こすルールの特定
2. スキルの精度の経時的な追跡
3. パターン分析によるスキルの自動改善

スキーマ

date,file,line,rule_source,category,severity,issue,verdict,rationale

フィールド	型	説明	値の例
date	ISO date	レビューが行われた日付	2025-12-23
file	path	相対ファイルパス	amelia/agents/developer.py
line	string	行番号	128、190-191
rule_source	string	問題を引き起こしたスキルとルール	python-code-review/common-mistakes:unused-variables、pydantic-ai-common-pitfalls:tool-decorator
category	enum	問題の分類	type-safety、async、error-handling、style、patterns、testing、security
severity	enum	レビュアーが付けた重要度	critical、major、minor
issue	string	問題の簡単な説明	Return type list[Any] loses type safety
verdict	enum	人による判断	ACCEPT、REJECT、DEFER、ACKNOWLEDGE
rationale	string	判断を選んだ理由	pydantic-ai docs explicitly support this pattern

ゲート（フィードバックログの行）

行を追加する前に、順番どおりに実行してください。ゲートに失敗した場合は、次へ進まないでください。

1. コードに紐づいた根拠

   • 合格条件： file がリポジトリ相対の既存パス（またはレビュー時点で存在していたパス）であり、line が、要約を言い換えただけではなく、実際に開いて確認した行番号を示していること。

2. ルールの出典を特定可能

   • 合格条件： rule_source が skill-name[/section]:rule-id の形式に一致していること（ルールの出典形式を参照）。トリガーが不明な場合は、最善の推定に基づく出典を設定し、ルール ID を作り上げるのではなく、その不確実性を rationale に記載してください。

3. 根拠資料に裏付けられた判定

   • 合格条件： REJECT の場合、rationale に確認可能な情報（コマンドと出力、ドキュメントの URL、引用したコード）を記載すること。ACCEPT の場合、修正内容を記載するか、変更箇所を示すこと。DEFER／ACKNOWLEDGE の場合は、判定の種類に従い、トラッカー、スケジュール、または文書化された意図を示すこと。

4. 行の形式が有効

   • 合格条件： 行にヘッダー行と一致する9個のカンマ区切りフィールドがあること。カンマまたは改行を含むフィールドは CSV の引用符で囲み、標準的なパーサーが列を正しく保持できるようにしてください。

判定の種類

判定	意味	対応
ACCEPT	問題は妥当で、修正する	コードを変更した
REJECT	問題は誤り、または不適切	変更しない。必要に応じてスキルを改善する
DEFER	妥当だが、今は修正しない	後で対応するために追跡する
ACKNOWLEDGE	妥当だが、意図的なもの	意図的である理由を文書化する

各判定を使う場面

ACCEPT：レビュアーが実際の問題を正しく特定しました。

2025-12-27,amelia/agents/developer.py,128,python-code-review:type-safety,type-safety,major,Return type list[Any] loses type safety,ACCEPT,Changed to list[AgentMessage]

REJECT：レビュアーの指摘は誤りで、コードは正しいです。

2025-12-23,amelia/drivers/api/openai.py,102,python-code-review:line-length,style,minor,Line too long (104 > 100),REJECT,ruff check passes - no E501 violation exists

DEFER：問題は妥当ですが、現在の作業範囲外です。

2025-12-22,api/handlers.py,45,fastapi-code-review:error-handling,error-handling,minor,Missing specific exception type,DEFER,Refactoring planned for Q1

ACKNOWLEDGE：意図的な設計上の判断です。

2025-12-21,core/cache.py,89,python-code-review:optimization,patterns,minor,Using dict instead of dataclass,ACKNOWLEDGE,Performance-critical path - intentional

ルールの出典形式

形式：skill-name/section:rule-id または skill-name:rule-id

例：

• python-code-review/common-mistakes:unused-variables
• pydantic-ai-common-pitfalls:tool-decorator
• fastapi-code-review:dependency-injection
• pytest-code-review:fixture-scope

スキルのフォルダー名を使用し、問題を引き起こした特定のルールまたはセクションを示してください。

カテゴリー分類

カテゴリー	説明	例
type-safety	型注釈の問題	型の欠落、誤った型、Any の使用
async	Async／await の問題	非同期処理内でのブロッキング、await の欠落
error-handling	例外処理	bare except、エラー処理の欠落
style	コードのスタイル／フォーマット	行の長さ、命名規則
patterns	デザインパターン	アンチパターン、フレームワークの誤用
testing	テストの品質	カバレッジの不足、不安定なテスト
security	セキュリティ上の問題	インジェクション、シークレットの露出

適切な理由の書き方

ACCEPT の場合

修正した内容を説明します：

• "Exception を (FileNotFoundError, OSError) に変更しました"
• "model_copy(update={...}) を使うように修正しました"
• "未使用の Any インポートを削除しました"

REJECT の場合

問題が無効である理由を説明します：

• "ruff check は成功します。E501 違反はありません"（リンターが権威ある判定元です）
• "pydantic-ai のドキュメントでは、このパターンが明示的にサポートされています"（フレームワークの慣用的な書き方です）
• "コードコメントに記載された意図的な最適化です"（判断が記録されています）

DEFER の場合

いつ、なぜ対応するのかを説明します：

• "issue #123 で追跡しています"
• "Q1 にリファクタリングを予定しています"
• "依存関係のアップグレード待ちです"

ACKNOWLEDGE の場合

意図的である理由を説明します：

• "プロジェクトの規約（例：AGENTS.md または CLAUDE.md）に基づく、パフォーマンスが重要な処理経路です"
• "レガシー API との互換性要件です"
• "上流ライブラリのパターンに準拠しています"

ログの例

date,file,line,rule_source,category,severity,issue,verdict,rationale
2025-12-20,tests/integration/test_cli_flows.py,407,pytest-code-review:parametrization,testing,minor,Unused extra_args parameter in parametrization,ACCEPT,Fixed - removed dead parameter
2025-12-20,tests/integration/test_cli_flows.py,237-242,pytest-code-review:coverage,testing,major,Missing review --local in git repo error test,REJECT,Not applicable - review uses different error path
2025-12-21,amelia/server/orchestrator/service.py,1702,python-code-review:immutability,patterns,critical,Direct mutation of frozen ExecutionState,ACCEPT,Fixed using model_copy(update={...})
2025-12-23,amelia/drivers/api/tools.py,48-53,pydantic-ai-common-pitfalls:tool-decorator,patterns,major,Misleading RunContext pattern - should use decorators,REJECT,pydantic-ai docs explicitly support passing raw functions with RunContext to Agent(tools=[])
2025-12-23,amelia/drivers/api/openai.py,102,python-code-review:line-length,style,minor,Line too long (104 > 100),REJECT,ruff check passes - no E501 violation exists
2025-12-27,amelia/core/orchestrator.py,190-191,python-code-review:exception-handling,error-handling,major,Generic exception handling in get_code_changes_for_review,ACCEPT,Changed Exception to (FileNotFoundError OSError)
2025-12-27,amelia/agents/developer.py,128,python-code-review:type-safety,type-safety,major,Return type list[Any] loses type safety,ACCEPT,Changed to list[AgentMessage] and removed unused Any import

レビュー前の確認チェックリスト

指摘事項を報告する前に、レビュー担当者は必ず以下を確認してください：

確認手順

1. 問題の存在を確認する：文脈から推測せず、実際のコードを読みます
2. 周辺のコードを確認する：ガードや先行チェックなど、別の箇所で問題に対処している場合があります
3. 状態や変数の使用状況を追跡する：「未使用」と指摘する前に、すべての参照を検索します
4. 主張を検証する：「X がない」と指摘する場合、X が存在しないことを確認します
5. フレームワークの処理を確認する：多くのフレームワークは、検証やエラー処理を自動的に行います
6. 構文の理解を検証する：現行のドキュメント（Tailwind v4、TS 5.x など）で確認します

よくある誤検知のパターン

パターン	根本原因	防止策
"未使用の変数"	別の箇所で変数が使用されている	すべての参照を検索する
"検証がない"	フレームワークが検証する	Pydantic/Zod などを確認する
"型アサーション"	実際には型注釈	as と : のどちらかを確認する
"メモリリーク"	クリーンアップが存在する	effect の戻り値を確認する
"構文が間違っている"	新しいフレームワークのバージョン	現行のドキュメントで確認する
"スタイルの問題"	ルールではなく好み	どちらの方法も有効

誤検知のリスクを示す兆候

以下のいずれかを指摘しようとしている場合は、再確認してください：

• "この変数は未使用のようです" → まずすべての参照を検索します
• "エラー処理がありません" → 親やフレームワークによる処理を確認します
• "Y ではなく X を使うべきです" → どちらも有効な場合があります
• "この構文は間違っているようです" → 現行バージョンのドキュメントで確認します

完全な確認ワークフローについては、review-verification-protocol を参照してください。

スキルの改善への反映方法

1. rule_source ごとに集計する：REJECT 率の高いルールを特定します
2. 理由を分析する：却下理由に共通するテーマを見つけます
3. スキルを更新する：例外、補足説明、確認手順を追加します
4. 影響を追跡する：変更によって却下率が低下したかを測定します

完全な分析ワークフローについては、review-skill-improver スキルを参照してください。

改善の手がかり

パターン	スキルの改善
"リンターが成功する" という却下	スタイルの問題を指摘する前に、リンターで確認する手順を追加する
"ドキュメントでサポートされている" という却下	ドキュメントに記載されたフレームワークのパターンに対する例外を追加する
"意図的である" という却下	指摘する前に、コードベースの文脈を確認する
"コードの経路が違う" という却下	不備を指摘する前に、コードを追跡する手順を追加する