Starting With AGENTS.md: Five Steps to Building an Agent-Friendly Project

on Aug 2, 2026, tagged translations, ai, ai-agents, agentsmd, processes (share this post, e.g., on Mastodon or on Bluesky)

While recently reorganizing the references directory of Better Harness, I discovered an interesting issue: the practices accumulated there are becoming increasingly complete, but people encountering coding agent engineering for the first time actually find it harder to judge what to do first.

If you’ve had a coding agent modify a real project, you’ve probably seen this scenario: It can quickly find the code, make the changes, and even run the tests; but in a different conversation, it has to guess all over again what commands the project uses, which documents are reliable, and which files cannot be modified. You keep adding to the prompt, but the experience never truly stays in the project.

The problem isn’t just that the agent lacks context, but that the project hasn’t yet transformed its working methods into an engineered interface that AI can discover, execute, and verify.

AGENTS.md, the core documentation, skills, CLI, MCP, hooks, tests, and permissions each address different issues along this path. Individually, they resemble a continuously expanding set of configurations; however, when viewed within the context of the project’s growth, the order is actually quite clear:

Define clear entry points → Connect core knowledge → Codify repetitive processes → Integrate execution tools → Return to real-world tasks

A project that is agent-friendly is not defined by how many tools are installed, but by whether project knowledge can be discovered, processes can be executed, results can be verified, and experience can be applied to the next task.

Step 1: First, Use AGENTS.md to Provide the Agent With a Project Map

When a new employee joins a project on their first day, we usually don’t hand them the entire architecture document directly. Instead, we tell them what the project does, where the code is, how to start it, what tests to run after making changes, and which parts to avoid touching.

When a coding agent enters the repository, it needs such a map, too. This is the most easily understood use of AGENTS.md.

Different coding agents may have varying levels of support for filenames and loading scopes, but the content AGENTS.md carries should be as stable as possible: the package manager and runtime used by the project, installation and testing commands, conventions that cannot be inferred from the directory structure, the location of generated files, and security boundaries involving credentials, database migrations, and releases.

There’s no need to rewrite what the agent can see from the code. What’s truly worth including are facts that the agent can’t see but are easily guessed incorrectly. For example:

• The repository contains traces of both npm and pnpm, so which one is currently being used?
• A directory may look like source code, but it was actually generated by a tool.
• A full test run takes half an hour. When modifying a module, which focused command should be run first?

If you’re unsure how to get started, you can start by creating a very short AGENTS.md in the root directory of the repository:

# AGENTS.md

* Install dependencies: `pnpm install`
* After making changes, run first: `pnpm test -- <relevant-tests>`
* Do not edit directly: `dist/`, `generated/`
* Before modifying module boundaries: read `docs/ARCHITECTURE.md`
* For database migrations or releases: Request human confirmation first

This is just a minimal illustration; the commands and paths must be replaced with actual content available in your project, and you must run them yourself.

A practical AGENTS.md should be concise, accurate, actionable, and directly relevant to the current project. AGENTS.md Review also emphasizes an important principle: progressive disclosure. The root directory contains only the descriptions needed for most tasks; more detailed architecture, design, and workflows can be accessed as needed via links.

The first step doesn’t need to be a perfect agent manual. Focus on clearly defining the entry points, commands, risks, and documentation navigation to ensure the agent can enter the project correctly.

Step 2: Connect the Core Documents to the Task Path

With a project map, the agent only knows how to get started; it doesn’t yet understand why the code is organized the way it is. The knowledge that truly impacts the quality of changes remains scattered throughout architectural decisions, design specifications, testing strategies, and operational manuals.

The second step is to make these documents go from “existing in the repository” to “being found when the task reaches this point.”

Common core documents include ARCHITECTURE.md, DESIGN.md, coding standards, test guidelines, release notes, and runbooks. The names don’t need to be uniform, but their responsibilities should be clear: Architecture documents explain module boundaries and dependency directions; design documents record interface and interaction constraints; coding standards document the team’s unique technology choices; and test guidelines and runbooks explain how to verify and diagnose the system.

Just putting a string of links at the end of AGENTS.md isn’t enough. A more effective approach is to give the reading conditions as well:

* Before modifying module boundaries, read ARCHITECTURE.md;
* Before adjusting the public interface, check DESIGN.md;
* Before changing the release process, read the Runbook.

This short sentence connects the document to a specific task, forming a minimal knowledge route.

Ideally, there is only one authoritative source for the same fact. Architectural constraints belong to the architecture document, and AGENTS.md is only responsible for taking the agent there; if test commands are already provided by scripts, the documentation is responsible for explaining how to choose them, rather than copying a potentially outdated command. Therefore, Knowledge Asset Review focuses not on the quantity of documents, but on whether, when faced with a specific task, a piece of knowledge can be found, whether it remains accurate, and whether it can be acted on once read.

At this stage, AGENTS.md handles navigation, the core documents provide the explanations, and the source code and tests offer the final facts. The project begins to have a set of knowledge routes that agents can use, no longer relying on a single, all-encompassing prompt.

Step 3: Extract Your First Skill From Repetitive Tasks

Documentation is suitable for explaining stable knowledge, but some tasks involve more than just “knowing what”; they also include a set of recurring judgments and steps.

Every release requires checking the version, change log, and artifacts; every investigation of a production issue requires collecting logs, narrowing down the scope, and verifying fixes; every code review requires verifying final changes, test evidence, and risk boundaries. If the team has to remind the agent every time, this process is worth observing.

A skill can be understood as a work manual that is loaded on demand by the agent. It answers how a task should be completed: when to trigger, what inputs are needed, in what order to execute, what results to produce, how to verify, and under what circumstances to stop and hand it over to a human.

However, recurrence does not equate to immediate skill creation. A practical Skill Discovery threshold is: Similar needs have occurred at least twice; or although they have only occurred once, they are costly, risky, and likely to recur. Furthermore, it’s essential to confirm that the input is relatively stable, the steps are reusable, the results are verifiable, and the skill is not covered by existing documentation, scripts, or skills.

If you’re unsure where your first skill should come from, you can review your most recent conversations with the agent:

• Which requirements have already been explained twice?
• Which checks need a manual reminder every time?
• Which failures are most likely to recur after a fix?

They are generally more worth prioritizing than a generic list of recommended skills.

For example, the team encountered the same type of problem several times during code reviews: The agent only checked unstaged changes; tests ran against earlier code while the final commit had changed again; the summary stated “test passed” but didn’t record the specific commands. Instead of continuing to add reminders to AGENTS.md, it would be better to organize “review final changes” into a skill, which would standardize the scope of changes collected, run corresponding checks, record verification evidence, and list any uncovered risks.

A prompt addresses how to proceed in this round; a skill, on the other hand, ensures that the next agent to encounter the same kind of task still works in the same way.

Step 4: Transform Repetitive Processes Into Executable Engineering Interfaces

Writing the skill only defines the method. For the process to actually run, the agent also needs to read data, perform checks, or operate external systems.

At this point there’s no need to add an MCP Server right away. For projects that already have scripts or command-line tools, the CLI is usually the lowest-cost and easiest-to-reproduce starting point. An agent-friendly CLI should:

• make usage discoverable via --help;
• support non-interactive execution;
• provide stable output, offering structured formats such as JSON when necessary;
• return a clear error and exit status on failure;
• provide timeouts for time-consuming operations;
• support plan or dry-run before modifying external state.

Such a CLI can serve developers, agents, scripts, and CI simultaneously, and it’s easy to reproduce agent operations locally. When a team already uses gh, kubectl, or an internal operations CLI, consolidating those capabilities into a stable interface first is usually lighter than repackaging a separate set of tools for every agent host.

Prioritizing CLI does not mean rejecting MCP. MCP remains suitable when external systems lack appropriate command-line entry points or require structured resource discovery, host integration, or continuous interaction. The key is to build CLI and MCP on the same underlying capabilities and permission rules, rather than defining input, output, and error semantics separately.

Furthermore, not every problem should be left to a skill reminder. Rules a program can decide unambiguously—such as prohibiting changes to generated files—should be checked automatically by scripts, hooks, or CI; anything involving production environments, credentials, and irreversible operations should keep access control, sandboxing, or manual confirmation in place.

The principle behind Agent Customize Routing is simple: First build stable underlying capabilities, then choose the smallest and most suitable support mechanism for the problem. The number of tools does not represent maturity; only when responsibilities are clear, processes are reproducible, and results are verifiable can it be said to have truly entered the engineering process.

Step 5: Return to the Real Task and Let the Project Learn From the Experience

Once the agent completes the modifications and the tests pass, we can easily move on to the next requirement. But don’t rush to finish: Open the final code changes, confirm that the tests cover the modified version, and then check if it has completed the necessary reviews and CI. Writing the code is only part of the process; the task is only complete when the result can be verified and delivered.

Better Harness refers to the process from understanding requirements, finding knowledge, implementing modifications, to verifying delivery as the Agent Work Loop. In this loop, AGENTS.md helps the agent enter the project, the core documentation provides context, skills and tools drive task execution, and tests, hooks, and permissions safeguard results and boundaries.

After delivery, take another look at the task: Did the agent search for the startup command again? Did it make the same mistake again in the same directory? Does it still need someone to remind it of a certain check? Also, pay attention to the paths that have worked, such as whether a certain troubleshooting step has helped the task several times in a row.

These recurring frictions and valuable lessons learned are the starting point for the next round of improvements. Loop Discovery can be used to determine where these lessons should be accumulated:

• Stable facts are written back to AGENTS.md or the core documents;
• Repeated methods are organized into skills;
• Deterministic operations and checks should be handled by CLI, scripts, hooks, or CI;
• MCP should only be used when external resource discovery or continuous interaction is truly required;
• For high-risk, irreversible operations, retain access boundaries and require manual confirmation.

However, writing it into the repository doesn’t mean the practice is effective. Whether the agent can find and use it when a similar task comes next, thus avoiding rework or reminders, is what decides whether the practice is worth keeping.

Continuous improvement doesn’t mean constantly adding configurations, but rather ensuring that what’s left from this task truly helps the next one.

If you’re just starting out, choose a recent real-world task: Guide the agent from understanding requirements to validation and delivery, and at the end, capture just the single most reusable lesson.

The project doesn’t need to have a complete agent platform from day one. It just needs to start remembering how it works.

When this cycle starts, AI coding will no longer be just a clever tool for individuals to use temporarily, but will gradually become an engineering capability that the project itself possesses.

(This post is a machine-made, human-reviewed, and authorized translation of phodal.com/­blog/­building-agent-friendly-projects/­.)