AGENTS.md is a markdown file placed at your repository root that tells AI development tools how your project works. Unlike tool-specific files, an AGENTS.md provides unified configuration for any AI agent.
- The AGENTS.md file is a contextual and instructional file recognize by several AI agents, as described on the official AGENTS.md page.
- Creating an AGENTS.md file is recommended for all Projects, but is especially useful for software developers who use more than one AI agent as part of their development process.
An AGENTS.md file eliminates repetitive prompt instructions by establishing project conventions in one central location. Agents reference these guidelines automatically, ensuring consistent code generation that follows your project standards.
Your AGENTS.md file may include:
- Essential setup commands, build steps, and development server instructions for getting the project running quickly.
- Code style guidelines, formatting rules, and architectural patterns the project follows for consistent development.
- Testing workflows, quality checks, and merge requirements that must be completed before submitting code.
# Sample AGENTS.md file
## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.
## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.In the example above, the AGENTS.md file includes details on running the application within a development environment, testing instructions, and details for creating pull requests.
Just like with .builderrules files, AGENTS.md files can be replicated in multiple directories.
Rules should be actionable, focused, precise, and scoped.
- Keep rules under 500 lines.
- Split large rules into multiple, composable rules.
- Provide concrete examples or referenced files.
- Avoid vague guidance. Write rules like clear internal docs.
- Ensure rules in one file do not conflict with rules in another file.
For more best practices and detailed examples, visit AI instruction best practices.
Learn more about Configuration files in Fusion, or read up on AI instruction best practices.