В прошлой статье мы выбрали удобную среду, разобрались с личными блокнотиками агентов и повесили им вполне понятную табличку: всё, что касается проекта, ищи в проекте. Теперь осталось совсем немного — положить в проект что-нибудь полезное))
Потому что создать папку docs несложно. Можно даже сразу попросить агента и через несколько минут в ней будет столько красивых файлов, что захочется выдать себе диплом за организацию производства. Проблемы начнутся чуть позже, когда понадобится узнать, почему вчера решили делать именно так, кто сейчас правит соседний кусок и можно ли уже считать задачу законченной.
Мне нужна документация, из которой агент может понять, куда он попал, что мы здесь делаем и как продолжить работу. С этого и предлагаю начинать.
Сначала объясняем, что вообще строим
Допустим, делаем домашний каталог книг. Это учебный пример, такой проект я сейчас заводить не собираюсь, а то с моей привычкой отвлекаться статья опять закончится новым приложением))
Задача простая: дома много книг, хочется быстро посмотреть, какие уже есть, где лежат и кому что дали почитать. В первой версии достаточно названия, автора, места на полке и отметки, у кого книга. Всё хранится локально, семейную синхронизацию пока отложили, магазин электронных книг строить не планируем.
Последние два уточнения могут оказаться не менее полезными, чем первые четыре. Потому что агент вполне способен решить, что каталогу нужны аккаунты, сервер, поиск по внешней базе и распознавание обложек. Звучит разумно? Вполне. Нужно мне сейчас? Я вообще-то хотел перестать покупать второй экземпляр одной и той же книги.
Поэтому сначала записываем замысел и границы. Для кого делаем, какую неприятность убираем, что должно получиться в ближайшей версии, а что мы сознательно пока не трогаем. Если что-то ещё не решили — так и пишем. «Не решили» намного полезнее, чем уверенная фантазия агента о том, что мы наверняка имели в виду.
И здесь пригодится привычка обсуждать идею. Мне проще рассказать её своими словами, ответить на уточнения, посмотреть, что агент понял, и поправить если надо. Пусть он помогает мне оформить мысль, но я должен узнать в получившемся описании свою задачу. Если просил каталог, а в ответ получил бизнес-план книжного маркетплейса, подготовка проекта ещё не закончена.
Сколько файлов надо?
Столько, чтобы нужное можно было найти и обновить, не устраивая каждый раз археологическую экспедицию. Звучит уклончиво, знаю. Но я действительно не считаю, что любому проекту надо с порога вручить одинаковую папку из двадцати пяти обязательных документов.
У меня есть мобильные приложения, а есть вот этот проект, в котором мы готовим статьи. У статей нет сборки под Андроид, зато есть авторская редакция, которую агенту нельзя молча переписывать, и истории, которые я пока не хочу публиковать. Если притащить сюда все правила мессенджера, получится очень хорошо документированный бардак.
Для нашего учебного каталога на старте можно обойтись такой небольшой схемой:
book-catalog/
├── AGENTS.md
├── README.md
└── docs/
├── idea.md
└── work.mdНазвания двух последних файлов здесь условные, это пример для разбора. Если в существующем проекте уже есть подходящие документы, незачем переименовывать их ради сходства с моей картинкой.
AGENTS.md объясняет порядок работы: что прочитать до изменений, какие правила соблюдать и куда записать результат. README.md рассказывает, что находится в этой папке и где искать нужные части проекта. В idea.md лежит наш замысел, а в work.md пока хватит двух разделов: что остаётся сделать и какие решения уже приняли. По мере роста проекта их можно будет разделить, но сейчас у нас ещё даже ни одной книги в каталоге нет, а мы уже канцелярию открываем.
Самое полезное в этой схеме — связь между документами. Агент прочитал входную инструкцию, из неё понял, где замысел и текущая работа, а после задачи знает, куда вернуться с результатом. Если каждый файл существует сам по себе и обнаруживается только по счастливой случайности, это просто коллекция текстов.
Вот такой порядок я и называю алгоритмической структурой документации. Документы подсказывают следующий шаг: что сейчас прочитать, какое решение проверить и где оставить новые сведения. Без необходимости каждый раз спрашивать у меня дорогу.
Инструкции, которые можно исполнить
В проектном AGENTS.md мне не нужен ещё один портрет идеального программиста из коллекции волшебных промптов. Мне нужны там понятные агентам инструкции. Для того же каталога начало могло бы выглядеть так:
Перед изменениями прочитай README.md, docs/idea.md и актуальные задачи в docs/work.md. Проверь состояние рабочей папки, чтобы не затронуть чужую незавершённую работу.
>
Не расширяй состав первой версии без обсуждения. Если задача противоречит принятому решению, покажи противоречие и уточни его до реализации.
>
После работы запиши в docs/work.md результат, способ проверки и оставшиеся вопросы. Принятое изменение замысла отрази в docs/idea.md. Подписывай записи именем агента и идентификатором сессии.
>
Не выдавай план за сделанную работу, а успешную сборку — за проверку удобства приложения человеком.
Читатель предыдущих статей тут, наверное, уже поднимает руку: «Алекс, ты же говорил, что промпты — фигня, а сам нам второй выпуск подряд какие-то тексты для агента показываешь».
Да, потому что словами задачу всё равно придётся объяснять)) От фразы «ты величайший разработчик» я отказался, а от постановки задачи — пока нет. Здесь можно проверить каждое требование: прочитан ли файл, записан ли результат, есть ли подтверждение проверки. И эти указания лежат рядом с проектом, где их можно менять вместе с порядком работы.
Ещё я хочу, чтобы оба моих основных агента читали общие правила, а не получали две постепенно расходящиеся версии. Как связать входы Клода и Кодекса с одним проектным документом, мы уже разобрали в шестой статье. Сейчас важнее наполнить этот документ правилами именно нашей работы.
У файла тоже должна быть инструкция
Мы объяснили агенту, в какой документ писать. Хорошо бы ещё объяснить, что именно туда писать, потому что иначе «запиши результат» очень быстро превращается в пересказ всей сессии, включая три неудачных запуска команды и благодарность самому себе за продуктивный день.
В начале каждого рабочего документа я хочу видеть его назначение, порядок записей и границу с соседними документами. Например, у нашего work.md можно прямо написать: наверху актуальные задачи, ниже принятые решения с причинами; подробные логи сюда не складываем, желаемое устройство продукта ищем в idea.md.
Тогда запись об отложенной синхронизации будет выглядеть примерно так: «В первой версии храним каталог на одном устройстве, потому что сейчас проверяем, удобно ли вообще вести список. Семейную синхронизацию отложили; к вопросу вернёмся после проверки основной работы». Это учебное решение, но из него понятно, зачем мы так сделали и когда можно пересмотреть выбор.
А если написать только «синхронизация не нужна», следующий агент вполне может принять это за вечный закон природы. Потом придётся выяснять, откуда вообще взялся запрет, который никто не собирался устанавливать навсегда.
С незавершённым похожая история. «Продолжить работу над каталогом» практически ничего не сообщает. «Добавление книги готово, проверено сохранение названия и автора; следующий шаг — проверить редактирование места на полке» уже позволяет продолжить. Конечно, только если это действительно сделано и проверено, а не агент заранее красиво заполнил отчёт о своём будущем успехе.
А можно не собирать это вручную каждый раз?
Можно. И вот здесь начинается та унификация, ради которой мы вообще затеяли этот разговор.
У меня есть друг, которому я помог перейти от копирования кусков кода через ChatGPT к работе Кодекса прямо с файлами. Через какое-то время у него появились новые проекты и знакомые мне вопросы: почему агент застревает, почему приходится заново объяснять, что мы делаем. Я помог разложить проекты, перенести полезные записи и завести правила работы с документацией.
Что интересно, сами правила оказались вполне переносимыми. Ему не потребовалось превращать свои проекты в мой мессенджер, чтобы ими пользоваться. Состав документов получился другой, а общий порядок работы сохранился. И по его обратной связи всё наконец начало работать так, как он изначально и хотел. Иногда я ещё заглядывал поправить агентские блокнотики, но постоянно стоять над ним с инструкцией уже не требовалось.
Поэтому я бы унифицировал вопросы, на которые проект должен отвечать, и порядок его подготовки. Готовое поручение для нового проекта можно начать примерно так:
Подготовь проект к работе нескольких сменяемых агентов. Сначала прочитай существующие инструкции и осмотри структуру папки без изменений. Кратко изложи, что уже известно о назначении проекта, какие документы есть и чего не хватает для начала работы. Не спрашивай то, что уже написано; противоречия и действительно неизвестные вещи вынеси на обсуждение.
>
Предложи минимальный состав документации под этот проект. Используй существующие файлы, если они подходят. Для каждого документа укажи назначение, правила ведения и связь с остальными. Отдели замысел и принятые решения от текущих задач и результатов проверок.
>
После согласования создай или обнови эти документы, сохранив чужие изменения. Свяжи их понятным порядком входа из проектных инструкций. Не заполняй неизвестное выдуманными фактами и не создавай разделы ради разделов. Код приложения в рамках этой задачи не меняй.
Это заготовка, которую я бы адаптировал под конкретную работу. В новом проекте обсуждать придётся больше. В давно живущем сначала надо разобраться с тем, что там уже накопилось, иначе агент радостно построит новую систему рядом со старой и поздравит нас с наведением порядка. Мы такое уже проходили, спасибо.
И я обязательно читаю результат. Например, если в текстовом проекте агент завёл журнал состояния сервера, которого нет, это повод вернуться к разговору о назначении документов, а не восхититься его предусмотрительностью.
Проверяем на следующем агенте
Для первой проверки не нужен большой эксперимент. Можно открыть новую сессию, дать агенту только папку проекта и попросить прочитать документы, после чего объяснить: что мы делаем, на чём остановились, какое действие следующее и где записано основание для этого выбора. Пока без изменений.
Не пересказать ему сначала всю историю, а потом проверить, хорошо ли он её запомнил. Пусть найдёт сам и покажет, на какие записи опирается.
Если не нашёл — смотрим, почему. Ссылка ведёт не туда? Решение осталось только в старом чате? Два файла сообщают противоположное? Или всё написано, но агент решил, что читать необязательно? Это разные проблемы и добавление ещё одного большого документа помогает далеко не в каждой из них.
А дальше смотрим уже на настоящей работе. Закончил задачу — оставил результат. Следующий агент пришёл — понял, что сделано, что ещё открыто и где требуется моё решение. Вот в этот момент документация начинает приносить пользу.
Чтобы не гадать, кто оставил конкретную запись, я прошу агентов подписывать свои секции именем и идентификатором сессии. Имя помогает различать авторов, а идентификатор — не смешивать несколько заходов одного и того же агента. Если позже понадобится разобраться, откуда взялось решение или чем закончилась задача, у записи будет понятное происхождение.
Недавно я заметил ещё один приятный эффект подписей. Раньше в документах была мешанина неизвестного авторства, а теперь агенты видят, кто над чем работает. Клод говорит примерно: я готов продолжать, но там сейчас Кодекс занят, давай дождёмся, пусть он закоммитит, а потом решим, кто что выкатывает. И вместо «это делал не я» получается «это делает коллега, не буду мешать».
Вообще прям два супер воспитанных сотрудника))
Разумеется, от одной подписи они волшебно воспитанными не стали. Но теперь у них хотя бы есть общая информация, по которой можно согласовать действия. Имя агента, его сессия и текущее состояние работы оказались полезнее, чем ещё один призыв «работайте дружно и не допускайте ошибок».
Вот с этого уже можно начинать. Небольшой набор нужных документов, понятные правила входа и записи результата, проверка на реальной смене агента. Остальное будет появляться по мере необходимости — и иногда исчезать, потому что схема должна успевать за вашей работой.
А вот почему даже после всего этого приходится периодически говорить «прочитай доки, блин», мы ещё разберём. Там и собака с ветпаспортом пригодится: документы у неё в полном порядке, а спит она всё равно где хочет))