Anthropic built Claude Code as a terminal tool that reads the CLAUDE.md file in the project directory by default. This file can contain code style instructions, framework preferences, and function naming conventions. Boris Cherny from Anthropic describes it as “the only configuration file you really need.” Most users, however, do not dig deeper - and beneath the surface awaits a host of mechanisms that the official documentation does not mention. As Arpan Patel writes in his guide, there is an entire layer of hidden configurations that drastically change the way you work with the tool.
TL;DR: Claude Code has hidden configuration layers not found in Anthropic’s official documentation. The CLAUDE.md file can have a local version (.claude/CLAUDE.local.md), there is a system of reusable Skills, commands like /goal and /insights let you control session flow, and MCP plugins extend the tool’s capabilities with external data sources. As Arpan Patel notes, Anthropic keeps these features in experimental mode without full documentation.
How to write CLAUDE.md so that Claude Code actually listens?
The CLAUDE.md file is the main point of contact between the developer and Claude Code’s behavior. Boris Cherny from Anthropic recommends keeping it under 200 lines and dividing it into clear sections: code style, project architecture, tests, dependencies. A file that is too long causes the model to ignore the later sections - this behavior stems from context window limitations. Arpan Patel confirms that the best users keep this file concise and up to date.
Additionally, it is worth including specific code examples in CLAUDE.md rather than abstract rules. Instead of “use TypeScript,” it is better to write “every new file must have a .ts extension and use strict mode.” The model responds better to concrete instructions. This is a fundamental principle of prompt writing.
Furthermore, sections should be separated with markdown headers - Claude Code parses the file structure and treats headers as context separators. Therefore, a readable file structure translates into better results.
What is CLAUDE.local.md and why should you use it?
In addition to the main CLAUDE.md, there is a .claude/CLAUDE.local.md file that allows for environment-specific configuration. Arpan Patel explains that this file should not be committed to the git repository - it contains local preferences: SDK paths, development environment configuration, editor preferences. This solution resolves the problem of conflicts between team members.
In practice, it works like this: the main CLAUDE.md defines team standards, while CLAUDE.local.md stores individual configuration. For example, one developer may prefer running tests through Docker, while another uses a local environment. Each defines this in their local file.
Additionally, the local file allows experimenting with configuration without the risk of affecting the rest of the team. You can test different style instructions, check how the model responds to specific phrasing, and then move proven solutions to the main file.
How do Skills work and why do they change the workflow?
Skills are reusable instruction blocks stored in the .claude/skills/ directory. Each skill is a separate markdown file that Claude Code loads on demand. Arpan Patel provides examples: a skill for code review, a skill for writing unit tests, a skill for generating API documentation. Instead of repeating the same instructions in CLAUDE.md, you extract them into separate files.
This approach has two advantages. First, it reduces the size of the main configuration file - the model has less text to process with each query. Second, it allows layered context loading: you activate only the skills needed for a specific task.
The mechanism is simple. A skill is a .md file in the appropriate directory. Claude Code recognizes it automatically and integrates it into the current session context. I recommend starting with one simple skill - for example, for code review - and gradually building a library.
Which Claude Code commands are underrated?
The /goal command lets you define the session’s objective before starting work. Instead of entering ad-hoc commands, you specify upfront: “I want to refactor the authentication module to the Repository pattern.” Claude Code sticks to this goal throughout the session, reducing the risk of context drift. Arpan Patel confirms that this is one of the least used commands.
Meanwhile, /insights generates a summary of what Claude Code has learned during the session. This is useful for long tasks where the model performs dozens of steps - the summary lets you verify whether the tool has stayed on course.
Below is an overview of underrated commands and their applications:
| Command | Application | When to use |
|---|---|---|
| /goal | Defines the session objective | At the start of any longer work |
| /insights | Session summary | After completing a task or midway through |
| /compact | Compresses context | When the session becomes long |
| /cost | Checks token cost | Before deciding to continue |
The /compact command is particularly worth using frequently. When a session exceeds several dozen exchanges, the context grows and the model begins to lose earlier instructions. Compression preserves the most important information while reducing token consumption. As Blake Crosley writes in his guide, this is a fundamental cost optimization technique.
How to configure MCP so that Claude Code talks to external tools?
Model Context Protocol is a mechanism that allows Claude Code to communicate with external data sources. Through MCP, you can connect databases, APIs, file systems, and even other AI models. Arpan Patel describes this as “a bridge between Claude’s isolated environment and the rest of the world.”
Configuring MCP requires adding appropriate entries to the configuration file. For example, to connect a PostgreSQL database, you define the connection in the MCP configuration and Claude Code automatically gains the ability to execute SQL queries. This eliminates the need to manually copy data between tools.
However, it is worth being cautious with permissions. MCP gives Claude Code access to external systems, so you should carefully control what the tool can do. I recommend starting with read-only access and gradually expanding permissions as you build trust in the configuration.
For more on configuring Claude Code, read Claude Code Overview - Claude Code Docs. For tracking current changes in the tool, see Changelog - Claude Code Documentation.
What environment variables give you control over Claude Code’s behavior?
Claude Code has a number of environment variables that allow you to fine-tune its operation without modifying code. As Blake Crosley describes in his guide, variables such as CLAUDE_CODE_MAX_TOKENS or CLAUDE_CODE_MODEL let you control the model and generation limits. These variables are configured in a .env file or directly in the terminal before launching the tool.
Here are the key environment variables listed in the documentation:
CLAUDE_CODE_MODEL- allows forcing a specific model (for example, claude-sonnet-4-20250514)CLAUDE_CODE_MAX_TOKENS- controls the token limit in responsesCLAUDE_CODE_TEMPERATURE- regulates response determinismDISABLE_PROMPT_CACHING- disables prompt cachingCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC- blocks telemetry
Therefore, it is worth checking the current list of variables in the tool’s repository. Anthropic regularly adds new options that may not yet have official documentation.
What hooks does Claude Code allow you to define?
Hooks are a mechanism that allows you to run custom scripts at specific points in the Claude Code lifecycle. Blake Crosley describes hooks as an attachment point where a developer can inject validation logic, code formatting, or notifications. For example, a post-response hook can automatically run a linter after each model response.
Hook configuration is done in the .claude/settings.json file in the hooks section. Each hook defines an event and a shell command to execute. Moreover, hooks can modify the response before it is displayed.
| Hook event | When it runs | Example use case |
|---|---|---|
| pre-request | Before sending to the API | Prompt validation |
| post-response | After receiving a response | Automatic linting |
| on-error | When an error occurs | Slack notification |
| on-file-change | When a file changes | Dev server restart |
Although hooks offer significant flexibility, caution is warranted. Scripts run by hooks have access to the file system. Therefore, it is worth limiting their permissions to a minimum.
How to create a custom subagent in Claude Code?
Subagents are specialized instances of Claude Code launched within the main session. Arpan Patel describes subagents as a way to separate tasks - for example, one subagent handles tests while the main session writes code. Creating custom subagents requires defining them in the .claude/agents/ directory as markdown files with instructions.
Each subagent file specifies the role, constraints, and available tools. For example, a code review subagent may have read-only access to files and the git diff command. This approach enables building pipelines where different tasks are performed by specialized agents.
An example subagent structure looks like this:
- A
.claude/agents/reviewer.mdfile with a role description and instructions - Definition of available tools (for example, read-only file access)
- Context constraints (for example, max 10 files per session)
- Output instructions (response format)
Thus, subagents enable building complex workflows without duplicating instructions in the main CLAUDE.md.
Why can Claude Code costs grow quickly?
Microsoft burned through its annual budget for Claude Code licenses in five months. As reported by ithardware.pl, the company plans to withdraw licenses due to uncontrolled cost growth. This shows that without proper configuration and limits, the tool can generate significant expenses, especially with large teams and long sessions.
The main cost factor is context. Every exchange in a session adds tokens to the history, and the model processes the entire history with each query. This is why the /compact command is so important - it reduces context and lowers the cost of subsequent exchanges.
Additionally, MCP and hooks can generate extra API calls. For example, a post-response hook triggered after every response adds another query. Therefore, it is worth monitoring token consumption through the /cost command.
In practice, costs are controlled through several mechanisms:
- Regular use of
/compactevery 20-30 exchanges - Defining clear goals through
/goalat the start of a session - Limiting the number of active MCP connections and hooks
- Monitoring costs through
/costbefore continuing - Setting environment variables that limit tokens
What workflow patterns does the Anthropic team recommend?
Boris Cherny from Anthropic, the creator of Claude Code, recommends a specific approach to working with the tool. As reported by Business Insider, Cherny advises 22-year-old computer science graduates to start startups because “this is a golden age.” This philosophy translates to Claude Code’s design - the tool is meant to be a partner in creation, not just an assistant.
The Anthropic team uses several patterns internally. First, sessions start with /goal and a clearly defined objective. Second, context is compressed regularly through /compact. Third, skills and subagents are extracted into separate files to keep CLAUDE.md concise. Arpan Patel confirms that this pattern is the most effective in daily work.
Moreover, Anthropic recommends an iterative approach to configuration. Instead of creating the perfect CLAUDE.md from the start, it is better to begin with a minimal version and expand it as needed. Local .claude/CLAUDE.local.md files allow for experimentation without affecting the team.
For practical application examples, see Beyond the Prompt: Claude Code by Arpan Patel.
Frequently Asked Questions
How many lines should the CLAUDE.md file have?
Boris Cherny from Anthropic recommends keeping the CLAUDE.md file under 200 lines. Exceeding this value causes the model to ignore the later sections of the file due to context window limitations.
How often should you use the /compact command?
Blake Crosley recommends context compression every 20-30 exchanges. Regular use of /compact reduces token consumption and prevents context drift during long sessions.
Can Claude Code operate without supervision?
As reported by AI Weekly, Claude Code can perform tasks unsupervised for about two hours. However, this requires a clear goal defined through /goal and regular verification of results.
Where should Claude Code skills be stored?
Skills are stored in the .claude/skills/ directory as separate markdown files. Arpan Patel confirms that this approach reduces the size of the main CLAUDE.md and enables layered context loading.
Summary
Claude Code offers far more capabilities than the official documentation suggests. The CLAUDE.md file is just the beginning - true control over the tool lies in environment variables, hooks, subagents, and the CLAUDE.local.md file. The Anthropic team uses these mechanisms internally but does not fully document them publicly.
Key takeaways from this overview:
- The CLAUDE.md file should have a maximum of 200 lines with specific instructions
- Environment variables allow control over the model, token limits, and telemetry
- Hooks run custom scripts at specific points in the Claude Code lifecycle
- Subagents enable distributing tasks among specialized instances
- Costs are controlled through
/compact,/goal, and monitoring via/cost
The Microsoft example shows that uncontrolled use of Claude Code can quickly burn through a budget. Therefore, it is worth starting with a basic configuration and gradually adding advanced mechanisms. For more on session management, see claude-warmup: managing the 5-hour Claude Code window, and for an alternative approach to the tool, see claw-code: claude code rewritten from scratch (open-source).