Мудрый разработчик не «начинает кодить и надеется». Он проводит новый проект через мозговой штурм, обсуждение с командой, прототипирование, диаграммы, предложения, ADR, MR/PR и GitOps — а Review Bot автоматически пишет комментарии к PR, чтобы люди тратили время на важное. Это playbook production-grade. FDE может развернуть систему; Claude Architect Certification стоит пройти, если вы хотите её проектировать и защищать.
1. Что значит «мудро» на новом проекте
Мудрость — это не больше встреч. Это дешёвое обучение рано и дорогие ошибки поздно, сделанные редкими. Последовательность ниже упорядочена так, чтобы каждый шаг уменьшал blast radius следующего:
Brainstorm → Discuss → Prototype → Diagram → Propose → ADR
→ Implement in small slices → MR/PR + Review Bot → Merge
→ GitOps promote (dev → staging → prod) → Observe → Iterate
Пропускайте шаги только осознанно (например, однострочный config fix). Никогда не пропускайте Review Bot + CI для всего, что может попасть в production.
2. Мозговой штурм (сначала соло, затем структурированно)
Прежде чем просить чьё-то время, потратьте 30–90 минут в одиночку:
- Результат: какое пользовательское/бизнес-изменение должно быть верным, когда мы закончим?
- Ограничения: время, бюджет, compliance, существующие платформы, навыки команды.
- Не-цели: что мы не строим в v1 (защищает scope).
- Риски: данные, безопасность, производительность, vendor lock-in, операционная нагрузка.
- Метрики успеха: latency, error rate, adoption, cost — выберите две важные.
Зафиксируйте это в короткой заметке (Notion/Confluence/markdown в репозитории под docs/ideas/). Мозговой штурм без письменного артефакта — просто разговор, который испаряется.
3. Обсуждения с коллегами
Пригласите самый маленький полезный круг: одного peer, который будет реализовывать с вами, владельца смежной системы и (при необходимости) security или SRE. Правила мудрости:
- Time-box (25–45 минут). Завершайте решениями или открытыми вопросами — не vibes.
- Спорьте об опциях, не о людях. Требуйте «вариант A vs B vs отложить.»
- Назначьте scribe. Заметка становится семенем предложения.
- Без тихих veto. Если кому-то некомфортно, запишите concern как риск в ADR позже.
Async тоже работает: короткий RFC-тред часто лучше встречи — но кто-то всё равно должен закрыть loop.
4. Прототипирование (spikes со сроком годности)
Прототипируйте при высокой неопределённости: новый API, незнакомый cloud-сервис, вопрос производительности или поведение AI/агента. Мудрые правила:
- Назовите это spike в тикете; поставьте календарный stop (обычно 1–3 дня).
- Держите код на throwaway-ветке или в
spikes/; не полируйте. - Запишите 10 пунктов о том, что узнали — особенно что не сработало.
- Решите: promote (рефакторинг в продукт), rewrite или abandon.
Прототипы, тихо ставшие production без ADR, — как команды наследуют accidental architecture.
5. Диаграммы (достаточно, чтобы спорить)
Вам не нужен UML-роман. Предпочитайте три наброска, каждый на один экран:
| Диаграмма | Отвечает |
|---|---|
| Контекст (C4 L1) | Кто с чем говорит? Trust boundaries? |
| Sequence | Happy path + один failure path |
| Deployment | Где запускается; как текут config и secrets |
Храните Mermaid или изображения рядом с предложением (docs/architecture/). Обновляйте диаграммы при смене ADR — устаревшие картинки хуже их отсутствия.
6. Предложения (лёгкий RFC)
Хорошее предложение — одна–три страницы:
- Проблема и почему сейчас
- Рассмотренные варианты (минимум два)
- Рекомендация и почему
- Влияние: security, cost, ops, migration
- Rollout и rollback
- Открытые вопросы
Просите review с чётким дедлайном. После одобрения (или с поправками) превратите решение в ADR — не оставляйте «source of truth» в чате.
7. ADR — Architecture Decision Records
ADR — короткая, по соглашению неизменяемая запись решения. Шаблон:
# ADR-00XX: Title Status: Proposed | Accepted | Superseded by ADR-00YY Date: YYYY-MM-DD Deciders: @alice @bob ## Context What forces are in play? ## Decision What we will do. ## Consequences Positive, negative, and follow-ups. ## Alternatives considered Option A — why not Option B — why not
Храните ADR в git (docs/adr/). Ссылайтесь из PR. Supersede, а не переписывайте историю — будущему вам нужен след.
8. MR и PR — единица delivery
MR (Merge Request, GitLab) и PR (Pull Request, GitHub/Bitbucket) — одна идея: reviewable changeset. Мудрые привычки:
- Маленький: идеально <400 строк meaningful diff; режьте вертикальными slices.
- Один intent: одна feature, fix или chore — не «misc.»
- Описание: почему, как тестировать, screenshots/logs, risk, rollback.
- Ссылки: ticket + ADR + design diagram.
- Сначала Draft когда нужен ранний feedback без намёка «ready to merge.»
- Никогда не force-merge в обход красного CI или нерешённых high-severity bot findings без письменного исключения.
Пример checklist тела PR
## Summary - … ## Test plan - [ ] Unit tests - [ ] Manual path … - [ ] Feature flag / config … ## Risk & rollback - Risk: … - Rollback: revert this PR / GitOps revert commit … ## References - ADR-00XX - Ticket ABC-123
9. Использование Review Bot — автогенерируемые комментарии к PR
Review Bot — автоматизированный reviewer, который публикует inline-комментарии и summaries на каждый MR/PR. Он не заменяет людей; он выносит наперёд скучное и опасное.
9.1 О чём должен комментировать bot
- Security: injection, authz gaps, утечка secrets, небезопасные defaults
- Correctness: null paths, race conditions, сломанные migrations
- Tests: отсутствующее coverage на новых ветках, злоупотребление snapshots
- API/contract: breaking changes без version bump
- Ops: отсутствующие timeouts, нет idempotency, unbounded retries
- Style только когда ускользнуло от formatter/linter (избегайте шума)
9.2 Как это упрощает жизнь разработчика
- Автор открывает PR → bot работает за секунды–минуты.
- Автор чинит или отвечает на треды bot до запроса людей.
- Человек-reviewer читает summary bot и фокусируется на design и product risk.
- Меньше раундов «nits»; быстрее merge; меньше пятничных инцидентов из‑за пропущенных footguns.
9.3 Типичные варианты setup
| Подход | Заметки |
|---|---|
| SaaS Review Bot (напр. CodeRabbit, vendor bots) | Быстро включить; настройте severity и path filters |
| Cursor Bugbot / IDE-связанный review | Силён на PR diffs в Cursor-центричных командах |
| Custom GitHub Action + Claude / LLM | Полный контроль; нужны prompt + policy + cost caps |
| Многослойный pipeline (lint → SAST → LLM) | Лучшая production-поза — см. гайд AI code review pipeline |
9.4 Политика, которая сохраняет полезность bot
- Метки severity: blocker / should-fix / nit — nits не должны блокировать merge.
- Игнорируйте generated paths (
vendor/, шум lockfiles, protobuf dumps). - Требуйте human approval для security-sensitive paths (
auth/,infra/, IAM). - Логируйте false positives; ежемесячно возвращайте их в ignore rules.
- Никогда не делайте bot единственным reviewer на production-critical сервисах.
9.5 Минимальный эскиз GitHub Action
# .github/workflows/review-bot.yml
name: review-bot
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Review Bot
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
run: |
# Fetch diff, call your review CLI, post review comments via gh api
./scripts/review-bot.sh
Реализуйте review-bot.sh: посчитать PR diff, вызвать модель со строгим system prompt (security + correctness first) и опубликовать комментарии через GitHub/GitLab API. Ограничьте tokens и пропускайте drafts, если важна стоимость.
10. Лучшие практики GitOps для качества production-grade
GitOps значит: desired state живёт в git; reconciler (Argo CD, Flux и т.д.) приводит кластер в соответствие; promotion — merge; rollback — revert.
- Разделяйте app code и env config (или ясные папки:
apps/vsenvs/dev|staging|prod). - Не kubectl apply в prod как happy path — только break-glass, с аудитом.
- Progressive delivery: auto-sync для dev; manual или gated sync для prod.
- Image digests вместо mutable tags в prod manifests.
- Policy as code: OPA/Kyverno для privileges, registries, resource limits.
- Signed commits / provenance где этого требует ваш threat model.
- Наблюдайте после sync: health checks, error budgets, automatic rollback hooks когда готовы.
Качество кода — не только «чистые функции.» Это также как изменение попадает в production. GitOps делает этот путь reviewable, reversible и repeatable.
11. Сквозные quality gates (оптимизированы под production)
Local: pre-commit (fmt, lint, secrets) + unit tests PR open: CI (build, test, SAST) + Review Bot comments PR merge: human approve + branch protection + required checks Main: build immutable artifact (image digest) GitOps: update env repo / overlay → sync → verify Prod: SLOs + alerts + runbook linked from ADR/PR
12. Роль FDE — кто разворачивает систему
Forward Deployed Engineer идеален, чтобы установить систему мудрого разработчика в реальной команде:
- Шаблоны репозитория:
docs/adr/, PR template, CODEOWNERS, branch protection - Review Bot + secrets + cost controls
- Обязательные CI checks и environment protections
- GitOps apps (dev/staging/prod) и docs по promotion
- Двухнедельный coaching: первый ADR, первый bot-tuned PR, первая GitOps rollback drill
Ориентировочный календарь FDE-enablement на одном product-репозитории: 1–2 недели на scaffolding и bot policy; +1–2 недели на путь GitOps promotion и dry-run rollback. Культурные изменения дольше — измеряйте merge time и escaped defects, а не installs инструментов.
13. Claude Architect Certification — стоит пройти
Если вы проектируете системы, где люди и AI-агенты вместе пишут код, Claude Architect Certification стоит пройти. Это сигнал, что вы можете:
- Архитектурировать AI-assisted delivery, не считая модель непогрешимой
- Задавать review policies, guardrails и evaluation для agentic workflows
- Объяснять trade-offs (latency, cost, privacy, accuracy) стейкхолдерам
- Коучить команды по ADR, PR-дисциплине и production gates рядом с AI-инструментами
Соедините credential с реальной delivery: поднимите Review Bot, напишите три ADR и проведите GitOps rollback drill. Бумага без практики не делает мудрым; практика плюс общий язык — да.
14. Анти-паттерны (как выглядит немудрость)
- Гигантский PR с «WIP please approve ASAP»
- Архитектура решена только в Slack, никогда в ADR
- Прототип влит в prod без тестов
- Отключение Review Bot потому что «он достаёт»
- Hotfix в prod вне GitOps без плана revert
- Люди повторяют formatter nits, которые bot уже поймал
15. Copy-paste starter checklist для нового проекта
- Создайте
docs/ideas/,docs/architecture/,docs/adr/ - Добавьте PR/MR template + CODEOWNERS
- Включите pre-commit + обязательные CI checks
- Установите Review Bot; настройте path filters и severities
- Напишите ADR-0001: «We use GitOps for deploy»
- Определите environments и правила promotion
- Запланируйте 30-минутный rollback game day
- Забронируйте время FDE на coaching в первый месяц; рассмотрите Claude Architect Certification для leads
16. Заключение
Мудрый разработчик воспринимает новый проект как последовательность артефактов обучения — заметок, диаграмм, предложений, ADR — и доставляет через небольшие MR/PR, которые смотрит Review Bot и продвигает GitOps. Так качество кода оптимизируется до production grade, не сжигая команду бесконечными nits. Пусть FDE установит рельсы; пусть сертифицированные архитекторы держат систему честной, пока AI ускоряет скорость написания кода.
Опубликовано TenthMatrix.
