The Claude Code Configuration Playbook: From Permissions to Progressive Disclosure

SettingsDesign

Most people open Claude Code, type a prompt, and wonder why they get generic output. The problem is never the model. It is always the setup.

A CPO at a $2.6B company runs a single Claude Code command that plans his entire workday (from claude code daily workflow vibePM). A solo founder operates 35 AI agents organized into seven departments from a single .claude folder (from one person startup claude agents). A non-programmer consultant built a full AI Chief of Staff in 36 hours by writing markdown files, not code. The difference between these operators and the person waiting for Claude to ask permission on every file read is not intelligence or programming ability. It is configuration.

This guide covers every layer of that configuration — from the three settings.json lines that unlock autonomous operation, through the context architecture that lets 10-word prompts produce client-ready output, to the state-machine skill patterns that power users build at 1,400 lines deep. The meta-lesson from 400+ Claude sessions is that system engineering beats prompt engineering — investing two hours in setup means every subsequent interaction is frictionless (from claude cowork context architecture checklist).

The Three-Layer Model

Claude Code configuration operates at three distinct layers, each building on the one below. Get the foundation wrong and nothing above it matters. Get it right and the whole system compounds.

Layer 1: Environment — the physical setup. Bypass permissions, audio hooks, editor integration, terminal layout. This is the hardware layer. You configure it once and never touch it again.

Layer 2: Context Architecture — the knowledge layer. CLAUDE.md, rules files, manifests, memory systems. This is where you teach Claude who you are, what your project does, and how you work. It persists across sessions and compounds over time.

Layer 3: Skill Design — the expertise layer. Progressive disclosure, state machines, extension mechanisms. This is where you encode workflows, judgment, and domain knowledge into reusable patterns.

Most people stop at Layer 1 (if they configure anything at all). Power users invest heavily in Layer 2 and treat Layer 3 as their primary competitive advantage.

Layer 1: Environment — The Physical Setup

Bypass Permissions: The Non-Negotiable First Step

The single most important configuration change you will make is enabling bypass permissions. Without it, Claude asks for confirmation on every file write, every bash command, every web search. When you are running four to six parallel sessions — one writing a plan, one building from a different plan, one running research, one fixing a bug — permission prompts make context-switching impossible (from every claude code hack mvanhorn).

Add this to ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["WebSearch", "WebFetch", "Bash", "Read", "Write", "Edit", "Glob", "Grep", "Task", "TodoWrite"],
    "deny": [],
    "defaultMode": "bypassPermissions"
  },
  "skipDangerousModePermissionPrompt": true
}

The critical line is skipDangerousModePermissionPrompt: true. Without it, Claude still asks you to confirm bypass mode at the start of every session — defeating the entire purpose (from every claude code hack mvanhorn). The flag name --dangerously-skip-permissions is deliberately scary, a UX pattern that makes the footgun obvious so you opt in consciously rather than accidentally (from claude code desktop skip permissions).

You can toggle bypass mode within a session using Shift+Tab. The allow/deny lists give you fine-grained control: allow build and test commands freely, deny destructive commands like rm -rf and sensitive file reads like .env (from claude folder anatomy).

This is non-negotiable for autonomous workflows. The demand signal is clear — 957 likes on the feature announcement alone, and every power user workflow documented in the community assumes bypass is enabled (from claude code desktop skip permissions). If you are still clicking "Allow" on every action, you are operating Claude Code as an interactive assistant when it should be a background worker.

Audio Hooks: Ambient Awareness for Parallel Sessions

Once you have bypass permissions enabled and Claude is running autonomously in multiple terminals, you need a way to know when sessions finish without watching them. Sound hooks solve this:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "afplay /System/Library/Sounds/Blow.aiff"
      }]
    }]
  }
}

This plays a system sound every time Claude finishes a task. Essential when running four to six parallel sessions — you hear which one just completed and switch to it (from every claude code hack mvanhorn).

But the real insight goes beyond utility. Delba Oliveira's viral tip (5.2K likes) was not just to add sound hooks — it was to add your favorite childhood game sounds. Starcraft "work complete" when a task finishes. Warcraft peon sounds when Claude needs permission. Mario coin sounds for successful commits (from claude hooks sound alerts). This is not frivolous. Making the developer experience joyful drives adoption. When your tools are fun, you use them more, which means you configure them better, which means your output improves. The hooks system is becoming an extensibility surface for developer culture, not just functionality.

The hook configuration goes in the same ~/.claude/settings.json file. You can add custom sound files to any accessible path — download your preferred game sounds and point afplay at them. On macOS, /System/Library/Sounds/ has built-in options if you want something working in 30 seconds.

Zed Autosave: The Google Docs Collaboration Experience

The editor integration that makes Claude Code feel collaborative rather than transactional is Zed with aggressive autosave:

{ "autosave": { "after_delay": { "milliseconds": 500 } } }

Set this in Zed's settings (Cmd+, in Zed). With 500ms autosave, Zed saves every half-second. Claude Code watches the filesystem. Changes appear in Zed instantly — Claude's edits materialize in your editor in real time, and your typing is visible to Claude within a second. Run Ghostty on one half of the screen, Zed on the other. It feels like collaborating on a Google Doc, except one collaborator is an AI (from every claude code hack mvanhorn).

This setup matters because it changes the interaction model from "command and wait" to "continuous co-editing." You can see Claude working. You can type in the same file. You can catch problems in real time instead of reviewing a finished diff. The cognitive load drops dramatically when you can watch the work happening.

The Physical Layout

The ideal Claude Code physical setup is:

If you are on a Mac Mini for remote access, add tmux so sessions survive bad WiFi. Telegram integration lets you send commands from your phone — /ce:plan fix the timeout issue from dinner, plan waiting in Zed when you get home (from every claude code hack mvanhorn).

Effort Levels

Claude Code changed its default effort level from high to medium, based on observed median usage patterns. The reasoning: medium balances intelligence with speed for the majority of tasks (from claude code effort levels).

Effort is configurable via the /model selector with three tiers: low (faster), medium (default), and high (more intelligence). The setting is sticky — it persists across sessions. Switch to high for complex architecture decisions, drop to low for routine file operations.

A critical warning from the Claude Code team: confusing or conflicting instructions in CLAUDE.md files are the most common cause of unexpected behavior when effort is set to high (from claude code effort levels). If Claude seems to be ignoring instructions or producing inconsistent output at high effort, check your CLAUDE.md for contradictions before blaming the model. This connects directly to the next layer — your context architecture determines your output quality at every effort level.

Layer 2: Context Architecture — Teaching Claude Who You Are

CLAUDE.md: The Most Important File in the System

When Claude Code starts a session, the first thing it reads is CLAUDE.md. It loads it into the system prompt and holds it in context for the entire conversation. Whatever you write in CLAUDE.md, Claude follows. This is the highest-leverage file in your entire configuration — get it right and everything else becomes optimization (from claude folder anatomy).

The hard constraint: keep CLAUDE.md under 200 lines. Files longer than that eat too much context and Claude's instruction adherence actually drops (from claude folder anatomy). This is not a suggestion. Long instruction files create the exact contradictions and ambiguity that the Claude Code team identified as the primary cause of degraded output (from claude code effort levels).

What goes in CLAUDE.md:

What does not go in CLAUDE.md: reference material, templates, code examples, long explanations, per-directory rules, or anything that belongs in a separate file. Every line in CLAUDE.md is loaded into every session. If it does not apply to every session, it belongs somewhere else.

The power of declarative one-liners is underappreciated. A single line — "When you complete work, log it to memory/weekly-recaps/current-week.md" — turns Claude into a persistent work logger that automatically maintains a weekly recap. By Friday you have a full week log without writing anything yourself. Two-minute setup, permanent value (from weekly recap agent memory). This demonstrates the ideal CLAUDE.md instruction: short, specific, behavioral, always-applicable.

Two .claude Directories: Team vs. Personal

There are two .claude directories, not one. Understanding the split is essential for team configuration.

Project-level .claude/ lives in your repo root, gets committed to git, and is shared with your entire team. This holds team configuration: shared rules, common commands, project-specific skills, and the project's CLAUDE.md.

User-level ~/.claude/ lives in your home directory and holds personal preferences, session history, and machine-local state. This is where your global settings.json, personal commands, and auto-memory live (from claude folder anatomy).

For personal overrides that should not affect the team, use CLAUDE.local.md in your project root. Claude reads it alongside the main CLAUDE.md, and it is automatically gitignored so your personal tweaks never land in the repo. The same pattern exists for settings.local.json — personal permission overrides that stay local (from claude folder anatomy).

This separation is critical for teams. The project CLAUDE.md contains the conventions everyone follows. Your CLAUDE.local.md contains your personal workflow preferences (voice mode, preferred tools, auto-formatting settings) that should not be imposed on teammates.

The .claude/rules/ Directory: Modular, Scoped Instructions

For instructions that only apply in certain contexts, use .claude/rules/. Every markdown file in this directory gets loaded alongside CLAUDE.md automatically. But the real power is path-scoped rules — add a YAML frontmatter block with a paths field and the rule only activates when Claude is working with matching files (from claude folder anatomy).

Example: a rule file .claude/rules/api-conventions.md with frontmatter paths: ["src/api/**"] only loads when Claude is editing API files. A rule file .claude/rules/test-patterns.md with frontmatter paths: ["**/*.test.ts"] only loads when editing tests.

This solves the 200-line CLAUDE.md problem elegantly. Instead of cramming every instruction into one file, you split by concern and scope. API conventions load when working on APIs. Test patterns load when writing tests. Database rules load when touching migrations. The base CLAUDE.md stays slim and universal while domain-specific instructions appear exactly when needed.

The Three-Tier Manifest: Prioritized Context Loading

For projects with extensive documentation, a _MANIFEST.md file creates a prioritized loading order using three tiers (from claude cowork context architecture checklist):

Your global CLAUDE.md instructions should tell Claude to read the manifest first, load only Tier 1 files, and ask clarifying questions before starting work. This prevents context overload — Claude reads what matters instead of everything (from claude cowork context architecture checklist).

The manifest pattern works because it encodes institutional knowledge about what matters. A new team member reading every file in the docs directory will be overwhelmed. A team member who reads the top five documents in priority order will be effective in a day. Claude operates the same way — give it a prioritized reading list and it produces better output with less context consumed.

The Minimum Viable Context Setup

If you are starting from zero, the minimum viable context setup is three markdown files (from claude cowork context architecture checklist):

  1. about-me.md — your role, current priorities, and one or two examples of your best work. This grounds Claude in who it is working for.
  2. brand-voice.md — your tone, two or three samples of your writing, and phrases you hate. This prevents generic AI-voice output.
  3. working-style.md — guardrails like "ask before executing," "show plan first," "never delete without confirmation."

These three files, loaded into Claude's global instructions, take about 30 minutes to create and produce an immediate, noticeable improvement in output quality. Content drafts that previously required three revision rounds land on the first try once Claude has pre-loaded context about your identity, voice, and working preferences (from claude cowork workspace setup system).

The gap between generic and executive-level Claude output is entirely a context problem, not a model capability problem. Most users start from scratch every session instead of pre-loading context. Fixing this is the single highest-ROI activity in Claude Code configuration (from claude cowork workspace setup system).

Building a Persistent Memory System

Context architecture is not a one-time setup. The best configurations compound over time through persistent memory.

Josh Pigford built a hyper-personalization system using nothing but plain text Markdown files — USER.md (identity, schedule, preferences), MEMORY.md (curated long-term memory updated each session), and a directory of per-person files. No database. No vector store. No proprietary format (from shpigford hyper personalization ai).

The breakthrough pattern is the daily drip: a cron job that asks one thoughtful personal question per day, processes the answer, and files it to the right place. After six weeks of daily questions, the AI transitions from a transactional assistant to a collaborative partner that stops asking clarifying questions because the answers are already in files it reads at session start (from shpigford hyper personalization ai).

Effective AI memory should be curated and distilled — decisions made, lessons learned, opinions expressed — not a raw conversation log. The AI reads MEMORY.md every session and updates it when something worth remembering happens (from shpigford hyper personalization ai). This matches the CLAUDE.md philosophy: concise, high-signal, always-loaded context beats verbose logs that dilute attention.

An onboarding interview (10-15 minutes of structured dialogue, not a survey) gets you to roughly 60% coverage of personal context. The remaining depth comes from incremental daily questions that surface context you would never think to volunteer — morning routines, coffee preferences, communication styles with specific colleagues (from shpigford hyper personalization ai). The daily drip adds more useful context after six weeks than the initial setup.

The 8-Phase Bootstrap

For a comprehensive workspace setup, JJ Englert's 8-phase bootstrap prompt systematically interviews you to build an entire workspace (from claude cowork workspace setup system):

  1. Plugins and Connections — install integrations (Slack, Gmail, Calendar, Notion)
  2. About Me — role, priorities, work samples
  3. Brand Voice — tone, writing samples, anti-patterns
  4. Working Preferences — guardrails, approval requirements, risk tolerance
  5. Content Strategy — what you create, for whom, in what format
  6. Team and Contacts — key people, their roles, communication preferences
  7. Active Projects — current work, status, deadlines
  8. Memory System + Skill Files — persistent memory structure, per-folder skill configurations

Each phase builds on the previous ones. By the end, Claude has comprehensive context about you, your work, your team, and your preferences. The result: sessions feel like picking up a conversation with an executive assistant who already knows everything about your situation (from claude cowork workspace setup system).

Layer 3: Skill Design — Encoding Expertise

The Six Extension Mechanisms

Before designing skills, understand Claude Code's six distinct extension mechanisms. Each solves a different problem, and using the wrong one creates unnecessary complexity (from claude code extensions crash course):

Plugins are packaged workflows from the marketplace — app-store model where third parties bundle complete customizations. Install them, they work. Examples: Compound Engineering, Ralph Wiggum. Use plugins for established workflows you want to adopt wholesale.

Skills are on-demand knowledge files that Claude loads into context when the task matches the skill's description. Each skill lives in its own subdirectory with a SKILL.md file. The key difference from commands: skills can bundle supporting files alongside them. Skills are packages. Use skills for domain expertise, specialized workflows, and reference material (from claude folder anatomy).

MCPs (Model Context Protocol) connect Claude to external tools, apps, and services. They enable Claude to access information and take actions on databases, infrastructure, and SaaS tools. Examples: Supabase, Linear, Slack, Vercel. Use MCPs for any integration that requires talking to an external API (from claude code extensions crash course).

Commands are single markdown files that become slash commands. A file named review.md in .claude/commands/ creates /project:review. Use $ARGUMENTS to pass text after the command name. Project commands in .claude/commands/ are committed and shared with the team. Personal commands go in ~/.claude/commands/ (from claude folder anatomy). Use commands for prompt shortcuts and repetitive workflows.

Subagents are role-specific personas defined in .claude/agents/. Each agent markdown file has its own system prompt, tool access restrictions, and model preference. The tools field restricts what the agent can do. The model field lets you use a cheaper, faster model for focused tasks — Haiku for read-only exploration, for instance (from claude folder anatomy). Use subagents for delegated tasks that benefit from a specialist persona.

Hooks are scripts that run automatically before or after Claude Code actions. They add determinism and consistency: run tests before committing, block dangerous commands, run formatters and linters (from claude code extensions crash course). Hooks are the lifecycle automation layer — they fire without human intervention.

The distinction between skills, MCPs, and hooks is the most important one to internalize. Skills are for reusable prompts and domain knowledge. MCPs are for tool integrations with external services. Hooks are for lifecycle automation that should happen every time without thinking (from claude code daily workflow vibePM). Mixing these up — putting hook logic in a skill, or MCP configuration in CLAUDE.md — creates confusion and maintenance burden.

Progressive Disclosure: The 89% Context Reduction

The most impactful skill design pattern is progressive disclosure. Zara Zhang's Frontend Slides skill went from 1,625 lines loaded every time to 183 — an 89% reduction in context bloat with zero loss of functionality (from progressive disclosure claude skills).

The principle: treat your instruction file like a table of contents, not a textbook. Put the rules up front. Put the reference material in separate files the agent reads only when it needs them (from progressive disclosure claude skills).

Before progressive disclosure:

SKILL.md (1,625 lines)
├── Rules and decision logic (200 lines)
├── Templates for 8 output types (400 lines)
├── Example outputs (500 lines)
├── Edge case handling (300 lines)
└── Style reference (225 lines)

After progressive disclosure:

SKILL.md (183 lines)
├── Rules and decision logic (150 lines)
├── Decision tree: "If output type is X, read templates/X.md"
└── Quick reference table (33 lines)

templates/
├── slide-deck.md
├── landing-page.md
└── ... (loaded on demand)

examples/
├── good-output.md
├── bad-output.md
└── ... (loaded on demand)

reference/
├── edge-cases.md
└── style-guide.md (loaded on demand)

The 89% reduction matters because context is finite and expensive. Every line in a skill file competes with the actual task content for space in Claude's context window. A skill that loads 1,625 lines of instructions before seeing the user's request has already consumed significant capacity. A skill that loads 183 lines of decision logic and then selectively reads reference material only as needed preserves context for the work itself.

The analogy from the original author: it is the difference between handing a new hire a 30-page briefing document versus a 2-page summary with "see appendix B for details" (from progressive disclosure claude skills). The new hire (Claude) gets oriented quickly, then pulls reference material as questions come up rather than trying to memorize everything upfront.

Skills as State Machines

At the advanced end, power users build skills as complex state machines. Brad Feld's /start command is a 1,400-line markdown file with 15 sequential steps. When he mapped the data dependencies between steps, he found 12-22 seconds of removable overhead from defensive machinery that had accumulated during development but was no longer necessary (from claude skill state machine optimization).

The mental model: treat each step in a skill as a node in a state machine with explicit input/output contracts. Step 3 requires the output of steps 1 and 2. Step 7 requires the output of steps 4 and 6 but not 5. By mapping these dependencies, you can identify:

Skills accumulate defensive machinery over time. During development, you add null checks, validation steps, and error handling for problems you encountered once. As the skill matures, many of these guards become redundant — the upstream step now guarantees the condition, or the edge case has been structurally eliminated. But the checks remain as performance drag because nobody audits them (from claude skill state machine optimization).

The prescription: periodically audit complex skills for dependency waste. Map the data flow between steps. Identify which checks are still necessary versus which are artifacts of past debugging. For a 15-step skill, this audit found 12-22 seconds of savings — meaningful when the skill runs multiple times per day.

This framing — skills as state machines with data dependencies — is an advanced mental model that enables systematic optimization. Most skill authors think linearly: step 1, then step 2, then step 3. State-machine thinking reveals parallelism opportunities and redundant constraints that linear thinking misses (from claude skill state machine optimization).

Skills That Control Output Format

A less obvious category of skills shapes how Claude communicates, not just what it does. The Visual Explainer skill transforms Claude Code's terminal text output into rich HTML pages with consistent design via reference templates and a CSS pattern library (from visual explainer agent skill).

The concept of "cognitive debt" from agent interactions is real: agents can do more, but if their output is hard to parse, the productivity gain is eroded by comprehension overhead. Squinting at walls of terminal text to find the relevant information in a 200-line response is a UI problem, and skills that solve it are a new and powerful category (from visual explainer agent skill).

Output-format skills include:

The pattern generalizes: any domain where you want consistent formatting, tone, or visual treatment across multiple Claude interactions is a candidate for an output-format skill.

Agent Department Architecture

For comprehensive coverage, Om Patel demonstrated a .claude folder with 35 agent markdown files organized into seven departments: engineering (frontend, backend, mobile, AI, devops, prototyper), product (trend researcher, feedback synthesizer, sprint prioritizer), marketing, design, project management, operations, and testing (from one person startup claude agents).

Each agent file has three sections:

  1. Instructions — what the agent does, its specific responsibilities
  2. Personality — how it communicates, its expertise persona
  3. Scope — boundaries of what it can and cannot touch

The testing department pattern is particularly instructive: dedicated agents for tool evaluation, API testing, workflow optimization, performance benchmarking, and test results analysis. This is not a single "test runner" — it is a QA team encoded as skill files, each with narrow scope and clear boundaries (from one person startup claude agents).

You do not need 35 agents to start. Begin with three or four covering your most common work types. Add agents as you identify repetitive patterns that benefit from a specialist persona. The architecture scales naturally because each agent is a standalone markdown file — adding one does not affect the others.

Design Configuration: Skills as Transferable Taste

The 3-Layer Design Harness

Design configuration in Claude Code follows a three-layer pattern: Skills transfer expertise, Canvases provide a working surface, and Inspiration tools train the eye. This harness lets engineers ship design without becoming designers (from design without designing neethanwu).

Skills layer — the most actionable part for configuration:

Canvas layer — surfaces where agents do design work:

Inspiration layer — feeding taste into the workflow:

The harness pattern is not specific to design. Any domain where you need expertise you do not personally possess can be structured the same way: skills for transferred judgment, a working surface for the agent, and reference material for taste calibration.

Visual Editing: Click Instead of Describe

Claude Code Desktop supports direct DOM element selection — click an element on your frontend instead of describing it in text. Claude receives the tag name, CSS classes, key styles, surrounding HTML context, and a cropped screenshot. For React apps, it also gets the source file path, component name, and current props (from claude code dom element selection).

A separate tool built by Quentin Romero Lauro creates a full Figma-like visual editor for Claude Code: select any element on your local frontend, edit it like you would in Figma, apply the changes through Claude Code (from figma for claude code). The 2.6K likes on this announcement signal strong latent demand for visual editing layers on top of AI coding tools.

The design-to-code gap is closing from both sides. Design tools are becoming code-native (Paper's HTML/CSS canvas). Code tools are becoming design-visual (DOM element selection, Figma-style editors). The convergence point is that designers and developers work in the same medium — code — with different interfaces layered on top.

Multimodal Input: Video Beats Text

For replicating existing designs, video input produces better results than text descriptions because it captures interaction patterns, spacing, animation, and component relationships that are difficult to articulate in words (from video to ui claude workflow).

The workflow: record a video of the target UI, upload it to Claude to get a markdown description of components and interactions, then feed that markdown to Claude Code to build it. The intermediate markdown artifact gives you a checkpoint to review and refine the AI's understanding before committing to code (from video to ui claude workflow).

The bottleneck in vibe-coding UIs is not the AI's coding ability but the human's ability to describe what they want. Video capture bypasses the vocabulary problem entirely. You do not need to know that a specific pattern is called a "disclosure panel" or a "skeleton loader" — you show it and Claude figures out the terminology.

Component Libraries Building for Agents

shadcn/cli v4 introduced "shadcn/skills" as a first-class concept, signaling that the component library ecosystem is building explicit support for AI coding agent workflows (from shadcn cli v4 skills). The release also adds presets, dry-run mode, and monorepo support — features that make component installation safe for automated pipelines.

This is a leading indicator. When the most popular component library (5.8K likes on the v4 announcement) explicitly targets coding agents as a primary audience, it means the toolchain is adapting to agent-driven development as the default workflow, not an edge case (from shadcn cli v4 skills).

Configure your project to use component libraries that are agent-friendly. shadcn with its CLI and skill support is currently the strongest option. The dry-run mode is particularly valuable for automated workflows — Claude can preview what a component install will change before committing to it.

Web Fetch: The Hidden Context Trap

One non-obvious configuration concern: Claude Code's web fetch tool uses a subagent architecture where a smaller model summarizes the full page content and returns only the summary to your main agent. This prevents context window overflow but can lose critical detail (from claude code web fetch summarizes).

This is a lossy operation disguised as a complete one. When you tell Claude to "read this documentation page," you might assume it has the full content. It does not — it has a summary generated by a smaller model that may have dropped the specific detail you needed.

The workaround: for pages where you need the full content, instruct Claude to save the page to a temp folder and analyze it in sections. This preserves detail at the cost of more steps (from claude code web fetch summarizes).

Situations where this matters:

Situations where the summary is fine:

The Configuration Lifecycle

Day One: Essential Setup (30 minutes)

  1. Enable bypass permissions in ~/.claude/settings.json
  2. Add a Stop hook with your preferred notification sound
  3. Configure Zed autosave at 500ms
  4. Write a CLAUDE.md under 200 lines with your identity, behavioral rules, and workflow patterns
  5. Create about-me.md, brand-voice.md, and working-style.md in your context directory

Week One: Project Configuration (2 hours)

  1. Create .claude/rules/ files for your main code areas (API, tests, frontend, etc.)
  2. Write a _MANIFEST.md with tiered document priorities
  3. Install one or two skills relevant to your daily work (Impeccable for design, Compound Engineering for planning)
  4. Set up a weekly recap logging instruction in CLAUDE.md
  5. Create two or three custom commands for your most repetitive workflows

Month One: Skill Development (ongoing)

  1. Audit your CLAUDE.md for contradictions or ambiguity
  2. Apply progressive disclosure to any skill files over 200 lines
  3. Start building agent personas for your three most common work types
  4. Set up a persistent memory system (MEMORY.md or equivalent)
  5. Map data dependencies in your most complex skill and eliminate redundant checks

Ongoing: The Compound Loop

The payoff of configuration is not linear — it compounds. Each context file you add makes every future session more effective. Each skill you refine makes the next project faster. Each memory entry makes Claude's responses more personalized.

After six weeks of accumulated context, something shifts. Claude stops asking clarifying questions because the answers are already in files it loaded at session start. Interactions shift from transactional to collaborative (from shpigford hyper personalization ai). This is the end state: not a tool you configure but a working partner that knows your preferences, your codebase, your team, and your judgment.

The two-hour investment in setup means subsequent prompts can be as short as 10 words and still produce client-ready output (from claude cowork context architecture checklist). That is the return on configuration: not faster prompts, but shorter ones that work better.

Quick Reference: File Locations and Purposes

File/Directory Location Purpose Scope
settings.json ~/.claude/ Permissions, hooks, global preferences All projects
settings.local.json .claude/ Personal project overrides This project, personal
CLAUDE.md Project root Core instructions (<200 lines) This project, team
CLAUDE.local.md Project root Personal instruction overrides This project, personal
.claude/rules/ Project root Path-scoped modular rules This project, team
.claude/commands/ Project root Project slash commands This project, team
~/.claude/commands/ Home directory Global slash commands All projects
.claude/skills/ Project root Packaged workflows with SKILL.md This project, team
.claude/agents/ Project root Subagent personas This project, team
_MANIFEST.md Project folders Tiered context loading order This project, team
MEMORY.md Context directory Curated persistent memory Personal

Common Mistakes and How to Fix Them

Mistake: CLAUDE.md over 200 lines. Move reference material to .claude/rules/ or skill files. Keep only universal behavioral rules in CLAUDE.md.

Mistake: Conflicting instructions across files. CLAUDE.md says "always add tests." A rule file says "skip tests for prototype code." Claude gets confused. Audit all instruction sources for contradictions — this is the number one cause of bad output at high effort (from claude code effort levels).

Mistake: Loading everything into context. Use manifests and progressive disclosure. Tier 1 loads always. Tier 2 loads on demand. Tier 3 stays archived. An 89% context reduction with no functionality loss is typical when you restructure monolithic files (from progressive disclosure claude skills).

Mistake: Treating web fetch as complete. Remember the subagent summarization. For critical pages, save locally and analyze in sections (from claude code web fetch summarizes).

Mistake: Putting hook logic in CLAUDE.md. "Run tests before committing" belongs in a hook (deterministic, automatic). "Consider running tests" in CLAUDE.md is a suggestion the agent may or may not follow. Use hooks for things that must always happen. Use CLAUDE.md for behavioral preferences.

Mistake: Never auditing skill files. Skills accumulate defensive machinery over time. Periodic dependency audits for complex skills recover meaningful performance (from claude skill state machine optimization).

Mistake: Skipping the memory system. Without persistent memory, every session starts cold. The daily drip pattern — one personal question per day, filed to the right place — compounds faster than any other configuration investment (from shpigford hyper personalization ai).

Sources Cited