Working with CLAUDE.md and AGENTS.md

CLAUDE.md and AGENTS.md are the files your agent reads first to learn about your workspace. CLAUDE.md is for Claude Code. AGENTS.md is for Codex. Both serve the same purpose: tell the agent who you are, what this workspace is for, and how you work.

A good one of these files is the difference between an agent that needs you to repeat yourself every chat and one that picks up where you left off.

Where they live

In the root of your workspace folder, alongside your top-level folders.

your-workspace/
├── CLAUDE.md
├── AGENTS.md
├── accounts/
├── playbooks/
└── ...

If you only use Claude Code, you only need CLAUDE.md. If you only use Codex, only AGENTS.md. If you use both, keep them in sync (the easiest way is to have one be a copy of the other, and update them together).

What to put in them

The agent reads this file at the start of every session. Keep it scannable, not exhaustive.

A good CLAUDE.md or AGENTS.md covers:

• Who you are. Your name, role, what you do day to day.
• What this workspace is. The purpose of the folder, what kinds of work happen here.
• How you work. Conventions to follow, tools you use, things to avoid.
• Where to look. A short map of the folders inside this workspace, so the agent knows where things live.
• What's in flight. Active projects or context worth flagging up front.

What to leave out:

• Long histories or wikis. The agent can read other files when it needs to.
• Information that lives elsewhere and changes often (live metrics, calendar, etc.)
• Anything sensitive you wouldn't want every chat to see

How the starting guide writes the first one

When you turn on the starting guide for a new folder, Palette writes your first CLAUDE.md or AGENTS.md based on:

• What you tell the guide about yourself
• What your context layer knows about you, if connected
• The first workflow you set up

It's a starting point. As you work, you'll want to expand it.

Keeping it sharp

The fastest way to update CLAUDE.md or AGENTS.md is to ask your agent to do it.

• "Update CLAUDE.md to add the new accounts folder."
• "Reflect this decision in AGENTS.md."
• "Check CLAUDE.md against how I actually work. Anything out of date?"

Treat it like a living doc. When you change how the workspace is organized, or how you work, update the file.

Sharing with your team

If you share the workspace folder with your team, you share CLAUDE.md and AGENTS.md with them too. Everyone's agent reads the same context.

For shared workspaces:

• Keep the file focused on the team and the work, not on individual preferences
• Put personal preferences (your voice, how you like things drafted) in a separate file the agent can read
• Update it together, the same way you'd update any shared doc

Next

• Agents, Claude Code and Codex
• Workspaces, the folder these files live in
• Quick start, the starting guide that writes the first version