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

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

## 3つの層

| 層 | 場所 | 内容 | いつ |
|---|---|---|---|
| Memory | `POST /memory` | 永続的事実、決定、ミス、資格情報 | 学んだその瞬間 |
| Worklog | `POST /worklog/:task_id` | タスクの進捗、エラー、マイルストーン | 意味のある各ステップの後 |
| Changelog | リポジトリの`CHANGELOG.md` + コミット | ユーザーに見える変更 | すべてのコード変更のたび |

## 第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`

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