If you work in software development, you will surely have heard of agentic coding: a paradigm in which artificial intelligence doesn't just suggest code snippets, but acts like a true autonomous developer. It reads files, runs commands in the terminal, navigates the codebase, creates branches, runs tests, and fixes bugs—all without you having to dictate every single action.
Claude Code It's Anthropic's tool that embodies this philosophy. Born in February 2025 as a CLI capable of editing files and launching bash commands, it has evolved into an extensible platform with six distinct mechanisms: CLAUDE.md, skill, hook, subagent, Plugin e agent teamThe heart of it all, however, remains the CLAUDE.md file: the persistent memory that transforms Claude from a general assistant to a developer tailored to your specific project.
In this comprehensive guide, you'll learn how to configure Claude Code from A to Z. We'll cover how to write an effective CLAUDE.md, how to create custom skills, how to leverage subagents and hooks to automate workflows, and most importantly, how to avoid the most common mistakes that waste hours of work. Each section includes step-by-step instructions, concrete examples, and operational tips tested in production.
Before diving into the configuration, it's helpful to understand the breadth of what Claude Code can do. It's not just an assistant that suggests snippets: it's an agent with direct access to your operating system, filesystem, and network—and because of this, it has a granular permissions system you need to understand.
Claude Code was born as a terminal tool. It can execute any bash command: navigate the filesystem, install dependencies, launch builds and tests, manage processes, query databases, orchestrate Docker containers, and interact with Git (commit, branch, merge, push, create PRs). This makes it useful not only for writing code, but also for tasks system administration: analyze logs, debug network configurations, manage deployments, and automate DevOps operations. Anything you can do from the terminal, Claude can do—except it thinks in context and can chain dozens of operations together autonomously.
Claude Code is not tied to the standalone terminal. Anthropic has released aofficial extension for US Code (also compatible with Cursor, Windsurf and Trae) and a plugin for JetBrains (IntelliJ IDEA, WebStorm, PyCharm). The VS Code extension offers a native chat panel with plan reviews, auto-accept changes, file mentions with @, conversation history and the ability to open parallel sessions in separate tabs.
The JetBrains plugin provides a similar experience, with configuration shared via the same file ~/.claude/settings.jsonIn both cases, Claude Code sees open files, the current selection in the editor, and the output from the integrated terminal—eliminating the need to copy and paste between the IDE and the AI tool.
There is also one Browser-based IDE available claude.ai/code running in a cloud sandbox, and a standalone desktop app for parallel sessions via Git worktrees and remote sessions. Many developers take a hybrid approach: Cursor for inline refactoring and quick tab completion, and Claude Code for complex, multi-file automation tasks.
Since Claude Code has direct access to the filesystem and the terminal, the permit system It is a critical component. Claude Code offers four operating modes:
Normal Mode (default): Claude asks for confirmation before every sensitive operation—writing files, executing bash commands, making network calls. Ideal for new projects or unfamiliar codebases.
Schedule Mode: Read-only access. Claude can analyze and plan, but cannot modify anything. Perfect for audits and risk-free refactoring preparation.
Auto-accept ModeFile read and write operations are automatically approved, while shell commands still require confirmation. Speeds up routine work by about 40%.
Bypass Mode (--dangerously-skip-permissions): removes all confirmations. Use exclusively in controlled environments like Docker containers or CI/CD pipelines, never on the main development machine.
In addition to the modes, you can configure granular rules of allow/deny in the file settings.json, specifying patterns for individual commands. For example, you can automatically allow npm run test e git status, but block curl, rm -rf and file access .env:
// .claude/settings.json
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git status)",
"Bash(git diff *)"
],
"deny": [
"Bash(curl *)",
"Bash(rm -rf *)",
"Read(./.env)",
"Read(./secrets/**)"
]
}
}The rules follow a precise hierarchy: the global settings (~/.claude/settings.json) are overwritten by the project ones (.claude/settings.json), which in turn are overridden by CLI flags. The command /permissions During the session, it allows you to add or remove tools from the allowlist on the fly. One aspect not to be overlooked: the subagents inherit the parent's permission mode — if the main session is bypassed, every subagent will be bypassed as well.
The file CLAUDE.md It's a Markdown document that Claude Code automatically reads at the start of each session. It works like an onboarding manual for AI: it contains project information, coding conventions, commands to use, and architectural rules that you'd otherwise have to repeat every conversation.
Think of it as a configuration file which Claude automatically incorporates into every conversation, ensuring he always knows the project structure, coding standards, and the team's preferred workflows.
Claude Code loads CLAUDE.md files following a precise hierarchy. This cascading structure allows you to define global rules (applicable to all projects) and local rules (specific to a single project or subdirectory).
Global user level: the file in ~/.claude/CLAUDE.md It's read first and applies to every project. Ideal for personal style preferences, abbreviations, and cross-functional configurations.
Root level of the project: the file CLAUDE.md In the repository's root directory. This is where the tech stack, build/test commands, folder architecture, and team rules go.
Subdirectory levelCLAUDE.md files located in individual folders. They only activate when Claude is working in that specific area of the codebase. Perfect for modules with specific conventions.
💡 Pro Tip: The file name is case-sensitive. It must be exactly CLAUDE.md (all uppercase for CLAUDE, lowercase for .md). A file named claude.md or Claude.md will not be recognized.
Each line of your CLAUDE.md consumes tokens from the context window, the same budget that goes for source code, conversation, and system instructions. Community research indicates that frontier models can follow about 150-200 instructions coherently. Claude Code's system prompt already contains about 50 of them: this means you have room for no more than 100-150 additional instructions before quality begins to degrade.
A crucial aspect: degradation is uniform. It's not just the instructions at the bottom of the file that are ignored — they all lose their relevance as the number grows.
The golden rule is simple: if you remove a line and Claude makes no mistakes, that line was not neededAim to keep the root file under 200 lines. Some production teams work with fewer than 60.
The fastest way to get started is the command /initLaunch it in your project directory and Claude will analyze your codebase: it will read the package.json files, existing documentation, configuration files, and code structure, generating a custom CLAUDE.md.
# Nella directory del progetto
claude
> /initThe generated file will typically include build commands, test instructions, root directories, and detected conventions. However, treat it as a starting point, not a finished product: the result captures obvious patterns but may lack nuances specific to your workflow. Review what Claude produces and refine it based on your team's actual practices.
You can also use /init On projects that already have a CLAUDE.md: Claude will analyze the current file and suggest improvements based on what he has learned from exploring the codebase.
The most effective structure for a CLAUDE.md mirrors the way you would onboard a senior engineer joining the team. It is divided into three logical blocks.
A line or two that immediately orients Claude. There's no need for encyclopedic details: the application type, the main stack, and the scope are enough.
# MioProgetto
Piattaforma SaaS per l'automazione documentale.
Monorepo TypeScript: backend (Express), frontend (React), docs (Docusaurus).Here you include architectural decisions that Claude can't infer from the code. Why did you choose that database? Why are certain modules separated? What are the business constraints?
## Architettura
- /apps/api: Express + Prisma su PostgreSQL
- /apps/web: React 19 con App Router
- /packages/shared: tipi TypeScript condivisi
- Il backend viene deployato indipendentemente su Cloud Run,
il frontend su Vercel.This is the most critical section. Include all the commands Claude needs to know to actually work on the project: build, test, lint, deploy, migrations. Be specific with flags and arguments—if you omit details, Claude will invent nonexistent flags or run commands that fail.
## Comandi
- `pnpm dev`: avvia dev server (porta 3000)
- `pnpm test`: esegui test Jest
- `pnpm test:e2e`: Playwright end-to-end
- `pnpm lint`: check ESLint + Prettier
- `pnpm db:migrate`: migrazioni Prisma
## Regole di Codice
- TypeScript strict, mai usare `any`
- Named export, mai default export
- Componenti React funzionali con hook
- CSS solo tramite Tailwind utility classes
- Commit message in formato conventional commitsEvery project has its pitfalls: hidden workarounds, peculiar dependencies, endpoints that behave counterintuitively. This section prevents mistakes that Claude would inevitably make without the right context.
## Note Importanti
- NON committare mai file .env
- Il webhook Stripe in /api/webhooks DEVE validare le firme
- Le immagini prodotto sono su Cloudinary, non in locale
- Il modulo auth usa un wrapper custom: vedi @docs/auth-flow.md
- Il database di staging ha 30 minuti di ritardo sulla replicaA common mistake is pasting entire code snippets into CLAUDE.md. These fragments quickly become obsolete and consume valuable context. The best practice is to use references to specific files and lines, letting Claude read the source directly when needed.
# Invece di copiare il codice dell'auth middleware:
- Riferimento implementazione auth: src/middleware/auth.ts:15-45
- Pattern per i controller API: src/controllers/users.ts (usare come template)🚫 What NOT to put in CLAUDE.md: code formatting rules (use a linter or a hook), code snippets that must be stale, instructions for specific tasks (use dedicated skills or commands), comprehensive API documentation (too long, a link is better).
Skills are Markdown files that teach Claude repeatable workflows. Unlike the instructions in CLAUDE.md (which are always loaded), skills are activated only when the conversation context matches their description. This approach, called progressive disclosure, avoid cluttering the context with irrelevant information.
Starting with the most recent versions of Claude Code, skills and commands have been unified. A skill can now spawn isolated subagents with their own context window, inject dynamic data via shell commands, limit the tools available to Claude, modify the model used, and hook into lifecycle events.
mkdir -p .claude/skills/The file must contain a YAML frontmatter with the configuration, followed by the Markdown prompt. Here's an example for a code review skill:
---
name: code-reviewer
description: >
Scansiona file sorgente e suggerisce miglioramenti per
leggibilità, performance e best practice.
Si attiva su file TypeScript e JavaScript.
tools: Read, Glob, Grep
model: sonnet
---
Sei un code reviewer esperto.
Per ogni file analizzato:
1. Identifica problemi di leggibilità
2. Segnala potenziali bug o race condition
3. Suggerisci miglioramenti di performance
4. Verifica aderenza ai pattern del progetto
Mostra il codice attuale e la versione migliorata.The description is what determines when Claude automatically activates the skill. A vague description like "Check the quality of the code" It will trigger the skill on everything, including JSON or README configuration files. A precise description with directory scopes and file types prevents unwanted triggers.
🎯 Description rules: Always include the file type it affects, the scope directories, and the specific trigger. Example: "Check for brand voice conformance when Claude writes or edits Markdown files in the drafts/ or content/ directories.".
This is the most important distinction to understand: Skills are probabilistic, hooks are deterministicSkills are suggested by Claude based on context—if he's focused on a complex task, he might skip your skill. A hook is a shell script that always runs, without exception, at a specific point in the workflow.
In practice: if an instruction of the type "never run rm -rf" is placed in CLAUDE.md, it is honored about 70% of the time. With a hook that blocks the command, the percentage rises to 100%. For security rules, determinism always trumps probabilism.
A subagent is a Claude instance launched by Claude himself to process a subtask in parallel. The subagent is an autonomous process that inherits the project context (skills, CLAUDE.md, commands) without polluting the main conversation. In 2026, Claude Code supports up to 10 concurrent subagents.
This solves one of the biggest problems in agentic coding: context window clutter. After an hour of searching, writing, and editing, Claude has forgotten what you originally searched for. Subagents divide the work: one agent searches the web in its own window, another analyzes the code, a third implements—and the main thread stays clean.
In terms of performance, running three subagents in parallel to analyze a 50.000-row project takes about 45 seconds, compared to 3 minutes for sequential execution. Eighty percent of tasks involving more than three files benefit from subagent parallelization.
Type /agents in Claude Code's session. Select Create new agent, then choose whether to make it global (user-level, saved in ~/.claude/agents/) or local to the project.
---
name: security-scanner
description: Analizza codice per vulnerabilità di sicurezza
tools: Read, Glob, Grep, Bash
model: opus
maxTurns: 10
permissionMode: default
---
Sei un esperto di sicurezza applicativa.
Analizza il codice per le seguenti categorie di vulnerabilità:
- SQL injection e NoSQL injection
- Cross-site scripting (XSS)
- Gestione insicura dei segreti
- Dipendenze con CVE note
Per ogni problema trovato, fornisci:
- Severità (critica/alta/media/bassa)
- File e riga esatta
- Codice corretto propostoOnce created, you can invoke the subagent by simply typing: "Use security scanner to scan the latest commit"Claude will delegate the task to the agent, which will work in its own context window and return only the results to the main thread.
⚠️ Important limitation: Subagents cannot launch other subagents—no infinite recursion. Agent Teams are required for coordination between agents (available February 2026 with Opus 4.6).
An advanced technique is to include memory instructions directly in the subagent's Markdown file, so it proactively maintains its own knowledge base. For example, you can instruct the subagent to take notes on codepaths, patterns, and architectural decisions discovered during analysis. This builds institutional knowledge that persists across conversations.
A hook is made up of three elements: a event's audience (when activated), a to match (which instrument triggers it) and a command (the script to run). Hooks support four anchor points: pre-tool-use, post-tool-use, notification e user-prompt-submitEach hook receives contextual environment variables such as $FILE_PATH e $TOOL_NAME.
Every file created by Claude is formatted automatically, without manual intervention:
// .claude/settings.json
{
"hooks": {
"post-tool-use": [
{
"matcher": "Write",
"command": "prettier --write $FILE_PATH"
}
]
}
}A pre-tool-use hook that prevents destructive commands from being executed:
{
"pre-tool-use": [
{
"matcher": "Bash",
"command": "./scripts/validate-safe-command.sh"
}
]
}The validation script receives the command via stdin in JSON format. If the exit code is 2, the operation is blocked and the error message is returned to Claude. This provides a hard stop that Claude Code honors 100% of the time.
{
"post-tool-use": [
{
"matcher": "Edit",
"command": "eslint --fix $FILE_PATH"
}
]
}Awards Shift+Tab twice to activate Plan Mode. In this mode, Claude becomes an analysis and planning machine: he can read files, explore the codebase and formulate a detailed plan, but can't change anythingIt's like putting Claude into "architect mode" before moving on to implementation.
The best practice is to ask Claude to write the plan to an external file (e.g. plan.md) and use it as a checklist during implementation. This file becomes working memory that persists across sessions: when you return to a project days later, you're not starting from scratch.
Strategic compaction: When the context window fills up, Claude automatically activates compaction, summarizing the most important information. For greater control, use /compact <istruzioni>, for example /compact Concentrati sulle modifiche APIYou can customize the behavior in CLAUDE.md with instructions like: "When compacting, always preserve the complete list of changed files and test commands".
Proactive manual compaction: Don't wait for the context to fill up. Do it. /compact manually when you reach about 50% capacity. For task switches, use /clear to completely reset the context.
The /btw command: For quick questions that don't need to stay in context, use /btwThe reply appears in a temporary overlay without entering the conversation history—perfect for checking a detail without adding context.
Be directive, not descriptive. Claude Code isn't a chatbot: it's an agent. Instead of explaining what you want, tell it what to do. Instead of "Could you add input validation?", you write: "Add Zod validation to all endpoints in /api/routes/. Pattern: email required, name string max 100 chars, age positive number. Run test after each file."
Challenge Claude. A powerful trick: after a mediocre fix, write "Now that you know all this, throw away this solution and implement the elegant one.". Or: "Prove it works — diff main from your branch.". Or again: "Tell me about these changes and don't do PR until I pass your test."Claude works better when you give him an explicit quality goal.
Delegate the search to subagents. When you need to explore the codebase or gather information, write "Use subagent to investigate X"This launches parallel Explore agents that scan the repository and return a distilled map, keeping the main thread clean and focused.
Claude Code can be integrated into CI/CD pipelines and automation scripts. Some essential flags:
--allowedTools limits the tools available — essential for unattended execution. --verbose Enable verbose debugging (use in development, disable in production). --model specify the model, for example claude --model claude-opus-4-6. --add-dir Adds external directories to the session without changing the working directory. You can also use the slash command. /add-dir mid-session to organically expand the workspace without losing context.
To get the most out of understanding Claude's decisions, turn on the thinking mode (to see the reasoning) and set theOutput Style on "Explanatory" in /config to obtain detailed output with insight boxes. This is especially useful during debugging and architectural reviews.
Il Model Context Protocol (MCP) is a open standard published by Anthropic in 2024 that unifies communication between AI agents and external data sources. Essentially, an MCP server adds specialized tools to Claude Code: database access, web browsing, cloud file management, integration with GitHub, Slack, Jira, and much more. In 2026, over 200 community MCP servers will be available on npm.
// .claude/settings.json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"]
}
}
}You can also create custom MCP servers in TypeScript or Python. The ecosystem covers databases, monitoring, cloud services, and documentation systems. For security, always verify the source of an MCP server before installing: an unverified plugin could access your files and environment variables.
Since version 2.1.7, Claude Code includes the Tool Search which dynamically loads MCP tools when they exceed 10% of the context window. If you have many MCP servers configured and prefer to preload them all, you can disable this feature—but be aware that this increases context consumption.
Here's a complete and annotated example of CLAUDE.md for a full-stack Next.js application with Prisma, Stripe, and deployment on Vercel. This template was built following all the best practices described in this guide and balances completeness and brevity.
# ShopFront
E-commerce Next.js 14 con App Router, pagamenti Stripe, ORM Prisma.
## Stack
TypeScript strict | Next.js 14 | Tailwind CSS | Prisma | PostgreSQL | Stripe
## Comandi
- `pnpm dev` → dev server porta 3000
- `pnpm test` → Jest unit test
- `pnpm test:e2e` → Playwright
- `pnpm lint` → ESLint + Prettier
- `pnpm db:migrate` → Prisma migrate dev
- `pnpm db:seed` → popola dati di test
## Architettura
- /app → pagine e layout (App Router)
- /components/ui → componenti riutilizzabili
- /lib → utility e logica condivisa
- /prisma → schema e migrazioni
- /app/api → route API
## Regole
- Named export, mai default export
- Componenti funzionali con hook
- CSS: solo Tailwind utility, zero CSS custom
- Commit: conventional commits (feat/fix/chore)
- Branch: feature/TICKET-123-descrizione
## Avvertenze
- MAI committare .env
- Webhook Stripe: DEVE validare firme (vedi /app/api/webhooks/)
- Immagini: Cloudinary, non locale
- Auth: wrapper custom, vedi docs/auth-flow.md
## Compattazione
Quando compatti, preserva: lista file modificati, comandi test, stato migrazioni.Notice how the entire file fits into about 35 lines — well under the recommended limit of 200. Each line has a specific purpose, and there is no code snippet that could go wrong.
The encyclopedic CLAUDE.md. Inserting 500+ lines of documentation thinking "more context is better." In reality, the quality of instruction-following degrades uniformly as the number of instructions increases. Solution: Cut under 200 lines, move the rest to skills or external reference files.
The all-rounder session. Starting with one task, then asking for something unrelated, then returning to the first task. The context fills with irrelevant information and quality plummets. Solution: /clear between unrelated tasks. One session, one goal.
Correct ad infinitum. Claude makes a mistake, you correct him, he makes another mistake, you correct him again. The context is now full of failed attempts that confuse the model. Solution: After two failed corrections, do /clear and rewrite a better initial prompt incorporating what you've learned.
Use CLAUDE.md for linting. Code formatting rules don't need to be in CLAUDE.md. Use a real linter (ESLint, Prettier) or a post-tool-use hook. Deterministic tools are cheaper, faster, and more reliable than an LLM for this type of task.
Code snippet in CLAUDE.md. They become obsolete quickly and consume valuable context. Use file:line pointers to the actual source code—Claude can read the files himself.
Vague descriptions in skills. A description like "improve the code" It fires on everything. Always specify specific file types, directories, and triggers in the skill description.
Ignore Plan Mode. Skipping planning and rushing implementation leads to partial or architecturally fragile solutions. Invest 2 minutes in Plan Mode to save 20 minutes of rework.
Claude Code in 2026 is no longer a simple terminal chatbot: it's an extensible platform for AI-assisted software development. The key to getting the most out of it is a layered approach:
1. CLAUDE.md —the foundation. A few universal instructions, always loaded, concise, and focused on what Claude can't infer from the code.
2. Skill — Repeatable workflows. They activate only when needed thanks to progressive disclosure, avoiding context contamination.
3. Hook — Deterministic automation. Formatting, security, validation. Always executed, without exceptions.
4. Subagent — parallelization. They keep the main context clean, divide the work, and reduce times by up to 70% on multi-file tasks.
5. MCP Server —integration with the outside world. Databases, APIs, cloud services, specialized tools.
Start simple: generate CLAUDE.md with /init, trim the unnecessary, add real commands. Then expand based on friction points in your daily workflow. The most effective CLAUDE.md is a living document that evolves with your codebase—not a monolith written once and forgotten.
The future of software development is collaborative: you define the vision and architecture, Claude implements and tests. With the right setup, this collaboration becomes a productivity multiplier that can reduce development time on repetitive tasks by up to 40%. The difference between a good result and an exceptional one isn't the model—it's the quality of the context you provide.
The official source code and plugins are available on GitHub repository by Claude Code.
If you work with code or have a startup and want to delve deeper into the topics covered in this article, we at Pizer We can help you. For startups we have just launched MVP Zero, the service that uses agentic coding to help you develop a minimal working prototype to validate your business idea. Contact us today to get started in the world of agentic coding!
