Kotlin Project Guide

This file provides guidance for AI agents working with code in this repository.

Repository Overview

This is the Kotlin programming language repository containing:

Kotlin compiler (frontend and JVM, JS, WASM, Native backends)
Compiler plugins (compose, serialization, allopen, noarg, etc.)
Standard library, kotlin-reflect, kotlin-test
Build system support (Gradle, Maven, JPS)
Kotlin scripting support
Analysis API

Note: The IntelliJ Kotlin plugin is in a separate repository (JetBrains/intellij-community).

Build Commands

# Generate test sources (run after adding new test data files)
./gradlew generateTests

Common Pitfalls

Don't modify *Generated.java test files directly - regenerate them with generateTests Gradle task

Areas

BEFORE running tests, modifying, or investigating code — identify the area and READ its docs.

Area	Prefixes	Location	Docs
Analysis API	`Ka`, `KaFir`, `LL*`	analysis/	AGENTS.md
Backend: JVM		compiler/ir/backend.jvm/	AGENTS.md
Backend: JS		compiler/ir/backend.js/	AGENTS.md
Backend: Native		kotlin-native/, native/	AGENTS.md
Backend: WASM		compiler/ir/backend.wasm/	AGENTS.md
Build Tools API		compiler/build-tools/	AGENTS.md
Compiler plugins		plugins/	—
FIR (K2 frontend)	`Fir*`	compiler/fir/	AGENTS.md
FIR Analysis Tests		compiler/fir/analysis-tests/	AGENTS.md
IR	`Ir*`	compiler/ir/	AGENTS.md
K1 (legacy frontend)		compiler/frontend/	—
Kotlin Gradle Plugin		libraries/tools/kotlin-gradle-plugin/	AGENTS.md
Kotlin Gradle Plugin API		libraries/tools/kotlin-gradle-plugin-api/	AGENTS.md
KGP Integration Tests		libraries/tools/kotlin-gradle-plugin-integration-tests/	AGENTS.md
PSI	`Kt*`	compiler/psi/	AGENTS.md
Standard library		libraries/stdlib/	—
Test infrastructure		compiler/test-infrastructure/, compiler/tests-common-new/	testing.md

Adding new area docs: Create AGENTS.md with content and CLAUDE.md containing only @AGENTS.md

Running Individual Tests

MANDATORY: First check the Areas table above — some areas have specialized test tooling.

Use -q (quiet) flag to reduce output noise. Example of commands for areas WITHOUT specialized tooling:

# Run a specific test class
./gradlew :compiler:test --tests "org.jetbrains.kotlin.codegen.BlackBoxCodegenTestGenerated" -q

# Run a specific test method
./gradlew :compiler:test --tests "org.jetbrains.kotlin.codegen.BlackBoxCodegenTestGenerated.testSomeTest"

# Run FIR compiler tests
./gradlew :compiler:fir:fir2ir:test --tests "org.jetbrains.kotlin.test.runners.ir.FirLightTreeJvmIrTextTestGenerated"

# Update test data files (when format changes)
./gradlew :compiler:test --tests "TestClassName" -Pkotlin.test.update.test.data=true --continue

Commit Guidelines

When creating a commit, you MUST read commit-guidelines.md first — do not author or amend a commit without following it. It holds the mandatory rules for commit messages, formatting, subsystem tag prefixes, and MR structure.

JetBrains IDE MCP - MANDATORY for the project files and operations

NEVER use these tools: Grep, Glob, Read, Edit, Write, Task(Explore). ALWAYS use JetBrains MCP equivalents instead.

Exception: for paths outside the project (e.g., ~/.claude/), use standard tools — MCP only works with project-relative paths.

NEVER use execute_terminal_command tool. ALWAYS use default Bash instead.

Use other similar tools only if it is not possible to use the JetBrains IDE MCP, and you together with the user can't manage to make it work.

Why MCP over standard tools?

Synchronization with IDE:

Standard tools work with the filesystem directly, MCP works with IDE's view of files
If a file is open in IDE with unsaved changes, standard Read sees the old disk version, while MCP sees current IDE buffer
Standard Write/Edit may conflict with IDE's buffer or not be picked up immediately
MCP changes integrate with IDE's undo history

IDE capabilities:

search_in_files_by_text uses IntelliJ indexes — faster than grep on large codebases
rename_refactoring understands code structure and updates all references correctly
get_symbol_info provides type info, documentation, and declarations
get_file_problems runs IntelliJ inspections beyond syntax checking

MCP server configuration

The JetBrains IDE MCP server can be called as jetbrains, idea, my-idea, my-idea-dev, etc. If there are many options for the JetBrains IDE MCP server, ask the user what MCP server to use.

Tool mapping

Instead of	Use JetBrains MCP
`Read`	`get_file_text_by_path`
`Edit`, `Write`	`replace_text_in_file`, `create_new_file`
`Grep`	`search_in_files_by_text`, `search_in_files_by_regex`
`Glob`	`find_files_by_name_keyword`, `find_files_by_glob`
`Task(Explore)`	`list_directory_tree`, `search_in_files_by_text`

Additional MCP tools

Code analysis: get_symbol_info, get_file_problems for understanding code
Refactoring: rename_refactoring for symbol renaming (safer than text replacement)
Run configurations: get_run_configurations() to discover, or execute_run_configuration(name="...") if name is known

MANDATORY - Verify After Writing Code

Use JetBrains MCP get_file_problems with errorsOnly=false to check files for warnings. FIX any warnings related to the code changes made. You may ignore unrelated warnings.

Run the relevant tests after making changes. Slowness is never a reason to skip. Fix failures before declaring done.

Working with YouTrack

“KT-XXXXX”, where XXXXX is the issue number, is an issue in https://youtrack.jetbrains.com/. The direct URL for an issue is https://youtrack.jetbrains.com/issue/KT-XXXXX. When accessing youtrack.jetbrains.com, never fetch web pages from such URLs directly. Use YouTrack MCP if configured. Otherwise, use YouTrack REST API, e.g. with a GET request to

https://youtrack.jetbrains.com/api/issues/KT-XXXXX?fields=fields=summary,description,customFields(name,value(name,login,text))