Claude Code WorkFlow

An AI-driven R&D workflow framework

Breaks the full chain of "Requirements → Breakdown → Implementation → Verification → Review → Delivery → Release" into traceable commands, skills, subagents, and rules.
AI executes, humans supervise every critical checkpoint · Runs on top of Claude Code

Operations Manual · Cross-Domain Adaptation · Architecture Decisions · Framework Internals · Quick Start

What Is This
Highlights
Framework Five-Part Architecture
Eight-Step Workflow Scaffold
Three Design Principles
Proof in the Wild
Directory Overview
How to Use
Branch Guide & Related Repos
Where to Start
License

What Is This

This repository is the framework core itself — it is domain-agnostic (frontend / backend / data / mobile / DevOps / QA / design / product / writing / research...). Concrete implementations live under workspace/ and are swapped out by the user per domain.

The framework uses Gates and Archives to directly address the two classic pain points of AI-collaborative R&D:

Problem	Symptom	How the framework treats it
AI has no constraints	Makes things up, edits randomly, works around bugs	Hard Gates (PRD Completeness / `@rules` Traceability Chain / No Hardcoding / Silent Guard Hooks)
AI has no memory	Every session starts from guessing	Archive accumulation (ADR / retrospectives / tasks.json) — readable across sessions

The framework is not tied to a tech stack and not tied to a domain. Domain specialization lives in .claude/rules/*.md and workspace/.

Highlights

Eight-Step SDLC — /prd → /plan → /code → /test → /review → /build → /deploy → /release as a single pipeline, supplemented by /fix /bug-check /prd-check /plan-check /start /meta-audit
Hard Gates — prd-check catches placeholders, plan-check catches incomplete tasks; AI cannot silently skip them
Traceability Chain — PRD anchor → Task ID → artifact @prd/@rules → verification it(); any link can be scanned downstream when something changes
Five-Part Collaboration — Commands (decisions) + Skills (scripts) + Subagents (parallel / independent perspective) + Hooks (silent guard) + Rules (long-term constraints), with clear boundaries
Cross-domain portable — Swap workspace/ + rewrite the contents of .claude/rules/ to use for backend / data / mobile / any other domain (see ADAPTING.md)
Archives carry context — ADRs record decisions, retrospectives record health, tasks.json records progress; a new session can read the history at a glance

Framework Five-Part Architecture

Part	Location	Trigger	Best for
Commands	.claude/commands/	User `/<name>`	Main workflow (pure thinking)
Skills	.claude/skills/	Explicit or auto	Running scripts to fetch data
Subagents	.claude/agents/	Main command spawn	Parallel / context isolation
Hooks	.claude/hooks/	Auto on events	Silent guard (non-blocking)
Rules	.claude/rules/	AI follows automatically	Long-term stable artifact constraints

Boundaries and addition conventions — see .claude/README.md.

Eight-Step Workflow Scaffold

 /prd       Spoken requirement ──→ Structured PRD (with [TBD])
    │
    │  Human review; /prd-check zeroes out placeholders
    ▼
 /plan      PRD ──→ Task manifest (with prdRef + business rules)
    │
    │  /plan-check acceptance
    ▼
 /code      Task manifest ──→ Artifact (header carries @prd / @task / @rules)
    ▼
 /test      Artifact @rules ──→ Verification cases (one per rule)
    ▼
 /review    Independent-perspective audit (can spawn code-reviewer)
    ▼
 /build     Productization
    ▼
 /deploy    Deliver to target environment
    ▼
 /release   Aggregate changelog + cut tag

Each step's abstract semantics are domain-agnostic; artifacts are swapped per domain. Full operations manual: docs/WORKFLOW.md.

Three Design Principles

Traceable

PRD anchor → Task ID → artifact @prd/@rules → verification cases, threaded end to end.

Change any link and the downstream chain can be swept — nothing missed, nothing out of place.

Human Review at Key Checkpoints

AI handles full execution, but stops and waits for a human nod before PRD / breakdown / review / delivery.

AI cannot silently bypass gates. /prd-check and /plan-check are hard blocks, not reminders.

Failures Are Visible

No hiding errors, no auto workarounds, no "green" masking real bugs.

When things go red, triage by four categories (tools → environment → expectation → artifact), and the artifact is the last thing you suspect.

Proof in the Wild

The framework is not a thought experiment — it has been re-applied across three different stacks, three different platforms, and three different domains, without rewriting the core. Each project below ships with its own methodology-report.md for an honest accounting of what worked and what did not.

Project	Domain	Stack	Status	What it proves
`ai-frontend`	Web admin	UmiJS + React + Antd + Vitest + Playwright	Reference implementation	The original frontend incarnation — every mechanism (Gates, `@rules`, traceability) was born here
Spider	Desktop dev tool	Tauri 2 + Rust + React	Active dev · 16 commits	Cross-stack: methodology survives the TS-only → Rust + TS double-stack jump. PRD anchors map cleanly from JSDoc to Rust `///` docs, IPC introduces a new "no-hardcode" red line
Cpcash Wallet (private repo, available on request)	Web3 mobile wallet	Flutter (Dart) on Android · iOS · HarmonyOS	Production · 138 commits · Phase 2 in progress	Cross-platform & cross-domain: 167 tasks closed at 100% completion, 4 bugs fully closed-loop, dev + staging releases shipped in 13 days

What the numbers actually say

Cpcash Wallet (the highest-fidelity case):

138 commits in 13 days, every commit carrying a task ID (T001-T043 — 43/43 = 100%)
167 tasks closed at 100% across 5 modules (account / assets / home / transfer / receive)
4 structured bug reports drove /fix to closed-loop (bug density ≈ 2.4%, low for Web3)
3 platforms shipped from one Dart codebase (Android / iOS / HarmonyOS), including a HarmonyOS-specific MissingPluginException resolved in-line without forking a platform branch

Spider (the meta case):

The product itself visualizes any claude-code-workflow repo as a kanban — a tool built with the methodology to render the methodology
React (15 feature modules) + Rust backend (PTY / scan / watcher / IPC) — same @prd / @task / @rules chain works across both
Demonstrates that the framework's "domain layer" can be a developer-tool product, not just business apps

What the projects also revealed (honest gaps)

Spider's slowdown after 16 commits suggests the 8-step PRD-first flow has higher overhead in exploratory tooling work — a real boundary case for "When NOT to use the framework"
Test coverage in Cpcash skewed toward UI bug reports rather than widget tests — the methodology supports both but doesn't yet force the right balance for Flutter projects
Token economics are still unmeasured — needed before recommending the framework for cost-sensitive teams

Full reports: Spider methodology report · Cpcash methodology report (private repo, available on request)

Directory Overview

claude-code-work/
├── README.md                 ← You are here (framework overview)
├── CLAUDE.md                 ← Project rules (auto-loaded when Claude Code starts)
├── .claude/                  ← Framework core (domain-agnostic mechanisms)
│   ├── commands/             ← Eight-step commands + helper commands
│   ├── skills/               ← Extension skills
│   ├── agents/               ← Dedicated subagents
│   ├── hooks/                ← Event hooks
│   └── rules/                ← Artifact constraints (swap contents per domain, keep structure)
├── docs/                     ← AI workflow artifacts + historical archives
│   ├── WORKFLOW.md           ← Eight-step operations manual
│   ├── ADAPTING.md           ← Cross-domain adaptation checklist (required when forking)
│   ├── DECISIONS.md          ← Architecture Decision Records (ADR)
│   ├── prds/                 ← PRDs generated by /prd
│   ├── tasks/                ← Task manifests generated by /plan (JSON)
│   ├── bug-reports/          ← Inputs for /fix
│   └── retrospectives/       ← Read-only snapshots produced by /meta-audit
└── workspace/                ← Actual project (swap for any domain)

Framework core = .claude/ + docs/ + CLAUDE.md + README.md
Domain specialization = workspace/ + the concrete contents of .claude/rules/*.md

How to Use

Prerequisites

Claude Code CLI installed and signed in

Three steps to get started

# 1. Fork this repo and rename it for your domain
git clone https://github.com/Caspian-Sun/claude-code-workflow.git ai-<domain>-automation
cd ai-<domain>-automation

# 2. Follow ADAPTING.md to swap in your domain layer
#    - Replace workspace/ with a project scaffold for your domain
#    - Rewrite the rule contents in .claude/rules/*.md
#    - Update the onboarding in CLAUDE.md

# 3. Open Claude Code and run your first requirement
claude
> /start                       # Required on first run — AI reads through the project
> /prd <your requirement description>  # Generate a PRD draft

The framework core itself requires no extra installation — Claude Code CLI is all you need. Dependencies under workspace/ depend on your domain (frontend pnpm install, backend might be mvn / go mod / pip install, etc.).

Branch Guide & Related Repos

Branches in this repo

Branch	Purpose
`main`	Framework core overview (domain-agnostic, you are here)
`ai-frontend`	Frontend domain implementation (UmiJS + React + antd + Vitest + Playwright)
`feature`	Integration branch for development
`Harness`	Iteration branch for the framework core

Sister repos (built with this methodology)

Repo	What it is	Why look at it
Spider	Tauri 2 desktop tool that visualizes any `claude-code-workflow` repo as a kanban	Proves the framework works on Rust + React double-stack and inside a developer-tool product
Cpcash Wallet (private repo)	Flutter Web3 wallet (Android · iOS · HarmonyOS)	Proves the framework works on Flutter / Dart, on three mobile OSes, in a high-stakes domain (crypto), and at production scale (138 commits, 167 tasks closed)

To see a full domain example, check out the ai-frontend branch in this repo or browse the sister repos above. ai-backend / ai-data and other branches will be added over time.

Where to Start

I am...	Open this first
Picking up the framework for the first time	docs/WORKFLOW.md — Eight-Step operations manual
Wanting to port the framework to a domain	docs/ADAPTING.md — Cross-domain adaptation checklist
Modifying framework mechanisms (add command / skill / agent)	.claude/README.md — Boundaries of the five parts
Checking how the framework evolved	docs/DECISIONS.md — Architecture Decision Records (ADR)
Reviewing past health scans	docs/retrospectives/ — `/meta-audit` read-only reports
Enabling GitHub automation	.github/SETUP.md

Contributing

Issues and PRs are welcome. Before submitting:

Run /meta-audit to check whether your change introduces health regressions
If you change framework mechanisms, add an ADR entry in docs/DECISIONS.md with background

claude-code-workflow