Improving Your AI Agent, One Rule at a Time

image of Alex Garrett-Smith

Alex Garrett-Smith •2d

tl;dr. Use an agent markdown file, review it regularly, don’t let it get out of control, and share it with your team.

AI agents thrive on context. The simplest way to define this up-front is with an agent markdown file which feeds your agent with context at the start of every session, and I’m going to help you get the most out of yours. While it’s easy to treat these agent files as a dumping ground, we’ll also discuss why this isn’t a good idea, how to keep them useful, and avoid bloat.

Since I use Claude Code exclusively, I’ll be referencing CLAUDE.md throughout this post, but the same advice applies regardless of which agent you’re using.


First, Are You Using One?

If not, let’s make the case and get started. A great way to begin your agent file is to define your development philosophy. Whether you’re working alone or on a team, adding a few overarching guiding points can help shape the direction your agent takes.

Here’s how I generally start my CLAUDE.md file:

# Development philosophy
- Prefer simple solutions over clever ones.
- Write code that is clear and self-explanatory.
- Build with the long term in mind.

And honestly, this alone is fine to start with.

This doesn’t mean your agent will transform into your direct replacement and output perfect code every time, but we’ve given it something to initially guide it.


If Your AI Agent Makes the Same Mistake Twice

I have a rule. If Claude does something wrong twice (actually, sometimes once), I update my CLAUDE.md file.

An example: With Vue.js, I prefer the Composition API over the Options API. How does Claude know this? Right now, it doesn’t. I could specify this every time I enter plan mode or paste in a planned feature prompt, but it’s likely I’ll keep forgetting.

So here’s what I’d append to my CLAUDE.md file:

## Vue conventions
- Use the Composition API, not the Options API.
- Prefer <script setup> syntax for components.

This is a small, direct instruction. However, we can also define broader architectural rules.

While working with Laravel and Inertia.js, I find that Claude Code rarely makes use of Laravel’s API Resources to pass data to views, which to me is a fundamentally important technique for transferring data to Vue components due to performance, security and organisation.

I let Claude know:

# Laravel conventions
- Use Laravel API Resources for all data passed to Inertia views, with only the data required for the view. Never pass raw models.

Add these small rules as you notice your agent not following the conventions or rules you’ve defined for yourself, and continue to tweak them if you still don’t get the result you want.

I promise that if you update your agent file regularly with these conventions, as you spot them, you’re more likely to get faster and more efficient as you go.


Who Said You Had to Update It?

If remembering to update your agent file feels like keeping documentation up to date, the good news is: you don’t have to do it yourself. Have your agent do it!

(A little secret… I didn’t write any of the conventions above myself.)

Instead, here’s what I’d prompt in Claude Code:

You’re directly passing models down to Vue components which is exposing data. Could you refactor this to use API resources with only the data we need? Please update CLAUDE.md so this doesn’t happen again.

There’s no magic formula to the way you ask for this to be updated. In this case, I wanted the fix, but as a side effect asked Claude to update CLAUDE.md. Then, I double-check to make sure the convention Claude wrote is clear, I tweak it if needed, and move on.


Too Much Context

As you can imagine, your agent file can become a dumping ground for just about anything. A side effect to a huge context file is either too much information or worse, conflicting information. Oh, and if it’s too big you’ll likely not review it regularly.

Here’s what I try not to include in CLAUDE.md:

  • Things the agent can easily infer from the codebase, like the tech stack we’re using.

  • One-off decisions or temporary experiments.

  • One-off instructions for a single task or feature.

  • Long explanations instead of short, clear instructions (check that your agent doesn’t generate these itself).

There’s no hard and fast rule around your agent file size, but as a general rule, if I can’t scan it and quickly figure out key technical decisions and it reads more like developer documentation… it’s time to clean up.

In fact, there’s a lot that linting and static analysis can do already to avoid cluttering your agent file with small technical decisions.

I recently cleared up CLAUDE.md thanks to linting. Previously, I had the following Vue convention in CLAUDE.md:

- Order single-file component blocks as: `<template>`, then `<script setup>` (Composition API), then `<style>`.

Something about this didn’t seem right to me at the time I added it, and my intuition was correct… there’s an eslint rule for this!

export default [
    js.configs.recommended,
    ...pluginVue.configs['flat/recommended'],
    {
        //...
        rules: {
          'vue/block-order': ["error", {
              order: ["template", "script", "style"]
          }],
          //...
        },
    },
]

Whether you agree with my ordering here, I’m sure you’ll agree that a linting rule here is a lot less flaky.


Tell Your Agent Not to Agree with You

One of the most productive items I added to my agent file is asking it not to agree with me all the time. This dramatically improved planning and implementation if I’d got something wrong myself or provided unclear instructions.

Here it is:

Don’t just agree with me or accept my conclusions. Push back if you think I'm wrong.

You can word this differently if you prefer a softer approach, but I’ve found this to be really effective.


“Any questions?”

As a side tip, while I’m prompting anything that causes an action (e.g. code implementation) and I’m not sure I have all the details correct, I ask this simple question. Nine times out of ten, my agent will come back with some items that need clarification before it gets to work.

[some longer implementation prompt for a feature]. Any questions?

I wouldn’t include this directly in the agents file, because it’s not required for everything, but complements this approach nicely.


Share It with Your Team

Commit your agent file to the project repo! You want every member of your team to benefit from the context around what everyone is building.

I’ve mostly observed that teams all use the same agent, but if they don’t, there’s a workaround. Have a generic AGENTS.md file, which will work across many agents. You can read more about the AGENTS.md open standard here. Of course, this approach is useful for open-source projects where the likelihood of contributors using different agents is higher.

Most agents are supported, but if you’re using one that isn’t, there are specific instructions in the link above.


tl;dr

I hope this has helped you understand the vital role an agent markdown file plays in your workflow. To recap, here’s the takeaway:

  • Use one: If you’re not already, at least fill it with your development philosophy or ask your agent not to always agree with you.

  • Same mistake twice? Update it: You’ll get better output, more speed, and less breakage if you tweak your agent file as you go.

  • Let your agent update itself: You don’t even have to bother writing your own rules. Ask your agent to.

  • Keep it lean, specific and relevant: Review it regularly, don’t use it as a dumping ground for everything.

  • Share it with your team: Let everyone contribute and benefit.