Skip to content

claude-code-guide.md

Latest commit

 

History

History
1530 lines (1125 loc) · 79.1 KB

claude-code-guide.md

File metadata and controls

1530 lines (1125 loc) · 79.1 KB

Claude Code — Гайд по фичам и воркфлоу

Собрано из официального CHANGELOG, публичных материалов сообщества и треда bcherny (март 2026). Версия Claude Code на момент сборки: 2.1.78

🏷️ Система приоритетов

Каждый раздел помечен флажком — насколько он важен при настройке Claude Code:

Флажок Уровень Смысл
🔴 Обязательно Настрой это в первую очередь. Без этого агент работает значительно хуже — ты теряешь качество на каждом промпте. Применимо к любому проекту и стеку.
🟡 По случаю Мощный инструмент, но нужен не всем. Внедряй когда проект дорос до определённого масштаба или задача совпадает с профилем фичи. Ниже указано, в каких именно ситуациях.
🟢 На любителя Удобная фича, но не влияет на качество кода. Кому-то экономит 5 минут в день, кому-то не нужна вовсе. Попробуй — реши сам.

Рекомендация: начни с 🔴-разделов, затем пройдись по 🟡 и отметь релевантные для своего проекта.

1. 🔴 Качество кода агентов

Never typecast (as)

Зачем: Одна строка в AGENTS.md которая улучшает качество кода больше, чем любой skill. Запрет as заставляет агента решать проблему типов правильно, а не замалчивать её.

Как внедрить:

Добавить в AGENTS.md:

## Code Standards
- Never typecast. Never use `as`

Для автоматического enforcement — плагин Biome:

https://github.com/albertodeago/biome-plugin-no-type-assertion

📌 Пример из жизни

Ситуация: Ты пишешь Next.js приложение с Prisma ORM. Агент получает данные из API и ему нужно привести unknown к типу User. Без запрета он напишет:

const user = data as User; // тихо сломается если API вернёт другую структуру

С запретом as агент вынужден написать runtime-валидацию:

const user = UserSchema.parse(data); // Zod — упадёт явно если структура не совпала

Результат: вместо скрытого бага в продакшене — ошибка на этапе разработки.

Кому нужно: всем TypeScript-проектам — от лендинга на Next.js до enterprise монолита. Чем больше кодовая база, тем критичнее. Для Python/Go/Rust проектов — формулируй аналогичные правила под свой стек (например, Never use # type: ignore для Python).

2. 🔴 Архитектура Skills (harness optimization)

Зачем: Строгая структура Skills даёт ~90% улучшение стабильности результатов. Посредственный агент внутри жёсткой системы ограничений работает лучше, чем мощный агент в плохо структурированном окружении. Это не prompt-инжиниринг — это системный дизайн.

Принцип: один Skill = одна функция. Результат = комбинация атомарных Skills.

Структура SKILL.md:

---
name: my-skill
description: Короткое описание для триггера
---

## Skill Purpose
Один абзац. Суть задачи. Только основная идея — детали идут ниже.

## Instructions
1. Точный шаг с точным путём
   Execute: ~/scripts/run.py
2. Следующий шаг
3. ...

> Правило: если шагов больше 3 — разбить на отдельные Skills.

## Non-Negotiable Acceptance Criteria
- [ ] Критерий 1 — агент не выдаёт результат пока не выполнен
- [ ] Критерий 2
- [ ] Критерий 3

> Используй именно "Non-Negotiable", не "Rules" — второе оставляет агенту пространство для интерпретации.

## Output
Точный формат ответа. Обязателен для стабильного chaining Skills.

Нестабильные результаты = слабый harness. Если агент ведёт себя непредсказуемо — проблема в структуре, не в модели.

📌 Пример из жизни

Ситуация: У тебя SaaS-продукт. Каждую неделю надо: создать миграцию БД → обновить API-эндпоинты → обновить фронтенд-типы → написать тесты. Без Skills агент каждый раз делает это немного по-разному — то забывает тесты, то пишет миграцию не в тот формат.

С Skills ты создаёшь:

.claude/skills/
├── db-migration.md      # Skill: создать миграцию в формате Prisma
├── api-endpoint.md      # Skill: CRUD эндпоинт по шаблону
├── generate-types.md    # Skill: обновить TypeScript типы из схемы
└── integration-test.md  # Skill: тест для нового эндпоинта

Каждый Skill имеет Non-Negotiable критерии:

## Non-Negotiable Acceptance Criteria
- [ ] Миграция включает rollback (down migration)
- [ ] Все поля имеют явные типы, нет `any` или `unknown`
- [ ] Запущен `prisma migrate dev` и миграция прошла без ошибок

Результат: повторяемый, предсказуемый pipeline. Каждый раз — одинаковое качество.

Кому нужно: всем, кто использует Claude Code регулярно (не разово). Особенно командам где несколько человек пользуются агентом — Skills стандартизируют подход. Проекты с повторяющимися паттернами (CRUD, миграции, генерация кода) получают максимальную выгоду.

3. 🟡 Параллельная работа: Git Worktrees

Зачем: Запускать десятки агентов в одном репозитории без конфликтов. Каждый агент получает свой изолированный worktree и работает независимо.

Как внедрить:

# Новая сессия в изолированном worktree
claude -w

# или
claude --worktree

В Desktop app — чекбокс "worktree" при создании сессии.

Для non-git VCS — хук WorktreeCreate для своей логики создания worktree.

Для агентов в .claude/agents/*.md:

---
isolation: worktree
---

Документация: https://git-scm.com/docs/git-worktree

📌 Пример из жизни

Ситуация: Ты lead в команде из 3 фронтенд-разработчиков. У вас React-приложение с 50+ компонентами. Нужно одновременно: рефакторить авторизацию, писать новую фичу корзины, и фиксить баги в каталоге. Без worktrees — три задачи в одном дереве файлов, конфликты неизбежны.

С worktrees:

# Терминал 1 — рефакторинг авторизации
claude -w
> "Рефакторни auth модуль, переведи с context на zustand"

# Терминал 2 — новая фича
claude -w
> "Создай модуль корзины с компонентами Cart, CartItem, CartSummary"

# Терминал 3 — багфикс
claude -w
> "Исправь баг с пагинацией в каталоге — items.length на странице 2 всегда 0"

Каждый агент работает в изолированной копии репо. Нет конфликтов. В конце — три PR на ревью.

Кому нужно:

  • Проекты с несколькими параллельными задачами (фичи + багфиксы + рефакторинг)
  • Команды где несколько человек пользуются Claude Code на одном репо
  • Монолиты с долгими PR-циклами
  • Ситуации когда хочешь попробовать два подхода к одной задаче и сравнить

Когда НЕ нужно: соло-разработка с одной задачей за раз.

4. 🟡 Массовые изменения: /batch

Зачем: Крупные code migrations и другие параллелизируемые задачи. /batch интервьюирует тебя, затем сам разбивает работу и запускает столько worktree-агентов, сколько нужно — десятки, сотни, тысячи.

Как внедрить:

/batch

Claude задаст уточняющие вопросы, сам определит декомпозицию, сам запустит агентов.

Используй для: миграций, рефакторингов, массовых переименований, обновлений зависимостей.

📌 Пример из жизни

Ситуация: Компания решила мигрировать с Material UI v4 на v5. 200+ компонентов, в каждом — изменение API импортов, замена makeStyles на styled, обновление пропсов. Вручную — неделя работы. Агент по одному файлу — всё равно долго.

/batch
> Claude: Какая задача?
> Ты: Мигрировать все компоненты с MUI v4 на MUI v5.
>       Заменить makeStyles на styled/sx, обновить импорты с @material-ui на @mui.
> Claude: Нашёл 217 файлов. Разбиваю на 43 группы по модулям. Запускаю агентов...

Claude сам:

  1. Находит все затронутые файлы
  2. Группирует по логическим модулям (чтобы связанные файлы менялись вместе)
  3. Запускает параллельных агентов (каждый в своём worktree)
  4. Собирает результаты

Результат: 200+ файлов мигрированы за 20 минут вместо недели.

Кому нужно:

  • Крупные миграции фреймворков/библиотек (React Router v5→v6, Vue 2→3, Angular upgrade)
  • Массовые рефакторинги (переименование entity во всём коде, смена паттерна)
  • Обновление API-контрактов когда меняется 50+ файлов
  • Монорепозитории с десятками пакетов

Когда НЕ нужно: точечные изменения в 1-5 файлах — обычная сессия справится быстрее.

5. 🟡 Автоматизация: /loop и /schedule

Зачем: Превратить Claude Code из инструмента в фоновый процесс. Агент работает сам по расписанию пока ты занимаешься другим.

Как внедрить:

# Базовый синтаксис
/loop <интервал> <команда>

# Примеры из практики bcherny:
/loop 5m /babysit          # auto code review + rebase + shepherd PRs
/loop 30m /slack-feedback  # PR за фидбэком из Slack каждые 30 мин
/loop /post-merge-sweeper  # PRs для пропущенных review comments
/loop 1h /pr-pruner        # закрытие стейл PRs

Scheduled Tasks через Desktop sidebar: Schedule → New task → промпт + время + частота.

Или естественным языком: "set up a daily code review every morning at 9am" — Claude сам настроит.

Ограничение: машина должна не спать, Desktop должен быть открыт.

📌 Пример из жизни

Ситуация: Ты тех-лид стартапа. Команда из 5 разработчиков, каждый день 8-12 PR. Ты физически не успеваешь ревьювить всё, PR-ы висят по 2-3 дня. Качество падает, конфликты растут.

Настраиваешь два автоматических процесса:

# Каждые 5 минут — проверить открытые PR, rebase если нужно, оставить ревью
/loop 5m /babysit

# Каждый день в 9 утра — отчёт по стейл PR-ам старше 48 часов
# Через Desktop: Schedule → "Review stale PRs older than 48h, ping authors in comments"

Или более конкретный workflow:

# Каждый час — проверить что тесты проходят на всех открытых PR
/loop 1h "Check all open PRs, if tests fail — leave comment with diagnosis"

Результат: PR-ы ревьювятся в течение минут. Стейл ветки не копятся. Ты фокусируешься на архитектурных решениях, а не на рутине.

Кому нужно:

  • Команды с активным PR-потоком (5+ PR/день)
  • Тех-лиды которые не успевают ревьювить
  • Проекты с CI/CD где нужен постоянный мониторинг
  • Open-source мейнтейнеры с большим потоком контрибуций

Когда НЕ нужно: соло-проекты, проекты без PR-процесса, ранний прототип.

6. 🟡 Hooks — детерминированная логика в агентном цикле

Зачем: Хуки позволяют подключить свою логику к любому моменту работы агента. Это не промпт — это гарантированное выполнение.

События:

Событие Когда срабатывает
SessionStart Загрузка контекста при старте
PreToolUse До каждого вызова инструмента
PostToolUse После каждого вызова
Stop Когда агент останавливается
PermissionRequest При запросе разрешения
SessionEnd Завершение сессии
WorktreeCreate/Remove Создание/удаление worktree
StopFailure Ошибка API (rate limit, auth)

Примеры применения:

# Динамическая загрузка контекста при старте
SessionStart → скрипт читает актуальные данные и передаёт в промпт

# Логирование всех bash команд
PreToolUse(Bash) → записывает команду в лог

# Апрув опасных операций с телефона
PermissionRequest → POST в WhatsApp/Telegram → ждёт ответа

# Не дать агенту остановиться
Stop → пингует агента продолжать работу

Документация: https://code.claude.com/docs/en/hooks

📌 Пример из жизни

Ситуация: У тебя финтех-проект с микросервисной архитектурой. Каждый сервис имеет свои переменные окружения, свою схему БД, свои зависимости. Когда агент стартует сессию — ему нужен актуальный контекст: какие сервисы запущены, какие миграции применены, какие feature-флаги активны.

Настраиваешь хук SessionStart:

// .claude/settings.json
{
  "hooks": {
    "SessionStart": [{
      "command": "python scripts/claude-context.py",
      "timeout": 10000
    }]
  }
}
# scripts/claude-context.py
# Собирает актуальный контекст и выводит в stdout — Claude прочитает
import subprocess, json

# Какие сервисы запущены
services = subprocess.check_output(["docker", "compose", "ps", "--format", "json"])
# Последняя миграция
migration = subprocess.check_output(["prisma", "migrate", "status"])
# Активные feature flags
flags = json.load(open("config/features.json"))

print(f"## Current Environment State")
print(f"Running services: {services.decode()}")
print(f"DB migration status: {migration.decode()}")
print(f"Active feature flags: {json.dumps(flags, indent=2)}")

Или более простой пример — логирование для аудита:

{
  "hooks": {
    "PreToolUse": [{
      "command": "python scripts/log-action.py",
      "timeout": 5000
    }]
  }
}

Результат: агент всегда работает с актуальным контекстом. Все действия логируются. Опасные операции требуют подтверждения.

Кому нужно:

  • Проекты с динамическим контекстом (микросервисы, feature flags, multi-tenant)
  • Команды с требованиями аудита и compliance (финтех, медтех)
  • Проекты где агент работает с production-данными и нужен safety layer
  • CI/CD интеграции где агент должен знать состояние pipeline

Когда НЕ нужно: простые проекты с одним сервисом и статичной конфигурацией.

7. 🟢 Мобильное приложение + Remote Control

Зачем: Писать и ревьювить код без ноутбука. Управлять локальными сессиями с телефона.

Как внедрить:

Мобильное приложение:

  • iOS/Android → вкладка Code

Управление сессиями:

# Перенести cloud-сессию в терминал
claude --teleport
# или внутри сессии:
/teleport

# Управлять локальной сессией с телефона/веба
/remote-control

Рекомендация: включить "Enable Remote Control for all sessions" в /config — тогда каждая сессия автоматически доступна удалённо.

📌 Пример из жизни

Ситуация: Ты запустил длинную миграцию с телефона по дороге на работу. Или сидишь на созвоне и хочешь быстро проверить статус агента на компьютере — не переключаясь из Zoom.

# На ноутбуке запустил тяжёлую задачу
claude> "Рефакторни все API-эндпоинты под новую схему авторизации"
# Агент работает...

# С телефона открываешь Claude Code app → видишь сессию →
# пишешь: "Покажи прогресс, какие файлы уже изменены?"
# или: "/btw не забудь обновить тесты для /api/users"

Или обратный сценарий — начал с телефона, продолжил на компе:

# На телефоне: "Создай скелет нового микросервиса notification-service"
# Через 10 минут за компом:
claude --teleport  # подхватил сессию с телефона в терминал

Кому нужно:

  • Разработчики которые часто в дороге или на созвонах
  • Тех-лиды которые хотят мониторить агентов с телефона
  • Те кто запускает долгие задачи и хочет проверять статус без переключения контекста

Кому скорее всего не нужно: те кто работает исключительно за десктопом в офисе.

8. 🟢 Branching сессий

Зачем: Попробовать альтернативный подход не теряя текущий контекст. Или дать одну задачу двум веткам и сравнить результат.

Как внедрить:

# Внутри сессии
/branch

# Из CLI
claude --resume <session-id> --fork-session

📌 Пример из жизни

Ситуация: Ты обсуждаешь с агентом архитектуру нового модуля уведомлений. Агент предложил использовать Redis pub/sub. Ты думаешь — а может лучше WebSocket напрямую? Не хочешь терять текущий контекст обсуждения.

# Текущая сессия — Redis подход
claude> "Давай реализуем через Redis pub/sub"
# Агент начинает...

# Делаешь ветку — WebSocket подход
/branch
claude> "А теперь давай попробуем через WebSocket напрямую, без Redis"
# Агент реализует альтернативу

# Сравниваешь два результата, выбираешь лучший

Другой сценарий — "а что если":

# Агент написал компонент с CSS Modules
# Ты хочешь посмотреть как выглядит вариант с Tailwind
/branch
claude> "Перепиши этот компонент на Tailwind вместо CSS Modules"

Кому нужно:

  • Архитектурные решения где хочешь сравнить два подхода
  • Ситуации "а что если" без риска потерять текущую работу
  • Эксперименты с разными технологиями/библиотеками для одной задачи

Кому скорее всего не нужно: линейная разработка без экспериментов.

9. 🟢 /btw — параллельные вопросы

Зачем: Задать быстрый вопрос пока агент работает, не прерывая его.

Как внедрить:

/btw что такое X?

Агент ответит в сторонке и продолжит основную задачу.

📌 Пример из жизни

Ситуация: Агент пишет сложный модуль парсинга CSV-файлов. Ты параллельно читаешь его код и видишь незнакомую конструкцию. Не хочешь прерывать — он в процессе.

claude> "Напиши парсер CSV с поддержкой кастомных разделителей и экранирования"
# Агент работает, пишет код...

/btw почему ты используешь генератор вместо обычного массива?
# Агент быстро объясняет: "Генератор не загружает весь файл в память —
# для файлов в 500MB это критично" — и продолжает основную задачу

/btw а TextDecoder поддерживается в Node 16?
# Быстрый ответ, основная работа не прерывается

Кому нужно:

  • Те кто учится на коде агента и хочет понимать решения в реальном времени
  • Длинные сессии где агент работает 5-10 минут и ты хочешь задать уточнение
  • Ситуации "вспомнил ещё кое-что" посреди генерации

Кому скорее всего не нужно: короткие сессии где проще дождаться конца и спросить.

10. 🟡 Chrome Extension для фронтенда

Зачем: Дать агенту "глаза" — способность видеть результат своей работы и итерировать. Ключевой принцип: агент без браузера не может сделать хороший фронтенд, так же как инженер без браузера.

Как внедрить:

Установить расширение: https://code.claude.com/docs/en/chrome

Работает в Chrome и Edge. После установки — агент сам запускает сервер, открывает браузер, видит результат, итерирует.

📌 Пример из жизни

Ситуация: Ты просишь агента сверстать лендинг по макету из Figma. Без расширения — агент пишет HTML/CSS вслепую, ты вручную проверяешь и говоришь "кнопка слишком большая, отступ не тот". С расширением — агент сам видит результат.

claude> "Сверстай hero-секцию: заголовок, подзаголовок, CTA-кнопка, фоновый градиент.
        Макет: https://figma.com/file/xxx"

Что происходит с расширением:

  1. Агент пишет HTML + CSS
  2. Запускает npm run dev
  3. Открывает Chrome → делает скриншот страницы
  4. Анализирует: "Кнопка не отцентрирована, добавляю margin: 0 auto"
  5. Перезагружает → делает новый скриншот
  6. "Теперь ОК, но шрифт заголовка слишком мелкий на мобильном"
  7. Добавляет media query → проверяет → готово

Результат: вместо 5 итераций "ты → агент → ты → агент" — агент сам доводит до пикселя.

Кому нужно:

  • Любая фронтенд-разработка: React, Vue, Svelte, plain HTML
  • Вёрстка по макетам (Figma, Sketch)
  • Исправление визуальных багов ("на мобильном съезжает", "в Safari по-другому")
  • CSS-анимации и интерактивные элементы

Когда НЕ нужно: бэкенд-проекты, CLI-утилиты, библиотеки без UI.

11. 🟡 Desktop: Preview веб-приложений

Зачем: Встроенный браузер в Desktop app для автоматического запуска и тестирования веб-серверов — без ручной настройки.

Документация: https://code.claude.com/docs/en/desktop#preview-your-app

📌 Пример из жизни

Ситуация: Ты работаешь в Claude Code Desktop и пишешь React-приложение. Вместо того чтобы переключаться между Desktop и Chrome — встроенный preview показывает результат прямо в окне Claude.

claude> "Создай форму регистрации с валидацией полей"
# Агент пишет код → автоматически запускает dev server →
# встроенный preview показывает результат прямо в Desktop app →
# агент видит результат и итерирует

Работает как Chrome Extension (#10), но без установки расширения — всё внутри Desktop.

Кому нужно:

  • Пользователи Claude Code Desktop (не CLI) с фронтенд-проектами
  • Те кто хочет "всё в одном окне" без переключения
  • Быстрое прототипирование — увидеть результат мгновенно

Альтернатива: если работаешь в CLI — используй Chrome Extension (#10) вместо этого.

12. 🟡 --bare для SDK (до 10x ускорение)

Зачем: По дефолту каждый запуск claude -p ищет CLAUDE.md, settings, MCPs — это лишняя работа для non-interactive usage. --bare отключает автопоиск.

Как внедрить:

claude -p --bare --system-prompt "..." --mcp-config ./mcp.json "твоя задача"

Anthropic планирует сделать --bare дефолтом в будущих версиях. Сейчас — opt-in.

📌 Пример из жизни

Ситуация: Ты интегрировал Claude Code в CI/CD pipeline. На каждый PR автоматически запускается код-ревью через claude -p. Проблема: каждый запуск тратит 5-10 секунд на поиск и загрузку CLAUDE.md, settings, подключение MCP серверов — это лишнее для скриптового вызова.

# Было (медленно — 12 сек на старт):
claude -p "Review this diff: $(git diff main...HEAD)"

# Стало (быстро — 1-2 сек на старт):
claude -p --bare \
  --system-prompt "You are a code reviewer. Focus on bugs, security, performance." \
  "Review this diff: $(git diff main...HEAD)"

Более сложный пример — pipeline генерации документации:

#!/bin/bash
# generate-docs.sh — запускается в CI на каждый merge в main
for file in src/api/*.ts; do
  claude -p --bare \
    --system-prompt "Generate JSDoc for the given TypeScript file. Output only the updated file." \
    "$(cat $file)" > "${file}.documented"
done

Результат: CI-шаг вместо 2 минут занимает 20 секунд. Чистый скриптовый вызов без overhead.

Кому нужно:

  • CI/CD интеграции (GitHub Actions, GitLab CI, Jenkins)
  • Скрипты и пайплайны которые вызывают Claude Code десятки/сотни раз
  • SDK-usage: свои инструменты поверх Claude Code CLI
  • Batch-обработка файлов где каждый вызов должен быть быстрым

Когда НЕ нужно: интерактивная работа в терминале — там CLAUDE.md и MCPs нужны.

13. 🟡 --add-dir для мультирепозиторного workflow

Зачем: Дать агенту доступ к нескольким репозиториям в одной сессии.

Как внедрить:

# При запуске
claude --add-dir ../другой-репо

# Внутри сессии
/add-dir ../другой-репо

Для команды — добавить в settings.json:

{
  "additionalDirectories": ["../shared-lib", "../api"]
}

Документация: https://code.claude.com/docs/en/cli-reference

📌 Пример из жизни

Ситуация: Типичная архитектура стартапа — три репозитория:

~/projects/
├── frontend/     # React SPA
├── backend/      # Node.js API
└── shared-types/ # TypeScript типы, общие для обоих

Ты меняешь API-эндпоинт в backend/ и нужно обновить типы в shared-types/ и вызов в frontend/. Без --add-dir — три отдельные сессии, ручная координация.

cd ~/projects/backend
claude --add-dir ../shared-types --add-dir ../frontend

claude> "Добавь поле `avatar_url` к User:
        1. Обнови тип в shared-types/src/user.ts
        2. Добавь поле в API-ответ backend/src/routes/users.ts
        3. Покажи аватар в frontend/src/components/UserProfile.tsx"

Агент видит все три репо и делает согласованные изменения в одной сессии.

Другой пример — монорепо с Turborepo/Nx:

cd packages/web
claude --add-dir ../api --add-dir ../shared

Кому нужно:

  • Мультирепозиторные архитектуры (frontend + backend + shared)
  • Монорепозитории с пакетами которые зависят друг от друга
  • Ситуации где изменение в одном месте требует обновления в другом
  • Микросервисы с общим контрактом (protobuf, OpenAPI schema)

Когда НЕ нужно: один репозиторий, самодостаточные проекты.

14. 🟡 --agent для кастомных агентов

Зачем: Запустить Claude Code с кастомным system prompt и конкретным набором инструментов. Мощный примитив для создания специализированных агентов под конкретные задачи.

Как внедрить:

Создать файл .claude/agents/my-agent.md:

---
name: my-agent
description: Что делает этот агент
tools: Bash, Read, Write
model: sonnet
---

Ты специализированный агент для...

Запустить:

claude --agent=my-agent

Документация: https://code.claude.com/docs/en/sub-agents

📌 Пример из жизни

Ситуация: В твоей команде есть повторяющиеся задачи: ревью SQL-миграций, генерация API-документации, создание компонентов по шаблону. Каждый раз объяснять агенту контекст — потеря времени. Кастомные агенты решают это.

Пример — агент для ревью SQL-миграций:

# .claude/agents/sql-reviewer.md
---
name: sql-reviewer
description: Ревью SQL-миграций на безопасность и производительность
tools: Read, Bash
model: sonnet
---

Ты эксперт по PostgreSQL миграциям. При получении миграции:

1. Проверь обратимость (есть ли DOWN migration)
2. Проверь блокировки: ALTER TABLE на больших таблицах без CONCURRENTLY — красный флаг
3. Проверь индексы: новые колонки с WHERE-запросами должны иметь индекс
4. Проверь дефолты: NOT NULL без DEFAULT на существующей таблице = downtime

## Non-Negotiable
- Если найден blocking ALTER — вывести WARNING с предложением safe-версии
- Всегда показывать estimated lock time для каждой операции

Использование:

claude --agent=sql-reviewer
> "Проревьюй миграции в db/migrations/2026-03-*"

Ещё пример — агент для создания React-компонентов:

# .claude/agents/component-factory.md
---
name: component-factory
description: Создаёт React-компонент по шаблону проекта
tools: Read, Write, Bash
---

Создай React-компонент. Обязательно:
1. TypeScript, named export, no default export
2. Стили через CSS Modules (.module.css)
3. Storybook story рядом (ComponentName.stories.tsx)
4. Unit test рядом (ComponentName.test.tsx)
5. Barrel export через index.ts

Кому нужно:

  • Команды со стандартизированными процессами (ревью, генерация, проверки)
  • Проекты с шаблонами: "каждый новый модуль выглядит так"
  • Компании с domain-specific правилами (финтех, медтех, gamedev)
  • Онбординг: новый разработчик запускает агента вместо чтения 50 страниц docs

Когда НЕ нужно: одноразовые задачи, прототипирование, маленькие проекты без шаблонов.

15. 🟢 /voice — голосовой ввод

Как внедрить:

  • CLI: /voice → держать пробел
  • Desktop: кнопка голоса
  • iOS: включить диктовку в настройках системы

📌 Пример из жизни

Ситуация: Ты на диване с ноутбуком, думаешь над архитектурой. Проще проговорить мысль голосом, чем печатать длинный промпт.

/voice
# Держишь пробел и говоришь:
# "Мне нужен модуль нотификаций. Он должен поддерживать три канала:
#  email через SendGrid, push через Firebase, и SMS через Twilio.
#  Каждый канал — отдельный адаптер за единым интерфейсом.
#  Очередь на Redis, retry с exponential backoff."

Агент получает текст и начинает работу. Быстрее чем печатать 5 предложений.

Ещё удобно для описания багов:

/voice
# "На странице профиля, если юзер не загрузил аватар,
#  показывается broken image вместо дефолтной иконки.
#  Это только на мобильном разрешении, на десктопе норм."

Кому нужно:

  • Те кто предпочитает думать вслух
  • Длинные, описательные промпты (баг-репорты, архитектурные решения)
  • Работа с мобильного приложения

Кому скорее всего не нужно: те кто печатает быстрее чем говорит, работа в шумном офисе.

16. 🟡 gstack — специализированные когнитивные режимы

Зачем: Вместо одного generic агента — команда специалистов. Каждый skill — строго одна роль. Ключевой принцип: явные "когнитивные режимы" дают предсказуемый результат.

Установка (одна команда в Claude Code):

Install gstack: run `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`

Режимы:

Команда Роль Что делает
/plan-ceo-review Founder/CEO Находит 10-star продукт внутри запроса
/plan-eng-review Eng Manager Архитектура, диаграммы, edge cases
/review Paranoid Staff Eng Баги которые проходят CI но ломают прод
/ship Release Engineer sync + tests + PR одной командой
/browse QA Engineer Headless Chromium, ~100ms, видит UI
/qa QA Lead Diff-aware: читает git diff, тестирует затронутые страницы
/retro Eng Manager Командная ретроспектива с метриками

Репозиторий: https://github.com/garrytan/gstack

📌 Пример из жизни

Ситуация: Ты строишь B2B SaaS. Новая фича — dashboard с аналитикой. Хочешь пройти полный цикл от идеи до PR, используя специализированные роли.

Шаг 1 — Product review:

/plan-ceo-review
> "Dashboard аналитики: графики revenue, churn, MRR. Фильтры по дате и сегменту."
# CEO-mode: "Убери churn с главного экрана — это пугает.
#  Добавь 'Net Revenue Retention' — это показывает рост.
#  Первый экран должен вызывать 'wow, мы растём'."

Шаг 2 — Engineering review:

/plan-eng-review
# Eng Manager: рисует архитектуру, находит edge cases:
# "Что если данных за период нет? Пустой график или сообщение?
#  Фильтр по дате: клиентский или серверный? При 100k записей — только серверный."

Шаг 3 — Реализация + ревью:

# Пишешь код...

/review
# Paranoid Staff Eng: "Ты вычисляешь MRR на клиенте суммируя все subscriptions.
#  При 10k подписок это 2 секунды блокировки UI.
#  Перенеси в SQL-агрегацию или Web Worker."

Шаг 4 — QA + Ship:

/qa     # Тестирует затронутые страницы в headless browser
/ship   # Собирает, прогоняет тесты, создаёт PR

Результат: полный pipeline от продукт-мышления до PR, каждый этап — специализированный агент.

Кому нужно:

  • Продуктовые команды где важен и UX и качество кода
  • Стартапы где один человек = CEO + CTO + IC: gstack даёт "виртуальную команду"
  • Проекты с фронтендом где важно визуальное QA (headless browser)
  • Команды практикующие structured review process

Когда НЕ нужно: чистый бэкенд без UI, маленькие утилиты, one-off скрипты.

17. 🔴 Thinking — показывать процесс рассуждений

Зачем: С v2.0.0 thinking скрыт по умолчанию. Для дебага и понимания решений агента — включить явно.

Как включить:

В settings.json:

{
  "alwaysThinkingEnabled": true
}

Или в сессии: Ctrl+O → transcript mode.

Управление глубиной thinking:

/effort low|medium|high

📌 Пример из жизни

Ситуация: Агент делает что-то странное — рефакторит файл который ты не просил, или выбирает непонятное решение. Без thinking — чёрный ящик, непонятно почему.

# Без thinking:
claude> "Оптимизируй запрос к БД в users.service.ts"
# Агент молча переписывает 3 файла, меняет ORM-вызовы, добавляет кэш.
# Ты: "Зачем кэш? Я просил только запрос оптимизировать!"

# С thinking (alwaysThinkingEnabled: true):
claude> "Оптимизируй запрос к БД в users.service.ts"
# 💭 Thinking: "Запрос users.service.ts:42 делает N+1 — для каждого user
#   загружает orders отдельным запросом. Могу решить через JOIN, но
#   этот же запрос используется в cache-layer (users.cache.ts),
#   который ожидает flat user object без orders. Если добавлю JOIN,
#   сломаю кэш. Два варианта:
#   1. JOIN + обновить кэш-слой
#   2. Eager loading через ORM relation
#   Вариант 2 проще и не ломает контракт."
# Теперь ты понимаешь ЧТО и ПОЧЕМУ он делает.

Управление глубиной thinking в зависимости от задачи:

/effort low     # Быстрые задачи: "переименуй переменную", "добавь import"
/effort medium  # Стандарт: фичи, рефакторинг, баги
/effort high    # Сложные задачи: архитектура, security-audit, дебаг race condition

Кому нужно: всем. Это базовая настройка для понимания и контроля агента:

  • Дебаг неожиданного поведения — понять почему агент принял конкретное решение
  • Обучение — учиться на рассуждениях агента (особенно junior-разработчикам)
  • Ревью — убедиться что агент правильно понял задачу до того как он напишет 500 строк кода
  • Сложные задачи — architectural decisions, security, performance optimization

/effort полезен всем: не тратить compute на тривиальные задачи, максимально вкладываться в сложные.

18. 🔴 CLAUDE.md как основной документ управления

Зачем: CLAUDE.md — главный инструмент настройки поведения агента. Загружается автоматически.

Структура:

## Project Overview
Краткое описание проекта

## Code Standards
- Never typecast. Never use `as`
- [другие стандарты]

## Architecture
Ключевые решения которые не нужно переизобретать

## Workflow
Как работаем в этом проекте

HTML-комментарии <!-- --> в CLAUDE.md скрыты от агента при автозагрузке, но видны при явном чтении через Read tool. Используй для заметок себе.

📌 Пример из жизни

Ситуация: У тебя Next.js e-commerce проект. Без CLAUDE.md каждая сессия начинается с нуля — агент не знает структуру проекта, конвенции, архитектурные решения. Ты объясняешь одно и то же снова и снова.

С CLAUDE.md — агент стартует с полным контекстом:

# CLAUDE.md

## Project Overview
E-commerce на Next.js 14 (App Router) + Prisma + PostgreSQL + Stripe.
Монорепо на Turborepo: apps/web, apps/admin, packages/shared.

## Code Standards
- Never typecast. Never use `as` — используй Zod для runtime-валидации
- Все API-ручки через Route Handlers (app/api/), не Pages API
- Стили: Tailwind CSS, никаких CSS-in-JS
- Состояние: Zustand для клиента, React Query для серверных данных
- Формы: react-hook-form + zod resolver

## Architecture
- Auth: NextAuth.js с JWT strategy, middleware в middleware.ts
- Платежи: Stripe Checkout → webhook в /api/webhooks/stripe
- Изображения: S3 + CloudFront, оптимизация через next/image
- Emails: React Email + Resend

## Workflow
- Ветки: feature/<name>, fix/<name>
- Коммиты: Conventional Commits (feat:, fix:, chore:)
- Перед PR: `pnpm lint && pnpm test && pnpm build`
- Деплой: Vercel, preview на каждый PR

## Known Issues
<!-- Заметка для себя: не показывать агенту автоматически -->
<!-- TODO: мигрировать с next-auth v4 на v5 после стабилизации -->
- Stripe webhook иногда дублирует события — есть idempotency check в lib/stripe.ts
- На Safari анимация корзины лагает — известный CSS transform баг

Результат: каждая новая сессия — агент уже знает:

  • Какой стек и почему именно он
  • Какие паттерны использовать (Zod, не as; Zustand, не Redux)
  • Как устроена авторизация и платежи
  • Какие баги известны (чтобы не "чинить" их заново)

Кому нужно: абсолютно всем кто использует Claude Code больше одной сессии:

  • Любой проект — от pet-project до enterprise: CLAUDE.md экономит 2-5 минут на каждую сессию
  • Команды — единые стандарты для всех кто запускает агента
  • Сложные архитектуры — агент не будет "изобретать" то что уже решено
  • Онбординг — новый разработчик читает CLAUDE.md и понимает ключевые решения

Это самый важный файл в настройке Claude Code. Всё остальное — оптимизация поверх.

19. 🔴 Harness Engineering — теория и ресурсы

Главный тезис: слабые результаты агента почти всегда проблема harness (окружения), а не модели. Это красная нить через весь гайд — Never use as, структура Skills с Non-Negotiable критериями, worktrees, hooks — всё это harness engineering в разных формах.

Определение: harness engineering — практика формирования окружения вокруг агента так, чтобы он работал предсказуемо. Пересекается с context engineering, evaluation, observability, оркестрацией и safe autonomy.

📌 Пример из жизни

Ситуация: Ты жалуешься: "Агент генерирует плохой код, не следует стандартам, забывает тесты". Интуиция подсказывает — сменить модель или prompt. Harness engineering говорит: проблема не в модели.

До (плохой harness):

Ты: "Напиши авторизацию"
Агент: *пишет что-то... каждый раз по-разному*
Ты: "Нет, не так! Используй JWT, не sessions!"
Агент: *переписывает... забывает refresh token*
Ты: "Добавь refresh token!"
# 5 итераций... результат посредственный

После (хороший harness):

# CLAUDE.md
## Auth
- JWT с access + refresh tokens
- Access token: 15 min, refresh: 7 days
- Хранение: httpOnly cookies, не localStorage
- Middleware: app/middleware.ts, проверяет access token

# .claude/skills/auth-module.md
## Non-Negotiable Acceptance Criteria
- [ ] Access token expires in 15 min
- [ ] Refresh token expires in 7 days
- [ ] Tokens stored in httpOnly secure cookies
- [ ] /auth/refresh endpoint exists and tested
- [ ] Middleware rejects expired tokens with 401
Ты: "Напиши авторизацию"
Агент: *читает CLAUDE.md + skill → точно знает ЧТО и КАК*
# 1 итерация, предсказуемый результат

Аналогия: harness engineering = дорожная разметка. Без разметки — опытный водитель доедет, но каждый раз по разной траектории. С разметкой — даже новичок едет предсказуемо.

Кому нужно: абсолютно всем — это фундамент, а не фича:

  • Это не отдельный инструмент, а мышление: "если агент делает не то — проблема в моём окружении"
  • Статьи ниже — обязательное чтение для любого кто хочет получить максимум от AI-агентов
  • Применимо к любому стеку, любому размеру проекта

Первичные источники от Anthropic

Статья Суть
Effective harnesses for long-running agents Initializer agents, init.sh, self-verification, handoff artifacts через много контекстных окон
Claude Code: Best practices for agentic coding Repo structure, checkpoints, validation, delegation
Writing effective tools for agents Tool interfaces которые модель вызывает правильно и безопасно
Effective context engineering Context window как рабочий бюджет памяти, не помойка
Building effective agents Workflows, agents, tools — когда структура бьёт сырой промпт

Практические гайды

Статья Суть
Writing a good CLAUDE.md Дурабельные repo-local инструкции которым агент следует повторно
Skill Issue: Harness Engineering Конкретный аргумент: слабые результаты = проблема harness
12 Factor Agents Принципы для production агентов: explicit prompts, state ownership, pause-resume
Context Engineering for AI Agents (Manus) KV-cache locality, tool masking, filesystem memory

Awesome-list

Полный курированный список: https://github.com/walkinglabs/awesome-harness-engineering

20. 🟡 MCP-серверы — расширение возможностей агента

Зачем: MCP (Model Context Protocol) — протокол который даёт Claude Code доступ к внешним инструментам. Без MCP агент умеет: читать/писать файлы, bash, git. С MCP — подключается к базам данных, удалённым серверам, браузерам, документации и любым API.

Принцип: один MCP-сервер = один источник данных или инструмент. Агент сам решает когда вызвать нужный MCP на основе контекста задачи.

Как подключить MCP:

# Через CLI
claude mcp add <имя> -- <команда запуска>

# Или в .claude/settings.json
{
  "mcpServers": {
    "имя-сервера": {
      "command": "npx",
      "args": ["-y", "@package/mcp-server"]
    }
  }
}

Документация: https://code.claude.com/docs/en/mcp

20.1 Context7 — актуальная документация библиотек

Зачем: Claude Code обучен на данных с конкретной датой среза. Он не знает про новые API, breaking changes, обновлённые best practices. Context7 подтягивает актуальную документацию прямо из официальных источников библиотек — в реальном времени, для конкретной версии.

Установка:

claude mcp add context7 -- npx -y @upstash/context7-mcp@latest

Использование:

Добавить use context7 в промпт:

Создай middleware для FastAPI с JWT-авторизацией. use context7

Агент автоматически:

  1. Определяет что нужна документация FastAPI
  2. Подтягивает актуальные docs для текущей версии
  3. Пишет код на основе реальных API, а не памяти

📌 Пример из жизни

Ситуация: Ты используешь Selenium 4.x для парсинга. В Selenium 4 изменился API — find_element_by_xpath() стал find_element(By.XPATH, ...). Без Context7 агент может написать старый синтаксис (он видел его чаще в обучающих данных). С Context7 — подтянет актуальный API.

# Без context7:
driver.find_element_by_xpath("//div[@class='price']")  # deprecated с Selenium 4

# С context7:
driver.find_element(By.XPATH, "//div[@class='price']")  # актуальный API

Кому нужно: всем — это базовый MCP. Особенно если работаешь с часто обновляемыми библиотеками (фреймворки, ORM, облачные SDK).

Репозиторий: https://github.com/upstash/context7

20.2 SSH Manager — управление удалёнными серверами

Зачем: Дать агенту SSH-доступ к серверам. Агент может: выполнять команды, читать логи, проверять статус сервисов, управлять Docker-контейнерами, делать бэкапы — всё через естественный язык.

Установка:

npm install -g mcp-ssh-manager
claude mcp add ssh-manager -- npx mcp-ssh-manager

# Добавить сервер
ssh-manager server add
# → имя: production
# → хост: 192.168.1.100
# → пользователь: deploy
# → ключ: ~/.ssh/id_rsa

Возможности (37+ инструментов):

Категория Что умеет
Команды Выполнение любых shell-команд на удалённом сервере
Мониторинг CPU, RAM, диск, статус сервисов
Docker Список контейнеров, логи, restart, stats
Файлы Upload/download файлов между локальной машиной и сервером
БД Дамп/восстановление MySQL, PostgreSQL, MongoDB
Безопасность Анализ логов, блокировка IP через iptables/ufw

📌 Пример из жизни

Ситуация: Ты DevOps/бэкенд-разработчик. Парсер на продакшене упал в 3 ночи. Утром нужно понять что произошло, починить и перезапустить.

claude> "Подключись к серверу production.
        Покажи логи парсера за последние 2 часа.
        Найди ошибки и объясни что случилось."

# Агент:
# 1. SSH на production
# 2. tail -n 500 /var/log/parser/error.log
# 3. Анализирует: "OLX заблокировал IP в 03:17. Rate limit exceeded.
#    Прокси-ротация не сработала — файл proxies.txt пустой."
# 4. Предлагает: "Обновить список прокси и перезапустить парсер"

claude> "Перезапусти парсер и покажи что он работает"
# docker restart parser && docker logs --tail 20 parser

Более продвинутый пример — защита сервера:

claude> "Проанализируй /var/log/auth.log за последние сутки.
        Найди подозрительные IP с брутфорсом.
        Заблокируй их через ufw."

# Агент:
# 1. grep "Failed password" /var/log/auth.log | awk '{print $11}' | sort | uniq -c | sort -rn
# 2. "Найдено 3 IP с 500+ попытками: 45.33.x.x, 91.12.x.x, 185.7.x.x"
# 3. ufw deny from 45.33.x.x && ufw deny from 91.12.x.x && ...

Кому нужно:

  • DevOps и сисадмины которые управляют серверами
  • Бэкенд-разработчики с доступом к staging/production
  • Проекты с Docker на удалённых серверах
  • Мониторинг и инцидент-менеджмент

Когда НЕ нужно: локальная разработка без серверов, фронтенд-проекты.

⚠️ Безопасность: SSH-доступ для AI — мощно, но опасно. Рекомендации:

  • Используй отдельного пользователя с ограниченными правами
  • Никогда не давай root-доступ
  • Начни с read-only команд (логи, статус)
  • Используй SSH-ключи, не пароли
  • На production — только после тестирования на staging

Репозиторий: https://github.com/bvisible/mcp-ssh-manager

20.3 PostgreSQL MCP — прямой доступ к базе данных

Зачем: Агент подключается к PostgreSQL и может: выполнять SQL-запросы, исследовать схему, анализировать производительность, помогать с миграциями. Вместо того чтобы копировать запросы между терминалом и Claude — агент работает с БД напрямую.

Установка:

# Базовый вариант (read-only по умолчанию)
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres \
  "postgresql://user:pass@localhost:5432/mydb"

# Или продвинутый с анализом производительности
npm install -g @henkey/postgres-mcp-server

Возможности:

Функция Описание
Schema exploration Список таблиц, колонок, типов, связей
SQL-запросы SELECT, INSERT, UPDATE (если разрешено)
EXPLAIN анализ Показать план выполнения запроса
Индексы Предложить оптимальные индексы
Миграции Помощь с генерацией миграций
Здоровье БД Размер таблиц, мёртвые строки, bloat

📌 Пример из жизни

Ситуация: Ты работаешь над парсером недвижимости. Данные сохраняются в PostgreSQL. Нужно понять структуру данных, найти дубликаты, оптимизировать медленный запрос.

claude> "Покажи схему таблицы properties — какие поля, типы, индексы"
# Агент: SELECT * FROM information_schema.columns WHERE table_name = 'properties'
# "Таблица properties: id, url, price, area, rooms, address, source, created_at, ...
#  Индексы: primary key на id, нет индекса на url — это проблема для дедупликации"

claude> "Найди дубликаты объявлений по URL"
# SELECT url, COUNT(*) as cnt FROM properties GROUP BY url HAVING COUNT(*) > 1 ORDER BY cnt DESC
# "Найдено 847 дубликатов. Топ: olx.ua/d/obyavlenie/... — 12 копий"

claude> "Почему запрос поиска по районам медленный?"
# EXPLAIN ANALYZE SELECT * FROM properties WHERE address ILIKE '%Шевченковский%'
# "Sequential scan на 500k строк. Нужен GIN-индекс для text search:
#  CREATE INDEX idx_properties_address_gin ON properties USING gin(address gin_trgm_ops)"

Кому нужно:

  • Проекты с PostgreSQL где нужно часто исследовать данные
  • Дебаг парсеров — проверить что данные сохраняются правильно
  • Оптимизация запросов без переключения между IDE и psql
  • Миграции и рефакторинг схемы

Когда НЕ нужно: проекты без БД, или когда хватает обычного psql/pgAdmin.

⚠️ Безопасность:

  • По умолчанию включай read-only режим
  • Для production — создай отдельного пользователя с SELECT-only правами
  • Write-доступ — только для dev/staging

Репозиторий: https://github.com/modelcontextprotocol/servers/tree/main/src/postgres

20.4 DevOps Skill — комплексное управление инфраструктурой

Зачем: Объединить SSH Manager + PostgreSQL MCP + знание инфраструктуры в один Skill. Агент работает как junior DevOps: мониторит, диагностирует, чинит — но по строгим правилам.

Структура:

# .claude/skills/devops.md
---
name: devops
description: Диагностика и управление серверной инфраструктурой
---

## Skill Purpose
Диагностика проблем, мониторинг здоровья инфраструктуры, безопасное
выполнение операций на серверах через SSH Manager MCP.

## Instructions
1. Перед ЛЮБОЙ операцией — сначала проверь текущее состояние (статус, логи)
2. Для диагностики — используй read-only команды
3. Для изменений — сначала покажи план, дождись подтверждения
4. После изменений — проверь что всё работает

## Non-Negotiable Acceptance Criteria
- [ ] Никогда не выполнять rm -rf, DROP DATABASE, или деструктивные команды без явного подтверждения
- [ ] Всегда сначала диагностика, потом действие
- [ ] Логировать каждую выполненную команду на сервере
- [ ] Перед перезапуском сервиса — проверить что нет активных соединений/транзакций
- [ ] После любого изменения — верификация что сервис работает (health check)

## Output
Структурированный отчёт:
- Что было проверено
- Что найдено (ошибки, аномалии)
- Что сделано (с командами)
- Текущий статус после изменений

📌 Пример из жизни

Ситуация: Понедельник утро. Парсер не работал всё выходные. Нужно: понять причину → починить → убедиться что данные не потеряны → перезапустить.

claude> "Продиагностируй почему парсер не работал с пятницы"
# Агент (используя SSH + PostgreSQL MCP):
# 1. docker ps -a → парсер в статусе "Exited (137)" с пятницы 23:45
# 2. docker logs parser --since 72h → OOM Kill (Out of Memory)
# 3. SELECT COUNT(*), MAX(created_at) FROM properties → последняя запись: пятница 23:44
# 4. free -h на сервере → 95% RAM занято Redis кэшем
#
# Отчёт:
# - Причина: OOM Kill — Redis съел всю память, Docker убил парсер
# - Потеряно: ~48 часов парсинга (с пятницы 23:45 до сейчас)
# - Рекомендация: ограничить Redis maxmemory, добавить restart: always в docker-compose

claude> "Исправь и перезапусти"
# 1. docker exec redis redis-cli CONFIG SET maxmemory 512mb
# 2. docker exec redis redis-cli CONFIG SET maxmemory-policy allkeys-lru
# 3. docker restart parser
# 4. sleep 10 && docker logs --tail 5 parser → "Successfully parsed 3 listings"
# 5. SELECT COUNT(*) FROM properties WHERE created_at > now() - interval '5 minutes' → 3
# ✅ Парсер работает, данные пишутся

Кому нужно:

  • Команды без выделенного DevOps (разработчик = и DevOps тоже)
  • Стартапы где один человек и код пишет, и сервер чинит
  • Проекты с Docker-инфраструктурой на VPS
  • Инцидент-менеджмент: быстрая диагностика в стрессовой ситуации

Когда НЕ нужно: есть выделенный DevOps/SRE, managed infrastructure (Vercel, Railway, Heroku), или нет SSH-доступа.

Полезные MCP-серверы — сводная таблица

MCP-сервер Назначение Установка Приоритет
Context7 Актуальная документация библиотек claude mcp add context7 -- npx -y @upstash/context7-mcp@latest 🔴 Всем
SSH Manager Управление серверами через SSH npm i -g mcp-ssh-manager 🟡 DevOps/бэкенд с серверами
PostgreSQL Прямой доступ к БД npx -y @modelcontextprotocol/server-postgres 🟡 Проекты с PostgreSQL
Playwright Управление браузером, скриншоты, тесты claude mcp add playwright -- npx @anthropic/mcp-playwright 🟡 Фронтенд, e2e тесты
GitHub PR, issues, actions из агента Встроен в Claude Code 🟢 Командная разработка

Полный каталог MCP-серверов: https://github.com/modelcontextprotocol/servers

21. 🟡 Iterative Self-Refinement — автономное улучшение кода за ночь

Зачем: Запустить агента в цикл: анализ → поиск проблемы → исправление → повтор. За 30-50 итераций агент находит и исправляет то, что человек не заметил бы за неделю ручного ревью. Каждая итерация агент смотрит на код "свежими глазами" и замечает новое.

Принцип: человек после 2-й итерации устаёт и перестаёт замечать. Агент не устаёт — на 40-й итерации он так же внимателен как на 1-й.

Как внедрить:

Способ 1 — через /loop:

/loop 50 "Проанализируй код проекта. Найди одну проблему (баг, дубликат, 
          неоптимальность, нарушение конвенций). Исправь. 
          Запиши в ITERATIONS.md: что нашёл, что исправил, почему."

Способ 2 — через Stop hook (агент не останавливается пока есть что улучшать):

// .claude/settings.json
{
  "hooks": {
    "Stop": [{
      "command": "echo 'Продолжай. Найди ещё одну проблему и исправь.'",
      "timeout": 5000
    }]
  }
}

Способ 3 — через bash-скрипт (максимальный контроль):

#!/bin/bash
# overnight-refactor.sh
git checkout -b refactor/overnight-$(date +%Y%m%d)
git commit -am "checkpoint: before overnight refactoring"

for i in $(seq 1 50); do
  echo "=== Итерация $i/50 ==="
  claude -p "Итерация $i/50. 
    1. Проанализируй весь проект
    2. Найди ОДНУ конкретную проблему (баг, дубликат, мёртвый код, 
       неоптимальный запрос, нарушение DRY/SOLID)
    3. Исправь её
    4. Добавь запись в ITERATIONS.md: номер, что было, что стало, почему
    5. Если проблем не осталось — напиши 'DONE' и остановись"
  
  git add -A && git commit -m "refactor: iteration $i"
  
  # Остановиться если агент сказал DONE
  grep -q "DONE" ITERATIONS.md && break
done
echo "Готово. Посмотри git log и ITERATIONS.md"

📌 Пример из жизни

Ситуация: У тебя Python-бэкенд на 15k строк. Код писали 3 разных разработчика за 2 года. Стиль разный, дубликаты, устаревшие паттерны, неоптимальные SQL-запросы. Рефакторить вручную — неделя. Ты запускаешь скрипт перед сном.

Итерация 1-5: очевидное

#1: Удалил 3 неиспользуемых импорта в parsers/olx.py
#2: Заменил print() на logger.info() в 7 местах
#3: Убрал дублированную функция format_price() — была в utils.py и helpers.py
#4: Добавил timeout к requests.get() в 4 файлах (было без таймаута)
#5: Заменил bare except: на except requests.RequestException: в 6 местах

Итерация 10-20: паттерны

#12: Вынес повторяющуюся логику retry в декоратор @with_retry(max=3, backoff=2)
#15: Заменил 8 одинаковых блоков подключения к Redis на connection pool
#18: Нашёл N+1 запрос в API endpoint /properties — заменил на JOIN

Итерация 30-50: глубокие улучшения

#33: Объединил 3 похожих парсера (OLX, DOM.RIA, Lun) в абстрактный базовый класс
#41: Нашёл race condition в очереди рассылок — добавил Redis lock
#47: Оптимизировал bulk insert: вместо 1000 отдельных INSERT — один COPY
#50: DONE — критических проблем не осталось

Утром:

git log --oneline  # 47 коммитов с описанием каждого изменения
cat ITERATIONS.md  # полный отчёт что и почему
git diff main      # весь diff для ревью

Результат: код стал чище, быстрее, безопаснее. Каждое изменение задокументировано. Можно откатить любую итерацию отдельно.

⚠️ Обязательные меры безопасности:

Что Зачем
git commit перед запуском Откат если всё сломалось
Отдельная ветка Не трогать main
Коммит каждой итерации Откат конкретного изменения
Тесты после (если есть) Убедиться что ничего не сломано
ITERATIONS.md Отчёт для ревью утром
Лимит итераций Не бесконечно — 30-50 достаточно

⚠️ Расход токенов: 50 итераций на проекте 15k строк ≈ серьёзный расход. Считай бюджет заранее.

Кому нужно:

  • Legacy-код который давно не рефакторили
  • Проекты после нескольких разработчиков с разным стилем
  • Подготовка кода к ревью или аудиту
  • "Выжать максимум" из кодовой базы перед релизом

Когда НЕ нужно:

  • Свежий, чистый код — агент не найдёт что улучшать после 5-й итерации
  • Код без тестов и без возможности проверить — рискованно
  • Когда бюджет на токены ограничен

22. Официальные ресурсы

Ресурс Ссылка
CHANGELOG (v2.1.78) https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
Hooks https://code.claude.com/docs/en/hooks
Sub-agents https://code.claude.com/docs/en/sub-agents
CLI Reference https://code.claude.com/docs/en/cli-reference
Chrome Extension https://code.claude.com/docs/en/chrome
Remote Control https://code.claude.com/docs/en/remote-control
Scheduled Tasks https://code.claude.com/docs/en/scheduled-tasks
MCP Servers https://github.com/modelcontextprotocol/servers
gstack https://github.com/garrytan/gstack
Biome no-type-assertion https://github.com/albertodeago/biome-plugin-no-type-assertion
Official Skills repo https://github.com/anthropics/skills
Awesome Harness Engineering https://github.com/walkinglabs/awesome-harness-engineering
Context7 https://github.com/upstash/context7
SSH Manager MCP https://github.com/bvisible/mcp-ssh-manager