A persona definition is a structured prompt that shapes how a single base model responds. Let's open one up and see exactly how it works—and why structure matters more than you'd expect.

The Persona Lens Model series

What's in a Persona File

A persona definition (what Cursor calls a "subagent") is a Markdown file containing structured sections. Here's a simplified example:

# Security Auditor

## Role
You are a security auditor and penetration tester who 
reviews code for vulnerabilities and security weaknesses.

## Expertise
- OWASP Top 10 vulnerabilities
- Authentication and authorization patterns
- Input validation and sanitization
- Cryptography best practices
- Secure coding standards

## Process
1. Scope: Identify security-sensitive code paths
2. Analyze: Check for common vulnerabilities
3. Validate: Verify findings are exploitable
4. Assess: Rate severity and impact
5. Recommend: Provide specific mitigations
6. Document: Create structured findings report

## Output Format
### Security Review: [Component Name]

**Risk Level**: [Critical/High/Medium/Low]

#### Findings
| ID | Severity | Category | Description |
|----|----------|----------|-------------|
...

#### Recommendations
...

## Constraints
- Never dismiss potential vulnerabilities without investigation
- Always provide remediation, not just findings
- Flag uncertain findings for human review

That's it. No code. No API calls. No special runtime. Just text that describes how to behave.

How Claude Applies a Persona

When you invoke "the security auditor," Claude reads this file and applies each section:

flowchart TD
    subgraph "Persona Application"
        Role[Adopts Role] --> Frame[Frames Thinking]
        Frame --> Expertise[Applies Expertise Filter]
        Expertise --> Process[Follows Process]
        Process --> Output[Structures Output]
        Output --> Constraints[Respects Constraints]
    end
    
    Code[Your Code] --> Role
    Constraints --> Result[Security-Focused Analysis]

Role adoption: Claude frames its responses from the stated perspective. "You are a security auditor" isn't a suggestion—it's an instruction the model follows.

Expertise filtering: The listed expertise areas prime Claude to focus on those domains. OWASP Top 10 knowledge gets activated. Unrelated knowledge (like cooking recipes) stays dormant.

Process following: The numbered steps become Claude's actual workflow. It will scope, then analyze, then validate, in that order.

Output shaping: The format template produces consistent structure. Ask five times, get five reviews with the same sections.

Constraint enforcement: The "do/don't" rules guide edge cases. "Never dismiss potential vulnerabilities" means Claude will err toward flagging rather than ignoring.

The Stateless Reality

Here's a critical point: persona files are templates reapplied fresh each time.

The security auditor doesn't "remember" the last code review it did. Each invocation:

  1. Reads the persona file anew
  2. Applies it to the current context
  3. Produces output
  4. Forgets everything

This is why:

  • The same persona might give different results for identical inputs (stochastic generation)
  • You can't tell an "agent" to "remember what we discussed last time"
  • Context must be provided explicitly in each invocation

If you need persistence, you need external state management—the persona itself holds nothing.

Why Structure Matters

Claude interprets persona files literally. Vague instructions produce vague results. Compare:

Weak Persona Strong Persona
"You help with security stuff" "You are a security auditor who reviews code for OWASP Top 10 vulnerabilities"
"Be thorough" "Step 1: Identify all entry points. Step 2: Trace data flow..."
"Give good output" "[Specific table format with columns for ID, Severity, Description]"
"Be careful" "Never mark a vulnerability as resolved without verifying the fix"

The left column gives Claude room to improvise. Sometimes that's fine. But for consistent, specialized behavior, the right column wins.

Key insight: A persona file is prompt engineering, packaged as a reusable artifact.

The Anatomy Breakdown

Every effective persona file has these components:

Component Purpose Example
Role Identity framing "You are a security auditor..."
Expertise Knowledge activation "OWASP Top 10, cryptography..."
Process Workflow structure "1. Scope 2. Analyze 3. Validate..."
Output Format Consistent structure "Table with Severity, Description..."
Constraints Guardrails "Never dismiss without investigation"

Optional but valuable:

  • Examples: Show desired output (few-shot prompting)
  • Triggers: When this persona should activate
  • Anti-patterns: What NOT to do (explicit failure modes)

Authoring Guidelines

Role: Be Specific About Perspective

Bad:

You are a helpful assistant.

Good:

You are a senior application security engineer specializing in code review. 
You think like an attacker to find vulnerabilities before they're exploited.

The good version establishes seniority (has judgment), specialty (security, not general), and perspective (adversarial thinking).

Expertise: Bounded, Not Buzzwords

Bad:

You know about security.

Good:

## Expertise
- OWASP Top 10 vulnerabilities
- Authentication and authorization flaws
- Injection attacks (SQL, XSS, command)
- Cryptographic weaknesses
- Secure coding patterns in JavaScript/TypeScript

Note what it doesn't include: network security, infrastructure hardening, compliance frameworks. The agent has boundaries.

Process: Numbered Steps, Not Aspirations

Bad:

Analyze the code carefully.

Good:

## Process
1. Threat Modeling: Identify assets, attackers, attack surfaces
2. Code Analysis: Input validation, auth mechanisms, data handling
3. Risk Assessment: Severity × Exploitability × Impact
4. Recommendations: Prioritized by risk, with specific fixes

Output: Show the Template

Bad:

Provide a report of your findings.

Good:

## Output Format

### Security Audit Report

#### Summary
[1-2 sentence overview: critical count, recommendation]

#### Critical Issues
1. **[Vulnerability Name]**
   - Location: file:line
   - Risk: [severity] - [impact description]
   - Fix: [specific remediation with code]

#### Recommendations
[Prioritized action items]

Constraints: Explicit Boundaries

Bad:

Be careful with security recommendations.

Good:

## Constraints
- Never assume code is safe without evidence
- Always provide proof-of-concept for vulnerabilities (sanitized, not weaponized)
- Don't recommend security theater (checkbox measures that don't add protection)
- If unsure about a finding, flag for human review rather than omitting

Common Misconceptions

  • "More detail is always better" — Diminishing returns exist. A 500-word persona file works. A 5,000-word one may confuse more than clarify. Focus on the components that shape behavior.

  • "The model becomes the persona" — Claude doesn't transform into a different entity. It role-plays while retaining its base capabilities and limitations. A "security auditor" persona doesn't make Claude better at security—it makes Claude focus on security in its responses.

  • "Constraints are optional" — They're critical. Without explicit guardrails, the model follows the path of least resistance, which may not be what you want.

Quick Reference: Persona File Checklist

  • [ ] Role is specific with clear perspective
  • [ ] Expertise areas listed explicitly (not implied)
  • [ ] Process has numbered, sequential steps
  • [ ] Output format includes a template or example
  • [ ] Constraints include at least 3 "never" statements
  • [ ] Total length under 1,000 words (diminishing returns beyond)

What to Do Next

  1. Examine your existing prompts: Could they be structured as reusable persona files?
  2. Apply the template: Use the anatomy breakdown to create or improve a persona
  3. Read the final post: We'll cover design patterns for multi-persona systems

"The persona file is prompt engineering, packaged as a reusable artifact."

Next: Designing with the Persona Lens Model — Practical patterns for routing, layering, and coordinating personas.