AGENTS.md: The Config File Every Repo Should Have Now

Modern development relies increasingly on large language models to assist with refactoring, debugging, and feature implementation. As these tools evolve, providing consistent context becomes a critical bottleneck. This is where an AGENTS.md guide serves as a standardized solution, acting as a cross-agent instruction file that tells AI coding assistants exactly how to interact with your specific codebase. By placing this file in your repository root, you ensure that every agent, regardless of its specific architecture, follows your architectural patterns, testing requirements, and deployment protocols without manual prompting every session.

The Convergence of Project Context

For years, developers have used README.md to onboard human contributors. This file typically includes high level overviews that humans scan, skip, or interpret through intuition. AI agents do not have intuition. They operate best when given structured, explicit constraints. An AGENTS.md file creates a bridge between the raw code and the agent's reasoning engine.

While different tools explore their own ways of handling context, there is a clear trend toward standardization. Some environments use hidden directories or proprietary configuration formats. However, a Markdown file is portable, version-controlled, and instantly readable by any LLM that performs a directory listing. It reduces the hallucination rate by defining the source of truth for project rules.

What Should Go Into Your AGENTS.md

A comprehensive instruction file should not just repeat the README. It needs to address the technical specificities that an AI agent might miss during a simple grep of the filesystem. Consider including the following categories:

• Tech Stack Details: Specify exact versions and preferred libraries, especially if the project uses older versions that conflict with the LLM's training data.
• Architecture Patterns: Define if the project uses Hexagonal Architecture, Feature-Sliced Design, or a traditional MVC approach.
• Testing Protocols: Outline how to run tests, where new tests should live, and the required coverage thresholds.
• Coding Style: Mention specific linting rules or naming conventions that are not strictly enforced by the compiler.
• Forbidden Patterns: Explicitly list libraries, functions, or patterns that the agent must never use, such as deprecated APIs.

How Modern Tools Interpret Project Rules

Most coding assistants work by ingesting context through a combination of RAG (Retrieval-Augmented Generation) and direct file access. When an agent enters a repo, its first task is often to look for a map. Tools like Claude Code or Codex CLI are designed to perform better when they have clear boundaries.

In the Deska ecosystem, this file plays a pivotal role. Deska is a free desktop app for Mac, Windows, and Linux that provides an infinite canvas for development. Within this workspace, you can run multiple tools side by side as panels, including specialized coding assistants. Because Deska is a local-first environment, your AGENTS.md file stays on your machine, ensuring that your architectural secrets remain private while still guiding the AI.

When you use the integrated coding agents in Deska, they can access the local filesystem directly. If your project contains an AGENTS.md file, these agents can reference it to ensure they don't suggest a React hook in a Vue component or vice versa. This is particularly useful when you have multiple panels open, such as a terminal and a code editor, and you want the AI to understand the relationship between them.

Structuring the File for Maximum LLM Clarity

Writing for an AI requires a different mindset than writing for a human. Use clear, imperative language. Avoid fluff and focus on actionable constraints.

1. Use Header Hierarchies: Use H2 and H3 tags to categorize information so the agent can navigate the document structure easily.
2. Provide Examples: If you want a specific style of documentation or unit test, include a small code block as a reference.
3. Define Workflow Commands: List the specific CLI commands for building, linting, and starting the dev server.
4. Update Frequency: Treat this file as a living document. Whenever a new architectural decision is made, update the AGENTS.md before you even open a PR.

Comparing Approaches to Agent Orchestration

Different IDEs and editors have experimental ways to manage context. Some use hidden dotfiles, while others rely on cloud-based indexing. These approaches differ in approach compared to a plain text Markdown file. The advantage of the Markdown approach is its universality; it works across VS Code, Vim, and standalone desktop apps.

For developers who prefer a specialized environment, Deska offers a workspace where you can run Claude Code, Codex CLI, and OpenCode simultaneously. By seeing these agents operate in parallel panels, you can observe how each one reacts to your AGENTS.md instructions. You might find that one agent is better at following architectural rules while another excels at writing the actual test cases based on those rules.

Privacy and Security Considerations

One of the greatest concerns with AI development is where your data goes. If you use cloud-based editors, your project context is often stored on remote servers. A local-first approach mitigates this risk. By keeping your instructions and code on your physical machine, you control the data flow.

Deska supports this by allowing you to use your own API keys, or BYOK, for the lifetime tier. This means your data and storage remain under your jurisdiction. Even when using the mobile app to monitor progress through a secure relay, the devices pair directly without exposing ports to the open internet. Your AGENTS.md file, therefore, acts as a local guide that never needs to be indexed by an external third party.

FAQ: Common Questions About AI Instruction Files

How do I stop an AI agent from ignoring my AGENTS.md?

Most agents respond to a system prompt that tells them to always check for a configuration file first. You can also explicitly point the agent to the file in your initial chat session. In Deska, you can use Ask Deska, the voice and chat assistant, to tell the workspace agents to prioritize reading the root markdown files.

Should I put AGENTS.md in gitignore?

No, it is highly recommended to commit this file to your repository. This ensures that every developer on your team, and every agent they run, is operating under the same set of constraints. It serves as the automated equivalent of a contribution guide.

Can I have multiple agent instruction files?

While one file is easier to manage, large monorepos might benefit from putting specific instructions in subdirectories. However, most current LLM tools look for a root-level file first. Sticking to a single, well-structured AGENTS.md in the root directory is usually the best approach for consistency.

Streamlining Your Workflow

Adopting a cross-agent instruction file is a small investment that pays off every time an AI assistant suggests code that actually fits your project style. Whether you are using specialized terminals or a visual canvas, having a source of truth for your AI team members is essential.

If you are looking for a way to manage these agents more effectively, you can download Deska to start building in an environment designed for modern, agentic workflows. By running your coding tools side by side on an infinite canvas, you gain the visibility needed to scale your development efforts without losing track of your project rules.