【要約】AIコーディングエージェントの「完了」をSQLite・JSONL・Evidenceで検証可能にする [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
AIエージェントを用いた開発において、作業の「完了」を客観的に定義・検証できない問題が発生している。エージェントが「完了した」と主張しても、その根拠となるテスト結果や成果物の証拠が不明確なため、信頼性に欠ける。具体的には以下の課題がある。
- ・エージェントの「完了」の主張を、次のセッションで再確認できない。
- ・テストやレビューの証拠がどこにあるのか、追跡が困難である。
- ・人間の判断が必要な箇所と、エージェントが進めてよい箇所の境界が曖昧である。
// Approach
開発者は、状態管理、監査、表示の役割を明確に分離したガード付き状態機械を導入した。単なるダッシュボードの構築ではなく、データの整合性を重視した設計を採用している。
- ・SQLite: 現在の状態（Goal, Task, Evidence等）を保持する「System of Record」として利用。
- ・JSONL: 状態変更の履歴を追記型で残す「監査投影」として利用。
- ・HTML: 人間が状況を把握するための「生成ビュー」として利用し、エージェントには読み込ませない。
- ・Evidence: テスト出力や成果物を
pcl evidence add --copy等でSHA-256ハッシュと共に固定管理。
// Result
この設計により、エージェントの作業プロセスを、機械的に検証可能な状態遷移へと昇華させた。作業完了時に
pcl finish --emit-packet を実行することで、検証結果をパケット化できる。- ・デモ環境（macOS, Python 3.13）において、テスト実行からGoalのクローズまでを9秒で完結。
- ・
COMPLETED_VERIFIEDという明確な状態遷移を実現。 - ・
pipxを用いた既存プロジェクトへの段階的な導入パスを提供。
Senior Engineer Insight
> エージェントの「完了」という主観的な主張を、ハッシュ値という客観的な事実へ変換する設計は極めて合理的だ。SQLiteによる状態管理とJSONLによる監査ログの分離は、システムの信頼性と追跡可能性を同時に高めている。実戦投入においては、
pcl.yaml の設定精度がガードレールの強度を左右するため、設定の自動化やテンプレート化が鍵となるだろう。エージェントにHTMLを読ませず、JSONとEvidenceのみを扱わせる境界設計も、堅牢なシステム構築の観点から高く評価できる。