Часть 6. Создание конституции

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

specs/
  mission.md
  tech-stack.md
  roadmap.md

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

Что входит в mission.md

mission.md отвечает на вопросы «зачем» и «для кого»:

# Миссия

AgentClinic — вымышленная клиника психического здоровья, где ИИ-агенты восстанавливаются после стресса от работы с людьми.

## Назначение

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

## Основная аудитория

- Разработчики, изучающие SDD с агентами, которые пишут код.
- Разработчики, показывающие демонстрации ИИ-кодинга.
- Инженеры, изучающие небольшое серверное приложение на TypeScript.

## Успех

Разработчик должен понять структуру приложения, роль SDD-артефактов в реализации и способ расширять проект без потери архитектурной цельности.

Что входит в tech-stack.md

tech-stack.md фиксирует технические решения:

# Технический стек

## Язык и среда выполнения

- TypeScript в строгом режиме.
- Node.js как среда выполнения.

## Веб-фреймворк

- Hono для серверных маршрутов.
- Hono JSX для HTML, который рендерится на сервере.
- Без клиентского фреймворка в первых фазах.

## Хранение данных

- SQLite для локального хранения.
- Прямые SQL-миграции до появления ORM.

## Тестирование

- Vitest для автоматической проверки после добавления тестовой инфраструктуры.

## Ограничения

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

Что входит в roadmap.md

Дорожная карта должна быть короткой и разбитой на фазы:

# Дорожная карта

Каждая фаза должна помещаться в одну сфокусированную ветку.

## Фаза 1: Hello Hono

Цель: доказать, что базовая связка TypeScript и Hono работает.

- [ ] Установить Hono и tsx.
- [ ] Создать маршрут GET /.
- [ ] Вернуть минимальный HTML с серверным рендерингом.
- [ ] Добавить скрипт проверки типов.

## Фаза 2: Агенты и недуги

Цель: добавить базовые доменные данные.

- [ ] Добавить базу SQLite.
- [ ] Добавить таблицу агентов и начальные данные.
- [ ] Добавить таблицу недугов и начальные данные.
- [ ] Добавить страницы /agents и /ailments.

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

tech-stack.md и requirements.md фичи: что куда

Студенты часто путают, какие решения попадают в конституцию, а какие — в спецификацию фичи. Граница простая.

В specs/tech-stack.md живут долговременные решения проекта: язык, веб-фреймворк, СУБД, библиотека тестирования, общая модель кэширования. Их меняют редко, и каждое изменение влечёт перепланирование (часть 10).

В specs/<feature>/requirements.md живут решения уровня фичи: какие маршруты добавить, какие поля в форме, какие правила валидации, какой текст ошибки. Их меняют от спецификации к спецификации, без перепланирования.

Простой тест: если решение переживёт пять фич без изменений, оно в tech-stack.md. Если оно касается одной фичи и забудется после слияния — оно в requirements.md.

Пример: «использовать Hono» — это tech-stack.md. «Маршрут GET /agents отдаёт HTML со списком из 10 записей» — это requirements.md фичи. «Все списки на сайте отдают по 10 записей по умолчанию» — это снова tech-stack.md (или отдельный conventions.md, если такой решите завести).

Что вынести из голов в QWEN.md и конституцию

Большая часть негласных правил команды нигде не записана. Они живут в головах: «у нас обработчики ошибок выглядят вот так», «никогда не используем any», «коммиты пишем в формате «глагол + объект»», «в маршрутах сначала валидация, потом запрос к базе». Пока правил мало и команда маленькая, это не больно. Когда работу делает агент, эти правила невидимы.

Хорошая практика — выносить такие неявные знания в QWEN.md или конституцию. Несколько типичных мест, которые стоит проверить и записать:

• стиль кода и именование (когда camelCase, когда snake_case, можно ли использовать сокращения);
• запрещённые конструкции (any, // @ts-ignore, прямые console.log в продуктовом коде);
• список разрешённых зависимостей и правило «новая зависимость требует обсуждения»;
• формат сообщений об ошибках для пользователя и для логов;

• как именно структурируется обработка ошибок (исключения, тип-результат, что-то ещё);
• формат сообщений коммитов;
• ритуалы перед слиянием (какие команды запускаются, кто ревьюит).

Запишите не всё, что в головах, а то, что агент стабильно угадывает неверно. Лучший способ это понять — после первой фичи открыть git diff и найти моменты, где вы исправляли стиль или решения за агентом. Каждая такая правка — кандидат на правило в QWEN.md.

Интервью через Qwen Code

Запрос:

Мы пишем AgentClinic — место, где ИИ-агенты отдыхают от людей.
Посмотри @README.md и используй пожелания участников проекта.

Создай конституцию в @specs:
- mission.md
- tech-stack.md
- roadmap.md

Перед записью на диск задай мне ровно три сгруппированных вопроса:
1. Миссия и целевая аудитория
2. Технический стек и ограничения
3. Дорожная карта и первая фаза реализации

Используй серверный TypeScript. Порекомендуй минимальный веб-фреймворк, но пока не устанавливай его.

Если Qwen Code не задаёт вопросы и сразу пишет файлы, остановите его:

Остановись. Не записывай файлы до интервью.
Сначала задай три сгруппированных вопроса, как указано в QWEN.md.

Как отвечать на вопросы агента

Хороший ответ содержит решения, а не общие пожелания:

Миссия:
Приложение учебное и сатирическое. Содержание должно быть смешным, код — серьёзным.
Основная аудитория: разработчики, изучающие SDD, и зрители демонстраций ИИ-кодинга.

Технический стек:
Используем серверный TypeScript. Предпочитаем Hono. SQLite добавим позже. React пока не нужен.
Оставляем строгий TypeScript. В первой фазе с базой данных не используем ORM.

Дорожная карта:
Фаза 1 должна только доказать, что базовая Hono-связка работает.
Фаза 2 может добавить агентов и недуги.
Фаза 3 может добавить терапии и записи на приём.
Каждая фаза должна помещаться в одну ветку.

Проверка конституции до коммита

Попросите Qwen проверить свои же файлы:

Проверь @specs/mission.md, @specs/tech-stack.md и @specs/roadmap.md.
Найди противоречия, расплывчатые формулировки и решения, слишком крупные для первой фазы.
Пока не изменяй файлы.

Типичные проблемы:

• дорожная карта слишком крупная;
• технический стек содержит зависимости «на всякий случай»;
• mission.md не говорит, кто читатель кода;
• SQLite упомянут в дорожной карте, но не в техническом стеке;

• «современный интерфейс» написан без конкретных ограничений.

Коммит

git add specs/mission.md specs/tech-stack.md specs/roadmap.md
git commit -m "Add SDD project constitution"

Практика

1. Дайте Qwen Code исходные пожелания участников проекта из README.
2. Проведите интервью.
3. Создайте три файла конституции.
4. Проверьте их на противоречия.
5. Закоммитьте.

Контрольные вопросы

1. Почему конституцию нужно писать вместе с агентом, а не просто вручную?
2. Какие решения должны жить в tech-stack.md, а не в спецификации фичи?
3. Почему дорожная карта должна состоять из маленьких фаз?