Comparison

A · CLAUDE.md · JetBrains/kotlin B · AGENTS.md · JetBrains/kotlin

What each file covers, counted
Dimension	Only in A	Only in B	Overlap
Sections	3	19	0%
Commands	0	10	0%
Section tags	1	6	0%

What each file covers

Sections

0 shared · 3 only in A · 19 only in B

− CLAUDE.md - Guidelines for Kotlin Development
− Project Guidelines
− Individual Preferences
+ Kotlin Build Tools API (BTA)
+ Modules
+ Architecture: ClassLoader Isolation
+ Key Abstractions
+ Generated Files
+ Regenerate generated sources (compiler argument classes and API version file; after changing compiler arguments in :compiler:arguments)
+ Regenerate API binary compatibility dump (after any public API change)
+ Compatibility Model
+ Running Tests
+ Run all tests (testExample is excluded from check — run it explicitly if needed)
+ Run against a specific BTA impl version (pattern: testCompatibility<version>)
+ Run against current snapshot impl
+ Classpath/module-path escaping edge cases
+ Verify restricted arguments are rejected correctly
+ Individual named test suites follow the pattern :test<SuiteName>
+ The full list is in `businessLogicTestSuits` in kotlin-build-tools-api-tests/build.gradle.kts
+ Forward compatibility tests
+ Writing Tests
+ Key Conventions and Pitfalls

Commands

0 shared · 0 only in A · 10 only in B

+ ./gradlew :compiler:build-tools:kotlin-build-tools-api:generateBtaSources
+ ./gradlew :compiler:build-tools:kotlin-build-tools-impl:generateBtaSources
+ ./gradlew :compiler:build-tools:kotlin-build-tools-compat:generateBtaSources
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api:apiDump
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:check
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibility2.3.20
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibilitySnapshot
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testEscapableCharacters
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testRestrictedArguments
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-forward-tests:check

Section tags

0 shared · 1 only in A · 6 only in B

− agent-behaviour
+ build
+ test
+ code-style
+ architecture
+ api
+ deployment

Line diff

+113 added−12 removed7 unchanged5.8% identical

JetBrains/kotlin · CLAUDE.md

@@ −1 @@

1---

2project: Kotlin

3languages: [Kotlin, Java]

4build-system: Gradle

5repository: monorepo

6---

8# CLAUDE.md - Guidelines for Kotlin Development

10## Project Guidelines

12**CRITICAL: @./.ai/guidelines.md guidelines MUST be followed at all times.**

14## Individual Preferences

16**Local Preferences:** @./.claude/local.md

18When asked to update memory, you must update `./.claude/CLAUDE.md` if it is not specified that another file should be modified.

JetBrains/kotlin · compiler/build-tools/AGENTS.md

@@ +1 @@

1# Kotlin Build Tools API (BTA)

3An experimental interface for build systems (Gradle plugin, Maven plugin, etc.) to invoke Kotlin compilation without a direct compiler

4dependency. Build systems should use the API from `kotlin-build-tools-api`, load the implementation in an isolated ClassLoader, and avoid

5accessing compiler internals directly.

7## Modules

9| Module | Purpose |

10|------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|

11| [`kotlin-build-tools-api`](kotlin-build-tools-api) | Public interfaces only; no implementation; `explicitApi()`; API dump checked in |

12| [`kotlin-build-tools-impl`](kotlin-build-tools-impl) | Default implementation; version-coupled to the compiler; must run in isolated ClassLoader |

13| [`kotlin-build-tools-compat`](kotlin-build-tools-compat) | Adapter for compilers < 2.3.0 (wraps deprecated `CompilationService`) |

14| [`kotlin-build-tools-cri-impl`](kotlin-build-tools-cri-impl) | Protobuf serialization for Compiler Reference Index; shipped as shadow JAR |

15| [`kotlin-build-tools-jdk-utils`](kotlin-build-tools-jdk-utils) | Internal utility for Java 9+ platform ClassLoader detection; do not use outside BTA modules |

16| [`kotlin-build-tools-generator`](kotlin-build-tools-generator) | KotlinPoet-based code generator producing compiler argument classes from `:compiler:arguments` and API version file |

17| [`kotlin-build-statistics`](kotlin-build-statistics) | Shared library for build metric collection (times, performance, GC, attributes); used by impl and KGP |

18| [`util-kotlinpoet`](util-kotlinpoet) | KotlinPoet utility helpers shared by code generators in the BTA area |

19| [`kotlin-build-tools-api-tests`](kotlin-build-tools-api-tests) | Main integration test suite (JUnit 5, multiple named test suites) |

20| [`kotlin-build-tools-api-forward-tests`](kotlin-build-tools-api-forward-tests) | Tests the forward compatibility guarantee (X+1) |

22## Architecture: ClassLoader Isolation

24The impl JAR must be loaded in an isolated ClassLoader to prevent classpath conflicts with the consumer:

26```kotlin

27val toolchains = KotlinToolchains.loadImplementation(implClasspath) // implClasspath: List<Path>

28```

30- `loadImplementation(List<Path>)` — preferred API; wraps the classpath in a `URLClassLoader` backed by `SharedApiClassesClassLoader`

31 automatically

32- `loadImplementation(ClassLoader)` — lower-level overload for custom ClassLoader setups; the ClassLoader's parent should be

33 `SharedApiClassesClassLoader`

34- The impl JAR version must match the compiler version (`kotlin-build-tools-impl` is version-coupled to the compiler)

35- For compilers < 2.3.0, include `kotlin-build-tools-compat` in the impl classpath → see [

36 `kotlin-build-tools-compat/README.md`](kotlin-build-tools-compat/README.md)

38## Key Abstractions

40All in `kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/`:

42- `KotlinToolchains` — factory entry point; creates `BuildSession` instances (`KotlinToolchains.kt`)

43- `BuildSession` (`AutoCloseable`) — manages caches, thread pools, and daemon connections

44- `Toolchain` (sealed interface) — `JvmPlatformToolchain`, `CriToolchain`, `AbiValidationToolchain`

45- `BuildOperation<R>` / `BuildOperation.Builder` — type-safe operation configuration (`BuildOperation.kt`)

46- `ExecutionPolicy` — `InProcess` vs `WithDaemon` (`ExecutionPolicy.kt`)

47- `KotlinLogger` — pluggable logging interface (`KotlinLogger.kt`)

49## Generated Files

51Do not edit generated files manually — regenerate them with the tasks below.

53Two kinds — both must be regenerated after relevant changes:

55```bash

56# Regenerate generated sources (compiler argument classes and API version file; after changing compiler arguments in :compiler:arguments)

57./gradlew :compiler:build-tools:kotlin-build-tools-api:generateBtaSources

58./gradlew :compiler:build-tools:kotlin-build-tools-impl:generateBtaSources

59./gradlew :compiler:build-tools:kotlin-build-tools-compat:generateBtaSources

61# Regenerate API binary compatibility dump (after any public API change)

62./gradlew :compiler:build-tools:kotlin-build-tools-api:apiDump

63```

65## Compatibility Model

67```

68BTA version X is guaranteed to work with implementation versions [X-3, X+1]

69```

71- **Backward compat (X-3):** tested in `kotlin-build-tools-api-tests` compatibility suites (one suite per listed version)

72- **Forward compat (X+1):** tested in `kotlin-build-tools-api-forward-tests`

73- When adding an API change that may break compatibility, add tests to both modules and run locally to verify

75## Running Tests

77```bash

78# Run all tests (testExample is excluded from check — run it explicitly if needed)

79./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:check

81# Run against a specific BTA impl version (pattern: testCompatibility<version>)

82./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibility2.3.20

84# Run against current snapshot impl

85./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibilitySnapshot

87# Classpath/module-path escaping edge cases

88./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testEscapableCharacters

90# Verify restricted arguments are rejected correctly

91./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testRestrictedArguments

93# Individual named test suites follow the pattern :test<SuiteName>

94# The full list is in `businessLogicTestSuits` in kotlin-build-tools-api-tests/build.gradle.kts

96# Forward compatibility tests

97./gradlew :compiler:build-tools:kotlin-build-tools-api-forward-tests:check

98```

100## Writing Tests

101

102See [`kotlin-build-tools-api-tests/README.md`](kotlin-build-tools-api-tests/README.md) for full conventions. Key rules:

103

104- All tests extend `BaseTest` (`src/main/kotlin/BaseTest.kt`)

105- All compilation tests extend `BaseCompilationTest` (`src/main/kotlin/compilation/BaseCompilationTest.kt`)

106- Add `@DisplayName` to both test class and methods

107- Add `@TestMetadata` pointing to the relevant test data directory for IDE navigation

108- Keep test classes small — tests run in parallel

109- Use the scenario DSL for incremental compilation tests; see `src/testExample/kotlin/ExampleIncrementalScenarioTest.kt`

110- Annotate strategy-agnostic tests with `@DefaultStrategyAgnosticCompilationTest`

111- Add a new test suite by appending its name to `businessLogicTestSuits` in `build.gradle.kts`

112- Compatibility suites (`testCompatibility*`): add tests sparingly — they run once per listed version

113

114## Key Conventions and Pitfalls

115

116- Every public API addition in `kotlin-build-tools-api` must include KDoc documentation

117- Do not add implementation dependencies to `kotlin-build-tools-api` — it must stay implementation-free

118- Do not use `kotlin-build-tools-jdk-utils` outside BTA modules (requires `@KotlinBuildToolsInternalJdkUtils` opt-in)

119- After changing compiler arguments, always regenerate both `generateBtaSources` and `apiDump`

120

@@ −1 +1 @@

1−---

2−project: Kotlin

3−languages: [Kotlin, Java]

4−build-system: Gradle

5−repository: monorepo

6−---

1+# Kotlin Build Tools API (BTA)

8−# CLAUDE.md - Guidelines for Kotlin Development

3+An experimental interface for build systems (Gradle plugin, Maven plugin, etc.) to invoke Kotlin compilation without a direct compiler

4+dependency. Build systems should use the API from `kotlin-build-tools-api`, load the implementation in an isolated ClassLoader, and avoid

5+accessing compiler internals directly.

10−## Project Guidelines

7+## Modules

118

12−**CRITICAL: @./.ai/guidelines.md guidelines MUST be followed at all times.**

9+| Module | Purpose |

10+|------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|

11+| [`kotlin-build-tools-api`](kotlin-build-tools-api) | Public interfaces only; no implementation; `explicitApi()`; API dump checked in |

12+| [`kotlin-build-tools-impl`](kotlin-build-tools-impl) | Default implementation; version-coupled to the compiler; must run in isolated ClassLoader |

13+| [`kotlin-build-tools-compat`](kotlin-build-tools-compat) | Adapter for compilers < 2.3.0 (wraps deprecated `CompilationService`) |

14+| [`kotlin-build-tools-cri-impl`](kotlin-build-tools-cri-impl) | Protobuf serialization for Compiler Reference Index; shipped as shadow JAR |

15+| [`kotlin-build-tools-jdk-utils`](kotlin-build-tools-jdk-utils) | Internal utility for Java 9+ platform ClassLoader detection; do not use outside BTA modules |

16+| [`kotlin-build-tools-generator`](kotlin-build-tools-generator) | KotlinPoet-based code generator producing compiler argument classes from `:compiler:arguments` and API version file |

17+| [`kotlin-build-statistics`](kotlin-build-statistics) | Shared library for build metric collection (times, performance, GC, attributes); used by impl and KGP |

18+| [`util-kotlinpoet`](util-kotlinpoet) | KotlinPoet utility helpers shared by code generators in the BTA area |

19+| [`kotlin-build-tools-api-tests`](kotlin-build-tools-api-tests) | Main integration test suite (JUnit 5, multiple named test suites) |

20+| [`kotlin-build-tools-api-forward-tests`](kotlin-build-tools-api-forward-tests) | Tests the forward compatibility guarantee (X+1) |

1321

14−## Individual Preferences

22+## Architecture: ClassLoader Isolation

1523

16−**Local Preferences:** @./.claude/local.md

24+The impl JAR must be loaded in an isolated ClassLoader to prevent classpath conflicts with the consumer:

1725

18−When asked to update memory, you must update `./.claude/CLAUDE.md` if it is not specified that another file should be modified.

26+```kotlin

27+val toolchains = KotlinToolchains.loadImplementation(implClasspath) // implClasspath: List<Path>

28+```

29+

30+- `loadImplementation(List<Path>)` — preferred API; wraps the classpath in a `URLClassLoader` backed by `SharedApiClassesClassLoader`

31+ automatically

32+- `loadImplementation(ClassLoader)` — lower-level overload for custom ClassLoader setups; the ClassLoader's parent should be

33+ `SharedApiClassesClassLoader`

34+- The impl JAR version must match the compiler version (`kotlin-build-tools-impl` is version-coupled to the compiler)

35+- For compilers < 2.3.0, include `kotlin-build-tools-compat` in the impl classpath → see [

36+ `kotlin-build-tools-compat/README.md`](kotlin-build-tools-compat/README.md)

37+

38+## Key Abstractions

39+

40+All in `kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/`:

41+

42+- `KotlinToolchains` — factory entry point; creates `BuildSession` instances (`KotlinToolchains.kt`)

43+- `BuildSession` (`AutoCloseable`) — manages caches, thread pools, and daemon connections

44+- `Toolchain` (sealed interface) — `JvmPlatformToolchain`, `CriToolchain`, `AbiValidationToolchain`

45+- `BuildOperation<R>` / `BuildOperation.Builder` — type-safe operation configuration (`BuildOperation.kt`)

46+- `ExecutionPolicy` — `InProcess` vs `WithDaemon` (`ExecutionPolicy.kt`)

47+- `KotlinLogger` — pluggable logging interface (`KotlinLogger.kt`)

48+

49+## Generated Files

50+

51+Do not edit generated files manually — regenerate them with the tasks below.

52+

53+Two kinds — both must be regenerated after relevant changes:

54+

55+```bash

56+# Regenerate generated sources (compiler argument classes and API version file; after changing compiler arguments in :compiler:arguments)

57+./gradlew :compiler:build-tools:kotlin-build-tools-api:generateBtaSources

58+./gradlew :compiler:build-tools:kotlin-build-tools-impl:generateBtaSources

59+./gradlew :compiler:build-tools:kotlin-build-tools-compat:generateBtaSources

60+

61+# Regenerate API binary compatibility dump (after any public API change)

62+./gradlew :compiler:build-tools:kotlin-build-tools-api:apiDump

63+```

64+

65+## Compatibility Model

66+

67+```

68+BTA version X is guaranteed to work with implementation versions [X-3, X+1]

69+```

70+

71+- **Backward compat (X-3):** tested in `kotlin-build-tools-api-tests` compatibility suites (one suite per listed version)

72+- **Forward compat (X+1):** tested in `kotlin-build-tools-api-forward-tests`

73+- When adding an API change that may break compatibility, add tests to both modules and run locally to verify

74+

75+## Running Tests

76+

77+```bash

78+# Run all tests (testExample is excluded from check — run it explicitly if needed)

79+./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:check

80+

81+# Run against a specific BTA impl version (pattern: testCompatibility<version>)

82+./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibility2.3.20

83+

84+# Run against current snapshot impl

85+./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibilitySnapshot

86+

87+# Classpath/module-path escaping edge cases

88+./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testEscapableCharacters

89+

90+# Verify restricted arguments are rejected correctly

91+./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testRestrictedArguments

92+

93+# Individual named test suites follow the pattern :test<SuiteName>

94+# The full list is in `businessLogicTestSuits` in kotlin-build-tools-api-tests/build.gradle.kts

95+

96+# Forward compatibility tests

97+./gradlew :compiler:build-tools:kotlin-build-tools-api-forward-tests:check

98+```

99+

100+## Writing Tests

101+

102+See [`kotlin-build-tools-api-tests/README.md`](kotlin-build-tools-api-tests/README.md) for full conventions. Key rules:

103+

104+- All tests extend `BaseTest` (`src/main/kotlin/BaseTest.kt`)

105+- All compilation tests extend `BaseCompilationTest` (`src/main/kotlin/compilation/BaseCompilationTest.kt`)

106+- Add `@DisplayName` to both test class and methods

107+- Add `@TestMetadata` pointing to the relevant test data directory for IDE navigation

108+- Keep test classes small — tests run in parallel

109+- Use the scenario DSL for incremental compilation tests; see `src/testExample/kotlin/ExampleIncrementalScenarioTest.kt`

110+- Annotate strategy-agnostic tests with `@DefaultStrategyAgnosticCompilationTest`

111+- Add a new test suite by appending its name to `businessLogicTestSuits` in `build.gradle.kts`

112+- Compatibility suites (`testCompatibility*`): add tests sparingly — they run once per listed version

113+

114+## Key Conventions and Pitfalls

115+

116+- Every public API addition in `kotlin-build-tools-api` must include KDoc documentation

117+- Do not add implementation dependencies to `kotlin-build-tools-api` — it must stay implementation-free

118+- Do not use `kotlin-build-tools-jdk-utils` outside BTA modules (requires `@KotlinBuildToolsInternalJdkUtils` opt-in)

119+- After changing compiler arguments, always regenerate both `generateBtaSources` and `apiDump`

19120