118 lines
6.6 KiB
Markdown
118 lines
6.6 KiB
Markdown
# Принципы работы
|
||
|
||
Философия, на которой построен этот шаблон. Если вы разработчик — прочитайте это перед тем как писать код.
|
||
|
||
---
|
||
|
||
## Глава 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/` файл
|
||
|
||
**Шаблон должен стать умнее после каждого проекта.**
|