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

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

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

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

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

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

```markdown
# Миссия

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

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

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

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

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

## Успех

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Фаза 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

Запрос:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Коммит

```bash
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. Почему дорожная карта должна состоять из маленьких фаз?