Я начал писать инструкции не для людей, а для AI

Долгое время внутренняя документация проекта для меня имела довольно понятного читателя.

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

Иногда я писал документацию для самого себя из будущего. Потому что через полгода собственный код вполне способен выглядеть как работа незнакомого человека.

Но аудитория всё равно оставалась человеческой. А потом появился ещё один читатель.

новый developer
+
AI agent

И неожиданно это довольно сильно изменило моё отношение к документации.

Раньше многое можно было просто объяснить

Когда в проект приходит новый разработчик, у документации всегда есть довольно удобный запасной механизм. Другой разработчик.

Что-то непонятно — спросит. Что-то устарело — ему расскажут актуальный вариант. Не нашёл нужный сервис — коллега покажет. Увидел странное архитектурное решение — можно узнать его историю.

Поэтому внутренняя документация довольно часто существует в полуготовом состоянии. README описывает запуск проекта. Есть несколько страниц про архитектуру. Какие-то правила написаны в Wiki. Остальное находится где-то между Slack, комментариями в pull request и коллективной памятью команды.

И система продолжает работать. Потому что люди умеют компенсировать пробелы общением. С AI это работает немного иначе.

AI не знает, что здесь «все и так знают»

Это очень быстро становится заметно. Например, для команды очевидно:

В controller бизнес-логику не кладём.

Или:

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

Или:

Тесты нужно запускать не напрямую через PHPUnit, а через composer test.

Или:

Для денег всегда используем существующий Money Value Object.

Никто уже не обсуждает эти правила. Они просто есть. Опытный разработчик соблюдает их автоматически. Новый человек узнаёт на onboarding или первом code review.

А AI? Если правило нигде не записано, он должен его угадать. Иногда угадывает. Иногда находит паттерн по существующему коду. А иногда создаёт совершенно нормальное техническое решение, которое в этом конкретном проекте считается неправильным.

И тогда довольно легко сказать: AI опять не понял проект. Хотя проект ничего ему и не объяснил. Про это я уже писал в заметке про то, что контекст оказался важнее модели.

Именно тогда документация перестала казаться чем-то отдельным от разработки

Раньше документация часто воспринималась как работа после работы. Сначала сделал feature. Потом, если осталось время, обновил README. Если изменение достаточно большое — написал страницу в документации. Если очень большое — может быть, ещё ADR.

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

С coding agents я начал замечать гораздо более прямую зависимость. Плохая документация сегодня означает плохую реализацию завтра. Не когда-нибудь. Не после прихода нового сотрудника через полгода. А буквально в следующей задаче, которую я отдам AI.

Это сильно меняет мотивацию.

Я начал записывать то, что раньше держал в голове

Самые полезные инструкции оказались довольно скучными. Не философия проекта. Не длинные архитектурные манифесты. А простые вещи.

Например:

Используй существующие application services.
Не добавляй бизнес-логику в controllers.
Для новых сущностей используй UUID.
Не добавляй package без отдельной необходимости.
Перед изменением API проверь backward compatibility.
Не редактируй generated files.
После изменений запускай:
composer test
composer phpstan

Для человека из команды половина этих пунктов может казаться очевидной. Именно поэтому раньше мне не хотелось их записывать. Но для агента «очевидное» — очень плохая категория информации. Либо правило доступно. Либо его нет.

Самое интересное — я стал замечать плохие правила

Иногда начинаешь писать инструкцию для AI и понимаешь, что сам не можешь нормально её сформулировать.

Например:

Используй правильный service для работы с заказами.

Какой правильный? Почему именно он? Где проходит граница его ответственности?

Или:

Не трогай legacy без необходимости.

Что считается необходимостью?

Или:

Следуй архитектуре проекта.

Какой именно архитектуре?

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

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

AI оказался довольно хорошим тестом документации

Есть простой эксперимент. Дать агенту задачу. Не объяснять ничего устно. И посмотреть, сможет ли он понять проект по тому, что уже лежит в repository.

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

А если каждую задачу приходится начинать с двадцатистрочного prompt «обязательно учти, что...» — значит, возможно, проблема уже не в prompt. Этой информации просто не хватает самому проекту.

В какой-то момент я начал воспринимать повторяющиеся объяснения как сигнал. Если правило приходится сообщать AI второй или третий раз, вероятно, его пора записать.

Так у документации появился довольно быстрый feedback loop

Раньше качество внутренней документации проверялось редко. Написал страницу. Через три месяца пришёл новый сотрудник. Он что-то не понял. Страница обновилась.

Теперь feedback может появляться каждый день. Например, агент постоянно запускает неправильную команду тестирования. Можно каждый раз исправлять: нет, используй другую команду. А можно один раз записать правильную.

Агент регулярно создаёт классы не в том namespace. Появляется правило. Постоянно забывает обновлять определённый тип тестов. Добавляется checklist.

То есть документация постепенно развивается из реальных ошибок процесса. Мне это нравится гораздо больше, чем попытка заранее написать идеальное руководство на пятьдесят страниц.

Но появился и риск написать слишком много

После первых успехов очень легко решить: отлично, сейчас я объясню AI вообще всё. И появляется огромный файл. Там coding style. Архитектура. Git conventions. Правила тестирования. Описание бизнеса. Все известные edge cases. История проекта с 2018 года.

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

Для себя я постепенно начал разделять несколько уровней.

README
    ↓
что это за проект и как с ним начать работать
AGENTS.md / project instructions
    ↓
как агенту работать с repository
архитектурная документация
    ↓
почему система устроена именно так
документация модулей
    ↓
что важно в конкретной области
тесты
    ↓
какое поведение система обязана сохранять

Не обязательно именно с такими файлами и названиями. Важнее сама идея. У разных знаний разная область действия.

Инструкция для AI и документация проекта — не совсем одно и то же

Это различие для меня стало особенно интересным.

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

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

И постепенно внутри проекта появляется новый слой документации. Не только «как работает система». Но ещё «как AI должен с ней работать».

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

Некоторые инструкции я бы не написал человеку никогда

Например:

Не создавай новый abstraction, если существующий механизм уже решает задачу.

Человеку на code review я могу просто объяснить конкретный случай. AI же способен повторять один и тот же тип решения снова и снова. Если модель любит определённый паттерн, он начнёт появляться в разных частях codebase. Поэтому возникает желание явно ограничивать поведение.

Не делай unrelated refactoring.
Не переписывай рабочий код ради единообразия.
Не добавляй новые зависимости без необходимости.
Не создавай новый слой архитектуры для одной реализации.
Если существующий подход проекта противоречит твоему предпочтению,
сначала следуй подходу проекта.

Это довольно странный жанр документа. Почти инструкция новому сотруднику. Только новому сотруднику, который прекрасно знает Symfony, PHP и десятки архитектурных паттернов, но совершенно не знает, когда лучше ничего из этого не применять.

Чем сильнее AI, тем важнее ограничения

Слабый инструмент просто не сможет сделать слишком много. Сильный — сможет. Он способен взять небольшую задачу и начать довольно масштабную переработку. Причём аргументировать её будет очень убедительно.

Я заметил дублирование и вынес общий abstraction.

Я заменил устаревший подход на более современный.

Я унифицировал обработку ошибок.

И иногда всё это действительно хорошие идеи. Просто не в этой задаче.

Поэтому хорошая инструкция для AI — это не только список возможностей. Это ещё и границы автономности. Что можно менять самостоятельно. Что можно предложить. А что требует отдельного согласования.

Чем больше я делегирую, тем важнее становится этот слой.

Я начал писать документацию более буквально

Человеку иногда достаточно фразы «запусти обычные проверки». Он знает, что такое «обычные». AI лучше дать:

После изменения PHP-кода выполни:

composer test
composer phpstan
composer cs-check

Человеку можно сказать: не ломай старое API. Агенту полезнее:

Публичные REST endpoints используются внешними клиентами.
Не удаляй поля response и не меняй их типы без явного указания задачи.

Получается, документация становится менее зависимой от общего понимания. Меньше «ну здесь понятно». Больше «вот конкретное правило». И мне кажется, что это полезно не только для AI. Новый разработчик тоже будет благодарен.

Возник неожиданный вопрос: где должна жить правда?

Допустим, есть правило проекта. Можно записать его в README, в AGENTS.md, в документации, в комментарии, в тесте, в коде. Что выбрать?

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

Поэтому я всё чаще думаю не просто «нужно добавить контекст», а «где для этого контекста правильное место?»

Например, бизнес-ограничение лучше выразить кодом и тестом. Архитектурное решение — архитектурной документацией. Команду проверки — project instructions. Способ запуска — README.

Это снова очень обычная инженерная проблема. AI просто сделал её более заметной.

Документация постепенно становится частью runtime для агента

Не в буквальном смысле, конечно. Но эффект похожий.

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

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

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

Поэтому инструкции тоже требуют review

Если AGENTS.md влияет на десятки будущих задач, изменение одной строки в нём иногда важнее изменения одного production-класса.

Например, добавили: всегда используй repository для доступа к данным. Звучит нормально. Но что означает «всегда»? Может быть, в reporting layer есть отдельный read model. И теперь агент начинает переделывать правильный код под слишком широкое правило.

Так что писать инструкции тоже приходится осторожно. Хорошее правило должно уменьшать неопределённость. Плохое просто заменяет одну ошибку другой.

Я начал думать о repository как об окружении для разработчика

Раньше хороший repository для меня означал примерно: понятную структуру, рабочий setup, нормальные тесты, README, предсказуемые conventions.

Теперь к этому добавился ещё один вопрос:

Если я дам этот repository coding agent, насколько долго он сможет работать без моих устных пояснений?

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

Самое забавное — я вроде бы пишу инструкции для AI, а выигрывают люди

Хорошо сформулированное правило «после изменения схемы обязательно обновить fixtures и integration tests» полезно агенту. Но оно так же полезно разработчику, который пришёл в проект вчера.

Описание «domain layer не должен зависеть от Symfony» полезно AI. Но оно одновременно фиксирует архитектурное решение для команды.

Документ «вот основные компоненты billing и вот границы их ответственности» помогает модели исследовать задачу. Но ещё больше помогает человеку, который через год будет чинить этот модуль.

В итоге довольно парадоксально. Я начал писать часть документации специально для AI. А проект от этого становится понятнее для людей.

Возможно, AI просто создал нового очень требовательного читателя

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

Если написано «используй этот подход» — он использует. Если написано «запусти эту команду» — он запускает. Если ничего не написано, начинает строить предположения.

И поэтому качество формулировок становится очень заметным. Расплывчатая документация даёт расплывчатое поведение. Противоречивая — противоречивое. Устаревшая — неправильное.

Возможно, именно такой читатель внутренней документации нам давно был нужен.

Раньше документация помогала войти в проект

Теперь она ещё и помогает проекту объяснить себя — не только человеку, но и агенту.

И мне кажется, что это довольно важное изменение. Потому что если coding agents действительно будут выполнять всё более крупные части инженерной работы, им потребуется не просто доступ к коду. Им потребуется среда, в которой записано:

что это за система
как она устроена
какие решения здесь считаются правильными
какие ограничения нельзя нарушать
как проверить результат
что можно менять самостоятельно
а где нужно остановиться и спросить

Когда-то всё это можно было держать в головах команды. Потом мы начали писать onboarding-документацию для новых разработчиков. Теперь у проекта появилась ещё одна аудитория.

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