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

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

Глава 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: Саморазвитие

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

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

Reactive — агенты реагируют на события (pre-commit, push)
- Audit правил, авто-форматирование, проверка тестов
Proactive — агенты предлагают улучшения
- Анализ кода, предложение рефакторинга, оптимизация БД
Autonomous — агенты принимают решения
- Self-healing, auto-scaling, auto-versioning

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

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

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

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

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

6.6 KiB Raw Permalink Blame History Unescape Escape