NAME
.junie/guidelines.md — instruction file for Junie
SYNOPSIS
.junie/guidelines.md
METADATA
DESCRIPTION
`.junie/guidelines.md` is the instruction file for Junie, JetBrains' autonomous AI coding agent. It provides project-specific guidelines that Junie reads at the start of each session to understand coding conventions, architecture, and quality standards.
Junie is separate from JetBrains' AI Assistant (which handles inline completions and chat). The guidelines file lives in the `.junie/` directory and uses plain Markdown — no frontmatter, no special directives, no multi-file rules.
The file is designed to be committed to version control and shared with the team. Unlike tools that support multiple rule files with glob-based activation, Junie uses a single guidelines file. Keep it focused and well-organized with clear headings.
STRUCTURE
ANNOTATED EXAMPLE
1# Project Guidelines
2
3## Overview
4Kotlin/JVM microservice using Spring Boot 3.2 and Gradle.
5PostgreSQL database with Flyway migrations. Deployed on Kubernetes.
6
7## Code Style
8- Kotlin coding conventions (ktlint enforced)
9- Use data classes for DTOs and value objects
10- Prefer extension functions over utility classes
11- Coroutines for async operations — no CompletableFuture
12
13## Architecture
14- Hexagonal architecture: domain, application, infrastructure layers
15- Domain layer has zero framework dependencies
16- Use cases are single-purpose application services
17- Repository interfaces in domain, implementations in infrastructure
18
19## Testing
20- JUnit 5 with Kotest assertions
21- Testcontainers for database integration tests
22- MockK for mocking — never Mockito
23- Minimum 80% line coverage for new code
24
25## API Conventions
26- REST endpoints follow OpenAPI spec in docs/api.yaml
27- Use problem+json (RFC 7807) for error responses
28- Pagination with cursor-based tokens, not offset
29- All endpoints require authentication except /health
COMMON MISTAKES
Junie specifically looks for guidelines in the `.junie/` directory. A guidelines.md at the project root will be ignored.
JetBrains has two AI products: AI Assistant (inline completions and chat) and Junie (autonomous coding agent). The `.junie/guidelines.md` file only affects Junie, not the AI Assistant.
Unlike tools that scan a directory for multiple rule files, Junie expects a single `guidelines.md` file. Use headings and sections within that file to organize different topics.