ln-643-api-contract-auditor

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリからの相対パスです。

API コントラクト監査担当（L3 ワーカー）

タイプ： L3 ワーカー

API コントラクト、サービス境界におけるメソッドシグネチャ、DTO の使用パターンを監査する専門ワーカーです。

目的と範囲

• アーキテクチャレベルで API コントラクト（サービス境界、レイヤー分離）を監査します
• レイヤーの漏出、DTO パターン、エラーコントラクトの一貫性を確認します
• 4 つのスコア（準拠性、完全性、品質、実装）を含む構造化分析を返します

対象外：

• コードの重複（同じ DTO の形状が繰り返される、同じマッピングロジック、同じバリデーション）
• アーキテクチャ境界に関する指摘のみを報告します（誤ったレイヤー、コントラクトの欠落）

入力

- pattern: "API Contracts"     # Pattern name
- locations: string[]          # Service/API directories
- adr_reference: string        # Path to related ADR
- bestPractices: object        # Best practices from MCP Ref/Context7
- output_dir: string           # e.g., ".hex-skills/runtime-artifacts/runs/{run_id}/audit-report"

# Domain-aware (optional)
- domain_mode: "global" | "domain-aware"   # Default: "global"
- current_domain: string                   # e.g., "users", "billing" (only if domain-aware)
- scan_path: string                        # e.g., "src/users/" (only if domain-aware)

ワークフロー

フェーズ 0：参照資料の読み込み

必ず読むこと： references/detection_patterns.md と references/mcp_tool_preferences.md を読み込みます。

検出ポリシー：2 層の検出（候補のスキャン、その後のコンテキスト検証）を使用します。検証方法が曖昧な場合に限り、references/two_layer_detection.md を読み込みます。 ツールポリシー：ホストの AGENTS.md が対象範囲外となる独立したサブエージェントとして実行される場合があるため、ファイルの読み取り、検索、編集には、まず hex-line MCP を使用します。MCP の動作が不明確な場合に限り、references/mcp_integration_patterns.md を読み込みます。

シンボルまたは参照の分析によってコントラクトに関する指摘の精度が大幅に向上する場合は、まず hex-graph を使用します。利用可能な場合、ローカルコードの読み取りにはまず hex-line を使用します。MCP が利用できない、サポートされていない、またはインデックス化されていない場合は、組み込みの Read/Grep/Glob/Bash を使用して続行し、レポートにフォールバックしたことを記載します。

フェーズ 1：サービス境界の特定

scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root

1. Find API layer: Glob("**/api/**/*.py", "**/routes/**/*.ts", "**/controllers/**/*.ts", root=scan_root)
2. Find service layer: Glob("**/services/**/*.py", "**/services/**/*.ts", root=scan_root)
3. Find domain layer: Glob("**/domain/**/*.py", "**/models/**/*.py", root=scan_root)
4. Map: which services are called by which API endpoints

フェーズ 2：コントラクトの分析（5 つのルール）

必ず読むこと： 各ルールに対応する言語別の Grep パターンについて、references/detection_patterns.md を読み込みます。

#	ルール	深刻度	確認内容
1	レイヤーの漏出	HIGH/MEDIUM	サービス／ドメインが HTTP 型（Request、parsed_body、headers）を受け入れている
2	DTO の欠落	MEDIUM/LOW	4 つ以上のパラメーターが、DTO にまとめられず 2 つ以上のメソッドで繰り返されている
3	エンティティの漏出	HIGH/MEDIUM	レスポンス DTO を使わずに ORM エンティティを API から返している。次の場合は深刻度を下げます：外部の利用者がいない内部 API の場合は LOW
4	エラーコントラクト	MEDIUM/LOW	同じサービス内でエラーパターン（raise と return None）が混在している
5	冗長なオーバーロード	LOW/MEDIUM	_with_／_and_ という接尾辞の異なるメソッドの組み合わせで、パラメーターが 1～2 個異なるもの
6	アーキテクチャ上の誠実性	HIGH/MEDIUM	読み取りを示す名前の関数（get_/find_/check_/validate_/is_/has_）の本体に書き込みの副作用が含まれている。除外項目は references/ai_ready_architecture.md を参照

スコープの境界： 重複に関する指摘はスキップします。アーキテクチャ境界に関する指摘のみを報告します。

フェーズ 3：4 つのスコアを算出

準拠性スコア（0-100）：

基準	点数
レイヤーの漏出がない（サービス内に HTTP 型がない）	+35
エラー処理パターンに一貫性がある	+25
プロジェクトの命名規則に従っている	+10
読み取りを示す名前の関数に隠れた副作用がない	+10
API へのエンティティの漏出がない	+20

完全性スコア（0-100）：

基準	点数
すべてのサービスメソッドに型付きパラメーターがある	+30
すべてのサービスメソッドに型付き戻り値がある	+30
複雑なデータに DTO が定義されている	+20
エラー型が文書化または型付けされている	+20

品質スコア（0-100）：

基準	点数
サービスメソッドにブール値フラグのパラメーターがない	+15
書き込み処理を隠す不透明な戻り値の型がない	+10
DTO を使わずにパラメーターが 5 個を超えるメソッドがない	+25
モジュール全体で命名に一貫性がある	+25
冗長なオーバーロードがない	+25

実装スコア（0-100）：

基準	点数
DTO／スキーマが存在し、使用されている	+30
型注釈がある	+25
境界でバリデーションを行っている（Pydantic、Zod）	+25
API レスポンス DTO がドメインから分離されている	+20

フェーズ 3.5：スコアの計算

必ず読むこと： references/audit_worker_core_contract.md と references/audit_scoring.md を読み込みます。

主要スコアには、ペナルティ方式の計算式を使用します（すべてのワーカーで共通です）。

penalty = (critical x 2.0) + (high x 1.0) + (medium x 0.5) + (low x 0.2)
score = max(0, 10 - penalty)

診断用サブスコア（それぞれ 0～100）は個別に計算し、診断目的に限り AUDIT-META に報告します。

フェーズ 4：レポートの作成

必ず読むこと： references/templates/audit_worker_report_template.md を読み込みます。

references/audit_summary_contract.md に従って JSON サマリーを作成します。管理モードでは、呼び出し元から runId と summaryArtifactPath の両方が渡されます。スタンドアロンモードでは、共通コントラクトに従って、ワーカーが実行単位の成果物パスを生成します。

# Build markdown report in memory with:
# - AUDIT-META (extended: score [penalty-based] + diagnostic score_compliance/completeness/quality/implementation)
# - Checks table (layer_leakage, missing_dto, entity_leakage, error_contracts, redundant_overloads)
# - Findings table (issues sorted by severity)
# - DATA-EXTENDED: issues array with principle + domain fields (for cross-domain aggregation)

IF domain_mode == "domain-aware":
  Write to {output_dir}/643-api-contract-{current_domain}.md
ELSE:
  Write to {output_dir}/643-api-contract.md

フェーズ 5：サマリーの返却

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/643-api-contract-users.md
Score: 6.75/10 (C:65 K:70 Q:55 I:80) | Issues: 4 (H:2 M:1 L:1)

重要なルール

すでに読み込まれている references/audit_worker_core_contract.md を適用します。

• アーキテクチャレベルのみ： 内部実装ではなく、サービス境界に焦点を当てます
• スコア付けの前に読む： 実際のサービスコードを読まずにスコアを付けてはいけません
• スコープ境界： 重複に関する指摘はスキップします
• 検出パターン： detection_patterns.md にある言語固有の Grep を使用します
• ドメインを考慮： domain_mode="domain-aware" の場合は scan_path のみをスキャンし、指摘に domain を付けます
• 独自の観点： サービス／API 境界のコントラクトのみを監査します。コードの重複、パッケージの健全性、依存関係のトポロジー、ランタイム運用は監査しません
• 必要な対応： すべての指摘で ADD_DTO、STOP_ENTITY_LEAK、STANDARDIZE_ERROR_CONTRACT のいずれかを使用します

完了条件

すでに読み込まれている references/audit_worker_core_contract.md を適用します。

• サービス境界（API、サービス、ドメインの各レイヤー）を特定済み
• メソッドシグネチャを抽出し、分析済み
• detection_patterns.md を使用して、5 つのルールをすべて確認済み
• スコープ境界を適用済み（重複に関する指摘なし）
• 根拠を添えて 4 つのスコアを算出済み
• 重要度、場所、提案、工数を含めて問題を特定済み
• ドメインを考慮する場合：指摘に domain フィールドを付与済み
• レポートを {output_dir}/643-api-contract[-{domain}].md に書き込み済み（単一の Write 呼び出しによるアトミックな書き込み）
• コントラクトに従ってサマリーを書き込み済み

参照ファイル

• 検出パターン：references/detection_patterns.md
• スコアリングルール：references/audit_scoring.md

---

バージョン： 2.0.0 最終更新日： 2026-02-08