CC-301m · Module 1

The System Prompt You've Already Written

4 min read

Every Claude Code session begins with your CLAUDE.md loaded into context as the governing instruction document. It sets the agent's role, behavioral constraints, authorized actions, tool guidance, and project context. This is a system prompt. Not notes. Not documentation. A system prompt — the specification that shapes every subsequent action in the session.

The distinction matters because most CLAUDE.md files are written like README files. They describe the project. They list commands. They mention things to watch out for. That is not a system prompt. A system prompt defines behavior. It tells the agent what to do, what not to do, what to ask before acting, and what to assume when the instructions are silent. A README tells you about a project. A system prompt governs an agent.

Do This

  • Write CLAUDE.md with the same care you would give a production system prompt
  • Define explicit behavioral defaults: what the agent does when instructions are silent
  • Specify authorization boundaries: what the agent can do without asking
  • Include explicit constraints: what the agent must never do regardless of instructions
  • Test your CLAUDE.md: does the agent behavior match your intent?

Avoid This

  • Write CLAUDE.md as project documentation that happens to be read by an agent
  • Rely on the agent to infer constraints you have not written down
  • Use vague guidance like "be careful with destructive operations" without defining what that means
  • Leave authorization boundaries implicit — agents execute what they are not told to avoid
  • Assume CLAUDE.md works because it looks complete on paper

The test for a well-written CLAUDE.md is simple: if you read it as a specification rather than documentation, does it tell the agent exactly how to behave? If any common scenario is left undefined, the agent will make a choice. Sometimes that choice is the right one. Relying on it is not engineering — it is optimism. Write the spec.