An AGENTS.md file gives a coding agent project specific instructions before it starts work. The most useful file is not a second copy of your whole documentation. It tells the agent how this repository is organized, which conventions matter, how to check a change, and where it should pause for a person. Clear instructions help more than a long list of general advice.
Write down what a new contributor needs first
Start with the facts that would otherwise take someone time to discover: the important directories, the way the app is divided, the command used to run it, and the checks expected before a change is done. Be specific. “Keep the project clean” gives an agent little to follow. “Run npm run build after changing a route” is useful when that command is real and current.
Keep instructions close to the code they describe. A root AGENTS.md can set shared rules, and a narrower file can explain a particular package or subsystem. Remove details when they become stale. An old command in an instruction file can be more confusing than no instruction at all.
- Name the directories and files that contain the feature logic.
- State the project conventions that are not obvious from nearby code.
- List the exact checks that prove a routine change is complete.
- Describe boundaries such as protected files, generated output, or required approval.
Use a small template, then edit it for the repository
The sample below is a starting point, not a rule book. Replace every placeholder with a command and location you have verified. If a project has no test suite, do not tell the agent to run tests that do not exist. Say what it can check instead and ask it to report anything it could not verify.
LucentraCode can be configured to use AGENTS.md as a project instruction file. Other tools have their own rules for discovering instruction files, so check each agent’s documentation before relying on one file to control every product.
A prompt to adapt
# Project guide
## Structure
The main application lives in [directory].
Shared code lives in [directory].
## Before editing
Read [key file] and the closest existing example.
Keep changes within the requested behavior.
## Checks
Run [verified command] for application changes.
Run [verified command] for tests.
Report checks that could not run.
## Boundaries
Do not edit generated files in [directory].
Ask before changing dependencies, data formats, or deployment settings.
Review the full diff before finishing.Keep instructions separate from the task prompt
The project file should hold stable information. The task prompt should describe the current change. Put temporary details, acceptance criteria, and a specific bug report in the request rather than changing the repository guide for one task.
If an instruction is already enforced by a formatter, test, or permission setting, say where that control lives instead of repeating a long explanation. Instructions help the agent reason. They do not replace automated checks or access controls.
Review the file like code
Ask a teammate who knows the repository whether the guide is correct. Check that example commands work from the expected directory and that nested instructions do not contradict the root. Keep the file in version control so contributors can review changes to the agent’s working rules.
A concise guide can make a multi model workflow more predictable. It does not guarantee that every agent will follow every instruction, so keep human review and project checks in place.