What information should an AGENTS.md file provide?

What information should an AGENTS.md file provide?

An AGENTS.md file should explain how a coding agent can work successfully in a particular repository. It is most useful as a concise operating guide that points to detailed documents, rather than duplicating every product requirement or collecting an entire conversation history.

Explain how to work in this repository

Include the application layout, package manager, setup commands, and relevant validation commands. Identify where shared components, server handlers, database access, and tests belong. Mention conventions that are easy to miss, such as using the existing form components or updating an API contract when request fields change.

For a wedding application, the guide could direct agents to the PRD, permission matrix, design reference, and project-status document. This helps an agent find the agreed requirements before implementing organizer or collaborator flows.

State concrete boundaries and expectations

Useful instructions describe observable behavior: preserve unrelated edits, avoid logging credentials, enforce wedding membership on protected operations, and report which checks actually ran. Explain how the team handles schema changes, dependencies, and unresolved requirements.

Do not put API keys, user records, or production passwords in the file. Configuration examples should name required variables without including their values. Keep temporary debugging notes in a task record instead of letting them obscure permanent guidance.

Check the agent's discovery rules

Different coding agents may discover and prioritize instruction files differently. Codex supports project guidance and more specific instructions according to its documented discovery rules; do not assume every tool reads every nested file automatically. Official OpenAI guidance.

After editing the guide, verify the intended agent can find it from the relevant working directory. Keep commands accurate and remove obsolete instructions. A short, maintained file gives clearer direction than a large collection of contradictory rules.