---
title: 'Agents.md Limits'
url: 'https://zivendodigital.com/en/ai-development/agents-md-limits'
markdown: 'https://zivendodigital.com/en/ai-development/agents-md-limits.md'
lang: en
date: '2026-10-07'
description: 'AGENTS.md Is a Guide, Not a Control System ARTICLE 6 · AI DEVELOPMENT · REPOSITORY RULES · WORKFLOW CONTROL Why one instruction file cannot carry your entire AI development strategy. When developers first discover repository instruction files such as AGENTS.md or CLAUDE.md, it feels like finding th…'
---

# AGENTS.md Is a Guide, Not a Control System

###### ARTICLE 6 · AI DEVELOPMENT · REPOSITORY RULES · WORKFLOW CONTROL

*Why one instruction file cannot carry your entire AI development strategy.*

When developers first discover repository instruction files such as `AGENTS.md` or `CLAUDE.md`, it feels like finding the missing piece of AI coding.

You write down your technology stack, coding conventions, and strict formatting rules. You place the file in your repository, start your coding agent, and expect consistent behaviour across future sessions.

For the first few sessions, it works reasonably well.

### Then the Cracks Appear

As the application grows, you notice familiar problems:

- **Missed instructions:** The agent overlooks a rule you wrote in capital letters.
- **Too much context:** A lengthy instruction file competes with source code and the active task.
- **Missing history:** After a week away, the file tells you little about what was built, tested, or approved.

The lesson is simple:

**AGENTS.md is a valuable operating guide. It is not an autonomous control system.**

![AGENTS.md_ From Rules to Results.png](https://zivendodigital.com/user/pages/05.ai-development/09.agents-md-limits/AGENTS.md_%20From%20Rules%20to%20Results.png)

 Important

**Instructions describe expected behaviour.**

They do not, by themselves, enforce permissions, maintain project history, or prove that work was verified.

## The Seven Core Limitations of AGENTS.md

### 1. It Does Not Guarantee Compliance

Writing rules in a text file does not make an AI agent deterministic.

The agent can miss, misinterpret, or inconsistently apply an instruction—particularly when the surrounding context is complex or contradictory.

Emphatic wording such as *“YOU MUST ALWAYS”* can express importance, but it does not create an enforcement mechanism.

**Rules still need observable checks.**

### 2. It Uses a Finite Context Budget

Instruction files contribute to the context the agent must process.

Some tools limit how much instruction text they load. Even when the complete file is available, excessive detail makes it harder to identify the rules relevant to the current task.

Your instructions share that working context with:

- Source code.
- Task requirements.
- Tool outputs.
- Error messages.
- Dependency information.

 Tip

**Keep the main instruction file concise.**

Link to detailed documents and make clear when the agent should read them.

### 3. More Instructions Do Not Automatically Improve Results

A longer rulebook is not necessarily a better rulebook.

Repeated instructions, conflicting requirements, and rarely relevant exceptions can obscure the essentials.

For example, a file that says both *“avoid changing shared utilities”* and *“refactor duplicated logic whenever possible”* leaves an important scope decision unresolved.

**Prioritise clear, consistent rules over sheer volume.**

### 4. It Is Not Complete Project Memory

`AGENTS.md` records the information written into it.

It does not automatically capture:

- Decisions made in previous conversations.
- Architectural trade-offs.
- Current backlog progress.
- Verification results.
- Debugging lessons.
- Work awaiting approval.

Those records must be maintained elsewhere and made accessible to the agent.

 Warning

**Standing rules cannot tell you where the project stopped.**

You need a current task record and execution history to resume work reliably.

### 5. It Can Become Outdated

As your repository changes, its instructions can drift away from reality.

A renamed directory, replaced dependency, or new testing command can leave the agent following an obsolete workflow.

When you update the file, confirm that the active session has loaded the revised instructions. Reload behaviour varies between tools.

**Maintain the rulebook alongside the code it describes.**

### 6. It Cannot Enforce Permissions or Quality

A text file cannot independently:

- Grant or restrict API access.
- Block prohibited file changes.
- Enforce branch protection.
- Prove that tests ran.
- Prevent a failed build from being merged.

Writing *“always run tests before finishing”* establishes an expectation. It does not establish a technical gate.

Enforcement requires controls such as permissions, automated checks, and approval requirements.

 Caution

**A rule is not evidence that the rule was followed.**

Review actual test outputs, runtime logs, and code changes before accepting a completion claim.

### 7. It Does Not Have Final Authority

Repository instructions operate within the agent’s wider instruction and execution environment.

Higher-priority instructions and tool restrictions may take precedence.

Your file cannot override those controls simply by declaring itself authoritative.

**Treat it as project guidance within the available environment.**

## The Correct Role: A Concise Operating Guide

Use `AGENTS.md` as a standing rulebook that helps an agent orient itself and work consistently.

Give changing project state and verification their own records and controls.

| Component | Responsibility | Typical contents |
|---|---|---|
| **AGENTS.md** | Standing project guidance | Technology stack, essential commands, conventions, and architectural references |
| **Persistent task ledger** | Current execution state | Task scope, dependencies, acceptance criteria, and review status |
| **Engineering journal** | Decisions and results | Change summaries, verification evidence, blockers, and next actions |
| **External verification gates** | Enforcement and approval | CI checks, access controls, runtime review, and human sign-off |

These components support each other. None should be expected to do every job.

## What Belongs in AGENTS.md?

### Project Purpose and Technology Stack

Give the agent a short orientation:

- What the application does.
- Its primary languages and frameworks.
- The important architectural constraints.

Keep it specific to the repository.

### Essential Commands

Record the actual commands for:

- Building.
- Linting.
- Running tests.
- Starting the application.
- Locating or inspecting runtime logs.

Include relevant prerequisites where necessary.

**Commands should be usable, not merely descriptive.**

### Standing Conventions and Boundaries

Include durable rules such as:

- Follow established repository patterns.
- Keep changes within the approved task scope.
- Record relevant errors with timestamps.
- Report blocked verification explicitly.
- Request a scope decision before changing excluded components.

### References to Detailed Documentation

Point to architecture documents, specifications, and module-specific guidance.

Explain when those references are relevant so the agent knows what to read before implementation.

 Tip

**Make AGENTS.md an entry point to the project’s knowledge.**

It should help the agent find the right information without duplicating every document.

## What Should Live Elsewhere?

| Information | Better home |
|---|---|
| **Active tasks and temporary bug lists** | Persistent task board |
| **Changing priorities and dependencies** | Backlog and milestone records |
| **Historical change summaries** | Engineering journal and Git history |
| **Detailed architectural decisions** | Architecture documentation |
| **Verification results** | Task evidence and CI outputs |
| **Enforceable restrictions** | Permissions, automated checks, and approval controls |

Avoid turning the root instruction file into a growing transcript of everything that has happened.

## Connect Static Rules to Dynamic Execution

A reliable workflow gives the agent both standing guidance and current task context.

Before implementation:

1. **Read the repository rules.**
2. **Open the approved task card.**
3. **Review relevant decisions and dependencies.**
4. **Confirm scope and acceptance criteria.**

Before approval:

1. **Inspect the actual changes.**
2. **Run the appropriate verification.**
3. **Review relevant runtime logs.**
4. **Record results and limitations.**
5. **Obtain human sign-off.**

 Important

**AGENTS.md explains how to work.**

The task ledger records what to work on. Verification evidence supports whether the result is ready to approve.

## Build a Workflow Around the File

A concise `AGENTS.md` can improve consistency and reduce repeated explanations.

Pair it with persistent task records, bounded execution, and evidence-backed review to reduce drift as the project grows.

The aim is not a perfect instruction file.

**It is a workflow in which expectations are clear, progress is recorded, and completion can be checked.**

---

 Note

**Put the Complete Workflow Into Practice**

[The Card-Driven AI Development Playbook](https://zivendodigital.com/en/pages/ai-development-playbook) includes repository instruction templates, prompt packs, and the 30-card Invoice Capture case study to help you connect standing rules with controlled execution and verification.

---

## Navigation

- Parent: [The Controlled AI Development Series](https://zivendodigital.com/en/ai-development.md)
- Previous: [Memory vs Intelligence](https://zivendodigital.com/en/ai-development/memory-vs-intelligence.md)
