Junie's guidelines.md to AGENTS.md Migration: Why Your Rules Might Be Ignored (2026)

There’s a recurring report in JetBrains’ issue tracker with a title that undersells how confusing it is in practice: “Junie is not using guidelines.md anymore.” The file is still there. The content hasn’t changed. Junie just stopped reading it, or seems to — and the explanation is that JetBrains changed which file Junie looks for first, without most teams noticing.

Junie’s guideline system moved to AGENTS.md, the same open format used by Codex, Amp, and a growing list of other coding agents. .junie/guidelines.md still works, but it’s now second in line, not first. If your project has both files — or an AGENTS.md you added for a different tool, with content Junie was never meant to read — you can end up with Junie silently following the wrong instructions.

Here’s the actual discovery order, what changed, and how to migrate cleanly.

The discovery order (2026)

When Junie starts a task, it checks these locations in sequence and stops at the first one it finds:

1. AGENTS.md — project root
2. .junie/guidelines.md or .junie/guidelines/ folder — legacy format, still supported

That’s it. Two tiers, not a merge. If AGENTS.md exists in your project root, Junie reads that and does not also read .junie/guidelines.md — even if the legacy file has instructions you assumed were still active.

This is the part that catches teams out. A project that adopted AGENTS.md for Codex or Amp, without realizing Junie now honors the same file, will have Junie following instructions written for a different agent — while the .junie/guidelines.md file that used to configure Junie specifically sits there unread.

Global guidelines

Junie also supports an organization-wide file at ~/.junie/AGENTS.md. When both global and project-level guidelines exist, Junie surfaces both, marks which is which, and de-duplicates identical content rather than concatenating everything blindly. Project-level guidelines take precedence when the two conflict.

Custom paths

If neither default location fits your setup, Junie’s IDE settings (Settings → Tools → Junie → Project Settings) let you point to a custom guidelines path directly, bypassing the discovery order entirely.

Why the change happened

JetBrains didn’t invent a new format here — it adopted the one already spreading across the ecosystem. AGENTS.md started as OpenAI Codex’s convention and has since been picked up by Amp, Factory Droid, Google Antigravity, Goose, and others as a shared, tool-agnostic place to put agent instructions. A .junie/-namespaced file only ever configured Junie; a root-level AGENTS.md configures every agent a team happens to run, without three near-duplicate files drifting out of sync.

The tradeoff is exactly the confusion above: a format built to be shared by multiple tools means one tool’s unexpected read of a file another tool wrote is now the default behavior, not an edge case.

Migrating from .junie/guidelines.md

If you’re currently relying on .junie/guidelines.md and want to move to the current standard:

1. Check whether AGENTS.md already exists in your project root.

ls AGENTS.md .junie/guidelines.md 2>/dev/null

If both exist, Junie is already reading AGENTS.md only — your .junie/guidelines.md content is currently inactive for Junie, whether or not you intended that.

2. Decide: merge or keep separate.

• If AGENTS.md is Junie-only in this project, move the content over directly and delete .junie/guidelines.md (or leave it as a stale reference — Junie ignores it once AGENTS.md is present).
• If AGENTS.md already serves another agent (Codex, Amp, etc.), merge carefully. Junie-specific instructions (IDE-specific behaviors, JetBrains inspection preferences) can live in the same file — Junie doesn’t require exclusive ownership of AGENTS.md, it just reads whatever is there.

3. For org-wide defaults, use ~/.junie/AGENTS.md.

Team-wide conventions that shouldn’t be re-declared in every repo belong here rather than copy-pasted into each project’s AGENTS.md.

4. Verify with a throwaway instruction.

Add a single obviously-testable line — e.g. Always respond to comments in French — to whichever file you expect Junie to read, run one trivial task, and confirm the behavior shows up. Remove the test line once confirmed. This catches discovery-order mistakes faster than reading documentation does.

What Junie-specific content still needs .junie/

Not everything moved to AGENTS.md. Junie’s .junie/ directory still handles:

A common working pattern: shared, cross-tool instructions in root AGENTS.md, JetBrains/Junie-specific rules split into .junie/rules/, referenced from AGENTS.md if needed.

FAQ

Does Junie read both AGENTS.md and .junie/guidelines.md at once? No. It’s a discovery order, not a merge. AGENTS.md in the project root wins if present; .junie/guidelines.md only applies when no root AGENTS.md exists.

I have an AGENTS.md for Codex/Amp already — will Junie read it too? Yes, automatically, since Junie now follows the same open convention. This is usually what you want, but review the file for instructions that assume a different agent’s tool set.

Is .junie/guidelines.md deprecated? It’s legacy, not deprecated — JetBrains documentation states it remains supported. But it’s second-priority behind AGENTS.md, which is easy to miss if you migrated to AGENTS.md for a different tool without checking Junie’s docs.

What happens with conflicting global and project guidelines? Junie shows both, labeled by source, de-duplicates identical lines, and gives the project-level file precedence on conflicts.

Can I use a completely custom guidelines path? Yes, via Junie’s IDE settings (Settings → Tools → Junie → Project Settings), which overrides the default discovery order.

See how other AI coding agents handle AGENTS.md discovery — including Amp, Factory Droid CLI, and Goose — in our rules gallery, where we track the actual precedence behavior tool by tool rather than relying on documentation alone.