How to Write an AGENTS.md File: A Pre-Build Checklist

A coding agent can make a confident change in the wrong folder if it does not know how your project is organized. Before your next session, check the instructions you plan to give it. Learning how to write an AGENTS.md file starts with recording the few project facts that should survive a new conversation, then checking that your particular tool reads the file where you put it. A stale instruction can be worse than no instruction because it sounds authoritative.

What belongs in an AGENTS.md file?

Keep this file about repeatable working rules. It should help an agent find the right code, run the relevant checks, and avoid changes that would surprise you. Each item below should describe your actual repository, not the repository you expect to have later.

• State the project’s purpose. Use a sentence such as “This app tracks appointments for a single user.” The agent needs the current scope, not a pitch for future features.
• Name the important locations. Point to the folders for application code, tests, and configuration only if those folders exist.
• Give the commands you actually run. Include the relevant install, development, and test commands. Run them yourself before asking an agent to rely on them.
• Identify the current source of truth. Say where requirements or product decisions live so an old chat message does not quietly become the specification.
• Set a boundary for risky changes. For example, require review before changing authentication, database structure, or destructive actions. Keep the rule specific enough to act on.

A compact file is easier to maintain than a long catalog of preferences. If a line cannot change what the agent does during a build, it probably belongs elsewhere.

What should you check before relying on it?

AGENTS.md is a convention used by coding tools, but support and file-discovery behavior can vary. Check your tool’s current documentation for where it looks and which instructions take priority. Then make a small request and inspect the result rather than assuming the file was read.

• Place the file where your tool expects it. Confirm the location in that tool’s documentation, especially when working across multiple repositories or folders.
• Remove instructions that conflict. A rule to avoid database edits cannot sit beside an unconditional request to implement persistence without clarifying when review is needed.
• Exclude secrets and credentials. Instructions can explain which environment variables the app needs without containing their values.
• Ask for a visible verification step. Request that the agent name the command it ran and report any check it could not complete.
• Test one instruction with a small change. Ask for a minor edit, then review the diff and the agent’s explanation to see whether the instruction affected its work.

The file does not replace review. An agent may misunderstand a rule, and even a correctly followed rule can produce a bug. Check changed files and rerun the flows that matter before deploying.

When should you update the file?

Revisit AGENTS.md when a command changes, a folder moves, or you discover a rule you keep repeating in prompts. Remove instructions that describe an old architecture. A short note about today’s unfinished feature belongs in your session notes unless it has become a durable rule for future work.

Use this end-of-session software project journal checklist to capture unfinished work and your next action without making either a permanent agent rule.

A quick maintenance pass after a meaningful change is enough. Compare the file with the repository as it exists, then fix any mismatch while the decision is still fresh. To keep session notes, feature work, and prompts connected without loading every temporary detail into AGENTS.md, organize your build context in VibeCrumbs.