How to Create the Perfect AGENTS.md (incl. Template)

Maybe you know the feeling:

Your AI coding assistant just doesn't understand your project properly. You switch from Claude to Cursor, then to Continue.dev – and have to start from scratch with explanations each time.

Or even worse: You've written elaborate CLAUDE.md files, but they only work with Claude Code. With other tools, you're back to square one.

The solution? AGENTS.md – the new universal standard that over 20,000 open-source projects already use and that works with virtually all modern AI coding tools.

In this article, I'll show you how to create a perfect AGENTS.md that works with all tools – including a ready-to-use template and a complete tool compatibility matrix.

1. What Is an AGENTS.md File?

AGENTS.md is the new industry standard for AI coding instructions. Think of it like a README file, but for machines instead of humans.

The genius of it:

It's simple Markdown without special syntax or frontmatter. Any tool that can read Markdown also understands AGENTS.md.

After months of testing with various systems, I can say: AGENTS.md has emerged as the most practical approach. Major tech companies like OpenAI and Google actively support the standard.

The file works hierarchically – AI tools automatically read the nearest AGENTS.md in the directory tree. This makes it incredibly flexible for large projects with different areas.

2. AGENTS.md vs. CLAUDE.md vs. .claude/agents/

Let's clarify what's good for what:

The Three Systems Compared

The trick for maximum compatibility:

# Rename CLAUDE.md to AGENTS.md
mv CLAUDE.md AGENTS.md

# Symlink for Claude Code compatibility
ln -s AGENTS.md CLAUDE.md

# Now it works with all tools!

3. Structure and Layout of an AGENTS.md

AGENTS.md is deliberately kept simple. No YAML frontmatter, no special syntax – just clean Markdown.

After dozens of iterations, this structure has proven optimal:

# Project Name

Brief description of the project and its main goals.

## Development Environment
- Build commands and scripts
- Testing instructions
- Important dependencies

## Code Style Guidelines
- Formatting rules
- Naming conventions
- Architecture patterns

## Project Context
- Important files and their purpose
- Unusual patterns or gotchas
- Performance-critical areas

## Testing Instructions
- Test runner commands
- Coverage requirements
- CI/CD processes

What you should avoid:

• Too many details (> 500 lines are often ignored)
• Outdated information (nothing is worse than wrong instructions)
• Tool-specific syntax (stick to standard Markdown)
• Sensitive information (no secrets or credentials!)

4. Step by Step to the Perfect AGENTS.md

Now it gets practical. I'll show you how to create an AGENTS.md in just a few minutes:

4.1 Project Analysis: What Does the AI Need to Know?

Before you start, ask yourself these questions:

1. What are the most common tasks in your project?
2. What mistakes does the AI keep making?
3. What's unusual about your setup?
4. What standards are important to you?

The answers to these belong in your AGENTS.md.

4.2 The Universal Template

Here's my proven template that you can copy and customize directly:

# [Project Name]

[One-sentence description of what the project does]

## Development Setup

```bash
# Installation
npm install  # or yarn/pnpm

# Development
npm run dev

# Build
npm run build

# Tests
npm test
```

## Tech Stack

- **Framework**: [e.g., Next.js 15, React 18]
- **Language**: [e.g., TypeScript with strict mode]
- **Styling**: [e.g., Tailwind CSS v4]
- **Database**: [e.g., PostgreSQL with Prisma]
- **Testing**: [e.g., Jest + React Testing Library]

## Project Structure

```
src/
├── app/          # Next.js App Router
├── components/   # Reusable UI components
├── lib/          # Utilities and services
├── hooks/        # Custom React hooks
└── types/        # TypeScript type definitions
```

## Code Standards

### General Rules
- Prefer TypeScript over JavaScript
- Use functional components with hooks
- Follow ESLint configuration
- Write tests for new features

### Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Utilities: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE
- Types/Interfaces: PascalCase with suffix (UserType)

### File Organization
- Colocate tests with source files
- Group related components in folders
- Use index.ts for clean imports

## Important Patterns

### API Calls
Always use the API client from lib/api:
```typescript
import { apiClient } from '@/lib/api'
const data = await apiClient.get('/endpoint')
```

### State Management
- Use React Context for global state
- Prefer local state when possible
- Consider Zustand for complex state

## Testing Guidelines

- Write tests alongside implementation
- Focus on user behavior, not implementation
- Maintain > 80% coverage for critical paths
- Use data-testid for reliable selection

## Common Pitfalls to Avoid

- DON'T: Create new files unless necessary
- DON'T: Use console.log in production code
- DON'T: Ignore TypeScript errors
- DON'T: Skip tests for "simple" features
- DO: Check existing components before creating new ones
- DO: Follow established patterns in the codebase
- DO: Keep functions small and focused

## Performance Considerations

- Lazy load heavy components
- Use React.memo for expensive renders
- Optimize images with next/image
- Monitor bundle size

## Deployment

- Main branch deploys to production
- PR previews on Vercel
- Environment variables in .env.local
- Secrets managed via Vercel dashboard

## Additional Resources

- Architecture decisions: docs/architecture.md
- API documentation: docs/api.md
- Component library: Storybook at localhost:6006

4.3 Customization for Your Project

The template is just the start. Here's my proven process for customization:

1. Week 1: Use the basic template
2. Daily: Note when the AI does something wrong
3. Weekly: Update the AGENTS.md with the learnings
4. After 1 month: Major revision based on experience

An example from my practice: After 2 weeks, I had added 15 specific rules for my Next.js blog system. The AI error rate dropped by 70%.

5. Avoiding Common Beginner Mistakes

I see these mistakes over and over (and have made some of them myself):

1. Being too general: "Write good code" doesn't help. Be specific: "Use async/await instead of .then() chains"
2. Information overload: 1000+ lines? The AI ignores 90%. Keep it focused.
3. Forgetting to update: Your project evolves, but the AGENTS.md stays old = chaos
4. Tool-specific features: Use only standard Markdown for maximum compatibility
5. No examples: Show the AI how it's done right with code examples
6. Sensitive data: Never put API keys or passwords in AGENTS.md!

6. Tool Compatibility: What Works Where?

After extensive testing with all common tools, here's the definitive compatibility matrix:

Full Support (Native)

• ✅ Codex CLI (OpenAI) - Automatic detection
• ✅ Amp - Loads AGENTS.md at startup
• ✅ Roo Code - Hierarchical loading
• ✅ Factory - Full support since v2.0
• ✅ Jules (Google) - Beta, but works
• ✅ Continue.dev - Via plugin

Partial Support (Workarounds Needed)

• 🟡 Cursor - Use .cursorrules as symlink
• 🟡 Claude Code - Create symlink to CLAUDE.md
• 🟡 Cody - Define custom commands
• 🟡 Windsurf - Planned for Q2 2025

No Direct Support

• ❌ GitHub Copilot - Use comments in code
• ❌ Amazon CodeWhisperer - No configuration files
• ❌ Tabnine - Only inline comments

Workarounds for Non-Supported Tools

For tools without AGENTS.md support, I've developed these tricks:

#!/bin/bash
# setup-ai-tools.sh

# For Cursor
ln -sf AGENTS.md .cursorrules

# For Claude Code
ln -sf AGENTS.md CLAUDE.md

# For Cody (generate config)
echo "# Generated from AGENTS.md" > .cody/config.json
# ... conversion logic

echo "✅ AI tool configs synced with AGENTS.md"

7. Pro Tips for Advanced Usage

Time for the advanced tricks from my daily practice:

7.1 Hierarchical AGENTS.md for Large Projects

project/
├── AGENTS.md                 # Global project rules
├── frontend/
│   └── AGENTS.md            # Frontend-specific
├── backend/
│   └── AGENTS.md            # Backend-specific
└── tests/
    └── AGENTS.md            # Test-specific

AI tools automatically read the nearest file. This way you can define area-specific rules without overloading the main AGENTS.md.

7.2 Dynamic Sections for Different Modes

## Mode: Development
- Use verbose logging
- Include debug statements
- Skip optimization

## Mode: Production
- No console.log statements
- Optimize for performance
- Include error tracking

## Mode: Testing
- Mock external services
- Use test database
- Verbose test output

7.3 Team Synchronization with Git

AGENTS.md belongs in the repository! But with a system:

# Project Guidelines

[... Main content ...]

---
## Changelog
<!-- Document team updates -->
- 2025-09-26: Added TypeScript strict rules (FH)
- 2025-09-20: Updated test coverage requirements (TM)
- 2025-09-15: Initial version (FH)

## Personal Overrides
<!-- Don't commit this section -->
<!-- Move locally to AGENTS.personal.md -->

7.4 Performance Monitoring

Measure the impact of your AGENTS.md:

• Track AI error rate before/after updates
• Measure time to correct solution
• Document recurring problems

My metrics after 6 months of optimization: 70% fewer correction prompts needed, 3x faster task completion.

8. Migration from Existing Systems

You already have a CLAUDE.md or other config? Here's how to migrate painlessly:

From CLAUDE.md to AGENTS.md

#!/bin/bash
# migrate-to-agents.sh

# Create backup
cp CLAUDE.md CLAUDE.md.backup

# Copy content
cp CLAUDE.md AGENTS.md

# Remove tool-specific sections
sed -i '/Claude-specific/d' AGENTS.md

# Create symlinks
ln -sf AGENTS.md CLAUDE.md
ln -sf AGENTS.md .cursorrules

echo "✅ Migration complete!"

From Multiple Configs to One AGENTS.md

Many projects have .cursorrules, .claude/config, etc. Here's how to consolidate:

1. Collect all existing configs
2. Identify overlaps
3. Merge into AGENTS.md with clear structure
4. Create symlinks for backward compatibility
5. Test with all tools

9. Future-Proofing: What's Coming Next?

AGENTS.md is evolving rapidly. These are the trends I'm observing:

• Standardization: W3C-like spec in the works
• Tool convergence: More and more tools are adopting the standard
• Extended features: Conditionals and includes are planned
• IDE integration: Native VS Code support is coming

My advice: Switch to AGENTS.md now. The 30-minute investment pays off a hundredfold.

Conclusion: AGENTS.md Is the Future

After 8 months of intensive use, I can say: AGENTS.md has tripled my productivity with AI tools.

Universal compatibility means: configured once, usable everywhere. No more tool lock-ins, no redundant configs, no frustration when switching tools.

With the template from this article, you're ready to go in 10 minutes. The question is not if, but when you switch.