What Problem These Files Solve
Every Claude session starts from scratch. There is no memory of what you worked on yesterday, no recollection of your naming conventions, and no knowledge of which servers are production or which scripts live where. If you want Claude to follow your standards, you normally have to explain them at the start of every conversation.
CLAUDE.md fixes this. It is a plain text file that Claude reads automatically at the start of every session, before you type a single word. Think of it as a briefing document that puts Claude in context: your environment, your preferences, your ground rules. Once it is set up, you stop repeating yourself.
AGENTS.md serves the same purpose, but with a broader scope. It is an open standard supported by Claude, GitHub Copilot, Cursor, Gemini CLI, and a growing number of other AI tools. If your team uses more than one AI assistant, a single AGENTS.md gives all of them consistent instructions without maintaining separate config files for each tool.
Where the Files Live
CLAUDE.md can go in several places, and Claude loads all of them, with more specific locations taking precedence over broader ones.
Personal / global: ~/.claude/CLAUDE.md. Applies to every project on your machine. Good for your own preferences: how you like code formatted, tools you always use, shortcuts you rely on.
Project-level: ./CLAUDE.md or ./.claude/CLAUDE.md in your project root. Shared with your team via source control. This is where project architecture, naming standards, and common workflows belong.
Managed policy: on macOS at /Library/Application Support/ClaudeCode/CLAUDE.md, on Linux and WSL at /etc/claude-code/CLAUDE.md. This is intended for IT or DevOps teams who want organization-wide rules deployed across all developer machines via MDM, Ansible, or Group Policy. Individual users cannot override it.
For AGENTS.md, place it in your project root. Claude will pick it up automatically in any directory where no CLAUDE.md exists, making it useful as a cross-tool fallback.
What to Put in CLAUDE.md
Less is more here. The file is loaded into Claude’s context window every session, so every line costs tokens. Anthropic recommends staying under 200 lines. Only include things that are universally true for every task you do in that project.
Good candidates for a project CLAUDE.md in an IT environment:
- The tech stack and key tools (PowerShell version, Azure CLI, Terraform version)
- Naming conventions for resources, scripts, and variables
- Environment topology: which subscriptions are prod vs. dev, which naming prefixes are used
- Commands to run tests or validate scripts before committing
- Things Claude should never do (delete prod resources, hard-code credentials, skip error handling)
Things that do not belong in a project CLAUDE.md: your personal editor shortcuts, preferences that only apply to you, or instructions that are only relevant to one specific task. Put personal preferences in ~/.claude/CLAUDE.md, and task-specific guidance in a separate rules file.
A Starter CLAUDE.md for IT Infrastructure Work
Here is a practical starting point you can adapt. This example targets a team doing Azure infrastructure work with PowerShell and Terraform.
# Project: Azure Infrastructure Automation
## Environment
- PowerShell 7.4, Azure CLI 2.x, Terraform 1.7+
- Subscriptions: prod (sub-xxx-prod), dev (sub-xxx-dev), staging (sub-xxx-stg)
- Naming convention: {env}-{region}-{type}-{name} (e.g., prod-we-vm-webserver01)
## Code Standards
- All PowerShell scripts must use [CmdletBinding()] and param() blocks
- Always include -ErrorAction Stop on critical Azure CLI and Az module calls
- Use Write-Verbose for progress, Write-Warning for recoverable issues, throw for fatal errors
- No hard-coded credentials, subscription IDs, or resource names -- use variables or parameters
- Run PSScriptAnalyzer before committing any .ps1 file
## Terraform
- State stored in Azure Storage: tfstate-prod-we-sa01 (prod), tfstate-dev-we-sa01 (dev)
- Always run terraform plan and review output before apply
- Tag every resource with: env, owner, project, cost-center
## What Not to Do
- Never target the prod subscription unless explicitly asked
- Never delete resources -- use -WhatIf or plan output for destructive operations
- Never skip error handling to make code shorter
You do not need to write this by hand from scratch. If you already have a project open in Claude Code, run /init and Claude will analyze the directory and generate a starting CLAUDE.md based on what it finds. You then refine it from there with anything Claude would not discover on its own.
A Starter for Your Personal ~/.claude/CLAUDE.md
This file is for habits and preferences that apply across all your projects.
# Personal Preferences
## Style
- Prefer PowerShell over Bash for cross-platform scripts
- Use single quotes in PowerShell unless interpolation is needed
- Prefer explicit parameter names over positional arguments
- Always add comment-based help to functions (Synopsis, Description, Parameter, Example)
## Working Style
- Explain what you are about to do before writing code
- For any change touching production config, summarize the blast radius first
- When in doubt about scope, ask before proceeding
## Tools I Use
- Azure CLI for read operations, Az PowerShell module for write operations
- VS Code with PSScriptAnalyzer and Bicep extensions
- Git flow: feature branches, PRs to main, squash merges
Organizing Rules for Larger Projects
If your CLAUDE.md starts growing past 200 lines, the right move is to split it using the .claude/rules/ directory. Each file in that directory covers one topic, and you can scope rules to specific file types so they only load when Claude is working with matching files.
.claude/
├── CLAUDE.md # Core project context, under 200 lines
└── rules/
├── terraform.md # Terraform-specific standards
├── powershell.md # PowerShell style rules
└── security.md # Security and compliance requirements
You can also scope a rules file to specific paths using YAML frontmatter at the top of the file:
---
paths:
- "**/*.tf"
- "modules/**/*"
---
# Terraform Rules
- All modules must declare required_providers with version constraints
- Use data sources instead of hard-coded resource IDs
- Every output must have a description
This way, Terraform rules only load when Claude is working with .tf files, keeping context clean and focused.
AGENTS.md for Multi-Tool Teams
If your team uses a mix of AI coding tools — some people on Claude Code, others using GitHub Copilot or Cursor — AGENTS.md lets you maintain one shared file that all of them read. The format and content are identical to CLAUDE.md. The only difference is the filename.
The practical approach for mixed teams: put shared project standards in AGENTS.md at the project root, and keep tool-specific preferences in each user’s personal CLAUDE.md. That way the project standards are consistent regardless of which AI tool someone runs, while individuals still have their own setup.
Auto Memory: What Claude Learns on Its Own
Beyond CLAUDE.md, Claude Code has an auto memory feature that writes notes to itself as you work. If you correct Claude on something — say, “we use PSScriptAnalyzer strict mode, not default” — it can save that to a memory file so it does not make the same mistake next session.
Auto memory is stored per project at ~/.claude/projects/<project>/memory/MEMORY.md. It is plain markdown you can read and edit at any time. Run /memory in any Claude Code session to browse what has been saved, toggle auto memory on or off, and open memory files directly.
The distinction to keep in mind: CLAUDE.md is for rules you set intentionally. Auto memory is for things Claude picks up from your corrections and behavior. Both load at the start of every session and complement each other.
A Few Practical Tips
Keep each rule concrete enough that you could verify it. “Always use -ErrorAction Stop on Az module calls” is something you can check. “Handle errors properly” is not. Vague instructions get followed inconsistently.
Review your CLAUDE.md every few months. Rules accumulate, old ones become irrelevant, and conflicting instructions cause unpredictable behavior. If two rules say different things about the same situation, Claude may pick one arbitrarily.
Start small. A 20-line CLAUDE.md that covers your three biggest pain points will serve you better than a 300-line file that Claude dilutes across too much context. Add rules as you notice Claude getting things wrong, not all at once upfront.
For organization-wide deployments, the managed policy location (Linux: /etc/claude-code/CLAUDE.md) is worth setting up if you are rolling out Claude Code across a team. Anything in that file cannot be overridden by project or personal files, making it suitable for security policies and compliance requirements you need to enforce consistently.
