AIエージェントによるコードベースの誤動作を逆追跡して復旧する方法
makedreamJuly 30, 2026
0
Computing/SoftwareRelated Video
4:58Mindwalk：コードベース全体を3Dマップで可視化
Better Stack
Comments (0)
Log in to leave a comment
No posts yet
makedream4:58makedream4:58Better Stack
Log in to leave a comment
No posts yet
10万行を超えるバックエンドリポジトリにClaude CodeやCodexのようなAIエージェントを導入してみると、最初はそのスピードに感嘆する。しかしある瞬間、プロンプトが数行誤って入力された途端、AIは境界線を突破し、共通ユーティリティや環境設定ファイルにまで手を加えてしまう。セッションログは数メガバイト単位で膨れ上がり、ビルドは落ち、原因ファイルを探そうとGit Diffを1時間以上眺めていると、「いっそのこと最初から自分で書いたほうがマシだった」という思いが込み上げてくる。
エージェントに自律性を与えつつ、不要なファイルの破損を防ぐには、明確なハード隔離と可視化されたトレース追跡体系が必要だ。
自然言語の指示ファイルであるCLAUDE.mdや.aiignoreは、コンテキストウィンドウが長くなるとエージェントに回避されがちだ。プロンプト段階でのリクエストはあくまで推奨事項に過ぎないため、文脈を見失った瞬間にエージェントのツール実行は容赦なく垣根を越えてしまう。
エージェントの介入を物理的に遮断するには、プロジェクトルートに決定論的な権限制御エンジンである.claude/settings.jsonを直接配置する必要がある。
`json
{
"permissions": {
"deny": [
"Edit(src/core/config/)",
"Edit(src/shared/utils/)",
"Read(./.env*)",
"Bash(rm -rf *)"
],
"ask": [
"Edit(src/api/v1/legacy/**)"
]
}
}
`
明示的な遮断ルールを設定した後は、ファイルシステムレベルでももう一度ロックをかけておく方が安全だ。プロダクションビルドスクリプトやセキュリティキーファイルは、OSレベルで書き込み権限を剥奪しておくのがスマートだ。
.claude/settings.jsonを作成する。permissions.deny配列に環境設定、共通ユーティリティのパス、破壊的なBashコマンドを登録する。chmod 444 .env*コマンドを実行し、プロセスの書き込み権限を遮断する。このように権限を制御しておけば、AIが突如共通モジュールを修正したことで発生するビルドエラーを大幅にカットできる。
開発者個人のローカル環境だけにセッションログ(.jsonl)を置いておくと、後からサイドエフェクトが発生した際に原因究明が困難になる。PRを提出するタイミングでセッションのトレースを圧縮して検証するようにGitHub Actionsワークフローを構築する。
`yaml
name: AI Agent Session Audit & Risk Analysis
on:
pull_request:
types: [opened, synchronize]
jobs:
audit-session:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Mindwalk Telemetry Extractor
run: |
docker run --rm -v ${{ github.workspace }}:/workspace \
cosmtrek/mindwalk:v0.1.0 parse --log-dir=./.claude/sessions --out=telemetry.json
- name: Run Deterministic Repo Audit
id: repo_audit
run: |
curl -sSL https://github.com/aletheore/releases/download/v1.0/aletheore -o aletheore
chmod +x aletheore
./aletheore audit --telemetry=telemetry.json --max-allowed-depth=3
- name: Upload Mindwalk 3D Visual Artifact
uses: actions/upload-artifact@v4
with:
name: mindwalk-3d-trace-${{ github.event.pull_request.number }}
path: telemetry.json
`
Rustベースの分析エンジンやTree-sitterを組み合わせてエージェントのスコープ逸脱の有無を検査すれば、許容範囲を外れた上位モジュールの修正時にCIビルドを即座に失敗へロールバックできる。
変更リスク度は、単なるコードの行数ではなくノードの結合度を中心に計算する方式が有効だ。
ここでは修正されたファイル数であり、は変更されたノードの平均3D結合度である。閾値を超えた場合にSlack通知で3D可視化マップのリンクを送信するように設定しておけば、レビュアーがリスク度を即座に把握できる。
エージェントがコードベースを荒らしてしまった時は、コミット全体を破棄するのではなく、タイムラインを追跡して汚染されたファイルのみを選別復旧すべきだ。誤動作を開始した特定の時間帯を抽出したら、jqを使ってJSONLログから該当時点のプロンプトと推論パスを抜き出す。
`bash
jq -c 'select(.timestamp >= "2026-07-11T14:20:00Z" and .timestamp <= "2026-07-11T14:25:00Z") |
{timestamp: .timestamp, prompt: .payload.prompt, tool_use: .payload.tool_use, thinking: .payload.thinking}'
./.claude/sessions/session_abc123.jsonl
`
原因を確認できたら、復旧作業は以下の3段階に分けて進める。
git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)git clean -fd -- src/unwanted_generated_dir/)この方法を使えば、正常に動作しているコードまで失ってしまう事態を防ぎ、破損したファイルだけをスマートに復元できる。
モノレポ環境でノードが数万個に増えると、可視化ツール自体もクラッシュしてしまう。ブラウザの動作が重くなるとデバッグの意欲も削がれる。不要なディレクトリをレンダリング対象から外すには、mindwalk.config.jsonの除外フィルターをしっかり設定しておく必要がある。
`json
{
"visualization": {
"excludePatterns": [
"/node_modules/",
"/vendor/",
"/.git/",
"/dist/",
"/coverage/",
"/*.log",
"/*.pb.go"
],
"maxDepth": 5,
"groupingStrategy": "directory-segmented"
}
}
`
最後に、可視化パイプラインや分析ツールをバックグラウンドのDockerコンテナで起動する際は、リソース割当量を制限しておかないとローカルIDEがフリーズしてしまう。
mindwalk.config.jsonを作成し、依存関係ディレクトリのノードを可視化対象から除外する。--cpus="1.5"および--memory="2g"オプションを指定する。--nice=19フラグを付与し、CPU優先度を最低に下げる。