Claude Code: Real-World Workflows

Components are theory. These workflows are proof. Each documents a real session where the Claude Code system delivered measurable results.

Workflow: Parallel Project Restructuring

Scenario

Five project documentation files in domus-captures were monolithic — all content inline, no partials. The T16g deployment project had been restructured as the gold standard. Goal: bring all remaining flat projects up to the same modular pattern.

Trigger

User request: "I want ALL of the projects to model this at once. Get the agents army to work."

Components Used

Component Role

Explore Agent

Scanned all project files, categorized as GOOD/FLAT/PARTIAL

5 General Agents (parallel)

Each restructured one flat project independently

Antora Build Hook

Pre-commit hook verified 0 warnings after changes

AsciiDoc Rule

Auto-loaded for all .adoc edits — enforced attribute usage

Execution Flow

1. Explore agent scans 150+ project files              → 5 FLAT identified
2. Read all 5 flat files + T16g model page              → pattern extracted
3. Launch 5 agents simultaneously:
   ├── Agent 1: PRJ-domus-antora-ui (53 lines)          → 5 partials
   ├── Agent 2: PRJ-domus-pdf-export (90 lines)         → 6 partials
   ├── Agent 3: PRJ-rust-learning (118 lines)            → 7 partials
   ├── Agent 4: siem/in-house-alternative (271 lines)    → 6 partials
   └── Agent 5: siem/monad-evaluation (715 lines)        → 11 partials
4. All agents complete                                   → 35 partials created
5. git commit triggers Antora pre-commit hook            → Build clean, 0 warnings

Result

Metric Before After

Flat project files

5

0

Total partials created

0

35

Lines extracted

1,247 inline

1,470 in partials

Main page size (avg)

~150 lines

~20 lines (thin wrappers)

Antora build warnings

0

0

Commit: 89beb1a — 41 files changed, 1,470 insertions(+), 1,181 deletions(-)

Teaching Point

Parallelization with quality gates. Five independent agents ran simultaneously because the restructuring tasks had no dependencies. The Antora pre-commit hook served as the quality gate — if any agent produced broken includes, the build would have caught it. This pattern works for any batch operation where tasks are independent and a build step can verify correctness.

Workflow: P16g Deployment Audit & Mass Fix

Scenario

The ThinkPad P16g deployment runbook (18 partials, 12 phases) had been renamed from T16g to P16g, but 40+ stale references to the old hostname remained scattered across 14 files. Additional bugs included missing Vault credential loading, zsh noclobber compatibility, and hardcoded hostname assumptions.

Trigger

User request: "Really look through the deployment and make any refinements if needed."

Components Used

Component Role

Explore Agent

Deep audit across all 18 partials — found 5 critical, 1 high, 4 medium issues

2 Background Agents (parallel)

Agent 1: mass t16g→p16g rename (57 changes, 10 files). Agent 2: bug fixes (vault creds, zsh redirect, hostname vars)

CLAUDE.md Rules

Verification pattern (verify-before/apply/verify-after) flagged as missing in medium-priority findings

Execution Flow

1. Explore agent audits 18 partials                     → 10 issues found
2. Findings presented to user with severity levels       → "pronto now!!"
3. Launch 2 background agents simultaneously:
   ├── Agent 1: Mass rename (t16g→p16g)                  → 57 changes, 10 files
   └── Agent 2: Bug fixes                                → 4 fixes, 3 files
4. Both agents complete in ~50 seconds
5. User commits and pushes from terminal

Result

Metric Before After

Stale hostname references

40+

0

Missing ds d000 dev/vault

1 command block

Fixed

Zsh noclobber violations

1 (> should be >|)

Fixed

Hardcoded $(cat /etc/hostname)

3 instances

Replaced with explicit variable

Historical field notes

Preserved

Documents the error + correction

Commit: user-authored — 13 files changed, 57 renames + 4 bug fixes

Teaching Point

Audit-first, fix-second. The Explore agent found issues without changing anything. Only after the user reviewed and approved ("pronto now!!") did the fix agents run. This mirrors the plan/apply pattern in infrastructure-as-code (Terraform plan → apply). The two fix agents ran in parallel because rename operations and bug fixes touched different sections of the files — no merge conflicts possible.

Workflow: Live Config → Documentation Sync

Scenario

The Claude Code Features documentation (16 partials across 4 pages) had drifted significantly from the live configuration. CLAUDE.md was 845 lines but docs said 772. Settings had 97 allowed commands but docs said 56. Output styles existed but weren’t documented at all.

Trigger

User request: "Make this billion dollar style docs."

Components Used

Component Role

Explore Agent

Full audit of ~/.claude/, dots-quantum stow package, domus-captures project config — produced gap analysis

5 General Agents (parallel)

Each updated related groups of partials from live state data

Antora Build Hook

Pre-commit verification — 0 warnings

AsciiDoc Rule

Enforced attribute usage and structural standards across all 16 partials

Execution Flow

1. Read all 12 existing partials + 4 pages              → baseline captured
2. Explore agent audits live config:
   ├── ~/.claude/ symlink structure
   ├── dots-quantum canonical files
   ├── domus-captures project-scoped config
   └── D2 diagrams inventory
3. Gap analysis produced                                 → 10+ stale items identified
4. Launch 5 agents simultaneously:
   ├── Agent 1: summary + architecture + deployment model + metadata
   ├── Agent 2: skills + hooks
   ├── Agent 3: agents + mcp-servers
   ├── Agent 4: rules + output-styles (NEW) + settings
   └── Agent 5: claude-md + quick-reference + success-metrics
5. All agents complete                                   → 16 partials updated, 1 created
6. git commit triggers Antora pre-commit hook            → Build clean, 0 warnings

Result

Metric Before After

CLAUDE.md line count

772 (stale)

845 (accurate)

Permissions documented

56 allows

97 allows, 10 denies (categorized)

Output styles documented

None

professional.md fully documented

Deployment model

Not documented

Full stow/symlink architecture

Agent documentation

Flat list, wrong counts

Global vs project-scoped, actual configs

/drill skill status

"Implemented" (wrong)

"Planned" (correct)

Architecture diagram

v1

v2

Settings size documented

2KB

7.6KB, 240 lines

Commit: d51c486 — 27 files changed, 1,041 insertions(+), 284 deletions(-)

Teaching Point

Live state is the source of truth, not documentation. The workflow starts by auditing the actual configuration files, not reading the docs. The gap analysis identifies drift. Then agents update docs to match reality. This is the same principle as infrastructure drift detection — your monitoring should tell you what IS, not what you THINK is deployed.

Workflow: Daily Operations Cadence

Scenario

Start-of-day routine using Claude Code skills and agents to maintain documentation hygiene across 15+ Antora component repos.

Daily Flow

Session start
├── SessionStart hook fires
│   ├── Displays "Professional Environment Active"
│   ├── Shows output style (professional)
│   └── Reports backup file count
│
├── /worklog                              # Skill: create today's worklog
│   ├── Creates WRKLOG-YYYY-MM-DD.adoc
│   ├── Generates 8 standard partials
│   └── Adds to nav.adoc
│
├── "update carryover days"               # Agent: carryover-updater
│   ├── Scans all tracker partials
│   └── Increments day counters
│
├── [documentation work happens]
│   ├── Edit .adoc file
│   │   ├── PreToolUse hook: auto-backup to ~/.claude/backups/
│   │   └── PostToolUse hook: validate \{attributes} against antora.yml
│   ├── Edit .sh file
│   │   └── PostToolUse hook: ShellCheck validation
│   └── AsciiDoc rule auto-loads for all .adoc edits
│
├── /deploy "docs: Today's updates"       # Skill: push + rebuild
│   ├── Commits with conventional format
│   ├── Pushes to origin
│   └── Triggers Cloudflare Pages rebuild
│
└── "fix the build"                       # Agent: build-fixer (if needed)
    ├── Runs Antora build
    ├── Parses all warnings
    ├── Fixes each one
    └── Verifies clean build

Components in Play

Component Type When

SessionStart hook

Hook

Session opens

/worklog

Skill

Morning kickoff

carryover-updater

Agent

After worklog

Auto-backup

Hook (PreToolUse)

Every file edit/write

Attribute validator

Hook (PostToolUse)

Every .adoc edit

ShellCheck

Hook (PostToolUse)

Every .sh edit

AsciiDoc rule

Rule

Auto-loads for .adoc files

/deploy

Skill

End of work block

build-fixer

Agent

When build has warnings

UserPromptSubmit

Hook

Every prompt (sensitive file check)

Teaching Point

Layered automation. No single feature handles everything. Hooks fire automatically on lifecycle events. Skills are invoked explicitly for known workflows. Agents handle complex, judgment-requiring tasks. Rules silently enforce standards. The layers compose — a /deploy invocation benefits from all the hooks that ran during the editing phase, catching errors before they reach the commit.