ナレッジの運用サイクル

エージェントが下書きを書き、人間がそれを検証し、実際の利用結果からフィードバックを得る。「ナレッジ作成ガイド」で登録した知識を陳腐化させず、継続的に鮮度と品質を保つための運用サイクルを解説します。

本ガイドは ochakai v0.31.1 に対応しています。詳細は公式リポジトリの改善ループ・CLI リファレンス・Golden Query のカナリア実行ガイドを参照してください。

0. status（公開段階）と trust（検証状態）の 2 軸管理

ochakai のナレッジは、独立した 2 つの軸でライフサイクルを管理します。

管理軸	取りうる値	意味と役割	更新コマンド
status	`draft` / `stable` / `deprecated`	公開の成熟度段階（作成中、安定版、非推奨）	`ochakai put`（Frontmatter 編集）
trust	`unverified` / `machine-confirmed` / `human-reviewed`	誰によって検証されたかの信頼レベル（未検証、CI自動確認済、人間による承認済）	`ochakai verify`

ochakai verify は、人が内容の正しさを確認したという来歴を台帳に記録するコマンドです。対象が draft なら、検証と同時に status の一行だけを stable に書き換えます。残りのバイトは変わらず、その書き換えは検証者自身の編集として保存されてから検証が記録されます。すでに stable や deprecated のドキュメントを検証し直しても、本文と ETag には触れません（v0.31.0、決定 0157）。検証を経ずに status だけを動かすなら、ochakai put を使います。検証は、人か、CI カナリアのような確認ジョブが行います。ジョブの検証は machine-confirmed と読まれ、human-reviewed にはなりません。LLM は検証しません。

検証が保証するのは、確認した時点の内容です。検証のあとに本文を編集したり移動したりすると、trust は unverified に戻ります。整形だけの書き込みでは戻りません。検証の記録は台帳に残るので、読み直して問題がなければもう一度 verify します。

検索時は human-reviewed かつ stable なドキュメントが優先して上位にランクされます。

ochakai list usage --status draft              # 公開前の下書き一覧を確認
ochakai search "売上" --trust human-reviewed   # 人間が検証済みの高信頼ナレッジに絞って検索

1. エージェントとの 4 つの対話ステップ

エージェント（Claude Code 等）を接続したら、以下の 4 つのステップでナレッジの利用と改善が循環します（フックを設定している場合は、1 と 2 は自動的に行われます）。

思い出す（Recall）: エージェントが勝手な推測で SQL を組む前に、ochakai から既存の検証済みナレッジを検索させます。
「売上集計に関して、既に登録されているナレッジはある？回答する前に ochakai を検索して確認して。」
書き戻す（Write-back）: 分析の過程で判明した重要な前提やビジネスルールを、下書きとして記録させます。
「商品部門別の売上集計では、products.department の値に Men と Women 以外の特殊コードが入ることが分かった。次回以降の集計で誤りを防ぐため、Caveats に追記して ochakai に保存して。」
登録されたドキュメントは draft（未検証）として保存され、来歴にエージェント名が記録されます。v0.30.0 から、MCP で status を書かずに保存したものも draft になります。
人が検証する（Verify）: 人間が Web UI や CLI でドラフトを確認し、内容が正しければ検証済みに承認（verify）します。あるいは理由を付記して却下（delete）します。
人間によるレビューこそが、ナレッジの信頼性を担保する最も重要なステップです。
結果をフィードバックする（Outcome Reporting）: ナレッジを参照して実行した結果が想定と異なっていた場合、失敗フィードバックを報告します。
「この Golden Query の数値が月次決算の確定値と一致しなかった。理由を付記して failed として ochakai に報告して。」
失敗報告（report_outcome）が上がったドキュメントは、自動的に再検証キューへと送られ、エージェントへの推薦優先度が下がります。

2. 検証・却下・公開の手順

CLI からの操作は主に以下の 3 つです（Web UI のボタンからも同一の操作が可能です）。

ochakai verify metrics/revenue
# 検証完了: draft ならまず stable にしてから、承認者と時刻が台帳に記録される

ochakai delete metrics/bad-revenue --note "返金データの除外条件が二重カウントになっている"
# 却下: ドキュメントは削除され、却下理由が変更履歴と log.md に記録される

ochakai get metrics/revenue > c.md
# 検証を経ずに status を stable へ書き換える編集
ochakai put metrics/revenue -f c.md

Web UI を利用すれば、ブラウザ上で直感的にレビューと承認作業を行えます。

ochakai ui   # ローカルで Web UI を起動（http://127.0.0.1:8098）

Web UI ではナレッジをツリー表示し、利用回数や参照リンクを確認しながら、ワンクリックで検証や却下を行えます。

デプロイでデータエージェント（「立てて、運用する」§5）が有効なら、Web UI に「エージェント」タブが出ます。自分のエージェントを持たない人がナレッジについて質問でき、答えには引用したドキュメントが人に確かめられたものかが添えられます。答えの下の「合っている」は、その答えが読んだドキュメントへの成功報告になります。「違う」は質問した人が選んだドキュメントへの失敗報告になり、検証済みのものなら §4 の再検証フィードに入ります。エージェントは新しい下書きを書く場合もありますが、検証・却下・書き換えはしません。

3. レビューの優先順位

ochakai list usage --status draft    # 直近 90 日間で実際に参照された順にドラフトを表示

実務での運用が始まると、エージェントが実際に参照した回数が多い順にドラフトが並びます。利用頻度が高く、まだ人間が確認していないものから優先的にレビューするのが最も費用対効果の高い方法です。

すべてのドキュメントを急いで検証済みにする必要はありません。初期取り込みのテーブルが draft のままでも、検索時は検証済みのドキュメントが優先表示されるため安全に機能します。

4. 4 つのレビューフィードと対応方針

定期的に見直すべきナレッジを把握するため、ochakai には 4 つのフィードが用意されています。

再検証フィード（failed）: エージェントやユーザーから「集計が合わなかった」「クエリが失敗した」と報告されたドキュメントです。優先的に内容を確認し、修正して再検証（verify）するか、非推奨化・削除を行います。
期限切れフィード（stale_after）: 作成者が Frontmatter で指定した見直し期日（stale_after）を過ぎたドキュメントです。現在のビジネス状況と合致しているか確認します。
編集後未検証（edited）: 検証のあとに編集・移動され、いまの内容をまだ誰も確認していないドキュメントです。差分を読み、問題がなければ再検証します。
検証の古さ（verified_at）: 最後の検証から最も時間が経過している順にナレッジを並べます。定期的な見直し対象のピックアップに利用します。

ochakai list failed --trust human-reviewed   # 失敗報告が上がっている検証済みナレッジ
ochakai list stale_after                     # 指定期日を過ぎたナレッジ
ochakai list verified_at --trust unverified  # 検証後に編集され、いまの内容が未確認のナレッジ
ochakai list verified_at                     # 長期間再検証されていないナレッジ

ochakai stats                # レビュー待ちの全体状況を一目で確認
ochakai stats --exit-code    # CI/cron 用: 未処理のレビューが残っている場合に非ゼロで終了

Web UI の「レビュー」タブに表示されるバッジでも、これらの対応待ち件数を一目で確認できます。週に一度チェックして消化する運用をおすすめします。

失敗報告と答えられなかった検索が週に一度では読み切れなくなったら、仕分けをエージェントに任せられます。棚卸しの Skill をナレッジベースに取り込み、人が検証してから使います。エージェントは問いを束ねて振り分け、候補の下書きを書き、questions.txt で前後を比べます。人の前に来るのは、その結果をまとめた一枚だけです。検証は変わらず人が行い、この Skill は verify を実行しません。

5. 利用統計と品質モニタリング

個々のナレッジがどの程度役に立っているかは、利用統計コマンドで確認できます。

ochakai usage metrics/revenue

検索で提示された回数、本文が取得された回数、エージェントからの成功（worked）および失敗（failed）の報告件数、直近の参照日時が表示されます。

また、ochakai stats では「どのドキュメントの語にも一致しなかった検索（ナレッジのギャップ）」が頻度順に表示されます。セマンティック検索を有効にしたデプロイでは近いものが必ず返りますが、それでも語が一致しなければここに数えます（v0.28.7 から）。社内でどのようなデータ知識が求められているかが可視化されるため、次に記述すべきナレッジの優先順位付けに役立ちます。

6. Golden Query の CI カナリア実行（スキーマ変更の自動検知）

データウェアハウス側でテーブルやカラムの統廃合が行われると、過去に作成した Golden Query が突然動かなくなる（スキーマドリフト）リスクがあります。エージェントが本番業務で遭遇する前に、CI（GitHub Actions 等）から定期的に Golden Query を自動テストし、結果を ochakai にフィードバックする運用が推奨されます。

ochakai 自身は DWH へ直接接続しないため、認証情報は CI 側に安全に保持されます。CI は ochakai から Golden Query の一覧を取得し、DWH に対して dry-run または実クエリを実行して、成否を ochakai に書き戻します。

自動カナリアテストの流れ

クエリの取得: ochakai search または ochakai list で検証済みの Attested Computation 一覧を取得します。
テスト実行: BigQuery の --dry_run 等を利用して、SQL が現在も構文・スキーマ的に有効かテストします。
結果の書き戻し:
- 成功した場合: ochakai verify <id> で検証日時を更新。
- 失敗した場合: ochakai report <id> failed --note "dry-run failed: column not found" で自動報告し、再検証フィードへ送る。

GitHub Actions + BigQuery での CI 設定例

週に一度自動実行し、BigQuery の --dry_run でスキーマ変更によるクエリ破損を自動検知するワークフロー例です:

name: golden-query-canary
on:
  schedule:
    - cron: "0 21 * * 1" # 毎週月曜 06:00 JST
jobs:
  canary:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Workload Identity Federation によるキーレス認証
    steps:
      - uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: ${{ vars.WIF_PROVIDER }}
          service_account: ${{ vars.CANARY_SA }}
      - name: run canaries
        run: |
          TOKEN=$(gcloud auth print-identity-token --audiences="$OCHAKAI_URL")
          curl -s -H "Authorization: Bearer $TOKEN" \
            "$OCHAKAI_URL/api/v1/search?type=Attested%20Computation&trust=human-reviewed&sort=verified_at&limit=50" \
          | jq -r '.hits[].id' | while read -r id; do
              doc=$(curl -s -H "Authorization: Bearer $TOKEN" \
                -H 'Accept: text/markdown' "$OCHAKAI_URL/api/v1/bundle/$id.md")
              sql=$(printf '%s' "$doc" | sed -n '/^```sql$/,/^```$/p' | sed '1d;$d')
              if ! bq query --nouse_legacy_sql --dry_run "$sql" >/dev/null 2>&1; then
                echo "::error::computation $id no longer compiles against the warehouse"
                curl -s -X POST -H "Authorization: Bearer $TOKEN" \
                  -H 'Content-Type: application/json' \
                  -d '{"outcome":"failed","note":"canary: dry-run failed"}' \
                  "$OCHAKAI_URL/api/v1/usage/$id" >/dev/null
              else
                curl -s -X POST -H "Authorization: Bearer $TOKEN" \
                  -H 'Content-Type: application/json' \
                  -d '{"ruling":"verified"}' \
                  "$OCHAKAI_URL/api/v1/review/$id" >/dev/null
              fi
            done

まとめ

「エージェントが発見・下書きし、人間が検証し、CI で鮮度をテストする」運用サイクルにより、基盤変更に強い持続可能なデータナレッジレイヤーを維持できます。