Cursor AGENTS.md Best Practices

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.

​

What is AGENTS.md?

​

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

​

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

• 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

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

​

2. Header Structure

# {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

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

## 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

​

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

# {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

**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

• 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

• 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
• Cursor Agent Best Practices: https://cursor.com/blog/agent-best-practices
• Project AGENTS.md: AGENTS.md (current: docs/VERSIONS.md)
• AI Guide: AI_GUIDE.md (current: see docs/VERSIONS.md)
• Documentation Standards: docs/DOCUMENTATION_STANDARDS.md