Я постепенно пришёл к тому, что проектная документация нужна не столько для отчётности и даже не столько для людей, сколько для сохранения рабочего контекста.
Особенно это стало заметно при работе с AI-агентами. Каждый новый чат фактически начинает работу заново. Он не помнит, почему мы приняли конкретное решение, какое направление сейчас главное, что уже проверено, где лежат результаты и какие ограничения нельзя нарушать.
Можно каждый раз пересказывать всё заново. Но тогда значительная часть работы превращается в восстановление контекста.
Поэтому основная память должна находиться не внутри отдельного чата, а внутри самого проекта
Чаты и агенты могут меняться, а структура проекта, решения, текущее состояние и правила работы сохраняются.
Коротко, как это устроено
В моей системе проект представляет собой не просто папку с файлами. Это постоянный владелец определённой цели, продукта, системы или функции.
У каждого проекта есть:
. понятная цель и границы;
. запись в общем реестре проектов;
. единая точка входа для AI-агентов;
. набор документов с разными зонами ответственности;
. текущее состояние;
. ближайшие задачи;
. история решений;
. операционные инструкции;
. память о проведённых сессиях и полученных уроках.
Вся эта система строится на нескольких принципах.
Документацию читает и поддерживает система, а не пользователь
Контекст раскрывается прогрессивно: сначала агент получает базовую информацию, а дополнительные документы подключает только по мере усложнения или специализации задачи
Агент самостоятельно отражает подтверждённые факты, но не принимает за человека управленческие решения
Новая работа начинается очень просто:
Проект:
<название проекта>
Задача:
<что нужно сделать>Пользователю не нужно помнить, какие документы должен прочитать агент. Это определяет сам проект.
Агент находит проект в реестре, открывает его инструкции, определяет тип задачи и читает только тот набор документов, который нужен для этой конкретной работы.
После завершения он тоже не обновляет всю документацию подряд. Он меняет только те документы, смысл которых действительно изменился.
Человек формулирует задачу и принимает решения. Система сама восстанавливает контекст, понимает, какие документы ей нужны, и поддерживает их актуальное состояние.
Как создаётся новый проект
Когда появляется новая рабочая область, я сначала определяю, действительно ли это отдельный проект.
Для меня проектом становится то, что имеет постоянную ответственность: продукт, платформа, функция или самостоятельная система с собственными границами и жизненным циклом.
Если речь идёт о временном результате, который затрагивает несколько проектов, это скорее инициатива. Инициатива заканчивается после достижения результата. Проект остаётся владельцем своей области и после завершения инициативы.
Проект является постоянным владельцем области, а инициатива является временным результатом
После определения границ проект создаётся в несколько шагов:
- Создаётся отдельная папка проекта.
- В неё переносится стандартный шаблон проектной документации.
- Заполняются цель, границы, текущее состояние и первые задачи.
- Проект добавляется в общий реестр.
- Вся дальнейшая работа ведётся внутри его границ.
Общий реестр важен не только как список. Он отвечает на вопрос, какие проекты действительно существуют, за что каждый из них отвечает и где проходит граница между ними.
Просто наличие папки ещё не делает рабочую область проектом
Это позволяет не выдавать временные каталоги, эксперименты, результаты отдельных запусков или промежуточные материалы за самостоятельные проекты.
Почему документов несколько
Сначала может показаться, что такое количество документов избыточно. Почему бы не хранить всё в одном большом файле?
Проблема в том, что разные виды информации живут в разных временных горизонтах.
Ближайшая задача может измениться завтра. Текущее состояние проекта может измениться через неделю. Архитектурное решение может действовать несколько лет. История сессий должна сохраняться, но не мешать восстановлению актуального контекста.
Если всё это хранить вместе, документ довольно быстро становится одновременно длинным, устаревшим и противоречивым.
Я разделяю документы не по формальным типам файлов, а по назначению и сроку жизни информации
Принцип прогрессивного развёртывания контекста
В основе этой структуры лежит ещё один важный для меня принцип: прогрессивное развёртывание контекста.
Я не хочу, чтобы агент перед каждой задачей загружал всю документацию проекта, всю историю решений, все инструкции и все специализированные стандарты. Такой подход не только расходует лишний контекст, но и увеличивает вероятность того, что агент отвлечётся на информацию, которая не относится к текущей задаче.
Контекст должен раскрываться постепенно: от общего к конкретному и по мере усложнения задачи
Сначала агент получает базовую информацию: что это за проект, в каком состоянии он находится и какая работа сейчас актуальна.
Если задача небольшая, этого может быть достаточно.
Если задача затрагивает устройство системы, агент дополнительно открывает архитектуру и журнал решений.
Если работа относится к повторяемой операции, подключается runbook.
Если появляется вопрос стратегии, агент обращается к roadmap и памяти проекта.
Если задача касается узкой предметной области, данных, безопасности, релиза или другой специализированной темы, подключаются соответствующие стандарты и дополнительные инструкции.
То есть проектная документация работает не как одна большая инструкция, которую нужно прочитать целиком. Она работает как несколько уровней контекста.
Агент получает не максимум доступной информации, а необходимый объём информации для текущего уровня задачи
Роль маршрутизатора выполняет AGENTS.md. Он определяет, с какого минимального набора начать и при каких условиях нужно перейти на следующий уровень глубины.
Именно поэтому документы разделены по назначению. Такое разделение помогает не только поддерживать порядок, но и управлять тем, когда и какой контекст становится доступен агенту.
AGENTS.md: правила работы агента внутри проекта
AGENTS.md является единой точкой входа для AI-агента.
В нём описывается не сам продукт, а порядок работы с проектом:
. как начинать новую сессию;
. как определить тип задачи;
. какие документы читать;
. какие ограничения соблюдать;
. какие проверки выполнять;
. какие документы обновлять после завершения;
. когда нужно остановиться и запросить решение человека.
Например, исправление ошибки, исследование, новая функция и архитектурное изменение требуют разного контекста.
Для небольшой ошибки агенту обычно достаточно прочитать описание проекта, текущее состояние, список задач, открытые проблемы и затронутые файлы.
Для архитектурного изменения уже понадобятся архитектура, память проекта, журнал решений и, возможно, roadmap.
Агент не загружает всю историю проекта на всякий случай. Он сначала определяет характер работы, а затем читает минимально необходимый набор документов
README.md: что это вообще за проект
README.md отвечает на базовые вопросы:
. что делает проект;
. для кого он существует;
. какой результат должен давать;
. где находятся основные точки входа;
. какие источники являются основными;
. какие ограничения особенно важны.
Это первый содержательный документ для человека, который впервые видит проект.
Я стараюсь не превращать README в полную энциклопедию.
Задача README не рассказать всю историю проекта, а помочь быстро понять его назначение и структуру
Здесь же могут находиться стандартные формулировки повторяющихся запросов, ссылки на основные компоненты и короткое объяснение того, как начать работу.
PROJECT_MEMORY.md: устойчивая память проекта
PROJECT_MEMORY.md хранит информацию, которая должна пережить отдельные задачи и сессии.
Обычно это:
. основная цель проекта;
. ключевые пользователи;
. важные сценарии;
. источники требований и данных;
. устойчивые правила;
. общий рабочий процесс;
. расположение основных результатов.
Это не журнал событий. Если вчера была выполнена небольшая задача, она не обязательно должна попадать в память проекта.
В память попадает то, что новый агент должен знать и через несколько месяцев, чтобы правильно понимать проект
Я стараюсь держать этот документ коротким. Подробная история может храниться отдельно, но рабочая память должна оставаться актуальной и пригодной для быстрого восстановления контекста.
PROJECT_STATE.md: где проект находится сейчас
PROJECT_STATE.md описывает настоящее состояние проекта.
В нём фиксируются:
. текущий фокус;
. последний устойчивый результат;
. открытая работа;
. известные ограничения;
. основные риски;
. информация для следующей сессии.
Если PROJECT_MEMORY.md отвечает на вопрос «Что это за проект в целом?», то PROJECT_STATE.md отвечает на вопрос «Что происходит с ним сейчас?».
Следующий человек или агент не должен перечитывать всю историю, чтобы понять, на чём остановилась предыдущая сессия
TASKS.md: ближайшая исполнимая работа
TASKS.md содержит оперативный backlog проекта.
Я разделяю его как минимум на несколько горизонтов:
. Now: то, что действительно выполняется или готово к выполнению;
. Next: ближайшие следующие задачи;
. Later: отложенная работа;
. Done: завершённые задачи, если их полезно пока сохранить.
Здесь важно не превращать Now в длинный список всех пожеланий. Если там десятки пунктов, он перестаёт показывать реальный фокус.
TASKS.md является списком исполнимой работы, а не складом всех когда-либо появившихся идей
ISSUES.md: наблюдения ещё не являются задачами
ISSUES.md нужен для сохранения ошибок, проблем, улучшений, идей, наблюдений и технического долга.
Для меня принципиально важно отделять обнаруженную проблему от решения начать работу над ней.
Если агент заметил потенциальное улучшение, это не означает, что проект автоматически должен расширить текущий объём работы. Сначала наблюдение фиксируется. После этого его можно исследовать, определить причины, рассмотреть варианты решения и принять человеческое решение.
Внутри записи я разделяю:
. наблюдаемые факты;
. гипотезы;
. исключённые причины;
. недостающие свидетельства;
. возможные решения;
. рекомендацию агента;
. решение человека;
. способ проверки результата.
Одна и та же проблема сохраняет стабильный идентификатор на всём жизненном цикле. Анализ и варианты решения остаются рядом с исходным наблюдением.
Наблюдение ещё не является задачей, рекомендация агента ещё не является решением человека
В TASKS.md такая запись попадает только после явного решения начать работу. В ROADMAP.md она попадает только в том случае, если действительно меняет стратегическое направление.
Это защищает проект от ситуации, когда каждое замечание агента незаметно превращается в обязательство команды.
ROADMAP.md: направление, а не текущий список дел
ROADMAP.md описывает долгосрочную траекторию проекта.
Здесь находятся:
. долгосрочная цель;
. видение будущего состояния;
. этапы развития;
. ожидаемые результаты этапов;
. зависимости;
. стратегические риски;
. критерии завершения этапов.
Roadmap не должен дублировать текущий backlog.
Задача может быть важной и срочной, но при этом не менять направление проекта. Тогда ей место в TASKS.md.
И наоборот, стратегический этап может быть важен, хотя конкретная работа по нему ещё не готова к выполнению.
Стратегия хранится в ROADMAP.md, а ближайшие действия в TASKS.md
ARCHITECTURE.md: как проект фактически устроен
ARCHITECTURE.md описывает устройство проекта:
. основные компоненты;
. связи между ними;
. потоки данных;
. входы и выходы;
. внешние зависимости;
. обязательные проверки.
Мне важно, чтобы этот документ описывал фактическую архитектуру, а не желаемую картину, которая пока существует только в обсуждении.
Если рассматривается возможное будущее изменение, оно может находиться в исследовании или проекте решения. В основную архитектуру оно попадает после принятия и реализации.
Архитектура должна описывать то, как система действительно устроена сейчас
Для простого проекта архитектурный документ может быть совсем небольшим. Его размер должен соответствовать сложности системы.
DECISIONS.md: почему мы сделали именно так
DECISIONS.md хранит решения с долгосрочным эффектом.
У записи обычно есть четыре части:
. контекст;
. принятое решение;
. статус;
. последствия и ограничения.
Этот документ помогает не только помнить, что было решено, но и понимать почему.
Без такого журнала через некоторое время легко вернуться к уже рассмотренному варианту, не вспомнить причины отказа или принять противоположное решение на основании неполного контекста.
Не каждое рабочее действие является решением. В DECISIONS.md попадают только выборы с долгосрочным эффектом
SESSION_LOG.md: что происходило в конкретной сессии
SESSION_LOG.md представляет собой хронологический журнал работы.
В записи сессии обычно достаточно четырёх частей:
. цель;
. что было изменено;
. что было проверено;
. что делать дальше.
Это не текущая память проекта и не changelog продукта.
Журнал сессий нужен для восстановления последовательности работы и для передачи результата между исполнителями. Он показывает, что происходило, но не должен заставлять следующего агента читать всю историю перед началом задачи.
Актуальное состояние из журнала переносится в PROJECT_STATE.md, если оно действительно изменилось.
SESSION_LOG.md хранит ход работы, а PROJECT_STATE.md хранит её актуальный итог
CHANGELOG.md: устойчивые изменения
CHANGELOG.md фиксирует изменения, которые стали частью проекта:
. добавленные возможности;
. изменённое поведение;
. исправления;
. удалённые элементы;
. существенные изменения структуры или документации.
Он отличается от SESSION_LOG.md.
Сессия может закончиться исследованием без изменения продукта. Тогда запись в журнале сессий нужна, а в changelog добавлять нечего.
И наоборот, changelog должен говорить не о том, что агент открывал файлы и запускал проверки, а о том, что устойчиво изменилось для проекта или его пользователей.
SESSION_LOG.md отвечает на вопрос «Что мы делали?», а CHANGELOG.md на вопрос «Что устойчиво изменилось?»
RUNBOOK.md: как выполнять повторяемую работу
RUNBOOK.md содержит инструкции для повторяемых процессов.
Например:
. как подготовить входные данные;
. как выполнить типовую операцию;
. как проверить результат;
. как подготовить выпуск;
. как остановить процесс;
. как восстановиться после ошибки;
. как завершить сессию.
Если одно и то же действие приходится несколько раз объяснять новым людям или агентам, это хороший кандидат для runbook.
Цель RUNBOOK.md не описать весь проект, а обеспечить воспроизводимое выполнение конкретной операции
RETROSPECTIVE.md: чему проект научился
RETROSPECTIVE.md хранит повторяемые уроки.
Здесь можно зафиксировать:
. что произошло;
. почему это оказалось важным;
. какое изменение стоит внести;
. куда этот урок должен быть перенесён.
Некоторые уроки остаются внутри проекта. Другие оказываются полезными для нескольких проектов.
Если урок превращается в обязательное ограничение, он может стать стандартом. Если это проверенный способ решения задачи, он может стать паттерном. Если это готовая структура для повторного использования, он может попасть в шаблон нового проекта.
Проект должен не только сохранять свою историю, но и постепенно улучшать всё рабочее пространство
Дополнительные каталоги
Кроме документов, в проекте обычно есть две простые зоны:
. work/: промежуточные материалы, исследования и черновики;
. outputs/: финальные или пользовательские результаты.
Это помогает не смешивать рабочий процесс с готовыми артефактами и основной памятью проекта.
Как агенты используют всю эту систему
Самое важное здесь не сами файлы, а последовательность работы.
Сначала агент определяет проект. Если проект ещё не выбран, он обращается к общему реестру, а не пытается угадать проект по названию папки.
Затем он открывает AGENTS.md проекта, определяет тип задачи и выбирает минимальный набор документов.
Перед содержательной работой агент также проверяет открытые проблемы, связанные с текущей задачей. Он может предложить учесть близкое улучшение, но не должен молча расширять работу.
После выполнения агент проверяет результат способом, соответствующим риску, и обновляет только нужные документы.
Например, после небольшого исправления могут измениться:
. SESSION_LOG.md, потому что была рабочая сессия;
. TASKS.md, потому что задача завершена;
. CHANGELOG.md, если изменилось устойчивое поведение;
. PROJECT_STATE.md, если исправление изменило текущее состояние проекта.
Но это не означает, что нужно автоматически переписывать архитектуру, roadmap, память и журнал решений.
Каждый документ обновляется только тогда, когда изменилось то, за что он отвечает
Стандарты, паттерны и шаблоны
Над проектами у меня существует ещё три уровня инженерного знания.
Стандарты описывают обязательные ограничения и правила. Например, правила работы с данными, изменениями, проблемами, релизами или внешними системами.
Паттерны описывают проверенные способы решения типовых задач. Их можно применять, если они подходят проекту, но это не обязательно универсальный запрет или требование.
Шаблоны представляют собой готовые заготовки. Шаблон проекта как раз создаёт исходный набор документов и структуру каталогов.
Стандарт отвечает на вопрос «Что обязательно?», паттерн на вопрос «Как это можно хорошо решить?», шаблон на вопрос «С чего начать?»
Тексты общих стандартов не копируются в каждый проект. Проект ссылается на общий стандарт и хранит только локальные уточнения.
Иначе довольно быстро появятся несколько расходящихся версий одного правила.
Как завершается работа
Для меня важен не только запуск проекта, но и корректное завершение каждой сессии.
В конце должно быть понятно:
. что выполнено;
. что проверено;
. какие файлы изменены;
. что осталось сделать;
. какие есть риски;
. какие решения требуются от человека;
. где находится результат;
. доступен ли он только в рабочей версии или уже стал частью основной версии проекта.
Подготовленный, опубликованный, интегрированный и выпущенный результат являются разными состояниями
Сам факт того, что агент что-то подготовил, ещё не означает, что это стало общей версией проекта или дошло до пользователя.
Кто поддерживает документацию актуальной
В моей системе я сам практически не захожу в эти файлы и не обновляю их вручную. Это делает агент как часть работы над проектом.
В конце задачи он определяет, какие документы действительно изменились по смыслу, актуализирует их и сообщает мне, что именно было обновлено.
Но самостоятельность агента здесь ограничена.
Агент без отдельного вопроса отражает подтверждённые факты, но не принимает за меня управленческие решения
Без отдельного согласования агент может:
. записать в SESSION_LOG.md, что было сделано и проверено;
. обновить PROJECT_STATE.md, если фактически изменилось состояние проекта, ограничения, риски или передача работы;
. отметить выполненную задачу в TASKS.md;
. добавить в CHANGELOG.md уже произошедшее устойчивое изменение;
. актуализировать архитектуру или runbook после уже разрешённого и выполненного изменения;
. зафиксировать конкретную обнаруженную проблему в ISSUES.md со статусом наблюдения, не превращая её автоматически в задачу.
Агент спрашивает меня, если запись в документацию будет означать новое решение или обязательство:
. добавить новую работу в исполняемый backlog;
. продвинуть проблему из ISSUES.md в TASKS.md или ROADMAP.md;
. изменить приоритет, владельца, срок или границы задачи;
. изменить стратегию, этап roadmap, границы проекта или архитектурное направление;
. записать принятое долгосрочное решение в DECISIONS.md;
. выбрать решение проблемы, принять риск, отложить или отклонить работу;
. изменить общий стандарт, паттерн, шаблон или структуру рабочего пространства;
. сделать вывод там, где факты неполные, противоречат друг другу или допускают несколько трактовок.
Если такое решение уже было явно принято мной в рамках текущей задачи, агент не спрашивает второй раз только ради его отражения в документации. Он фиксирует принятое решение и показывает, что именно изменил.
Граница проходит не между ручным и автоматическим редактированием файлов, а между фиксацией фактов и принятием решений
Для меня это важная часть всей системы. Документация остаётся актуальной без моей ручной работы, но агент не получает право незаметно менять направление проекта, создавать новые обязательства или выдавать свою рекомендацию за моё решение.
С чего я бы предложил начать новичку
Полный набор документов появился у меня не сразу, и я не думаю, что человеку без проектной документации нужно в первый день создавать тринадцать файлов и пытаться идеально их заполнить.
Начинать стоит не с полного комплекта документов, а с минимального рабочего цикла
Для начала достаточно четырёх документов.
1. README.md
Запишите:
. цель проекта;
. для кого он существует;
. какой результат должен давать;
. основные ограничения;
. где лежат рабочие материалы и результаты.
2. PROJECT_STATE.md
Запишите:
. где проект находится сейчас;
. что является текущим фокусом;
. что уже работает;
. что не работает;
. какие есть ограничения и риски;
. что должен знать следующий исполнитель.
3. TASKS.md
Разделите работу хотя бы на:
. сейчас;
. дальше;
. позже;
. завершено.
Не пытайтесь сразу перенести туда все идеи. Оставьте в разделе «сейчас» только несколько действительно исполнимых задач.
4. SESSION_LOG.md
После каждой содержательной сессии оставляйте четыре коротких ответа:
. какая была цель;
. что изменилось;
. что проверено;
. какой следующий шаг.
Этого уже достаточно, чтобы перестать полностью зависеть от памяти отдельного человека или истории одного чата.
Если в проекте работают AI-агенты, я бы сразу добавил пятый документ.
5. AGENTS.md
В нём достаточно описать:
. с каких документов начинать;
. какие действия запрещены;
. какие проверки обязательны;
. что обновлять после завершения;
. когда агент должен остановиться и обратиться к человеку.
Вторым этапом я бы добавил:
. ISSUES.md, когда появятся наблюдения, которые ещё не стали задачами;
. DECISIONS.md, когда появятся первые долгосрочные решения;
. RUNBOOK.md, когда начнут повторяться одни и те же операции.
Архитектуру, roadmap, changelog, устойчивую память и ретроспективу можно добавлять по мере реальной необходимости.
Пустые или формально заполненные документы не создают память проекта
Сначала важно сформировать минимальный рабочий цикл:
понять проект
→ увидеть текущее состояние
→ выбрать следующую задачу
→ выполнить и проверить
→ оставить понятную передачу состоянияОстальные документы появляются тогда, когда информации становится тесно в минимальном наборе и возникает понятная причина разделить её по назначению.
В моём текущем опыте ценность этой системы именно в этом. Она не требует от человека помнить структуру документации, но позволяет новому человеку или агенту продолжить работу без полного пересказа всей истории.
Документы становятся не архивом после проекта, а частью самой работы
Приложение. Как поручить AI-агенту создать свой стандарт проектной документации
Это приложение можно передать AI-агенту вместе со статьёй.
Статья объясняет принципы и мой способ организации проектной документации. Приложение превращает эти принципы в алгоритм, по которому агент сможет проанализировать рабочее пространство другого человека и предложить подходящую ему систему.
Статья является референсом, а не шаблоном, который нужно скопировать без изменений
Количество документов, их названия, глубина правил и границы самостоятельности агента должны соответствовать реальной сложности конкретного рабочего пространства.
Инструкция агенту
Тебе передана статья с описанием системы проектной документации.
Твоя задача: помочь пользователю разработать собственный стандарт проектной документации, а после отдельного согласования создать или адаптировать необходимые документы.
Работай в два этапа.
Этап 1. Анализ и проект стандарта
На этом этапе ничего не создавай, не удаляй, не перемещай и не переписывай.
Сначала изучи существующее рабочее пространство в разрешённых пользователем границах. Если документация уже существует, не предлагай заменять её автоматически. Определи, что можно сохранить, что требует уточнения и каких элементов действительно не хватает.
После анализа подготовь проект системы и остановись для согласования.
Этап 2. Создание и внедрение
Переходи к созданию или изменению файлов только после того, как пользователь явно согласовал:
. структуру системы;
. перечень документов;
. назначение каждого документа;
. границы самостоятельности агента;
. точный объём изменений.
Согласование общей идеи не считай разрешением на удаление, перенос или перезапись существующих материалов.
Сначала проект стандарта, затем решение человека, и только после этого создание файлов
Шаг 1. Определи границы рабочего пространства
Сначала установи:
. что пользователь считает проектом;
. какие постоянные проекты уже существуют;
. какие рабочие области являются временными задачами, экспериментами или инициативами;
. где хранятся рабочие материалы и итоговые результаты;
. работают ли в пространстве другие люди или AI-агенты;
. какие данные, действия и документы требуют особой осторожности;
. используется ли Git, облачное хранилище, локальная папка или другая система версий.
Не считай каждую папку отдельным проектом.
Постоянный проект должен иметь собственную цель, границы, ответственность и жизненный цикл. Временный результат или сквозная работа могут быть задачей или инициативой внутри существующего проекта.
Шаг 2. Задай только необходимые вопросы
Не заставляй пользователя заполнять большую анкету, если часть ответов уже можно получить из доступной структуры и документов.
Задавай вопросы только там, где отсутствие ответа существенно меняет предлагаемую систему.
Минимально нужно понять:
. какие результаты создаёт пользователь;
. сколько у него постоянных проектов;
. кто продолжает работу после него;
. используются ли AI-агенты;
. какие виды задач повторяются;
. какие решения пользователь хочет оставлять только за собой;
. насколько формальной и подробной должна быть документация.
Если ответ не получен, не придумывай его. Отметь значение как неизвестное и покажи, как эта неопределённость влияет на предложение.
Шаг 3. Выбери подходящий уровень документации
Не создавай полный набор документов только потому, что он описан в статье.
Предложи один из уровней или собственную адаптацию.
Минимальный уровень
Подходит человеку, у которого пока нет проектной системы.
Базовый набор:
. README.md: цель, пользователи, результат и границы проекта;
. PROJECT_STATE.md: текущее состояние, фокус, ограничения и следующий шаг;
. TASKS.md: ближайшая исполнимая работа;
. SESSION_LOG.md: краткая передача состояния после содержательной работы.
Если используются AI-агенты, добавь:
. AGENTS.md: правила входа агента в проект, чтения документов, выполнения работы и обновления состояния.
Рабочий уровень
Добавляется, когда проект развивается и появляются решения, повторяемые процессы и ещё не принятые в работу наблюдения:
. ISSUES.md;
. DECISIONS.md;
. RUNBOOK.md.
Полный уровень
Добавляется только при реальной необходимости:
. PROJECT_MEMORY.md;
. ARCHITECTURE.md;
. ROADMAP.md;
. CHANGELOG.md;
. RETROSPECTIVE.md.
Для специальных областей могут потребоваться дополнительные стандарты, реестры или документы. Не добавляй их без подтверждённой потребности.
Зрелость документации определяется не количеством файлов, а тем, насколько хорошо система сохраняет контекст и поддерживает работу
Шаг 4. Определи ответственность каждого документа
Для каждого предлагаемого документа составь короткий паспорт.
В паспорте укажи:
. название документа;
. его назначение;
. какие сведения являются для него источником;
. что в нём хранить нельзя;
. когда агент должен его читать;
. при каких событиях его нужно обновлять;
. может ли агент обновить его самостоятельно;
. какие изменения требуют решения человека;
. с какими другими документами он не должен дублироваться.
Если два документа отвечают за одно и то же, предложи объединение или более чёткое разделение ответственности.
Пример разделения:
. стратегия хранится в ROADMAP.md;
. ближайшая работа хранится в TASKS.md;
. текущее состояние хранится в PROJECT_STATE.md;
. основания долгосрочных решений хранятся в DECISIONS.md;
. ход отдельных сессий хранится в SESSION_LOG.md;
. устойчивые изменения хранятся в CHANGELOG.md.
Шаг 5. Построй прогрессивное развёртывание контекста
Разработай правила, по которым агент не читает всю документацию при каждой задаче.
Агент должен получать минимальный достаточный контекст, а дополнительные уровни подключать по мере усложнения задачи
Определи как минимум три уровня.
Базовый контекст
Информация, которая нужна для начала большинства задач:
. правила проекта;
. краткое описание проекта;
. текущее состояние;
. ближайшие задачи;
. открытые проблемы, связанные с текущей работой.
Расширенный контекст
Подключается в зависимости от типа задачи:
. архитектура для изменений устройства системы;
. журнал решений для работы с долгосрочными ограничениями;
. roadmap для стратегических изменений;
. runbook для повторяемых операций;
. changelog и открытые проблемы для подготовки выпуска;
. память проекта для восстановления устойчивого контекста.
Специализированный контекст
Подключается только для узких областей:
. данные;
. безопасность;
. финансы;
. юридические требования;
. релизы;
. инфраструктура;
. внешние интеграции;
. другие предметные стандарты.
Для каждого типа задачи зафиксируй:
. с каких документов начинать;
. какие документы подключать дополнительно;
. при каком условии углублять контекст;
. когда нужно остановиться и запросить пользователя.
Шаг 6. Построй матрицу обновления документов
Определи, какие документы могут изменяться после разных типов задач.
Например:
. после небольшой работы обычно обновляются журнал сессии и статус задачи;
. после устойчивого изменения может обновляться changelog;
. после изменения фактического устройства системы обновляется архитектура;
. после принятого долгосрочного решения обновляется журнал решений;
. после изменения стратегии обновляется roadmap;
. после появления повторяемого урока обновляется ретроспектива;
. после изменения повторяемого процесса обновляется runbook.
Не обновляй документы «для порядка» или только потому, что сессия завершилась.
Каждый документ изменяется только тогда, когда изменилось то, за что он отвечает
Шаг 7. Построй матрицу полномочий агента
Раздели изменения на две группы.
Агент может выполнить без отдельного согласования
Агент может самостоятельно отражать подтверждённые факты в границах уже разрешённой задачи.
Например:
. записать, что было сделано и проверено;
. актуализировать текущее состояние проекта;
. отметить фактически выполненную задачу;
. зафиксировать уже произошедшее устойчивое изменение;
. обновить инструкцию после уже согласованного изменения процесса;
. сохранить конкретное наблюдение или проблему, не превращая её в обязательство;
. оставить понятную передачу состояния следующему исполнителю.
Агент должен запросить решение пользователя
Агент не должен самостоятельно:
. создавать новое обязательство;
. добавлять новую работу в исполняемый backlog;
. менять приоритет, владельца или срок;
. расширять границы задачи или проекта;
. превращать наблюдение в задачу или этап roadmap;
. принимать архитектурное или стратегическое решение;
. выбирать решение проблемы от имени пользователя;
. принимать риск;
. откладывать или отклонять работу от имени пользователя;
. изменять общий стандарт, шаблон или структуру рабочего пространства;
. делать однозначный вывод при неполных или противоречивых данных;
. удалять, перемещать или полностью переписывать существующие документы без отдельного разрешения.
Если решение уже было явно принято пользователем в текущей работе, не запрашивай его повторно только ради синхронизации документации.
Граница самостоятельности агента проходит между фиксацией фактов и принятием решений
Шаг 8. Подготовь проект стандарта
До создания файлов представь пользователю единый проект системы.
Он должен включать:
. краткое описание текущего состояния;
. выявленные проблемы и дублирование;
. допущения и неизвестные данные;
. рекомендуемый уровень документации;
. предлагаемую структуру проектов и папок;
. перечень документов;
. паспорт каждого документа;
. матрицу чтения по типам задач;
. матрицу обновления;
. матрицу полномочий;
. порядок запуска новой работы;
. порядок завершения сессии;
. план перехода от текущего состояния;
. перечень решений, которые требуется принять пользователю.
Отдельно покажи:
. что предлагается сохранить без изменений;
. что предлагается дополнить;
. что предлагается создать;
. что кажется устаревшим, но пока не должно удаляться;
. какие изменения могут повлиять на существующую работу.
После этого остановись и запроси согласование.
Шаг 9. Создай документы после согласования
После согласования:
. создавай только одобренные документы;
. сохраняй существующие материалы;
. не удаляй и не перемещай файлы без отдельного разрешения;
. не придумывай отсутствующие цели, решения, приоритеты и владельцев;
. оставляй неизвестные значения явно неизвестными;
. делай документы короткими и пригодными для восстановления контекста;
. добавляй ссылки на общие стандарты вместо копирования их полного текста;
. настрой AGENTS.md как единую точку входа для AI-агентов;
. зафиксируй правила прогрессивного развёртывания контекста;
. зафиксируй границу между самостоятельным обновлением и человеческим решением.
Если внедрение выполняется поэтапно, не называй предложенную или частично созданную систему полностью применённой.
Шаг 10. Проверь результат
После создания системы проверь:
. у каждого документа есть отдельная зона ответственности;
. документы не дублируют друг друга;
. агент может начать работу с минимального контекста;
. для сложных задач определены дополнительные уровни чтения;
. пользователь не обязан вручную поддерживать файлы после каждой сессии;
. агент понимает, что обновляет самостоятельно;
. агент понимает, где должен остановиться и запросить решение;
. наблюдения не превращаются автоматически в обязательства;
. стратегия не смешана с текущими задачами;
. история не мешает восстановлению актуального состояния;
. следующий человек или агент может продолжить работу без чтения предыдущего чата.
В финальном ответе различай состояния:
. предложено;
. согласовано;
. создано;
. применено;
. проверено.
Не называй проект стандарта внедрённой системой до фактического создания и проверки документов.
Формат первого ответа пользователю
Первый ответ должен содержать:
- Как ты понял рабочее пространство пользователя.
- Что уже существует и может быть сохранено.
- Каких сведений не хватает.
- Какой уровень документации ты рекомендуешь.
- Какие документы предлагаешь использовать.
- Как будет работать прогрессивное развёртывание контекста.
- Что агент сможет обновлять самостоятельно.
- Какие изменения потребуют решения пользователя.
- Как будет выглядеть переход к новой системе.
- Какие точные решения нужно согласовать до создания файлов.
Заверши первый ответ прямой фразой:
«На этом этапе я ничего не создавал и не изменял. После вашего согласования структуры и границ я подготовлю точные шаблоны и план внедрения».