Claude Code configuration guide
Last updated: June 2026
Claude Code has three configuration layers. They serve different purposes, and using the wrong one wastes tokens, slows responses, and makes your agent less reliable. Here's how each one works and when to use it.
The three config files
CLAUDE.md (project root)
The primary configuration file for Claude Code. Place it in your project root. Claude Code reads it at the start of every session.
# Project: My SaaS App
# Stack: Next.js 15, TypeScript, Prisma, PostgreSQL
## Rules
- Use TypeScript strict mode everywhere
- All API routes need input validation with Zod
- Write tests before implementation (TDD)
- Use conventional commits: feat:, fix:, docs:
- Never commit .env files or secrets
## Architecture
- Pages in app/ (App Router)
- API routes in app/api/
- Database schema in prisma/schema.prisma
- Shared types in types/agents.md (project root)
An alternative to CLAUDE.md. Works the same way — persistent instructions read every session. Some teams prefer agents.md because it's more descriptive of what the file does.
Use CLAUDE.md or agents.md, not both. They serve the same purpose. If both exist, Claude Code reads both, which is usually not what you want.
skill.md (on-demand)
Loaded only when needed for specific tasks. Put task-specific instructions here instead of bloating your agents.md.
# Security Audit Skill
When performing a security audit:
1. Check for OWASP Top 10 vulnerabilities
2. Scan for exposed secrets in git history
3. Review authentication/authorization flows
4. Validate all user inputs are sanitized
5. Check CSRF protection on state-changing endpoints
Output format: Markdown table with findings,
severity, and remediation steps.When to use each file
| Question | Use |
|---|---|
| True for every session? | CLAUDE.md / agents.md |
| Only needed for specific tasks? | skill.md |
| Coding standards & conventions? | CLAUDE.md / agents.md |
| Workflow for a specific task? | skill.md |
| Reusable across projects? | skill.md |
| Project-specific configuration? | CLAUDE.md / agents.md |
File location conventions
CLAUDE.md or agents.md goes in the project root. Skill files go in a .claude/skills/ directory by convention, but Claude Code can find them anywhere you put them.
Common mistakes
- •Putting everything in CLAUDE.md. A 500-line config file means Claude Code reads 500 lines of instructions every single message. That costs tokens and dilutes focus.
- •Using both CLAUDE.md and agents.md. Pick one. Having both creates confusion about where instructions live.
- •Not using skill files at all. If you find your CLAUDE.md growing past 100 lines, that's a sign some of those instructions should be in skill files instead.
- •Copying someone else's config without adapting it. Your project has different conventions, stack, and priorities. Write your own.
Not sure where your instructions go?
Describe the functionality you want your AI agent to have. Get an instant recommendation for CLAUDE.md, agents.md, or skill.md.
Try ClaudeOrNot →