We split Claude Code into four roles. The output stopped lying.

Lital Shalev — Thu, 22 Oct 2026 14:12:54 +0000

Most AI coding assistants are extremely good at one thing: making a confident-sounding first draft of whatever you ask.

That is also their failure mode.

If you let a single AI conversation handle "turn this idea into a tested, reviewed, merge-ready pull request," what you actually get is: a spec the model invented, an architecture the model chose silently, code written to pass tests the model also wrote, and no review because the author is the same entity as the reviewer. Shipping that is how AI-assisted engineering acquires its reputation for subtle bugs and unreadable modules.

Strong engineering teams have never worked that way. Even a two-person team informally splits the work: someone frames the problem, someone decides the approach, someone builds, someone else looks at the diff. The roles may compress onto one person, but the four moments are still there.

I made that structure explicit for Claude Code, as four slash-command skills, each with one job.

The four skills

Each /<skill> is a self-contained SKILL.md file with a strict output format. You invoke them in sequence (or individually), and each produces an artifact the next stage holds accountable.

/product-owner

Turns a raw idea into a testable spec. Output: PROBLEM, TASK SPEC, USER STORIES, ACCEPTANCE CRITERIA, EDGE CASES, OUT OF SCOPE, OPEN QUESTIONS, DEFINITION OF DONE.

The important part: if the request is missing something load-bearing, this skill is required to flag it under OPEN QUESTIONS rather than invent an answer. The thing that keeps AI coding from being safe is that models by default fill ambiguity with plausibility. Making "ask, don't guess" a hard rule at the spec stage is where most of the ROI lives.

/architect

Takes the spec and designs the minimal implementation approach. Output: APPROACH, COMPONENTS, DATA FLOW, INTERFACES, CONSTRAINTS, RISKS, TRADEOFFS, DEFINITION OF DONE.

First thing the architect skill does is a size check. If the diff would exceed ~400 lines of meaningful code, or touch more than 3-4 files across layers, it refuses to design the whole thing and instead splits it into sub-tasks. The downstream Dev/QA skill works much better on small, isolated changes.

/dev-qa

Implements the feature with tests. The core discipline: "Acceptance criteria are the contract. Every checked box must correspond to working code AND a test that would fail without it. If you cannot write the test, you do not understand the requirement."

Also: no drive-by refactors, no new dependencies without an architect note approving them, no commits to main, no bypassing failing tests. CI must be green before pushing.

/code-reviewer

Read-only. Reviews the diff against the spec and architect notes. Output: VERDICT (approve / request changes / needs human), CRITICAL issues, IMPORTANT issues, SUGGESTIONS, WHAT'S DONE WELL, VERIFICATION STORY.

Every Critical or Important issue must include affected area, risk, and recommended fix. "This feels bad" is not a valid finding; evidence is.

Why structuring it this way matters

Three things change when the roles are explicit:

Ambiguity surfaces at the cheapest stage. OPEN QUESTIONS at the spec step costs nothing to resolve. The same ambiguity caught at code review costs a rework round.

Drift becomes traceable. If the final PR doesn't match what the user asked for, the gap is attributable to a specific stage, with a specific output you can inspect.

Scope creep gets a hard stop. Dev/QA is explicitly banned from "while I'm here" cleanups. The architect refuses oversized tasks. The reviewer rejects PRs that exceed the spec.

None of this is theoretical. If you have ever reviewed a PR that quietly tripled in scope between the ticket and the diff, you know exactly what these guardrails prevent.

Install

git clone https://github.com/KumiQ/ai-engineering-skills.git
cd ai-engineering-skills
mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills/product-owner"  ~/.claude/skills/product-owner
ln -s "$(pwd)/skills/architect"      ~/.claude/skills/architect
ln -s "$(pwd)/skills/dev-qa"         ~/.claude/skills/dev-qa
ln -s "$(pwd)/skills/code-reviewer"  ~/.claude/skills/code-reviewer

Restart Claude Code. /product-owner, /architect, /dev-qa, /code-reviewer are now available in every project.

Where this came from

I run KumiQ, where we work on making organizational engineering standards usable by AI coding agents, through a Model Context Protocol (MCP) server. These four role-based skills are the workflow layer that sits on top of that: once the agent has access to your organization's standards, these are the roles that actually use them to produce shipped work.

The skills are MIT-licensed, independent of KumiQ, and useful on their own. If your team is figuring out how to adopt AI coding tools without the output quality dropping, start here.

Repo: https://github.com/KumiQ/ai-engineering-skills

I would genuinely like to hear what breaks when you try these on your own stack. Issues and PRs welcome.

DEV Community: Lital Shalev