ln-511-code-quality-checker

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリを基準とします。

コード品質チェッカー

タイプ： L3 ワーカー
カテゴリー： 5XX 品質

完了した実装タスクを分析し、メトリクス、MCP Ref の検証、問題に対するペナルティに基づいて定量的なコード品質スコアを算出します。

入力

入力	必須	ソース	説明
storyId	はい	args、git ブランチ、kanban、ユーザー	処理するストーリー

解決方法： ストーリー解決チェーン。
ステータスフィルター： 進行中、レビュー待ち

ツールポリシー：ホストの AGENTS.md にある MCP の設定に従ってください。ホストポリシーがない場合、または MCP の動作が不明な場合に限り、references/mcp_tool_preferences.md と references/mcp_integration_patterns.md を読み込んでください。プロジェクトがインデックス化されている場合は、クローン、アーキテクチャ、セマンティック品質の根拠を得るための主要な手段として hex-graph を使用してください。グラフが利用できないか、サポートされていない場合に限り、Grep/Read にフォールバックしてください。

目的と範囲

• ストーリーと完了した実装タスクを読み込みます（テストタスクは除外）
• メトリクスと問題のペナルティを使ってコード品質スコアを算出します
• MCP Ref の検証： 外部ソースを通じて最適性、ベストプラクティス、パフォーマンスを検証します
• DRY/KISS/YAGNI 違反、アーキテクチャ境界の逸脱、セキュリティ上の問題を確認します
• 構造化された問題リストと定量的な判定を出力します。Linear や kanban は編集しません

コードメトリクス

メトリクス	しきい値	ペナルティ
循環的複雑度	≤10 は OK、11-20 は警告、>20 は失敗	関数ごとに -5（警告）、-10（失敗）
関数のサイズ	≤50 行は OK、>50 行は警告	関数ごとに -3
ファイルサイズ	≤500 行は OK、>500 行は警告	ファイルごとに -5
ネストの深さ	≤3 は OK、>3 は警告	該当箇所ごとに -3
パラメーター数	≤4 は OK、>4 は警告	関数ごとに -2

コード品質スコア

計算式：Code Quality Score = 100 - metric_penalties - issue_penalties

重大度別の問題ペナルティ：

重大度	ペナルティ	例
高	-20	セキュリティ脆弱性、O(n²)+ のアルゴリズム、N+1 クエリ
中	-10	DRY 違反、非最適な方法、設定の欠落
低	-3	命名規則、軽微なコードの臭い

スコアの解釈：

スコア	ステータス	判定
90-100	優秀	PASS
70-89	許容範囲	CONCERNS
<70	しきい値未満	ISSUES_FOUND

イシューのプレフィックス

プレフィックス	カテゴリー	デフォルトの重大度	MCP 参照
SEC-	セキュリティ（認証、検証、シークレット）	高	—
SEC-DESTR-	破壊的な操作（ガード：DB、FS、MIG、ENV、FORCE）	高／中	—
PERF-	パフォーマンス（アルゴリズム、設定、ボトルネック）	中	✓ 必須
MNT-	保守性（DRY、SOLID、複雑さ、デッドコード）	中	—
ARCH-	アーキテクチャ（レイヤー、境界、パターン、契約）	中	—
BP-	ベストプラクティス（実装が推奨事項と異なる）	中	✓ 必須
OPT-	最適性（この目的により適した方法がある）	中	✓ 必須

OPT- のサブカテゴリー：

プレフィックス	カテゴリー	重大度
OPT-OSS-	オープンソースの代替手段が利用可能	中（200 LOC を超える場合は高）

ARCH- のサブカテゴリー：

プレフィックス	カテゴリー	重大度
ARCH-LB-	レイヤー境界：インフラ層以外での I/O、ドメイン層での HTTP	高
ARCH-TX-	トランザクション境界：3 つ以上のレイヤーでの commit()、UoW 所有権の混在	高（認証／決済の場合は CRITICAL）
ARCH-DTO-	DTO の欠如（DTO なしで 4 つ以上のパラメーター）、エンティティの漏洩（API レスポンスに ORM エンティティを含める）	中（認証／決済の場合は高）
ARCH-DI-	依存性注入：テスト用に依存関係を置き換えられない（直接インスタンス化、注入機構なし）。例外：パラメーター／クロージャーで十分な小規模スクリプト／CLI → 対象外	中
ARCH-CEH-	エラー処理の一元化：エラーが黙って無視される、本番環境にスタックトレースが漏れる、一貫したエラーログがない。例外：50 行のスクリプト → LOW に引き下げ	中（ハンドラーがまったくない場合は高）
ARCH-SES-	セッション所有権：同じモジュール内に DI セッションとローカルセッションがある	中
ARCH-AI-SEB	副作用の範囲：1 つの リーフ関数に 3 つ以上の副作用カテゴリーがある。競合解決：オーケストレーター／コーディネーター関数（3 つ以上のサービスをインポートし、順次委譲する）は複数のカテゴリーを持つことが想定されます — SEB として報告しないでください	中
ARCH-AI-AH	アーキテクチャ上の誠実さ：読み取りを示す名前の関数に書き込みの副作用がある	中
ARCH-AI-FO	フラットなオーケストレーション：リーフサービスが他のサービスを 3 つ以上インポートする。オーケストレーターによるインポートは想定されるため、報告しないでください	中
ARCH-EVENT-	イベントチャネルの一貫性：パブリッシャー／サブスクライバー名の不一致（MISMATCH）、対応する相手のない孤立チャネル（ORPHAN）	高（不一致）、中（孤立）

PERF- のサブカテゴリー：

プレフィックス	カテゴリー	重大度
PERF-ALG-	アルゴリズムの計算量（Big O）	O(n²) 以上の場合は高
PERF-CFG-	パッケージ／ライブラリの設定	中
PERF-PTN-	アーキテクチャパターンのパフォーマンス	高
PERF-DB-	データベースクエリ、インデックス	高

MNT- のサブカテゴリー：

プレフィックス	カテゴリー	重大度
MNT-DC-	デッドコード：置き換えられた実装、未使用のエクスポート／再エクスポート、後方互換性のためのラッパー、サポートされていないエイリアス	中（公開 API の場合は高）
MNT-DRY-	DRY 違反：複数のファイルにまたがるロジックの重複	中
MNT-GOD-	ゴッドクラス：メソッドが 15 個超、または 500 行超のクラス（単なるファイルサイズではない）	中（1000 行を超える場合は高）
MNT-SIG-	メソッドシグネチャの品質：ブール値フラグのパラメーター、戻り値の型が不明瞭、命名の不統一、省略可能なパラメーターが 5 個超	低
MNT-ERR-	エラー契約の不整合：同じサービス内で例外の送出と None の返却が混在	中

使用するタイミング

• Story のステータスが Done のすべての実装タスク
• 技術的負債の解消およびインラインエージェントレビューの前

ワークフロー（簡潔版）

必ず読むこと： references/input_resolution_pattern.md を読み込んでください

1. storyId を解決する: ガイドに従って Story Resolution Chain を実行します（ステータスフィルター：[In Progress, To Review]）。

2. Linear 経由でストーリー（全体）と完了した実装タスク（詳細な説明を含む）を読み込みます。ラベルが "tests" のタスクはスキップします。

3. 変更されたファイルを収集する（changed_files[]）： 必ず読み込む： references/git_scope_detection.md を読み込みます

   • ln-510 から呼び出された場合：コーディネーターのコンテキストから changed_files[] を使用し、ガイドの Enrich ステップに進みます
   • 単独で呼び出された場合：ガイドのアルゴリズム全体を実行します

4. 2 層検出（必須）： 必ず読み込む： references/two_layer_detection.md を読み込みます しきい値に基づくすべての検出結果には、Layer 2 のコンテキスト分析が必要です。Layer 2 のない Layer 1 の検出結果は、有効な検出結果ではありません。指標違反を報告する前に、「この違反は意図的なものですか、それとも設計上妥当なものですか？」と確認します。以下の指標の Exception 列を参照してください。

5. コード指標を計算する：

   • 関数ごとの循環的複雑度（目標 ≤10。例外：enum/switch によるディスパッチ、ステートマシン、パーサー文法 → LOW に格下げ）
   • 関数のサイズ（目標 ≤50 行。例外：順次委譲を行うオーケストレーター関数）
   • ファイルサイズ（目標 ≤500 行。例外：設定／スキーマ／マイグレーションファイル、生成コード）
   • ネストの深さ（目標 ≤3）
   • パラメーター数（目標 ≤4。例外：ビルダー／オプションパターン）

6. MCP Ref の検証（コード変更では必須 — --skip-mcp-ref フラグが渡された場合はスキップ）： 必ず読み込む： references/research_tool_fallback.md を読み込みます

   ファストトラックモード： --skip-mcp-ref を指定して呼び出された場合、このステップ全体（OPT-、BP-、PERF- チェックなし）をスキップします。ステップ 6（静的解析）に直接進みます。指標と静的解析のカバレッジを維持しながら、コストを約 5000 トークンから約 800 トークンに削減します。

   レベル 1 — 最適性（OPT-）：

   • タスクから目標を抽出します（例：「ユーザー認証」、「キャッシュ」、「API レート制限」）
   • 代替案を調査します：ref_search_documentation("{goal} approaches comparison {tech_stack} 2026")
   • 選択したアプローチを、プロジェクトのコンテキストに照らして代替案と比較します
   • 最適でない選択を OPT- の問題として報告します

   レベル 2 — ベストプラクティス（BP-）：

   • 調査します：ref_search_documentation("{chosen_approach} best practices {tech_stack} 2026")
   • ライブラリについては、query-docs(library_id, "best practices implementation patterns") を使用します
   • 推奨パターンからの逸脱を BP- の問題として報告します

   レベル 3 — パフォーマンス（PERF-）：

   • PERF-ALG： アルゴリズムの複雑度を分析します（O(n²)+ を検出し、MCP Ref で最適な方法を調査）
   • PERF-CFG： query-docs を使用してライブラリの設定（接続プーリング、バッチサイズ、タイムアウト）を確認します
   • PERF-PTN： パターンの落とし穴を調査します：ref_search_documentation("{pattern} performance bottlenecks")
   • PERF-DB： query-docs(orm_library_id, "query optimization") を使用して N+1 とインデックス不足を確認します

   MCP Ref 検証のトリガー：

   • 新しい依存関係を追加した場合（package.json/requirements.txt が変更された）
   • 新しいパターン／ライブラリを使用した場合
   • API／データベースを変更した場合
   • クリティカルパスにループ／再帰がある場合
   • ORM クエリを追加した場合

7. 静的な問題についてコードを分析する（プレフィックスを割り当てる）： 必読： references/clean_code_checklist.md、references/destructive_operation_safety.md を読み込みます。

   • 大きなコードファイルの場合、対象を絞って読み込む前に outline(file_path) を使用します。
   • SEC-：ハードコードされた認証情報、未検証の入力、SQL インジェクション、競合状態
   • SEC-DESTR-：保護されていない破壊的操作 — 上記で読み込んだ destructive_operation_safety.md のコードレベルガード表を使用します。5 つのガードカテゴリ（DB、FS、MIG、ENV、FORCE）をすべて確認します。
   • MNT-：DRY 違反（MNT-DRY-：ロジックの重複）、デッドコード（MNT-DC-：チェックリストに準拠）、複雑な条件分岐、適切でない命名
   • MNT-DRY- ストーリー横断ホットスポットスキャン： 共通パターンのシグネチャ（エラーハンドラー：catch.*Error|handleError、バリデーター：validate|isValid、設定アクセス：getSettings|getConfig）を src/ 内のすべてのファイルで Grep し、件数を確認します。いずれかのパターンが 5 つ以上のファイルに現れる場合は、3 つのファイルをサンプルとして選び（それぞれ 50 行を読み込み）、構造的な類似性を確認します。類似度が 80% を超える場合は → MNT-DRY-CROSS（中、-10 ポイント）：Pattern X duplicated in N files — extract to shared module.
   • MNT-DRY- の優先手段（hex-graph）： hex-graph にインデックスがある場合は、audit_workspace(path=scan_path, verbosity="minimal", limit=5, clone_member_limit=3) を使用します。異なるファイルにある 2 つ以上のメンバーを含むクローングループはすべて MNT-DRY-CROSS とします。範囲を限定したプレビューでは不十分な場合に限り、上限を引き上げます。優先度の判断には、返されたホットスポットとクローンのコンテキストを使用します。hex-graph を利用できない場合は、上記の Grep パターンスキャンに切り替えます。
   • MNT-DC- ストーリー横断の未使用エクスポートスキャン： Story で変更された各ファイルについて、export 宣言の数を数えます。次に、src/ 内のすべてのファイルを Grep し、これらのエクスポートへの import 参照を確認します。import 参照が 0 件のエクスポートは → MNT-DC-CROSS（中、-10 ポイント）：{export} in {file} exported but never imported — remove or mark internal.
   • OPT-OSS- 相互参照 ln-645（静的、高速処理でも安全）： docs/project/.audit/ln-640/*/645-open-source-replacer*.md が存在する場合（すべての日付の glob を対象にし、最新のものを使用）、確信度が HIGH の置き換え候補が現在の Story で変更されたファイルに該当するか確認します。該当する場合は、ln-645 レポートからモジュールパス、目標、推奨パッケージ、確信度、スター数、ライセンスを含む OPT-OSS-{N} の課題を作成します。重要度は、200 LOC を超える場合は高、それ以外は中です。この確認ではローカルファイルのみを読み取ります — MCP 呼び出しは行いません — --skip-mcp-ref を指定した場合も実行されます。
   • ARCH-：レイヤー違反、循環依存、ガイドへの不適合
   • ARCH-LB-：レイヤー境界違反（インフラストラクチャ層以外での HTTP／DB／FS 呼び出し）
   • ARCH-TX-：トランザクション境界違反（複数レイヤーにまたがる commit()）
   • ARCH-DTO-：DTO の欠如（4 つ以上の繰り返しパラメーター）、エンティティの漏出（API から ORM エンティティを返す）
   • ARCH-DI-：ビジネスロジック内での直接インスタンス化（DI コンテナーがない、またはパターンが混在している）
   • ARCH-CEH-：一元化されたエラー処理の欠如、または迂回
   • ARCH-SES-：セッション所有権の競合（同じモジュール内で DI とローカルセッションを併用）
   • ARCH-AI-SEB：副作用の広がり（1 つの リーフ関数内に 3 つ以上のカテゴリがある場合。オーケストレーター関数は対象外 — 上記の表の「競合の解決」を参照）
   • ARCH-AI-AH：アーキテクチャ上の誠実性（読み取りを示す名前の関数が、隠れた書き込みを行う）
   • ARCH-AI-FO：フラットなオーケストレーション（リーフサービスが 3 つ以上のサービスをインポートする場合。オーケストレーターによるインポートは対象外）
   • ARCH-EVENT-：イベントチャネルの不一致 — 変更された changed_files[] 内で、NOTIFY|pg_notify|\.publish\(|\.emit\(（パブリッシャー）と LISTEN|\.subscribe\(|\.on\(（サブスクライバー）を Grep します。チャネル名の文字列を相互参照します。
   • MNT-GOD-：ゴッドクラス（クラスあたりメソッドが 15 個を超える、または 500 行を超える）
   • MNT-SIG-：メソッドシグネチャの品質（ブール値フラグ、不明瞭な戻り値）
   • MNT-ERR-：エラーコントラクトの不整合（同じサービス内で raise と return のパターンが混在している）

8. コード品質スコアを計算する：

   • 100 から開始します
   • メトリクスによる減点を差し引きます（「コードメトリクス」表を参照）
   • 問題による減点を差し引きます（「問題の減点」表を参照）

9. スコアと構造化された問題を含む判定結果を出力します。 必読： references/output_schema.md を読み込みます。 スキーマに従って出力します。調査結果を Linear のコメントに追加します。

重要なルール

• 適合性を判断する前に、Story／Tasks に記載されているガイドを読みます。
• MCP Ref の検証： アーキテクチャに関する変更については、判断する前に必ず ref_search_documentation で検証します。
• ライブラリについての Context7： ライブラリの使用状況をレビューする際は、query-docs で正しいパターンを確認します。
• コメント内の言語（EN／RU）を維持します。
• タスクの作成やステータスの変更は行いません。次の対応は呼び出し元が決定します。

ランタイム概要アーティファクト

必読： references/quality_summary_contract.md と references/quality_worker_runtime_contract.md を読み込みます。

ランタイムプロファイル：

• family: quality-worker
• worker: ln-511
• summary kind: quality-worker
• コーディネーターが使用するペイロードフィールド：worker、status、verdict、score、issues、warnings

呼び出しルール：

• スタンドアロン：runId と summaryArtifactPath を省略します。
• 管理対象：両方の runId と正確な summaryArtifactPath を渡します。
• 終了結果を出す前に、必ず検証済みのサマリーを書き込みます。

完了の定義

• Story と Done の実装タスクを読み込み済み（テストタスクは除外）
• コードメトリクスを算出済み（循環的複雑度、関数／ファイルのサイズ）
• MCP Ref の検証を完了済み（OPT-、BP-、PERF- カテゴリ）
• ARCH- サブカテゴリ（LB、TX、DTO、DI、CEH、SES、EVENT）を確認済み。MNT- サブカテゴリ（DC、DRY、GOD、SIG、ERR）を確認済み
• 接頭辞と重要度を付けた問題を特定済み。MCP Ref／Context7 のソースを記載
• コード品質スコアを算出済み
• references/output_schema.md に従って出力を整形済み
• 調査結果をトラッカーのコメントに投稿済み

参照ファイル

• Git のスコープ検出：references/git_scope_detection.md
• コードメトリクス：references/code_metrics.md（しきい値と減点）
• ガイド：docs/guides/
• コンテキスト用テンプレート：references/templates/task_template_implementation.md
• クリーンコードのチェックリスト： references/clean_code_checklist.md
• リサーチツールのフォールバック：references/research_tool_fallback.md

---

Version: 5.1.0 Last Updated: 2026-03-15