ln-627-diagnosability-auditor

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

診断可能性監査担当（L3 ワーカー）

種類： L3 ワーカー

運用担当者がインシデントを診断できるかを監査する専門ワーカーです。

目的と範囲

• 診断可能性（カテゴリー 10：優先度中）を監査します
• 構造化ログ、メトリクス、トレース、相関 ID、ログレベルを確認します
• ADD_DIAGNOSTIC_SIGNAL、STRUCTURE_LOGS、または PROPAGATE_CORRELATION を出力します
• コンプライアンススコア（X/10）を算出します

入力

必須の読み込み： references/audit_worker_core_contract.md と references/mcp_tool_preferences.md を読み込みます。 ツールの方針：ホストの AGENTS.md が適用範囲外となる独立したサブエージェントとして実行される場合があるため、ファイルの読み取り、検索、編集にはまず hex-line MCP を使用します。MCP の動作が不明な場合に限り、references/mcp_integration_patterns.md を読み込みます。

技術スタック、フレームワーク、コードベースのルート、output_dir を含む contextStore を受け取ります。

トレース、呼び出しパス、またはファイル間参照によって監査の質が大きく向上する場合は、まず hex-graph を使用します。利用可能な場合、ローカルコードの読み取りにはまず hex-line を使用します。MCP が利用できない、未対応、またはインデックス化されていない場合は、組み込みの Read/Grep/Glob/Bash を使用して続行し、レポートにフォールバックしたことを記載します。

ワークフロー

検出方針：2 層検出（候補のスキャン後にコンテキストを検証）を使用します。検証方法が曖昧な場合に限り、references/two_layer_detection.md を読み込みます。

1. コンテキストと output_dir を解析します
2. プロジェクトの種類を判定します（レイヤー 2 の事前確認）： Web サービス（すべての確認が適用）、CLI ツール（ヘルスチェック／プローブは対象外）、ライブラリ（ほとんどの確認は任意）のいずれかを判定します。該当する確認項目をそれに応じて調整します。
3. 可観測性のパターンを確認します（レイヤー 1：grep）
4. 候補ごとにコンテキストを分析します（レイヤー 2）：
   • 構造化ログ：ライブラリ（ログ出力なしでも問題ありません）か、サービス（ログ出力が必要）かを確認します
   • リクエストトレース：モノリスでは必要性が低く、マイクロサービスでは重要です
5. 確認済みの検出結果を収集します
6. スコアを算出します
7. レポートを作成： references/templates/audit_worker_report_template.md に従って完全な Markdown レポートをメモリ上で作成し、単一の Write 呼び出しで {output_dir}/ln-627--global.md に書き込みます
8. 要約を返す： 最小限の要約を返します

監査ルール

1. 構造化ログ

検出：

• console.log（非構造化）を grep で検索します
• 適切なロガー（winston、pino、logrus、zap）が使用されているか確認します

重大度：

• 中： 本番コードで console.log を使用
• 低： 開発コードで console.log を使用

推奨事項： 構造化ロガー（winston、pino）を使用します

工数： M（ロガーを追加し、呼び出しを置き換える）

2. 相関 ID

検出：

• リクエスト ID／相関 ID ミドルウェアを確認します
• ID がログに記録され、送信先への呼び出しに伝播されることを確認します

重大度：

• 中： リクエストを処理するサービスに相関 ID がない

推奨事項： リクエスト ID ミドルウェアを追加し、構造化ログに相関 ID を含めます

工数： M

3. メトリクス収集

検出：

• Prometheus クライアント、StatsD、CloudWatch を確認します
• メトリクスの記録処理（histogram、counter）を grep で検索します

重大度：

• 中： メトリクス計測がない

推奨事項： Prometheus メトリクスを追加します

工数： M（コードを計測）

4. リクエストトレース

検出：

• ログ内の相関 ID を確認します
• トレースの伝播（OpenTelemetry、Zipkin）を確認します

重大度：

• 中： 相関 ID がない（分散システムのデバッグが困難）

推奨事項： リクエスト ID ミドルウェアを追加します

工数： M（ミドルウェアを追加し、ID を伝播）

5. ログレベル

検出：

• ロガーがレベル（info、warn、error、debug）に対応しているか確認します
• 適切なレベルが使用されているか確認します

重大度：

• 低： エラーログしかなく、可視性が不十分

推奨事項： info／debug ログを追加します

工数： S（ログ文を追加）

スコアリングアルゴリズム

必須の読み込み： references/audit_scoring.md を読み込みます。

出力形式

必ずお読みください： references/templates/audit_worker_report_template.md を読み込んでください。

references/audit_summary_contract.md に従って JSON サマリーを書いてください。管理モードでは、呼び出し元から runId と summaryArtifactPath の両方が渡されます。スタンドアロンモードでは、ワーカーが共有コントラクトに従って、独自の実行スコープのアーティファクトパスを生成します。

{output_dir}/ln-627--global.md に、category: "Diagnosability" と、structured_logging、correlation_ids、metrics_collection、request_tracing、log_levels のチェックを含むレポートを書いてください。

references/audit_summary_contract.md に従ってサマリーを返してください。

summaryArtifactPath がない場合は、スタンドアロンのランタイムサマリーを .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json に書き込み、必要に応じて同じサマリーを構造化出力にも出力してください。

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-627--global.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

参照ファイル

• 監査出力スキーマ： references/audit_output_schema.md

重要なルール

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

• 自動修正は禁止： 報告のみを行い、ログやエンドポイントを追加しないでください
• フレームワークを考慮した検出： プロジェクトの技術スタックに合わせてパターンを調整してください（Node では winston/pino、Go では logrus/zap など）
• 現実的な作業量： S = 1 時間未満、M = 1～4 時間、L = 4 時間超
• 除外項目： console.log の検出ではテストファイルを除外し、開発専用スクリプトも除外してください
• コンテキストに応じた重大度： 本番コード内の console.log は MEDIUM、開発ユーティリティ内では LOW
• 独自の観点： 診断シグナルのみを監査してください。Liveness/readiness プローブとシャットダウンの動作は、ライフサイクル／設定監査の対象です。
• 必要なアクション： 各指摘には ADD_DIAGNOSTIC_SIGNAL、STRUCTURE_LOGS、PROPAGATE_CORRELATION のいずれかを使用してください。

完了の定義

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

• contextStore が解析されている（技術スタック、フレームワーク、output_dir）
• 5 つのチェックがすべて完了している（構造化ログ、相関 ID、メトリクス、リクエストトレーシング、ログレベル）
• 重大度、場所、作業量、アクション、推奨事項を含む指摘が収集されている
• references/audit_scoring.md に従ってスコアが算出されている
• {output_dir}/ln-627--global.md にレポートが書き込まれている（単一の Write 呼び出しによるアトミックな書き込み）
• コントラクトに従ってサマリーが書き込まれている

---

バージョン： 3.0.0 最終更新日： 2025-12-23