症状

複数の担当に分けたAIエージェントの運用で、新しく決めたルールが実際の指示ファイルに反映されないまま放置されることがありました。決定自体は別の記録にちゃんと残っているのに、実際に手を動かす担当の設定ファイルには反映されていない、という状態です。

もう一つ、指示ファイルに書いてあるのに、実行のたびに同じ間違いが繰り返されるケースもありました。5回修正しても、6回目にまた同じ間違いが発生。

前提の環境

用途別に分けた複数のエージェント設定(それぞれ独立した指示ファイル)
決定はいったん別の記録ファイルにまとめてから、必要な指示ファイルへ書き写す運用
実行環境はClaude Code(Cowork経由)

直し方

1. 決定と指示ファイルを機械で突き合わせる

決めたことを検索語としてタブ区切りのリストに残し、対象の指示ファイル群のどこにも見つからないものだけを検出するスクリプトを作りました。

#!/usr/bin/env bash
# handoff-check.sh
# 使い方: ./handoff-check.sh handoffs.tsv agents_dir
set -euo pipefail

LIST="$1"
DIR="$2"
MISSING=0

while IFS=$'\t' read -r keyword decided_on source; do
  [ -z "$keyword" ] && continue
  HIT=$(grep -rl -- "$keyword" "$DIR"/*.md 2>/dev/null || true)
  if [ -z "$HIT" ]; then
    echo "未反映:「$keyword」($decided_on 決定・出どころ: $source)"
    MISSING=1
  fi
done < "$LIST"

[ "$MISSING" -eq 1 ] && { echo "→ 反映されていない決定があります"; exit 1; }
echo "→ すべて反映済みです"

handoffs.tsvはこんな中身です。

本文の外にタグを1〜2個添える	2026-08-26	読者設計の決定メモ
まとめの一文で締めない	2026-08-10	下書きの直し

実行例です。

$ ./handoff-check.sh handoffs.tsv agents
未反映:「本文の外にタグを1〜2個添える」(2026-08-26 決定・出どころ: 読者設計の決定メモ)
→ 反映されていない決定があります

決定メモを書く側で、検索に使える短い言葉をセットで残しておくのがポイントです。長い自然文のままだと、言い回しの違いですり抜けます。

2. 間違いが繰り返される項目は、書く担当ではなくレビュー担当(レビューが最終チェックする)へ移す

指示ファイルに書いてあるのに実行時に読んでもらえない項目は、書く担当への指示を増やすのではなく、出来上がったものを通すか差し戻すかを決める別の担当の判定基準に、他の項目と同列の1行として足しました。念を押す一文を添えるだけでは、結局「思い出せるか」に賭けることになり、あまり意味をなさず。

なぜそうなるか

「決定を書いた」ことと「実行する担当が実際にそれを踏まえて動く」ことのあいだには、誰かが両者を突き合わせる工程がない限り、齟齬が発生します。その齟齬は、それを見る人が気がつくかどうか次第でとても頼りない。同様に、指示ファイルに書いてある項目でも、作業しながら全部を思い出すのには限界があります。繰り返し間違う項目は、作る側の注意力ではなく、後工程の機械的なチェックのほうに持たせたほうが安定します。

結果(確認中)

運用に組み込んだばかりなので、次に新しい決定をするたびにこのチェックを挟んで、どのくらい漏れを拾えるかを見ていきます。