AGENTS.md Configuration

​

What is AGENTS.md?

​

Creating an AGENTS.md file

​

Basic structure

# Project Guidelines

## Common Commands
- `npm test` - Run the test suite
- `npm run build` - Build for production
- `npm run dev` - Start development server

## Key Files
- `src/components/` - Reusable UI components
- `src/utils/` - Utility functions
- `config/` - Configuration files

## Code Style
Follow the guidelines in CONTRIBUTING.md

​

What to include

• How to test or rebuild generated code
• Development server startup commands
• Build and deployment processes
• Linting and formatting commands

• Important directories and their purposes
• Entry points and configuration files
• Where to find specific types of code

• Links to style guides or coding standards
• Naming conventions for files, functions, and variables
• Branch naming patterns and Git workflows

• Framework or technology choices
• Architecture decisions
• Dependencies and their purposes

​

Example AGENTS.md

# Guidelines
For PR creation guidelines, check dev/docs/pull-request-guidelines.md
For Go modifications, follow the rules in dev/docs/go-styleguide.md
For frontend modifications, follow the rules in dev/docs/frontend.md
For vscode changes, follow the rules in dev/docs/vscode.md

# Feature work
- use feature branches from main for pushing work following this naming pattern:
  - [2-3 initials from git config user.name]/[[numeric-part-of-issue-ID?]-][2-3 words shorthand of the topics, separated by dashes]]
  - should not be more than 24 characters total
  - extract initials by taking first letter of each word from git user.name (e.g., "John Doe" → "jd", "Alice Smith Johnson" → "asj")
IMPORTANT: Always run git config user.name first to get the actual name - do not assume or guess the initials

# Code generation
- ALWAYS use leeway scripts to generate code, e.g. `leeway run api/def:generate` instead of running `buf generate` directly.
- Use `leeeway collect scripts` to understand what code generation scripts are available.

​

Best practices

​

Keep it concise

• Focus on essential information that affects how Ona Agent works on your project
• Avoid duplicating information that’s already well-documented elsewhere
• Reference other files when appropriate rather than copying content

​

Use emphasis for critical rules

• Use IMPORTANT or ALWAYS in all caps to highlight critical requirements
• Bold key terms and commands for better readability
• Use bullet points for easy scanning

​

Reference external documentation

• Link to existing style guides, contributing guidelines, or architecture docs
• Point to specific files rather than duplicating their content
• Keep the AGENTS.md file as a navigation hub

​

Make it actionable

• Provide specific commands rather than general descriptions
• Include exact file paths and naming conventions
• Give concrete examples of branch names, commit messages, etc.

​

How Ona Agent uses AGENTS.md

​

Automatic loading

• Ona Agent automatically reads AGENTS.md at the start of every conversation
• The content becomes part of the agent’s context for the entire session
• No additional commands or setup required

​

Context integration

• Instructions from AGENTS.md influence all of Ona Agent’s responses
• The agent will follow the guidelines when making code changes
• Commands and conventions are applied consistently across tasks

​

File references

• When you reference other files in AGENTS.md, Ona Agent will read them as needed
• This allows you to keep the main file concise while providing detailed guidance
• The agent understands the project structure through these references

​

Updating AGENTS.md

​

Version control

• Commit AGENTS.md changes like any other project file
• Include updates in pull requests when changing project conventions
• Document significant changes in commit messages

​

Team collaboration

• Ensure all team members understand the AGENTS.md conventions
• Update the file when project structure or processes change
• Review AGENTS.md during onboarding to help new team members

​

Iterative improvement

• Monitor how well Ona Agent follows the guidelines
• Refine instructions based on agent behavior and team feedback
• Add emphasis (IMPORTANT, ALWAYS) for frequently missed requirements

​

Troubleshooting

​

Agent not following guidelines

• Check that the file is named exactly AGENTS.md in the repository root
• Verify the instructions are clear and specific
• Add emphasis (bold, ALL CAPS) to critical requirements
• Consider breaking complex instructions into smaller, actionable steps

​

Guidelines being ignored

• Move the most important rules to the top of the file
• Use stronger emphasis (IMPORTANT, ALWAYS) for critical requirements
• Provide concrete examples rather than abstract descriptions
• Reference specific files or commands rather than general concepts

​

File not loading

• Ensure the file is in the repository root directory
• Check that the filename uses the exact spelling: AGENTS.md
• Verify the file contains valid markdown content
• Start a new conversation to ensure the latest version is loaded

​

Next steps

• Create an AGENTS.md file in your repository root
• Start with basic project information and common commands
• Iterate based on how well Ona Agent follows your guidelines
• Learn about slash commands for organization-wide prompts