# Vibe Coding: гайд для инженеров и команд > Системный подход к vibe coding для профессиональных разработчиков: архитектура, rules-driven development, enforcement, командная работа. Не для новичков. > Author: Roman Belov · Published: 2026-06-27 · Source: https://futurecraft.pro/ru/blog/vibe-coding-guide/ Андрей Карпати [придумал термин](https://x.com/karpathy/status/1886192184808149383) в феврале 2025: «I just see things, say things, run things, and copy paste things, and it mostly works». Через месяц vibe coding стал мемом. Через полгода — подходом, который меняет профессиональную разработку. Проблема в том, как его понимают. Большинство статей описывают vibe coding как «опишите на словах — AI напишет код». Создаётся впечатление, что речь про автокомплит на стероидах. Для новичков — может быть. Для инженеров — нет. Vibe coding для инженера — AI пишет рутинную реализацию, архитектурные решения остаются за человеком, качество проверяют автоматические хуки. «AI пишет код по твоим правилам, и эти правила — код». Здесь — конкретные подходы, инструменты и паттерны. Для тех, кто пишет код профессионально и хочет встроить AI в свой процесс — без магии и маркетинга. ## Что такое Vibe Coding (и что это НЕ) ### Определение для инженеров Vibe coding — подход к разработке, где инженер фокусируется на намерении и архитектуре, а AI генерирует реализацию. Ключевое слово — «инженер». Не «пользователь». Не «промптер». Три компонента, которые делают vibe coding инженерным подходом: 1. **Контекст проекта** закодирован в файлах (CLAUDE.md, .cursorrules), а не в голове разработчика 2. **Правила качества** — автоматические, не устные: hooks, linters, тесты 3. **AI работает в ограничениях**: архитектура, паттерны, зависимости определены заранее Без этих трёх компонентов vibe coding — просто промптинг. С ними — инженерный процесс с AI-ускорением. ### Что это НЕ **Не автокомплит.** Copilot дописывает строку. Vibe coding — когда AI реализует целый модуль, следуя правилам проекта. **Не «я не программист, но...».** Статьи про «создай приложение без навыков кодирования» — про другое. Vibe coding для инженеров предполагает, что ты понимаешь код, который генерирует AI. Ты — архитектор, AI — подрядчик. **Не замена code review.** AI-генерированный код требует ревью — часто более тщательного, чем человеческий. AI уверенно пишет код, который компилируется и проходит тесты, но нарушает инварианты системы. **Не серебряная пуля.** Vibe coding ускоряет реализацию — не проектирование, не отладку сложных распределённых систем, не понимание предметной области. ### Почему инженеры скептичны — и когда меняют мнение Скептицизм обоснован. Первый опыт обычно выглядит так: попросил AI написать функцию, получил что-то работающее, потратил час на доводку. Экономия — минус тридцать минут. Перелом происходит, когда инженер переходит от разовых запросов к системе: - Первый раз настроил CLAUDE.md — и Claude перестал предлагать паттерны, которые в проекте не используются - Первый раз pre-commit hook отловил AI-генерированный код без тестов — и стало понятно, зачем enforcement - Первый раз закоммитил rules-файл в репозиторий — и коллега получил тот же контекст без устных объяснений Система работает. Отдельные промпты — не всегда. ## Эволюция: от хаоса к системе Vibe coding прошёл четыре этапа. Большинство команд застряли на первом-втором. ### Этап 1: Хаотичный промптинг «Напиши мне функцию сортировки», «Сделай React-компонент формы», «Исправь этот баг». Каждый запрос — с нуля. Контекста нет. Результат непредсказуем. Характеристики: - Каждый промпт — изолированный - Результат зависит от формулировки - Нет повторяемости: один и тот же запрос даёт разный код - Инженер тратит больше времени на промпт, чем на написание кода вручную Это не vibe coding. Это чат с AI. ### Этап 2: Prompt engineering System prompts. Few-shot examples. Chain-of-thought. Инженер формализует способ общения с AI. ``` You are a senior TypeScript developer. Follow functional programming patterns. Use zod for validation. Return Result instead of throwing. ``` Характеристики: - Промпты структурированы и переиспользуемы - Качество растёт за счёт контекста в промпте - Но промпт живёт в голове разработчика или в личных заметках - Нет версионирования, нет синхронизации в команде Лучше, чем хаос. Но промпт на 500 токенов не передаёт контекст проекта на 100 000 строк. ### Этап 3: Context engineering Контекст проекта кодируется в файлы. CLAUDE.md, .cursorrules, .windsurfrules — эти файлы загружаются в каждую сессию AI и дают модели полный контекст: стек, архитектуру, конвенции, запреты. ```markdown # CLAUDE.md ## Stack - TypeScript 5.4, strict mode - React 19 + TanStack Router - Drizzle ORM + PostgreSQL - Vitest for testing ## Conventions - No default exports - Zod schemas co-located with API routes - Error handling: Result, never throw in business logic - File naming: kebab-case ``` Характеристики: - Контекст версионируется в git - Каждый член команды работает с AI в одном контексте - AI «знает» проект: стек, конвенции, архитектуру - Результат стабильнее, но всё ещё не гарантирован Это уже vibe coding. Но без гарантий. ### Этап 4: Enforcement Правила принудительно исполняются, а не просто описаны. Pre-commit hooks блокируют коммит, если код не проходит проверки. CI/CD отклоняет PR с нарушениями. AI не может обойти quality gates. ```yaml # .husky/pre-commit npx lint-staged # lint-staged.config.js export default { '*.{ts,tsx}': [ 'eslint --fix --max-warnings 0', 'prettier --write', () => 'tsc --noEmit', 'vitest related --run', ], }; ``` Характеристики: - Качество гарантируется автоматически, не зависит от дисциплины - AI генерирует любой код — плохой не пройдёт - Цикл: AI генерирует → hook отклоняет → AI исправляет → hook принимает - Инженер верифицирует результат, а не качество каждой строки Это зрелый vibe coding. AI пишет. Система проверяет. Инженер контролирует. ### Vibe Shift: почему 2025–2026 — переломный момент Три фактора совпали: 1. **Модели стали достаточно хорошими.** Claude Opus 4.8, GPT-5.5, Gemini 3.5 Flash генерируют код, который проходит тесты с первой-второй попытки. Ещё два года назад требовалось 5–10 итераций. 2. **Инструменты созрели.** Claude Code (CLI + desktop app + Agent SDK), Cursor 3.5, Devin Desktop, OpenAI Codex — не прототипы, а production-ready платформы с поддержкой rules, agents, hooks и cloud delegation. 3. **Enforcement стал нормой.** Pre-commit hooks, CI/CD с AI-проверками, automated testing — инфраструктура для контроля AI-кода существует и работает. Переход от «AI как помощник» к «AI как подрядчик под контролем» — это и есть vibe shift. ## Архитектура системного Vibe Coding Системный vibe coding опирается на три компонента. В [Vibe Framework](https://github.com/CheatB/vibe-framework) их называют «три столпа» — удобная модель для понимания. ### Мозг: контекст и правила Мозг — это всё, что AI знает о проекте до начала работы. **Файлы контекста:** - `CLAUDE.md` — для Claude Code. Загружается автоматически при каждом запуске - `.cursor/rules/*.mdc` — для Cursor (актуальный формат с 2025; legacy `.cursorrules` поддерживается, но игнорируется в Agent mode) - `.windsurfrules` — для Devin Desktop (ex-Windsurf) - `copilot-instructions.md` — для GitHub Copilot **Что включать:** ```markdown # Project Context ## Commands npm run dev # Dev server npm run test # Run tests npm run build # Production build ## Architecture - Monorepo: Turborepo - API: tRPC + Drizzle - Frontend: React 19 + TanStack Router + TanStack Query - Database: PostgreSQL 16 ## Conventions - Named exports only - Barrel files: src/features/*/index.ts - Tests: co-located (*.test.ts next to source) - Errors: never throw in business logic, use Result - SQL: raw queries through Drizzle, no query builder for complex joins ## Do NOT - Add dependencies without explicit approval - Use default exports - Put business logic in API route handlers - Use any/unknown without explicit reason in comment ``` **Чего НЕ включать:** - Очевидное (как писать функции в TypeScript) - Временные решения (TODO, хаки, «потом переделаем») - Избыточный контекст (каждый токен снижает внимание модели ко всему остальному) Оптимальный размер CLAUDE.md — 100–300 строк. Больше — модель теряет фокус. Меньше — недостаточно контекста. ### Руки: инструменты и агенты Руки — это то, через что AI взаимодействует с проектом. **Инструменты (Tools):** - Чтение/запись файлов - Выполнение shell-команд - Поиск по кодовой базе (grep, glob) - Git-операции - MCP серверы (внешние интеграции: GitHub, БД, мониторинг) **Агенты:** - Субагенты в Claude Code — изолированные AI-потоки с отдельным контекстом - Agents Window в Cursor 3 — параллельные агенты локально и в облаке - Devin Local в Devin Desktop — многоступенчатые операции (Cascade deprecated с июля 2026) **Skills (Claude Code):** - Переиспользуемые команды: `/commit`, `/review`, `/test` - Определяются как markdown-файлы - Включают конкретный промпт и набор разрешённых действий Пример skill-файла: ```markdown # /review Review the current git diff for: 1. Logic errors 2. Missing error handling 3. Deviation from project conventions (see CLAUDE.md) 4. Missing tests for new functions Output: list of issues with file:line references. Do NOT auto-fix — only report. ``` ### Совесть: enforcement и quality gates Совесть — самый важный компонент. Без неё мозг и руки генерируют правдоподобный, но не гарантированно качественный код. **Pre-commit hooks:** - Lint (eslint/biome) — стиль и потенциальные ошибки - Format (prettier/biome) — единообразное форматирование - Type-check (tsc --noEmit) — типобезопасность - Test (vitest related) — тесты для изменённых файлов **CI/CD:** - Полный прогон тестов - Проверка покрытия (coverage threshold) - Security audit (npm audit, snyk) - Bundle size check **Дополнительные проверки:** - Архитектурные правила (eslint-plugin-boundaries — запрет импортов между слоями) - Dependency check (не добавлять зависимости без разрешения) - Commit message format (conventional commits) **Агентная изоляция (2026-норма):** - Каждый агент работает в отдельном worktree/branch — изменения не пересекаются до явного merge - Permission modes: allow-deny список инструментов, network controls для агентов с внешними запросами - MCP governance: allowlist серверов, OAuth scopes, запрет опасных tools на уровне конфига - Agent logs как артефакт PR: что читал, что менял, какие команды запускал, какие тесты прошли **AI-review gate (рекомендуемая практика):** - Автоматический AI-ревью каждого PR до код-ревью человеком: Bugbot (Cursor), Codex Security (OpenAI) - Prompt-injection gate: проверка issues, PR-комментариев, doc-страниц и MCP-outputs на инъекции - AI-код проходит те же SAST-проверки, что и человеческий (snyk, semgrep, bandit) Почему совесть важнее всего: AI уверенно генерирует код, который выглядит правильным. Без автоматических проверок такой код попадёт в main. С ними — не попадёт, пока не пройдёт все gates. AI исправляет свои ошибки быстро — если получает конкретный feedback от линтера или теста. Цикл работает так: ``` AI генерирует код → pre-commit hook запускает lint → lint находит unused import → AI убирает import → hook запускает тесты → тест падает (забыл edge case) → AI добавляет обработку → все проверки проходят → коммит создан ``` При использовании агентного режима (Claude Code, Cursor Composer) этот цикл может происходить без ручного вмешательства — агент сам исправляет ошибки по выводу хука. В интерактивном режиме инженер видит результат каждого шага и принимает решение о коммите. ## Фазы проекта с AI AI меняет и реализацию, и порядок работы. Линейный waterfall и хаотичный agile одинаково плохо сочетаются с AI. Эффективный процесс — фазовый. ### Фаза 1: Спецификация До генерации кода — спецификация. AI работает лучше с чётким описанием, чем с расплывчатым «сделай хорошо». ```markdown ## Feature: Rate Limiter Middleware ### Behavior - Limit requests per IP: 100/minute for API, 20/minute for auth endpoints - Return 429 with Retry-After header when exceeded - Use sliding window algorithm - Store counters in Redis (ioredis client from existing infra) ### Interface ```typescript type RateLimiterConfig = { windowMs: number; maxRequests: number; keyGenerator: (req: Request) => string; }; function createRateLimiter(config: RateLimiterConfig): Middleware; ``` ### Constraints - No new dependencies (use existing ioredis) - Must handle Redis connection failure gracefully (allow requests, log warning) - Tests: unit (mock Redis) + integration (real Redis via testcontainers) ``` Спецификация — это контракт между инженером и AI. Чем точнее контракт, тем меньше итераций. ### Фаза 2: Design System и токены Для фронтенда — design tokens до реализации. AI с токенами генерирует консистентный UI. AI без токенов хардкодит значения. ```typescript // tokens.ts export const spacing = { xs: '0.25rem', // 4px sm: '0.5rem', // 8px md: '1rem', // 16px lg: '1.5rem', // 24px xl: '2rem', // 32px } as const; export const colors = { primary: 'hsl(222, 47%, 11%)', accent: 'hsl(43, 74%, 54%)', surface: { base: 'hsl(0, 0%, 4%)', raised: 'hsl(0, 0%, 7%)', overlay: 'hsl(0, 0%, 10%)', }, } as const; ``` В rules-файле: ```markdown ## Design System - Use tokens from src/tokens.ts — NEVER hardcode colors, spacing, font sizes - Components must accept className prop for composition - No inline styles except dynamic values (e.g., width from props) ``` ### Фаза 3: Декомпозиция Большая задача → эпики → фичи → задачи. Каждая задача — атомарная: один промпт, один коммит, одна проверяемая единица. ``` Epic: User Authentication ├── Feature: Email/password registration │ ├── Task: Registration form component │ ├── Task: API route POST /auth/register │ ├── Task: Email verification flow │ └── Task: Tests for registration ├── Feature: Login flow │ ├── Task: Login form component │ ├── Task: API route POST /auth/login │ ├── Task: Session management │ └── Task: Tests for login └── Feature: Password reset ├── Task: Reset request form + API ├── Task: Reset confirmation + token validation └── Task: Tests for reset flow ``` Wave-based параллелизм: задачи без зависимостей выполняются параллельно. Субагент на registration form, субагент на API route. Оба работают с одним CLAUDE.md. ### Фаза 4: Реализация Каждая фича проходит цикл: brainstorm → build → test → commit. **Brainstorm:** обсуди подход с AI до генерации кода. Какие edge cases? Какие трейдоффы? Какие существующие утилиты переиспользовать? **Build:** AI генерирует код. Не правь вручную на этом этапе — дай AI закончить. **Test:** AI генерирует тесты. Ревьюй тесты до запуска — тесты это спецификация. Если тесты не покрывают edge case, попроси добавить до реализации. **Commit:** Автоматический: pre-commit hooks, conventional commit message. ### Фаза 5: Верификация AI генерирует тесты — инженер верифицирует. Не наоборот. Что проверять в AI-тестах: - Тесты проверяют поведение, а не реализацию? (мокают ли внутренние функции — плохо) - Покрыты ли edge cases? (null, empty, concurrent, timeout) - Нет ли тавтологий? (тест, который повторяет реализацию вместо проверки) - Assertions достаточно конкретные? (`toEqual` vs `toBeTruthy`) ## Инструменты для профессионального Vibe Coding ### Claude Code Флагманский агент Anthropic. Доступен как CLI (терминал), desktop app и IDE-плагин; один аккаунт, единый контекст. **Desktop app (с апреля 2026):** переработан под параллельные сессии. Боковая панель управления несколькими агентами, drag-and-drop layout, встроенный терминал и редактор файлов, быстрый diff-viewer. Parity с CLI: plugins, MCP, skills работают одинаково в обоих режимах. **Routines (cloud automations):** сохранённые задачи, которые выполняются в облаке Anthropic — без необходимости держать ноутбук включённым. Триггеры: расписание, событие в GitHub, Slack и т. д. **Rules:** CLAUDE.md в корне проекта. Иерархия: `~/.claude/CLAUDE.md` (глобальные) → проектный `CLAUDE.md` → `.claude/` директория с дополнительными правилами. **Agents:** Субагенты — markdown-файлы в `.claude/agents/`. Каждый агент — специализированный AI с изолированным контекстом. Параллельные агенты запускаются в отдельных worktree/branches. **Skills:** Переиспользуемые команды в `.claude/commands/`. Вызываются через `/skill-name`. **Hooks:** Pre/post-tool hooks на каждый lifecycle-шаг агента. Пример: после каждого `git commit` автоматически запускать тесты; перед `Bash` — логировать команду. **Agent SDK (Python/TypeScript):** тот же agent loop, что внутри Claude Code — tools, context, hooks, subagents, MCP, permissions — как библиотека для собственных пайплайнов. **Non-interactive / headless:** `claude -p`, JSON-output, stream JSON, schema output, `--max-turns`. Используется в CI/CD и автоматизациях без интерактивного ввода. **MCP:** Model Context Protocol — интеграция с внешними сервисами. GitHub, Notion, базы данных, мониторинг — через стандартный протокол. ```json // .mcp.json { "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"], "env": { "DATABASE_URL": "postgresql://..." } } } } ``` ### Cursor IDE на базе VS Code. Версия 3.5 (май 2026) — полноценная агентная платформа с cloud и marketplace. **Rules:** `.cursor/rules/*.mdc` — отдельные `.mdc`-файлы в директории `.cursor/rules/`. Поддерживают YAML-frontmatter с режимами активации (always/auto-attach/agent-requested/manual). Legacy-файл `.cursorrules` в корне проекта также читается, но игнорируется в Agent mode. **Composer:** Агентный режим. Создаёт/редактирует несколько файлов за один запрос. **Agents Window:** Параллельный запуск агентов локально, в worktrees, в облаке (изолированные cloud VMs с терминалом и браузером) и на remote SSH. Агенты создают PR и работают асинхронно. **Cloud Agents (v3.5):** агенты в облачных VM с полным доступом к терминалу, браузеру и нескольким репозиториям параллельно. Результаты приходят обратно в IDE. **Bugbot:** AI-ревью в каждом PR. Находит баги и потенциальные проблемы автоматически (~90 сек средний цикл). Входит в командный план. **Customize page:** единая страница управления plugins, skills, MCP, subagents, rules, commands и hooks — на уровне пользователя, команды или workspace. Team marketplace для совместного использования конфигураций. **Models:** Поддерживает Claude, GPT, Gemini. Можно переключать между задачами. ### Devin Desktop (ex-Windsurf) С 2 июня 2026 Windsurf переименован в Devin Desktop: Cognition встроила IDE в свою агентную экосистему через стандартный over-the-air update. Все настройки Windsurf мигрировали автоматически. **Agent Command Center (Spaces):** Kanban-интерфейс для управления локальными и облачными агентами из одного места. Запуск нескольких задач параллельно — штатный режим. **Devin Local:** новый локальный агент, заменивший Cascade (end-of-life 1 июля 2026). До 30% выше token efficiency, поддержка subagents — параллельная обработка задач, которой в Cascade не было. **Memories:** Персистентный контекст между сессиями сохранился. **SWE-1.6:** собственная модель Cognition для кодирования (выпущена апрель 2026). Работает поверх базовых моделей; входит в paid-планы бесплатно. Меньше overthinking, больше parallel tool calls. ### OpenAI Codex Агентная платформа OpenAI для кодирования. Единый бренд для CLI, desktop app и облачных задач. **Codex CLI:** локальный агент, запускается в терминале. Читает, редактирует и запускает код. Open-source, Rust. Прямая альтернатива Claude Code CLI. **Codex App (Mac + Windows):** desktop-приложение для координации нескольких параллельных агентов. Управление worktrees, automations, Git. Windows-версия вышла в мае 2026. **Codex Cloud / Web tasks:** фоновые агентные задачи в облачном окружении OpenAI. Делегирование без занятой локальной машины. **Codex Security:** AI-анализ безопасности кода. Локальный плагин и облачный scan с repo-specific threat model, validation evidence и suggested fixes. **Модели:** работает на GPT-5.5 — первой полностью переобученной базовой модели с agentic-first training (выпущена апрель 2026). **Позиционирование:** если Claude Code — terminal-first Unix-инструмент, то Codex — full-stack OpenAI-агентная платформа со встроенным security-слоем. ### Сравнение подходов | Аспект | Claude Code | Cursor | Devin Desktop | OpenAI Codex | |---|---|---|---|---| | Интерфейс | CLI + Desktop | IDE (VS Code fork) | IDE (VS Code fork) | CLI + Desktop + Cloud | | Rules-файлы | CLAUDE.md, .claude/ | .cursor/rules/*.mdc | .windsurfrules | — (context via CLI flags) | | Агенты | Субагенты + Routines | Cloud Agents + Agents Window | Devin Local + облачные агенты | Parallel threads + Cloud tasks | | MCP-поддержка | Полная | Частичная | Частичная | Ограниченная | | CI/CD интеграция | Нативная (CLI, GitHub Actions) | Через терминал | Через терминал | GitHub bot, webhooks | | Hooks | Pre/post-tool (lifecycle) | Нет | Нет | Нет | | Skills/Commands | Да (.claude/commands/) | Нет (сниппеты) | Нет | Нет | | Headless-режим | Да (Agent SDK, non-interactive) | Нет | Нет | Частично (API) | | Security gate | Нет (внешние инструменты) | Bugbot (PR-level) | Нет | Codex Security | | Стоимость | $20–200/мес или API | $20/мес (Pro) | $20/мес (Pro) | $20/мес или API | | Лучше всего для | CLI-ориентированные, backend, DevOps | Фронтенд, IDE-работа, команды | Multi-agent command center | OpenAI-стек, security-фокус | ### Общие инструменты Независимо от IDE/CLI: - **Pre-commit hooks:** husky + lint-staged (JS/TS), pre-commit (Python), lefthook (универсальный) - **Linters:** eslint, biome (JS/TS); ruff (Python); clippy (Rust) - **Formatters:** prettier, biome (JS/TS); black, ruff (Python); rustfmt (Rust) - **Type checking:** tsc --noEmit (TS); mypy, pyright (Python) - **Testing:** vitest (JS/TS); pytest (Python); cargo test (Rust) - **CI/CD:** GitHub Actions, GitLab CI — запуск всех проверок при push/PR ## Vibe Coding в команде Индивидуальный vibe coding — навык. Командный — процесс. Разница принципиальная. ### Shared rules Rules-файлы коммитятся в репозиторий. Каждый член команды — и каждый AI-ассистент — работает в одном контексте. ``` repo/ ├── CLAUDE.md # Claude Code users ├── .cursor/rules/ # Cursor users (.mdc-файлы с frontmatter) ├── .windsurfrules # Devin Desktop users (формат сохранился после ребрендинга) ├── .eslintrc.js # Enforcement (all) ├── .husky/pre-commit # Enforcement (all) └── vitest.config.ts # Testing (all) ``` Правило: если что-то важно для AI — это важно и для человека. Rules-файлы заменяют устные договорённости. Новый разработчик открывает CLAUDE.md и понимает конвенции, не читая 50 страниц Confluence. ### Code review AI-кода AI-генерированный код требует специфического ревью. Чеклист: **Архитектура:** - [ ] Следует ли код установленным паттернам проекта? - [ ] Нет ли новых абстракций там, где хватило бы существующих? - [ ] Правильный ли слой (AI любит смешивать UI и бизнес-логику)? **Зависимости:** - [ ] Не добавлены ли новые зависимости без обсуждения? - [ ] Не дублируют ли утилиты существующие (AI часто пишет хелпер, не зная что такой есть)? **Edge cases:** - [ ] Обработка ошибок реальная, а не catch-all? - [ ] Нет ли race conditions в async-коде? - [ ] Валидация входных данных на месте? **Тесты:** - [ ] Тесты проверяют поведение, не реализацию? - [ ] Есть ли негативные тесты (что должно НЕ работать)? **«Запах» AI-кода:** - [ ] Нет ли избыточных комментариев, объясняющих очевидное? - [ ] Нет ли over-engineering (3 абстракции для одного use case)? - [ ] Нет ли заглушек с `// TODO: implement`? ### Onboarding: новый разработчик + AI Шаги для нового члена команды: 1. **Прочитать CLAUDE.md** — это одновременно документация и конфигурация AI 2. **Запустить `npm test` и `npm run lint`** — убедиться, что enforcement работает 3. **Сделать первую задачу с AI** — с ментором, который покажет workflow 4. **Добавить правило** — если AI сделал что-то, что пришлось поправить, добавить правило в rules-файл Правило: каждый баг от AI → новое правило в CLAUDE.md. Файл растёт органически из реальных проблем, не из теоретических best practices. ### Метрики Что измерять для оценки эффекта vibe coding: | Метрика | Как измерить | На что обращать внимание | |---|---|---| | **Velocity** | Story points/неделя, PRs merged | Рост в первый месяц, стабилизация потом | | **Time-to-merge** | Время от создания PR до мержа | Должно уменьшаться (код чище благодаря hooks) | | **Defect rate** | Баги на 1000 строк | Следить чтобы не росло (AI-код может быть хрупким) | | **Test coverage** | % покрытия | AI хорошо генерирует тесты — coverage растёт | | **Rule additions** | Правила/неделя в CLAUDE.md | Активный рост = команда учится работать с AI | | **AI cost** | $/разработчик/месяц | Средняя норма: $100–250/мес при ежедневном использовании | | **Human intervention rate** | Ручные правки в AI-PR / всего AI-PR | Снижение = rules-файл работает | | **Rework rate** | Ревертнутые AI-PR / всего AI-PR | Рост = недостаточный enforcement или spec | | **Cost per merged PR** | AI-расходы / PRs merged | Эффективность агентного workflow | | **Security findings (AI-код)** | SAST hits confirmed в AI-PR | Должно стремиться к нулю с хорошими rules | ### Anti-patterns в командах **«У каждого свой промпт».** Разработчики используют личные system prompts вместо shared rules. Итог: несогласованный код, разные паттерны в одном проекте. Решение: rules-файл в репозитории, личные настройки — только расширяют, не переопределяют. **«AI всё сделает».** Команда перестаёт делать дизайн и архитектурные решения, полагаясь на AI. AI генерирует «что-то работающее» без системного мышления. Итог: архитектурный хаос за 2 месяца. **«Не трогай — работает».** AI-генерированный код не рефакторят, потому что «он же работает». Технический долг копится незаметно. **«Один инструмент на всех».** Принудительный переход всей команды на один AI-инструмент. Кто-то продуктивнее в CLI, кто-то в IDE. Важны shared rules, а не shared tool. ## Rules-Driven Development Rules-driven development (RDD) — подход, при котором поведение AI управляется декларативными правилами, а не ad-hoc промптами. ### Правила вместо советов Совет: «Пожалуйста, используй named exports». Правило: `NEVER use default exports. Named exports only. This is enforced by eslint rule import/no-default-export.` Разница: - Совет AI может проигнорировать (особенно при длинном контексте) - Правило формулируется императивно и подкрепляется enforcement - Правило включает «почему» — AI лучше следует правилам, когда понимает причину ### Структура правила Каждое правило содержит три элемента: ```markdown ## Error Handling **WHAT:** Use Result pattern for business logic errors. Never throw. **WHY:** Thrown exceptions bypass TypeScript type system. Callers don't know a function can fail until runtime. **WHEN:** All functions in src/domain/ and src/services/. API route handlers can throw — framework catches them. ``` ### Примеры rules-файлов **Backend (Node.js/TypeScript):** ```markdown ## API Routes - Route handlers in src/routes/ — thin, only validation + delegation - Business logic in src/services/ — never import from routes - Database queries in src/repositories/ — never import from services directly, use interfaces ## Error Handling - Domain errors: src/errors.ts, extend AppError base class - Services return Result, never throw - Route handlers: try/catch at top level, map AppError to HTTP status ## Database - Migrations in src/db/migrations/ — generated by drizzle-kit - Never modify database schema without migration - All queries use parameterized statements (drizzle handles this, but verify in raw SQL) ## Testing - Unit tests: *.test.ts next to source file - Integration tests: src/__tests__/integration/ - Mock external services, never mock internal modules - Test file structure: describe(module) > describe(function) > it(behavior) ``` **Frontend (React/TypeScript):** ```markdown ## Components - Feature components: src/features/{name}/components/ - Shared components: src/components/shared/ - No prop drilling beyond 2 levels — use context or composition - Every component that accepts children must type them as React.ReactNode ## State Management - Server state: TanStack Query (no Redux for API data) - Local UI state: useState/useReducer - Global UI state (theme, sidebar): Zustand store in src/stores/ ## Styling - Tailwind CSS — no CSS files, no CSS-in-JS - Use tokens from tailwind.config.ts (colors, spacing, breakpoints) - No arbitrary values in Tailwind classes ([32px]) — add to config if needed - Responsive: mobile-first (sm: md: lg:) ## Forms - React Hook Form + Zod - Schema in src/schemas/ — shared between frontend validation and API - Error messages in src/i18n/ — never hardcode strings ``` ### Enforcement через hooks Правила в CLAUDE.md — soft enforcement. Hooks — hard enforcement. Комбинация: ```javascript // lint-staged.config.js export default { '*.{ts,tsx}': [ // Стиль и паттерны 'eslint --fix --max-warnings 0', 'prettier --write', // Типобезопасность () => 'tsc --noEmit', // Тесты для изменённых файлов 'vitest related --run', ], }; ``` ESLint-правила, которые особенно полезны при vibe coding: ```javascript // eslint.config.js (flat config) export default [ { rules: { 'import/no-default-export': 'error', 'no-console': ['error', { allow: ['warn', 'error'] }], '@typescript-eslint/no-explicit-any': 'error', '@typescript-eslint/no-unused-vars': 'error', 'no-restricted-imports': ['error', { patterns: [{ group: ['../../../*'], message: 'Avoid deep relative imports. Use path aliases.', }], }], }, }, ]; ``` AI генерирует код с `any`? ESLint блокирует. AI добавляет `console.log` для дебага? ESLint блокирует. AI делает deep relative import? ESLint блокирует. AI исправляет — автоматически. ### Маркеры в коде для AI Маркеры — комментарии в коде, которые дают AI дополнительный контекст: ```typescript // AI:CONTEXT — This module handles rate limiting. // See ADR-007 for why we use sliding window instead of fixed. // AI:INVARIANT — maxRequests must never exceed 1000 per window. // This is a hard business rule, not a technical limitation. // AI:CAREFUL — This function is called from 15+ places. // Changing its signature requires updating all callers. // AI:NO-MODIFY — Generated by protobuf. Do not edit manually. ``` Маркеры — не комментарии для людей. Это метаданные для AI. Они помогают модели понять, что трогать нельзя, что важно, и где искать контекст. ## Типовые сценарии Три собирательных сценария показывают, как системный vibe coding выглядит в разных масштабах. Это гипотетические иллюстрации, а не измеренные кейсы — цифры ориентировочные. ### Solo: MVP за пару недель **Контекст:** solo-разработчик собирает SaaS для мониторинга API endpoints. Stack: Next.js 15, Drizzle ORM, PostgreSQL. **Подход:** - CLAUDE.md на 150–200 строк (стек, конвенции, DB-схема, API-контракты) - Pre-commit: eslint + prettier + tsc + vitest - Claude Code для реализации. Каждая фича — отдельный промпт с чёткой спецификацией **Ожидаемый результат (ориентировочно):** - Working MVP за 2–3 недели - Несколько десятков API endpoints с высоким test coverage - Главный источник багов в проде — то, что AI не учитывает сам: concurrent requests, race conditions, нетривиальные edge cases **Ключевой урок:** спецификация каждой фичи занимает 20–30 минут, реализация AI — 5–15 минут. Спецификация дороже кода — и это нормально. ### Команда 5 человек: рефакторинг legacy **Контекст:** Express.js монолит на ~80 000 строк, без типов, test coverage около 10%. Цель: миграция на TypeScript + разделение на модули. **Подход:** - Shared CLAUDE.md с правилами миграции: как конвертировать routes, как типизировать, какие паттерны использовать - Каждый разработчик берёт модуль, конвертирует с AI - Pre-commit hooks: strict TypeScript (no-any), eslint, тесты - Weekly rules review: обновление CLAUDE.md на основе найденных проблем **Ожидаемая динамика за квартал (ориентировочно):** | Показатель | До | После | |---|---|---| | TypeScript coverage | 0% | 70–80% | | Test coverage | ~10% | 50–65% | | Баги в проде | базовый уровень | заметно ниже — за счёт типов и тестов | | Время деплоя | десятки минут | минуты | | CLAUDE.md | стартовые ~50 строк | 300+ строк | **Ключевой урок:** CLAUDE.md вырастает со стартовых ~50 строк до 300+ за квартал. Каждое правило — результат реальной проблемы. К третьему месяцу AI делает меньше ошибок: rules-файл покрывает типичные паттерны проекта. ### Enterprise: AI в существующий процесс **Контекст:** Финтех, 40 разработчиков, строгий compliance. Нельзя «просто начать использовать AI». **Подход (6 месяцев):** Месяц 1–2: пилот на 5 разработчиках, некритичный внутренний инструмент. Цель — доказать безопасность и эффективность. Месяц 3–4: расширение до 15 человек. Shared rules. Обязательный security review для AI-кода. Метрики. Месяц 5–6: 30+ разработчиков. AI-код проходит те же проверки, что и человеческий. Дополнительно: SAST-сканер на AI-генерированные PR. **Ожидаемый результат (ориентировочно):** - Velocity: рост на десятки процентов, если мерить PRs merged / sprint - Defect rate: без роста — enforcement удерживает качество - Security-инциденты от AI-кода: близко к нулю при SAST + manual review - Adoption: большинство разработчиков переходит на ежедневную работу с AI **Ключевой урок:** Enterprise-внедрение — это не техническая проблема. Это управление изменениями. Rules + enforcement + метрики = аргументы для менеджмента. ## Проблемы и ограничения Проблемы у vibe coding есть. Знать их важнее, чем знать преимущества. ### AI-генерированный technical debt AI оптимизирует на «работает прямо сейчас», а не на «легко поддерживать через год». Типичные проблемы: - **Copy-paste вместо абстракции.** AI копирует паттерн 5 раз вместо создания переиспользуемой функции. Каждое копирование работает. Поддерживать 5 копий — нет. - **Over-engineering.** Обратная сторона: AI создаёт абстракцию ради одного use case. Factory для объекта, который создаётся в одном месте. - **Inconsistent patterns.** В понедельник AI использовал один подход для error handling, в пятницу — другой. Оба работают. Кодовая база — зоопарк. Mitigation: rules-файл + architectural linting (eslint-plugin-boundaries) + регулярный рефакторинг. ### «Works but why?» AI генерирует код, который проходит тесты. Разработчик мержит. Через месяц — баг. Разработчик открывает код и не понимает, как он работает. Потому что никто не ревьюил реализацию, только результат. Правило: если не можешь объяснить каждую строку — не мержи. AI-код требует того же уровня понимания, что и код коллеги. ### Over-reliance: потеря навыков Реальный риск, особенно для junior и mid-level инженеров. Если AI всегда пишет реализацию, разработчик перестаёт думать на уровне кода. Mitigation: - Регулярные code katas без AI - Архитектурные ревью — человек объясняет решения, а не AI - Ротация: периоды «без AI» для критических модулей ### Security concerns AI генерирует код с уязвимостями: - SQL injection (если не используется ORM/параметризация) - Hardcoded secrets (AI «выдумывает» credentials) - Insecure defaults (отключённая валидация, CORS *) - Dependency confusion (несуществующие пакеты в import) Mitigation: SAST в CI/CD, `npm audit` в pre-commit, security-ориентированные правила в rules-файле, ручной security review для auth/payment/data modules. ### Управление стоимостью AI-инструменты стоят денег: модели тарифицируют по токенам, большой контекст бьёт по бюджету. Практика: мониторинг расходов через дашборд провайдера. Средний бюджет — $100–250 на разработчика в месяц при активном использовании. Экономия на context engineering: меньше токенов в контексте = меньше стоимость запроса. ## Как начать ### Минимальный набор (день 1) 1. **Rules-файл.** Создай CLAUDE.md (или `.cursorrules` / `.cursor/rules/*.mdc` для Cursor) с базовой информацией: стек, команды сборки, 5–10 ключевых правил проекта. ```markdown # CLAUDE.md ## Commands npm run dev / npm test / npm run build ## Stack TypeScript, React, Drizzle, PostgreSQL ## Rules - Named exports only - Tests next to source files (*.test.ts) - No console.log in committed code - Error handling: Result, never throw in services - All API inputs validated with Zod ``` 2. **Pre-commit hooks.** Настрой за 10 минут: ```bash npx husky init npm install -D lint-staged # .husky/pre-commit npx lint-staged ``` 3. **Тесты.** Убедись, что тестовый фреймворк настроен и один базовый тест проходит. AI будет генерировать тесты — инфраструктура должна быть готова. ### Прогрессивное усложнение (недели 2–8) **Неделя 2:** Расширь rules-файл. После каждой сессии с AI, где пришлось исправлять — добавь правило. **Неделя 3:** Добавь eslint-правила, специфичные для проекта. `import/no-default-export`, `no-restricted-imports`, architectural boundaries. **Неделя 4:** Попробуй субагентов (Claude Code) или Agents Window (Cursor) для задач, затрагивающих несколько файлов. **Неделя 5–6:** Настрой CI/CD с полным прогоном тестов, coverage check, lint. Автоматизируй то, что раньше проверял вручную. **Неделя 7–8:** Skills/commands для повторяющихся операций: `/review`, `/test`, `/refactor`. MCP-серверы для интеграций (GitHub, database). ### Чеклист для команды - [ ] Rules-файл (CLAUDE.md / .cursorrules) в репозитории - [ ] Pre-commit hooks: lint + format + type-check - [ ] Тестовая инфраструктура: фреймворк настроен, базовые тесты проходят - [ ] Code review процесс обновлён: чеклист для AI-кода - [ ] Onboarding-документ: как работать с AI в проекте - [ ] Метрики: velocity, defect rate, AI cost — базовые значения зафиксированы - [ ] Rules review: еженедельное обновление rules-файла на основе опыта - [ ] Security: SAST в CI/CD, правила в rules-файле для auth/data модулей - [ ] Бюджет: лимиты расходов на AI-инструменты установлены и мониторятся --- Vibe coding — эволюция инженерного процесса, а не революция. Модели достаточно хороши. Инструменты созрели. Enforcement-инфраструктура существует. Осталось интегрировать. Инженеры, которые воспринимают AI как подрядчика с чёткими правилами, получают ускорение. Те, кто ждут от AI магии или бросают контроль, получают технический долг. CLAUDE.md. Pre-commit hooks. Тесты. Начните с этого. Остальное приложится.