Avoid Common Pitfalls When Designing AGENTS.md for LLM Agents

Content‑Level Misconceptions

Three main issues are identified:

Writing an Encyclopedia

Some users create thousands of lines of documentation, trying to include all knowledge. In reality, AGENTS.md should contain only indexes and maps that point to detailed documents, not the full content itself.

OpenAI advises that a short, precise AGENTS.md is more useful than a long file filled with vague rules, because excessive description consumes tokens and can “dumb down” the AI.

Over‑Explaining Basic Knowledge

Including explanations of fundamentals like “what is React” or “what is Git” adds noise, as the AI already possesses this common knowledge.

Including Full llms.txt Content

Embedding an entire llms.txt (a plain‑text dump of all pages) confuses the model with too much context, making it hard to identify important information.

Structural and Management Misconceptions

Three additional problems are highlighted:

Single‑File Bloat

When AGENTS.md exceeds 100–300 lines, token consumption spikes and key information gets lost.

The correct approach is to keep the main file concise and split task‑specific rules into separate files (e.g., SPEC_backend.md, SPEC_frontend.md).

Treating Temporary Prompts as Persistent Rules

Users often re‑enter rules manually in each conversation instead of placing them in AGENTS.md, or they embed persistent rules directly in prompts, leading to duplication.

Lack of Version Control Awareness

Failing to version‑control AGENTS.md prevents teams from sharing accumulated experience. It should be maintained like a .gitignore file, with entries added or removed over time.

Strategy‑Level Misconceptions

Three strategic errors are discussed:

Preventive Programming Mindset

Attempting to pre‑write every possible rule and edge case in AGENTS.md is ineffective. Investing in validation, test suites, linters, and CI pipelines yields better results than lengthy preventive rules.

Letting AI Generate Its Own AGENTS.md

When agents generate their own instruction files, the output often degrades performance; a smaller, curated context is usually more beneficial.

Ignoring Error‑Driven Iteration

AGENTS.md

should be updated after errors occur, not designed as a perfect pre‑emptive document.

Context‑Management Misconceptions

Two common issues are identified:

A single project thread leads to context bloat and reduced result quality.

Not using /compact to clean resolved error stacks, leaving 40+ failed iteration records that waste tokens.

During task switches, failing to use /clear or HANDOFF.md causes unrelated history to interfere with the current task.

Over‑Preloading Files

Loading all files at the start of a session instead of searching on demand wastes over 100,000 tokens. Agents should use glob and grep tools to fetch needed files lazily.

Architecture‑Design Misconceptions

One Agent Handles All Tasks

Guiding a single agent to perform front‑end, back‑end, and infrastructure tasks ignores the single‑responsibility principle; dedicated sub‑agents or skills are preferable.

Tool Over‑Atomization or Over‑Aggregation

Extremes such as a “universal tool” that does everything or splitting every function into separate tools (e.g., ListDir, FindByName) create selection noise and overwhelm the schema.

Ignoring Compact Instructions

During long‑session compression, failing to mark indispensable information (architecture decisions, modified files, validation status) leads the AI to forget critical details.

Security and Permission Misconceptions

Key risks include granting agents unnecessary capabilities (e.g., write/delete permissions when only read access is needed), using high‑privilege accounts for read‑only tasks, and allowing high‑risk operations (file deletion, pushing to main) without human confirmation.

Summary

The recommended best practices are:

Keep AGENTS.md to 100–300 lines as an index, not a full encyclopedia.

Adopt error‑driven, post‑mortem updates rather than exhaustive pre‑emptive rules.

Organize files hierarchically: global → repository‑level → sub‑directory.

Manually review AI‑generated documents and trim to essential information.

Assume the AI has common knowledge; only document project‑specific rules.

Invest in testing, linting, and CI feedback loops.

Maintain one task per thread and use /compact / /clear promptly.

Design agents with focused responsibilities and avoid over‑atomized tool sets.

Explicitly mark critical information that must survive compression.

Restrict agent permissions to the minimum required and require human approval for high‑risk actions.

Following these guidelines helps developers create efficient, maintainable, and secure AGENTS.md files for LLM‑driven agents.