AI coding agents such as Claude, Codex, Gemini, and other autonomous developer tools are becoming a central part of modern software development workflows. However, one of the biggest limitations when using AI agents is the token context window. Every prompt, file, and instruction consumes tokens, which directly affects cost, performance, and reliability.
A powerful way to reduce token usage and improve agent efficiency is by using a structured documentation file such as agents.md. Properly documenting your system allows agents to understand the project quickly without repeatedly consuming large amounts of context.
In this article, we explain how to structure an agents.md file to dramatically reduce token usage while improving agent performance.
What is an agents.md file?
An agents.md file is a centralized documentation file that explains how AI agents should interact with a codebase or project. It acts as a lightweight instruction manual that helps the agent understand:
- Project architecture
- Important rules
- Development conventions
- Key file locations
- Available tools and commands
- Agent responsibilities
Instead of forcing the AI to scan the entire repository repeatedly, the agent reads the agents.md file first and uses it as a guide.
Why agents.md saves tokens
AI agents often attempt to understand a project by reading many files across the repository. This process can consume thousands of tokens every time the agent runs.
When a structured agents.md file exists, the agent can immediately understand the system without loading unnecessary files.
This creates several advantages:
- Lower token usage
- Faster agent execution
- More accurate code modifications
- Reduced hallucination risk
In large codebases, a well-designed agents.md file can reduce token usage by 50–90% during agent workflows.
The core structure of a good agents.md file
A good agents.md file should be structured so that an AI agent can quickly understand the system without reading large code sections.
The most effective structure usually includes the following sections.
1. Project overview
Start with a short explanation of the system. This should be concise but clear enough for an AI agent to understand the purpose of the project.
# Project Overview
This project is a tutoring marketplace platform.
Main components:
- Drupal backend
- React booking system
- Stripe payments
- Tutor and student dashboards
The overview prevents the agent from trying to infer the entire system architecture from the codebase.
2. System architecture summary
Provide a simplified description of the architecture. This allows the agent to quickly identify where different features live.
# Architecture
Backend: Drupal 10
Key modules:
- konordo_booking
- konordo_payments
- konordo_tax
Frontend:
- React booking calendar
- FullCalendar integration
- Luxon for timezone conversion
Without this section, agents often scan dozens of files to reconstruct architecture.
3. Key entities and data models
Agents frequently need to understand data structures. Listing them directly avoids expensive file scanning.
# Core Entities
Booking:
- booking_order_id
- student_id
- datetime_start
- datetime_end
- status
Payment:
- amount
- status
- stripe_payment_intent
This lets the agent understand how the system works without loading multiple database or schema files.
4. Development rules
This section is extremely important because it prevents the AI agent from making incorrect assumptions.
# Development Rules
- Do not modify Drupal core.
- All custom code must live inside custom modules.
- Payment logic must remain inside konordo_payments.
- Booking logic must remain inside konordo_booking.
These rules prevent the agent from writing code in the wrong places.
5. Common tasks
Defining common tasks helps agents execute workflows without needing large prompts.
# Common Tasks
Add booking feature:
- Update konordo_booking entity
- Update API endpoint
- Update React calendar
Modify payment logic:
- Modify konordo_payments module
- Ensure Stripe compatibility
This helps the agent jump directly to relevant files.
6. Tool usage
Agents often have access to tools such as Playwright, shell commands, or repository search. Documenting these tools improves efficiency.
# Tools Available
Playwright
- Used for browser testing
Shell
- Used for running commands
Repository search
- Used to locate files quickly
7. File map
Large projects benefit from a simplified map of important directories.
# Key Directories
/modules/custom/konordo_booking
/modules/custom/konordo_payments
/react-calendar
/api
This reduces the need for repository-wide scanning.
Best practices for minimizing token usage
To maximize the effectiveness of agents.md, follow these best practices.
- Keep explanations short and structured
- Use bullet points instead of long paragraphs
- Document only the most important concepts
- Avoid copying large code blocks
- Focus on architecture and rules
The goal is not to replace documentation entirely, but to create a compressed knowledge map for the AI agent.
Why agents.md will become standard in AI development
As AI agents become more autonomous, projects will increasingly rely on structured knowledge files. These files allow agents to operate with less context while still making correct decisions.
In the future, many repositories will likely include standardized files such as:
- agents.md
- system.md
- architecture.md
- memory.md
These files will function as the operating manuals for AI agents, allowing them to work efficiently inside complex codebases.
Conclusion
AI coding agents can dramatically accelerate development, but they also introduce new challenges related to token limits and context management. A well-designed agents.md file solves this problem by giving agents a concise overview of the system.
By documenting architecture, rules, entities, and workflows in a structured way, developers can reduce token usage, improve agent accuracy, and create a smoother collaboration between humans and AI.