こんにちは、みねです。
「AIワーカーがまた失敗した」——で、何が原因だったか分かりますか？
ログを見ても「何をやったか」が追えない。プロンプトは消えた。コマンド履歴もない。これでは改善サイクルが回りません。
今回は最小限の観測を仕込んで、「失敗から学べる仕組み」を作ります。
この記事でできるようになること
- AIワーカーの行動を「後から追える」状態にできる
- CI落ちを5つのカテゴリに分類し、次スプリントで改善できる
- 観測のオーバーヘッドを最小限に抑えながら、必要な情報を取れる
対象読者
- AIワーカーを使っているが「なぜ失敗したか」が分からないことがある
- 改善のためのデータが欲しいが、大げさな監視システムは入れたくない
- 「ログを見れば分かる」状態を作りたい
この記事でやらないこと
- eBPF/OpenTelemetryの詳細な実装手順
- 本番環境の監視システム構築
1. eBPFで何が嬉しいのか
1.1 低オーバーヘッド観測
eBPF（extended Berkeley Packet Filter）は、Linuxカーネルレベルでプログラムを動かし、低オーバーヘッドで観測を行う技術です。
text
┌─────────────────────────────────────────────────┐
│ 従来の観測 │
├─────────────────────────────────────────────────┤
│ アプリケーション │
│ ↓ ログ出力 │
│ ログエージェント │
│ ↓ 送信 │
│ ログサーバー │
│ │
│ → オーバーヘッド大、設定複雑 │
└─────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────┐
│ eBPFの観測 │
├─────────────────────────────────────────────────┤
│ Linuxカーネル（eBPFプログラム） │
│ ↓ システムコール/ネットワーク/ファイル操作 │
│ 直接観測 │
│ │
│ → 低オーバーヘッド、アプリ改修不要 │
└─────────────────────────────────────────────────┘
1.2 AIワーカー文脈での価値
eBPFの「アプリを改修せずに観測できる」という特性は、AIワーカーの観測に向いています：
- AIクライアントのソースコードを触らずに、実行コマンドを追跡
- ファイルアクセスパターンを記録
- ネットワーク通信（API呼び出し）を観測
2. "AI運用ログ"はアプリログより先に効く
2.1 何を観測すべきか
text
┌────────────────────────────────────────────────┐
│ AI運用ログの優先順位 │
├────────────────────────────────────────────────┤
│ 1. プロンプト / handoff.md │
│ → 何を依頼したか │
│ │
│ 2. コマンド履歴 │
│ → 何を実行したか │
│ │
│ 3. ファイル変更 │
│ → 何を書いたか │
│ │
│ 4. CI結果 │
│ → 成功/失敗、エラーメッセージ │
│ │
│ 5. 復旧アクション │
│ → 失敗後に何をしたか │
└────────────────────────────────────────────────┘
2.2 最小の収集形式
大げさなシステムは不要。ai/metrics.md に人間が読める形で記録します：
markdown
# AI Worker Metrics Log
## 2026-02-07
### Task #123: Fix login timeout
| Phase | Timestamp | Action | Result |
| :------ | :-------- | :--------------------- | :------------- |
| Plan | 10:00 | handoff.md作成 | OK |
| Execute | 10:15 | src/api/auth.ts 編集 | OK |
| Execute | 10:20 | pnpm test | FAIL (timeout) |
| Retry | 10:25 | src/api/auth.ts 再編集 | OK |
| Execute | 10:30 | pnpm test | PASS |
| PR | 10:35 | PR作成 | OK |
**失敗原因**: 初回の修正でkeep-alive値の単位を間違えた（秒→ミリ秒）
**改善アクション**: handoffに単位を明示するルール追加
3. CI落ち分類のテンプレ
3.1 5つのカテゴリ
text
┌─────────────────────────────────────────────────┐
│ CI落ちの分類 │
├──────────────┬──────────────────────────────────┤
│ カテゴリ │ 例 │
├──────────────┼──────────────────────────────────┤
│ 型エラー │ TypeScript: TS2345, TS2322 │
│ 依存エラー │ Module not found, Version mismatch│
│ テスト失敗 │ Assertion failed, Timeout │
│ 環境エラー │ Docker build fail, Permission denied│
│ 仕様誤解 │ Issue内容と実装の不一致 │
└──────────────┴──────────────────────────────────┘
3.2 分類の自動化（簡易版）
bash
#!/bin/bash
# ai/scripts/classify-ci-failure.sh
LOG_FILE=$1
if grep -q "TS[0-9]\{4\}" "$LOG_FILE"; then
echo "type_error"
elif grep -q "Module not found\|Cannot find module" "$LOG_FILE"; then
echo "dependency_error"
elif grep -q "AssertionError\|Expected.*Received" "$LOG_FILE"; then
echo "test_failure"
elif grep -q "Permission denied\|EACCES\|Docker" "$LOG_FILE"; then
echo "environment_error"
else
echo "unknown"
fi
3.3 週次集計テンプレ
markdown
# CI Failure Summary - Week of 2026-02-03
| カテゴリ | 件数 | 割合 | トレンド |
| :--------- | :--- | :--- | :------- |
| 型エラー | 3 | 30% | ↓ |
| 依存エラー | 2 | 20% | → |
| テスト失敗 | 4 | 40% | ↑ |
| 環境エラー | 0 | 0% | → |
| 仕様誤解 | 1 | 10% | → |
## 今週の改善アクション
- [ ] テスト失敗が増加 → handoffにテスト対象の明示を追加
- [ ] 型エラー減少 → tsconfig strictモードの効果確認
4. 次スプリントで改善する「チェックリスト化」
4.1 失敗パターン → ルール化
text
┌─────────────────────────────────────────────────┐
│ 失敗 → ルール化のサイクル │
├─────────────────────────────────────────────────┤
│ │
│ ①失敗発生 │
│ ↓ │
│ ②分類（5カテゴリ） │
│ ↓ │
│ ③根本原因分析（なぜ起きた？） │
│ ↓ │
│ ④再発防止策（handoff/rules/CI） │
│ ↓ │
│ ⑤次スプリントで検証 │
│ │
└─────────────────────────────────────────────────┘
4.2 改善チェックリスト
markdown
# AI Worker Improvement Checklist
## 型エラー対策
- [ ] handoffに「TypeScript strictモードで検証」を追加
- [ ] 変更前にpnpm typecheckを必須化
## 依存エラー対策
- [ ] lockファイル変更禁止を明示
- [ ] 依存追加は人間承認必須
## テスト失敗対策
- [ ] 既存テスト実行を変更前に必須化
- [ ] 新規テスト追加の最小ラインを定義
## 環境エラー対策
- [ ] Dockerビルドをローカルで必須化
- [ ] 環境変数の一覧を参照可能に
## 仕様誤解対策
- [ ] handoffに「不明点」セクション追加
- [ ] 仮定を明示して人間に確認依頼
5. 注意：全部取ろうとすると死ぬ
[!WARNING] 観測のオーバーヘッドに注意 「とりあえず全部ログ」は、ストレージ・パフォーマンス・セキュリティすべてに悪影響
5.1 最小の科学で回す
text
┌────────────────────────────────────────────────┐
│ 観測の段階的拡張 │
├────────────────────────────────────────────────┤
│ Week 1: 必須のみ │
│ - CI結果（pass/fail） │
│ - 失敗時のエラーメッセージ │
│ │
│ Week 2: handoff追加 │
│ - プロンプト / handoff.md │
│ - 変更ファイル一覧 │
│ │
│ Month 2: 詳細追加 │
│ - コマンド履歴 │
│ - 実行時間 │
│ │
│ 必要に応じて: eBPF/OTel連携 │
│ - システムコールトレース │
│ - 分散トレーシング │
└────────────────────────────────────────────────┘
5.2 取らないもの
- セキュリティに関わる情報（トークン、認証情報）
- 個人情報を含むログ
- 再現に不要な詳細（全コマンドの標準出力など）
測れる仮説と検証
仮説
- H1: CI落ちを分類できると、次スプリントでCI pass rateが改善する
- H2: 観測の自動化で、Review burdenが下がる（「何やったか」が自動で追える）
KPI
| 指標 | 測定方法 | 目標 |
|---|---|---|
| CI pass rate | CI履歴 | 週ごとに改善 |
| 分類カバー率 | unknown / 総件数 | unknown < 10% |
| Review burden | レビュー指摘の「何をした？」系質問 | 0件 |
今日から一歩
まずは今日、次のCIエラーを5カテゴリのどれかに分類してください。
bash
# 最後のCI失敗ログを取得
gh run view --log-failed | head -100
# 分類を記録
echo "2026-02-07: #123 - test_failure - timeout設定ミス" >> ai/ci-failures.log
1週間後、パターンが見えてきます。そこから改善が始まります。
シリーズ記事
- AI自動運転を"ベンチマーク思考"で検証する
- MCPで"運転席と作業者"を分離して事故率を下げる
- LLM/AI開発のObservabilityを"eBPF × OTel"で最小実装する（本記事）
- WASM Component Modelで"安全な拡張"を作る
- 2026年の「AIコーディング自動運転」最前線
関連記事
- AIエージェントの可観測性と障害解析 — eBPF が見る OS/カーネル層と対になる「アプリ層の観測（トレース / 構造化ログ / error taxonomy）」をどう設計するかを整理しています。
参考リンク
シリーズ全体に戻る: 親記事
