What Are Output Styles? Taking Control of Claude Code's Responses
If you've spent any time with Claude Code, you've probably wished it would respond a bit differently sometimes — maybe more concisely during rapid iteration, or with more explanation when navigating an unfamiliar codebase. Output Styles let you reshape how Claude Code communicates without touching its underlying capabilities.
What makes this feature powerful is that it replaces Claude Code's entire system prompt personality while preserving all its tools and abilities. Think of it as changing the voice without changing the brain.
What Changes and What Stays the Same
Everything that stays intact when you switch styles:
CLAUDE.mdproject context system- Full tool ecosystem (file operations, Bash, editors, and more)
- Sub-agent and Custom Agent delegation
- MCP server integrations
- Context management and compaction
What the style controls:
- Response tone and formatting
- Domain assumptions and priorities
- Task approach methodology
- Interaction patterns
Using the Built-in Styles
How to Select a Style
To configure your output style in Claude Code, run the /config command:
# In Claude Code interactive mode
/config
# Select "Output style" from the menuYour selection is saved to .claude/settings.local.json at the project level, so you can use different styles for different projects.
Default Style
The Default style is the standard system prompt optimized for completing software engineering tasks efficiently. It's concise, practical, and the right choice for most experienced developers who just want to get things done.
Explanatory Style
The Explanatory style inserts educational "Insights" between coding actions. It's ideal when you're exploring a new codebase for the first time or trying to understand the reasoning behind architectural decisions.
# Example: Requesting a refactor with Explanatory style
> Optimize the database queries in this file
# Claude's response includes:
# 💡 Insight: This file exhibits an N+1 query problem.
# Instead of issuing individual queries inside a loop,
# a JOIN or subquery approach fetches all data in one
# round trip, reducing latency significantly.
#
# [Proceeds with actual refactoring]Learning Style
The Learning style turns Claude into a coding coach. Rather than doing everything for you, it prompts you to write small, strategic pieces of code yourself. This is perfect for developers looking to level up their skills.
# Example: Adding error handling with Learning style
> Add error handling to this API endpoint
# Claude's response:
# 💡 Insight: A try-catch block should wrap the main
# logic, and the catch block should return an appropriate
# HTTP status code with the error message.
#
# Try adding the try-catch block yourself first.
# Hint: Use the error object's message property to
# construct the response body.
#
# Share your code when you're ready and I'll review it.Creating Custom Output Styles
When the built-in styles don't fit your workflow, you can create your own as Markdown files.
Where to Place Style Files
Custom styles can live at two levels:
# User level (shared across all projects)
~/.claude/output-styles/my-style.md
# Project level (specific to one project)
.claude/output-styles/my-style.md
Basic Structure of a Custom Style
---
name: concise-engineer
description: Minimal, straight-to-the-point responses
---
You are a senior software engineer who values brevity.
## Response Rules
- Lead with the code change, not the explanation
- Summarize changes in short bullet points
- Always include language identifiers in code blocks
- Skip greetings and unnecessary preamble
- State the reasoning in one line before implementation
## Code Conventions
- Use descriptive variable and function names (camelCase)
- Include inline comments only for complex logic
- Assume TypeScript strict mode by defaultPractical Custom Style Examples
1. Code Reviewer Style
---
name: code-reviewer
description: Responds with a code review mindset
---
You act as a senior code reviewer.
## Review Priorities
When asked to make changes, analyze the code through these lenses
before implementing:
1. **Security**: Input validation, SQL injection, XSS risks
2. **Performance**: Unnecessary loops, N+1 queries, memory leaks
3. **Readability**: Naming conventions, function length, separation of concerns
4. **Testability**: Mockable design, dependency injection
List improvement points concisely before making changes.
Flag critical issues with ⚠️.2. Architect Style
---
name: architect
description: Responds from a system design perspective
---
You are a software architect.
## Design Principles
- Apply SOLID principles to design decisions
- Make tradeoffs explicit (e.g., "speed vs. readability")
- Always consider scalability implications
- Explain how changes affect the broader system
## Response Format
1. Design decision summary (1-2 lines)
2. Rationale and tradeoffs
3. Implementation code
4. Future extension points (when applicable)3. Documentation-First Style
---
name: documenter
description: Prioritizes documentation alongside code changes
---
Include the following documentation with every code change:
- JSDoc/TSDoc comments (functions, classes, types)
- Inline comments (complex logic only)
- Change summary with a suggested commit message
If README.md needs updating, include the diff.Distributing Styles Through Plugins
For teams that want consistent Claude Code behavior across all members, output styles can be packaged and distributed as plugins.
Defining Styles in a Plugin
my-team-plugin/
├── .claude-plugin/
│ └── plugin.json
└── output-styles/
├── team-standard.md
└── pr-review.md
Reference the styles directory in plugin.json:
{
"name": "my-team-styles",
"version": "1.0.0",
"description": "Team-standard output styles for Claude Code",
"outputStyles": "./output-styles/"
}Once the plugin is installed, your team's custom styles automatically appear in the /config style selection menu. This ensures everyone on the team gets a consistent experience without manual file copying.
Recommended Configurations by Use Case
Starting a New Project
When building a new codebase from scratch, stick with the Default style. It generates code quickly with minimal overhead, which is exactly what you need during rapid iteration.
Understanding an Existing Codebase
When joining a project for the first time, switch to the Explanatory style. The educational insights it provides alongside code changes can dramatically accelerate your onboarding process by explaining framework patterns and architectural decisions in context.
Mentoring Junior Developers
The Learning style works as an always-available coding mentor. Instead of writing all the code, it provides hints and prompts the developer to write strategic portions themselves, building real understanding.
Automated Code Review
Create a custom code-reviewer style and use it for self-review before submitting pull requests. It catches security vulnerabilities, performance issues, and code quality problems before they reach your team.
Advanced Techniques
Programmatic Style Switching
In CI/CD pipelines or automation scripts, you can switch styles programmatically:
# Directly update settings.local.json
cat > .claude/settings.local.json << 'EOF'
{
"outputStyle": "concise-engineer"
}
EOF
# Run Claude Code in non-interactive mode
claude -p "Refactor this file for better performance" --output-format stream-jsonCombining with CLAUDE.md
Output styles and CLAUDE.md serve complementary roles:
- CLAUDE.md: Project-specific rules and context ("Use Jest for tests", "API responses follow this schema")
- Output Styles: General response behavior ("Be concise", "Review before implementing")
# Example CLAUDE.md
## Project Rules
- Package manager: pnpm
- Commit messages: Conventional Commits format
- Maintain 80%+ test coverage
# Output style separately controls response toneBy configuring both appropriately, you can manage project technical constraints and communication style independently.
Wrapping Up
Claude Code's output styles transform the AI pair programming experience by giving you full control over how Claude communicates. Start by trying the three built-in styles — Default, Explanatory, and Learning — and create custom styles when you need something more tailored.
For teams, distributing styles as plugins ensures everyone benefits from a consistent, high-quality interaction pattern with Claude Code.
Get started by running /config and switching styles. Once you feel the difference, create your first custom style in ~/.claude/output-styles/ and make Claude Code truly your own.
For more details, refer to the official Output Styles documentation. You might also find our guides on [hidden power tips for Claude Code]((/articles/claude-code/claude-code-hidden-power-tips) and [Claude Code Hooks automation]((/articles/claude-code/claude-code-hooks-automation) helpful as well.