Initial commit: VoIdeaAI - voice-first AI idea assistant

2026-05-13 12:51:42 +03:00
commit 688d043dad
421 changed files with 47915 additions and 0 deletions
@@ -0,0 +1,117 @@
+# Принципы работы
+
+Философия, на которой построен этот шаблон. Если вы разработчик — прочитайте это перед тем как писать код.
+
+---
+
+## Глава 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/` файл
+
+**Шаблон должен стать умнее после каждого проекта.**