What should go in AI agent instruction files like CLAUDE.md and AGENTS.md?

I spent about 40 hours over four months tuning my CLAUDE.md and AGENTS.md files and skills, mostly to stop AI coding tools from hallucinating problems that don't exist. It also taught me that most instruction-file trouble comes from having too much in them.

What is an agent, really?

After my team built a custom agent system with tens of thousands of lines of code, I came to a simple definition. An agent is really a personality file, a context file, scheduled actions and skill files. That's it. The instruction files are most of the agent.

What goes wrong with instruction files?

After repeated audits over a year, the diagnosis keeps coming back the same:

"Most of the time, it was agents building too much code, causing too many restrictions, causing too many things to need to happen that don't, or conflicting language in different areas."

• Rules pile up. Every bad moment becomes a new rule. Eventually rules contradict each other across files.
• Agents ignore rules anyway. Even after I put it in the instructions, the memory and the CLAUDE.md, an agent will still tell me to go grab an API key myself. A rule isn't enforcement.
• Repeated prompts don't fix code problems. When the same failure keeps coming back, a check at the real boundary beats repeating the instruction louder.

What rules are worth having?

The ones I keep are short and change behavior. A few, in the words I actually use:

Do not say something is fixed, done, live, working, or verified
without evidence appropriate to the task.
Failure is not an excuse to quietly stop.
Existing capability before new capability.
Approved systems and assets outrank improvisation.

Each one maps to a real failure I kept hitting: agents claiming they tested things, agents giving up silently, agents building custom code for problems already solved, and agents freestyling designs when a brand system exists.

What else belongs in the files?

1. Who you are and how you work. I'm non-technical and talk plainly, so my files say to explain things in plain English and to tell me exactly how to do any step only I can do.
2. Where the truth lives. GitHub is the source of truth. Codex and Claude Code just change it, and a team folder in GitHub holds the rules for how we build.
3. Brand and design. My sites share one design system: markdown instructions plus CSS tokens. New builds need no design thinking. See how to stop AI slop.
4. What to do on failure. Say what failed, why it matters, what was tried, try reasonable alternatives, recommend the fix, and name the one decision you need from me.

How do I share instruction files with a team?

When I bring on an operator, they get a cloned copy of my environment: CLAUDE.md, AGENTS.md, skills, brand guidelines and project context, tool-agnostic between Codex and Claude Code. They work like an extension of me with fewer permissions.

How do I keep the files from bloating?

Ask for deletions, not additions. Agents are reluctant to cut, so you have to insist: why AI agents write too much code.