The agent.md File: A Systematic Prompt to Improve LLM-Assisted Code Quality

What Happened: The agent.md Idea in Plain English

Fabien Sanglard, a veteran software engineer known for deep dives into graphics and systems programming, published a simple but powerful idea: an agent.md file. It’s a single, structured markdown document you place in the root of your project. When you ask a Large Language Model (LLM) to write or review code, you instruct it to read this file first. The file acts as a system prompt, but one that lives in the codebase, is version-controlled, and evolves with the project.

Sanglard’s agent.md is not a vague wishlist like "write clean code." It’s a precise, hierarchical specification. It defines the project’s language, build system, coding style, naming conventions, testing requirements, and even the exact command to run before considering a task complete. The key insight is that LLMs are powerful but amnesic and inconsistent. They need to be constantly reminded of the rules. An agent.md file is the persistent memory they lack, a contract that turns a general-purpose tool into a project-specific specialist.

The source post details a real-world example from a C project. The agent.md mandates specific compiler flags (-std=c99), a particular build system (nobuild), and a strict rule that every code change must be followed by a successful ./build.sh execution. This isn't just about code style; it's about defining a rigorous, automated "Definition of Done" that the LLM must respect.

Why This Matters for Engineers and FDEs

For a working engineer, this technique solves a familiar frustration: the LLM that confidently generates code that looks right but fails to compile, ignores your project’s architecture, or invents non-existent APIs. The agent.md is a direct countermeasure to these failure modes. It shifts the interaction from a loose, conversational style to a more deterministic, contract-driven one.

For a Forward Deployed Engineer (FDE), the value is even more acute. An FDE's life is spent in foreign codebases, building integrations, demos, and prototypes at speed. The context-switching tax is immense. You’re often the first person to stitch together a customer’s legacy system with your platform’s modern APIs. An agent.md becomes your onboarding partner. You can generate a project-specific one for a customer proof-of-concept in minutes, and then use an LLM to scaffold integrations or data pipelines that actually respect the customer’s constraints—like their specific authentication method or data format quirks. This directly relates to the core FDE skill of shipping high-quality demos fast, a topic we cover in our deep dive on the FDE toolkit.

This technique also acts as a safeguard against the subtle skill erosion we discuss in our analysis of AI coding collapse. By forcing you to explicitly define your standards, agent.md keeps you engaged in the "why" behind the rules, preventing you from becoming a passive code reviewer who just clicks "Accept."

The Anatomy of an Effective agent.md

An agent.md that actually works is not a style guide. It’s an executable specification. Here’s how to structure one, based on the core principles from Sanglard’s post and engineering best practices.

1. The Immutable Header

Start with a locked-down section that defines the non-negotiable foundation. This prevents the LLM from "helpfully" migrating you to a different build system or language standard.

# Project Context
- **Language Standard:** C99
- **Build System:** nobuild
- **Build Command:** `./build.sh`
- **Testing Framework:** Custom test harness in `./tests/`
- **Testing Command:** `./run_tests.sh`

2. The Decision Log

This is the most critical section for preventing hallucinations. LLMs are pattern-matching engines. When they see a common problem, they’ll reach for the most statistically likely solution, which is often a popular library. If you’ve explicitly decided not to use that library, you must preempt it.

# Architectural Decisions & Constraints
- **No external dependencies.** The project is self-contained. Do not suggest or use libraries like `libcurl` or `openssl`.
- **Memory management:** Use arena allocators. Do not use `malloc`/`free` directly.
- **Error handling:** Return error codes. No exceptions.

3. The Coding Style Contract

Be ruthlessly specific. Vague terms like "clean code" are meaningless to an LLM. Provide concrete, checkable rules.

# Coding Conventions
- **Naming:** `snake_case` for functions and variables. `PascalCase` for structs.
- **Formatting:** 4-space indentation. Allman style braces.
- **Comments:** No comments for self-explanatory code. Use `//` for single-line explanations of intent.
- **Includes:** Group in order: standard library, then project headers. No unused includes.

4. The Definition of Done

This is the gate. The LLM’s job is not just to produce text; it’s to produce text that passes a verifiable check. The agent.md must define this check explicitly.

# Task Completion Protocol
After writing or modifying any code, you MUST:
1. Run `./build.sh`.
2. If the build fails, analyze the error and fix the code. Do not ask for permission.
3. If the build succeeds, run `./run_tests.sh`.
4. If any test fails, analyze the failure and fix the code.
5. Report the final, successful output of both commands.

This protocol transforms the LLM from a code-suggesting tool into a goal-seeking agent. It creates a tight feedback loop where the compiler and test suite are the ultimate arbiters of correctness.

How to Actually Use This Technique Today

You can implement this in your workflow right now. The process is straightforward but requires discipline.

Step 1: Bootstrap Your agent.md

Don't write it from scratch. Use an LLM to help you. Feed it your project’s README, a few representative source files, and your package.json or CMakeLists.txt. Use a prompt like:

"Analyze this project. Generate a draft agent.md file that specifies the language standard, build system, coding conventions, and a strict task completion protocol. Base the conventions on the patterns you observe in the existing code."

Review the output critically. The LLM will get some things wrong. This editing process is where the real value lies—it forces you to articulate your own standards.

Step 2: Integrate It Into Your Prompt

When starting a new coding session, your first prompt should be:

"Read agent.md and acknowledge its constraints. You must follow the Task Completion Protocol for all responses."

For tools with persistent system prompts or project instructions (like Cursor or GitHub Copilot with custom instructions), paste the entire content of your agent.md directly into that configuration. This is the most reliable method.

Step 3: Use It for Code Review

An agent.md is a perfect reviewer’s checklist. Before submitting a PR, copy the file’s content and your diff into an LLM with the prompt:

"Review this diff against the attached agent.md specification. Flag any violation of the coding conventions, architectural constraints, or the Definition of Done."

This catches the 80% of errors that are mechanical violations of your own rules, freeing up human reviewers to focus on logic and design. This approach is a core tactic for writing technical docs that engineers and non-engineers alike can trust, similar to the principles we outline in writing customer-facing technical docs.

Step 4: Version Control and Evolve It

Your agent.md is now a living artifact of your project’s engineering culture. Commit it. When a code review reveals a recurring pattern of LLM mistakes, update the file to explicitly forbid it. When you adopt a new library, add it to the allowed list. This file becomes the single source of truth for how code should be written in this project, for both humans and machines.

A Balanced Take: The Real ROI and Hidden Costs

Let’s be honest about what this technique does and doesn’t do.

The Upside: From Stochastic Parrot to Junior Engineer An LLM without an agent.md is a brilliant, amnesic intern who has read the entire internet but never seen your codebase. It will produce code that is syntactically perfect but contextually wrong. The agent.md elevates it to the level of a meticulous junior engineer who has memorized the team’s coding standards document. It won’t make architectural breakthroughs, but it will reliably produce code that compiles, passes tests, and looks like it belongs in the project. This is a massive productivity unlock for boilerplate, data wrangling, and writing tests.

The Downside: The Specification Tax The hidden cost is the upfront and ongoing effort of maintaining the specification. A bad or incomplete agent.md is worse than no agent.md at all. It can give you a false sense of security. An LLM might follow a poorly specified rule to the letter in a way that creates a subtle bug. You’ve simply automated a bad practice. The technique also doesn’t address the more profound challenge of AI coding collapse. If you blindly accept code that passes the agent.md’s gate, you’re still not exercising your own design muscles. You must still read and understand every line.

The FDE-Specific Trade-off For FDEs building integrations, the ROI is asymmetrically high. The code you write is often glue code with strict, repetitive patterns. An agent.md that specifies the customer’s API authentication, error handling format, and logging standard can turn a half-day integration task into a 30-minute one. However, the risk is that the LLM will hallucinate the customer’s API itself. Your agent.md must include a strict constraint: "If you are unsure about an API endpoint or parameter, do not guess. State your uncertainty and ask for the relevant documentation." This prevents the most dangerous class of integration bugs. This disciplined approach to building reliable systems is exactly what we explore in our guide to building a SQL analyst agent.

FAQ: agent.md for LLM-Assisted Coding

Q: Is this just a fancy system prompt? Yes, but that’s the point. System prompts are ephemeral and tool-specific. An agent.md is a persistent, version-controlled artifact that lives with the code. It’s a system prompt that has been promoted to a first-class project dependency. You can use the same file with ChatGPT, Copilot, and Cursor, ensuring consistent behavior across tools.

Q: How detailed should the coding conventions be? As detailed as your team’s actual conventions. Don’t invent rules just for the LLM. The file should reflect your real standards. A good test: if a new human hire could read it and understand how to write code for the project, it’s at the right level of detail. The only difference is you must be more explicit about things humans take for granted, like "do not use external libraries."

Q: Won't the LLM just ignore it sometimes? Yes, especially with very long files or complex tasks. The technique is not foolproof. That’s why the "Task Completion Protocol" with its build-and-test loop is the essential enforcement mechanism. The LLM’s output is not the final product; the passing test suite is. The agent.md simply increases the probability that the first attempt will be correct.

Q: Can I use this for languages other than C? Absolutely. The concept is language-agnostic. For a Python project, your agent.md would specify the use of uv, ruff for linting, mypy for type checking, and pytest for testing. The protocol would then be uv run ruff check . && uv run mypy . && uv run pytest. The principle is always the same: define a deterministic, automated quality gate.

Q: How does this relate to the FDE role specifically? An FDE’s core value is building trust through working software, fast. An agent.md is a force multiplier for this. When you land in a new customer environment, you can pair with their lead engineer to draft an agent.md in an hour. This document then becomes the executable specification that lets you safely generate boilerplate integrations, data transformation scripts, and demo scaffolding at a pace that would otherwise be reckless. It’s a practical tool for the "trusted advisor" style of FDE work we detail in our breakdown of the Palantir-style FDE model.