[Project.md: структурированные файлы контекста как полноценный входной параметр для проектных агентов]

Я веду проекты в Enji с помощью PM Агента, который разрабатывает наша команда. Эта двойственность — быть одновременно пользователем и частью команды — означает, что проблемы я замечаю иначе. Речь об одной из них: той, которую я дольше, чем следовало, не могла назвать своими словами.

У PM Агента был доступ ко всему, что ему могло понадобиться: тикеты Jira, коммиты GitHub, ворклоги и история спринтов. Когда я спрашивала о статусе проекта, он давал ответы технически точные, но слишком обобщенные — из категории тех, что правильно резюмируют данные, но не понимают, что эти данные означают для конкретного проекта и конкретного клиента, работающего в конкретных ограничениях.

Таким образом, агент знал, что происходит, но не знал, что это значит.

Однажды я спросила, есть ли риск не успеть к майлстоуну Q2. Ответ ссылался на процент выполненных тикетов и скорость выполнения спринта — все верно. Чего он не знал: в договоре нашего клиенты было закреплено условие, из-за которого двухнедельный сдвиг обходился значительно дороже, чем следовало из цифр. И тимлид уже отметил, что два открытых тикета окажутся сложнее, чем отражали их оценки. Учесть ни то ни другое агент не мог — потому что ни того ни другого не было в Jira.

Именно эту проблему я и пыталась решить.

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

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

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

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

Практика определения того, что должен знать агент, теперь имеет название: контекстная инженерия (context engineering). Это меньше о промптах и больше о том, чтобы осознанно решить, что вообще считается контекстом для конкретного проекта и конкретной команды. Project.md — это наиболее простая форма для начала выстраивания контекста для агента, с которой мы решили начать.

Project.md — это текстовый файл, который живет в настройках проекта в Enji. Идея проста: вы один раз записываете то, что должен понять новый участник команды, чтобы работать на этом проекте, — и агент читает его при каждом ответе.

Я воспринимаю его как контракт контекста: формальное соглашение между командой и агентом о том, что является источником истины. Не то, что произошло в последнем спринте (это Jira), а то, что представляет собой проект, для кого он, каковы ограничения и как мы здесь определяем хороший результат.

Вот, что включено в этот файл:

• Описание проекта и текущая фаза: что мы строим, кто клиент и где мы находимся в жизненном цикле поставки.
• Ключевые майлстоуны и их бизнес-значимость: не просто даты, но и то, что каждый майлстоун означает согласно условиям договора или на что влияет стратегически.
• Структура команды и зоны ответственности: кто за что отвечает, включая то, как мы организуем передачу задач.
• Пороги рисков и правила эскалации: что является триггером для уведомления клиента, что мы решаем внутри, что считается блокером, а что — просто моментом, на который стоит обратить внимание.
• Конвенции и чувствительные темы клиента: терминология, которую использует клиент, темы, требующие осторожной формулировки, и предпочтения в коммуникации.
• Наше определение "под риском": потому что "три открытых тикета за четыре дня до майлстоуна" означает совершенно разные вещи в зависимости от проекта.

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

Pproject.md хорошо справляется с проектно-специфичным контекстом. Но у нас есть и институциональные знания на уровне организации: архитектурные решения, документация по API, гайды по процессам и ретроспективные заметки по прошлым проектам с тем же клиентом. Эти знания живут в Confluence — и после того как мы подключили его к PM агенту, они тоже стали доступны для запросов.

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

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

Самый наглядный способ показать, что изменилось в обоих слоях, — это рассмотреть реальные вопросы: для первых двух используется контекст конкретного проекта из файла Project.md, а для последнего — организационный контекст из Confluence.

"Есть ли риск не успеть к майлстоуну Q2?"

До: "Текущий процент выполнения спринта — 71%. При 12 открытых тикетах и среднем времени цикла 2,3 дня поставка к Q2 возможна, но с натяжкой. Рекомендую пересмотреть бэклог на предмет сокращения скоупа."

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

Данные были идентичны, но интерпретация изменилась, потому что агент теперь понимал, что Q2 означает для этого клиента.

"Есть ли что-то в проекте, что начинает дрейфовать и на что стоит обратить внимание?"

До: "Три тикета открыты, до конца спринта четыре дня. Время цикла в пределах нормы. Немедленных блокеров не обнаружено."

После: "Три тикета открыты за четыре дня до конца спринта — для большинства проектов это в пределах нормы. Однако определение риска для этого проекта помечает как проблемные любые запросы клиентов, остающиеся открытыми в последние пять дней. Два из трех являются запросами клиентов, поэтому по собственному порогу проекта они заслуживают внимания сейчас, а не в конце спринта."

Ответ "до" применяет универсальное понятие нормы. Ответ "после" применяет определение риска конкретно этого проекта — то, что записано в Project.md, — и одни и те же цифры по тикетам, выглядевшие нормально, теперь вызывают подозрение, потому что агент измеряет их относительно реального стандарта команды, а не дефолтного.

"Каков статус модуля аутентификации?"

До: Сводка статусов тикетов и последних коммитов — точная, но лишенная контекста. Говорит, что изменилось, но не почему это важно.

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

Здесь агент подтянул информацию об организационном контексте из доков, в Confluence, а не из md-файла проекта.

Как видно из ответов, в каждом случае агент перешел от технически корректного аутпута к реально полезному.

Project.md не обновляется сам. Когда что-то значимое меняется — новый майлстоун, скорректированное правило эскалации, клиент, отменивший прежнюю конвенцию, — кто-то должен обновить файл.

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

Мы обнаружили, что сам процесс написания обновленной информации показывает разрывы в согласованности. Когда два участника команды расходятся во мнениях о том, что должно войти в раздел с правилами эскалации — мы видим это проблему сразу, а не когда что-то пошло не так.

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