Dev Workflow

dev-workflow — правила разработки кода

Скилл применяется ко всем проектам Jared, где пишем код. Для продакт-задач (Notion, Jira, Confluence, тексты, оформление гипотез) не применяется — там работаем как раньше, без церемоний.

Core invariant — BL status transitions (ВСЕГДА)

Это правило выполняется на каждой задаче из бэклога, без исключений. Не часть pre-flight (тот про сессию целиком) — это про каждый BL отдельно.

При взятии BL в работу (перед первым изменением файла / Edit / Write / Bash-action, относящимся к задаче):

1. Прочитать BL целиком (frontmatter + Context + DoD).
2. Отметить status: in_progress в frontmatter BL-файла.
3. Добавить (если нет) claimed_by: @ и claimed_at: .

При закрытии BL (после того как DoD выполнен и изменения закоммичены):

1. Отметить status: done.
2. Добавить closed: .
3. Заполнить секцию ## Done или ## Progress с итогом (что сделано,

commits / PR).

Worktree caveat: если работаешь из .claude/worktrees//, BL-файлы живут в main checkout (private/backlog/). Используй python3 или sed через Bash с absolute path к main checkout — Edit/Write упадут из-за worktree-path хука. Детали в секции «Алгоритм завершения BL» ниже.

Failure mode: если начал работу над BL без отметки in_progress — ты нарушил invariant. Сразу остановись, проставь статус, продолжай. Запрещено: «допишу статус в конце», «отмечу при закрытии». Транзишн planned/open → in_progress происходит до первого изменения, не после.

Этот invariant обязателен потому что:

• Параллельные сессии без видимого in_progress приводят к дубликату работы.
• Закрытие BL без done — пропадает audit-trail, BL остаётся в planned

навсегда.

• Эту дисциплину невозможно обеспечить hook'ом (нет надёжного триггера

«начало работы по BL-N»), поэтому она в скилле как правило для LLM.

Pre-flight (перед Шагом 0) — branch + backlog audit

Адресует два класса повторяющихся проблем:

1. Stale-branch trap: запуск команды со ветки, отстающей от main,

даёт wrong результат → диагностируется как баг в коде → часы на ложный фикс. Реальный кейс 2026-05-17 в ai-job-searcher: feat/reclassify-imap-bl44 отставала на 4 коммита (RFC 030), bridge- роли wrongly Weak'нулись (BL-67 / BL-68).

1. Параллельные сессии + общий бэклог: Jared часто работает в 2-3

сессиях одновременно. Между ними меняется private/backlog/ и состояние веток. Если новая BL берётся без re-read'а — риск дублирующей работы или conflict'ов.

Когда запускать

| Момент | Branch audit | Backlog audit | |---|---|---| | Первое касание dev-репо в сессии | ✅ обязательно | ✅ обязательно | | Между задачами в одной сессии (закрыл BL, иду за следующей) | ✅ обязательно | ✅ обязательно | | Перед merge / push / большой prep-командой (prepare, миграция) | ✅ обязательно | — | | На каждое сообщение | ❌ нет | ❌ нет |

A) Branch audit

git rev-parse --abbrev-ref HEAD                   # current branch
git status -sb                                     # tree state + ahead/behind tracking
git fetch origin main --quiet
git rev-list --count HEAD..origin/main             # # of commits behind main
git log --oneline HEAD..origin/main | head -10     # what's in those commits
git worktree list                                   # other active worktrees
gh pr list --state open --json number,title,headRefName,baseRefName 2>/dev/null

Когда докладывать юзеру (обязательный отчёт):

• Ветка отстаёт от main на >0 коммитов → одно сообщение: какая ветка,

на сколько, что в недостающих коммитах (короткими описаниями), и предложить путь (merge main / rebase / switch to main). Не начинать основную работу до согласования стратегии.

• Working tree содержит правки в файлах, которые меняет open PR →

упомянуть возможный дубликат работы.

• Несколько активных worktree'ев → перечислить.
• Всё чисто, ветка up-to-date → одной строкой `branch: ,

in sync with main`.

B) Backlog audit

ls -lt private/backlog/*.md | head -15                              # what changed recently
grep -l "^status: in_progress" private/backlog/*.md 2>/dev/null      # active claims
grep -A1 "^status: in_progress" private/backlog/*.md 2>/dev/null     # who claimed

Worktree caveat (важно). private/ gitignored — он живёт только в main checkout, не реплицируется в .claude/worktrees//. Если cwd — это worktree (см. git rev-parse --show-toplevel против git worktree list), то ls private/ вернёт "No such file" — это не значит, что BL'ов нет.

Правильное действие:

# Определить main checkout (первая строка `git worktree list` — main)
MAIN=$(git worktree list | head -1 | awk '{print $1}')
ls -lt "$MAIN"/private/backlog/*.md | head -15
grep -l "^status: in_progress" "$MAIN"/private/backlog/*.md 2>/dev/null

Или гонять команды из main checkout напрямую через absolute path. Тот же caveat применяется к закрытию BL — см. «Алгоритм завершения BL» ниже.

Когда докладывать юзеру:

• BL'ы изменены за последние ~60 минут не моей сессией → перечислить

(другая сессия что-то сделала — стоит понять что, прежде чем планировать).

• BL status: in_progress с claimed_by != моя сессия → flag в отчёте:

«BL-X занята сессией @, не беру».

• BL status: in_progress с claimed_at > 24h ago без активности →

возможен stale claim, спросить юзера сбросить ли.

C) Claim mechanism (при взятии новой BL)

Identity сессии: @, например feat/reclassify-imap-bl44@18:10. Простой формат, человекочитаемый. Branch уникален per-worktree, время отличает разные сессии на одной ветке.

Алгоритм взятия BL:

1. Прочитать BL целиком (включая Plan, DoD, refs).
2. Грепнуть ^claimed_by: в BL — если уже claimed другой сессией и

claimed_at свежий → не брать, спросить юзера.

1. Если free — отредактировать frontmatter BL:

``yaml status: in_progress claimed_by: @ claimed_at: ``

1. Если frontmatter ранее не содержал этих полей — добавить их.
2. Только после этого начинать первое действие по задаче.

Алгоритм завершения BL:

1. status: in_progress → done.
2. Добавить closed: .
3. claimed_by оставить (полезно для истории/debug — кто закрыл).
4. Заполнить ## Progress итогом: что сделано, ссылки на commits / PR.

Worktree caveat при закрытии. Если работаешь из .claude/worktrees//, файл private/backlog/BL-NN.md физически лежит в main checkout, не в worktree. Поэтому:

• Edit/Write по worktree-relative пути либо упадёт с "file not found",

либо (если хук check_worktree_path.sh настроен) заблокируется при попытке Edit'ить absolute path в main.

• Делать через Bash с absolute path: sed -i '' для замены статуса /

cat >> "$MAIN/private/backlog/BL-NN.md" для дописки Progress. Хук не трогает Bash, а файл gitignored — это не часть PR, обычное housekeeping.

• Альтернатива — переключить cwd в main checkout, но обычно избыточно

ради одного файла.

Не пропускать закрытие, увидев "no private/" в worktree — это гарантированная ошибка, а не отсутствие BL.

Если задача abandon'ится посреди работы:

• status: in_progress → open.
• Удалить claimed_by и claimed_at (либо переписать в last_claimed_by

если хочется audit-trail).

• Дописать в ## Progress: почему abandon, что успели.

Анти-паттерны

• Молча начать работу с непроверенной ветки.
• Взять BL без claim → другие параллельные сессии не увидят что она

занята → дубликат работы.

• Между задачами полагаться на in-memory кэш бэклога. Между BL'ами

re-read обязателен, особенно если сессия идёт >1 часа.

• При неожиданном результате (prepare wrong, `test fails по

необъяснимой причине`, «фича не работает хотя точно сделана») первая мысль — диагностировать код. Должно быть наоборот: first thought — проверить свежесть ветки и состояние бэклога.

Когда не запускать

• Сессия про продакт-задачу (Notion, Jira, тексты, гипотезы) — dev-workflow

не применяется в принципе.

• Папка без .git/ — branch audit пропускается, backlog audit остаётся

если есть private/backlog/.

• Чисто read-only лукапы по коду — необязательно, но желательно при

первом обращении к репо в сессии.

Cost

~10 команд, ~3 секунды, ~500 токенов. Окупается одним предотвращённым phantom-багом или одним предотвращённым дубликатом работы между сессиями.

Шаг 0 — классификация

В начале задачи Claude определяет тир. Если неочевидно — называет предполагаемый тир и спрашивает пользователя, согласен ли он.

| Тир | Триггер | Процесс | |---|---|---| | XS | 7) — пускаются волнами, чтобы не топить контекст PM.

• Если стоимость токенов критична — PM явно предупреждает: «4 агента

фоном — примерно в N раз дороже последовательного режима, но быстрее. Идём?». Решает пользователь.

Чего PM-Claude НЕ делегирует

Чтобы режим не выродился в «Claude нажимает кнопки», PM сохраняет ownership на:

• Образ результата всей задачи. Юниты — это раздробленный продукт,

но продукт всё ещё в голове PM.

• Декомпозицию и интерфейсные контракты. Архитектура и границы

юнитов — это PM, не агенты.

• Финальную интеграцию и DOD-проверку. Сборка, кросс-юнитный

smoke, ревью собранного диффа.

• Решение «параллелим или нет». Гейт остаётся явным.
• Коммуникацию с пользователем. Агенты не пишут пользователю

напрямую — всё через PM.

Агенты — это руки. Голова и продукт — PM.

Антипаттерны

• «Распараллелим всё». Если юниты не независимы — overhead съест

выигрыш. PM обязан честно говорить «не разлепляется».

• «PM пишет код сам, потому что агент тупит». Это нарушение роли.

Либо переоткрытие юнита, либо честный возврат к последовательному режиму. Микс ломает ответственность.

• «Контракт согласован агентами между собой». Никогда. Контракт —

только PM. Если агенты «договариваются» — это значит, PM забыл зафиксировать формат, и юниты разъедутся.

• «Запустили и забыли». PM обязан проверить каждый возвращённый

юнит против его «что увидит пользователь», не просто принять «done» от агента.

Шаг 1 — RFC (только M/L)

Короткий дизайн-док в PROJECT/rfc/NNN-title.md ДО кода.

## Проблема
Что не работает / чего не хватает. 1–2 предложения.

## Варианты
- A: ...
- B: ...

## Выбрано + почему
Вариант X, потому что ...

## Identity & PII (обязательно, если фича касается user data)
- ID: формат, источник random (criteria по `feedback_pii_random_ids.md`).
- PII-поля: что считается PII, как помечены в schema (`pii_class`).
- Хранение: где живут (gitignored / encrypted), как gitnoring устроен.
- Логирование: что НЕ должно попасть в логи; redaction policy.
- Удаление: hard delete возможен? Как реализуется right-to-be-forgotten?
- Multi-user-ready: всё ли scope'ится по profile? Что меняется при SaaS-пивоте?
- Если фича не работает с user data — пишем «N/A — фича не касается user data».

## Риски / что может сломаться
- ...

## План проверки
Как поймём, что работает (тесты, ручной сценарий, метрика).

Claude пишет RFC и ЖДЁТ явного approve от пользователя перед кодом. Для XS — RFC не нужен.

Identity & PII секция в RFC обязательна для всех M/L фич. Даже если ответ «N/A» — это явное решение, зафиксированное. Полные правила — в ~/.claude/skills/scaffold-project/SKILL.md секция «Identity & PII rules», или в memory feedback_pii_random_ids.md.

Шаг 2 — код + тесты

Стек тестов:

| Язык | Фреймворк | Запуск | |---|---|---| | JavaScript / Node | node --test (встроено в Node 20+) | node --test в корне проекта | | Python | pytest | pip install pytest && pytest |

Файлы тестов лежат рядом с кодом: parser.js → parser.test.js, loader.py → test_loader.py.

Testing pyramid:

• Юнит — чистая логика без сети/диска. Пишем много.
• Интеграционные — внешние API (MCP, Superset, Jira, Notion). Моки сети, не реальные запросы — иначе флак и квоты.
• E2E / ручная — только для критичных прод-сценариев. Описываем чеклистом в RFC, не автоматизируем преждевременно.

Smoke-тест обязателен даже для XS — один простейший тест, доказывающий, что основная функция вызывается, не падает, возвращает ожидаемый тип. Ловит 80% поломок рефакторинга за 2 минуты работы.

Шаг 3 — линтеры (только где есть нетривиальный код)

Ставим по мере необходимости, локально в подпроект.

| Язык | Инструмент | Конфиг | |---|---|---| | JavaScript | prettier + eslint (@eslint/js recommended) | минимальный, zero-config | | Python | ruff (lint + format в одном) | zero-config |

Для bash-скриптов и одноразовых утилит — проверяем глазами, линтер не нужен.

Шаг 4 — pre-commit hook

Появляется только когда в подпроекте есть тесты или линтеры. До этого — живём без хука.

Когда будет что гонять:

1. Скрипт в .githooks/pre-commit (коммитим в репо, чтобы пережил сессии).
2. git config core.hooksPath .githooks локально.
3. Первая версия — warning-only: прогоняет тесты + линтер для изменённых

файлов, печатает результат, НЕ блокирует коммит. Когда привыкнем — переключаем в блокирующий режим.

Отдельно: секрет-guard pre-commit hook добавляем при подготовке к публикации в паблик-репо — блокирует Notion tokens, Google OAuth secrets, private keys, AWS keys, имя/email автора.

Шаг 5 — мульти-агентное ревью

Тир M

После кода — субагент (general-purpose с фокус-промптом) получает diff. Фокус:

• Читаемость и именование.
• Edge cases, которые могли забыть.
• Простота — нет over-engineering, абстракций «на вырост».
• Соответствие DOD.
• Secrets / hardcoded credentials.

Критичные findings Claude исправляет сам. Остальное — summary пользователю.

Тир L

Дополнительно:

• /security-review — уязвимости (injection, XSS, утечки, auth),

секреты, небезопасные дефолты.

• /review — общий PR-review с точки зрения качества изменений.
• Для публичных фич — UX edge cases (пустые состояния, ошибки, обрывы сети).

Финальный approve — всегда у пользователя

Claude не коммитит код без ok (для M/L). Для XS — показывает diff и коммитит, если пользователь заранее дал зелёный свет.

Commit и push — атомарно (2026-05-17)

После каждого git commit Claude сразу же делает git push без отдельного вопроса. Локальное состояние и GitHub синхронизируются автоматически. См. правило в проектном CLAUDE.md → раздел «Git push».

Исключения (НЕ пушим автоматически):

• pre-commit hook упал или тесты красные → сначала фиксим;
• коммит в WIP-состоянии (явно отмечен как промежуточный);
• force push в чужую ветку или main/master → требует явного approve.

Если ветки нет в origin — git push -u origin (set upstream) автоматически.

Шаг 6 — уровни безопасности (S1/S2/S3)

Безопасность масштабируется инкрементально.

| Уровень | Триггер | Что подключаем | |---|---|---| | S1 — базовый | локальные скрипты, MCP, личные тулы | /security-review для L-тира, secret-detection в code-review, npm audit / pip-audit перед коммитом новых зависимостей, «секреты не в репо» | | S2 — pre-prod | SaaS готов к внешнему доступу, появился auth / БД с данными | threat modeling в RFC для фич с auth + данными, SAST (semgrep), OWASP Top 10 чеклист, проверка secrets в CI, auto dependency scanning | | S3 — prod с пользователями | публичный SaaS, реальные пользователи | pentest-агент против staging, регулярные прогоны перед релизом, внешний аудит перед платными клиентами / чужими данными / платежами |

Дефолт по репо — S1. Переход на S2 — когда появляется первый подпроект с auth или публичным URL.

Pentest-агент (S3, план на будущее)

Запускается против staging-инстанса (не против кода, не против prod). Процесс: subagent получает URL + тестовые креды + HTTP/browser тулы → идёт по OWASP Top 10 чеклисту (auth bypass, injection, XSS, IDOR, CSRF, SSRF, rate limiting, secrets exposure, broken access control) → каждую попытку логирует payload → response → classification → возвращает отчёт по severity. Critical/high — блокеры релиза. Medium/low — в бэклог с дедлайном.

НЕ заменяет: внешний профпентест перед платным продуктом, bug bount

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ymuromcev
• Source: ymuromcev/claude-dev-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.