Тема: Часть 6. Создание конституции
Уровень сложности: Средний
Расчётное время изучения: 3-4 часа (включая практику с Qwen Code)
Предварительные требования: Базовое понимание Git и командной строки
Знакомство с TypeScript и Node.js
Опыт работы с markdown-документами
Понимание основ SDD (Specification-Driven Development) из предыдущих частей курса
Доступ к Qwen Code или аналогичному AI-ассистенту для практических заданий
Цели обучения: Создавать проектную конституцию из трёх обязательных файлов (mission.md, tech-stack.md, roadmap.md) до начала разработки первой фичи
Различать долговременные архитектурные решения (tech-stack.md) и решения уровня отдельной фичи (requirements.md) по критерию переживания пяти фич без изменений
Проводить структурированное интервью с AI-агентом для совместного создания конституции, задавая три сгруппированных блока вопросов
Выявлять и формализовать неявные командные правила в QWEN.md на основе анализа git diff после первой фичи
Проверять конституцию на противоречия, расплывчатость и крупность фаз перед коммитом
Обзор: Конституция — это проектный договор между человеком, AI-агентом и будущими участниками проекта, который предотвращает повторное «угадывание» агентом миссии, стека и порядка работы. В методологии SDD конституция формируется до первой продуктовой фичи и состоит из трёх обязательных файлов в директории specs/: mission.md (зачем и для кого), tech-stack.md (технические решения проекта) и roadmap.md (фазовый план реализации). Эта часть курса учит не просто писать эти документы вручную, а создавать их совместно с агентом через структурированное интервью, проверять на противоречия и выносить неявные правила в явные конвенции. Особое внимание уделяется границе между конституционными решениями и спецификациями фич, а также практике фиксации негласных правил команды в QWEN.md на основе реального опыта взаимодействия с агентом.
Ключевые концепции: Конституция проекта: Набор из трёх файлов (mission.md, tech-stack.md, roadmap.md) в директории specs/, формируемый до первой фичи. Работает как договор: если пропустить, агент будет каждый раз заново угадывать миссию, стек и порядок работы, что приводит к архитектурной деградации и потере целостности.
Mission.md: Отвечает на вопросы «зачем» и «для кого». Содержит назначение продукта, основную аудиторию и критерий успеха. Пример из курса: AgentClinic — сатирическое учебное приложение, где ИИ-агенты — пациенты клиники психического здоровья, а люди вызывают их недуги. Код при этом должен оставаться серьёзным и учебным.
Tech-stack.md: Фиксирует долговременные технические решения проекта: язык, среду выполнения, веб-фреймворк, СУБД, библиотеку тестирования, ограничения на зависимости. Ключевой принцип: решения здесь должны пережить минимум пять фич без изменений. Каждое изменение влечёт перепланирование (часть 10 курса).
Roadmap.md: Короткая дорожная карта, разбитая на маленькие фазы, каждая из которых помещается в одну сфокусированную ветку. Фазы должны быть настолько маленькими, чтобы их можно было проверить без героизма. Пример: Фаза 1 только доказывает работоспособность базовой связки, Фаза 2 добавляет доменные данные.
Граница tech-stack.md / requirements.md: Фундаментальное правило разделения: в tech-stack.md живут решения уровня проекта (переживают пять фич), в requirements.md фичи — решения уровня одной фичи (маршруты, поля форм, правила валидации). Простой тест: если решение забудется после слияния фичи — оно в requirements.md. Пример: «использовать Hono» — tech-stack.md; «маршрут GET /agents отдаёт HTML со списком из 10 записей» — requirements.md фичи; «все списки отдают по 10 записей по умолчанию» — tech-stack.md или conventions.md.
Qwen.md и неявные правила: Документ для фиксации негласных командных правил, которые агент стабильно угадывает неверно. Типичные области: стиль кода и именование, запрещённые конструкции (any, @ts-ignore), список разрешённых зависимостей, формат сообщений об ошибках, структура обработки ошибок, формат коммитов, ритуалы перед слиянием. Лучший способ выявить — проанализировать git diff после первой фичи и найти правки стиля или решений, сделанные за агентом.
Интервью через qwen code: Структурированный процесс совместного создания конституции: агенту даётся контекст, он задаёт ровно три сгруппированных вопроса (миссия и аудитория, технический стек, дорожная карта), получает конкретные решения в ответе, а не общие пожелания, и только затем записывает файлы. Если агент пропускает интервью — его нужно остановить и потребовать следовать протоколу.
Проверка конституции: Обязательный шаг перед коммитом: агент проверяет собственные файлы на противоречия, расплывчатые формулировки и слишком крупные фазы. Типичные проблемы: дорожная карта требует героизма, стек содержит зависимости «на всякий случай», mission.md не определяет читателя кода, SQLite упомянут в дорожной карте но не в стеке, «современный интерфейс» без конкретных ограничений.
Практические упражнения: Название: Упражнение 1: Классификация решений — куда записать?
Проблема: Даны пять технических решений для проекта AgentClinic. Определите для каждого, в какой документ оно попадает: tech-stack.md, requirements.md фичи, или roadmap.md. Обоснуйте по критерию «переживёт пять фич».
- Использовать библиотеку Hono для веб-фреймворка
- Маршрут POST /appointments принимает поля agentId, ailmentId, date и возвращает 201 с ID записи
- Добавить ORM Prisma для работы с базой данных
- Фаза 2: добавить таблицу терапий и страницу /therapies
- Все формы на сайте используют серверную валидацию с возвратом ошибок в одном формате
Решение: 1. tech-stack.md — выбор веб-фреймворка определяет архитектуру всего проекта, переживёт множество фич.
- requirements.md фичи «Запись на приём» — конкретный маршрут, поля и код ответа относятся к одной фиче, после реализации забудется.
- tech-stack.md — выбор ORM — долговременное архитектурное решение, влияет на все слои работы с данными.
- roadmap.md — это фаза дорожной карты, не техническое решение и не детали фичи.
- tech-stack.md (или отдельный conventions.md) — правило валидации для всех форм проекта, переживёт множество фич. Если бы речь шла только о форме записи на приём — это было бы requirements.md.
Сложность: beginner
Название: Упражнение 2: Составление mission.md для нового проекта
Проблема: Вы начинаете проект «DevGarden» — платформу для визуализации роста навыков разработчика в форме сада растений. Каждый коммит поливает растение, пропуск дня — увядание. Напишите полный файл mission.md, включающий: назначение (сатирический или серьёзный тон?), основную аудиторию (минимум 2 группы), критерий успеха. Следуйте структуре из курса.
Решение: Пример ответа:
# Миссия
DevGarden — платформа, которая превращает историю коммитов разработчика в живой сад: регулярная активность поливает растения, перерывы приводят к увяданию.
## Назначение
Продукт — мотивационный инструмент с элементами геймификации. Завязка подаётся в полусерьёзном тоне: растения реагируут на реальную активность в репозиториях, а увядание — наглядная метафора «технического долга» врезервуара внимания.
## Основная аудитория
- Разработчики, изучающие SDD с агентами, которые пишут код.
- Команды, внедряющие геймификацию метрик разработки.
- Инженеры, изучающие интеграцию с GitHub API и серверное приложение на TypeScript.
## Успех
Разработчик должен понять, как SDD-артефакты помогают сохранить единую метафору продукта через множество фич, и уметь расширять сад новыми видами растений без потери архитектурной цельности.Проверьте: есть ли ответ на «зачем» (мотивация через метафору), «для кого» (3 группы), конкретный критерий успеха (понимание роли SDD-артефактов, а не просто «приложение работает»).
Сложность: intermediate
Название: Упражнение 3: Анализ git diff для создания QWEN.md
Проблема: После первой фичи с агентом вы обнаружили в git diff следующие правки, сделанные вручную за агентом:
- Агент использовал
console.logдля ошибок БД → вы заменили на структурированный логгер с уровнями - Агент назвал переменную
usrData→ вы переименовали вuserData - Агент поставил
// @ts-ignoreперед запросом к SQLite → вы убрали и добавили правильную типизацию - Агент написал коммит «some fixes» → вы переписали на «fix(db): handle connection timeout in agent repository»
- Агент добавил зависимость
lodashдля одной функцииdebounce→ вы заменили на нативную реализацию
Сформулируйте 3-5 правил для QWEN.md на основе этих паттернов.
Решение: Пример QWEN.md:
# QWEN.md — Конвенции проекта AgentClinic
## Логирование
- В продуктовом коде запрещены прямые `console.log` и `console.error`
- Использовать единый структурированный логгер с уровнями (info, warn, error, debug)
- Сообщения об ошибках БД должны включать контекст операции, не раскрывать чувствительные данные
## Именование
- Запрещены сокращения: `usr`, `data`, `cnt` → использовать `user`, `data`, `count`
- camelCase для переменных и функций, PascalCase для классов и интерфейсов, snake_case для полей БД
## TypeScript
- Запрещены `any` и `// @ts-ignore` в продуктовом коде
- Каждый запрос к БД должен иметь явную типизацию результата
## Коммиты
- Формат: `<type>(<<scope>): <глагол в настоящем времени> + <объект>`
- Примеры: `feat(agents): add list endpoint`, `fix(db): handle connection timeout`
- Запрещены коммиты вида «fix», «update», «some changes»
## Зависимости
- Новая зависимость требует обсуждения и обновления tech-stack.md
- Предпочитать нативные решения библиотекам для простых задач (debounce, throttle, deep clone простых объектов)Ключевой навык: превращать наблюдаемые паттерны ошибок в конкретные, проверяемые правила, а не общие рекомендации.
Сложность: intermediate
Название: Упражнение 4: Проверка конституции на противоречия
Проблема: Дана черновая конституция проекта. Найдите минимум 4 проблемы, которые должен выявить шаг проверки перед коммитом.
# mission.md
AgentClinic — клиника для ИИ-агентов. Учебное приложение для всех.
# tech-stack.md
- TypeScript
- Hono
- SQLite (локальное хранение)
- ORM Prisma
- React для UI
- Vitest
# roadmap.md
## Фаза 1
- Установить все зависимости
- Настроить базу данных с миграциями
- Создать все таблицы (agents, ailments, therapies, appointments)
- Реализовать все маршруты (GET, POST, PUT, DELETE)
- Добавить аутентификацию администратора
- Написать тесты на всёРешение: Выявленные проблемы:
- Расплывчатая миссия: «для всех» — не конкретная аудитория, нет критерия успеха, не ясен тон (сатирический/серьёзный).
- Противоречие в стеке: в tech-stack.md указан React для UI, но в курсе и в типичном подходе AgentClinic используется серверный рендеринг Hono JSX — нужно уточнить, является ли React сознательным отступлением от учебной методологии.
- SQLite в дорожной карте, но не в стеке: SQLite упомянут в tech-stack.md (ок), но ORM Prisma добавлена без обоснования — в курсе прямо указано «прямые SQL-миграции до появления ORM», то есть ORM появляется позже, не в начале.
- Фаза 1 требует героизма: 6 пунктов, включая «всё» — маршруты всех типов, аутентификацию, тесты на всё. Это нарушает принцип «каждая фаза в одну ветку, проверяется без героизма». Должно быть разбито на 3-4 фазы.
- Зависимость «на всякий случай»: аутентификация администратора в первой фазе учебного сатирического приложения — возможно, преждевременная сложность, не обоснованная миссией.
- Нет ограничений в стеке: отсутствуют правила добавления зависимостей, нет запрета на «на всякий случай».
Сложность: advanced
Кейсы: Название: Кейс: Как команда потеряла три итерации из-за отсутствия mission.md
Сценарий: Команда из трёх разработчиков начала проект «EcoTrack» — приложение для отслеживания углеродного следа. Технический лидер быстро написал tech-stack.md с React Native и Firebase, а дорожную карту составил на три крупные фазы по два месяца каждая. Файл mission.md посчитали излишним — «всё и так понятно, экология и всё такое».
Задача: После первой итерации выяснилось, что разработчики понимали продукт по-разному: один делал B2C-приложение для экологичного шопинга, второй — корпоративный дашборд для ESG-отчётности, третий — геймифицированный трекер для школьников. В tech-stack.md появились конфликтующие добавления: Mapbox для карт магазинов, Tableau-интеграция для отчётов, Unity для игровых механик. Агент (Claude Code) при каждой новой фиче переспрашивал базовые вещи и генерировал код под разные аудитории в разных частях приложения.
Решение: Команда остановила разработку, провела совместную сессию с агентом через структурированное интервью. mission.md был создан с чётким определением: «EcoTrack — B2B SaaS для средних компаний (50-500 сотрудников), которым нужно автоматизировать сбор данных для ESG-отчётности по стандарту GRI. Тон: деловой, без геймификации». Технический стек очистили от Mapbox и Unity, добавили ограничение «новая интеграция требует обоснования ROI для целевой компании». Дорожную карту разбили на фазы по одну-две недели: Фаза 1 — прототип импорта данных из Excel, Фаза 2 — расчёт базовых метрик, Фаза 3 — генерация GRI-отчёта.
Результат: После внедрения конституции скорость разработки выросла на 40% (по метрике story points за спринт). Агент перестал «угадывать» и начал предлагать решения в рамках заданной архитектуры. Код-ревью сократилось с 15 комментариев «а зачем это?» до 2-3 технических замечаний. Через 4 месяца продукт запустили с тремя пилотными компаниями.
Извлечённые уроки: mission.md — не «вода», а фильтр для всех последующих решений: без него даже хороший tech-stack.md размывается под давлением неопределённости
Интервью с агентом работает как катализатор конвергенции команды: вынуждает формулировать неявные договорённости явно
Крупные фазы маскируют неопределённость: если фазу невозможно проверить за неделю, значит внутри неё спрятаны непроработанные риски
Агент как «зеркало» отражает хаос в проекте: если он постоянно «угадывает» по-разному, проблема не в агенте, а в отсутствии конституции
Связанные концепции: mission.md
Интервью через Qwen Code
Граница tech-stack.md / requirements.md
Проверка конституции
Название: Кейс: Как один разработчик создал QWEN.md после первой фичи и сэкономил 20 часов
Сценарий: Инди-разработчик Анна начала проект «BookShelf» — сервис для обмена книгами в районе. Она использовала Qwen Code для ускорения разработки. После первой фичи (регистрация и профиль) она заметила, что тратит много времени на правку стиля кода, возвращённого агентом.
Задача: Анализ git diff показал 47 ручных правок в 12 коммитах: агент использовал разные стили именования (snake_case vs camelCase), добавлял any для «простоты», писал коммиты на русском и английском вперемешку, использовал console.log вместо настроенного логгера pino. Каждая новая фича требовала повторения этого цикла правок.
Решение: Вместо продолжения «ручного» контроля Анна потратила 2 часа на создание QWEN.md на основе паттернов из git diff. Документ включал: таблицу соответствия контекстов и стилей именования (БД — snake_case, код — camelCase), запрет any с альтернативными паттернами типизации, шаблон коммита с примерами, требование использовать pino с уровнем логирования из конфига. Она также добавила раздел «Ритуал перед слиянием»: запуск линтера, тип-проверки, и одного теста на happy path.
Результат: Во второй фиче ручных правок сократилось с 47 до 3 (все — логические, не стилистические). Время на код-ревью собственных PR сократилось с 45 минут до 5. Агент начал генерировать коммиты в правильном формате самостоятельно. Через три фичи Анна расширила QWEN.md правилом «новая зависимость обсуждается» — агент предложил добавить lodash, и она отклонила, заменив на нативную реализацию, что сократило бандл на 12 КБ.
Извлечённые уроки: git diff после первой фичи — бесплатный аудит неявных правил: каждая ручная правка — кандидат в QWEN.md
QWEN.md окупается за одну фичу: 2 часа написания vs 20+ часов экономии на последующих итерациях
Конкретные примеры в QWEN.md важнее абстрактных правил: «использовать pino» хуже, чем «использовать pino с уровнем из config.logLevel, не console.log»
QWEN.md — живой документ: он растёт с проектом, но начинается с реальных болей, а не предполагаемых
Связанные концепции: QWEN.md и неявные правила
Проверка конституции
Граница tech-stack.md / requirements.md
Советы по изучению: Проходите материал последовательно: сначала поймите «зачем конституция», потом изучите структуру каждого файла, затем практикуйте интервью с агентом. Пропуск шага приводит к формальному созданию документов без понимания их роли.
Используйте метод «параллельного чтения»: открывайте одновременно исходный документ курса и примеры из practice_exercises, сравнивайте структуру. Это укрепляет паттерн-распознавание для самостоятельной работы.
Обязательно выполните упражнение 4 (проверка на противоречия) с таймером: ограничьте себя 10 минутами, как при реальном код-ревью. Давление времени тренирует выявление критических проблем вместо «идеального» анализа.
Создайте шаблоны файлов конституции в своём редакторе с плейсхолдерами вроде [НАЗНАЧЕНИЕ], [ОСНОВНАЯ_АУДИТОРИЯ_1]. Используйте их при каждом новом проекте — физический ритуал ускоряет внутреннее освоение методологии.
Ведите «дневник агентских интервью»: записывайте, какие вопросы задавал агент, какие ответы вы дали, что пошло не так. Через 3-4 проекта у вас сформируется личная библиотека «классических ловушек» и эффективных формулировок.
Для кинестетиков: напечатайте физическую карточку с критерием «переживёт пять фич» и положите рядом с монитором. При каждом решении физически перемещайте карточку: «это в стек?» — положить на tech-stack.md, «это в фичу?» — на requirements.md.
Для аудиалов: проговаривайте вслух шаги проверки конституции перед коммитом: «SQLite есть в стеке? Фазы помещаются в ветки? Миссия говорит, кто читает код?» — ритм речи создаёт мнемоническую опору.
Для визуалов: нарисуйте схему «жизненный цикл решения» — от появления идеи через тест «пять фич» до финального места в документации. Цветовое кодирование (красный — tech-stack.md, синий — requirements.md, зелёный — roadmap.md) ускоряет принятие решений в реальном времени.
Дополнительные ресурсы: Оригинальный документ курса (часть 6): Исходный материал, на котором основан этот гайд — обращайтесь для уточнения деталей и примеров кода
Документация hono: https://hono.dev — минимальный веб-фреймворк, рекомендуемый в курсе для серверного TypeScript
Conventional commits: https://www.conventionalcommits.org — стандарт формата коммитов, типичный элемент QWEN.md
Sqlite на node.js: https://github.com/WiseLibs/better-sqlite3 — популярный драйвер для работы с SQLite без ORM, соответствует философии курса
Vitest: https://vitest.dev — фреймворк тестирования, упомянутый в tech-stack.md примера
Шаблон mission.md от gitlab: https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#documentation-templates — альтернативные подходы к структурированию миссии продукта
Статья «architecture decision records»: https://adr.github.io — родственная практика фиксации долговременных решений, расширяет понимание роли tech-stack.md
Резюме: Конституция — сердце SDD-проекта: три файла (mission.md, tech-stack.md, roadmap.md), созданные до первой фичи, предотвращают хаотичное «угадывание» агентом и обеспечивают архитектурную целостность. Ключевые навыки этой части: различать долговременные решения (стек) и решения фич (requirements) по тесту «пять фич»; проводить структурированное интервью с агентом вместо ручного написания; выявлять неявные правила через анализ git diff и фиксировать в QWEN.md; проверять конституцию на противоречия и крупность фаз перед коммитом. Практика показывает: 2 часа на конституцию и QWEN.md экономят 20+ часов на последующих итерациях. Конституция живёт — она растёт с проектом, но её отсутствие в начале гарантирует архитектурный долг.