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

С появлением AI‑агентов ситуация изменилась: им нужен контекст о проекте, и сами они охотно бесконечно собирают документы и обновляют после каждого изменения. Создавать документацию стало проще. И её стало больше. Но пользы это не прибавило.

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

Документация — прежде всего инструмент коммуникации. Она передаёт знания и договорённости между людьми, командами, отделами и помогает проектировать систему, проверять реализацию и сопровождать её. Причём AI‑агент стал ещё одним новым звеном в цепочке коммуникации. И ему тоже нужны свои рабочие материалы.

Т.к. мы вели документацию в проектах ещё до широкого распространения AI‑инструментов, у нас не было проблем с адаптацией — мы просто добавили новый слой документов для работы с новым AI‑отделом. И в этой статье я расскажу и покажу, что у нас по итогу получилось и как устроена работа с документацией.


1. Назначение документации

Разным участникам команды техническая документация помогает решать разные задачи.

Разработчикам она помогает снизить когнитивную нагрузку при работе с незнакомой или забытой механикой. Самостоятельная попытка изложить решение помогает структурировать мысли, найти противоречия и обнаружить пробелы реализации. А на ревью документ позволяет сначала понять замысел перед оценкой кода, если это вообще после документации понадобится.

Геймдизайнерам документация помогает сопоставить требования с особенностями реализации, QA — уточнить ожидаемое поведение, UX‑дизайнерам — понять технические ограничения. Но на практике специалисты нетехнических отделов редко читают технические документы напрямую — для этого они используют агентов, искусственных и естественных.

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

В нашей команде одним из основных читателей технической документации является технический руководитель (то есть я). Чтобы оценить новые требования или развитие существующей механики, мне часто достаточно восстановить общую картину: из каких компонентов состоит система, как они взаимодействуют, где находятся ограничения и точки расширения. Для этого не нужно читать весь код или отвлекать разработчиков. Восстановить контекст можно и с помощью AI‑агента, но часто ответы нужны быстрее, чем он успеет исследовать код.

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

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

В небольшой вовлечённой многофункциональной команде схема коммуникации компактнее. Многое закрывается общим контекстом и прямым общением, поэтому потребность в документах ниже, а сами документы — проще. Основным читателем тогда вполне может стать AI‑агент. Отчасти поэтому концепция Tiny Teams сейчас становится более актуальной.


2. Виды документации

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

У информации также разный срок жизни и частота изменений. Одни знания сохраняются надолго, другие — меняются вместе с реализацией, какие‑то вовсе нужны только на время работы над конкретной задачей. Это тоже влияет на то, где и как информация хранится.

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

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

Архитектурный документ охватывает общую структуру проекта: инфраструктуру, общие компоненты, разделение на слои и контракты между системами.

Оба вида этих документов отвечают на вопросы «как устроена система сейчас» и «как её можно расширять». Они создаются и обновляются по мере изменения соответствующих механик и систем.

Чтобы не плодить бесполезную информацию и не делать лишнюю работу, отдельные технические документы мы создаём только для крупных, значимых единиц: например, механики боя, магазина или системы синхронизации прогресса.

Также у нас ведутся ADR (Architecture Decision Record). Такой документ появляется, когда команда сталкивается с проблемой, для решения которой нужно провести ресёрч и сделать определённый архитектурный выбор. В нём фиксируем саму проблему, рассмотренные варианты, причины выбора, принятые компромиссы и осознанные последствия.

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

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

Информацию о чём‑то менее значимом или более глубокие подробности реализации мы оставляем ближе к коду: чем информация конкретнее, тем чаще она обновляется вместе с ним. Контракты типов и методов описываем в XML‑документации, неочевидные детали логики — в комментариях, ожидаемое поведение и граничные сценарии — в юнит‑тестах.

На примере системы статусов:

  • Технический документ механики описывает её общие правила и взаимодействие её компонентов.

  • ADR хранит решение об использовании ECS и выборе фреймворка.

  • Архитектурный документ описывает взаимодействие ECS с объектно‑ориентированной частью приложения.

  • XML‑документация описывает контракты методов.

  • Комментарии поясняют сложный алгоритм отбрасывания статусов при коллизиях.

  • Тесты проверяют повторное применение статуса, завершение его действия и сочетание эффектов.

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

Чтобы команда придерживалась единых правил, мы отдельно фиксируем документы‑соглашения: например, как именовать сущности, организовывать проект и разделять контент.

Для AI‑агентов это всё становится кормом для соответствующих скиллов и инструкций.


3. Жизненный цикл документации

Сначала геймдизайнеры формулируют и согласуют требования в ГДД. ГДД у нас хранятся в Confluence. Если нужны интерфейс и визуальные образы, их дополняют UX‑описания, макеты и требования для художников. Эти материалы задают ожидаемое поведение, но не описывают технического устройства.

Разработчик изучает требования, существующую документацию и код: выясняет ограничения, точки интеграции и возможные подходы. На основе исследования появляется черновик‑зарисовка технического документа, который позволяет обсудить решение с коллегами или AI‑агентом до написания кода.

При работе с AI‑агентом дополнительно прорабатывается спецификация задачи — расширенный документ с более детальным описанием необходимых изменений. На её основе составляется план с границами и зависимостями отдельных этапов работы, чтобы потом их распределить по субагентам и построить адекватную историю изменений.

Перед отправкой Merge Request (далее — просто MR) технический документ приводится в соответствие с фактической реализацией. Если мы работаем с уже существующей механикой, то обновляем существующую документацию, но тоже в том же MR. За актуальность отвечает тот, кто выполняет задачу.

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

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

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


4. Организация документации

Техническая документация хранится в Markdown и отдельно от исходного кода, в директории Docs/ в рамках того же Git‑репозитория. Это даёт команде и агентам единое известное место для документов и позволяет поддерживать общую структуру.

Шаблон такой структуры с примерами документов можно найти в git‑репозитории. Все документы намеренно переведены полностью на русский и существенно переработаны со значительным упрощением, чтобы отдалить их от реального проекта.

Docs/
├── README.md
├── tech-passport.md
├── Architecture/
│   ├── Backend/
│   ├── Shared/
│   └── Unity/
├── GameFeatures/
│   ├── CoreGame/
│   └── MetaGame/
├── ADR/
├── Conventions/
└── Guides/

Индекс документации

В корне Docs/ находится README.md — индекс с деревом документов, ссылками и поисковыми тегами. Например:

GameFeatures/
└── CoreGame/
    ├── [attack-system.md](GameFeatures/CoreGame/attack-system.md):
    │   attack, атака, урон
    ├── [status-system.md](GameFeatures/CoreGame/status-system.md):
    │   status, статус, эффект, дебафф, бафф
    └── [ability-system.md](GameFeatures/CoreGame/ability-system.md):
        ability, способность, умение

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

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

Директория Docs/ обособлена от исходного кода, поэтому документацию легко индексировать для векторного поиска и RAG. Но обычно это избыточно: это усложнение, дополнительная поддержка и дисциплина при актуализации индекса. Для одного проекта выигрыша от этого усложнения никакого.

Связь документации с кодом

В XML‑документации классов мы используем <seealso>, чтобы указать соответствующий технический документ:

/// <summary>Управляет жизненным циклом игровых статусов.</summary>
/// <seealso href="status-system.md"/>
public class StatusService
{
}

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

Документация для AI‑агентов

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

./
├── AGENTS.md
├── Docs/
│   └── AGENTS.md
├── .opencode/
├─х .codex
├─х .claude
└── .agents/
    ├── skills/
    ├─х plans/
    │   └── status-system/
    │       ├── spec.md
    │       ├── plan.md
    │       ├── explore.md
    │       ├── research.md
    │       └── probe-01.md
    └─х tmp/

Инструкции для агентов у нас написаны на английском. Были времена, когда русский заметно влиял на качество ответов (и на кол‑во токенов, но кто бы их считал с подписками). Сейчас, по нашим наблюдениям, уже не так важно, на каком языке написаны документы. Но мы продолжаем использовать английский по инерции и для лаконичности.

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

Корневой AGENTS.md служит точкой входа в проект для агента: указывает важные каталоги, источники знаний и основные общие правила.

Вложенные в другие директории AGENTS.md дополняют общие инструкции правилами для отдельных частей проекта. Так, в Docs/ тоже есть свой AGENTS.md с требованиями к структуре и оформлению технических документов. Более конкретные детали описаны уже в соответствующих скиллах.

.agents/ — универсальная директория, которая позволяет хранить контент для агентов независимо от используемого харнесса, как и AGENTS.md. Для специфических харнессов у нас есть инструмент, создающий симлинки, раннюю версию которого я успел показать в своём докладе по AI‑Driven Development.

В каталоге skills/ находятся скиллы для агента. tmp/ служит общим местом для скриптов и прочих временных вспомогательных файлов агента. В plans/ хранятся временные материалы, которые нужны агенту для работы над задачами. Задачи группируются по каталогам с уникальными именами. Содержимое tmp/ и plans/ полностью исключается из git‑репозитория и существует только локально.

Внутри plans/ у каждой задачи могут быть следующие файлы:

  • explore.md — карта текущей области задачи, собранная по документации и коду: компоненты, связи, контракты и другие факты со ссылками на источники. Она помогает понять, как система устроена сейчас.

  • research.md — исследование вариантов решения конкретной проблемы: возможные подходы, их плюсы, минусы и ограничения. На его основе агент выбирает направление работы.

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

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

  • plan.md — разбиение спеки на задачи для субагентов. Для каждой задачи задаются описание, ожидаемый результат, зависимости, порядок выполнения и условия завершения.

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

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

Но есть референсный .opencode/ с подключенными MCP, плагинами, субагентами и прочими настройками, которые можно при желании мигрировать в форматы иных харнессов.

Автоматизация проверок

Каждый MR проходит отдельное AI‑ревью в CI как этап Quality Gate. Это не единственная точка, где агенты проверяют работу. Это происходит ещё и до публикации MR, но здесь — это финальный страховочный пункт.

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

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

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

Ещё сейчас тестируем дополнительного агента, который сверяет изменённые технические документы с ГДД и подсвечивает расхождения на этом уровне. Потому что такое, увы, случается, и за этим сложно уследить.

┌────┐     ┌───────────────┐                 ┌──────────────────┐
│ MR │ ──> │ AI-ревью в CI │ ── проблема ──> │ Комментарий в MR │
└────┘     └───────────────┘                 └──────────────────┘

┌───────────────┐     ┌────────────────────┐     ┌─────────────┐
│ По расписанию │ ──> │ Документация ↔ код │ ──> │ Исправление │
└───────────────┘     └────────────────────┘     └─────────────┘

┌──────────────┐     ┌────────┐                    ┌────────────┐
│ ГДД ↔ техдок │ ──> │ Сверка │ ── расхождение ──> │ Оповещение │
└──────────────┘     └────────┘                    └────────────┘

5. Качество документации

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

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

Документ читают многократно, поэтому минуты, сэкономленные автором на проработке, могут обернуться потерями времени или менталки каждого читателя. Краткость и удобная навигация важны даже тогда, когда сгенерировать ещё букв почти ничего не стоит.

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

Работу с документацией стоит начинать с вопросов: кому она нужна, на какой вопрос должна ответить и нельзя ли получить этот ответ из уже существующих источников? Может оказаться, что отдельный документ и вовсе не нужен. Избыток информации — это такая же проблема, как и её недостаток. За этим нужно следить.

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

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

Комментарии (2)


  1. InsiderCrush
    15.11.2026 14:48

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

    Если в вашей организации документация не прибавила пользы, у вас серьезная проблема с организацией. Документацию придумали не для бюрократии, которая просто побочным эффектом является. Документация это прежде всего защита вашего продукта от нелепых случайностей и человеческого фактора. Это защита от разного рода дрейфов внутри продукта. Это сотни и сотни сэкономленных часов, при масштабировании и при наборе новых сотрудников. А документация сделанная по ГОСТу или ISO это защита помноженная на три. И ставить под сомнение сам смысл ведения документации может только самый прожжённый вайбкодер, который никогда настоящего продукта в прод не выводил.


    1. aks2dio Автор
      15.11.2026 14:48

      Благодарю за мнение и уделённое внимание. Статья как раз посвященна описанной вами проблеме, разве что в более простом и доступном ключе, с акцентом на специфику геймдева.