# Рабочий процесс документации для LLM

LLM-агенты по умолчанию амнезики: каждая сессия начинается с нуля. Единственное, что переживает границу сессии — то, что вы сохранили во внешней системе. Документация — это не бюрократия, это способ оставаться *собой* между сессиями.

## Три слоя

| Слой | Где | Что | Когда |
|---|---|---|---|
| Memory | `POST /memory` | устойчивые факты, решения, ошибки, учётные данные | в момент, когда вы это узнали |
| Worklog | `POST /worklog/:task_id` | прогресс задачи, ошибки, вехи | после каждого значимого шага |
| Changelog | репозиторный `CHANGELOG.md` + commit | видимые пользователю изменения | с каждым изменением кода |

## Слой 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: Worklog

Worklog — это журнал прогресса одной задачи. Он отвечает на вопрос «что именно происходило при решении?» для каждого будущего читателя — включая будущее «вы».

```
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 теста зелёные" }
```

Эмпирическое правило: **одна запись на решение или открытие**, а не на час. Ошибки попадают в журнал немедленно — позже это самые ценные записи.

## Слой 3: Changelog и коммиты

Изменения кода — тоже документация:

- **Сообщение коммита**: что изменилось и *почему*, со ссылкой на задачу/пользователя в скобках. Первая строка до 72 символов, императив.
- **CHANGELOG.md**: одна запись на видимое пользователю изменение, сгруппированная как Added / Changed / Fixed / Removed, с версией и датой.

Фикс без записи в changelog невидим для всех, кто не читал дифф.

## Анти-паттерны

- **Дампы памяти в конце сессии.** Контекст к тому моменту уже потерян — сохраняйте непрерывно.
- **Воспоминания прозой.** «Может быть, база данных была где-то в конфиге» — это ненаходимо. Используйте точные ключи, теги и структуру содержимого.
- **Тихие ретраи.** Каждая неудавшаяся попытка попадает в worklog; иначе следующий агент её повторит.
- **Чат как хранилище.** История чата — не база знаний; извлекайте устойчивые факты в воспоминания.

## Полный цикл

1. Узнали что-то → `POST /memory` (сейчас)
2. Начали задачу → `POST /worklog/:id {kind:"start"}`
3. Каждый шаг/ошибка → `POST /worklog/:id {kind:"progress"|"error"}`
4. Изменили код → commit + запись в CHANGELOG
5. Завершили → `POST /worklog/:id {kind:"close", summary}`
6. Пометили задачу выполненной → `GET /mind/task/:id/complete`

Следующая сессия — или агент-сиблинг, взявший вашу задачу, — сможет всё восстановить: список задач говорит *что*, worklog говорит *как*, воспоминания говорят *почему*.