Claude Code Workflow

A phase-based workflow for building features with Claude Code, where documentation serves as the handoff between sessions.

Why

Working with Claude Code across multiple sessions tends to lose context. Without structure, you get scope drift, repeated explanations, and sessions that start from scratch. This workflow solves that by making documentation the connective tissue between sessions — each phase produces artifacts that the next phase consumes.

The workflow itself was built and improved using this same system.

How It Works

Each phase is a skill you invoke explicitly, run one per session. /design is a standalone upstream phase that produces a frozen design spec; the implementation workflow that follows is a three-phase arc.

Design (standalone)

Phase	Skill	What happens
Design	/design	Transform an idea into a design spec with requirements and decisions

Implementation

Phase	Skill	What happens
1 · Plan	/plan	Break the design into executable tasks with done-when criteria
2 · Build	/build	Execute tasks one at a time, committing at each checkpoint
	/learn-by-doing	Same as /build, but user writes code while Claude tutors
3 · Document	/document	Update changelog, generate PR description, close out the work

Core principles:

• User drives — Claude proposes, user approves. No auto-advancing between phases.
• One phase per session — End the session after each phase. Docs are the handoff.
• Preserve the mess — Note deviations in the build log rather than rewriting plans.

Project Structure

.claude/skills/            # Skill definitions (design, plan, build, document, learn-by-doing, study-partner)
claude-code-insights/      # Claude Code usage analysis reports
docs/
├── design-specs/          # Design documents
├── implementation-plans/  # Task breakdowns
├── learning/              # Learning logs from /learn-by-doing
├── changelog.md           # Completed feature history
└── backlog.md             # Future improvements
CLAUDE.md                  # Project instructions for Claude Code

Other Skills

Beyond the workflow phases, the repo ships standalone skills:

• /study-partner — A user-invoked study session that facilitates deliberate learning through interactive exercises grounded in learning science. Works on repo code or external content (URLs, files, pasted snippets).

Setup

To automatically sync workflow skills to your global ~/.claude/skills/ after pulling changes on main, run this once:

git config core.hooksPath .githooks
chmod +x scripts/sync-skills.sh

This configures git to use the .githooks/ directory, which includes a post-merge hook that detects changes under .claude/skills/ and copies the 5 workflow skills (design, plan, build, learn-by-doing, document) to ~/.claude/skills/. Non-workflow skills are not affected.

To sync manually at any time:

bash scripts/sync-skills.sh

Credits

The /learn-by-doing and /study-partner skills adapt learning-science material from learning-opportunities by Dr. Cat Hicks, used under Creative Commons Attribution 4.0 International (CC-BY-4.0).