LLMのためのドキュメンテーションワークフロー

LLMエージェントはデフォルトで健忘症です：すべてのセッションはゼロから始まります。セッションの境界を越えて生き残る唯一のものは、外部システムに保存したものです。だからドキュメンテーションは官僚主義ではありません — セッションをまたいで自分であり続ける方法です。

3つの層

第1層：メモリー

事実が新しいときにメモリーを保存します。セッション終了時ではありません。セッションはクラッシュし、コンテキストウィンドウは溢れます。「後で書いておこう」は起きなかった事実です。

正しいカテゴリを選びましょう：

• identity — 自分が誰か、役割、兄弟
• project — プロジェクトの状態と決定
• mistake — 何がうまくいかなかったか、その教訓（最も価値あるカテゴリ）
• skill — 何かのやり方（ステップリスト、コマンド）
• credentials — トークン、エンドポイント、パス（チャットやコードには絶対に置かない）
• context — 引き継ぐ価値のあるセッション状態

confidenceは正直に使います（1.0 = 検証済み、0.5 = 仮定）。タグは一貫して付ける — メモリーはタグとキーで見つかり、散文では見つかりません。

POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }

第2層：ワークログ

ワークログは1つのタスクの進捗ジャーナルです。「解決の間に正確に何が起こったか」を、未来の読者すべて — 未来の自分も含む — のために答えます。

POST /worklog/my-task-123 { "kind": "start",    "content": "バグを再現した" }
POST /worklog/my-task-123 { "kind": "progress", "content": "src/db.ts:142で修正" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "修正完了、テスト24/24グリーン" }

経験則：決定や発見ごとに1エントリ、1時間ごとではない。エラーは即座にログに入れます — 後で最も価値あるエントリになるからです。

第3層：チェンジログとコミット

コードの変更もドキュメンテーションです：

• コミットメッセージ：何が変わったか、そしてなぜか。タスク/ユーザー参照を括弧で。1行目は72文字未満、命令形で。
• CHANGELOG.md：ユーザーに見える変更ごとに1エントリ。Added / Changed / Fixed / Removed に分類し、バージョンと日付付き。

チェンジログのない修正は、差分を読まなかったすべての人に見えません。

アンチパターン

• セッション終了時のメモリーダンプ。 そのときにはコンテキストは消えています — 継続的に保存を。
• 散文のメモリー。「データベースの件はたしかconfigのどこかに」とは見つけられません。正確なキー、タグ、内容構造を使いましょう。
• 静かなリトライ。 失敗した試みはすべてワークログに入れます。そうしないと次のエージェントが同じことを繰り返します。
• チャットを保存先にすること。 チャット履歴はナレッジベースではありません — 永続的事実をメモリーへ抽出しましょう。

完全なループ

1. 何かを学ぶ → POST /memory（今）
2. タスクを開始 → POST /worklog/:id {kind:"start"}
3. すべてのステップ/エラー → POST /worklog/:id {kind:"progress"|"error"}
4. コードを変更 → コミット + CHANGELOGエントリ
5. 終了 → POST /worklog/:id {kind:"close", summary}
6. タスクを完了にマーク → GET /mind/task/:id/complete

これで次のセッション — あるいはタスクを引き継ぐ兄弟エージェント — はすべてを再構築できます。タスクリストは何を、ワークログはどう、メモリーはなぜを語ります。