Prompt file imported from azaharizaman/NexusErp (
.github/prompts/create-agentsmd.prompt.md). Copyright stays with the author.
Create high‑quality AGENTS.md file
...
What is AGENTS.md?
AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project. It complements README.md by containing detailed technical context that coding agents need but might clutter a human-focused README.
Key Principles
Agent-focused: Contains detailed technical instructions for automated tools
Complements README.md: Doesn't replace human documentation but adds agent-specific context
- Standardized location: Placed at repository root (or subproject roots for monorepos)
- Open format: Uses standard Markdown with flexible structure
- Ecosystem compatibility: Works across 20+ different AI coding tools and agents
... ...
Create high‑quality AGENTS.md file
...
File Structure and Content Guidelines
1. Required
Setup
- Create the file as
AGENTS.mdin the repository root - Use standard Markdown formatting
- No required fields - flexible structure based on project needs
... ...
Create high‑quality AGENTS.md file
...
File Structure and Content Guidelines
...
2. Essential Sections to Include
Project Overview
- Brief description of what the project does
- Architecture overview if complex
- Key technologies and frameworks used
Setup Commands
- Installation instructions
Environment setup steps
- Dependency management commands
- Database setup if applicable
Development Workflow
- How to start development server
- Build commands
Watch/hot-reload setup
- Package manager specifics (npm, pnpm, yarn, etc.)
Testing Instructions
- How to run tests (unit, integration, e2e)
- Test file locations and naming conventions
- Coverage requirements
- Specific test patterns or frameworks used
- How to run subset of tests or focus on specific areas
Code Style Guidelines
- Language-specific conventions
- Linting and formatting rules
- File organization patterns
- Naming conventions
- Import/export patterns
... ...
Create high‑quality AGENTS.md file
...
File Structure and Content Guidelines
...
2. Essential Sections to Include
...
Build and Deployment
- Build commands and outputs
- Environment configurations
- Deployment steps and requirements
- CI/CD pipeline information
... ...
Create high‑quality AGENTS.md file
...
File Structure and Content Guidelines
...
2. Essential Sections to Include
Project Overview
...
Setup Commands
...
Development Workflow
...
...
Code Style Guidelines
...
Build and Deployment
... ...
Create high‑quality AGENTS.md file
...
File Structure and Content Guidelines
...
- Optional but Recommended Sections
Security Considerations
- Security testing requirements
- Secrets management
- Authentication patterns
- Permission models
Monorepo Instructions (if applicable)
- How to work with multiple packages
- Cross-package dependencies
- Selective building/testing
Package-specific commands
Pull Request Guidelines
- Title format requirements
Required checks before submission
- Review process
- Commit message conventions
Debugging and Troubleshooting
- Common issues and solutions
- Logging patterns
- Debug configuration
- Performance considerations
... ...
Create high‑quality AGENTS.md file
...
File Structure and Content Guidelines
1. Required
...
2. Essential Sections to Include
...
... ...
Create high‑quality AGENTS.md file
...
Example Template
Use this as a starting template and customize based on the specific project:
# AGENTS.md
## Project Overview
[Brief description of the project, its
purpose, and key technologies]
## Setup Commands
- Install dependencies:
`[package manager] install`
- Start development server: `[command]`
- Build for
production: `[command]`
## Development Workflow
- [Development server startup
instructions]
- [Hot reload/watch mode information]
- [Environment variable setup]
##
Testing Instructions
- Run all tests: `[command]`
- Run unit tests:
`[command]`
- Run integration tests: `[command]`
- Test coverage: `[command]`
- [Specific
testing patterns or requirements]
## Code Style
- [Language and framework
conventions]
- [Linting rules and commands]
- [Formatting requirements]
- [File
organization patterns]
## Build and Deployment
- [Build process details]
- [Output
directories]
- [Environment-specific builds]
...
...
# Create high‑quality AGENTS.md file
...
## Example Template
...
- [Deployment commands]
## Pull
Request Guidelines
- Title format: [<project_name>] Brief description
- Required
checks: `[lint command]`, `[test command]`
- [Review requirements]
## Additional
Notes
- [Any project-specific context]
- [Common gotchas or troubleshooting tips]
-
[Performance considerations]... ...
Create high‑quality AGENTS.md file
...
Working Example from agents.md
Here's a real example from the agents.md website:
# 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
...
...
# Create high‑quality AGENTS.md file
...
## Working Example from agents.md
...
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.... ...
Create high‑quality AGENTS.md file
...
Implementation Steps
Analyze the project structure to understand:
-
Programming languages and frameworks used
-
Package managers and build tools
-
Testing frameworks
-
Project architecture (monorepo, single package, etc.)
-
Identify key workflows by examining:
- package.json scripts
- Makefile or other build files
- CI/CD configuration files
- Documentation files
-
Create comprehensive sections covering:
- All essential setup and development commands
- Testing strategies and commands
- Code style and conventions
- Build and deployment processes
-
Include specific, actionable commands that agents can execute directly
-
Test the instructions by ensuring all commands work as documented
-
Keep it focused on what agents need to know, not general project information
... ...
Create high‑quality AGENTS.md file
...
Best Practices
- Be specific: Include exact commands, not vague descriptions
- Use code blocks: Wrap commands in backticks for clarity
- Include context: Explain why certain steps are needed
- Stay current: Update as the project evolves
- Test commands: Ensure all listed commands actually work
- Consider nested files: For monorepos, create AGENTS.md files in subproject directories as needed
Monorepo Considerations
For large monorepos:
- Place a main AGENTS.md at the repository root
- Create additional AGENTS.md files in subproject directories
- The closest AGENTS.md file takes precedence for any given location
- Include navigation tips between packages/projects
... ...
Create high‑quality AGENTS.md file
...
Final Notes
- AGENTS.md works with 20+ AI coding tools including Cursor, Aider, Gemini CLI, and many others
- The format is intentionally flexible - adapt it to your project's needs
- Focus on actionable instructions that help agents understand and work with your codebase
- This is living documentation - update it as your project evolves
When creating the AGENTS.md file, prioritize clarity, completeness, and actionability. The goal is to give any coding agent enough context to understand and effectively contribute to the project without requiring additional human guidance. ...
Create high‑quality AGENTS.md file
You are a code agent. Your task is to create a complete, accurate AGENTS.md at the root of this repository that follows the public guidance at https://agents.md/.
AGENTS.md is an open format designed to provide coding agents with the context and instructions they need to work effectively on a project.
What is AGENTS.md?
...
Key Principles
... Agent-focused: Contains detailed technical instructions for automated tools
...
File Structure and Content Guidelines
...
Example Template
...
Working Example from agents.md
...
Implementation Steps
...
Best Practices
...
Monorepo Considerations
...