Two files, one repository
JetBrains/kotlin ships 2 formats across 7 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareCLAUDE.md ↔ AGENTS.md
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 19 | 3 | 0% |
| Commands | 0 | 10 | 0 | 0% |
| Section tags | 0 | 6 | 1 | 0% |
What each file covers
Sections
0 shared · 19 only in A · 3 only in B- − 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
- + CLAUDE.md - Guidelines for Kotlin Development
- + Project Guidelines
- + Individual Preferences
Commands
0 shared · 10 only in A · 0 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 · 6 only in A · 1 only in B- − build
- − test
- − code-style
- − architecture
- − api
- − deployment
- + agent-behaviour
Line diff
JetBrains/kotlin · compiler/build-tools/AGENTS.md
@@ −1 @@
1# Kotlin Build Tools API (BTA)
2
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.
6
7## Modules
8
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) |
21
22## Architecture: ClassLoader Isolation
23
24The impl JAR must be loaded in an isolated ClassLoader to prevent classpath conflicts with the consumer:
25
26```kotlin
27val 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
40All 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
51Do not edit generated files manually — regenerate them with the tasks below.
52
53Two 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```
68BTA 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
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
JetBrains/kotlin · CLAUDE.md
@@ +1 @@
1---
2project: Kotlin
3languages: [Kotlin, Java]
4build-system: Gradle
5repository: monorepo
6---
7
8# CLAUDE.md - Guidelines for Kotlin Development
9
10## Project Guidelines
11
12**CRITICAL: @./.ai/guidelines.md guidelines MUST be followed at all times.**
13
14## Individual Preferences
15
16**Local Preferences:** @./.claude/local.md
17
18When asked to update memory, you must update `./.claude/CLAUDE.md` if it is not specified that another file should be modified.
19
@@ −1 +1 @@
1−# Kotlin Build Tools API (BTA)
1+---
2+project: Kotlin
3+languages: [Kotlin, Java]
4+build-system: Gradle
5+repository: monorepo
6+---
27
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.
8+# CLAUDE.md - Guidelines for Kotlin Development
69
7−## Modules
10+## Project Guidelines
811
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) |
12+**CRITICAL: @./.ai/guidelines.md guidelines MUST be followed at all times.**
2113
22−## Architecture: ClassLoader Isolation
14+## Individual Preferences
2315
24−The impl JAR must be loaded in an isolated ClassLoader to prevent classpath conflicts with the consumer:
16+**Local Preferences:** @./.claude/local.md
2517
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`
18+When asked to update memory, you must update `./.claude/CLAUDE.md` if it is not specified that another file should be modified.
12019
