claude-dev-workflow

A Claude Code skill that enforces a tiered development workflow on every coding task — from a one-line bug fix to a full architectural change.

It is the personal workflow I use across all my code projects (CLIs, MCP servers, SaaS prototypes), captured as a skill so Claude Code applies the same discipline automatically. Published as a portable reference for anyone interested in opinionated AI-assisted development practices.

⚠️ The skill itself (SKILL.md) is written in Russian — that is my working language. This README in English explains what the skill does and how to adopt it.

What it does

When you give Claude Code a coding task, the skill triggers automatically and:

0. Runs a pre-flight branch + backlog audit before doing anything else (Pre-flight). Checks that the current branch is in sync with main, lists open PRs, and re-reads private/backlog/ to surface recent changes from other parallel sessions. Prevents two recurring classes of bugs: stale-branch phantom-bugs (running commands from a branch that's behind main and diagnosing the wrong code) and duplicate work across parallel sessions sharing one backlog.

1. Classifies the task into a tier:

   • XS — < 20 LOC, bug fix, single-file change. Minimal ceremony.
   • M — new feature, multi-file, non-trivial logic. Requires an RFC.
   • L — architecture, migration, security, breaking change. Requires a full RFC, multi-agent review, and explicit final approval.

2. Enforces an "image of result" before any code (Шаг 0.5). Before the RFC, before code, Claude must describe — in user-level language — what the user will see, type, and get. Approved in chat or written into a backlog item. Code starts only after approval.

3. Switches to PM/dispatch mode when work is parallelisable (Шаг 0.7). On a batch of ≥2 independent tasks (even all XS), or one M/L task that cleanly splits into independent units, Claude takes the project-manager role: decomposes the work into user-level units, gets explicit approval, then dispatches one subagent per unit into its own git worktree, runs them in parallel, monitors progress, integrates the results, and runs a single cross-cutting review on the merged diff. Agents never talk to each other — the interface contract stays with Claude. If an agent goes off-spec, Claude reopens the unit with a corrected brief; never silently takes over. Triggered automatically (with a visible gate) or manually via /dev-workflow dispatch.

4. Demands an RFC for M/L tasks under <project>/rfc/NNN-title.md: problem → options → chosen + why → risks → verification plan. Code is blocked until the user approves the RFC.

5. Requires a smoke test even for XS. One trivial test proving the primary function gets called and returns the expected shape. Catches ~80% of refactor breakage in two minutes.

6. Runs multi-agent code review for M/L. A code-reviewer subagent gets the diff and reports findings on readability, edge cases, over-engineering, and secrets. For L-tier, also runs /security-review and /review.

7. Final approval is always the user's. Claude does not commit M/L code without an explicit "ok".

8. Incrementally scales security through S1/S2/S3 levels:

   • S1 — local scripts and personal tools. /security-review for L-tier, secret-detection in code review.
   • S2 — pre-prod SaaS with auth or a public URL. SAST (semgrep), OWASP Top 10 checklist, threat modeling for auth/data features.
   • S3 — production with real users. A pentest subagent against staging, external audit before paid customers.

9. Blameless incident log in <project>/incidents.md — what broke, root cause, what we changed so it doesn't repeat.

The full content (testing pyramid, lint setup, pre-commit hook policy, CI guidance, definition-of-done checklist) lives in SKILL.md.

What it is not

• Not a framework. No code is shipped — only conventions. There is nothing to import, run, or configure. The skill is a long policy document Claude Code reads at session start and applies during work.
• Not a productivity tool. It deliberately adds friction for M/L tasks. The point is to slow down enough to think before writing multi-file changes.
• Not language-specific. Targets JavaScript/Node and Python in the test/lint guidance, but the tiering and review logic apply to any stack.
• Not for product/PM tasks. Excluded explicitly. Notion/Jira/ Confluence work bypasses this skill.

Installation

This skill is intended to be installed in your personal Claude Code skills directory:

# Clone the repo somewhere persistent
git clone https://github.com/ymuromcev/claude-dev-workflow.git ~/Code/claude-dev-workflow

# Symlink into Claude Code's skills directory
ln -s ~/Code/claude-dev-workflow ~/.claude/skills/dev-workflow

That's it. Claude Code auto-loads the skill on the next session and triggers it on any coding-task phrase.

To verify: in a Claude Code session, the skill should appear in /help → skills list under dev-workflow.

Companion skill

claude-scaffold-project is the companion bootstrapper — when you start a brand-new project, it scaffolds CLAUDE.md, rfc/, private/backlog/BL-001, and other structure that this workflow expects. They are designed to be used together, but each works on its own.

Tier examples

A typical XS interaction:

> fix the typo in CLAUDE.md "untrustred" → "untrusted"

Claude classifies as XS, edits, runs a quick check, shows the diff, commits.

A typical M interaction:

> add a new ATS adapter for Workable to engine/modules/discovery/

Claude pauses. Writes an "image of result" (what the user will see), asks for approval. Drafts an RFC under rfc/NNN-workable-adapter.md. Waits. Once approved, writes code + tests, runs code-reviewer subagent, fixes critical findings, shows diff, asks for commit approval.

A typical L interaction:

> migrate all profiles to a new TSV schema with a backfill

Same as M but also runs /security-review and requires a phased plan with rollback. No code starts until the full plan is approved.

A typical PM/dispatch interaction:

> close BL-12 through BL-15 — README updates across four projects

Claude proposes a 4-unit decomposition (one project per unit, all independent, no file overlap), shows what the user will see after each unit, asks "parallelise?". On "go", launches four subagents in their own worktrees in parallel, surfaces a one-line status per unit as they finish, reopens any unit that came back off-spec, merges the four worktrees, runs one combined review, and reports done. Claude itself writes no code in this flow — only orchestrates.

Why publish this?

Two reasons:

1. Portfolio transparency. This is part of my actual day-to-day working setup — not a curated demo. Showing it explains how I think about AI-assisted code more honestly than a one-page resume bullet.
2. Possible reuse. If anyone else finds the tiering / RFC-gating / multi-agent-review pattern useful, the skill is MIT-licensed and copyable.

Pairing with skills

Designed to compose with claude-scaffold-project: that skill creates a new project's directory layout (including the rfc/ folder this skill expects) and references this one in the generated CLAUDE.md. You can use either independently.

License

MIT.