AGENT SKILL

dev-workflow

Правила производственного цикла разработки кода для всех проектов Jared. Тирует задачу (XS / M / L), требует RFC перед кодом для M/L, обязательный smoke-тест даже на XS, мульти-агентное ревью для M/L, `/security-review` для L и любых фич с auth/данными, инцидент-лог в blameless-режиме, DOD-чеклист перед отчётом. Уровни безопасности S1→S3 подключаются инкрементально. Применяется ТОЛЬКО к разработке кода — скрипты, приложения, MCP-серверы, SaaS. На продакт-задачи (Notion, Jira, Confluence, тексты, гипотезы) — не распространяется. Trigger when: новая задача на разработку кода, появляется /dev-workflow, "начинаем фичу", "новая фича", "напиши скрипт", "подними MCP", "рефакторинг", "миграция", "архитектурное изменение", "новый подпроект" — или когда пользователь спрашивает, какой тир у задачи.

License 许可
MIT
最近更新
2026-05-17
Stars
★ 2
Forks
0

01 前言 Front Matter

name
dev-workflow
license
MIT
version
0.1.0
description
Правила производственного цикла разработки кода для всех проектов Jared. Тирует задачу (XS / M / L), требует RFC перед кодом для M/L, обязательный smoke-тест даже на XS, мульти-агентное ревью для M/L, `/security-review` для L и любых фич с auth/данными, инцидент-лог в blameless-режиме, DOD-чеклист перед отчётом. Уровни безопасности S1→S3 подключаются инкрементально. Применяется ТОЛЬКО к разработке кода — скрипты, приложения, MCP-серверы, SaaS. На продакт-задачи (Notion, Jira, Confluence, тексты, гипотезы) — не распространяется. Trigger when: новая задача на разработку кода, появляется /dev-workflow, "начинаем фичу", "новая фича", "напиши скрипт", "подними MCP", "рефакторинг", "миграция", "архитектурное изменение", "новый подпроект" — или когда пользователь спрашивает, какой тир у задачи.
allowed-tools
[ "Read", "Write", "Edit", "Grep", "Glob", "Bash", "TodoWrite", "Agent" ]
compatibility
claude-code

02 资源文件 3

03 SKILL.md 正文

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

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

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

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

Тир Триггер Процесс
XS < 20 строк, багфикс, правка текста/конфига, однофайловое изменение DOD → код → smoke-тест → self-review (git diff) → показать пользователю → commit
M новая фича, новый скрипт, 2+ файла, нетривиальная логика, новая интеграция RFC → approve пользователя → код + тесты → линтер → code-review агент → показать diff + summary → commit
L архитектура, миграция, безопасность, ломающее изменение, новый подпроект, изменение public API Полный RFC → approve плана → код по частям (feature flag если релевантно) → code-review + /security-review → итог → финальный approve → merge

Правило по умолчанию: сомневаешься между тирами — выбирай выше.

Шаг 0.5 — образ результата (user-level, ДО кода)

Перед RFC, перед кодом, перед техническими деталями — Claude формулирует конкретизированный образ результата на user-level и согласует его с пользователем. Это правило важнее RFC: RFC про архитектуру, образ результата — про UX. Оба нужны, но образ — первый.

Когда обязательно: M / L. Для XS — если задача неоднозначная или меняет user-visible поведение. Для тривиальных багфиксов / опечаток / правки конфига без UX-сдвига — пропускаем.

Шаблон:

## Что хочется получить

[Как было] → [Как станет], глазами пользователя.

- Какую команду / действие даёт пользователь.
- Что увидит на выходе (текст, файл, страницу, изменение в Notion / Drive / TSV).
- Какие edge-cases обработаются («если X пустой — увидишь сообщение Y»).
- Что **НЕ** входит в scope (что осталось ручным / отложено / отдельной задачей).

## Куда это положить

[Если правило / процесс — в какой файл; если код — в какой модуль / 
команду; если артефакт — в какой каталог.]

Где живёт образ результата:

  • Если у задачи есть BL-файл — в секции ## Plan или отдельной секции ## Что хочется получить.
  • Если BL нет — отдельным сообщением в чате с явным «ОК» от пользователя.
  • Если нет ни BL, ни approval — Claude предлагает завести BL и записать туда образ, ИЛИ зафиксировать образ в чате перед стартом.

Правило: если что-то не в BL и не в чате с approval — этого не существует. Continuation-инструкции после /compact, неявные «Step-N», «я подумал, нам ещё нужно X» — не источник плана. План — то, что зафиксировано и одобрено.

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

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

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

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

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

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

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

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

Шаг 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 и коммитит, если пользователь заранее дал зелёный свет.

Шаг 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 bounty при масштабе, compliance-аудиты (SOC2, GDPR) если станут требованием. Реализуем только при переходе на S3, не заранее.

Шаг 7 — инцидент-лог

Когда в прод-приложении что-то сломалось или не заработало с первого раза — фиксируем в PROJECT/incidents.md:

## YYYY-MM-DD — короткий заголовок
**Что произошло**: ...
**Почему (root cause)**: ...
**Что изменили, чтобы не повторилось**: правило / тест / конфиг / refactor.

Blameless — фиксируем причину, не виноватых. Каждый инцидент делает систему устойчивее: добавленный тест, правило в CLAUDE.md, защита в коде.

Шаг 8 — CI (GitHub Actions)

Добавляется когда первый подпроект выходит в прод (пользователи снаружи). До этого — overkill.

Минимум на старте:

  • Прогон тестов на PR.
  • Прогон линтера на PR.
  • Блок merge при красном CI.

Дальше — инкрементально по мере роста.

Шаг 9 — документация

Документация = живой контракт поведения системы. Если она не обновляется в том же коммите, что и код, — она быстро расходится с реальностью, и любой audit «как должно работать vs как работает» становится бессмысленным.

Базовое правило: код и документация поведения, которое он реализует, лежат в одном коммите. «Сделаю доку потом» = потом не будет.

Таблица триггеров

Триггер изменения Что обновляется
Меняется поведение команды / публичной функции / внешнего API Соответствующий behavioural-контракт в PROJECT/docs/SPEC.md (или эквиваленте per-команду)
Меняется data flow / структура подпроекта / появляется новый модуль PROJECT/ARCHITECTURE.md
Продуктовая развилка с trade-off'ом (выбран один вариант из нескольких) Новый ADR в PROJECT/docs/decisions/NNN-title.md (короткий: контекст / решение / последствия)
User-visible изменение (фича / breaking change / deprecation / удаление) Запись в PROJECT/CHANGELOG.md (формат Keep a Changelog)
Меняется data schema (TSV / JSON config / БД / внешняя property schema) Секция в SPEC + миграционная запись в incidents.md если миграция нетривиальна
Меняется setup / onboarding / запуск PROJECT/README.md
Меняется правило, которое Claude должен помнить между сессиями PROJECT/CLAUDE.md

Когда документации ещё НЕТ в подпроекте

Если SPEC / ARCHITECTURE / CHANGELOG / ADR-папки в подпроекте ещё не созданы — сначала спросить пользователя, нужно ли их завести под текущее изменение. Не создавать молча: пользователь решает, готов ли подпроект к формальной документационной дисциплине, или это пока ad-hoc разработка.

После создания первого артефакта — он живой, обновляется по триггерам выше без переспросов.

Что НЕ требует документации

  • XS-багфиксы, не меняющие поведение (опечатки, рефакторинг без изменений семантики, тесты, форматирование).
  • Внутренние имена / приватные хелперы, не вынесенные в публичный контракт.
  • Эксперименты под feature-флагом до раскатки.

Definition of Done — чеклист перед «готово»

Перед тем как отчитаться, Claude проходит:

  • [ ] Образ результата (Шаг 0.5) был согласован ДО кода — для M/L обязательно, для XS если меняет UX.
  • [ ] Код делает то, что просили (по DOD из TodoWrite).
  • [ ] Smoke-тест (минимум) или юнит/интеграционные тесты (M/L) проходят.
  • [ ] Линтер без ошибок (если настроен).
  • [ ] Diff перечитан (git diff).
  • [ ] Изменения консистентны между файлами.
  • [ ] Для M/L — code-review агент прошёл, критичные findings исправлены.
  • [ ] Секретов в коде нет.
  • [ ] Документация (SPEC / ARCHITECTURE / CHANGELOG / ADR / README / CLAUDE.md) обновлена под изменение поведения, если оно было — по таблице из Шага 9.

Если что-то не ок — исправляем, не спрашивая.

Тон коммуникации с пользователем

Пользователь — продакт, не тех-лид. Это значит:

  • Объяснения багов и инцидентов: на языке бизнес-логики и продуктовых side-effects, не на языке implementation. Что сломалось с точки зрения пользователя продукта, какие видимые последствия (дубли комментариев, пропущенные письма, неправильный статус), что сделано и какой риск на будущее. Без stack traces, uid/gid, имён файлов с путями, syscalls, внутренних модулей. Технические термины уровня "cron", "logs", "env vars", "OAuth", "permissions", "Docker" — окей, можно. Уровня EACCES, writeFileSync, atomic-rename, chown -R, uid 1000, Module._load — нет.

  • Развилки и решения: формулировать в терминах продуктового impact'а, не реализации. "Если выберем (A) — фикс никогда не вернётся, но редеплой 5 минут. Если (B) — переживём пока, починим если опять всплывёт" — да. "Если (A) — добавим entrypoint script, ENTRYPOINT вызовет gosu, exec opt-in" — нет.

  • Не сюсюкать. Пользователь знает, что такое cron, лог, переменная окружения, OAuth. Метафоры с "роботами", "дневниками", "папками-как- для-ребёнка" — оскорбительны и теряют сигнал.

  • Уровень детализации: достаточный, чтобы пользователь понимал ЧТО произошло и ПОЧЕМУ это важно, но не настолько, чтобы он начал читать стек. Если просит детали — даю детали; по умолчанию — нет.

  • Ошибки и стек-трейсы внутри своего workflow: Claude использует их для диагностики, но в ответе пользователю — пересказывает на продуктовом языке. Сырой стек показываем, только если пользователь сам спрашивает про конкретный класс ошибки.

Когда этот скилл НЕ применяется

  • Продакт-задачи: оформление гипотез, Notion / Jira / Confluence-страницы, тексты, posts, intake-формы.
  • Ad-hoc research / exploration без артефакта.
  • Однострочные правки на маке (опечатки, alias, env-var).

Для таких задач — работаем без тиринга и без DOD-церемонии.

04 同仓库更多 Skills