5 файлов документации, без которых Claude Code ломает архитектуру приложения

Документация к мобильному приложению, которое пишет Claude Code, лежит в репозитории рядом с кодом: файл CLAUDE.md с правилами и командами сборки, папка docs с требованиями, архитектурой, контрактом API и журналом решений. CLAUDE.md агент читает при старте каждой сессии, остальное открывает по ссылкам из него. Так договорённости не теряются между сессиями.

Почему возникает путаница: Claude Code каждую сессию начинает с чистого листа 🧠

Типичная картина на проекте B2B-приложения с 1С для торговых представителей. Во вторник разработчик просит агента добавить экран заявки, к вечеру экран работает. В четверг выясняется: агент подключил его напрямую к API и обошёл слой синхронизации, который две недели назад писали под офлайн-режим. Торговый представитель стоит в подвале склада без связи, нажимает «Отправить», и заявка исчезает.

Про офлайн-режим агент не знал. Он опирается на код, который прочитал в этой сессии, и на файлы с инструкциями, прежде всего CLAUDE.md. Требование жило в переписке в Telegram и в голове одного разработчика, поэтому агент выбрал самый короткий путь: логичный на вид, но ломающий договорённость. Живой программист переспросил бы коллегу. Агент чаще достраивает недостающее сам, причём делает это за час, поэтому ошибка расползается по проекту быстрее, чем её замечают.

Из кода агент не вытащит четыре вещи:

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

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

Как исправить путаницу: пять файлов документации, которые агент читает 📁

Толстое ТЗ на сто страниц не нужно. Нужен короткий набор файлов в репозитории, где каждый отвечает на один вопрос.

Что писать в CLAUDE.md

Команда /init в Claude Code создаёт черновик файла по существующему коду. Черновик пересказывает структуру проекта, а бизнес-условия и запреты в нём придётся дописать руками. Обычно это:

• ✓стек и версии, например Kotlin и Jetpack Compose или Swift и SwiftUI;
• ✓команды, которые агент запускает сам: сборка, линтер, тесты;
• ✓границы слоёв: «сетевые вызовы только через репозитории, экраны в API не ходят»;
• ✓запреты: не трогать сгенерированные файлы, не менять схему локальной базы без записи в decisions.md;
• ✓ссылки на остальные файлы в виде @docs/architecture.md.

Держите файл коротким. Когда он вырастает до нескольких экранов, правила в нём тонут, и агент исполняет их выборочно. Подробности уводите в docs.

Что писать в docs

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

В api-contract.md описывают обмен с бэкендом и учётной системой: форматы документов, идентификаторы номенклатуры, правило при конфликте остатков. Потерять этот файл дороже всего, потому что ошибка в обмене портит данные в 1С, а не только картинку на экране. Как устроена такая связка, показано на странице про интеграцию мобильного приложения с 1С.

В decisions.md на каждое развилочное решение уходит три строки: контекст, выбор, отвергнутые варианты. Первой стоит запись про платформу: писать нативно или на 1С:Мобильной платформе. Без неё через полгода кто-то предложит «переписать всё на другом стеке» и повторит уже закрытый спор.

Что делать, если ошибка повторяется: агент нарушает правило из CLAUDE.md

В файле написано «экраны не ходят в API напрямую», а в пятницу агент делает это снова. Причина в формулировке правила или в объёме файла. Проверьте по порядку:

1. ✓Сократите файл. Правило, которое потерялось среди десятков соседних, агент не выполнит.
2. ✓Перепишите правило так, чтобы его можно было проверить. «Пиши аккуратный код» нельзя ни нарушить, ни выполнить. «Сетевые вызовы только в пакете data/repository» проверяется одним поиском по проекту.
3. ✓Добавьте автоматическую проверку. Линтер или тест, который падает, когда экран обращается к API, ловит нарушение раньше ревьюера. Команду запуска впишите в CLAUDE.md, и агент прогонит её сам. Для жёстких запретов подойдут hooks: скрипт срабатывает на событие вроде правки файла и может остановить действие.
4. ✓Начинайте каждую новую задачу с /clear. Длинная сессия забивается промежуточными правками, а после очистки агент заново читает CLAUDE.md.
5. ✓Каждую повторившуюся ошибку превращайте в строку файла: что случилось и что делать вместо этого.

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

Как выглядит проверяемое правило

Расплывчатое «Следи за качеством кода и не ломай офлайн» лучше заменить тремя строками в CLAUDE.md:

• ✓«Заявку сохраняет только OrderRepository: он пишет в локальную базу и ставит заявку в очередь отправки.»
• ✓«Перед правкой пакета data/sync прочитай @docs/architecture.md.»
• ✓«После правок запусти ./gradlew test и ./gradlew lint и не завершай задачу, пока обе команды не проходят.»

Для iOS или Flutter команды другие, логика та же: правило называет место и способ проверки.

Как предотвратить потерю знаний: правила жизни документации 🛡️

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

• ✓Документацию меняют в том же коммите, что и код. Поменяли метод обмена, а api-contract.md не тронули, значит, ревью не пройдено.
• ✓Перед новой функцией сначала пишут сценарий в requirements.md. Затем просят Claude Code составить план в режиме планирования, сверяют его с architecture.md и только после этого разрешают менять файлы.
• ✓Устаревший файл правят или удаляют сразу. Отсутствие документа лучше неверного: агент выполнит неверный буквально.
• ✓В CLAUDE.md не кладут секреты. Файл лежит в репозитории, и его видит каждый, у кого есть доступ, поэтому ключи и пароли живут в переменных окружения.
• ✓Работают на тестовых данных. Обработку персональных данных клиентов и сотрудников регулирует 152-ФЗ, поэтому выгрузку из боевой базы не вставляют ни в промпты, ни в примеры документации.

У каждого файла должен быть один владелец с именем: разработчик ведёт architecture.md, менеджер проекта отвечает за requirements.md. Файл без владельца устаревает первым.

Простая проверка на прочность: попросите человека, который не видел проект, собрать приложение только по документам. Всё, на чём он споткнётся, и есть дыры. Агенту такая проверка нужнее, потому что недостающее он достроит сам.

Что потребовать от подрядчика при приёмке приложения

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

• ✓доступ к репозиторию на стороне заказчика вместе с историей коммитов;
• ✓CLAUDE.md и папку docs с пятью файлами, актуальными на дату приёмки;
• ✓инструкцию «с нуля до запуска»: как собрать приложение и поднять тестовое окружение;
• ✓контракт обмена с 1С и описание тестовых данных;
• ✓перечень переданных ключей и учётных записей с указанием, где они хранятся.

Если в компании нет собственных разработчиков, эти файлы остаются единственной страховкой от зависимости от одного исполнителя.

Сколько стоит разработка приложения и как мы ведём проект 💼

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

Разработка мобильного приложения у нас стоит от 500 000 руб. Итог зависит от числа платформ, ролей пользователей и объёма обмена с 1С. Остальные расценки собраны на странице цены и тарифы.

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

❓ Частые вопросы

Что такое CLAUDE.md и зачем он нужен мобильному проекту?

CLAUDE.md — текстовый файл в корне репозитория, который Claude Code читает при старте каждой сессии. В нём пишут стек, команды сборки и тестов, правила кода и запреты. Для мобильного проекта он удерживает договорённости об архитектуре, офлайн-режиме и обмене с 1С, поэтому агент не начинает с чистого листа.

Сколько документации нужно для мобильного приложения малого бизнеса?

Хватает пяти файлов: CLAUDE.md, требования, архитектура, контракт API и журнал решений. Толстое ТЗ не нужно. Агенту и новому разработчику важнее короткие проверяемые формулировки, например: «без связи заявка сохраняется на телефоне и уходит, когда появляется сеть». Подробности выносят в отдельные файлы и подключают ссылкой.

Кому принадлежат код и документация приложения, которое писал подрядчик?

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

Можно ли передавать ИИ-агенту данные клиентов из 1С?

Реальные персональные данные лучше не отправлять: их обработку регулирует 152-ФЗ, а передача внешнему сервису, особенно зарубежному, требует отдельного юридического разбора. Для разработки берите тестовую выборку, например вымышленные записи с тем же форматом полей. Ключи доступа и пароли в промпты и в CLAUDE.md тоже не вставляют.

Сколько стоит разработка мобильного приложения с интеграцией 1С?

Разработка мобильного приложения у нас стоит от 500 000 руб. Итоговая сумма зависит от числа платформ, ролей пользователей и объёма обмена с 1С. Точную стоимость называем после разбора требований, поэтому чем полнее описаны сценарии и контракт обмена, тем точнее оценка. Документация ведётся в репозитории заказчика.