ln-514-test-log-analyzer

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

テストログアナライザー

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

アプリケーションログを2層で分析します。Node.js スクリプトが収集と定量分析を担当し、AI が分類、品質評価、修正案の提示を行います。

入力

必須の入力はありません。現在のプロジェクトディレクトリで実行され、ログソースを自動検出します。

任意の args — 呼び出し元からの指示（自然言語）：時間範囲、想定されるエラー、テストのコンテキスト。例："review logs for last 30min, auth 401 errors expected from negative tests"。

目的と範囲

• アプリケーションログを分析します（テスト実行後、開発中、または必要に応じて）
• エラーを4つのカテゴリに分類します：実際のバグ、テスト上のアーティファクト、想定される動作、運用上の警告
• ログの品質を評価します：ノイズの多さ、完全性、レベルの正確さ、形式、構造化ロギング
• スタックトレースをソースファイルに対応付け、修正案を提示します
• 品質判定のために調査結果を報告します（実際のバグのみがブロック対象です）
• ステータスの変更やタスクの作成は行いません — 報告のみです

使用するタイミング

• 任意のプロジェクトでアプリケーションログを分析するとき（デフォルト：直近1時間）
• テスト実行後にエラーを分類し、ログの品質を評価するとき
• コンテキストを指定して呼び出すこともできます：Skill(skill: "ln-514-test-log-analyzer", args: "review last 30min, 401 errors expected")

ワークフロー

フェーズ 0：指示の解析

args が指定されている場合 — 時間範囲（デフォルト：1時間）、想定されるエラーのリスト、テストのコンテキストを抽出します。 args が指定されていない場合 — デフォルトを使用します（直近1時間、想定されるエラーなし）。

フェーズ 1：ログソースの検出とスクリプトの実行

対象プロジェクトに次のファイルが存在する場合は読み取ります：docs/project/infrastructure.md、docs/project/runbook.md

1. 対象プロジェクトに scripts/analyze_test_logs.mjs が存在するか確認します。存在しない場合は、references/scripts/analyze_test_logs.mjs からコピーします。
2. ログソースのモードを検出します（自動検出の優先順位：docker → file → loki）：

モード	検出方法	ソース
docker	docker compose ps で稼働中のコンテナが返される	docker compose logs --since {window}
file	.log ファイルが存在する、または tests/manual/results/ に出力がある	infrastructure.md に記載されたファイルパスまたは *.log の glob
loki	LOKI_URL 環境変数、または environment_state.json の observability セクション	Loki HTTP query_range API

3. スクリプトを実行します：node scripts/analyze_test_logs.mjs --mode {detected} [options]
4. ログソースが見つからない場合 → NO_LOG_SOURCES ステータスを返し、フェーズ 5 に進みます。

レベルに基づくエラー検出（重要）： エラーを検索する Loki クエリや grep コマンドを作成するときは、ログ行全体の「error」という単語とのテキスト照合ではなく、必ず解析済みのレベルフィールドで絞り込んでください。uvicorn.error のようなロガー名には名前の一部として「error」が含まれていますが、INFO レベルで記録されるため、テキスト照合では誤検出が発生します。

ログ形式	正しいエラーフィルター	誤ったフィルター
パイプ区切り（ts | LEVEL | ...）	| ERROR または | CRITICAL（レベルフィールドの位置に一致）	grep -i error（ロガー名にも一致）
Loki 構造化ログ	{service_name="X"} | level="ERROR" または | pattern による抽出	{service_name="X"} |= "error"
キーと値（level=ERROR msg=...）	level=ERROR または level=FATAL	|~ "(?i)error"
Docker ログ（ローカル）	grep -E '| ERROR | | CRITICAL '	grep -iE 'error|exception'

analyze_test_logs.mjs スクリプトは、構造化正規表現パーサーによってこの処理を正しく行います。これらのルールは、分析中に作成するその場限りの Loki／grep クエリに適用されます。

フェーズ 2：4 カテゴリのエラー分類

スクリプトの JSON 出力から、各エラーグループを分類します。

カテゴリ	対応	基準
実際のバグ	修正	想定外のクラッシュ、データ損失、パイプラインの破損
テスト由来	スキップ	テストスクリプトに起因するもの、意図的なエラーパスの検証
想定内の動作	スキップ	レート制限、入力検証、無効なトークンによる認証失敗
運用上の警告	監視	クロックのずれ、リソースの逼迫、一時的な利用不能

テスト由来のエラーを検出するヒューリスティック：

• テスト名に次の文字列が含まれる：invalid、error、fail、reject、unauthorized、forbidden、not_found、bad_request、timeout
• テストが 2xx 以外のステータスコード（4xx、5xx）を検証している
• テストで pytest.raises、expect(...).rejects、assertThrows、should.throw が使われている
• 回帰テストの出力におけるテスト実行時刻とエラーが相関している
• tests/manual/ スクリプトに一致するパターン

references/error_taxonomy.md に基づくエラー分類体系（9 カテゴリ：CRASH、TIMEOUT、AUTH、DB、NETWORK、VALIDATION、CONFIG、RESOURCE、UNSUPPORTED_API）。

フェーズ 3：ログ品質の評価

必読： references/error_taxonomy.md を読み込みます（レベルごとの基準表＋レベルの正確性に関するリファレンス）。

ステップ 1：設定されているログレベルを検出します。 次の順に確認します。

1. LOG_LEVEL / LOGLEVEL 環境変数（.env、docker-compose.yml、infrastructure.md）
2. フレームワークの設定：Python の logging.conf / Django の LOGGING / Node の LOG_LEVEL
3. デフォルト：検出できない場合は INFO とします

設定されているレベルによってログに出力されるレベルが決まりますが、各レベルにはそれぞれ固有のノイズしきい値があります。

ステップ 2：6 つの品質指標を評価します。

指標	確認内容	シグナル
ノイズの多さ	error_taxonomy.md のセクション 4 に記載されたレベルごとのノイズしきい値：TRACE（本番ではゼロ）、DEBUG（50% を超えて独占）、INFO（30% 超）、WARNING（全体の 1% 超）、ERROR（全体の 0.1% 超）	NOISY: {level} template "{msg}" at {ratio}%
完全性と追跡可能性	ログエントリーが欠落している重要な操作＋追跡可能性のギャップ（下表を参照）	MISSING: No log for {operation} / TRACEABILITY_GAP: {type} in {file}:{line}
レベルの正確性	error_taxonomy.md のセクション 4 に記載されたレベルごとの基準：内容、アンチパターン、ライブラリのルール	WRONG_LEVEL: should be {level}
構造化ロギング	trace_id/request_id/ユーザーコンテキストの欠落、非構造化プレーンテキスト	UNSTRUCTURED: lacks {field}
機密情報	ログメッセージ内の PII／シークレット／トークン／パスワード	SENSITIVE: {type} exposure
コンテキストの充実度	実用的なコンテキスト（order_id、user_id、operation）のないエラー	LOW_CONTEXT: lacks context

追跡可能性のギャップの検出 — INFO レベルのログがない操作を、ソースコードから検索します。

操作の種類	期待されるログ	追加する場所
受信リクエストの処理	リクエスト受信＋レスポンスステータス	ルートハンドラーの開始時／終了時
外部 API 呼び出し	リクエスト送信＋レスポンスステータス＋所要時間	HTTP クライアント呼び出しの前／後
DB 書き込み（INSERT/UPDATE/DELETE）	操作＋対象エンティティ＋件数	ORM／クエリ呼び出しの前／後
認証の判定	結果（許可／拒否）＋理由	認証チェックの後
状態遷移	旧状態 → 新状態＋トリガー	遷移箇所
バックグラウンドジョブ	開始＋完了／失敗＋所要時間	ジョブハンドラーの開始時／終了時
ファイル／リソース操作	オープン／クローズ＋パス＋サイズ	I/O 操作箇所

ログ形式の品質（references/log_analysis_output_format.md に基づく 10 項目のチェックリスト）：

#	基準	確認内容
1	デュアル形式	本番では JSON、開発では読みやすい形式
2	タイムスタンプ	一貫性があり、タイムゾーンを考慮している
3	レベルフィールド	存在し、大文字で表記されている
4	トレース／相関 ID	すべてのエントリーに存在し、非同期処理でも安全
5	サービス名	ソースのサービスを特定できる
6	ソースの位置	module:line ＋関数
7	追加コンテキスト	文字列補間ではなく構造化フィールド
8	PII のマスキング	パスワード、API キー、メールアドレスに対応している
9	ノイズの抑制	重複フィルター、サードパーティのログを抑制している
10	パース可能性	開発：パイプ区切り。本番：1 行ごとに有効な JSON

スコア：基準を満たした項目数 / 10。

フェーズ 4：スタックトレースのマッピング＋修正の推奨事項

実際のバグごとに、次の手順を実行します。

1. スタックトレースのフレームを抽出し、発生元のフレーム（node_modules/site-packages ではなく、プロジェクトコード内の最初のフレーム）を特定します
2. ソースファイルと行番号に対応付けます
3. 修正の推奨事項を作成します：変更内容、変更箇所、工数見積もり（S/M/L）

Sentry に着想を得た指標を使って優先順位を付けます：

• 発生量が多い（発生回数）、テスト後のリグレッション（新しいエラー）、影響の大きい経路（認証／決済／DB）、相関するトレース（サービス間の trace_id）

フェーズ 5：レポートを生成する

必ず読んでください： references/log_analysis_output_format.md を読み込みます。

## Test Log Analysis というヘッダーを付けて、レポートをチャットに出力します。以下を含めてください。

• シグナルテーブル（Real Bugs の件数、フィルタリングされた Test Artifacts、ログノイズのステータス、ログ形式スコア、ログ品質スコア）
• Real Bugs テーブル（優先度、カテゴリ、エラー、ソース、修正の推奨事項）
• フィルタリング済みテーブル（カテゴリ、件数、例）
• ログ品質の問題テーブル（項目、サービス、問題、推奨事項）
• ノイズレポートテーブル（件数、比率、サービス、レベル、テンプレート、対応）
• 機械可読ブロック ``（プログラムによる処理用）

フェーズ 6：メタ分析

任意の参照資料：ユーザーが実行後のメタ分析またはプロトコル形式の実行振り返りを求めた場合に限り、references/meta_analysis_protocol.md を読み込みます。

スキルタイプ：execution-worker。要求された場合は、すべてのフェーズが完了した後に実行します。

判定への反映

品質コーディネーターの正規化マトリクスの構成要素：

ステータス	対応先	ペナルティ
CLEAN	--	0
WARNINGS_ONLY	--	0
REAL_BUGS_FOUND	FAIL	-20
SKIPPED / NO_LOG_SOURCES	無視	0

ログ品質／形式の問題は情報提供のみを目的とし、品質判定には影響しません。Real Bugs のみがブロック要因になります。

重要なルール

• ステータスの変更やタスクの作成は禁止です。レポートのみを行ってください。
• Test Artifacts と Expected Behavior は常にフィルタリングし、バグとして数えないでください。
• ログ品質の問題は参考情報です。通知しますが、ブロックはしません。
• スクリプトは以下の状況にも適切に対応する必要があります。Docker がない、ログファイルがない、または Loki がない場合は NO_LOG_SOURCES を返します。
• コメント内の言語を維持します（EN/RU）。

ランタイムサマリー成果物

必ず読んでください： references/quality_summary_contract.md と references/quality_worker_runtime_contract.md を読み込みます。

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

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

呼び出しルール：

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

完了の定義

• スクリプトが対象プロジェクトの scripts/ にデプロイされている（またはすでに存在する）
• ログソースが検出され、スクリプトが実行されている（または NO_LOG_SOURCES が返されている）
• エラーが 4 つのカテゴリに分類され、Real Bugs が特定されている
• ログ品質が評価されている（6 つの項目と 10 項目の形式チェックリスト）
• Real Bugs のスタックトレースがソースファイルに対応付けられている
• シグナルテーブルと機械可読ブロックを含むレポートがチャットに出力されている

参照ファイル

• エラー分類： references/error_taxonomy.md
• 出力形式： references/log_analysis_output_format.md
• 分析スクリプト： references/scripts/analyze_test_logs.mjs

---

バージョン： 1.0.0 最終更新日： 2026-03-13