0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

AIエージェントの引き継ぎ台帳をJSONLで作る:作業中断と再開に強い最小スキーマ

0
Posted at

AIエージェント引き継ぎ台帳 - objective、status、evidence、next_actionをJSONLで残す

引き継ぎ台帳の流れ - start、progress、blocked、handoff、resume

はじめに

AIエージェントに作業を任せると、完了報告は比較的簡単に出せます。難しいのは、中断した作業を次のセッションや別エージェントが安全に再開することです。

会話ログだけに頼ると、どこまで終わったのか、何を確認したのか、何が未解決なのかが埋もれます。特にMCP連携、X投稿、記事公開、Playwrightによる外部操作のように、route_idや承認状態が絡む作業では「たぶんここまで終わっている」という曖昧な引き継ぎが事故になります。

Agent Memoriesでは、作業の途中状態をJSONLの引き継ぎ台帳として残す設計を重視しています。この記事では、TypeScriptで扱いやすい最小schema、ログの残し方、dry-runとテスト観点までをまとめます。

なぜJSONLで残すのか

JSONLは、1行1イベントで追記できます。DBを用意しなくても、ファイルにappendするだけで最低限の台帳になります。

{"at":"2026-06-24T10:00:00+09:00","task_id":"tech-stock-20260624","actor":"asuna","type":"progress","objective":"tech-daily stock refill","status":"drafting"}

途中でプロセスが落ちても、最後に書けた行までは残ります。Git差分でも読みやすく、後から集計もしやすい形式です。

AIエージェント運用では、完了済みの作業よりも「未完了のまま止まった作業」の方が危険です。次の担当が状況を読み違えると、同じ調査を繰り返したり、未承認のまま公開したり、別アカウントで投稿したりします。JSONL台帳は、そうした再開時の認知負荷を下げるための運用部品です。

最小schema

最小構成は次の通りです。

type HandoffEventType =
  | "start"
  | "progress"
  | "blocked"
  | "handoff"
  | "resume"
  | "complete";

type HandoffEvent = {
  at: string;
  task_id: string;
  actor: string;
  type: HandoffEventType;
  objective: string;
  status: string;
  route_id?: string;
  evidence?: string[];
  next_action?: string;
  blocker?: string;
  rollback?: string;
};

重要なのは、evidence と next_action です。感想ではなく、再開に必要な証跡と次の一手を残します。route_id は、投稿や外部操作が絡む場合に必須に近い項目です。どの媒体、どのアカウント、どのsecretを使う前提だったのかを別の台帳で管理していても、引き継ぎイベント側にも参照キーを残しておくと事故が減ります。

rollback は必須ではありません。ただし、本番ファイル、投稿予約、広告設定、Zenn/Qiita公開のように戻し方が必要な作業では、最初から項目を持たせておく方が安全です。

startイベント

作業開始時には、目的と範囲を書きます。

{"at":"2026-06-24T10:05:00+09:00","task_id":"tech-stock-20260624","actor":"asuna","type":"start","objective":"tech-dailyの記事在庫を補充する","status":"investigating","route_id":"agent_memories_official","next_action":"content/techとstate/tech-published.jsonを確認する"}

ここで「何をしないか」も決めておくと、作業が広がりすぎません。たとえば、今回は投稿しない、secretを使わない、QC承認は別担当に回す、という範囲です。

実装では、開始時点で台帳に1行書けるかを確認してから作業します。ログが書けない状態で本番操作だけ進むと、後で何も追えません。

progressイベント

進捗は、確認した事実を中心に書きます。

{"at":"2026-06-24T10:20:00+09:00","task_id":"tech-stock-20260624","actor":"asuna","type":"progress","objective":"tech-dailyの記事在庫を補充する","status":"root cause found","evidence":["state/tech-published.json contains slugs 06-08","content/tech has no unpublished valid item"],"next_action":"新規原稿を1本作成してAlice QCへ回す"}

evidence は、再確認できるファイル、URL、コマンド結果、スクリーンショット名などにします。「たぶん空だった」「見た感じ問題ない」は再開性が低いので避けます。

コード側では、追記用の小さな関数を作っておくと運用に乗せやすくなります。

import { appendFile } from "node:fs/promises";

export async function appendHandoffEvent(path: string, event: HandoffEvent) {
  const line = JSON.stringify(event);
  await appendFile(path, `${line}\n`, "utf8");
}

この関数は、余計な整形をしません。JSONLでは1行が1イベントなので、pretty printよりも壊れにくさを優先します。

blockedイベント

止まった時は、止まった理由と解除条件を書きます。

{"at":"2026-06-24T10:30:00+09:00","task_id":"tech-stock-20260624","actor":"asuna","type":"blocked","objective":"tech-dailyの記事在庫を補充する","status":"waiting for Alice QC","blocker":"alice_qc_missing: qiita,zenn","next_action":"Alice approval JSONが追加されたらdry-runでalice_qc_missingを確認する"}

単に「確認待ち」と書くより、解除条件が明確になります。AIエージェントは、待ち状態を曖昧にすると、次回セッションで勝手に完了扱いしてしまうことがあります。blocker と next_action を分けると、「今できない理由」と「解除後にやること」を読み違えにくくなります。

外部投稿のような事故リスクがある作業では、blockedイベントに route_id と rollback も入れます。

{"at":"2026-06-24T10:34:00+09:00","task_id":"x-post-20260624","actor":"asuna","type":"blocked","objective":"Agent Memories公式Xの投稿予約","status":"route confirmation required","route_id":"agent_memories_official","blocker":"target account not confirmed","rollback":"no external action executed"}

resumeイベント

再開時には、前回の最後のイベントを読んだことを残します。

type ResumeEvent = HandoffEvent & {
  type: "resume";
  resumed_from_event_at: string;
};

実際のイベントは次のようになります。

{"at":"2026-06-24T11:10:00+09:00","task_id":"tech-stock-20260624","actor":"asuna","type":"resume","objective":"tech-dailyの記事在庫を補充する","status":"resumed from Alice QC wait","evidence":["approval file added: memory-search-recall-gate.qiita.approved.json"],"next_action":"python3 agentmemories-tech-daily.py --dry-run を実行する"}

resumeを残す理由は、再開した担当が何を前提に動いたかを後から追えるようにするためです。特に、MCPやPlaywrightで外部状態を触る場合は、再開時点の確認がログに残っていないと、事故原因を切り分けにくくなります。

completeイベント

完了時も、成果物と検証を残します。

{"at":"2026-06-24T10:45:00+09:00","task_id":"tech-stock-20260624","actor":"asuna","type":"complete","objective":"tech-dailyの記事在庫を補充する","status":"5 drafts added","evidence":["python3 agentmemories-tech-daily.py --dry-run returned next slug"],"next_action":"翌日の在庫アラートで残数を確認する"}

完了報告と台帳を分けることで、Discordの短い報告だけでは失われる詳細を残せます。チャットは判断を伝える場所、台帳は再開可能性を残す場所、と役割を分けるのが実装上も運用上も扱いやすいです。

dry-runとテスト観点

引き継ぎ台帳は、書ければ終わりではありません。最低限、次のテストを用意します。

import { describe, expect, it } from "vitest";

describe("handoff ledger schema", () => {
  it("requires objective, status, evidence or next_action", () => {
    const event = {
      at: "2026-06-24T10:00:00+09:00",
      task_id: "sample",
      actor: "asuna",
      type: "progress",
      objective: "refill tech daily stock",
      status: "drafting",
      evidence: ["content/tech checked"],
    };
    expect(event.objective).toBeTruthy();
    expect(event.status).toBeTruthy();
    expect(event.evidence.length).toBeGreaterThan(0);
  });
});

dry-runでは、台帳に追記せず、生成されるイベントだけを標準出力へ出します。

node scripts/handoff-ledger.mjs --task-id tech-stock-20260624 --type progress --dry-run

確認したいのは、イベントがJSONとして壊れていないこと、task_id が空でないこと、route_id が必要な作業で抜けていないこと、secret値が混ざっていないことです。ログは便利ですが、Cookie、APIキー、認証コードを残す場所ではありません。

運用で効くチェックリスト

実運用では、イベント種別よりも「次の人が再開できるか」を基準にします。

  • objectiveは作業範囲を表しているか
  • statusは現在状態として読めるか
  • evidenceは再確認できる形か
  • next_actionは1つ以上あるか
  • blockerは解除条件とセットになっているか
  • route_idが必要な作業で抜けていないか
  • rollbackが必要な作業で未記載になっていないか
  • secretや個人情報がログに入っていないか

このチェックを通すだけでも、AIエージェントの作業はかなり再開しやすくなります。

まとめ

AIエージェントの運用では、完了した作業よりも、中断した作業の再開性が重要です。

JSONLの引き継ぎ台帳に最低限残すべき項目は、objective、status、evidence、next_action です。外部操作があるなら route_id、止まっているなら blocker、戻し方が必要なら rollback も入れます。

記憶を持つAIパートナーを作るなら、会話の記憶だけでなく、作業の履歴も読める形で残す必要があります。引き継ぎ台帳は、そのための小さくて強い基盤です。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?