Skip to main content
CLAUDE.md and AGENTS.md can tell an agent who you are, what the workspace is for, and how you work. Automatic loading depends on the agent. 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.
Keep the file for the agents you use. If everyone uses Claude Code, CLAUDE.md is enough. If you use Codex too, keep AGENTS.md as well. The simplest approach is to share the relevant sections and update both together.

​
What to put in them

Claude Code or Codex reads its supported instruction file at the start of a 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, and the like).
  • 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 an initial CLAUDE.md based on:
  • What you tell the guide about yourself
  • What the workspace is for
  • The first workflow or starter skill you set up
It is a starting point. If your team also uses agents that read AGENTS.md, create that file separately and keep the relevant shared instructions aligned.

​
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. Claude Code and Codex can then read the same supported instructions; other agents need an explicit pointer when automatic loading is not guaranteed. 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.