// 116 tips in Configuration
Setting up and customising your Claude Code environment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.
Stop passing the same flags every time you launch Claude Code. Use claude config to set your preferred model, permission mode, and other defaults — at user level for personal preferences or project level for team-wide settings that everyone inherits automatically.
Unlike --system-prompt which replaces everything, --append-system-prompt layers additional instructions on top of your existing CLAUDE.md and default system prompt. Keep all your project context and just add a temporary constraint or focus area for one session.
Claude Code isn't just a terminal tool — official extensions for VS Code and JetBrains bring the same Claude Code experience directly into your editor. Get an inline chat panel, see diffs as they happen, and approve changes without leaving the IDE you already live in.
When running Claude Code in automation or headless mode, pass --max-turns to cap the number of agentic steps it takes before stopping. This prevents runaway operations, controls costs, and ensures Claude finishes within a predictable budget of actions.
You're not limited to a single CLAUDE.md at the project root. Drop additional CLAUDE.md files into subdirectories to give Claude module-specific context — different conventions for the frontend vs backend, special rules for a legacy module, or testing guidelines that only apply to one package.
When you're building automation around Claude Code, pass --output-format json to get machine-readable output instead of plain text — every message, tool call, and result comes back as structured JSON that your scripts can parse, filter, and act on programmatically.
Restrict which tools Claude has access to with --allowedTools and --disallowedTools — make Claude read-only by blocking Edit and Write, prevent command execution by blocking Bash, or whitelist only the specific tools a CI job needs. Fine-grained control for safety-conscious workflows.
Instead of writing a CLAUDE.md from scratch, run /init and let Claude analyze your project — it reads your directory structure, package files, config, and conventions, then generates a tailored CLAUDE.md with the right commands, architecture notes, and coding standards already filled in.
Claude Code normally works within your current directory, but --add-dir lets you bring in additional directories — shared libraries, sibling packages in a monorepo, a design system, or API specs from another project — so Claude can read and reference them alongside your code.