What is OpenCode CLI AGENTS.md and How to Write It?

Mar 30, 2026

What is AGENTS.md?

AGENTS.md is a repository-specific instruction file that tells AI coding assistants how to work with your project. It acts as an FAQ for the AI agent, loaded automatically when working in that repository.

When I started using OpenCode CLI, I noticed my AI agent would make assumptions about my project that weren’t always correct. It would use wrong frameworks, ignore my coding standards, or suggest patterns I didn’t want.

Then I discovered AGENTS.md. I created one file, placed it in my repository root, and suddenly my AI assistant understood my project conventions.

Here’s what it looks like:

# Project Instructions

## Tech Stack
- Frontend: React with TypeScript
- Backend: Node.js with Express
- Database: PostgreSQL
- Testing: Jest

## Code Style
- Use functional components with hooks
- Prefer composition over inheritance
- All API responses follow the format: { success, data, error }

This simple file changed how the AI interacted with my codebase. It stopped suggesting class components. It started using Jest for tests without me asking.

Why AGENTS.md Matters

AGENTS.md solves four key problems:

Automatic loading. When I open a repository in OpenCode CLI, the AI reads AGENTS.md automatically. I don’t need to remind it about my project conventions every session.

Consistent behavior. Every time I work in that repository, the AI follows the same rules. It doesn’t forget or make inconsistent choices.

Reduced hallucination. By specifying the tech stack explicitly, the AI stops guessing. It knows I use PostgreSQL, not MongoDB. It knows I use TypeScript, not JavaScript.

Team alignment. When multiple developers work with AI assistants on the same codebase, AGENTS.md ensures everyone gets consistent suggestions. My teammate and I get the same code style recommendations.

AGENTS.md vs Other Configuration Files

At first, I was confused about how AGENTS.md differs from other configuration files. Here’s what I learned:

File	Purpose	Loaded When	Scope
AGENTS.md	Repository-specific AI instructions	Working in that repository	Single repository
CLAUDE.md	Global AI instructions	Every session	All projects
GEMINI.md	Google Gemini instructions	Gemini-based agents	All projects
.cursorrules	Cursor IDE rules	Cursor IDE sessions	Single repository

The key difference is scope. AGENTS.md applies to one repository. CLAUDE.md applies everywhere. If I have a global CLAUDE.md and a local AGENTS.md, both get loaded—but repository-specific rules override global ones.

I use AGENTS.md for things unique to each project: tech stack, naming conventions, architectural decisions. I use CLAUDE.md for things consistent across all my work: coding style preferences, Git conventions, testing practices.

What to Include in AGENTS.md

After using AGENTS.md in multiple projects, I’ve found these sections essential:

Tech Stack. List the frameworks, languages, and tools. This prevents the AI from suggesting wrong technologies.

Code Style. Define naming conventions, component patterns, and file organization.

Architecture. Explain the project structure and key design decisions.

Testing. Specify the testing framework and coverage requirements.

Common Patterns. Show examples of how to write code in this project.

Gotchas. Document things that might confuse the AI or that need special handling.

Commands. List common development commands (build, test, deploy).

Path-Specific Instructions

OpenCode CLI also supports path-specific instructions through the opencode-path-instructions plugin. This lets you define rules that only apply when working with specific files or directories.

One developer mentioned: “In addition to skills, I use instructions for specific paths or project files. This ensures that they are loaded only when the agent is working with them.”

This is useful for:

Database migration files that need special patterns
API route files with specific middleware requirements
Test files with unique conventions
Configuration files with security considerations

Basic AGENTS.md Template

Here’s the template I start with for new projects:

# Project Instructions

## Tech Stack
- Language: [e.g., TypeScript]
- Framework: [e.g., React, Express]
- Database: [e.g., PostgreSQL, MongoDB]
- Testing: [e.g., Jest, Vitest]

## Project Structure
- /src - Source code
- /tests - Test files
- /docs - Documentation

## Code Style
- Naming: [e.g., camelCase for variables, PascalCase for components]
- Formatting: [e.g., Prettier with 2-space indentation]
- Linting: [e.g., ESLint with recommended rules]

## Architecture
- Pattern: [e.g., MVC, microservices, monolith]
- Key decisions: [e.g., why we chose this database]

## Testing
- Framework: [e.g., Jest]
- Coverage requirement: [e.g., 80%]
- Test location: [e.g., same directory with .test.ts suffix]

## Common Commands
- Install: `npm install`
- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Gotchas
- [Add project-specific warnings here]

I copy this template and fill in the brackets. Most projects need 30-50 lines to capture the essential context.

Production Example: WorldMonitor

Here’s an AGENTS.md I use in a real project called WorldMonitor:

# WorldMonitor Project Instructions

## Tech Stack
- Frontend: React 18 with TypeScript
- State: Zustand for state management
- Backend: Node.js 20 with Express
- Database: PostgreSQL 15 with Prisma ORM
- Cache: Redis for session and rate limiting
- Testing: Vitest with Testing Library
- Deployment: Docker containers on Kubernetes

## Project Structure

/src /components - React components /hooks - Custom React hooks /services - API service layer /stores - Zustand stores /utils - Shared utilities /prisma - Database schema and migrations /tests - Test files

## Code Style
- Use functional components with hooks only
- Prefer named exports for components
- Use TypeScript strict mode
- API responses: { success: boolean, data?: T, error?: string }
- Error handling: Use Result pattern, never throw in services

## Architecture
- Monolithic backend with clear service boundaries
- React Query for server state
- Zustand for client state
- Prisma for all database access
- Redis for rate limiting and caching

## Testing
- Unit tests for utilities and hooks
- Integration tests for API endpoints
- E2E tests for critical user flows
- Minimum 80% coverage on services
- Run tests with: `npm test`

## Common Commands
- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- DB Reset: `npx prisma migrate reset`
- Generate Types: `npx prisma generate`

## Gotchas
- Always use Prisma transactions for multi-table operations
- Redis keys follow pattern: `wm:{resource}:{id}`
- API routes require authentication middleware
- Never commit .env files

This file took me 15 minutes to write. It saves me from explaining the same things over and over.

Path-Specific Instructions Example

For path-specific rules, I create separate instruction files:

# API Route Instructions

These rules apply when editing files in /src/routes/

## Middleware
- All routes must use authMiddleware
- Apply rateLimiter to public endpoints
- Use requestValidator for input validation

## Response Format
```typescript
// Success
res.json({ success: true, data: result })

// Error
res.status(400).json({ success: false, error: 'Message' })

Error Handling

Use try/catch in all route handlers
Log errors with winston before responding
Never expose internal error details to clients

This file only loads when I'm working on API routes. It doesn't clutter the context when I'm editing frontend components.

## How AGENTS.md Gets Loaded

When I start OpenCode CLI in a repository, here's what happens:

1. OpenCode looks for AGENTS.md in the repository root
2. If found, it reads the contents
3. The instructions are added to the context
4. The AI follows these instructions for all operations in that repository

If AGENTS.md doesn't exist, OpenCode falls back to global CLAUDE.md instructions. But I recommend creating AGENTS.md for every project, even a minimal one.

## Common Mistakes to Avoid

When I first started using AGENTS.md, I made these mistakes:

**Mistake 1: Writing too much.**

I wrote a 500-line AGENTS.md with every detail about the project. The AI ignored half of it because the context was too long.

Now I keep it under 100 lines and focus on the most important conventions.

**Mistake 2: Being too vague.**

```text title="AGENTS.md (BAD)"
# Project Instructions

Write clean code and follow best practices.

This tells the AI nothing useful. I replaced it with specific rules:

# Project Instructions

## Code Style
- Use functional components with hooks
- All functions must have explicit return types
- Prefer composition over inheritance

Mistake 3: Forgetting to update it.

I added a new testing framework but forgot to update AGENTS.md. The AI kept suggesting the old framework.

Now I update AGENTS.md whenever I change project conventions.

Summary

In this post, I explained what AGENTS.md is and how to write effective repository-specific instructions for OpenCode CLI.

The key points are:

AGENTS.md is a per-repository instruction file that loads automatically
It solves the problem of AI making wrong assumptions about your project
Keep it under 100 lines with specific, actionable instructions
Include tech stack, code style, architecture, testing, and common commands
Use path-specific instructions for rules that only apply to certain files

When I started using AGENTS.md, my AI assistant stopped suggesting wrong frameworks and started following my project conventions. It took 15 minutes to write but saved hours of corrections.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion Source

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!