AGENTS.md: How 9 Lines of Text Transform Your AI Coding Assistant

Same AI, Wildly Different Answers

Imagine this scenario: you ask an AI assistant to "add a leaderboard." Two requests, same model, same prompt — yet the results couldn't be more different. One attempt breaks an entire quiz website; the other follows every project rule to the letter. What's the difference? Nine lines of text.

The problem isn't the AI's capability — it's what the AI can actually see. From the AI's perspective, it may have "read an entire library," but in this moment, all it has is one message: "add a leaderboard." What data should the leaderboard track? How should it be displayed? The AI has no idea, so it produces the most generic, assumption-laden version it can.

Without Context, AI Just Makes Things Up

That assumption-driven leaderboard made three mistakes at once: it was overbuilt and exceeded actual requirements; it displayed full real names in a club that only shows nicknames; and nobody checked whether the quiz page still worked after the leaderboard was added.

The user, Maya, had to explain each of these constraints one by one. The AI fixed them. But once the conversation closed, its "memory" was wiped. The next day, starting fresh, it would make the exact same mistakes again. This is the core frustration with current AI coding assistants: every session starts from zero. Rules learned yesterday vanish today. The implicit conventions of a project — naming patterns, data display standards, features that must never break — all live inside the developer's head, invisible to the AI.

Write the Rules Down Once. That's It.

Maya's solution was simple: write those rules down in a small file inside the project, just once. The file ended up being nine lines long.

The mechanism is straightforward. When she starts a coding session in a CLI tool that supports this feature, the tool automatically places this file in front of the AI alongside her request. The AI hasn't "remembered" anything — it never has memory — but the file is simply re-read at the start of each conversation.

The key insight here is this: instead of relying on memory that doesn't exist, you turn context into an external file that can be read over and over. Once the rules live in a file, they don't disappear when the conversation ends. This is one of the most basic expressions of "Context Engineering" — rather than manually feeding background information every time, let the tool inject it automatically.

A note on Context Engineering: "Context Engineering" is an emerging practice in AI application development, distinct from "Prompt Engineering." Prompt engineering focuses on how to phrase a single message to get better output. Context engineering focuses on systematically managing what information the AI can see across an entire task lifecycle — including project documentation, history, tool descriptions, and constraints. AGENTS.md is one of the lightest-weight implementations of context engineering: no extra infrastructure required, just a plain text file that persists project-level knowledge and injects it into every session at zero cost. As AI takes on more complex roles in software development, the quality of context is increasingly displacing model parameter count as the key variable determining output quality.

AGENTS.md and Tool Support

In tools like Codex, Copilot, and Cursor, this file is called AGENTS.md. It lives in the project root and uses natural language to describe project conventions, style preferences, and hard limits.

Claude Code has its own convention file, CLAUDE.md — and it can also read AGENTS.md. This means a well-written convention file can be reused across multiple AI coding tools without rewriting it for each one.

For developers, this is a low-cost, high-return practice. Nine lines of text may seem trivial, but they can transform a "generic, assumption-prone, repeatedly-wrong" assistant into a collaborator that actually understands your project's rules. You don't need a more powerful model — you just need to give it the right context.

On the name "AGENTS.md": The name comes from the concept of an "AI Agent" — an AI program that autonomously executes tasks within a given context. Files like this are essentially a project-level implementation of a "System Prompt." Traditional system prompts are injected in the background by a platform or developer; AGENTS.md hands that control back to the project maintainer, stored as a version-trackable plain text file in the code repository. This means team members can review the AI's behavioral boundaries the same way they review code, and new members who clone the repo automatically inherit the same set of conventions. The coexistence of CLAUDE.md and AGENTS.md reflects how various tools are competing for ecosystem compatibility — once a convention file becomes a de facto standard, cross-tool reuse dramatically reduces the cost of team migration.

A Question Worth Sitting With

The original video ends with a thought-provoking question: if your AI read one note about you at the start of every conversation, what would the first line say?

The value of this question is that it forces you to make implicit conventions explicit — those things that normally only exist in your head. Whether it's coding standards, data privacy requirements, or hard rules like "the quiz must always be openable" — figuring out what that first line should say is often the starting point for making AI truly work for you.