JetBrains .junie/guidelines.md vs AGENTS.md: A Comprehensive Comparison

An in-depth analysis of JetBrains Junie's .junie/guidelines.md and the universal AGENTS.md standard for AI coding agents.

Quick Comparison

What Are They?

AGENTS.md

Universal, ecosystem-agnostic format for documenting project-specific instructions for AI coding agents. Works with OpenAI Codex, GitHub Copilot, Cursor, Aider, Claude Code, and 20+ other tools.

.junie/guidelines.md

JetBrains-specific format designed for their Junie AI agent, deeply integrated into IntelliJ IDEA and other JetBrains IDEs.

Key Differences

1. Compatibility

• AGENTS.md: Cross-tool (Copilot, Cursor, Codex, etc.)
• .junie/guidelines.md: JetBrains only

2. Philosophy

• AGENTS.md: Command-centric ("Run these commands")
• .junie/guidelines.md: Example-driven ("Follow these patterns")

3. Ecosystem

• AGENTS.md: Community-driven, no official templates
• .junie/guidelines.md: Official catalog with curated guidelines

4. Location

• AGENTS.md: Visible in project root
• .junie/guidelines.md: Hidden in .junie/ directory

When to Use Each

Use AGENTS.md

• Multiple AI tools in team
• Open-source projects
• Cross-IDE compatibility needed
• Prefer visible documentation

Use .junie/guidelines.md

• All-in on JetBrains IDEs
• Want official tech stack templates
• Prefer example-driven docs
• Need AI-generated guidelines

Use Both

• Mixed tooling teams
• Best of both worlds
• Universal guidance + IDE-specific examples

Getting Started

AGENTS.md

touch AGENTS.md
# Add: tech stack, commands, conventions
git add AGENTS.md && git commit -m "docs: add AGENTS.md"

.junie/guidelines.md

# In JetBrains IDE: Click "Create project guidelines"
# Or manually:
mkdir .junie && touch .junie/guidelines.md
# Check: https://github.com/JetBrains/junie-guidelines

Resources

• AGENTS.md Specification
• Junie Documentation
• junie-guidelines Repository

Last updated: January 2025