# Spec-Guided Development (Skaro)

## Методология AI-assisted разработки

> **Философия:** Разработчик — архитектор и контролёр. LLM — мощный инструмент, но не автопилот.
> Спецификация живёт в репозитории рядом с кодом. Контекст не теряется между сессиями.

---

## Содержание

- [1. Принципы](#1-принципы)
- [2. Роли: человек vs LLM](#2-роли-человек-vs-llm)
- [3. Файловая структура проекта](#3-файловая-структура-проекта)
- [4. Фазы разработки](#4-фазы-разработки)
  - [Фаза 0. Constitution — принципы проекта](#фаза-0-constitution--принципы-проекта)
  - [Фаза 1. Architecture — архитектура](#фаза-1-architecture--архитектура)
  - [Фаза 2. Clarify — уточнение](#фаза-2-clarify--уточнение)
  - [Фаза 3. Plan — план работ](#фаза-3-plan--план-работ)
  - [Фаза 4. Implement — реализация](#фаза-4-implement--реализация)
  - [Фаза 5. Review — кросс-валидация](#фаза-5-review--кросс-валидация)
  - [Фаза 6. Docs — документация](#фаза-6-docs--документация)
  - [Фаза 7. Ops — DevOps и Security](#фаза-7-ops--devops-и-security)
- [5. Шаблоны файлов](#5-шаблоны-файлов)
- [6. Промпты для каждой фазы](#6-промпты-для-каждой-фазы)
- [7. Чеклисты](#7-чеклисты)
- [8. Адаптация: solo vs команда](#8-адаптация-solo-vs-команда)
- [9. Анти-паттерны](#9-анти-паттерны)
- [10. Масштабирование по размеру задачи](#10-масштабирование-по-размеру-задачи)

---

## 1. Принципы

### Проблема

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

- **Дублирование логики** — модель локально оптимизирует ответ и «изобретает» второй вариант того же решения.
- **Разъезд стиля и подходов** — как будто один файл писали разные люди без договорённостей.
- **Заглушки вместо реализации** — модель оставляет TODO без предупреждения.
- **Дорогая отладка** — больше времени уходит на распутывание несогласованностей, чем на саму разработку.
- **Потеря контекста** — в длинных чатах модель «забывает» ранние решения, и приходится повторять одно и то же.
- **Невоспроизводимость** — если контекст живёт только в истории чатов, другой разработчик (или вы через месяц) не сможет подхватить проект.

### Решение: Spec-Guided Development

Skaro — это методология, которая решает эти проблемы через три ключевых механизма:

1. **Файловые артефакты в репозитории** — весь контекст проекта (принципы, архитектура, спецификации, планы, отчёты) хранится в `.skaro/` и версионируется через Git. LLM получает контекст из файлов, а не из истории чата.

2. **Фазовый процесс с контрольными точками** — разработка проходит через последовательные фазы (архитектура → уточнение → план → реализация → валидация), и каждая фаза имеет определённые входы, выходы и Definition of Done.

3. **Чёткое разделение ролей** — разработчик принимает решения, LLM помогает их исследовать и реализовать. Не наоборот.

### Ключевые принципы Skaro

1. **Человек — архитектор, LLM — усилитель.** Архитектурные решения принимает разработчик. LLM ревьюирует, находит слепые зоны, предлагает альтернативы, генерирует код — но не принимает решений.

2. **Спецификация живёт в репозитории.** Все артефакты (constitution, архитектура, планы, отчёты по этапам) — это файлы в Git. Не чаты, не скриншоты, не «помнишь, мы обсуждали».

3. **Контекст через файлы, не через историю чата.** При каждом новом обращении к LLM передаются нужные файлы из `.skaro/`. Чат может быть пустым — контекст уже в проекте.

4. **Масштабирование формальности.** Баг-фикс не требует 7 фаз. Новая фича — требует. Методология адаптируется под размер задачи (см. [раздел 10](#10-масштабирование-по-размеру-задачи)).

5. **Проверяемые артефакты на каждом этапе.** Каждая фаза заканчивается конкретным файлом с Definition of Done. Если DoD не выполнен — фаза не завершена.

6. **Никаких заглушек без явного решения.** Если LLM оставляет TODO/заглушку, это должно быть задокументировано и обосновано, а не скрыто.

7. **Агенто-независимость.** Методология не привязана к конкретному LLM или инструменту. Работает с любым AI-ассистентом: Claude, ChatGPT, Copilot, Cursor, Gemini — что угодно. Артефакты одинаковы для всех.

---

## 2. Роли: человек vs LLM

| Действие | Человек | LLM |
|---|---|---|
| Принятие архитектурных решений | ✅ Решает | Предлагает варианты, ищет риски |
| Написание constitution | ✅ Пишет | Может предложить шаблон |
| Ревью архитектуры | Валидирует результат | ✅ Проводит ревью по чеклисту |
| Декомпозиция на этапы | Валидирует и корректирует | ✅ Предлагает разбивку |
| Написание кода | Ревьюирует и правит | ✅ Генерирует |
| Тесты | Ревьюирует покрытие | ✅ Пишет |
| Code review | ✅ Финальное решение | ✅ Первичный проход |
| Документация | Проверяет актуальность | ✅ Генерирует и сверяет с кодом |
| Security review | Принимает решения по рискам | ✅ Проходит по чеклисту |

---

## 3. Файловая структура проекта

```
project-root/
├── .skaro/                          # Все артефакты методологии
│   ├── constitution.md            # Неизменяемые принципы проекта
│   ├── architecture/
│   │   ├── adr-001-*.md           # Architecture Decision Records
│   │   ├── invariants.md          # Архитектурные инварианты
│   │   └── diagrams/              # Диаграммы (Mermaid / PlantUML)
│   ├── features/
│   │   └── <feature-name>/
│   │       ├── spec.md            # Спецификация фичи
│   │       ├── clarifications.md  # Уточнения (фаза Clarify)
│   │       ├── plan.md            # План реализации
│   │       ├── tasks.md           # Декомпозиция на задачи
│   │       └── stages/
│   │           ├── stage-01/
│   │           │   └── AI_NOTES.md
│   │           ├── stage-02/
│   │           │   └── AI_NOTES.md
│   │           └── ...
│   ├── docs/
│   │   └── review-log.md          # Лог кросс-валидаций
│   ├── ops/
│   │   ├── devops-notes.md
│   │   └── security-review.md
│   └── templates/                 # Шаблоны (см. раздел 5)
│       ├── constitution-template.md
│       ├── spec-template.md
│       ├── plan-template.md
│       ├── ai-notes-template.md
│       ├── adr-template.md
│       └── security-checklist.md
├── src/
├── tests/
└── ...
```

### Почему `.skaro/`

Папка `.skaro/` — сокращение от Spec-Guided Development. Можно переименовать под ваши предпочтения. Главное — артефакты лежат в репозитории, версионируются через Git и доступны любому участнику команды.

### Зачем хранить артефакты в репозитории, а не в чатах

- **Воспроизводимость.** Любой разработчик может подхватить проект, прочитав `.skaro/`.
- **Версионирование.** Видно, как эволюционировали решения: кто, когда и почему изменил инварианты или constitution.
- **Независимость от инструмента.** Переход с одного LLM на другой не теряет контекст — он в файлах.
- **Надёжность.** Чат может быть потерян, ограничен по длине, заархивирован. Файлы в Git — нет.

---

## 4. Фазы разработки

### Фаза 0. Constitution — принципы проекта

**Когда:** один раз при старте проекта, обновляется редко и осознанно.

**Кто делает:** разработчик пишет, LLM может помочь структурировать.

**Суть:** Constitution — это набор неизменяемых принципов, которым подчиняются все последующие фазы. Это не «рекомендации», а жёсткие правила. Каждый промпт к LLM должен ссылаться на constitution.

Constitution включает:
- Стек и версии (конкретные, не «последние»)
- Стандарты кодирования (или ссылка на lint-конфиг)
- Требования к тестированию (минимальное покрытие, обязательные уровни)
- Инфраструктурные ограничения
- Политики безопасности
- Правила работы с LLM (формат ответа, запрет заглушек, AI_NOTES)

**Входы:**
- Стек и версии
- Инфраструктурные ограничения
- Стандарты кодирования
- Требования к тестированию
- Политики безопасности

**Выход:** `.skaro/constitution.md`

**DoD:**
- [ ] Зафиксирован стек с конкретными версиями
- [ ] Описаны стандарты кодирования (или ссылка на lint-конфиг)
- [ ] Описаны минимальные требования к тестированию
- [ ] Описаны ограничения (инфра, бюджет, совместимость)
- [ ] Файл в Git, прошёл ревью (для команды)

---

### Фаза 1. Architecture — архитектура

**Когда:** при старте проекта и при значительных изменениях.

**Кто делает:** разработчик создаёт черновик архитектуры, LLM проводит ревью.

**Суть:** Вы приносите своё архитектурное решение — LLM ищет слабые места, предлагает альтернативы, формулирует инварианты. Но решение принимаете вы. LLM не проектирует архитектуру с нуля — он помогает вам найти слепые зоны в вашем решении.

**Входы:**
- `.skaro/constitution.md`
- Описание домена и ключевых сценариев
- Черновик архитектуры (ваш)

**Выходы:**
- `.skaro/architecture/invariants.md` — что нельзя сломать при реализации
- `.skaro/architecture/adr-NNN-*.md` — Architecture Decision Records (по одному на ключевое решение)
- `.skaro/architecture/diagrams/` — диаграммы компонентов, потоков данных

**Что такое инварианты:** это правила, которые должны соблюдаться всегда, независимо от фичи и этапа. Примеры:
- «Все мутации через Event Sourcing, прямая запись в read-модель запрещена»
- «Все внешние вызовы идемпотентны и имеют retry с exponential backoff»
- «Ни один эндпоинт не отвечает дольше 200ms на p95»

**DoD:**
- [ ] Есть карта компонентов с границами ответственности
- [ ] Описаны основные потоки данных
- [ ] Зафиксированы инварианты (идемпотентность, транзакционность, модель консистентности, ретраи)
- [ ] Каждое неочевидное решение оформлено как ADR
- [ ] LLM провела ревью и список рисков зафиксирован

---

### Фаза 2. Clarify — уточнение

**Когда:** перед планированием каждой фичи.

**Кто делает:** LLM задаёт вопросы, разработчик отвечает.

**Суть:** Прежде чем планировать реализацию, LLM систематически выявляет «дыры» в спецификации: неописанные edge-cases, неясные бизнес-правила, противоречия с constitution или инвариантами. Это критически важная фаза, которая экономит часы на этапе реализации.

Без этой фазы типичная проблема: вы пишете spec, передаёте его LLM для планирования, и на этапе реализации обнаруживаете, что LLM сделала десяток «скрытых допущений» — каждое из которых может быть неверным.

**Входы:**
- `.skaro/constitution.md`
- `.skaro/architecture/invariants.md`
- `.skaro/features/<feature>/spec.md` (черновик)

**Выход:** `.skaro/features/<feature>/clarifications.md`

**DoD:**
- [ ] LLM задала ≥ 5 вопросов по спецификации
- [ ] Все ответы зафиксированы в файле
- [ ] Спецификация обновлена с учётом уточнений
- [ ] Не осталось явных TODO/TBD в спецификации

---

### Фаза 3. Plan — план работ

**Когда:** после Clarify, перед реализацией каждой фичи.

**Кто делает:** LLM предлагает план, разработчик валидирует и корректирует.

**Суть:** LLM получает финальную спецификацию, инварианты и constitution, и предлагает декомпозицию на этапы. Разработчик проверяет: реалистичны ли оценки, не пропущены ли зависимости, не over-engineer'ит ли LLM простую задачу.

**Входы:**
- `.skaro/constitution.md`
- `.skaro/architecture/invariants.md`
- `.skaro/features/<feature>/spec.md` (финальная)
- `.skaro/features/<feature>/clarifications.md`

**Выходы:**
- `.skaro/features/<feature>/plan.md` — этапы с зависимостями
- `.skaro/features/<feature>/tasks.md` — декомпозиция на задачи

**DoD:**
- [ ] Каждый этап имеет: цель, входы/выходы, риски, DoD
- [ ] Зависимости между этапами явные
- [ ] Определены минимальные проверки (тесты, линтер, контракты)
- [ ] Нет этапов длиннее 1 рабочего дня (если длиннее — разбить)
- [ ] Разработчик проверил план на реалистичность

---

### Фаза 4. Implement — реализация

**Когда:** по этапам из плана, каждый этап — отдельная итерация.

**Кто делает:** LLM генерирует код, разработчик ревьюирует каждый этап.

**Суть:** На каждый этап LLM получает контекст из файлов (constitution + invariants + plan + текущее состояние кода), а не из истории чата. Это значит, что вы можете начать новый чат для каждого этапа — контекст не потеряется.

**Критически важно:** каждый этап проходит через ручное ревью разработчика перед коммитом. Никакого автоматического «реализуй всё». Разработчик читает каждую строку, проверяет соответствие инвариантам, ищет заглушки и скрытые допущения.

**Входы (на каждый этап):**
- `.skaro/constitution.md`
- `.skaro/architecture/invariants.md`
- `.skaro/features/<feature>/plan.md` — текущий этап
- Текущее состояние кода (релевантные файлы)

**Выходы (на каждый этап):**
- Код
- Тесты (unit + интеграционные, где уместно)
- `.skaro/features/<feature>/stages/stage-NN/AI_NOTES.md`

**DoD (каждый этап):**
- [ ] Проект собирается, тесты зелёные
- [ ] Нет заглушек без явного обоснования
- [ ] Публичные контракты (API/DTO/схемы) согласованы с архитектурой
- [ ] AI_NOTES.md заполнен: что/зачем/риски/как проверить
- [ ] Разработчик провёл ручное ревью кода
- [ ] Коммит в Git с осмысленным сообщением

---

### Фаза 5. Review — кросс-валидация

**Когда:** после завершения реализации фичи (все этапы пройдены).

**Кто делает:** LLM проводит, разработчик принимает решения.

**Суть:** LLM проверяет согласованность всех артефактов между собой: spec ↔ код, invariants ↔ реализация, constitution ↔ итоговый результат. Плюс полноценный code review. Это «финальная проверка», которая ловит расхождения, накопившиеся за несколько этапов реализации.

**Входы:**
- Все артефакты из `.skaro/`
- Финальный код фичи

**Выход:** `.skaro/docs/review-log.md` (дополняется по каждой фиче)

**DoD:**
- [ ] Нет расхождений между spec и кодом
- [ ] Инварианты не нарушены
- [ ] Constitution соблюдён
- [ ] Code review пройден (MUST FIX / SHOULD IMPROVE / NICE TO HAVE)
- [ ] Все MUST FIX исправлены

---

### Фаза 6. Docs — документация

**Когда:** после Review каждой значимой фичи.

**Кто делает:** LLM генерирует, разработчик сверяет с реальностью.

**Входы:**
- Код + тесты
- Все артефакты `.skaro/`

**Выход:** обновлённая проектная документация

**DoD:**
- [ ] Документация соответствует текущим контрактам
- [ ] Есть раздел «как запустить» и «как проверить»
- [ ] Ключевые решения зафиксированы (ADR)
- [ ] Нет устаревших примеров

---

### Фаза 7. Ops — DevOps и Security

**Когда:** периодически (при деплое, перед релизом, при изменении инфраструктуры).

**Кто делает:** LLM проходит по чеклистам, разработчик принимает решения.

**DevOps — входы:** требования к деплою, SLO/SLA, ограничения инфры
**DevOps — выход:** `.skaro/ops/devops-notes.md`

**Security — входы:** код, точки входа (API, интеграции, фоновые джобы)
**Security — выход:** `.skaro/ops/security-review.md`

**DoD (Security):**
- [ ] Пройден чеклист безопасности (см. [раздел 7](#чеклист-security-review))
- [ ] Все CRITICAL и HIGH риски имеют план устранения
- [ ] Секреты не хранятся в коде

---

## 5. Шаблоны файлов

### constitution-template.md

```markdown
# Constitution проекта: <название>

## Стек
- Язык: <язык> <версия>
- Фреймворк: <фреймворк> <версия>
- БД: <БД> <версия>
- Инфра: <Docker/K8s/облако>

## Стандарты кодирования
- Линтер: <название> с конфигом <путь>
- Форматтер: <название>
- Именование: <конвенции>
- Максимальная длина функции: <N строк>
- Максимальная вложенность: <N уровней>

## Тестирование
- Минимальное покрытие: <N%>
- Обязательно: unit-тесты на бизнес-логику
- Обязательно: интеграционные тесты на API-контракты
- Фреймворк: <название>

## Ограничения
- <инфраструктурные ограничения>
- <бюджетные ограничения>
- <совместимость>

## Безопасность
- Авторизация: <модель>
- Валидация входных данных: <подход>
- Секреты: <где хранятся>

## Правила работы с LLM
- Не оставлять заглушки без явного TODO с обоснованием
- Не дублировать код: предпочитать переиспользование
- Не делать скрытых допущений — если не уверен, спроси
- Всегда генерировать AI_NOTES.md по шаблону
- Соблюдать единый стиль, описанный выше
```

### spec-template.md

```markdown
# Спецификация: <название фичи>

## Контекст
Почему эта фича нужна, какую проблему решает.

## Пользовательские сценарии
1. **<Сценарий 1>:** <описание>
2. **<Сценарий 2>:** <описание>

## Функциональные требования
- FR-01: <требование>
- FR-02: <требование>

## Нефункциональные требования
- NFR-01: <производительность / доступность / масштабируемость>

## Границы (что НЕ входит)
- <явные исключения>

## Критерии приёмки
- [ ] <критерий 1>
- [ ] <критерий 2>

## Открытые вопросы
- <вопросы, требующие уточнения в фазе Clarify>
```

### ai-notes-template.md

```markdown
# AI_NOTES — Этап <N>: <название>

## Что сделано
- <список изменений>

## Почему так
- <обоснование ключевых решений>

## Созданные / изменённые файлы
| Файл | Действие | Описание |
|---|---|---|
| `path/to/file` | создан / изменён | что и зачем |

## Риски и ограничения
- <известные ограничения>
- <потенциальные проблемы>

## Соответствие инвариантам
- [ ] <инвариант 1> — соблюдён
- [ ] <инвариант 2> — соблюдён

## Как проверить
1. `<команда сборки>`
2. `<команда тестов>`
3. <ручные проверки>
```

### adr-template.md

```markdown
# ADR-<NNN>: <название решения>

**Статус:** proposed | accepted | deprecated | superseded by ADR-XXX
**Дата:** <YYYY-MM-DD>

## Контекст
Какая проблема или ситуация потребовала решения.

## Решение
Что решили делать и почему.

## Альтернативы
1. **<Альтернатива 1>:** <описание> — отклонена, потому что <причина>
2. **<Альтернатива 2>:** <описание> — отклонена, потому что <причина>

## Последствия
- Позитивные: <что улучшится>
- Негативные: <чем платим, какие trade-offs>
- Риски: <что может пойти не так>
```

---

## 6. Промпты для каждой фазы

### Фаза 0. Constitution

```
Помоги мне структурировать constitution проекта.
Вот вводные: <стек, ограничения, требования>.
Используй шаблон из .skaro/templates/constitution-template.md.
Задай уточняющие вопросы, если чего-то не хватает.
Не принимай решений за меня — предлагай варианты.
```

### Фаза 1. Architecture — ревью

```
Контекст:
- Constitution: [вставить или прикрепить .skaro/constitution.md]
- Описание домена: <...>

Вот моё архитектурное решение:
<вставить черновик>

Проведи ревью как архитектор:
1. Найди слабые места: масштабирование, консистентность, отказоустойчивость, наблюдаемость.
2. Проверь соответствие constitution.
3. Отметь спорные решения и предложи альтернативы с trade-offs.
4. Сформулируй список архитектурных инвариантов (что нельзя нарушить при реализации).
5. Предложи, какие ADR стоит зафиксировать.
6. Предложи минимальный набор диаграмм.

Формат ответа:
- Список рисков (CRITICAL / HIGH / MEDIUM / LOW)
- Список инвариантов
- Список рекомендуемых ADR
```

### Фаза 2. Clarify — уточнение

```
Контекст:
- Constitution: [прикрепить]
- Инварианты: [прикрепить .skaro/architecture/invariants.md]
- Спецификация фичи: [прикрепить .skaro/features/<feature>/spec.md]

Проведи структурированное уточнение спецификации:

1. Прочитай spec и constitution.
2. Найди все места, где:
   - неоднозначное поведение (что должно произойти если...?)
   - не описаны edge cases
   - возможны противоречия с инвариантами
   - нет критериев приёмки
   - неясны границы (что входит / не входит)
3. Задай мне вопросы по каждому найденному месту.
4. После моих ответов — обнови spec.md и создай clarifications.md.

Задавай вопросы по одному блоку за раз, не больше 5 вопросов.
```

### Фаза 3. Plan — план работ

```
Контекст:
- Constitution: [прикрепить]
- Инварианты: [прикрепить]
- Спецификация (финальная): [прикрепить]
- Уточнения: [прикрепить clarifications.md]

Составь план реализации:
1. Разбей на этапы (каждый ≤ 1 рабочий день).
2. Для каждого этапа укажи: цель, вход, выход, артефакты, риски, DoD.
3. Укажи зависимости между этапами.
4. Отметь, что можно делать параллельно.
5. Проверь: не нарушает ли план инварианты?
6. Проверь: соответствует ли план constitution?

Формат: создай plan.md и tasks.md по шаблонам.
Не добавляй этапов, которых нет в спецификации. Не over-engineer'ь.
```

### Фаза 4. Implement — реализация (на каждый этап)

```
Контекст:
- Constitution: [прикрепить]
- Инварианты: [прикрепить]
- План, текущий этап: <N> из plan.md [прикрепить релевантную часть]
- Текущий код: [прикрепить релевантные файлы]
- AI_NOTES предыдущего этапа: [прикрепить, если есть]

Реализуй этап <N>: <название>.

Требования:
- Выдай ТОЛЬКО файлы, которые создал/изменил.
- Напиши тесты (unit + интеграционные, где уместно).
- Создай AI_NOTES.md по шаблону.
- Не дублируй существующий код.
- Не оставляй заглушек.
- Если не уверен в решении — перечисли варианты, не делай скрытых допущений.
- Проверь соответствие инвариантам (отметь в AI_NOTES).
```

### Фаза 5. Review — кросс-валидация

```
Контекст:
- Constitution: [прикрепить]
- Инварианты: [прикрепить]
- Спецификация: [прикрепить]
- Весь код фичи: [прикрепить]

Проведи кросс-валидацию:

1. SPEC ↔ КОД: все ли требования из spec реализованы? Есть ли в коде то, чего нет в spec?
2. ИНВАРИАНТЫ ↔ КОД: не нарушены ли архитектурные инварианты?
3. CONSTITUTION ↔ КОД: соблюдены ли стандарты, тестирование, безопасность?

Затем проведи code review:
- корректность, edge cases, обработка ошибок
- стиль и единообразие
- дублирование
- тестируемость
- безопасность (инъекции, секреты, авторизация, валидация)
- производительность (N+1, лишние аллокации, блокировки)

Формат ответа:
- Расхождения spec ↔ код (список)
- Нарушения инвариантов (список)
- MUST FIX (блокируют мерж)
- SHOULD IMPROVE (желательно)
- NICE TO HAVE (при случае)
```

### Фаза 6. Docs

```
Контекст:
- Текущая документация: [прикрепить]
- Код + тесты: [прикрепить]
- Constitution: [прикрепить]

Сверь документацию с кодом:
1. Что устарело?
2. Где не хватает примеров?
3. Где расходятся контракты (документация говорит одно, код делает другое)?
4. Обнови документацию. Добавь раздел «как запустить» и «как проверить», если его нет.
```

### Фаза 7. Security review

```
Контекст:
- Constitution: [прикрепить]
- Код: [прикрепить]
- Точки входа: <API, интеграции, фоновые джобы>

Пройди по чеклисту безопасности (см. .skaro/templates/security-checklist.md):
- Для каждого пункта: статус (OK / RISK / N/A) + комментарий
- Приоритизируй риски: CRITICAL / HIGH / MEDIUM / LOW
- Предложи конкретные исправления для CRITICAL и HIGH
```

---

## 7. Чеклисты

### Чеклист: готовность фичи к реализации (Gate: Plan → Implement)

- [ ] Constitution актуален и описывает текущий стек
- [ ] Спецификация прошла фазу Clarify, нет открытых вопросов
- [ ] План разбит на этапы ≤ 1 дня каждый
- [ ] Зависимости между этапами явные
- [ ] Для каждого этапа есть DoD
- [ ] План не противоречит инвариантам
- [ ] Разработчик вручную проверил план

### Чеклист: готовность этапа (Gate: Implement → следующий этап)

- [ ] Код собирается без ошибок
- [ ] Все тесты зелёные
- [ ] Нет заглушек без обоснования
- [ ] AI_NOTES.md заполнен
- [ ] Публичные контракты согласованы с архитектурой
- [ ] Разработчик провёл ручное ревью
- [ ] Коммит с осмысленным сообщением

### Чеклист: кросс-валидация (Gate: Review → Docs)

- [ ] Все требования из spec реализованы
- [ ] В коде нет «лишнего» (не описанного в spec)
- [ ] Инварианты не нарушены
- [ ] Constitution соблюдён
- [ ] Все MUST FIX из code review исправлены

### Чеклист: Security review

- [ ] Входные данные валидируются на всех точках входа
- [ ] SQL-инъекции: используются параметризованные запросы
- [ ] XSS: выходные данные экранируются
- [ ] Авторизация: проверяется на каждом эндпоинте
- [ ] Аутентификация: токены/сессии имеют TTL
- [ ] Секреты: не хранятся в коде, используется vault/env
- [ ] Логирование: чувствительные данные не попадают в логи
- [ ] Rate limiting: настроен на публичных эндпоинтах
- [ ] CORS: настроен корректно
- [ ] Зависимости: нет известных CVE (проверка через `audit`)
- [ ] Ошибки: не раскрывают внутреннюю структуру в ответах API
- [ ] Файловые загрузки: валидация типа и размера

---

## 8. Адаптация: solo vs команда

### Solo-разработчик

- Constitution пишете сами, LLM помогает структурировать
- Фазы можно проходить быстрее (меньше формальности в описаниях)
- AI_NOTES.md всё равно нужны — это ваша «память» через неделю/месяц
- Git-ветки на фичи опциональны, но рекомендуются
- Кросс-валидация (фаза 5) — можно совмещать с code review

### Команда (2-5 человек)

- Constitution — общий документ, изменения через PR с ревью
- Каждая фаза завершается PR:
  - Фаза 1 (Architecture): PR с ADR и инвариантами → ревью тимлидом
  - Фаза 3 (Plan): PR с планом → ревью другим разработчиком
  - Фаза 4 (Implement): PR с кодом + AI_NOTES → стандартный code review
- Разные разработчики могут использовать разных AI-агентов — артефакты в `.skaro/` одинаковы для всех
- Security review (фаза 7) — ротация: каждый раз проводит другой член команды с помощью LLM
- Рекомендация: назначить «хранителя constitution» — человека, ответственного за согласованность принципов

### Таблица различий

| Аспект | Solo | Команда |
|---|---|---|
| Constitution | Пишете сами | PR + ревью |
| Architecture ревью | LLM ревьюирует | LLM + тимлид |
| Clarify | Вы отвечаете на вопросы LLM | Продакт/аналитик + вы |
| Plan | Вы валидируете | PR + ревью коллегой |
| Implement | Вы ревьюируете код LLM | Стандартный PR-процесс |
| Review | LLM + вы | LLM + другой разработчик |
| AI_NOTES.md | Для себя-в-будущем | Для всей команды |

---

## 9. Анти-паттерны

### ❌ «Один чат на всё»
**Проблема:** контекст размывается, LLM «забывает» архитектурные решения к середине реализации.
**Решение:** файлы в `.skaro/` — LLM получает нужный контекст явно, а не из истории чата.

### ❌ «LLM решает архитектуру»
**Проблема:** LLM оптимизирует локально и может предложить решение, несогласованное с остальным проектом.
**Решение:** вы — архитектор. LLM — ревьюер, который ищет слепые зоны.

### ❌ «Автоматическая реализация без ревью»
**Проблема:** автоматическая генерация всего кода одной командой создаёт код, который «работает», но не соответствует вашим стандартам, дублирует логику, содержит заглушки.
**Решение:** каждый этап проходит ручное ревью. Нет ревью — нет коммита.

### ❌ «Формальность ради формальности»
**Проблема:** баг-фикс в 3 строки проходит через 7 фаз с ADR и security review.
**Решение:** масштабирование формальности (см. раздел 10).

### ❌ «Constitution написан и забыт»
**Проблема:** стек обновился, подходы изменились, а constitution описывает реальность полугодовой давности.
**Решение:** ревью constitution при каждом значимом изменении стека. Добавьте напоминание в DoD фазы Architecture.

### ❌ «Слепое доверие code review от LLM»
**Проблема:** LLM может пропустить тонкие баги, race conditions, проблемы с производительностью.
**Решение:** LLM делает первичный проход, вы — финальный. LLM не заменяет ваше ревью, а экономит время на рутине.

### ❌ «Over-engineering спецификации»
**Проблема:** 20 страниц spec.md на CRUD-эндпоинт. Команда тратит больше времени на документы, чем на код.
**Решение:** spec должен быть пропорционален сложности задачи. Простая фича = короткий spec.

---

## 10. Масштабирование по размеру задачи

Не каждая задача требует всех 7 фаз. Вот матрица:

### 🟢 Мелкая задача (баг-фикс, мелкий рефакторинг, < 1 часа)

| Фаза | Нужна? |
|---|---|
| 0. Constitution | Уже есть |
| 1. Architecture | ❌ Пропускаем |
| 2. Clarify | ❌ Пропускаем |
| 3. Plan | ❌ Пропускаем |
| 4. Implement | ✅ Один этап, промпт с constitution + инвариантами |
| 5. Review | ✅ Быстрый — LLM code review + ваш взгляд |
| 6. Docs | ❌ Если не затронуты контракты |
| 7. Ops | ❌ Пропускаем |

**Промпт для мелкой задачи:**
```
Контекст:
- Constitution: [прикрепить]
- Инварианты: [прикрепить]
- Проблема: <описание бага / задачи рефакторинга>
- Файлы: [прикрепить релевантные]

Исправь проблему. Напиши тест, если его не было.
Создай короткий AI_NOTES.md (что/зачем/как проверить).
Не меняй ничего за пределами описанной проблемы.
```

### 🟡 Средняя задача (новый эндпоинт, модуль, 1-3 дня)

| Фаза | Нужна? |
|---|---|
| 0. Constitution | Уже есть |
| 1. Architecture | ⚠️ Только если затрагивает границы компонентов |
| 2. Clarify | ✅ Быстрый проход (3-5 вопросов) |
| 3. Plan | ✅ Упрощённый (1 файл, без tasks.md) |
| 4. Implement | ✅ 1-3 этапа |
| 5. Review | ✅ Полный |
| 6. Docs | ✅ Если новый API / контракт |
| 7. Ops | ❌ Обычно не нужна |

### 🔴 Крупная задача (новая фича, новый сервис, > 3 дней)

| Фаза | Нужна? |
|---|---|
| 0. Constitution | ✅ Проверить актуальность |
| 1. Architecture | ✅ Полная |
| 2. Clarify | ✅ Полная |
| 3. Plan | ✅ Полная (plan.md + tasks.md) |
| 4. Implement | ✅ Много этапов |
| 5. Review | ✅ Полная кросс-валидация |
| 6. Docs | ✅ Полная |
| 7. Ops | ✅ Если затрагивает деплой/инфру/безопасность |

---

## Быстрый старт

1. Создайте `.skaro/` в корне проекта.
2. Скопируйте шаблоны из раздела 5 в `.skaro/templates/`.
3. Заполните `.skaro/constitution.md`.
4. Для первой фичи: создайте `.skaro/features/<feature>/spec.md` по шаблону.
5. Пройдите фазы 2-7 последовательно, используя промпты из раздела 6.
6. Добавьте `.skaro/` в Git.

Всё. Никаких CLI, никаких зависимостей. Только файлы, Git и ваш LLM.

---

*Skaro v1.0 — Spec-Guided Development.*
