Making Claude Code Actually Work at Scale

Every project, I'd recreate the same slash commands. Every new feature, I'd sit there thinking "wait, which agent should I use for this?" And the worst part? I kept building features without actually thinking about who would use them. Sound familiar?

After the third time I wrote nearly identical Claude configurations, I realized I needed to solve this properly. Not just for one project—for all my projects, forever.

Here's what I built, why it works, and how you can use the same pattern.

The Problems I Was Hitting

Configuration sprawl. Each project got its own .claude directory, and they'd slowly diverge. I'd figure out a great pattern in one project, then forget to use it in the next one.

Decision fatigue. "Should I use the API specialist? Or the architect? Wait, do I even have those agents in this project?" By the time I'd decided, I'd lost my train of thought.

User blindness. I'm a developer. I build developer-friendly interfaces. But you know what? Not all users are developers. I kept building features from my own perspective without considering who would actually use them.

No synchronization. I work on two different systems, one for work and one for personal projects. Every time I'd improve my Claude setup on one machine, the other would be out of date.

It was death by a thousand papercuts.

The Core Insight

Here's what I realized: Claude Code needs structure, not just commands.

Random slash commands are useful. But what makes them powerful is when they compose—when your persona system informs your user stories, which inform your orchestration, which routes to your specialists.

That's the system I built. Four layers that amplify each other.

Layer 1: Specialist Agents

Instead of generic agents, I created domain specialists. Each one is focused and knows its stuff deeply:

.claude/agents/
├── a11y-expert.md           # Accessibility specialist
├── api-specialist.md        # API design
├── security-auditor.md      # Security review
├── performance-optimizer.md # Speed and optimization
└── ... (11 total)

When I need something, I go to the specialist. No more guessing.

Want to design an API? There's an agent for that. Worried about accessibility? There's an agent for that. Need a security review? There's an agent for that.

Each one understands its domain's best practices, common pitfalls, and how to work with the other specialists.

Layer 2: User Personas

This was the game-changer. I created persona files that encode who my users actually are:

.claude/contexts/personas/
├── end-user.md   # Regular users
├── admin.md      # System administrators
└── developer.md  # API consumers

Each persona defines:

• Technical level (how much do they know?)
• Primary devices (mobile? desktop?)
• Goals (what are they trying to do?)
• Pain points (what frustrates them?)
• Success metrics (how do we know it's working?)

Why this matters: Without personas, I built from my perspective. I'd create complex power-user interfaces when the actual users wanted simplicity. Personas keep me honest.

Here's a real example. I was building a bulk delete feature. Before personas, I would've made it technical and efficient (because I like that). But the persona said:

"Admin users need confidence before destructive actions. They want to preview what will be deleted."

So I added a preview step. That one line from the persona saved me from building the wrong thing.

Layer 3: The Orchestrator

This is where it gets interesting. I built an /engineer command that analyzes requests and routes them to the correct specialists.

Instead of me figuring out which agents to use, the orchestrator does it:

/engineer "implement password reset with email verification"

The orchestrator:

1. Analyzes the request (security + API + UI)
2. Identifies required domains
3. Recommends specialists in order
4. Preserves any persona context
5. Gives me ready-to-run commands

Output looks like:

## Implementation Analysis

Domains: Security, API, Frontend
Complexity: Medium

## Recommended Approach

Phase 1: /security-auditor
Review password reset security (token handling, email verification)

Phase 2: /api-specialist
Design reset endpoint and email service integration

Phase 3: /svelte:component-new
Build password reset form

## Command Sequence
/security-auditor "review password reset security requirements"
/api-specialist "design password reset API with email verification"
/svelte:component-new "PasswordResetForm with validation"

No more decision fatigue. The orchestrator tells me exactly what to do and why.

Layer 4: Framework-Specific Generators

I organize code generators by framework instead of generic categories:

.claude/commands/
├── react/      # React 19 + Next.js 15
├── svelte/     # Svelte 5 runes
└── misc/       # Utilities

Each generator follows the latest patterns for its framework. When React 19 came out, I updated the React generators. When Svelte 5 introduced runes, I updated the Svelte generators.

This scales cleanly. Need Vue? Add a vue/ directory. Need Astro? Add astro/.

How They Work Together

Here's the complete workflow:

1. Start with a persona-driven user story:

/user-story admin "wants to bulk delete inactive users"

This loads the admin persona and creates a rich user story with:

• Acceptance criteria aligned with admin needs (keyboard shortcuts, confidence before deleting)
• Technical considerations (bulk operations, audit logging)
• Success metrics (time to complete, error reduction)

2. Get implementation guidance:

/engineer "implement the above user story"

The orchestrator analyzes it and says:

Based on the admin persona (high technical level, desktop-focused, needs confidence):

Phase 1: /ui-architect - Design bulk selection interface (keyboard shortcuts, dense info)
Phase 2: /api-specialist - Design batch delete endpoint (preview mode for confidence)
Phase 3: /security-auditor - Review permissions and audit logging
Phase 4: /svelte:component-new - Implement BulkDeleteDialog

3. Execute with context preserved:

Each specialist gets the persona context. The UI architect knows to design for power users. The API specialist knows to include preview mode. The security auditor knows to log everything.

That's the power of composition. Each layer makes the next layer better.

The Synchronization Solution

Here's the clever part: I use Git + symlinks.

My Claude config lives in one repo:

~/dev/claude-config/

Every project just symlinks to it:

cd ~/my-project
ln -sf ~/dev/claude-config/.claude .claude

Now:

• One config, all projects
• Changes sync via git pull
• Works on all my machines
• Each project can extend without affecting others

When I improve an agent on one machine, git push, then git pull on my other. Done.

What I Learned

Personas are worth the effort. I was skeptical at first. "I know my users!" But writing them down revealed assumptions I didn't know I had. And they prevent future-me from building the wrong thing when I'm tired or distracted.

Orchestration beats documentation. Instead of maintaining a guide about which agent to use when, the /engineer command embeds that knowledge. It analyzes and tells me.

Framework organization scales. Organizing by framework (react/, svelte/) instead of generic categories (ui/) scales way better. Each framework has unique patterns.

Small, focused agents > generic ones. Eleven specialized agents beats one super-agent. I go directly to the specialist I need.

The system compounds. Every agent I add makes orchestration smarter. Every persona I create makes user stories richer. The whole system gets better over time.

Real Impact

After using this for a few weeks:

Efficiency:

• 50% less time deciding which agent to use
• Zero configuration duplication across projects
• Features ship faster with better quality

Quality:

• Accessibility issues caught early (personas encode a11y needs)
• Security reviewed systematically (orchestrator routes security features through auditor)
• Appropriate complexity for users (end-user features stay simple, admin features provide power)

Developer Experience:

• One command (/engineer) handles routing
• Accumulated knowledge compounds
• Works the same everywhere

Starting Small

You don't need to build all of this at once. Here's how I'd start today:

Week 1: Create one specialist agent for your biggest pain point. For me, it was accessibility reviews.

Week 2: Create one persona—probably "end-user". Just writing it down will change how you think.

Week 3: Add one more agent. Now you have two specialists.

Week 4: Create the orchestrator. With two specialists, you'll already see the value.

Then grow organically. Add agents when you feel pain. Add personas when you build for new user types.

Making This Public

I'm considering open-sourcing a boilerplate version of this system with:

• 3-5 essential agents (architect, reviewer, accessibility)
• 3 universal personas (admin, end-user, developer)
• The orchestrator
• One framework as a template (probably React for industry standards)
• Clear documentation

Basically, a "Claude Code starter kit" you can fork and extend.

Would this be useful? Let me know in the comments what you'd want to see, or if you've built similar systems.

The Pattern That Emerges

After weeks of using this, here's what I've realized:

Structure amplifies AI. Random slash commands are useful. But structured systems where commands compose? That's when AI assistance becomes genuinely transformative.

Claude Code is incredibly powerful. But it needs help—it needs structure, context, and coordination. Give it that, and you unlock a completely different level of productivity.

The best part? The system gets smarter as you use it. Every agent you add, every persona you create, every pattern you encode—it all compounds.

That's the real win here. Not just better development today, but a system that keeps getting better tomorrow.