Архитектурное ТЗ для Codex должно отвечать не только на вопрос «что построить», но и на вопросы «где проходят границы системы», «какие данные она хранит» и «что нельзя менять». Без этого агент может предложить логичную реализацию, которая не подходит существующему проекту или усложняет его поддержку.
Хорошее ТЗ не обязательно длинное. Важно, чтобы разработчик мог отличить обязательное требование от предположения, а заказчик мог проверить результат. Ниже приведена структура для небольшого бизнес-приложения, а не универсальная архитектура для любого масштаба.
Опишите текущую систему
Укажите, новый это проект или доработка. Для существующего приложения перечислите язык, фреймворк, базу данных, место развертывания, способ авторизации и внешние сервисы. Не навязывайте новый стек только потому, что он знаком модели. Сначала нужно понять ограничения уже работающей системы.
Приложите карту основных каталогов и команды проверок. Секреты в документ не включают: вместо пароля пишут название переменной окружения и объясняют, кто предоставляет доступ. Если версия компонента неизвестна, попросите установить ее по файлам зависимостей, а не угадать.
Разделите требования на четыре части
- Поведение: какие действия доступны пользователям и что происходит при ошибках.
- Данные: сущности, обязательные поля, связи, сроки хранения и владельцы записей.
- Границы: ответственность модулей, контракты API, внешние интеграции.
- Эксплуатация: запуск, журналирование, резервные копии, восстановление и измеримые ограничения.
Фраза «система должна быть быстрой» не дает критерия приемки. Лучше описать сценарий измерения: какое действие проверяем, сколько одновременных запросов создаем, на каком объеме данных и в каком окружении. Целевое время выбирают под бизнес-задачу. Его нельзя выдавать за достигнутый результат до тестирования.
Пример структуры ТЗ для заявок
Проект: учет входящих заявок.
Пользователи: менеджер и администратор.
Данные: заявка, контакт, статус, история изменений.
Вход: форма сайта; выход: очередь для менеджера.
Правило: ошибка сохранения не считается успешной заявкой.
Доступ: менеджер видит только разрешенные ему записи.
Интеграция: передача в CRM через отдельный адаптер.
Повтор: одна операция не создает две одинаковые заявки.
Журнал: идентификатор операции, результат, время;
без паролей и полных персональных данных.
Проверки: валидация, права, повтор, отказ CRM.
Не входит: телефония, платежи, массовые рассылки.Это каркас для обсуждения. Например, правило защиты от дублей нужно уточнить: одинаковый телефон не обязательно означает одинаковую заявку. Пользователь может обратиться повторно через неделю. Надежнее определить идентификатор конкретной операции и срок, в течение которого повторная доставка считается повтором.
Опишите интеграцию как договор между системами
Для CRM или 1С мало написать «синхронизировать данные». Нужно решить, какая система является источником истины, кто может изменять поле и что произойдет при конфликте. Уточните направление передачи, периодичность, подтверждение доставки и порядок повторных попыток.
Например, цены приходят из 1С, а контакты создаются на сайте. Тогда ручное изменение цены в административной панели сайта может быть запрещено или временно: следующая синхронизация его перезапишет. Такое поведение нужно согласовать до реализации, иначе технически исправная интеграция станет источником споров.
При недоступности внешней системы заявка должна либо сохраняться локально с понятным статусом отправки, либо возвращать пользователю честную ошибку. Выбор зависит от архитектуры. Нельзя молча терять данные и считать интеграцию успешной по факту отправленного HTTP-запроса.
Не проектируйте лишние уровни заранее
Небольшой сервис не обязан начинаться с микросервисов, отдельного брокера и нескольких баз. Дополнительные компоненты оправданы конкретной нагрузкой, требованиями изоляции или существующим окружением. Каждый компонент нужно обновлять, наблюдать и восстанавливать после сбоев.
Попросите Codex сначала предложить решение на основе текущих инструментов и отдельно объяснить, где понадобится новая зависимость. Сравнивайте не только удобство написания кода, но и стоимость сопровождения. Иногда один понятный модуль с четким интерфейсом лучше универсального расширяемого фреймворка.
Попросите проверить противоречия до кода
Прочитай ТЗ и существующий проект. Пока не меняй код.
Выдели противоречия и неизвестные условия.
Для каждого укажи влияние на данные, API и приемку.
Предложи минимальную архитектуру на текущем стеке.
Отдели обязательные изменения от возможных улучшений.
Не выбирай способ хранения секретов без учета окружения.После ответов обновите само ТЗ. Решение, оставшееся только в переписке, легко потерять при передаче задачи. У каждого спорного пункта должен быть статус: принято, отложено или требует проверки. Для контекста и ограничений можно использовать приемы из официального руководства по запросам Codex, но бизнес-правила придется определить самостоятельно.
Закончите документ приемкой и откатом
Для каждого изменения запишите, как его проверить и как вернуть предыдущую версию. Особое внимание уделите миграциям: откат приложения не всегда возвращает удаленные данные. До изменений базы необходима резервная копия и проверенный способ восстановления на тестовой среде.
Затем превратите ТЗ в небольшие MVP-задачи. Не поручайте агенту весь документ одним неограниченным запуском. Приемка каждого этапа должна опираться на реальные проверки, а не на уверенность итогового сообщения.
Нужна архитектура сайта с CRM, 1С или внутренними процессами? Опишите задачу VSVP: сначала определим владельцев данных, риски интеграции и границы первой версии.
