Follow these best practices when creating an AGENTS.md file or a tool-specific file like a .builderrules file for the best results.
- AI instructions are essential to creating code that aligns with your application's code and design style.
- Your AI instructions should develop and change over time, as you notice common pitfalls during the code generation process.
- As opposed to duplicating content for tool-specific configuration files, reference existing files.
AI agents can produce sophisticated code while simultaneously making basic mistakes that contradict project conventions. Configuration files address this inconsistency by providing agents with project-specific guidelines and standards.
Fusion provides 3 ways to instruct the AI:
- Through an AGENTS.md file. This file is an industry standard that can be used by several AI coding agents. Visit AGENTS.md for details.
- Through several files placed within a .builder/rules/ directory. These files can be scoped to discuss specific files or topics.
- Through one or more files called .builderrules which can be placed within the root directory or any directory within your application. These configuration files can live side-by-side with the functional files that they describe.
All of these files work very similarly, and Fusion will process all of them. The key difference between them lies in how you wish to architect your application's instructions.
For more details on the different types of files Fusion accepts for providing AI instructions, visit Project configuration files.
The following example demonstrates a comprehensive AGENTS.md file configuration that addresses common AI agent challenges.
Although the following example is specifically for an AGENTS.md file, the best practices described in this doc apply to .builderrules files and those files placed within a .builder/rules/ directory.
For more details on the difference between these files, visit Project configuration files and Builder rules.
This configuration includes coding standards, operational guidelines, project navigation, and quality assurance requirements.
# AGENTS.md
### Do
- Use MUI v3. Ensure your code is v3 compatible.
- Use Emotion CSS with the `css={{}}` prop format.
- Use MobX for state management with `useLocalStore`.
- Use design tokens from `DynamicStyles.tsx` for all styling. Do not hard code values.
- Use Apex Charts for charts. Do not supply custom HTML.
- Default to small components.
- Default to small diffs.
### Don't
- Do not hard code colors.
- Do not use divs if we have a component already.
- Do not add new heavy dependencies without approval.
### Commands
File-scope checks are preferred, such as:
```
npm run tsc --noEmit path/to/file.tsx
npm run prettier --write path/to/file.tsx
npm run eslint --fix path/to/file.tsx
```
Run tests with the following command.
```
npm run vitest run path/to/file.test.tsx
```
Only run a full build with the following command when explicitly requested.
```
npm run build:app
```
### Safety and Permissions
**Allowed without prompt:**
- Read files, list files
- TypeScript single file, Prettier, ESLint
- Vitest single test
**Ask first:**
- Package installs
- Git push
- Deleting files, chmod
- Running full build or end-to-end suites
### Project Structure
- See `App.tsx` for our routes.
- See `AppSideBar.tsx` for our sidebar.
- Components are in `app/components`.
- Theme tokens are in `app/lib/theme/tokens.ts`.
### Good and Bad Examples
- Avoid class-based components like `Admin.tsx`.
- Use functional components with hooks like `Projects.tsx`.
- Forms: Copy `app/components/Form.Field.tsx` and `app/components/Form.Submit.tsx`.
- Charts: Copy `app/components/Charts/Bar.tsx` and `app/lib/chartTheme.ts`.
- Data layer: Use `app/api/client.ts`. Do not fetch in components.
### API Documentation
- Documentation in `./api/docs/*.md`
- List projects: GET `/api/projects` using `app/api/client.ts`
- Update project name: PATCH `/api/projects/:id` using `client.projects.update`
### PR Checklist
- Format and type check: Green
- Unit tests: Green. Add tests for new code paths.
- Diff: Small with a brief summary
### When Stuck
- Ask a clarifying question, propose a short plan, or open a draft PR with notes.
### Test-First Mode
- Write or update tests first on new features, then code to green.
### Design System
- Use `@acme/ui` per the indexed documentation in `./design-system-index/*.md`.
- Tokens come from `@acme/ui/tokens`.The sections that follow explain each configuration component and demonstrate how to build similar guidelines for your project.
For a comprehensive walkthrough with visual examples and detailed explanations, see the blog post Improve your AI code output with AGENTS.md.
AI agents perform optimally when provided with explicit, detailed guidelines. Comprehensive specifications for coding standards, architectural patterns, and implementation preferences improve output quality.
Begin with concise, focused rules and expand the configuration as additional requirements emerge through continued testing.
For example, at the beginning of the example file is a list of Dos and Don'ts:
### Do
- Use MUI v3. Ensure your code is v3 compatible.
- Use Emotion CSS with the `css={{}}` prop format.
- Use MobX for state management with `useLocalStore`.
- Use design tokens from `DynamicStyles.tsx` for all styling. Do not hard code values.
- Use Apex Charts for charts. Do not supply custom HTML.
- Default to small components.
- Default to small diffs.
### Don't
- Do not hard code colors.
- Do not use divs if we have a component already.
- Do not add new heavy dependencies without approval.There are several benefits to this approach:
- Version-specific guidelines prevent compatibility issues that arise from library mismatches, such as code that functions correctly in one version but fails in another.
- Explicit state management specifications eliminate ambiguity in implementation approaches, ensuring consistent patterns across the codebase.
- Emphasizing small components and focused changes maintains code readability and simplifies the review process.
AI agents frequently execute full project-wide build commands unnecessarily, particularly in large codebases where these operations can require several minutes to complete.
Since agents track the specific files they modify, most essential commands including type checking, formatting, and testing can be executed on individual files rather than the entire project.
Specifying file-scoped command formats enables faster feedback cycles and reduces computational overhead. This targeted approach allows agents to validate changes efficiently without processing unmodified code.
### Commands
File-scope checks are preferred, such as:
```
npm run tsc --noEmit path/to/file.tsx
npm run prettier --write path/to/file.tsx
npm run eslint --fix path/to/file.tsx
```
Run tests with the following command.
```
npm run vitest run path/to/file.test.tsx
```
Only run a full build with the following command when explicitly requested.
```
npm run build:app
```There are several benefits to this approach:
- File-scoped commands significantly reduce execution time, enabling type checking of individual files in seconds rather than minutes.
- This approach conserves computational resources and CI minutes by avoiding unnecessary full project builds for minor changes such as property renaming.
- The improved speed and efficiency of targeted commands allows for routine validation checks that enhance code correctness without performance penalties.
Define which operations agents can execute without approval and which require permission. Clear boundaries prevent unexpected behavior while maintaining workflow efficiency.
### Safety and Permissions
**Allowed without prompt:**
- Read files, list files
- TypeScript single file, Prettier, ESLint
- Vitest single test
**Ask first:**
- Package installs
- Git push
- Deleting files, chmod
- Running full build or end-to-end suitesThere are several benefits to this approach:
- Prevents unexpected operations like automatic package installations.
- Establishes secure defaults by controlling operations that can mutate state or access networks.
While AI agents can discover project structure through exploration, providing direct navigation references eliminates redundant codebase analysis across conversation sessions. This configuration functions as a lightweight index for essential project components:
### Project Structure
- See `App.tsx` for our routes.
- See `AppSideBar.tsx` for our sidebar.
- Components are in `app/components`.
- Theme tokens are in `app/lib/theme/tokens.ts`.There are several benefits to this approach:
- Direct file references enable agents to locate relevant code immediately, mirroring typical developer workflow patterns.
- Critical files such as routing configurations and design tokens remain accessible when needed to improve contextual relevance in generated code.
Concrete file references provide more effective guidance than abstract principles. Specify exemplary implementations for agents to replicate while identifying deprecated patterns to avoid.
### Good and Bad Examples
- Avoid class-based components like `Admin.tsx`.
- Use functional components with hooks like `Projects.tsx`.
- Forms: Copy `app/components/Form.Field.tsx` and `app/components/Form.Submit.tsx`.
- Charts: Copy `app/components/Charts/Bar.tsx` and `app/lib/chartTheme.ts`.
- Data layer: Use `app/api/client.ts`. Do not fetch in components.There are several benefits to this approach:
- Explicit example references prevent agents from replicating outdated code that remains functional but contradicts current standards.
- Pattern-based guidance ensures new code follows established best practices rather than inconsistent legacy approaches.
To enable agents to generate functional interfaces with live data integration, provide direct references to API documentation and typed client implementations. Concise pointers to these resources eliminate guesswork in data integration.
MCP servers can expose external documentation not included in the repository. Configuration guidance for MCP server usage can also be specified within the file.
### API Documentation
- Documentation in `./api/docs/*.md`
- List projects: GET `/api/projects` using `app/api/client.ts`
- Update project name: PATCH `/api/projects/:id` using `client.projects.update`Direct API reference access ensures agents implement correct data integration patterns from initial generation and reduces iteration cycles and debugging requirements.
Define explicit criteria for pull request readiness using clear, actionable requirements. This mechanical approach ensures consistent standards across all contributions.
### PR Checklist
- Format and type check: Green
- Unit tests: Green. Add tests for new code paths.
- Diff: Small with a brief summaryStandardized requirements ensure uniform quality gates for all code changes. Predictable PR formats reduce review time by establishing clear expectations for contributors and reviewers.
Provide clear guidance for handling uncertainty situations. Agents should request clarification or propose implementation plans rather than making assumptions when faced with ambiguous requirements.
### When Stuck
- Ask a clarifying question, propose a short plan, or open a draft PR with notes.Proactive communication prevents extensive incorrect implementations by encouraging early clarification of uncertain requirements.
Specify test-driven development requirements to ensure correctness from the outset. Guidance on tests can enforce this workflow when appropriate.
### Test-First Mode
- Write or update tests first on new features, then code to green.Test-first approaches establish expected behavior before implementation, preventing specification drift and ensuring comprehensive coverage.
If your design system lives in a separate package, the agent guesses how to use it. Index your system so the agent learns component APIs, tokens, and examples. Then reference that output here.
### Design System
- Use `@acme/ui` per the indexed documentation in `./design-system-index/*.md`.
- Tokens come from `@acme/ui/tokens`.Comprehensive design system documentation reduces custom styling overrides and improves adherence to established design patterns. Clear component specifications eliminate guesswork in UI implementation decisions.
Some tools require specific configuration file names. Since agents can reference external files, tool-specific configurations can simply point to existing configuration files.
For example, Claude Code depends on a CLAUDE.md file for its instructions. Instead of duplicating your existing files, reference them within the CLAUDE.md file.
# CLAUDE.md
Strictly follow the rules in ./AGENTS.mdThis approach enables multiple tool-specific files while maintaining a single source of truth.
When writing your AI instructions, keep the following in mind:
- Start with a simple list of what to do and what to avoid, then add more details based on how the AI agent actually behaves.
- Test your instructions and improve them over time to make sure they solve real problems, not imaginary ones.
- Keep your configuration short and focused.
- Use specific examples and point to actual files in your project.
- Include commands for common tasks like checking code, formatting, and running tests.
- Add new rules only when you notice the same problems happening repeatedly.
Remember, to test how well your AI instructions work, use Fusion to see the results in your actual codebase.
For step-by-step examples, visual demonstrations, and real-world case studies showing the impact of different configuration approaches, visit the blog post Improve your AI code output with AGENTS.md.
To learn more about the various ways to influence AI code generation within Fusion, visit Configuration files.