I’ve configured instructions in AGENTS.md, but the agent isn’t following them. What should I do?
Q: I’ve configured instructions in AGENTS.md, but the agent isn’t following them. What should I do?
It is common to set instructions – whether in an AGENTS.md file, a CLAUDE.md file, or another rules file – only to find the agent ignoring them or applying them inconsistently.
To fix this, you need to understand why it happens: instructions are merely text appended to the model’s context for every request. Because large language models are inherently non-deterministic, they may occasionally misunderstand, de-prioritize, or entirely miss your directives.
The most effective approach is to treat your agent instructions as project infrastructure that requires continuous testing, verification, and evolution.
Strategies for Debugging and Refining Instructions
Here are several practical methods to ensure your agent consistently follows your guidelines:
Test and Verify Repeatedly: Do not assume an instruction works based on a single successful output. Force the agent to invoke the specified behavior multiple times. For instance, if you mandated a specific commit message style, trigger several commits to verify that the format is strictly and consistently applied across different scenarios.
Interrogate the Agent: Open a direct chat with the agent and ask it to explain its understanding of your instructions. Present hypothetical scenarios by asking, “What if I ask for this specific task to be carried out? How would you do it? Give me a clear and detailed step-by-step explanation.” This allows you to audit the agent’s interpretation before it performs actual work.
Inspect Thinking Traces: If your model emits reasoning traces, review them carefully. These “thoughts” provide valuable clues about which parts of the context the model is paying attention to and whether it actually processed your specific instructions before generating its final output.
Iterate Like a Prompt Engineer: Treat your configuration file as you would any AI prompt. If an instruction is ignored, try rewording it, moving it higher in the document, or repeating it. You can even use ALL CAPS to draw attention to critical, non-negotiable behaviors.
Ask the Agent for Help: If you are struggling to enforce a rule, ask the agent itself how best to phrase the instruction. It can often help you write a more effective prompt tailored to its own reasoning patterns.
The Importance of Consistency
Always remember that models are non-deterministic – the exact same instructions in the exact same environment will yield slightly different results on each run. You must run multiple trials of the same scenario to guarantee consistency. Iterate and refine your instructions until the desired behavior is fully understood and reliably executed.
…
Looking to learn how to use AI agents effectively for software development? The spring cohort of Elite AI-Assisted Coding, the #1 comprehensive course on making the most of agentic software development, is open for signups. Join us!
