# Принципы работы

Философия, на которой построен этот шаблон. Если вы разработчик — прочитайте это перед тем как писать код.

---

## Глава 1: Правила важнее кода

Код можно переписать. Архитектуру можно изменить. Но культура проекта — это то, что остаётся после любой переделки.

**Что это значит на практике:**
- Прежде чем писать код, узнай правила (`docs/00-rules.md`)
- Если не знаешь как сделать — найди похожий пример в проекте и делай так же
- Если сомневаешься — **спроси**. Лучше задать 10 вопросов, чем переписывать неделю

**Пример из жизни:** В одном проекте разработчик решил "упростить" и не писал docstrings к публичным методам. Через 3 месяца новый разработчик не мог понять что делает половина сервисов. Пришлось переписывать всё с нуля. Правило "docstrings обязательны" появилось после этого.

---

## Глава 2: Слоистая архитектура как образ мысли

Проект разделён на слои. Зависимости могут идти **только внутрь**:
```
API → Services → Integrations → Data → Core
```

**Что это значит:**
- **API** не знает про БД. Он только принимает запрос и отдаёт ответ.
- **Service** не знает про HTTP. Он реализует бизнес-логику.
- **Integration** не знает про бизнес-логику. Он только вызывает внешний API.
- **Data** не знает про внешний мир. Это модели и запросы к БД.
- **Core** — фундамент. Не зависит ни от чего.

**Почему так:**
- Можно заменить HTTP на gRPC, не трогая сервисы
- Можно заменить PostgreSQL на SQLite, не трогая API
- Можно тестировать каждый слой изолированно

---

## Глава 3: Агенты — это co-developer, а не опция

**Главный урок этого шаблона:** агенты должны жить в проекте с первого коммита.

**4 ядерных агента, которые создаются первыми:**

| Агент | Что делает | Без него |
|-------|-----------|----------|
| **DocAgent** | Пишет документацию параллельно с кодом | Документация пишется "потом" → никогда |
| **AuditAgent** | Проверяет каждый коммит на правила | Правила есть в файле, но не применяются |
| **EvolutionAgent** | Версионирует агентов, управляет развитием | Версии хаотичны, эволюция невозможна |
| **SupervisorAgent** | Следит за всеми агентами, их здоровьем | Экосистема агентов не контролируется |

**Остальные агенты подключаются по мере необходимости:**
- QATesterAgent — когда появились тесты
- FixAgent — когда пойман первый баг
- BacklogAgent — когда появился техдолг
- SecurityAgent — перед production
- SpecAgent — перед релизом
- RolloutAgent — перед деплоем
- ObserverAgent — после запуска
- UITestAgent — когда есть UI

Каждый агент появляется когда в нём возникает реальная потребность, но ядро — с первого дня.

---

## Глава 4: Документация — это код

**Если это не записано — этого не существует.**

- **ADR** фиксируют архитектурные решения. Через год никто не вспомнит "почему мы выбрали PostgreSQL".
- **CHANGELOG** — это контракт с пользователем. Каждое изменение должно быть задокументировано.
- **Decision Log** — лёгкий трекер для каждодневных решений. "Почему мы отложили OAuth".
- **Документация пишется параллельно с кодом**, а не после.

---

## Глава 5: Тестирование — не этап, а процесс

**Код без тестов — это не код, а предложение.**

- Каждый endpoint имеет минимум 1 smoke-тест
- Каждый сервис покрыт unit-тестами
- Каждый баг превращается в тест (чтобы не повторился)
- Покрытие > 80% — обязательно

---

## Глава 6: Саморазвитие

Проект должен становиться умнее без участия человека.

**Три уровня саморазвития:**

1. **Reactive** — агенты реагируют на события (pre-commit, push)
   - Audit правил, авто-форматирование, проверка тестов

2. **Proactive** — агенты предлагают улучшения
   - Анализ кода, предложение рефакторинга, оптимизация БД

3. **Autonomous** — агенты принимают решения
   - Self-healing, auto-scaling, auto-versioning

К концу Stage 3 (cм. `docs/migration-path.md`) проект должен достичь Level 2.

---

## Глава 7: Будущее

Шаблон растёт вместе с проектами. Если вы нашли ситуацию, которую шаблон не описывает:

1. Запишите её в `notes/encountered-issues.md`
2. Если есть идея улучшения — добавьте в `notes/improvements.md` с пометкой `[ASK]`
3. Обновите соответствующий `docs/` файл

**Шаблон должен стать умнее после каждого проекта.**