CLAUDE.md and AGENTS.md: Teaching Your Agent the Rules

Summary

CLAUDE.md and AGENTS.md are plain markdown files that live in your repository and the agent reads automatically at the start of every session. They hold your axioms, your stack, your conventions, your security rules and your tone. Writing a good one is the difference between correcting the same five mistakes forever and an agent that simply gets your project. The deeper idea, and the one that compounds, is to treat the file as a living skills library: every gotcha you hit goes into a markdown file once and never costs you again.

What you will learn

You will learn exactly what belongs in a project rules file, how to phrase rules as crisp axioms the agent will actually obey, the difference between a root CLAUDE.md and the AGENTS.md that Codex and other harnesses read, and how to turn the file into a continuous-learning system where every repeated correction becomes a permanent rule. By the end you will have a real file you can paste into your own project today.

Prerequisites

A working Claude Code setup and the prompt-engineering lesson from Course 1, because the axioms you wrote there move directly into this file. You should also have a project under version control from Course 1, since the rules file lives in the repo and is committed alongside your code so the whole project shares the same standards.

The problem

You correct the agent. It uses the wrong package manager, you fix it. It adds an em dash, you fix it. It skips the test, you fix it. Next session, fresh context, same three mistakes. You are paying tokens and attention to re-teach the same lessons over and over because nothing you said persisted. The agent is not stupid, it just has no memory between sessions. A rules file is that memory. Without one, your agent starts every day with amnesia and you are its full-time supervisor.

What a rules file actually is

CLAUDE.md is a markdown file Claude Code loads automatically and treats as standing instructions for the whole session. Put it at the root of your repo for project-wide rules. You can also keep a personal one at ~/.claude/CLAUDE.md for rules that follow you across every project, and Claude Code merges them. AGENTS.md is the equivalent file that Codex and a growing number of other harnesses read, so a cross-tool team often keeps both, or keeps the real rules in one and a short pointer in the other. Anything you would otherwise retype in every prompt belongs here: language, framework, package manager, testing policy, security rules, naming conventions and tone.

• Root CLAUDE.md: project rules, committed to the repo, shared by everyone who works in it.
• Personal ~/.claude/CLAUDE.md: your own cross-project preferences, not committed.
• AGENTS.md: the same role for Codex and other harnesses, so multi-tool setups stay consistent.
• It is loaded every turn, so keep it tight - a bloated rules file eats the same context window your task needs.

Writing rules as axioms

An agent follows a crisp absolute far better than a paragraph of nuance. Phrase every rule as "Always...", "Never..." or "Every... must...". Group them by topic so the file stays scannable. Here is a real, compact CLAUDE.md you could drop into a project today. Notice it covers the things you keep correcting, not everything imaginable. Short and obeyed beats long and ignored.

# Project Rules

## Stack
- TypeScript only. No plain JavaScript files.
- Package manager is bun. Never use npm or yarn.
- Framework is Astro for marketing pages, React for the app.

## Conventions
- Use rounded-sm for border-radius on everything.
- Never use em dashes. Use a normal "-" instead.
- Components are PascalCase, files are kebab-case.

## Quality
- Every new feature ships with a test.
- Before you say a task is done, run: bun run lint && bun run typecheck && bun run test.

## Security
- Secrets live in .env, which is gitignored. Never write a key into committed code.
- Default new repos to private.

## Tone
- Direct and concise. No filler, no apologising, no "as an AI".

The skills-library philosophy

This is the part that turns a config file into a competitive advantage. Treat CLAUDE.md as a growing library of hard-won knowledge, not a one-time setup. Every time the agent makes a mistake that will recur, you do not just fix it in the moment - you write it down as a rule. The agent picked the wrong directory for tests? Add a rule. It misunderstood how your auth flow works? Add a note. Over a few weeks the file becomes a precise model of how your specific project actually works, full of the gotchas that no generic model could know. The agent then needs less and less hand-holding because the institutional knowledge lives in the repo, not in your head.

• The trigger is repetition: any correction you can imagine making twice becomes a rule the first time.
• Capture gotchas, not just style: "the convex dev server must be running before tests" is worth more than a naming rule.
• You can tell the agent to do it: "Add a rule to CLAUDE.md so you never make this mistake again" works and is a habit worth building.
• The file is shared and committed, so a gotcha you discovered is now solved for every future session and every teammate.

Keeping it living, not stale

A rules file rots if you only ever add to it. Review it after big tasks. Prune rules that no longer apply because the stack changed. Promote a useful one-off instruction you keep pasting into a permanent rule. Split a giant file into linked sub-files if it gets unwieldy, since you can reference other markdown files from CLAUDE.md and keep the root lean. The investment compounds in the most satisfying way: every future task starts from a smarter baseline, and the gap between you and someone running a bare agent widens every week. This is the same continuous-learning loop that runs through the rest of the course - capture the lesson once, benefit forever.

Typical mistakes

The common failures: writing a 500-line rules file that buries the important rules and eats your context window; phrasing rules as gentle suggestions ("it would be nice if...") that the agent treats as optional; setting it up once and never updating it, so it slowly drifts out of sync with the real project; and duplicating rules across CLAUDE.md and AGENTS.md until they contradict each other. Keep it tight, keep it absolute, keep it current, and keep a single source of truth.

Business ROI

A good rules file is the cheapest quality and consistency upgrade you will ever buy. It converts your personal knowledge into an asset that lives in the repo, so a new agent session - or a new hire, or a contractor - is productive and on-standard immediately instead of after a week of corrections. For a founder, this is how you stop being the bottleneck. The institutional knowledge that used to live only in your head, and walked out the door every time a session ended, now compounds in a file your whole business shares. That is leverage you keep forever.

Checklist

You are ready to move on when each of these is true. Do not skip the living-document items - they are where the real value is.

• You have a root CLAUDE.md committed to your project with stack, conventions, quality and security rules.
• Your rules are phrased as absolutes, not suggestions.
• You have captured at least one real gotcha you previously corrected by hand.
• You know how to ask the agent to add a new rule when it slips up.

Resources

Keep the official Claude Code memory and CLAUDE.md documentation bookmarked for the exact loading and merge behaviour, since the details evolve. The axioms you saved in the Course 1 prompting lesson are the seed of this file - paste them in as your first rules. The Agent Task Brief template in the resource library pairs well with a rules file: the rules cover the constant standards, the brief covers the per-task specifics.

Your task

Create a CLAUDE.md at the root of a real project. Fill it with your stack, three conventions you keep correcting, your quality gate command, and your secret-handling rule. Then, the next time the agent makes a mistake, instead of just fixing it, tell it to add a rule so it never happens again. Watch the file grow into something only your project could have.

Next lesson

With rules in place, the agent knows your standards. The next lesson packages your actual workflows: skills and slash commands that turn a proven multi-step process into a single reusable trigger, so common work runs the same way every time without you retyping the brief.