OpenCode: OpenCode AGENTS.md Configuration
Last updated: 2026-08-31
--- title: OpenCode Rules (AGENTS.md) description: Learn to write AGENTS.md rule files defining AI behavior constraints in your project order: 12 lang: en
AGENTS.md is OpenCode's project-level rules file that defines AI behavior constraints for the current project.
1. What You Will Learn
- AGENTS.md purpose and positioning
- File creation methods
- Rule writing techniques
- Best practices
2. What is AGENTS.md
AGENTS.md is a Markdown file in the project root directory. AI automatically reads and follows its rules when working.
| Aspect | Details |
|---|---|
| Location | Project root directory |
| Format | Markdown |
| Scope | Current project only |
| Auto-load | AI reads automatically when starting |
3. Creating AGENTS.md
TUI command: /init (auto-generates based on project structure)
Or manually create an AGENTS.md file in the project root.
4. Rule Writing
Basic Structure
MARKDOWN
# Project Rules
## Coding Standards
- Use TypeScript strict mode
- Follow ESLint configuration
- Maximum function length: 50 lines
## Testing Requirements
- All new functions must have unit tests
- Test coverage no less than 80%
## Commit Standards
- Use Conventional Commits format
- Each commit does one thing only
Rule Categories
| Category | Examples |
|---|---|
| Coding standards | Code style, naming rules, type requirements |
| Architecture constraints | Directory structure, module boundaries |
| Testing requirements | Coverage, test types, test naming |
| Commit standards | Commit format, branch naming, PR rules |
| Security rules | No hardcoded keys, input validation |
| Business logic | Domain rules, data processing |
5. Best Practices
- Rules should be specific: "Max 50 lines per function" not "write good code"
- Rules should be executable: "No hardcoded API keys" not "be careful with security"
- Prioritize rules: Distinguish must-follow from recommended from optional
- Share with team: Commit AGENTS.md to Git, maintain collectively
6. AGENTS.md vs opencode.json
| Aspect | AGENTS.md | opencode.json |
|---|---|---|
| Format | Markdown | JSON |
| Audience | AI + humans | OpenCode program |
| Content | Behavior rules, coding standards | Config parameters, tool permissions |
| Effect | Advisory | Mandatory |
They complement each other: AGENTS.md tells AI "what to do," opencode.json controls "what it can do."
❓ FAQ
Q Will AI always follow AGENTS.md rules?
A Not guaranteed. AGENTS.md is advisory—AI tries to follow but it's not enforced. For mandatory rules, use opencode.json permission config.
Q Does AGENTS.md in subdirectories work?
A No. Only the root directory AGENTS.md is read by AI.
Q Alice has 100-line AGENTS.md, Bob has 5 lines—who gets better results?
A Not necessarily more is better. 5 precise rules may be more effective than 100 vague ones. Quality over quantity.
📖 Summary
- AGENTS.md is the project rules file for AI
- Create with
/initor manually - Rules should be specific, executable, prioritized
- Complements opencode.json: rules + permissions
- Commit to Git for team collaboration
📝 Exercises
-
Basic: Create an AGENTS.md with at least 5 coding standards.
-
Intermediate: Define complete development flow rules (code→test→commit) and have OpenCode follow them.
-
Advanced: Compare OpenCode output with and without AGENTS.md, quantifying rule impact on AI behavior.
