How to guide a coding agent

You can’t send a kid to a candy store, an adult to a Costco, or a coding agent to the internet without a little guidance.

Fortunately, today’s software pros have a growing number of ways to share their non-negotiables and preferences with a coding assistant before it makes its first move. We spoke with a few who shared how to form those important guidelines.

How may I assist you? A global survey of more than 24,000 developers by software company JetBrains, conducted between April to June 2025, found that 85% of respondents “regularly use AI tools for coding and development,” while 62% “rely on at least one AI coding assistant, agent, or code editor.”

An open-standard file known as AGENTS.md can be placed into a repo and provide AI coding agents with plain-text guidance for how to build, test, and contribute to a project. The “md,” or markdown file, which is read natively by tools like Codex, Cursor Copilot, and Gemini CLI, acts as a traditional README file (i.e., documentation of a folder’s contents, naming conventions, and dataset) for the agent.

The best strategy for building an AGENTS.md file, according to Kevin McDonald, principal consultant at tech consultancy Hylaine, is to first ask yourself, “What would a person who has never seen this code need to know in order to be able to start contributing as soon as possible?” he wrote to IT Brew in an email after a discussion on AI-assisted load testing.

“Coding assistants behave a lot like humans do, just faster, so setting up the AGENTS.md file like a README works perfectly well,” McDonald shared in his message.

In that email, he revealed a sample of the guidelines he uses to create an effective AGENTS.md. The file, he recommended, should likely contain:

• A high-level, concise description of the purpose of the app. (“Build a polished, minimal sales-demo facade for Company A. It is a standalone first-impression home page that visually introduces users to Company A,” McDonald suggested.)
• The type of application contained in the project (web app or a connected to an IoT app for example).
• A bulleted list of the main tech stack: for example, a programming language like TypeScript; library like React 19; build tool like Vite; runtime environment like Node.js 22; and package manager like npm.
• An explicit set of instructions for how the agent should add code. (“Before large edits, agents should: 1. Identify affected layer(s). 2. Confirm new files are placed in the correct folder. 3. Ensure imports follow dependency direction. 4. Run build/tests relevant to the change. 5. Summarize what changed and why,” McDonald wrote as a suggestion.)
• Any conventions that must be adhered to (i.e., directory structure, dependency flow, and design patterns).
• And specific patterns to avoid, especially if they conflict with general conventions.

Proper context. But not everyone believes in the power of agent-friendly documentation; recent research from ETH Zurich, for example, concluded that the context file has “only marginal effect on agent behavior.”

Some software engineers, like Ras Mic on an April episode of the Startup Ideas podcast, argue that the files use unnecessary tokens, adding context “at every turn.” He also noted the markdown file’s usefulness when dealing with proprietary information or methodology “that is specific to you that has to be referenced in every single conversation.”

Today’s developers trying to inform their coding agents also need to steer their LLMs around malicious activity, like false READMEs and package updates containing malware.

While Andrew Southall, cybersecurity pro and founder of analytics and automation firm Truly Digital, doesn’t use md files, he guides his Codex instances with system prompts via the command line like, “prefer standard JavaScript APIs over external libraries,” or “Do not use external libraries unless the request explicitly requires them.” Those are bundled into a system.md, which gets coded into overall developer instructions covering multiple repos. He’ll review the outputs, too, and the command lines are run in an enclosed, sandboxed environment.

“You do have to tell it those exact qualitative standards. You can’t just kind of go assume it expects it because it’s trained off the internet and the internet’s full of garbage,” he told IT Brew.