05 / 06 · Best Practices

🏛️ Hrishi Olickel

CTO и AI-researcher специализирующийся на внедрении AI в инженерные команды. Его ключевой тезис: CC меняет роль senior-разработчика и архитектора — не junior-а. Инструмент усиливает экспертизу, а не заменяет её.

🏛️

Hrishi Olickel

CTO, AI Researcher, Engineering Teams

@hrishioa

⚠️

Частая ошибка команд: дают junior-разработчикам CC без архитектурных ограничений и надеются что CC «всё сделает правильно». CC действительно напишет рабочий код — но без ADR (Architectural Decision Records) или CLAUDE.md с паттернами проекта этот код будет нарушать принятые соглашения и создавать технический долг. Hrishi Olickel's правило: CC усиливает того кто знает архитектуру. Junior не знает — значит CC умножит его незнание. Сначала архитектурный контекст, потом делегирование.

🏛️ Ключевой принцип

"CC меняет роль архитектора, не junior-разработчика." Senior с CC становится в 10 раз продуктивнее. Junior с CC может случайно сломать production в 10 раз быстрее — потому что не знает что ревьювить. Понимание зачем важнее умения промптить.

💡

Тонкость для опытных: ADR в системе Hrishi Olickel — это не просто документация, это «контракт» который CC должен соблюдать. Когда CC предлагает решение которое нарушает ADR, это не ошибка CC — это сигнал что либо ADR не попал в контекст, либо ADR устарел. Поэтому Hrishi рекомендует явно ссылаться на ADR в промпте: «Реализуй X, соблюдая ADR-007 о сервисном слое». Тогда любое отклонение CC — повод пересмотреть либо промпт, либо сам ADR.

"Architecture First" методология — ADR как входные данные

Самая распространённая ошибка при внедрении CC в команде — дать junior-разработчику CC и задачу без архитектурных ограничений. CC напишет рабочий код — но он будет противоречить архитектуре проекта, нарушать принятые паттерны и создавать технический долг.

Olickel внедрил практику ADR (Architectural Decision Record) как обязательный входной контекст для CC:

"Перед тем как CC начнёт писать код — архитектор (или senior) должен задать ограничения. ADR — это не документация для людей. Это инструкция для CC."

# docs/adr/ADR-007-payment-service-design.md

## Контекст
Реализуем поддержку нескольких платёжных провайдеров (Stripe, YooKassa).
Текущая архитектура: Laravel + сервисный слой, DI через IoC container.

## Решение
Использовать Strategy pattern через PHP интерфейс `PaymentProviderInterface`.

## Ограничения которые ДОЛЖНЫ соблюдаться CC:
- Интерфейс клиента (`PaymentService`) не должен меняться
- Все провайдеры через DI — никаких new Provider() в бизнес-логике
- Retry logic — в Service, не в Provider
- Все деньги в копейках (integer) — не float никогда
- Логирование через Laravel Log facade — не echo/var_dump

## Что НЕ в скоупе:
- Webhook handling (отдельный ADR)
- Refund flow (следующий спринт)

## Промпт для CC:
"Реализуй PaymentService используя ADR-007.
 Файл ADR: @docs/adr/ADR-007-payment-service-design.md
 Существующий код: @app/Services/PaymentService.php
 Соблюдай все ограничения из раздела 'Ограничения'."

Почему ADR перед кодом, а не после

CC оптимизирует под локальную задачу. Без глобальных ограничений он сделает лучшее локальное решение — которое может быть плохим глобальным решением. ADR даёт CC глобальный контекст и превращает "напиши код" в "напиши код в этих ограничениях".

"CC как amplifier, not replacement" — усилитель экспертизы

Olickel провёл наблюдение в нескольких командах: результат внедрения CC зависит от уровня разработчика нелинейно.

Senior + CC = 10x Senior

Знает что ревьювить. Видит когда CC нарушает архитектуру. Формулирует точные ограничения. Использует CC для boilerplate, сам делает архитектурные решения. Выходит код высокого уровня.

Junior + CC = Риск

Не знает что именно проверять в коде CC. Принимает working code = правильный code. Не видит нарушений архитектуры. Скорость растёт, качество падает. Технический долг накапливается незаметно.

Рекомендация Olickel для найма и онбординга:

# Политика использования CC в команде (Hrishi Olickel подход)

## Junior (0-6 месяцев в проекте)
- Первые 3 месяца: CC только для справки, не для генерации кода
  Причина: нужно сформировать понимание кодовой базы
- Месяцы 3-6: CC для boilerplate с обязательным ревью senior
  Каждый CC-PR требует отметку "CC-assisted: reviewed by @senior"
- После 6 месяцев: стандартный workflow команды

## Middle (понимает архитектуру)
- Свободное использование CC для фич с ADR
- Самостоятельное ревью CC-кода разрешено
- Обязательно: ADR или архитектурное решение ПЕРЕД CC

## Senior / Architect
- Полная свобода в использовании CC
- Дополнительная обязанность: задавать ADR для команды
- Code review CC-assisted PRs junior/middle — обязательно

## Универсальное правило
- Security, payments, auth — всегда ревью senior независимо от уровня

"Context Window as Team Memory" — CLAUDE.md как стандарты команды

Системный промпт и CLAUDE.md — это не настройка для одного разработчика. В команде это закодированные стандарты разработки: паттерны, запреты, архитектурные решения которые актуальны для всей кодовой базы.

Olickel структурирует командный CLAUDE.md для команды из 8 инженеров следующим образом:

# CLAUDE.md — командные стандарты [обновлён: 2026-05-10]

## Стек
- Backend: Laravel 11 + PHP 8.3
- Frontend: Vue 3 + TypeScript (Composition API)
- БД: PostgreSQL 16 (через Eloquent ORM)
- Очереди: Redis + Laravel Horizon
- Тесты: Pest PHP

## Архитектурные решения (ADR-ссылки)
- Payments: ADR-007 (Strategy pattern, копейки, DI)
- Auth: ADR-003 (JWT + refresh tokens, НЕ sessions)
- API: ADR-012 (REST, snake_case, versioning через URL /api/v2/)
- Events: ADR-015 (Laravel Events, НЕ direct calls между сервисами)

## ЗАПРЕЩЕНО (не нарушай без явного обсуждения)
- float для денег — только integer (копейки)
- new Service() в контроллерах — только через DI
- dd(), var_dump(), echo — только через Log::
- raw SQL в контроллерах — только через Repository/QueryBuilder
- HTTP requests напрямую из моделей — только через сервисы

## Паттерны кодовой базы
- Валидация: FormRequest классы, НЕ в контроллерах
- Авторизация: Policy классы, НЕ inline if checks
- Ответы API: ApiResource классы, НЕ array returns
- Ошибки: кастомные Exception классы с кодами

## Именование
- Контроллеры: UserController (не UsersController)
- Сервисы: UserService (не UserManager, не UserHelper)
- Репозитории: UserRepository
- События: UserRegistered (past tense, НЕ RegisterUser)
- Jobs: SendWelcomeEmail (action + object)

## Тесты
- Feature тесты для каждого endpoint
- Unit тесты для Service методов с бизнес-логикой
- Фабрики для всех моделей
- database: RefreshDatabase или DatabaseTransactions

## Что делать при неуверенности
Если задача не покрыта этим файлом — спроси в #architecture канале
прежде чем реализовывать. Не угадывай — уточняй.

CLAUDE.md как living document

CLAUDE.md должен обновляться при каждом архитектурном решении команды. Это не "документация которую никто не читает" — это активно используемый контекст для каждой сессии CC. Olickel рекомендует делать его обновление частью PR review: "если это изменение устанавливает новый паттерн — обнови CLAUDE.md".

"Delegation Pyramid" — что делегировать CC, а что нет

Olickel построил чёткую иерархию делегирования на основе наблюдений за командами. Принцип: делегировать CC то что хорошо определено и обратимо. Оставлять людям то что требует контекста бизнеса или критично при ошибке.

Делегировать полностью

CC без детального ревью

Boilerplate-код (CRUD, миграции, фабрики)
Документация и комментарии к существующему коду
Тесты для уже работающей логики (но проверить граничные случаи)
Рефакторинг именования и форматирование
Типичные утилиты (валидаторы, форматтеры, хелперы)
Git commit messages и changelog

Делегировать с проверкой

CC + обязательное ревью

Новые фичи (проверить соответствие ADR)
API дизайн (проверить консистентность с существующим)
Рефакторинг существующей логики
Интеграции с внешними сервисами (проверить error handling)
Алгоритмически сложный код (проверить корректность)

НЕ делегировать

Только люди

Архитектурные решения (ADR создаёт human, CC реализует)
Security design — аутентификация, авторизация, шифрование
Core бизнес-логика с неявными требованиями
Решения о данных пользователей и privacy
Trade-off решения с бизнес-последствиями

"Спроси себя: если CC ошибётся здесь, насколько сложно это исправить? Если ответ 'сложно' или 'опасно' — это не для делегирования."

"Onboarding через CC" — погружение в кодовую базу

Когда новый разработчик приходит в команду, CC с правильным CLAUDE.md становится ментором по кодовой базе. Он знает все паттерны, все архитектурные решения, всю структуру — потому что это закодировано в контексте.

Серия промптов для онбординга нового разработчика:

# День 1: понимание структуры
"Объясни архитектуру этого проекта.
 Какие слои есть? Как они взаимодействуют?
 Покажи путь HTTP запроса от контроллера до ответа."

# День 2: понимание бизнес-доменов
"Какие основные бизнес-сущности в проекте?
 Как связаны User, Subscription, Payment?
 Где находится бизнес-логика для каждой?"

# День 3: паттерны и соглашения
"Покажи примеры из кода:
 1. Как правильно создать новый сервис
 2. Как добавить новый endpoint
 3. Как написать тест для сервиса
 4. Как обработать ошибку в API"

# День 4: найти все использования
"Найди все места где используется платёжная система.
 Покажи flow от создания платежа до webhook."

# День 5: первая задача
"Вот задача: [описание].
 Какие файлы нужно изменить?
 Какие паттерны использовать из CLAUDE.md?
 Есть ли похожая реализация в проекте для образца?"

CC как интерактивная документация

Традиционная документация устаревает. CC с актуальным CLAUDE.md и доступом к коду всегда даёт актуальный ответ. Новый разработчик может задать "глупый" вопрос CC без стеснения — и получить конкретный ответ со ссылкой на код проекта, а не на устаревший Wiki.

Метрики эффективности CC в команде

Olickel настаивает: внедрение CC должно измеряться, а не ощущаться. Без метрик невозможно понять работает ли инструмент или просто создаёт иллюзию продуктивности.

# Метрики которые Olickel отслеживает

## Скорость (позитив ожидаем)
- Cycle time: от задачи до merged PR
- PR size: количество строк изменений на фичу
- Time to first commit: сколько времени до первого кода

## Качество (следим за деградацией)
- Bug rate: баги в production на фичу/месяц
- PR rework rate: сколько раз PR переделывался до merge
- Test coverage delta: растёт или падает с CC
- Technical debt tickets: новые задачи в backlog на рефакторинг

## Архитектурное соответствие (ADR compliance)
- CC-assisted PRs нарушивших ADR (цель: 0)
- Время ревью CC-assisted PRs vs обычных
- Количество "это не по архитектуре" комментариев в ревью

## Красные флаги
- Рост coverage без роста качества тестов → CC пишет тесты под себя
- Падение rework rate + рост bug rate → принимаем не глядя
- Рост PR size → CC генерирует лишнее, не рефакторим