agent-loop

エビデンスに基づく自律開発ループツールキット。決定論的なエージェントループ評価器の実行、機械エビデンスの収集、CI上での有界LLM修復ループの起動、そして無限ループではなく人間へのハンドオフで停止するために必要なファイルをまとめたリポジトリです。

目的

LLM にコード修正を任せる自律開発には、放置できない3つの構造的リスクがあります。

AI の自己申告問題 — LLM は「テストが通りました」「修正しました」と、実際には確認していないことを報告できてしまう。自己申告をそのまま信じる自動化は、壊れたコードをグリーン扱いでマージする。
無限ループ問題 — 修復ループに上限がないと、同じ失敗を延々と繰り返してトークンと時間を浪費する。モデル価格の変動やタスク量の増加でコストは静かに膨らむ。
権限の暴走問題 — 認証・課金・DB migration・CI設定のような高リスク変更を、AI が「安全だ」と自己判断してマージしてしまう。

agent-loop はこれらに対して、判定・停止・マージ可否をすべて決定論的なツールと人間に握らせ、LLM にはコード修正だけを任せるという役割分離で答えます。成功条件は「動き続けること」ではなく、「機械エビデンスで PASS を証明するか、証拠を揃えて人間にハンドオフするか」のどちらかで必ず停止することです。

特徴

決定論的評価器 — PASS/FAIL はハードゲートの機械判定。LLM の自己申告は claim（未検証の主張）として扱い、エビデンスにしない
機械エビデンス台帳（Evidence Ledger） — コマンド・exit code・ログ・git snapshot・PR状態を JSON 台帳に source: machine として記録
有界修復コントローラー — 試行回数・同一失敗の繰り返し・実行時間・トークン/コスト予算のいずれかで必ず停止し、handoff.md で人間に引き継ぐ
フェイルクローズド PR ガード — チェック未設定・保留・SKIPPED も失敗として扱い、GitHub の機械可読状態が安全を証明するまでマージしない
高リスク変更の機械分類 — 認証・課金・migration・secrets・CI/CD・インフラに触れる PR は人間レビュー承認を必須化（パスベース、LLM 判断なし）
トークン/コスト計測と予算ゲート — 使用量を台帳に記録し、フェーズ別レポートと予算超過時の強制停止に使う
変更スコープゲート — 許可パス・変更ファイル数・diff行数を宣言し、逸脱を機械検証で FAIL にする
回帰検出 — JUnit XML / git worktree の機械比較のみを回帰エビデンスとして認める
監査可能性 — AI判断ログ・ナレッジ資産・HTMLダッシュボードで「何が起きたか」「なぜそうしたか」を後から追える
軽量 — ランタイム依存ゼロ（Python 標準ライブラリのみ）。uv tool install 一発で任意のリポジトリに使える

Agent Loop とは

このツールキットが実装する「agent loop」は、LLMにコード修正を任せつつ、成否の判定・証拠の収集・停止の判断はすべて決定論的なツールが行う閉ループです。

        ┌──────────────────────────────────────────────────────┐
        │                    Controller（決定論）                │
        │                                                      │
  init  │  1. 検証パス: required_checks を自分で実行            │
 ───────┼──►   （コマンド・exit code・stdout/stderr を台帳に記録）│
        │  2. git snapshot を取得（HEAD・dirty・変更ファイル）    │
        │  3. Evaluator が台帳をハードゲートで評価               │
        │       PASS ──► 停止（成功）                           │
        │       FAIL ──► 4 へ                                  │
        │  4. 停止条件チェック:                                  │
        │       - 最大試行回数（max_attempts）                  │
        │       - 同一失敗の繰り返し（failure fingerprint）      │
        │       - 実行時間上限（max_runtime_minutes）            │
        │       - トークン/コスト予算（max_total_tokens 等）      │
        │       - 修復コマンド未設定                             │
        │       いずれか超過 ──► 人間ハンドオフ（handoff.md）     │
        │  5. Evaluator の repair_tasks から修復プロンプト生成    │
        │  6. LLM 修復コマンドを1回だけ実行 ──► 1 に戻る          │
        └──────────────────────────────────────────────────────┘

役割分担と信頼モデル

役割	担当	信頼レベル
チェック実行・ログ保存・git snapshot	Controller / CI（`agent_loop_capture.py`）	source of truth（`source: machine`）
PASS/FAIL 判定	Evaluator（`agent_loop_evaluator.py`）	決定論的ハードゲート
コード修正・原因仮説・台帳アノテーション	LLM 修復エージェント	信頼しない（claim 扱い）
マージ可否	PR guard（GitHub の機械可読な PR/check 状態）	fail-closed
waiver・高リスク判断・最終責任	人間	承認者として必須（AI は承認者になれない）

LLM は「なぜ失敗したか」の解釈と「どう直すか」の実装だけを担当します。LLM が「直りました」と言っても、コントローラーが required checks を再実行し、evaluator が新しい clean な git snapshot と一致する machine evidence を確認するまで PASS になりません。

Evaluator のハードゲート（抜粋）

check_execution_rate / declared_checks_executed — 宣言した必須チェックが exit 0 + ログ実在 + 最新 HEAD 一致で実行されたか
evidence_freshness — 最新 git snapshot が clean で、チェックの commit が一致するか
claim_verification / unsupported_completion_claims — 完了クレームが解決可能な証拠を持つか
fix_responsiveness / recheck_rate — 指摘の修正と再チェックが証拠付きか
finding_waivers_approved — accepted_risk/deferred に非AIの承認者と理由があるか
regression_evidence — 回帰データが機械計算で最新 HEAD と一致するか

1つでも落ちれば verdict は FAIL。スコアは参考値であり、ゲートを代替しません。

停止と人間ハンドオフ

ループは必ず有界です。停止時には agent-loop-handoff.md（停止理由・blocking failures・repair tasks・トークン/コスト使用量）を出力し、PR コメントとナレッジ資産（.agent-loop/knowledge/handoffs/）にも残します。「動き続けるより、証拠を揃えて人間に渡す」ことが成功条件です。

設計上の工夫

自己申告と証拠の分離

評価器は AI の発言をすべて claim として扱い、機械が収集したエビデンス（source: machine）だけを証拠として認めます。さらにエビデンスには鮮度を要求します: 必須チェックの証拠は最新 git snapshot の HEAD と一致し、working tree が clean でなければ無効です。これにより「修正前に取った古いグリーンのログ」や「コミットされていない手元の状態」で PASS を偽装することができません。

フェイルクローズド

PR ガードは「安全だと証明できないものはすべてブロック」に倒しています。チェックの失敗だけでなく、未設定・保留・SKIPPED・NEUTRAL・mergeable 未確定もブロック対象です。CI が壊れて何もチェックが走らない状態を「グリーン」と誤認する事故を防ぎます。マージ時はガード確認時点の head SHA を固定するため、確認とマージの間に新しいコミットが滑り込む TOCTOU も防ぎます。

失敗フィンガープリントによる無駄打ち防止

コントローラーは失敗内容のフィンガープリントを取り、同じ失敗が繰り返されたら試行回数が残っていても停止します。LLM が同じ修正を試しては同じ失敗をする「スラッシング」でトークンを浪費せず、早めに人間へ渡します。

高リスク分類は意図的に広くマッチさせる

agent_loop_risk.py のパスパターンは意図的に広めです。誤検知（false positive)のコストは人間レビュー1回ですが、見逃し（false negative）のコストは未レビューの認証情報やスキーマ変更が本番に出ることだからです。分類は fnmatch による決定論で、同じ diff は必ず同じ分類になります。

修復エージェントへの最小権限

修復コマンドにはデフォルトで GH_TOKEN/GITHUB_TOKEN 以外の secret を渡しません（--repair-env-allow NAME で明示許可）。修復エージェントが侵害・誤動作しても、触れる認証情報を最小限に抑えます。

注釈は証拠にならない

AI判断ログ（ai_decision_logs）とナレッジ資産（.agent-loop/knowledge/）は、監査と将来のエージェントの誘導のためのものであり、評価器の PASS/FAIL には一切影響しません。「教訓を書いたから通してよい」という抜け道を構造的に塞いでいます。

人間承認者の必須化

findings の accepted_risk / deferred には非AIの承認者が必要で、ai, agent, assistant, llm, claude, controller, bot は承認者名として無効です。AI が自分のリスクを自分で承認することはできません。

依存ゼロ・自己完結

ランタイム依存はゼロ（Python 3.10+ 標準ライブラリのみ）で、CI 環境へのインストールが一瞬で終わり、supply chain リスクも最小です。ダッシュボードも外部 JS/CSS に依存しない単一 HTML として生成されるため、artifact や静的ホスティングにそのまま置けます。

含まれるもの

hermes_cli/agent_loop_capture.py — 台帳の初期化、コマンドエビデンス、gitスナップショット、PRスナップショット、修復ステータスのヘルパー
hermes_cli/agent_loop_evaluator.py — 決定論的評価器とハードゲート
hermes_cli/agent_loop_controller.py — 最大試行回数・繰り返し失敗停止・実行時間制限・ハンドオフレポートを備えた有界修復コントローラー
hermes_cli/agent_loop_ledger_update.py — 要件/タスク/発見事項/クレームの決定論的セマンティック台帳アップデーター
hermes_cli/agent_loop_knowledge.py — 失敗・パターン・決定・ハンドオフのナレッジキャプチャ（教訓をリポジトリ資産として蓄積）
hermes_cli/agent_loop_pr_guard.py — CI/チェックが失敗・保留・未設定のときにAI PRのマージをブロックするフェイルクローズドガード
hermes_cli/agent_loop_pr_ci_loop.py — CIがグリーンになるまでAI PRを修復し、許可されたベースブランチに安全にマージする有界ループ
hermes_cli/agent_loop_regression.py — JUnit XML / git worktree から新規失敗を機械計算する回帰検出
hermes_cli/agent_loop_decision_log.py — AI/Controllerの判断理由・前提・リスクを台帳に監査ログとして残すヘルパー
hermes_cli/agent_loop_usage.py — トークン/コスト使用量のレポートと予算ゲート（agent-loop-usage, agent-loop-usage-record）
hermes_cli/agent_loop_risk.py — 変更ファイルパスによる高リスク変更の決定論的分類（認証・課金・migration・secrets・CI/CD・インフラ）
hermes_cli/agent_loop_dashboard.py — 台帳からループ監視用の静的HTMLダッシュボードを生成（agent-loop-dashboard）
scripts/setup.sh — マシンに一度だけ実行するセットアップ（uv tool install で agent-loop-* を導入、前提を検出・警告）
scripts/*.py — 上記のCLIラッパー（dev/legacy。セットアップ後は agent-loop-* コマンドの使用を推奨）
templates/evidence-ledger.json — スターター台帳
templates/knowledge-entry.md — レビュー可能なナレッジエントリテンプレート
templates/pr-body-human-review-ja.md — 人間がレビューすべき観点に絞った日本語PRボディ
docs/knowledge-asset-design.md — 失敗と教訓を永続的なプロジェクトナレッジに変換するための設計
docs/pr-human-review-ja.md — 日本語PRレビューサマリーとCIマージゲートポリシー
docs/ai-decision-log.md — 問題発生時にAI/Controllerの判断を追跡するための監査ログ設計
docs/non-functional-requirements-ja.md — 非機能要件チェックリスト（保守性・性能・可用性・セキュリティ・運用性・統制・拡張性ほか）
skills/software-development/agent-loop-evaluation/ — エビデンス台帳・決定論的評価・有界修復・ハンドオフルール
skills/software-development/subagent-driven-development/ — 自律実装ループ: 計画 → サブエージェント実装 → 仕様レビュー → 品質レビュー → 最終検証
skills/github/github-pr-workflow/ — ブランチ → コミット → ドラフトPR → CI → AIレビュー → マージ/クリーンアップのループ
skills/github/github-issues/, github-code-review, github-auth, github-repo-management — ループで使用するissue/PR/レビュー/認証/リポジトリ操作
skills/autonomous-ai-agents/{codex,claude-code,opencode}/ — オプションの外部コーディングエージェント委譲バックエンド
.github/workflows/agent-loop.yml — PR / workflow_dispatch / workflow_call のCIゲート
.github/workflows/pr-ci-repair-merge.yml — CIがグリーンになるまでPRを修復してから安全にマージする手動ワークフロー
.github/workflows/ci.yml — ツールキット自身のユニットテスト（Python 3.10 / 3.12 マトリクス）
tests/cli/ — Hermes Agentからコピーしたコアユニットテスト

前提条件 (Prerequisites)

uv — パッケージ管理・インストールに使用（https://docs.astral.sh/uv/）
git — 台帳スナップショットとPRワークフローに必要
gh (GitHub CLI) + gh auth login — PRガード／CI修復マージに必要

setup.sh はこれらを検出して不足を警告するだけで、自動インストールはしません（gh認証も同様）。

セットアップ（マシンに一度）

agent-loop-* コマンドをこのマシンのPATHに導入します。一度実行すれば、任意のリポジトリに cd して使えます（リポジトリごとの再インストールは不要）。

# クローンしたディレクトリで
./scripts/setup.sh

# uv 自体が未導入なら自動導入も任せる場合
./scripts/setup.sh --bootstrap-uv

# ローカルの変更を反映して再インストール
./scripts/setup.sh --upgrade

クローンせずに直接導入することもできます:

uv tool install --from git+https://github.com/RyoyaYahagi/agent-loop agent-loop

開発・CI向けの editable インストール（venv + テスト依存）:

./scripts/setup.sh --dev
source .venv/bin/activate

クイックスタート（リポジトリごと）

セットアップ後、評価したいリポジトリ内で実行します:

cd /path/to/your/repo

agent-loop-ledger-init \
  --ledger evidence-ledger.json \
  --loop-run-id issue-123 \
  --repo "owner/repo" \
  --issue 123 \
  --branch "feature/issue-123" \
  --base-ref main \
  --required-check "CHECK-test:pytest -q" \
  --required-check "CHECK-lint:ruff check ." \
  --required-status-check test

agent-loop-controller evidence-ledger.json --max-attempts 1 --output-report agent-loop-handoff.md

evidence-ledger.json と .agent-loop/ は実行状態なので、コミットしたくなければ対象リポジトリの .gitignore に追加してください。

--required-check は ID:command 形式です。--required-check-json '{"id":"CHECK-test","command_argv":["pytest","-q"],"timeout":600,"type":"unit-tests"}' も使えます。文字列IDだけの旧形式は宣言のみとして扱われ、コントローラーでは実行できないため評価はFAILします。

CLIコマンド一覧

セットアップ後に使える agent-loop-* コマンドの全体像です。

コマンド	役割
`agent-loop-ledger-init`	エビデンス台帳の初期化（スコープ・必須チェックの宣言）
`agent-loop-ledger-run`	コマンドを実行し、exit code・ログを機械エビデンスとして記録
`agent-loop-ledger-git-snapshot`	git snapshot（HEAD・dirty・変更ファイル）を記録
`agent-loop-ledger-pr-snapshot`	`gh` 経由で PR/チェック状態を記録
`agent-loop-ledger-repair`	修復試行のステータスを記録
`agent-loop-evaluate`	決定論的ハードゲートで台帳を評価（PASS/FAIL）
`agent-loop-controller`	有界修復ループの実行（検証→評価→修復→ハンドオフ）
`agent-loop-ledger-update`	セマンティックエントリ（要件/タスク/発見事項/クレーム）の構造化更新
`agent-loop-ledger-decision`	AI/Controllerの判断理由を監査ログとして記録
`agent-loop-regression`	JUnit XML / git worktree による機械回帰検出
`agent-loop-usage` / `agent-loop-usage-record`	トークン/コスト使用量のレポート・記録・予算ゲート
`agent-loop-dashboard`	台帳から監視用の静的HTMLダッシュボードを生成
`agent-loop-pr-merge-guard`	フェイルクローズドのPRマージガード
`agent-loop-pr-ci-repair-merge`	CIグリーンまでの有界修復＋安全マージループ

CIモード

評価のみゲート

決定論的評価器が FAIL を返した場合、ワークフローはPRを失敗させます。LLMがpass/failを判断することはありません。

有界修復モード

手動またはreusableワークフローで repair=true を設定して実行します。コントローラーの動作:

scope.required_checks をコントローラー自身が実行する
直後に git snapshot を取得する
台帳を評価する
決定論的な repair_tasks から修復プロンプトを生成する
設定した修復コマンドを1回実行する
再びコントローラー所有の検証パス（1）から始める
成功したら停止、いずれかの上限に達したら人間にエスカレーション

修復エージェントは機械エビデンスを書きません。コード修正とセマンティックな台帳アノテーションだけを行い、チェック再実行・ログ保存・snapshot はコントローラー/CIが所有します。

デフォルトの上限:

AGENT_LOOP_MAX_ATTEMPTS=3
AGENT_LOOP_MAX_SAME_FAILURE_COUNT=2
AGENT_LOOP_MAX_RUNTIME_MINUTES=30
AGENT_LOOP_MAX_TOTAL_TOKENS（未設定なら無制限）
AGENT_LOOP_MAX_COST_USD（未設定なら無制限）

AGENT_LOOP_REPAIR_COMMAND に生成されたプロンプトを受け取るコマンドを設定します。コントローラーが公開する環境変数:

HERMES_LEDGER_PATH
HERMES_AGENT_LOOP_REPAIR_PROMPT_FILE
HERMES_AGENT_LOOP_REPAIR_ATTEMPT
HERMES_AGENT_LOOP_PHASE

実行例:

AGENT_LOOP_REPAIR_COMMAND='hermes chat -q "$(cat $HERMES_AGENT_LOOP_REPAIR_PROMPT_FILE)"' \
agent-loop-controller evidence-ledger.json --comment-pr

試行回数が尽きた場合、同じ失敗が繰り返された場合、実行時間が切れた場合、権限/シークレットが不足している場合、または修復コマンドがない場合、コントローラーはエスカレーションで終了し agent-loop-handoff.md を書き出します。PR CI内では gh と GH_TOKEN が利用可能な場合、PRにハンドオフをコメントすることもできます。

トークン消費量の記録・可視化・予算ゲート

モデル価格の変動やタスク量の増加でループのコストは静かに膨らみます。agent-loop は使用量を台帳の usage_events[] に機械記録し、可視化と予算超過停止の両方に使います。

記録する

修復コマンドのラッパーなど、LLM を呼んだ側が各呼び出し後に記録します:

agent-loop-usage-record \
  --ledger evidence-ledger.json \
  --phase repair_attempt_1 \
  --agent-role repair-agent \
  --model claude-sonnet-5 --provider anthropic \
  --input-tokens 12000 --output-tokens 3500 \
  --estimated-cost-usd 0.084

可視化する

フェーズ別・エージェント別の消費量をレポートします。どのフェーズ（計画・修復・レビュー）がトークンを食っているかが見えるため、プロンプト圧縮や試行回数調整の改善に使えます:

agent-loop-usage evidence-ledger.json                    # Markdownレポート
agent-loop-usage evidence-ledger.json --format json      # ダッシュボード連携用
agent-loop-usage evidence-ledger.json --max-cost-usd 5   # 予算超過なら exit 1（CIゲート化）

コスト見積もりのないイベントは unknown_cost_events として明示され、「実コストは表示より高い」ことがレポートに出ます。

ループを止める

コントローラーは各試行の前に台帳の使用量合計を予算と比較し、超過していれば修復を続けずに人間へエスカレーションします（ハンドオフレポートに使用量サマリーを含む）:

agent-loop-controller evidence-ledger.json \
  --max-total-tokens 200000 \
  --max-cost-usd 5.0

環境変数 AGENT_LOOP_MAX_TOTAL_TOKENS / AGENT_LOOP_MAX_COST_USD でも設定できます。予算判定は記録された数値の機械比較であり、LLM の自己申告には依存しません。

日本語PRレビューサマリー

AI作成のPRには、人間が判断すべき観点（問題/スコープ、アーキテクチャ決定、責任境界、テストの妥当性、高リスクdiff、本番/顧客への影響）のみを示した日本語レビューサマリーを含める必要があります。使い方:

cp templates/pr-body-human-review-ja.md /tmp/pr-body.md
gh pr create --draft --body-file /tmp/pr-body.md

自動マージの前に、フェイルクローズドPRガードを実行してください:

agent-loop-pr-merge-guard <PR_NUMBER>

PRがドラフト状態の場合、チェックが失敗/保留/未設定の場合、必須チェックがrollupに存在しない場合、必須チェックが SKIPPED/NEUTRAL の場合、GitHubが mergeable=false または未確定を報告する場合、またはオプションのレビュー承認が必要だが未取得の場合にブロックします。--required-check NAME または台帳の scope.required_status_checks で必須GitHubチェック名を指定できます。完全なポリシーは docs/pr-human-review-ja.md を参照してください。

CIがグリーンになるまで修復を続けてからマージするには、有界CI修復ループを実行します:

agent-loop-pr-ci-repair-merge <PR_NUMBER> \
  --repair-command 'hermes chat -q "Fix PR {pr} CI failure. Attempt {attempt}. Check CI logs, patch only the needed files, run local checks, commit, and push."' \
  --max-attempts 3 \
  --allowed-base develop

安全のデフォルト設定:

高リスク変更（認証・課金・DB migration・secrets・CI/CD・インフラのパスに触れるPR）は、--require-review-approval の指定がなくても人間の APPROVED レビューが必須（agent_loop_risk.py によるパスベースの機械分類）
repair command には最小権限の環境変数のみ渡す。GH_TOKEN/GITHUB_TOKEN 以外のsecretはデフォルトで遮断され、--repair-env-allow NAME で明示的に許可する（旧来の全渡しは --repair-env-passthrough-all）
pr_merge_guard がチェックのグリーンを確認するまでマージしない
チェック未設定は成功ではなく失敗として扱う
必須チェックの SKIPPED / NEUTRAL は失敗として扱う
merge時はガード確認時のhead SHAを --match-head-commit で固定する
有界試行回数の後に停止し、人間にハンドオフする
デフォルトでは develop または staging へのみ自動マージ
--allow-main を明示的に設定しない限り main への自動マージは行わない

変更スコープゲート（diff_scope）

「関係ないファイルを触らない」「大規模リファクタをしない」はプロンプト指示だけでは守られません。台帳の scope に制約を宣言すると、evaluator が最新 git snapshot の変更ファイル・diff行数を機械検証し、逸脱を FAIL にします:

"scope": {
  "allowed_paths": ["src/*", "tests/*"],
  "max_changed_files": 10,
  "max_diff_lines": 500
}

制約未宣言の台帳は従来どおり動作します（ゲートはopt-in）。逸脱時の repair task は「スコープを広げて通すのではなく、逸脱を revert するか人間にエスカレーションせよ」という指示になります。

ダッシュボード監視

台帳から自己完結型のHTMLダッシュボード（評価履歴・チェック結果・修復状況・findings・トークン/コスト・判断ログ）を生成できます:

agent-loop-dashboard evidence-ledger.json --output agent-loop-dashboard.html

# 複数リポジトリ/ループの台帳をまとめて1ページに
agent-loop-dashboard repoA/evidence-ledger.json repoB/evidence-ledger.json

CI（agent-loop.yml）は評価のたびにダッシュボードを artifact としてアップロードします。GitHub Pages や社内静的ホスティングに置けば継続監視できます。ダッシュボードは読み取り専用のレポートであり、verdict の再計算や上書きはしません。

台帳の更新

証明として信頼せずに構造化アノテーションを適用する:

agent-loop-ledger-update --ledger evidence-ledger.json --updates examples/semantic-updates.json

アップデーターはセマンティックエントリをアノテーションとしてマークします。機械エビデンスは引き続きラッパー/CI/ツールから取得する必要があります。

accepted_risk / deferred の findings は、非AIの approved_by と reason が必要です。ai, agent, assistant, llm, claude, controller, bot は承認者として無効です。

回帰検出

JUnit XML同士の差分:

agent-loop-regression \
  --ledger evidence-ledger.json \
  --base-junit /tmp/base.xml \
  --head-junit /tmp/head.xml

git worktreeでbase/headを実行して差分:

agent-loop-regression \
  --ledger evidence-ledger.json \
  --base-ref origin/main \
  --test-command 'pytest -q --junitxml {junit}'

評価器は regressions.source == "machine" かつ head_commit が最新 git snapshot と一致する場合だけ回帰エビデンスとして認めます。

AI判断ログ

問題発生時に「なぜAI/Controllerがその行動を選んだか」を追えるように、ai_decision_logs を台帳に残せます。これは監査用アノテーションであり、evaluator のPASS/FAIL証拠にはなりません。

agent-loop-ledger-decision \
  --ledger evidence-ledger.json \
  --phase repair_attempt_1 \
  --actor ai \
  --decision "Fix failing typecheck before requesting review" \
  --rationale "CI reported a type error and merge guard blocks non-green checks." \
  --evidence-ref "checks[CHECK-typecheck]" \
  --confidence high

Controller と CI修復マージループは、PASS停止・修復実行・マージ・エスカレーションなどの主要判断を自動で記録します。詳細は docs/ai-decision-log.md を参照してください。

ナレッジ資産

失敗と永続的な教訓は .agent-loop/knowledge/ にMarkdownファイルと小さな index.json として昇格できます。これらのナレッジ資産は評価器エビデンスとは意図的に分離されています: 将来のエージェントを導くことはできますが、現在の実行をpassにすることはできません。

人間が書いた教訓を記録する:

agent-loop-knowledge-record \
  --repo-root . \
  --type pattern \
  --title "認証済みNext.jsページはforce-dynamicが必要" \
  --summary "getCurrentUser()を呼ぶページはdynamic = force-dynamicをエクスポートする必要がある。" \
  --prevention "プッシュ前に新しい認証済みページを確認する。" \
  --tag nextjs --tag ci

最新の台帳評価から失敗候補を作成する:

agent-loop-knowledge-record --repo-root . --ledger evidence-ledger.json

昇格ルール、ストレージレイアウト、コメントポリシーについては docs/knowledge-asset-design.md を参照してください。

コードコメントポリシー

オーケストレーションコードは重要な箇所でコメントを充実させるべきです。クラスや関数が存在する理由、持つ権限、防ぐ障害モード、信頼してはいけないものを説明するdocstring/コメントを追加してください。次のコード行を言い換えるだけのコメントは避けてください。

ハードルール

AIの自己申告はエビデンスではない
必須チェックはコマンド・cwd・コミット・終了コード・stdout/stderrログ・source: machine とともに機械的に収集する必要がある
台帳は schema_version: 2 必須。不正な構造や空台帳はFAIL
必須チェック証拠は最新git snapshotのHEADと一致し、snapshotがcleanでなければならない
完了クレームにはエビデンスが必要。根拠のない、または矛盾する完了クレームは失敗する
修正済み発見事項には再チェックエビデンスが必要
accepted_risk / deferred は人間承認者と理由がなければ未解決扱い
回帰データは機械計算のみ有効
修復コントローラーは有界であり、無限ループではなく人間にハンドオフする

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
hermes_cli		hermes_cli
scripts		scripts
skills		skills
templates		templates
tests/cli		tests/cli
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation