> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor AGENTS.md Best Practices

> This document outlines best practices for creating and maintaining AGENTS.md files for use with Cursor AI.

**Version:** 1.0.0\
**Last Updated:** 2026-01-16\
**Source:** Cursor Documentation + Research

This document outlines best practices for creating and maintaining `AGENTS.md` files for use with Cursor AI.

***

## What is AGENTS.md?

`AGENTS.md` is a markdown file used to provide global, repository-wide guidance to Cursor agents. It's a simpler alternative to structured `.cursor/rules` files, ideal for straightforward, readable instructions without metadata, scoping, or complexity.

***

## File Location Requirements

### Root AGENTS.md

* **Location:** Must be in project root (`AGENTS.md`)
* **Scope:** Applies globally across the entire project
* **No path or file-pattern scoping** - rules apply everywhere

### Nested AGENTS.md Files

* **Support:** Available in Cursor v1.6+ (planned for v1.6, check current version)
* **Location:** Can be placed in subdirectories (e.g., `src/platform/AGENTS.md`, `src/cores/hr/AGENTS.md`)
* **Behavior:** Instructions from nested files are automatically combined with parent directories
* **Precedence:** More specific instructions take precedence over parent instructions
* **Use Case:** Module-specific patterns, core-specific rules

**Reference:** [Cursor Rules Documentation](https://cursor.com/docs/context/rules#agentsmd)

***

## Size Recommendations

### General Guidelines

* **Target:** Keep files under \~500 lines
* **Rationale:** Large files become harder to maintain and may exceed context limits
* **If Exceeding:**
  * Consider splitting into `.cursor/rules` for complex, scoped rules
  * Move detailed patterns to separate documentation files
  * Link to external documentation instead of duplicating

### Size by File Type

* **Root AGENTS.md:** \<500 lines (platform-wide quick reference)
* **Platform AGENTS.md:** \<300 lines (PF-specific patterns)
* **Core AGENTS.md:** \<200 lines (module-specific patterns)
* **Shared AGENTS.md:** \<150 lines (UI component patterns)

***

## Structure Guidelines

### 1. Clear and Actionable Rules

**DO:**

* Write rules the way you'd explain internal documentation
* Prefer precise guidance (code style, naming conventions, workflows)
* Use examples when helpful
* Show "good" vs "bad" patterns
* Reference canonical files in your codebase

**DON'T:**

* Use vague suggestions
* Include rules that contradict each other
* Duplicate content that exists elsewhere (link instead)

### 2. Header Structure

```markdown theme={null}
# {Module/Project Name} - AI Agent Instructions

**Version:** X.X.X (for root only)
**Last Updated:** YYYY-MM-DD
**Status:** Active

> **See:** Root `AGENTS.md` (vX.X.X) for platform-wide instructions and version.
> See `AI_GUIDE.md` (vX.X.X) for detailed guidelines.
```

### 3. Section Organization

**Recommended Structure:**

1. **Quick Reference** (Start Here) - Most common patterns
2. **Module Overview** - Context and boundaries
3. **Architecture Rules** - Core principles
4. **Code Standards** - Import paths, naming, structure
5. **Patterns** - Common code patterns with examples
6. **What AI Must NEVER Do** - Prohibited patterns
7. **Pre-Flight Checklist** - Before writing code
8. **Key References** - Links to detailed docs

### 4. Use Examples

**Good Example:**

````markdown theme={null}
## Import Paths

```typescript
// ✅ CORRECT
import { Button } from '@/shared/ui/button';

// ❌ WRONG
import { Button } from '@/components/ui/button';
````

````

**Bad Example:**
```markdown
## Import Paths

Use the correct import paths.
````

***

## When to Use AGENTS.md vs .cursor/rules

### Use AGENTS.md When:

* ✅ You want one file of global guidelines
* ✅ Simple, readable instructions
* ✅ Smaller or simpler projects
* ✅ Module-specific patterns (nested files)
* ✅ Quick reference format

### Use .cursor/rules When:

* ✅ You need scoping (path or file-pattern based)
* ✅ Multiple rules with different metadata
* ✅ Precise control over when rules apply
* ✅ Conditionally applied rules
* ✅ Complex rule hierarchies
* ✅ Rich metadata requirements

**Reference:** [Cursor Rules Documentation](https://docs.cursor.com/context/rules)

***

## Version Control Best Practices

### 1. Track in Git

* ✅ Check AGENTS.md into git along with source files
* ✅ Ensures whole team sees it
* ✅ Changes are tracked and reviewable
* ✅ Version history available

### 2. Version Management

* **Root AGENTS.md:** Always has version (e.g., `v1.9.0`)
* **Nested AGENTS.md:** Reference root version, don't include own version
* **Update Version:** When making significant changes
* **Changelog:** Document major changes in header

### 3. Version Inheritance Pattern

```markdown theme={null}
# {Core} Module - AI Agent Instructions

> **See:** Root `AGENTS.md` for platform-wide instructions (current version: [docs/VERSIONS.md](../VERSIONS.md)).
```

***

## Update Frequency Guidelines

### When to Update

* **Immediately:** When core rules or patterns change
* **Immediately:** When architecture boundaries change
* **Within 24 hours:** When new patterns are established
* **Weekly:** Review during regular documentation review
* **Quarterly:** Comprehensive review and cleanup

### Update Triggers

* New patterns established
* Architecture changes
* Security requirements change
* Performance patterns updated
* Tool-specific optimizations needed

### Keep Current

* Agents follow whatever's in the file they can read
* Outdated instructions cause problems
* Update as project evolves
* Remove deprecated patterns

***

## Linking to External Documentation

### Best Practices

* ✅ Summarize critical parts in AGENTS.md
* ✅ Link to detailed documentation
* ✅ Don't duplicate huge documents fully
* ✅ Keep AGENTS.md as quick reference

### Link Format

```markdown theme={null}
**See:** `docs/development/UI_UX_STANDARDS.md` for complete UI/UX patterns.
**See:** `constitution.md` (current: see docs/VERSIONS.md) for engineering guardrails.
```

***

## Consistency Across Agents

### Purpose

AGENTS.md provides "always-on" context to:

* Cursor agents
* Inline Edits
* Chat sessions

### Consistency Requirements

* **Tone:** Consistent across all interactions
* **Structure:** Same output shape expected
* **Patterns:** Same patterns applied consistently
* **Rules:** No conflicting instructions

***

## Common Anti-Patterns

### ❌ Don't Do This

1. **Too Large:** File exceeds 500 lines without splitting
2. **Vague Rules:** "Write good code" instead of specific patterns
3. **Conflicting Rules:** Rules that contradict each other
4. **Outdated Content:** Patterns that no longer apply
5. **No Examples:** Rules without code examples
6. **Duplication:** Copying entire docs instead of linking
7. **No Version:** Missing version tracking
8. **Inconsistent Structure:** Different format across nested files

### ✅ Do This Instead

1. **Split Large Files:** Use `.cursor/rules` or separate docs
2. **Be Specific:** "Use `@/shared/ui/button` not `@/components/ui/button`"
3. **Resolve Conflicts:** One source of truth per rule
4. **Keep Current:** Regular reviews and updates
5. **Show Examples:** Good vs bad code patterns
6. **Link to Details:** Summarize and link to full docs
7. **Version Control:** Track versions in git
8. **Consistent Format:** Follow established structure

***

## Validation Checklist

Before committing AGENTS.md changes:

* [ ] File size appropriate (\<500 lines for root)
* [ ] Clear and actionable rules
* [ ] Examples provided (good vs bad)
* [ ] Version controlled (in git)
* [ ] Links to external docs where appropriate
* [ ] No conflicting rules
* [ ] Consistent structure
* [ ] Up-to-date content
* [ ] Nested files reference root version

***

## Related Documentation

* **Cursor Rules Documentation:** [https://cursor.com/docs/context/rules](https://cursor.com/docs/context/rules)
* **Cursor Agent Best Practices:** [https://cursor.com/blog/agent-best-practices](https://cursor.com/blog/agent-best-practices)
* **Project AGENTS.md:** `AGENTS.md` (current: [docs/VERSIONS.md](/VERSIONS))
* **AI Guide:** `AI_GUIDE.md` (current: see docs/VERSIONS.md)
* **Documentation Standards:** `docs/DOCUMENTATION_STANDARDS.md`

***

**Last Updated:** 2026-01-16\
**Next Review:** 2026-04-16 (Quarterly)