Продолжаю серию статей о разработке приложений командой ИИ-агентов. Подробно о методологии вы можете прочесть в первой статье цикла — Как быть Product Owner’ом для команды ИИ-агентов. Методология P.A.C.A. В данной статье расскажу какие артефакты, как и для чего используются.
Инструкции агентов
Входная точка
Кроме служебных файлов проекта в проекте находится каталог с памятью и файл с инструкциями AGENTS.md с минимальным набором правил. В AGENTS.md мной перечислены роли и где расположены инструкции для ролей.
# Правила и роли
Проект разрабатывается несколькими ИИ-агентами в тандеме. Каждый агент жёстко ограничен своей ролью.
**ЖЁСТКОЕ ПРАВИЛО:** в первом же своём ответе в новой сессии, до любого другого текста, ОБЯЗАТЕЛЬНО запроси у пользователя свою роль, если он явно её не указал. После получения роли немедленно прочитай соответствующий файл с инструкциями:
## РОЛЬ 1: РАЗРАБОТЧИК
**Целевая модель:** Любая. Загрузи и строго следуй инструкциям из `~/.agents/agents.md/AGENTS-DEV.md`.
## РОЛЬ 2: АРХИТЕКТОР
**Целевая модель:** Любая. Загрузи и строго следуй инструкциям из `~/.agents/agents.md/AGENTS-ARCH.md`.
...
## РОЛЬ N: ЛИДЕР КОМАНДЫ (TEAM LEAD)
**Целевая модель:** Любая. Загрузи и строго следуй инструкциям из `~/.agents/agents.md/AGENTS-TEAM-LEAD.md`.Когда агент вызывается ему сообщается его роль, чтобы он прочитал свои инструкции и понимал как дальше действовать.
Лидер команды (Team Lead) — это ключевая роль. Именно он, по сути, почти всегда общается со мной. А затем, уже дальше по цепочке, он вызывает разработчика, который, в свою очередь, подключает код-ревьюера, QA и инженера по безопасности.
При необходимости вы можете указать здесь любое количество ролей и ссылки на их инструкции. Кстати, тильда (~) в путях означает домашний каталог пользователя.
Целевая модель: Любая. Здесь можно указывать конкретную можель к которой применяется роль. У меня это атавизм, но вам возможно пригодится.
Каждому своя инструкция
Рассмотрим, какие у нас есть инструкции и что в эти инструкции заложено.
AGENTS-TEAM-LEAD.md — руководитель команды (Тимлид). Этот файл задаёт правила для главного управляющего всей виртуальной командой. Тимлид сам не пишет программы и не рисует кнопки — он организует работу остальных цифровых специалистов, как дирижёр в оркестре или прораб на стройке. Он берёт список готовых к работе задач, по очереди поручает их разработчикам и следит, чтобы никто не перепрыгивал через обязательные этапы проверки. Если в процессе возникает спорный вопрос, который меняет смысл продукта для будущего пользователя, Тимлид останавливает работу и приходит за решением к человеку-заказчику. Когда все открытые задачи решены, он принимает работу и составляет для владельца проекта понятный отчёт: что именно появилось в продукте и как это можно проверить своими руками.
AGENTS-ARCH.md — главный архитектор. В этом файле описана роль главного архитектора системы. Прежде чем разработчики напишут хотя бы одну строчку кода, Архитектор продумывает устройство будущего продукта: из каких блоков он состоит, как части программы общаются между собой и по каким правилам хранят информацию. Сам он код не пишет — его задача превратить пожелания заказчика в точное, непротиворечивое техническое задание, где предусмотрены все крайние случаи. К нему же приходят за решением, если во время работы разработчик столкнулся с технической развилкой, проблемой или противоречием.
AGENTS-DEV.md — ведущий разработчик. Этот файл описывает работу главного исполнителя, который превращает ТЗ архитектора в работающую программу. Разработчик берёт ровно одну задачу и воплощает её строго по инструкции, не выдумывая ничего от себя. Написав свою часть программы, он сначала проверяет её сам, а затем по очереди отдаёт независимым контролёрам: специалисту по кодревью, специалисту по безопасности и тестировщику. Если хотя бы один из них находит изъян, разработчик исправляет ошибку и проходит проверку заново. Только когда все одобрили результат, он передаёт готовую работу на приёмку тимлиду или заказчику, если тот его вызывал напрямую.
AGENTS-CODE-REVIEW.md — код-ревьювер. Файл определяет правила для независимого эксперта, который вычитывает написанный код программы. Он не запускает программу сам, а внимательно изучает каждую строчку: соответствует ли она ТЗ архитектора, нет ли в логике скрытых ошибок, придерживается ли разработчик стандартов написания кода и так далее. Код-ревьювер не верит разработчику на слово (в инструкциях так и написано) и никогда не исправляет чужие недочёты своими руками. Вместо этого он составляет подробный список замечаний и возвращает задачу на доработку.
AGENTS-SECURITY.md — инженер по безопасности. В этом файле заложены инструкции для цифрового охранника и взломщика в одном лице. Его цель — найти слабые места в защите продукта раньше, чем это сделают настоящие злоумышленники. Он изучает как сам текст программы (SAST), так и живое работающее приложение (DAST): пробует отправить некорректные данные, обойти проверку паролей, получить доступ к чужой информации и многое другое. При любой найденной уязвимости инженер по безопасности блокирует выпуск задачи и даёт рекомендации, как залатать дыру в защите.
AGENTS-QA.md — инженер по тестированию (QA). Этот файл описывает роль независимого исследователя продукта. Когда разработчик проверяет собственную работу, он невольно тестирует лишь то, в чём и так уверен. Инженер по тестированию решает эту проблему: он смотрит не на то, как написана программа внутри, а на то, как она должна работать по договору с заказчиком. Также он пишет автоматические проверки, запускает полное тестирование всей системы и лично «прокликивает» сайт или приложение в браузере — сначала как обычный гость, а затем как вошедший в систему пользователь. Задача проходит дальше только тогда, когда все функции работают без сбоя.
Регламенты и стандарты
Кроме озвученных документов в процессе разработки соблюдаются регламенты и стандарты на которые ссылаются инструкции агентов.
ARCHITECT_WORKFLOW.md — регламент проектирования и подготовки задач для архитектора. Этот файл описывает, как превратить общую идею заказчика в понятный и полный план работ для разработчиков. Главное правило документа: задача считается готовой только тогда, когда разработчик может выполнить её от начала до конца без единого уточняющего вопроса и без домыслов. Регламент запрещает размытые формулировки вроде «сделай как обычно» или «уточним по ходу дела». Вместо этого архитектор заранее сверяет пожелания заказчика с тем, что уже создано в проекте, продумывает поведение программы в нестандартных ситуациях и делит большую работу на небольшие последовательные этапы. Кроме того, документ объясняет, как команда учится на собственном опыте: каждая найденная ошибка не просто чинится один раз, а превращается в общее правило с автоматической проверкой, чтобы никто больше не наступил на те же грабли.
CODING_STANDARDS.md — стандарты написания и безопасности кода для всех агентов. В этом файле собраны единые правила чистоты, аккуратности и безопасности для всех, кто работает с кодом проекта. Документ требует, чтобы каждая новая задача выполнялась в отдельном изолированном рабочем пространстве и не мешала уже работающей версии продукта. Программа должна быть написана так, чтобы её легко читал любой специалист. Отдельный блок правил защищает продукт от взлома: он запрещает хранить пароли внутри кода, доверять непроверенным данным от посетителей или отключать защитные механизмы ради экономии времени.
RULES_NUMBERING_PLACING_TASKS.md — правила нумерации и очереди задач для архитектора. Этот документ наводит строгий порядок в списке дел проекта. В живой разработке план редко идёт только по прямой: по ходу проверки готовой функции часто всплывают мелкие доработки или замечания к прошлым этапам. Чтобы список задач не превратился в хаос, где невозможно понять, за что браться дальше, файл задаёт чёткие правила: когда нужно просто уточнить текущее задание, а когда — завести отдельную карточку на доработку. Он определяет, какой номер присвоить каждой новой задаче или исправлению и в какое именно место очереди их поставить, чтобы история проекта оставалась прозрачной, а команда всегда двигалась в правильной последовательности.
SUBAGENT_PROCESS.md — общие правила проверок и защита от сбоев для всех агентов. Файл регулирует повседневную дисциплину агентов во время работы, чтобы команда работала быстро, слаженно и не «зависала» на полпути. В нём описано, как контролёрам проводить повторную проверку после исправления ошибок: не тратить время на чтение всей документации заново, но при этом внимательно перепроверить как само исправление, так и соседние участки программы. Документ также помогает отличать мелкие правки текста или описания от изменений самой программы, чтобы не гонять тяжёлые многоминутные проверки впустую. Наконец, здесь заложены правила технической гигиены: сколько времени отводится на каждый шаг, как вовремя распознать зависшую программу и как аккуратно закрыть за собой все рабочие окна и процессы.
SUBAGENT_REPORTING.md — стандарт отчётности агентов. Этот файл устанавливает единый язык отчётности между агентами. Когда проверяющий находит проблему, он не просто блокирует задачу, а обязан точно указать её причину: ошибся ли сам разработчик при написании кода или же изъян закрался ещё на этапе проработки и технического задания. В документе зафиксировано в какой форме отчитываться перед другими агентами и в каком виде передавать данные. При этом в отчётах запрещена «вода» и общие похвалы — фиксируются только конкретные факты, проверенные ссылки и действия.
Скорее всего в дальнейшем могут появляться и другие артефакты.
Контекст и память
В предыдущей статье я рассказывал о контексте и памяти. В данной статье раскрою подробнее данную тему.
Зачем вообще нужна память проекту (каталог memory)? Главная проблема любого искусственного интеллекта — короткая память: каждый раз, когда запускается новый агент, он начинает работу как в первый рабочий день и ничего не помнит о прошлых разговорах. Если заставить его каждый раз перечитывать весь проект целиком, он быстро переполнит свой контекст и начнёт галлюцинировать. Память решает эту проблему: она устроена как образцовая картотека, где на видном месте лежит краткая сводка о текущем состоянии проекта, а все подробности аккуратно разложены по тематическим папкам и читаются только тогда, когда они действительно нужны. В инструкциях агентов прописано, кто что читает.
Главные файлы на верхнем уровне (читаются всегда)
README.md — конституция памяти. Этот файл задаёт правила пользования самой памятью: что именно лежит в каждом документе, кто из команды имеет право его менять и как поддерживать идеальный порядок. Главное правило этого документа — хранить на виду только то, как система устроена прямо сейчас, без длинных мемуаров о прошлых переделках, и никогда не держать одну и ту же информацию в двух разных источниках. Сам этот файл неприкосновенен для всех агентов — менять его может только человек-заказчик.
ROADMAP.md — дорожная карта проекта. Здесь описан общий маршрут создания продукта от самого первого шага до готовой версии. Большой проект разбит на понятные этапы — как строительство дома от фундамента и стен до внутренней отделки. По этому файлу любой участник команды сразу видит, какие крупные вехи уже позади, какой этап идёт прямо сейчас и что именно должно работать к моменту выпуска продукта.
TASKS.md — очередь активных задач. Это живой список дел текущего этапа. Каждая строчка здесь — одна конкретная задача с отметкой «выполнено» [x] или «не выполнено» [ ], её кратким смыслом в одно предложение и ссылкой на подробное техническое задание. В этом списке нет длинных инструкций или отчётов, благодаря чему взгляд сразу выхватывает общую картину: что уже готово и за что браться дальше.
PROGRESS.md — сводка текущего состояния. Короткая сводка на один экран, которая отвечает на вопрос: «Где мы находимся прямо сейчас?». В этом файле отмечено, готов ли текущий этап к работе, что делаем дальше, что сделали. Старые записи здесь не копятся — сводка каждый раз обновляется, показывая только самую свежую картину.
HANDOFF.md — эстафетная палочка. Этот небольшой документ передаёт смену от одного агента к другому. В нём собрано самое важное напутствие для того, кто приступает к работе следующим: ссылки на каноны и ключевые правила, которые нельзя нарушить, какая задача последняя реализована, какую задачу брать следующей.
ARCHITECTURE.md — архитектенера системы. Здесь зафиксировано, из каких блоков состоит система, где проходят границы между ними и по каким общим законам они взаимодействуют. Этот файл помогает специалистам видеть всю конструкцию целиком и не строить новые части вразрез с общим замыслом.
DATABASE_SCHEMA.md — стурктура базы данных. Подробная опись всей информации, которую хранит продукт: профили пользователей, настройки, заказы, платежи, файл и прочая информация (зависит от вашей системы). Документ заранее определяет, какие именно сведения записываются в базу и как они связаны друг с другом.
TECHNOLOGIES.md — технический паспорт. В этом файле зафиксирован технологический стек разрабатываемой системы, а также библиотеки и рабочие инструменты, из которых собран проект, с их точными версиями и настройками. Это единый стандарт благодаря которому ни один агент не принесёт в проект случайный или несовместимый компонент, из-за которого система может дать сбой.
Вложенные папки (читаются по необходимости точечно)
Папка tasks — архив подробных технических заданий. В этой папке лежат полные ТЗ к каждой отдельной задаче проекта (task-001.md, task-002.md и так далее). Разработчик не читает всё сразу — он открывает только своё ТЗ, где архитектор уже расписал для него все детали, алгоритмы и проверки. Когда задача успешно сдана заказчику, в конце ТЗ фиксируется отметка о выполнении, после чего документ становится неизменяемым и становится историей.
Папка modules — паспорта отдельных модулей продукта. Если в ARCHITECTURE.md система описана с высоты птичьего полёта, то в папке modules лежат подробные описания каждого отдельного модуля: например, раздела заказов, личного кабинета, уведомлений или панели администратора. Специалист заглядывает только в паспорта тех разделов, которые затрагивает его текущая задача.
Папка patterns — свод сквозных правил (канонов). Здесь хранятся файлы, в которых зафиксировано, как в проекте принято решать типовые задачи (k1...k16): как оформлять экраны и формы, как обрабатывать фотографии, как проверять права доступа или вести журналы событий. Рядом с ними находится файл с инцидентами «книга уроков» (incidents.md), куда архитектор записывает все сбои и ошибки, с которыми команда столкнулась по ходу работы, а правила, которые не дадут этим ошибкам повториться, фиксируются в канонах.
Папка archive — долговременный архив. По мере того как проект движется вперёд, списки выполненных задач, разобранных ошибок прошлых этапов разрастаются. Чтобы они не перегружали активную рабочую память команды, архитектор периодически переносит старые данные в папку archive. В обычной работе агенты туда не заглядывают, но вся история бережно сохранена на случай, если владельцу проекта понадобится поднять старые записи.
Матрица прав доступа
| Файл | Архитектор | Разработчик | Тестировщик / QA | Безопасность | Code Review | Team Lead |
|---|---|---|---|---|---|---|
README.md | Read | Read | Read | Read | Read | Read |
ROADMAP.md | Read / Write | Read / Update | Read | Read | Read | Read |
TASKS.md | Read / Write | Read / Update | Read | Read | Read | Read |
PROGRESS.md | Read / Write | Read / Update | Read | Read | Read | Read |
HANDOFF.md | Read / Write | Read / Write | Read | Read | Read | Read |
DATABASE_SCHEMA.md | Read / Write | Read / Update | Read | Read | Read | Read |
ARCHITECTURE.md | Read / Write | Read / Update | Read | Read | Read | Read |
TECHNOLOGIES.md | Read / Write | Read / Update | Read | Read | Read | Read |
tasks/*.md (адресно) | Read / Write | Read / Append | Read | Read | Read | Read |
patterns/k*.md (адресно) | Read / Write | Read | Read | Read | Read | — |
modules/*.md | Read / Write | Read / Write | Read | Read | Read | — |
patterns/incidents.md(адресно) | Read / Write | Read | Read | Read | Read | — |
archive/tasks.md,archive/incidents.md,archive/progress.md | Read / Write | — | — | — | — | — |
Адресно — если есть ссылка на документ в ТЗ.
Итог
В статье я описал структуру процесса. На базе предыдущей и текущей статей вы уже можете выстраивать подобные процессы у себя.
