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 |
1 command block |
Fixed |
Zsh noclobber violations |
1 ( |
Fixed |
Hardcoded |
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 |
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 |
|
Skill |
Morning kickoff |
|
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 |
|
Skill |
End of work block |
|
Agent |
When build has warnings |
|
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.