AIエージェントの「未完了タスク」をどこに書くか：working-memory.md 運用設計

Posted at 2026-05-09

AIエージェントの「未完了タスク」をどこに書くか：working-memory.md 運用設計

はじめに

Claude Code や Codex など、長期で同じリポジトリ・Vault を触るAIエージェントを運用していると、必ず突き当たる問題があります。

「セッションをまたいで残したいが、まだ正本ドキュメントに書くほど確定していない情報」をどこに置くか。

具体的にはこういう情報です。

今日途中まで進めた ETL パイプラインの bg ジョブ ID と次に確認すべきタイミング
DB のクレデンシャルが切れた疑いがある現象（まだ恒久ルール化するほど確証がない）
設計判断の候補（採用するかは要再検討）
「2026-05-16 以降にバックアップを削除する」という時限タスク

これを CLAUDE.md に書くと永続化されすぎて腐るし、Daily Note に書くと翌日には埋もれます。プロジェクトメモに書くには汎用的すぎる。

筆者の環境では1年弱の試行錯誤の末、memory/working-memory.md という一時バッファを置く という結論に落ち着きました。本記事ではその設計と運用ルールを共有します。

なぜ「ただのTODOリスト」では足りないのか

AIエージェントの記憶設計で最初にやりがちな失敗は、TODO管理ツール（Notion・Linear・GitHub Issues）に未完了タスクを集約することです。

これは人間向けには正解ですが、AIエージェントにとっては不十分です。理由は3つあります。

1. AIは「種別」と「次の昇格先」を読まないと判断できない

人間なら「DB認証エラー」と書けば文脈で対処できますが、AIは

これは恒久ルール化すべきか？（→ feedback_*.md 候補）
単発のクレデンシャルローテで終わる話か？（→ プロジェクトメモのみ）
設計判断として残すべきか？（→ ADR候補）

をメタ情報として明示されないと判断できません。

2. 「いつ昇格させるか」が曖昧だと永久に一時メモのまま腐る

タスクを書きっぱなしにすると、3ヶ月後には何のためのメモか分からなくなります。「昇格先候補」を最初から書かせる仕組みが必要です。

3. 完了済みタスクが下方堆積すると検索ノイズになる

特に RAG ベースで Vault を検索しているエージェント環境では、完了タスクが類似度検索のノイズになります。

working-memory.md の構造

筆者の環境では以下の YAML frontmatter + Markdown 構造で運用しています。

---
name: working-memory
description: セッション横断で継続すべき未完了タスク・失敗学習・ADR候補の一時記録
type: memory
created: 2026-04-22
---

# Working Memory

## 役割

| 種別 | 書く内容 | 後続の昇格先 |
|---|---|---|
| 未完了タスク | セッション内で完了できなかった具体タスク | MEMORY.md / PJメモ / Daily Note |
| 失敗学習 | まだ確定していない再発リスク | skill-traces.md / feedback_*.md |
| ADR候補 | 設計判断として残すべき可能性があるもの | 02_Knowledge/decisions/ |
| 調査保留 | 追加確認が必要な仮説・差分 | 該当PJメモ / playbook / ADR |

## 書き方

新しいものを上に追記する。

```md
## YYYY-MM-DD HH:mm JST - タイトル

- 種別:
- 背景:
- 次アクション:
- 昇格先候補:
```

ポイントは 冒頭テーブルで「昇格先」を明示していることです。エージェントが新しいエントリを書くとき、この表を見て自分で「どこに昇格させるべきか候補」を書きます。

実エントリの例

実際のエントリ例を匿名化して示します。

例1: 時限タスク（削除予約）

## 2026-05-09 08:00 JST - Codex Hooks 修正バックアップの削除予約

- 種別: 未完了タスク（要削除）
- 背景:
  - Codex Hooks が約3週間 dead code 状態だった件を修正
  - 修正前バックアップ2本を保持中:
    - ~/.codex/hooks.json.bak.20260509
    - ~/.codex/hooks/codex_hook_common.py.bak.20260509
- 次アクション: 2026-05-16 以降、Hook が問題なく動作していれば両ファイル削除
- 昇格先候補: 削除完了後、本エントリも削除

「2026-05-16 以降に削除」のような 時限つきタスク は、Daily Note には書きづらく、TODO管理ツールに入れると詳細を失います。working-memory なら「次アクション」と「絶対パス」をワンセットで残せます。

例2: 不確定な障害

## 2026-05-05 09:00 JST - 週次クローラの DB 認証失敗

- 種別: 未完了タスク（要対応）
- 背景:
  - 週次competitor crawl が password authentication failed で全停止
  - .env.local 最終更新が約1ヶ月前 → DB側でローテートされた可能性大
  - 影響: 今週の競合価格スナップショット欠損
- 次アクション:
  1. DB Console で password 再取得
  2. .env.local の DATABASE_URL 更新
  3. 疎通確認後に scheduled task を手動実行
  4. 同じDBを使う他PJも死んでいないか確認
- 昇格先候補:
  PJメモ
  （恒常運用ルール化なら feedback_db_credential_rotation.md 新規作成）

ここでのコツは 「昇格先候補」を2段階で書く ことです。

単発で終わるなら → PJメモへ
同じ事象が他PJでも起きるなら → 恒久ルール化（feedback_*.md）

最初から確定させず、後続セッションで判断材料を揃える設計にしています。

例3: 完了記録の残し方

完了したタスクは消すのではなく、「完了記録」種別で短く残します。

## 2026-04-26 - 週次ニュースレター #5 送信待ち [完了 2026-04-27]

- 種別: 未完了タスク（意図的・ユーザー確認待ち）
- 背景: campaign_id=24 を生成・送信前確認待ち
- 完了: 2026-04-27 送信実行 → 45件送信 / 失敗0件

タイトルに [完了 YYYY-MM-DD] を付けることで、後で grep して圧縮できるようにしておきます。

エージェントへの指示の書き方

CLAUDE.md（Claude Codeのプロジェクトルール）には以下のように書いておきます。

## working-memory 参照ルール

| トリガー | アクション |
|---|---|
| セッション開始時 | memory/working-memory.md を最初に読む |
| 修正指示・方向転換 | feedback_*.md に新規作成 or 既存更新 |
| 解決できなかった事象 | working-memory.md に「未完了タスク」として追記 |
| 重要な設計判断 | 02_Knowledge/decisions/ にADR形式で記録 |
| 規模超過 | /compact-memory で圧縮 |

これによりエージェントは

セッション開始時に working-memory.md を読み、前回の積み残しを認識
完了したエントリには [完了 YYYY-MM-DD] をタイトルに付与
確定したルールは別ファイルに昇格

を自律的に実行します。

運用してみて分かった3つのコツ

コツ1: タイトルに必ず日時とPJ識別子を入れる

## 2026-05-09 08:00 JST - Codex Hooks 修正バックアップの削除予約

このフォーマットを守るだけで、grep ベースの検索が劇的に楽になります。エージェントが「先週の障害なんだっけ？」と聞かれたとき、

grep -E "^## 2026-05" memory/working-memory.md

で1秒で答えが出ます。

コツ2: 「昇格先候補」を空欄で残さない

「とりあえずどこかに書いて後で考える」は、AIエージェント運用では 永久に「後」が来ません。

エントリ作成時に必ず昇格先候補を埋める。判断できなければ「不明・次回判断」と書く。空欄禁止。

コツ3: 月1回の圧縮ジョブを scheduled task で回す

[完了] タグ付きエントリが20件を超えたら自動で別ファイル（working-memory-archive-YYYY-MM.md）に切り出します。これをやらないと数ヶ月で1万行を超え、AIのコンテキストウィンドウを食い潰します。

筆者の環境では /compact-memory という Claude Code スキルで処理しています。実装は単純で、

[完了 YYYY-MM-DD] タグ付きエントリを正規表現で抽出
古い順に archive ファイルへ append
元ファイルからは削除

それだけです。

まとめ

AIエージェント向けの「未完了タスク置き場」は、TODOツールではなく 構造化された Markdown ファイル が向いている
working-memory.md に 種別 / 背景 / 次アクション / 昇格先候補 の4要素を必ず書く
完了したエントリは消さず [完了 YYYY-MM-DD] タグで残す（後続の圧縮ジョブの目印になる）
CLAUDE.md などのエージェント設定ファイルから「セッション開始時に読む」と明示することで、半自動的に運用が回る
月1回の圧縮ジョブ（grep ベースで十分）でファイル肥大化を防ぐ

「正本に書くほど確定していないが、忘れたら困る情報」の置き場所を持つだけで、AIエージェント運用の安定度は体感で2倍変わります。試してみてください。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up