Trait-Based Agent Composition in Claude Code

I had 56 hardcoded Claude Code agent definition files. A code review agent. A thorough code review agent. A security-focused code review agent. An exploratory code review agent. A conservative code review agent. A fast code review agent.

At some point I stopped and asked: why am I defining each combination manually?

Every new behavioral variation needed a new file. I was maintaining 56 slightly-different documents, each one a handwritten combination of role, tone, and execution style. When something changed in my workflow, I updated it in six places instead of one. New agent ideas stalled because creating them meant yet another file.

The problem had a name: agent sprawl. And I had it bad.

Want the foundational patterns first? The free 3-pattern guide covers memory, delegation, and knowledge graphs at concept level.

The Problem: Hardcoded Claude Code Agents Don't Scale

The sprawl happened gradually. First I had 10 agents. That was manageable. Then a task needed something slightly different - not a full rewrite, just a different tone. So I duplicated the file and tweaked it. Then another variant. Then a few more.

Fifty-six files later, I had agents that overlapped in obvious ways. code-review-agent.md, thorough-code-review-agent.md, and security-code-review-agent.md shared 80% of their content. The only real differences were 3-4 lines about tone and focus area.

The maintenance math was brutal. Update a shared behavior across 10 overlapping agents: 10 manual edits. Miss one: inconsistent behavior that's hard to debug. And every new behavioral need meant choosing between a new file or forcing an existing agent to do something it was not quite designed for.

There had to be a better structure.

The Solution: Three Dimensions That Compose Into Any Agent

The insight was that every agent I had built was actually a combination of three independent concerns: what it knows, how it communicates, and how it executes. Those three dimensions could be defined once and composed on demand.

Expertise determines what the agent knows. Here is one example from the 10 expertise types:

## Expertise: engineer
- Description: Implementation, debugging, optimization
- Core Skills: coding, debugging, testing, performance
- Output Style: working code with documentation

Personality determines how the agent communicates. Here is one from the 8 personality types:

## Personality: cautious
- Description: Highlights risks, edge cases
- Voice Markers: "However...", "One concern is...", "A potential risk..."
- Avoids: overconfidence, ignoring edge cases

Approach determines execution pattern. Here is one from the 6 approach types:

## Approach: adversarial
- Pattern: attack-defend
- Steps: Assume attacker mindset > Find vulnerabilities > Document
- Best For: security review, stress testing

Any combination of one from each dimension is a valid agent. The composed profile gets injected into the delegation prompt with role, voice markers, and execution steps. No new files required.

One Example: The Security Audit Composition

Take a security audit. In the old system I had a dedicated security-audit-agent.md. Under trait composition, I describe it in three words: security + cautious + adversarial.

Security expertise brings domain knowledge about vulnerability classes, attack vectors, and the relevant tools for static analysis. Cautious personality means the agent flags potential issues rather than assuming they are safe, asks for confirmation before suggesting destructive actions, and communicates risks clearly rather than burying them. Adversarial approach means it actively tries to break the code - looking for ways an attacker would exploit what it finds, not just checking a compliance checklist.

The composed agent behaves the way a good security reviewer actually behaves: paranoid, methodical, and adversarial toward the code by design.

Now suppose I need the same audit presented more diplomatically for a team that is defensive about their codebase. I change one dimension: security + empathetic + adversarial. Same expertise. Same adversarial execution. But the empathetic personality frames findings as shared problems to solve rather than failures to blame. Zero new files. One trait swap.

The Result: 56 Files Become 480 Combinations

Ten expertise types times eight personality types times six approach types: 480 unique combinations from 24 trait definitions. The combinations I actually use regularly - bug fix (engineer + precise + iterative), research (researcher + skeptical + exploratory), architecture review (architect + cautious + consultative) - work exactly as their hardcoded equivalents did. But the system can now compose anything I need without my involvement.

Adding an 11th expertise type creates 48 new combinations instantly. Updating the cautious personality definition improves every agent that uses it, across all 60 expertise-approach combinations it touches. The dimensions are independent. Changing one does not affect the others.

A 2024 arXiv study (2410.19238) on personality-diverse AI teams found a 27.3% improvement on multi-agent tasks compared to uniform personality teams. The research community has validated this for multi-agent coordination. Trait composition applies it at the individual agent level - each agent gets a distinct behavioral profile rather than defaulting to the same generic assistant personality.

No competing tool I have found uses combinatorial trait composition for claude code agents. Most treat agents as flat configurations. Some allow role prompts. None model expertise, personality, and approach as independent, composable dimensions.

The reduction in maintenance alone justified the rewrite. But the bigger benefit was removing the friction from creating new agent behaviors. A combination I had never needed before is two words away, not a new file away. This pairs naturally with the score-based auto-delegation system that decides when to delegate in the first place, and fits within the broader agent orchestration patterns that route work to the right profile automatically.

With the three starter traits above, you can already compose your first agents: engineer + cautious + adversarial for a defensive code review, or engineer + precise + systematic for a thorough refactor. The full taxonomy covers all 24 trait definitions with preferred tools, autonomy levels, and battle-tested combo recipes.