Проектный дневник для AI-сессий

Дата: 2026-05-18

Краткая идея

Проектный дневник - это компактный слой памяти между постоянными инструкциями проекта, планами работ и краткими сессионными summary. Его задача - помочь новой AI-сессии быстро понять, что недавно изменилось, какие решения уже приняты и где находится проект сейчас.

Дневник не является стенограммой чата, changelog, backlog, roadmap или заменой AGENTS.md. Это управляемая оперативная память проекта.

Главная проблема, которую решает дневник: один и тот же проект может продолжаться в нескольких чатах за день, но новая сессия не должна заново восстанавливать контекст из длинной истории переписки. При этом дневник не должен разрастаться в полотно текста. Поэтому дневник хранит только durable memory - сведения, которые будут полезны после сброса контекста.

Зачем нужен дневник

В типичном AI-workflow один проект живет долго, но отдельный чат лучше держать коротким. После завершения задачи пользователь запускает end-session, затем начинает новый чат и запускает new-session.

Без дневника новая сессия опирается только на:

• AGENTS.md - постоянные правила проекта;
• Summarizations.md - краткая сводка последней сессии;
• active ExecPlan - если есть большой план выполнения;
• текущее состояние файлов в репозитории.

Этого часто достаточно, но есть промежуточный тип информации:

• "сегодня добавили третий язык, теперь контент должен быть в RU/EN/AM";
• "решили не использовать WordPress";
• "нашли, что sitemap пока учитывает только две локали";
• "эта интеграция требует такой-то workaround";
• "дневной прогресс важен, но не тянет на постоянную инструкцию в AGENTS.md".

Такие сведения слишком конкретны для AGENTS.md, слишком краткоживущие для архитектурной документации, но слишком важны, чтобы терять их между чатами. Для них и нужен дневник.

Общая архитектура памяти

Мы разделили проектную память на несколько слоев:

AGENTS.md
  Постоянные правила проекта:
  команды, ограничения, conventions, definition of done.

Summarizations.md
  Компактный handoff последней сессии.

ExecPlan / active plans
  Пошаговый план большой задачи.

diary/current.md
  Короткий snapshot: где проект сейчас.

diary/decisions.md
  Долговечные решения, которые не надо переоткрывать.

diary/days/YYYY-MM-DD.md
  Значимые изменения по датам.

Такое разделение важно: дневник не должен превращаться в план, а план не должен превращаться в историю. AGENTS.md не должен хранить сессионный шум, а дневник не должен становиться постоянной политикой проекта.

Структура папки diary

В каждом проекте дневник живет в папке:

diary/
  README.md
  current.md
  decisions.md
  days/
    2026-05-18.md
    2026-05-19.md

Мы сознательно отказались от open-threads.md. Незавершенные пункты, если они важны только в рамках дня, остаются в days/YYYY-MM-DD.md в секции Carry Forward. Если это полноценный план, ему место в плановом файле или output планового skill.

Роли файлов

diary/README.md

README.md - это локальная конституция дневника проекта.

Он описывает:

• что считать durable memory;
• что писать;
• что не писать;
• лимиты размера;
• правила дедупликации;
• правила compaction;
• как работает Write Diary;
• как работает Read Diary;
• как дневник соотносится с AGENTS.md, Summarizations.md и планами.

Этот файл нужен, чтобы будущие AI-сессии не трактовали дневник по-разному. Глобальный skill задает базовый протокол, а локальный diary/README.md фиксирует правила внутри конкретного проекта.

diary/current.md

current.md - это короткий snapshot текущего состояния проекта.

Важно: это не план, не backlog и не список задач. Если у проекта уже есть skill для планирования или ExecPlan, current.md не должен дублировать его.

Смысл current.md:

• быстро показать, где проект находится сейчас;
• указать важный контекст;
• дать continuation hint - куда смотреть в первую очередь;
• напомнить границы: планы живут отдельно, постоянные правила живут в AGENTS.md.

Целевой размер: около 30 строк. Жесткий лимит: 50 строк.

diary/decisions.md

decisions.md хранит durable decisions - решения, которые будущие сессии не должны случайно переигрывать.

Примеры:

• проект поддерживает RU/EN/AM;
• все статьи должны создаваться в трех локалях;
• деплой идет через Vercel;
• auth реализуется через Supabase;
• не используем WordPress;
• выбран определенный формат данных или API contract.

Каждое решение получает ID:

D-YYYYMMDD-001
D-YYYYMMDD-002

Дневные файлы могут ссылаться на эти ID, чтобы не дублировать полное объяснение.

diary/days/YYYY-MM-DD.md

Дневной файл - это компактная запись значимых изменений за день.

Он не append-only в обычном смысле. Write Diary может переписывать дневной файл, объединять похожие пункты, удалять устаревшие carry-forward items и выносить durable decisions в decisions.md.

Целевой размер дневного файла: до 120 строк. Жесткий лимит: 200 строк.

Durable memory: что писать

В дневник пишется только то, что поможет продолжить проект после context reset.

Писать стоит, если изменились:

• цели проекта;
• scope;
• audience;
• языки, локали, валюты;
• роли пользователей;
• content model;
• архитектура;
• схема данных;
• API contract;
• интеграции;
• деплой;
• сборка;
• auth;
• permissions;
• storage;
• важные команды;
• внешние сервисы;
• workflow проекта.

Также стоит писать:

• non-obvious bugs;
• причины багов;
• workarounds;
• migration issues;
• compatibility rules;
• важные findings;
• verification status;
• решения, которые нельзя случайно переоткрывать;
• факты, которые явно пригодятся следующей AI-сессии.

Что не писать

Обычно не пишем:

• цвет кнопки;
• отступы;
• typography polish;
• мелкий copy polish;
• форматирование;
• lint-only правки;
• переименование локальных переменных;
• routine refactor без изменения поведения;
• список просмотренных файлов без вывода;
• временные ошибки, которые сразу исправлены;
• длинный вывод команд;
• повтор того, что уже есть в current.md, decisions.md или дневном файле.

Исключение: мелкая правка записывается, если она выражает durable rule. Например:

Все destructive actions должны использовать danger style.

Это уже не "поменяли цвет кнопки", а правило дизайн-системы.

Write Diary

Write Diary - это skill, который отвечает за создание и обновление дневника.

Он владеет:

• созданием diary/;
• созданием базовых файлов;
• решением, писать ли запись;
• фильтрацией важного и неважного;
• обновлением current.md;
• обновлением decisions.md;
• созданием или обновлением дневного файла;
• deduplication;
• compaction.

Если дневника нет, Write Diary создает:

diary/
  README.md
  current.md
  decisions.md
  days/
    YYYY-MM-DD.md

Если durable update нет, Write Diary не должен добавлять шум. Он может ответить, что обновление дневника не требуется.

Read Diary

Read Diary - это skill, который отвечает только за чтение дневника.

Он не редактирует файлы, не создает дневник и не выдумывает отсутствующий контекст.

Он читает:

• diary/README.md;
• diary/current.md;
• diary/decisions.md;
• выбранные файлы из diary/days/.

Примеры:

Read Diary за сегодня
Read Diary за 3 дня
Read Diary за последние 5 дней
Read Diary с 2026-05-15 по 2026-05-18

После чтения он должен вернуть компактный context warm-up:

Прочитал дневник: 2026-05-16..2026-05-18.

Current state:
- ...

Durable decisions:
- ...

Recent changes:
- ...

Carry forward:
- ...

Notes:
- ...

Интеграция с end-session и new-session

Мы встроили дневник в существующий session lifecycle.

end-session

end-session - это оркестратор завершения сессии.

Он не должен сам реализовывать правила дневника. Вместо этого он всегда вызывает project-diary-write.

Порядок:

1. update-exec-plan, если есть активный ExecPlan
2. summarizations - обновить Summarizations.md
3. project-diary-write - создать/обновить diary или пропустить, если durable update нет
4. create-agents-md через promote-lessons, только если появились постоянные repo-level lessons

Почему project-diary-write вызывается после Summarizations.md:

• summary уже выделяет важное из сессии;
• дневник может опереться на более ясный итог;
• AGENTS.md обновляется последним, потому что туда попадают только редкие постоянные правила.

new-session

new-session - это оркестратор старта новой сессии.

Он не создает дневник. Он только читает его, если diary/ уже существует.

Порядок:

1. AGENTS.md
2. Summarizations.md
3. .agent/PLANS.md
4. active ExecPlan
5. project-diary-read, если diary/ существует
6. optional CLAUDE.md, если нужен cross-tool context

Для дневника правило чтения такое:

Если есть сегодняшний diary/days/YYYY-MM-DD.md:
  читать последние 3 существующих дневных файла, включая сегодня.

Если сегодняшнего дневного файла нет:
  читать последние 2 существующих дневных файла.

Всегда читать:
  diary/README.md
  diary/current.md
  diary/decisions.md

Так новая сессия получает короткий recent context, но не читает всю историю проекта.

Почему new-session не создает diary

Мы обсудили вариант, при котором new-session создает пустой дневник, если его нет. От него отказались.

Причина: нормальный цикл работы выглядит так:

end-session -> новый чат -> new-session

Если end-session уже запускался, дневник либо создан, либо project-diary-write сознательно решил, что durable update не нужен. Поэтому new-session не должен менять файлы при старте.

Создание дневника - ответственность Write Diary / end-session, а не new-session.

Шаблон current.md

# Current State

Last updated: YYYY-MM-DD HH:MM

Purpose: short snapshot of where the project is now. This is not a plan, backlog, or replacement for `AGENTS.md`.

## Project Snapshot

- Project:
- Current state:
- Main active area:
- Recent meaningful change:

## Important Context

- Supported languages/locales:
- Important content or product rules:
- Important files or modules:
- Important commands or services:

## Continuation Hint

- If continuing work, first check:

## Boundaries

- Read `AGENTS.md` for permanent project instructions if it exists.
- Read `decisions.md` for durable decisions.
- Read recent `days/` files only when the user asks `Read Diary`.
- Detailed task plans belong in the project's planning file or planning skill output, not here.

Шаблон decisions.md

# Decisions

Purpose: record durable decisions that future AI sessions should not rediscover or casually reverse.

## Format

### D-YYYYMMDD-001 - Decision Title

- Date: YYYY-MM-DD
- Status: active
- Context: why the decision was needed.
- Decision: what was decided.
- Rationale: why this option was chosen.
- Consequences: what future work must assume or preserve.
- Applies to: files, modules, workflows, documents, or project areas.
- Replaces: D-YYYYMMDD-000 or none.

## Active Decisions

<!-- Keep newest first. -->

## Superseded Decisions

<!-- Move replaced decisions here. Keep their replacement ID. -->

Шаблон дневного файла

# YYYY-MM-DD

Purpose: compact daily project memory. This file is not a transcript.

## Snapshot

- Project state:
- Main focus:
- Next best action:

## Changes

-

## Decisions

-

## Findings

-

## Verification

-

## Carry Forward

-

Пример дневной записи

# 2026-05-18

Purpose: compact daily project memory. This file is not a transcript.

## Snapshot

- Project state: content pipeline now assumes three required locales.
- Main focus: localization scope.
- Next best action: check sitemap and article generation for AM support.

## Changes

- Added Armenian as a required project locale alongside Russian and English.
- Content tasks must no longer assume one article per topic.

## Decisions

- D-20260518-001 - Project requires RU/EN/AM content variants.

## Findings

- Existing sitemap logic may still assume only RU/EN.

## Verification

- Scope decision only; no code verification performed.

## Carry Forward

- Check sitemap locale handling.
- Update content generation prompts to require RU/EN/AM variants.

Дедупликация

Write Diary должен сравнивать пункты по смыслу, а не по строкам.

Правила:

• если новый пункт уточняет старый, заменить старый уточненным;
• если новый пункт отменяет старый, оставить только актуальное состояние;
• если несколько пунктов описывают одну проблему, объединить их в один finding;
• если decision уже есть в decisions.md, в дневнике оставить только ссылку на D-...;
• если carry-forward выполнен, удалить его из Carry Forward и записать результат в Changes или Verification.

Compaction

Если дневной файл приближается к 200 строкам:

1. Обновить Snapshot до последнего актуального состояния.
2. Объединить повторяющиеся записи.
3. Сохранить outcomes, decisions, findings, verification и carry-forward.
4. Удалить narrative, dead investigation paths, command noise и cosmetic-only details.
5. Перенести durable decisions в decisions.md.
6. Оставить в дневнике только ссылки на decision IDs.
7. Обновить current.md, только если изменился compact project snapshot.

Практический lifecycle

Обычная работа выглядит так:

1. Пользователь работает с AI в проекте.
2. В конце запускает end-session.
3. end-session обновляет план, summary и вызывает project-diary-write.
4. project-diary-write создает или обновляет diary.
5. Пользователь начинает новый чат.
6. В начале запускает new-session.
7. new-session читает AGENTS.md, summary, планы и вызывает project-diary-read.
8. AI получает короткий recent context и продолжает работу.

Термины и mental model

Эту систему проще понимать как context routing: разные типы знания не складываются в один большой файл, а маршрутизируются в разные memory targets.

Ключевая идея: не каждый факт заслуживает постоянного хранения. Если факт нужен только во время текущей задачи, он может остаться в чате. Если он нужен следующей сессии, он попадает в дневник. Если он должен стать правилом проекта, он уже кандидат в AGENTS.md.

Responsibility matrix

Эта матрица защищает систему от memory sprawl. Если новый факт непонятно куда положить, вопрос должен быть не "куда бы записать?", а "какую роль этот факт будет играть через несколько дней?".

Почему это не wiki

Wiki обычно стремится быть справочником: страницы, темы, связи, объяснения. Проектный дневник решает другую задачу. Он не описывает весь проект, а ускоряет continuation.

Wiki отвечает:

Что это за система и как она устроена?

Дневник отвечает:

Что изменилось недавно, что уже решено, и откуда продолжать?

Поэтому дневник допускает более плотный формат: bullets, короткие статусы, file paths, decision IDs, verification notes. Ему не нужна литературная полнота. Ему нужен высокий signal-to-token ratio.

Read/write split

Мы намеренно разделили операции чтения и записи.

Write Diary
  mutates files
  creates diary/
  filters durable memory
  compacts daily notes
  updates decisions/current/day files

Read Diary
  reads files
  does not mutate
  does not create diary/
  does not invent missing context
  returns compact startup context

Это важная engineering boundary. Если один skill одновременно читает, пишет, создает, интерпретирует и планирует, он быстро начинает смешивать ответственности. Отдельный write path позволяет жестко контролировать persistence. Отдельный read path делает session startup предсказуемым и дешевым.

Lifecycle routing

working session
  |
  v
end-session
  |
  +--> update-exec-plan      # если есть активный план
  +--> summarizations        # compact restart file
  +--> project-diary-write   # durable memory only
  +--> create-agents-md      # только редкие permanent lessons

new chat
  |
  v
new-session
  |
  +--> AGENTS.md
  +--> Summarizations.md
  +--> active ExecPlan
  +--> project-diary-read    # если diary/ существует

В этой схеме end-session и new-session не знают деталей дневника. Они только вызывают специализированные skills. Это сохраняет orchestration layer тонким.

Классификация записи

Перед записью Write Diary должен классифицировать факт:

Такая классификация защищает дневник от превращения в backlog. Важно, что один факт может иметь две проекции: краткое событие дня в days/ и устойчивое решение в decisions.md.

Signal examples

Хороший дневниковый пункт:

- Added Armenian as a required locale alongside Russian and English.
- Future content tasks must produce RU/EN/AM variants.

Почему это signal:

• меняет scope;
• влияет на будущие задачи;
• предотвращает неверные assumptions;
• не требует чтения старого чата.

Плохой дневниковый пункт:

- Changed button spacing and adjusted some text.

Почему это noise:

• нет durable consequence;
• не ясно, где и зачем;
• не помогает следующей сессии;
• похоже на changelog или commit detail.

Write Diary как persistence gate

Write Diary работает как persistence gate. Его задача не в том, чтобы "что-то записать", а в том, чтобы решить, заслуживает ли информация записи.

Алгоритм:

collect candidate facts
classify durable vs non-durable
drop cosmetic/noisy facts
merge with existing daily note
update decisions if a durable decision exists
update current only if snapshot changed
compact if limits are close

Самый важный outcome иногда выглядит так:

No durable diary update needed.

Это не ошибка. Это правильная защита от entropy.

Read Diary как context warm-up

Read Diary не должен становиться full project scan. Его задача - прогреть контекст новой сессии минимальным количеством high-signal файлов.

Default startup read:

diary/README.md
diary/current.md
diary/decisions.md
latest 2-3 diary/days/*.md

Почему не читаем все:

• старые дневные записи могут быть superseded;
• decisions уже вынесены в отдельный файл;
• current snapshot должен содержать актуальную правду;
• чтение всей истории разрушает token economy.

Если нужно историческое расследование, пользователь может явно запросить диапазон:

Read Diary с 2026-05-15 по 2026-05-18

Token economy

Цель дневника - не добавить еще один обязательный документ, а уменьшить стоимость восстановления контекста.

Правильная token economy выглядит так:

Дневник экономит токены только пока он:

• компактный;
• выборочно читается;
• не дублирует plan и summary;
• не хранит косметику;
• регулярно уплотняется;
• отделяет decisions от daily notes.

Если дневник начинает читаться целиком каждый раз, он превращается из memory optimization в memory overhead.

Failure modes

Implementation checklist

Минимальная реализация:

1. Создать global skill project-diary-write.
2. Создать global skill project-diary-read.
3. Встроить project-diary-write в end-session.
4. Встроить project-diary-read в new-session.
5. Разрешить Write Diary создавать diary/ при первом durable update.
6. Запретить new-session создавать diary/.
7. Держать current.md коротким snapshot.
8. Переносить durable decisions в decisions.md.

Проверка внедрения:

end-session должен вызывать Write Diary
new-session должен вызывать Read Diary
Read Diary не должен писать файлы
Write Diary должен иметь право сказать "no update needed"
daily files не должны становиться append-only transcript

Расширенный пример routing

Факт: "Добавили Armenian как обязательную локаль"
Route:
  days/YYYY-MM-DD.md -> Changes
  decisions.md -> D-YYYYMMDD-001
  current.md -> Supported languages/locales

Факт: "Поменяли цвет кнопки"
Route:
  none

Факт: "Все destructive actions теперь должны быть danger style"
Route:
  decisions.md -> durable design decision
  AGENTS.md -> только если это permanent repo convention

Факт: "Следующим шагом надо дописать sitemap"
Route:
  plan file, если это часть плана
  Carry Forward, если это короткий дневной хвост

Критерий качества

Дневник работает правильно, если новая AI-сессия после чтения понимает:

• что сейчас правда;
• что недавно изменилось;
• какие решения нельзя случайно переиграть;
• что было проверено;
• где смотреть дальше;
• какие недавние факты важны, но еще не являются постоянными правилами проекта.

Если запись не помогает этому, ее не нужно писать.