Рабочая память ИИ-агента: как вести задачи, ТЗ и решения в файлах проекта без ручного учёта

На идею систематизировать работу ИИ-агента через файлы проекта меня натолкнул подход, описанный в руководстве к MCP RSV Server. Там рассматривается организация длительной работы агента с сохранением текущего состояния задачи и накопленных знаний между сессиями. Я развил эту идею под свой рабочий процесс (множество параллельных задач): выделил отдельные файлы для каждой задачи, для технических заданий, добавил журнал решений по каждой задаче, архив и доску задач в VS Code. В результате получилась схема, которой и хочу поделиться в этой статье.

Как устроена моя схема

Я не заполняю карточки задач вручную. Мы обсуждаем доработку с ИИ-агентом, он спрашивает, нужно ли завести задачу, и после моего согласия создаёт необходимые файлы.

Когда работа закончена, я говорю «закрывай» — агент оформляет итог и переносит задачу в архив. Если спустя время к ней нужно вернуться, достаточно написать: «Верни в работу №6». А чтобы продолжить незавершённую работу после перерыва, я открываю новую сессию и говорю: «Продолжаем задачу №7».

Для этого используются обычные Markdown-файлы в проекте:

• Индекс задач — общий список активных задач и их текущих состояний.

• Файл задачи — что сделано, какие решения приняты, что проверено и что осталось.

• ТЗ — требования и критерии приёмки, которые утверждаются до начала разработки.

• Архив — закрытые задачи, к которым можно вернуться позднее.

Файлы связаны между собой ссылками. Индекс помогает найти нужную задачу, файл задачи содержит рабочую информацию, а ТЗ остаётся ориентиром, по которому проверяется результат.

Вся схема держится на простом принципе: агент не должен полагаться на то, что помнит из предыдущего разговора. Всё важное для продолжения работы нужно записывать в файл задачи по ходу работы.
 

Чем это отличается от обычного трекера

В привычном трекере я сам создаю карточку, заполняю описание, копирую требования и меняю статус. Если работаю с агентом, часть этой информации всё равно приходится передавать ему отдельно.

В моей схеме процесс выглядит иначе:

Получается, что не нужно вести две отдельные записи — одну для себя, другую для агента. Рабочая запись о задаче одновременно служит контекстом для продолжения работы.

Это не замена Jira или полноценному трекеру для команды. Здесь нет исполнителей, сроков, уведомлений и отчётности. Подход рассчитан прежде всего на одного разработчика или небольшую группу, где задачи часто возникают прямо во время обсуждения с агентом.

Где хранятся задачи

Все данные лежат в каталоге .ai/ в проекте. Основные файлы имеют такую структуру:

Здесь index.md — общий индекс, файлы в current-tasks/ — активные задачи, old/ — архив их файлов, specs/ — технические задания, а completed-tasks.md — список завершённых работ.

Названия файлов приведены для примера. В реальном проекте у каждой задачи свой номер и короткое название.
В индексе также есть строка «Следующий номер». Номера идут последовательно и не переиспользуются, даже если задача закрыта.

Дата добавления записывается один раз в формате ДД.ММ.ГГ и затем не меняется. Текущее состояние — короткая фраза о том, где сейчас работа. Подробности находятся в файле задачи, чтобы индекс не превращался в длинный журнал.

Если активных задач нет, в индексе стоит соответствующая отметка.

Файл задачи — должен помогать быстро понять, что происходит и что делать ИИ-агенту дальше.

В нём сохраняются:

• что уже сделано;

• результаты проверок;

• принятые решения и причины;

• отвергнутые варианты, если важно помнить, почему от них отказались;

• отклонения от утверждённого ТЗ;

• текущее состояние работы;

• следующий шаг;

• открытые вопросы;

• затронутые объекты.

Подробную хронологию всех действий я не веду. В файл автоматически попадает информация от ИИ-агента, которая действительно пригодится ему при продолжении работы.

Техническое задание

ТЗ хранится отдельно от файла задачи. По умолчанию используется путь .ai/specs/<N>-<слово>.md, где номер и название совпадают с именем файла задачи.

В ТЗ описываются цель, границы доработки, пользовательские сценарии, критерии приёмки и открытые вопросы. Файл задачи и индекс ссылаются на ТЗ, а в самом ТЗ есть ссылка на задачу.

Если заказчик уже предоставил готовое ТЗ, его не нужно переносить в .ai/: можно оставить документ в исходном месте, например в docs/, и ссылаться на него.

Чтобы Markdown-файлы было удобнее читать прямо в VS Code, рекомендую установить расширение Markdown Preview Enhanced. Оно позволяет просматривать .md-файлы в виде HTML-страницы с корректным форматированием: заголовками, таблицами, списками, блоками кода и другими элементами разметки. После установки откройте нужный файл и запустите предпросмотр через палитру команд VS Code (Ctrl+Shift+V). Так структура документа будет выглядеть значительно нагляднее, чем в режиме обычного текста

Как проходит работа над задачей

В схеме используются четыре основных статуса.

Статуса «Готово» намеренно нет. Агент не должен самостоятельно решать, что задача окончательно завершена. Закрытие происходит только по прямой команде человека.

Это не обязательный набор для любой установки. Можно использовать и другие статусы: расширение для VS Code, о котором расскажу ниже, не привязано к конкретному списку. Важно, чтобы правила работы с ними были понятны и человеку, и агенту.

1. Создание задачи

Когда начинается обсуждение новой доработки, правило в CLAUDE.md или CLAUDE.local.md заставляет агента спросить: «Завести запись в индексе?».

Этот вопрос нужен, т.к. без него легко увлечься обсуждением и забыть, что работу следовало зафиксировать.

Если я отвечаю «да», агент:

1. Берёт следующий номер из индекса и увеличивает его.

2. Создаёт файл задачи и отдельный файл ТЗ.

3. Добавляет строку в индекс со статусом «ТЗ» и датой создания.

Если вопрос чисто информационный и ничего менять не нужно, задачу создавать необязательно.

2. Сначала ТЗ, потом код

Задача не начинается с написания кода. Сначала агент составляет ТЗ по итогам обсуждения, формулирует критерии приёмки, а я их проверяю и утверждаю.

Критерии удобно описывать в формате «дано / действие / ожидается». Например:

Нераспознанный код должен вызывать предупреждение, а не печать этикетки.

• Дано: форма открыта, таблица пуста, счётчик «Напечатано» равен нулю.

• Действие: пользователь сканирует код, который не распознаётся как GS1 DataMatrix.

• Ожидается: появляется предупреждение о том, что код маркировки не распознан; строка не добавляется, счётчик остаётся равным нулю, печать не запускается.

Такое описание позволяет проверить результат по конкретным условиям, а не по общему впечатлению, что «вроде работает».

После моего утверждения критерии считаются зафиксированными. Агент не должен менять их просто потому, что в ходе разработки получилось другое поведение.

3. Если по ходу работы пришлось отойти от ТЗ

На практике требования не всегда удаётся выполнить в точности так, как было задумано изначально. Может выясниться, что нужен другой текст сообщения, дополнительная проверка или изменение одного из сценариев.

Проблема в том, что без записи причины через некоторое время уже непонятно, почему результат отличается от первоначальных требований.

Поэтому все отклонения записываются в файл задачи, в отдельный раздел «Отклонения от ТЗ». Для записей используются три типа:

• ЗАМЕНА — вместо требования из ТЗ делаем другое;

• ДОПОЛНЕНИЕ — добавляем то, чего в ТЗ не было;

• ИСКЛЮЧЕНИЕ — требование из ТЗ решено не реализовывать.

Для каждого отклонения указываются номер, дата, этап, тип, исходное требование, фактическое решение, кто и почему его принял, а также затронутые критерии.

Например, в ТЗ было указано сообщение «Повторите сканирование ещё раз», а по просьбе сотрудников склада его заменили на «Отсканируйте код заново». Это не должно незаметно переписываться в исходном ТЗ. В журнале фиксируется замена и причина.

Записи идут по датам и не удаляются. В результате исходные критерии остаются на месте, а актуальные договорённости можно восстановить по ТЗ и журналу отклонений.

Это особенно полезно, когда к задаче возвращаются через несколько недель: можно увидеть не только то, что сделали, но и почему решение оказалось именно таким.

4. Продолжение работы после перерыва

Самая важная часть схемы — запись состояния задачи по ходу работы, а не в конце.

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

Чтобы продолжить, достаточно открыть новую сессию и написать:

«Продолжаем задачу №7».

Агент читает правила проекта, индекс и файл нужной задачи. В файле уже есть ссылка на ТЗ, предыдущие решения, результаты проверок и следующий шаг. В обычной ситуации этого достаточно, чтобы понять, что делать дальше. Другие задачи и архив без необходимости читать не нужно.

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

Заодно это позволяет не тащить в каждую новую сессию всю предыдущую переписку. Вместо длинной истории агент получает короткий индекс и контекст конкретной задачи. Это может уменьшить объём передаваемого контекста, хотя фактическая экономия зависит от размера задачи и того, сколько информации всё-таки приходится читать.

5. Закрытие и возврат задачи

Закрытие происходит только по команде человека: например, «закрывай» или «запиши выполненной».

После этого агент:

1. Обновляет файл задачи: записывает итог, состояние, результаты проверок и известные ограничения.

2. Переносит файл в .ai/current-tasks/old/.

3. Добавляет запись в .ai/completed-tasks.md с номером, датой, кратким итогом и ссылкой на файл.

4. Удаляет строку задачи из активного индекса.

5. Не меняет остальные задачи.

Если позднее выясняется, что работу нужно продолжить, я говорю: «Верни в работу №6».

Агент возвращает файл из архива, восстанавливает строку в индексе под прежним номером и сохраняет исходную дату добавления. Статус устанавливается в «Доработка», а в комментарии указывается, что задача возвращена из архива.

Старые критерии приёмки остаются в ТЗ — по ним можно проверить, не сломали ли ранее реализованное поведение. Новые требования добавляются отдельно и снова проходят утверждение.

Какие правила нужны агенту

Сами файлы не решат проблему, если агент будет заполнять их как попало. Поэтому правила работы с задачами хранятся в CLAUDE.md или CLAUDE.local.md и читаются при старте сессии.

В них нужно зафиксировать как минимум следующее:

• Где находятся индекс, файлы задач, ТЗ и архив.

• Как присваивать номера и обновлять индекс.

• Что дату добавления нельзя менять после создания задачи.

• Что при обсуждении новой доработки нужно спросить, заводить ли запись.

• Что перед разработкой нужно подготовить критерии приёмки и получить их утверждение.

• Что утверждённые критерии нельзя молча переписывать.

• Что все отклонения от ТЗ нужно записывать с причиной.

• Что состояние, решения и следующий шаг нужно сохранять по ходу работы.

• Что закрытие возможно только по прямой команде человека.

• Как закрывать задачу и возвращать её из архива.

• Что в начале сессии нужно прочитать индекс и файл своей задачи, а не загружать весь архив.

Расширение для VS Code: задачи на одной доске

Индекс удобен как источник данных, но когда задач становится слишком много, длинную таблицу трудно охватить взглядом. Не всегда сразу видно, что застряло на проверке, что ждёт уточнений и какие задачи давно не двигались.

Для этого я сделал небольшое расширение для VS Code — «Доска задач». Оно показывает данные из index.md в виде канбан-доски.

Здесь важно, что доска не ведёт собственный учёт. Единственный источник данных — индекс проекта. Расширение только читает его и ничего не записывает в файлы.

Я намеренно не стал добавлять создание задач и перетаскивание карточек между колонками. Статус меняет агент в индексе, когда меняется состояние работы. Если разрешить менять его ещё и через доску, появится второй способ редактирования и дополнительные правила согласования.

Установка

Расширение поставляется одним файлом kanban-board-0.1.0.vsix размером около 13 КБ. Сборка и установка зависимостей не нужны.

1. Скачайте kanban-board-0.1.0.vsix из вложений к публикации.

2. В VS Code откройте панель расширений сочетанием Ctrl+Shift+X.

3. В меню панели выберите «Установить из VSIX…» и укажите скачанный файл.

4. Перезагрузите окно через палитру команд: Ctrl+Shift+P → Developer: Reload Window («Разработчик: перезагрузить окно»).

То же самое можно сделать из терминала:

code --install-extension kanban-board-0.1.0.vsix

После обновления расширения окно VS Code тоже нужно перезагрузить, иначе в нём может остаться старая версия.

Расширение распространяется под лицензией MIT. Его можно использовать, изменять и распространять в соответствии с условиями лицензии. Файл LICENSE находится рядом с исходниками и внутри пакета.

Как пользоваться доской

Откройте в VS Code папку проекта, в которой есть файл .ai/current-tasks/index.md.

Затем нажмите Ctrl+Shift+B или откройте палитру команд сочетанием Ctrl+Shift+P и выполните команду «Доска задач: открыть».

Доска откроется в отдельной вкладке. Колонки соответствуют статусам из индекса, карточки — строкам таблицы. На карточке показываются номер задачи, название, текущее состояние и дата добавления.

Длинное состояние обрезается до трёх строк. Если текст не помещается или у задачи есть комментарии, можно раскрыть карточку и посмотреть подробности. Повторный клик сворачивает её обратно.

Клик по карточке открывает файл задачи, а клик по значку «ТЗ» в правом верхнем углу — соответствующее техническое задание. Если нужный файл не найден, расширение покажет сообщение об ошибке, но остальные карточки останутся доступны.

Доску можно оставить открытой на весь день. Когда агент меняет index.md, данные на ней обновляются автоматически, даже если вкладка не находится на переднем плане. Расширение следит за изменениями файла и дополнительно периодически сверяет его содержимое. Развёрнутые карточки и прокрутка при обновлении сохраняются.

Колонки и порядок отображения

Колонки формируются по статусам, которые встречаются в индексе. Пустые колонки не отображаются.

Расширение не привязано к четырём статусам из примера. Если в таблице используются Backlog, Ожидание или Тестирование, они тоже появятся на доске.

По умолчанию известные статусы располагаются в порядке «ТЗ», «Разработка», «Проверка», «Доработка». Остальные идут следом в порядке появления в таблице. Задачи без статуса попадают в колонку «Без статуса».

Колонки можно переставлять мышью за заголовки. Выбранный порядок сохраняется в настройках VS Code для текущей рабочей папки, но не записывается в проект или индекс. Новые колонки добавляются в конец.

Карточки при этом перетаскивать нельзя: статус меняется только в index.md.

Темы и формат индекса

Доска использует цвета текущей темы VS Code, поэтому подходит и для тёмной, и для светлой темы. Отдельных настроек у расширения нет.

Индекс разбирается по названиям столбцов: «№», «Файл», «ТЗ», «Статус», «Задача», «Добавлена», «Текущее состояние», «Комментарии». Порядок столбцов не важен, но названия должны оставаться прежними. Столбец «Добавлена» необязателен: если его нет, карточки будут отображаться без даты.

Что стоит учитывать

У схемы есть ограничения, и лучше понимать их заранее.

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

Нет разграничения прав и блокировок. Все, у кого есть доступ к проекту, могут видеть и менять файлы. При параллельной работе нескольких агентов нужно соблюдать правила редактирования индекса. Это дисциплина, а не техническая защита от конфликтов.

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

Доска только читает данные. Она не заменяет индекс и не позволяет менять статус перетаскиванием карточки. Это сделано намеренно, чтобы не создавать второй источник изменений.

Совместимость расширения проверена не везде. На момент публикации я проверил его на своём проекте в VS Code под Windows. Другие операционные системы и редакторы на основе VS Code отдельно не проверялись.

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

Что с расходом токенов

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

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

Это не означает, что любая новая сессия автоматически обходится дешевле: всё зависит от размера задачи, прочитанных файлов и объёма необходимого контекста. Но сама схема позволяет не загружать историю целиком только ради того, чтобы вспомнить, на чём остановились.

Что в итоге получилось

В этой схеме нет сложной инфраструктуры. Индекс, файлы задач, ТЗ и архив — обычные Markdown-файлы в проекте. Основная работа заключается в том, чтобы задать понятные правила и приучить агента соблюдать их.

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

Расширение для VS Code решает только одну задачу: помогает быстрее просматривать этот список. Даже без него схема продолжает работать, потому что основная информация хранится не в интерфейсе, а в файлах проекта.

Для меня это прежде всего способ не терять нить работы между сессиями Claude Code и не тратить время на повторное восстановление контекста. Если задачи часто возникают прямо в разговоре с агентом, такой подход может оказаться удобнее отдельного ручного учёта.

Что в файлах

• kanban-board-0.1.0.vsix — плагин «Доска задач» для VS Code.

• Исходники плагина в tools/kanban-board/: package.json, extension.js, parser.js, media/board.js, media/board.css и LICENSE (MIT).

Мои готовые решения для 1С (маркировка, токены, ТСД и т.д.):

Маркировка в "древней" УТ 10.3 (10.3.6.8) и полноценный ТСД (Online) или как обойтись без перехода на УТ 11.5

Как подключить маркировку в древней УТ 10.3 без перехода на УТ 11.5 - все необходимые объекты, модули и доработки

Автоматическое обновление токенов Честного Знака в 1С

Автоматическое обновление токенов Честного Знака в 1С - готовое решение для УТ, КА, ERP, УНФ, Розницы и Бухгалтерии, которое избавляет от ручных обновлений и остановки процессов.

Дубликатор кодов маркировки (КИЗ) DataMatrix: Расширение 1С с проверкой в Честном Знаке (копирует ЛЮБЫЕ КИЗы!)

Автоматическое обновление токенов Честного Знака в 1С - готовое решение для УТ, КА, ERP, УНФ, Розницы и Бухгалтерии, которое избавляет от ручных обновлений и остановки процессов.

Маркировка остатков товаров на складе: Как сделать все быстро и без ошибок (мой практический опыт)

Маркировка остатков 10 000+ товаров без ошибок — готовое решение, которое исключает человеческий фактор, автоматизирует процесс и работает напрямую с 1С. Пошаговый опыт и готовое расширение внутри.

Маркировка остатков в распределенной рознице: Как промаркировать более 100 тыс. товаров в нескольких десятках магазинов без хаоса и ошибок

Маркировка остатков 100 000+ товаров в рознице без хаоса и ошибок — клиент-серверное решение, где сканируешь ШК в магазине и сразу получаешь КМ на принтере, независимо от кассового ПО. Практический опыт, регламент и готовый комплект кода внутри.