---
name: engineering-principles
description: >
  Pragmatic coding principles: SOLID, KISS, DRY, YAGNI in balance.
  Use when writing code, refactoring, reviewing, or designing architecture.
  Prevents over-engineering while maintaining code quality.
  Триггеры: "напиши код", "рефактори", "code review", "архитектура",
  "engineering principles", "SOLID", "KISS", "DRY", "YAGNI",
  "design this", "how to structure", "разбей на модули", "спроектируй архитектуру",
  "создай проект", "структура проекта", "объясни архитектуру"
---

# Engineering Principles — Pragmatic Balance

## Priority (when in conflict)

1. **Работает** → решает задачу пользователя
2. **Просто (KISS)** → простейшее рабочее решение, можно понять и поддерживать
3. **Не усложняй заранее (YAGNI)** → сначала работающий простой код, не усложнять заранее
4. **Убери настоящий дубль (DRY)** → только когда реально нужно (3+ места), настоящая одинаковая логика
5. **SOLID** → когда система уже растёт; маленький скрипт ≠ нужна абстракция

## Что даёт каждый принцип (цель, не догма)

| Принцип | Зачем | Стоп-сигнал |
|---------|-------|-------------|
| **SRP** — одна ответственность | Меняешь одно → не ломает другое | Функция > 40 строк или 3+ причин менять → раздели |
| **OCP** — расширяй, не меняй | Новая фича → старое работает | Не создавай абстракции "на будущее" (см. YAGNI) |
| **LSP** — замена без сюрпризов | Подставил реализацию → работает | `instanceof`, `if type` → плохой дизайн, переделай |
| **ISP** — минимум зависимостей | Не тяни лишнее | Интерфейс > 5 методов → разбей |
| **DIP** — завись от абстракций | Меняешь деталь → бизнес-логика не знает | Не абстрагируй то что не будет меняться |
| **KISS** — простота | Код понятен с первого чтения | if/else на 3 ветки ≠ нужна фабрика |
| **DRY** — без дублирования | Баг в одном месте → починил везде | Похожий код, разная логика → НЕ трогай |
| **YAGNI** — фокус | Не тратишь время на ненужное | "Конфиг на будущее", "generic для всего" → стоп |

## Product-first Checks

Перед финальной реализацией спроси:

1. Какую **видимую пользователю** проблему это решает?
2. Как пользователь поймёт что это сработало?
3. Что сломается если входные данные, сеть, зависимость или данные — плохие?
4. Можно ли это наблюдать, тестировать, откатить, объяснить?
5. Это простейший код который оставляет будущие изменения продукта дешёвыми?

## Product Engineering Priorities

1. **Correct user outcome** — правильный результат для пользователя
2. **Clear surfaced behavior** — ясные API/UI/контракты/ошибки
3. **Safe changeability** — безопасно менять
4. **Operational visibility** — можно наблюдать и дебажить
5. **Code elegance** — красота кода (последний приоритет)

## Before writing code — 3 вопроса

1. Какую задачу пользователя это решает?
2. Есть ли проще способ?
3. Что если это изменится — легко ли переделать?

## Complexity gates

- Cyclomatic complexity ≤ 15 (функции > 20 → рефактори или обоснуй в PR)
- Вложенность > 3 уровней → early return / guard clauses
- Файл > 400 строк → раздели если логически делится

## ✅/❌ Quick Reference

### KISS
✅ Простая коллекция вместо сложной структуры
✅ Одна функция 40 строк понятнее чем 3 по 15
❌ Фабрика + стратегия + декоратор для if/else на 3 ветки

### DRY
✅ Одинаковая бизнес-логика в 3 местах → вынеси
❌ Две функции с 2 общими строками → не объединяй
❌ Совпадение структуры ≠ дублирование (accidental duplication)

### YAGNI
❌ "Интерфейс пригодится когда будет вторая реализация"
❌ "Generic решение для всех возможных случаев"
❌ "Конфиг на будущее"
✅ Делаешь под задачу → рефакторишь когда задачи меняются

### SOLID
✅ SRP: одна причина менять → один класс/функция
❌ SRP: 10 классов для 10 строк кода → over-engineering
✅ DIP: бизнес-логика не знает про базу данных
❌ DIP: абстракция над каждым console.log
✅ OCP: новый тип через композицию, не правка существующего
❌ OCP: 5 уровней наследования "на всякий случай"

## Practical Guidelines

### Когда применять SOLID
- Код > 100 строк в одном файле
- Уже есть 2+ места где используется
- Команда > 1 человека или долгоживущий проект
- Частые изменения в одной области

### Когда остановиться (KISS wins)
- Скрипт < 50 строк
- Одноразовая утилита
- Прототип / spike
- if/else на 2-3 ветки
- Нет признаков что будет расти

### DRY — прагматичный подход
- **True duplication**: одинаковая логика, одинаковая причина менять → выноси
- **Accidental similarity**: похожая структура, разная причина менять → НЕ трогай
- **Rule of 3**: нашёл в 3 местах → время вынести

### YAGNI — красные флаги over-engineering
- "Потом пригодится"
- "На случай если..."
- "Может быть вторая реализация"
- "Generic для всех случаев"
- Абстракция без конкретного второго пользователя

## What this gives

| Principle | Real benefit |
|-----------|-------------|
| KISS | Readability — understand code on first read |
| YAGNI | Focus — spend time on what's needed now, no over-engineering |
| DRY | Consistency — fix bugs once, everywhere fixed (when truly duplicated) |
| SRP | Stability — change one thing without breaking another |
| OCP | Safe extensions — new features don't break old code |
| LSP | Predictability — swap implementations without surprises |
| ISP | Minimal deps — depend only on what you use |
| DIP | Modularity — swap infrastructure freely |

---

## Project Structure Standards

### Стандартная структура (адаптируй под стек)

```
project/
├── src/              # Бизнес-логика, компоненты, сервисы
│   ├── modules/      # Функциональные модули (SRP: один модуль = одна зона)
│   ├── shared/       # Переиспользуемые утилиты (общие helpers, types)
│   └── index         # Entry point
├── config/           # Конфигурации (дефолтные, примеры, env templates)
├── scripts/          # Утилиты: билд, деплой, миграции, генераторы
├── tests/            # Тесты: unit, integration, e2e
├── docs/             # Доки: API, архитектура, runbooks
└── .env.example      # Шаблон переменных окружения
```

### Зоны ответственности папок

| Папка | Что внутри | Что НЕ внутри |
|-------|-----------|---------------|
| `src/` | Бизнес-логика, компоненты, API handlers | Конфиги, скрипты деплоя, тесты |
| `config/` | Дефолтные конфиги, .env.example, templates | Секреты, хардкод значений |
| `scripts/` | Автоматизация, CLI-утилиты, генераторы | Бизнес-логика приложения |
| `tests/` | Unit, integration, e2e, fixtures, mocks | Production код |
| `docs/` | README, API specs, architecture decisions | Устаревшие доки без даты |

### SRP на уровне файлов
- Файл > 400 строк → раздели если логически делится
- Один класс/функция/модуль = одна причина менять
- Entry point (`index.ts`, `main.py`) = только wiring, без логики

---

## Architecture Explanation Guide

**После проектирования — объясни:**

### 1. Ключевые решения
- **Что решил** → **почему так** → **какие альтернативы отверг**
- Формат: `Решение: X. Причина: Y. Альтернатива Z отвергнута потому что W.`

### 2. Последовательность компонентов
- Что за чем идёт и почему
- Формат: `A → B → C` с пояснением зачем каждый шаг
- Пример: `CLI (парсинг args) → Config (валидация) → Service (логика) → Output (результат)`

### 3. Зона ответственности каждого компонента
- Каждый модуль/файл: что делает, что НЕ делает
- Формат: `Компонент X: делает Y. Не делает Z. Зависит от W.`

### 4. Потоки данных
- Откуда данные приходят, куда уходят, где трансформируются
- Формат: `Input → [Transform] → Output`
- Укажи контракты: типы данных, форматы, ошибки

### 5. Связи и зависимости
- Кто кого вызывает, кто от кого зависит
- Стрелки зависимостей: `модуль A → модуль B` (A зависит от B)
- Покажи где DIP/абстракции, где прямые зависимости

### Правило: кратко, без воды
- Связь → Причина → Следствие
- Не "этот компонент очень важен" → "Config валидирует env → сервис падает рано с понятной ошибкой"

---

## Pre-implementation Checklist

**Перед написанием кода — пройдись по чеклисту:**

### 1. План (Todos ≤ 10 пунктов)
- [ ] Составь todo-лист ≤ 10 конкретных действий
- [ ] Каждый пункт — действие, не абстракция ("создать src/config/parser.ts" не "настроить парсинг")
- [ ] Порядок: от фундамента к фичам

### 2. Проектирование
- [ ] Структура папок определена
- [ ] Зоны ответственности разделены (SRP)
- [ ] Контракты между модулями понятны
- [ ] Entry point определён

### 3. Объяснение
- [ ] Ключевые архитектурные решения зафиксированы
- [ ] Последовательность компонентов описана
- [ ] Потоки данных понятны

### 4. Complexity gates
- [ ] Cyclomatic complexity ≤ 15
- [ ] Вложенность ≤ 3 уровней (guard clauses)
- [ ] Файл ≤ 400 строк (разделить если больше)

---

## Syntax & Smoke Test Checklist

**После написания — проверь:**

### Проверка синтаксиса (по стеку)
| Язык | Команда |
|------|---------|
| JavaScript/Node.js | `node -c file.js` |
| TypeScript | `npx tsc --noEmit` |
| Python | `python -m py_compile file.py` |
| Bash | `bash -n script.sh` |
| Go | `go build ./...` |
| Rust | `cargo check` |

### Базовая работоспособность
- [ ] Запускается без краша (если есть entry point — запусти)
- [ ] Smoke test: основной сценарий работает
- [ ] Конфиги валидны (если есть config loader — проверь загрузку)
- [ ] Ошибки понятны (если падает — сообщение говорит что не так)

---

## Configuration Standards

### Обязательные конфиги
- [ ] `.env.example` — шаблон всех переменных с комментариями
- [ ] Дефолтный конфиг с безопасными значениями (fail-safe defaults)
- [ ] Пример config файла с пояснениями каждого поля

### Правила
- **Никогда не коммить реальные секреты** — токены, ключи, пароли
- `.env.example` показывает структуру, не значения
- Дефолты = безопасные (localhost, пустые строки, тестовые значения)
- Документируй откуда брать значения (ссылки на API, сервисы)

### Формат .env.example
```bash
# API ключ (получить на https://example.com/api-keys)
API_KEY=your-api-key-here

# URL базы данных (format: postgresql://user:pass@host:port/db)
DATABASE_URL=postgresql://localhost:5432/mydb

# Порт приложения (default: 3000)
PORT=3000

# Лог уровень: debug, info, warn, error (default: info)
LOG_LEVEL=info
```

---

## Implementation Workflow

**Полный цикл создания проекта/фичи:**

1. **Прочитай этот скилл** — загрузи engineering-principles
2. **Составь Todos ≤ 10** — конкретные действия, порядок
3. **Спроектируй структуру** — папки, модули, контракты
4. **Объясни архитектуру** — решения, последовательность, потоки
5. **Реализуй** — код, конфиги, скрипты, примеры
6. **Проверь синтаксис** — по языку (см. таблицу выше)
7. **Smoke test** — запусти, убедись работает
8. **Зафиксируй** — README, примеры использования