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	14	0%
Commands	0	6	0%
Section tags	1	5	0%

What each file covers

Sections

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

− CLAUDE.md - Guidelines for Kotlin Development
− Project Guidelines
− Individual Preferences
+ Analysis API Guidelines
+ Architecture
+ Relationship with PSI
+ Key Conventions
+ Working with Test Data
+ `updateTestData` — the only recommended way to update test data
+ Update test data by directory (preferred for iteration)
+ Update test data by test class pattern
+ Run only golden tests (useful for quick baseline updates)
+ Incremental update — only re-run variant tests for changed paths
+ Limit to a subset of modules using task paths (Gradle task-name matching)
+ `checkTestData` — verification only
+ Key Components
+ Detailed Documentation

Commands

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

+ ./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/
+ ./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testClassPattern=.*ResolveTest.*
+ ./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.goldenOnly=true
+ ./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.incremental=true
+ ./gradlew :analysis:analysis-api-fir:updateTestData :analysis:stubs:updateTestData
+ ./gradlew checkTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/singleByPsi/

Section tags

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

− agent-behaviour
+ test
+ code-style
+ architecture
+ api
+ docs

Line diff

+112 added−12 removed7 unchanged5.9% 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 · analysis/AGENTS.md

@@ +1 @@

1# Analysis API Guidelines

3A library for analyzing Kotlin code at the semantic level, providing structured access to symbols, types, and semantic relationships.

5**Entry point:** Use [`analyze()`](analysis-api/src/org/jetbrains/kotlin/analysis/api/analyze.kt) to start an analysis session. See [Analysis API documentation](https://kotl.in/analysis-api) for a usage guide.

7## Architecture

9- **Platform** — Provides declarations, project structure, and modification events (IntelliJ, Standalone)

10- **Engine** — Performs code analysis using platform-provided information (K1, K2)

11- **User** — Code that calls `analyze()` to work with symbols and types

13→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md) for detailed architecture overview

15## Relationship with PSI

17Analysis API builds on top of Kotlin PSI (`compiler/psi/`):

18- **PSI** provides syntax (structure of code): `KtElement`, `KtExpression`, `KtDeclaration`

19- **Analysis API** provides semantics (meaning of code): `KaSymbol`, `KaType`

21```

22PSI (syntax) → Analysis API (semantics) → Symbols, Types, Resolution

23```

25**Both PSI and Analysis API follow shared development principles** documented in [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md).

27WHEN working with PSI elements:

28→ READ [`compiler/psi/AGENTS.md`](../compiler/psi/AGENTS.md) for PSI-specific rules and conventions

30## Key Conventions

32- `Ka` prefix for Analysis API types, `Kt` for PSI types

33- Prefer interfaces to classes for better binary compatibility

34- Properties for attributes, functions for actions with parameters

35- Return nullable types for operations that can fail (avoid exceptions for non-exceptional cases)

36- All implementations must validate lifetime ownership with `withValidityAssertion`

37- Mark experimental APIs with `@KaExperimentalApi`, implementation details with `@KaImplementationDetail`

39## Working with Test Data

41When modifying test data files or running generated tests (`*Generated`) that compare output against `.txt` files, use `updateTestData` (to rewrite files) or `checkTestData` (to verify only) instead of standard test commands. Both take their options as `-P` properties, so changing filters between runs stays fast.

43### `updateTestData` — the only recommended way to update test data

45```bash

46# Update test data by directory (preferred for iteration)

47./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/

49# Update test data by test class pattern

50./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testClassPattern=.*ResolveTest.*

52# Run only golden tests (useful for quick baseline updates)

53./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.goldenOnly=true

55# Incremental update — only re-run variant tests for changed paths

56./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.incremental=true

58# Limit to a subset of modules using task paths (Gradle task-name matching)

59./gradlew :analysis:analysis-api-fir:updateTestData :analysis:stubs:updateTestData

60```

62`updateTestData` is fixed to update mode. There is no `updateTestDataGlobally` — Gradle's task-name matching runs the task in every applicable subproject when invoked from the repo root.

64### `checkTestData` — verification only

66If you specifically need to verify that existing test data is consistent without modifying anything (e.g., sanity-checking generated files after an `updateTestData` run), use `checkTestData`. It is the exact `-P`-driven counterpart of `updateTestData` but fixed to check mode: it fails on any mismatch and writes nothing.

68```bash

69./gradlew checkTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/singleByPsi/

70```

72Use this only for verification. For any workflow that writes test data, use `updateTestData`.

74**Why use these tasks instead of plain `:test`?**

75- Run only relevant tests (filtered by path or class pattern)

76- Handle variant chains correctly (golden `.txt` files run before variant-specific `.js.txt`, `.wasm.txt`, etc.)

77- Automatically discover all modules that use managed test data

78- Detect and remove redundant variant files

80For full options, see [test-data-manager-convention](../repo/gradle-build-conventions/test-data-manager-convention/README.md).

82## Key Components

84- [`analysis-api/`](analysis-api) - User-facing API surface (`KaSession`, `KaSymbol`, `KaType`)

85- [`analysis-api-platform-interface/`](analysis-api-platform-interface) - Platform abstraction (declaration providers, project structure, lifetime)

86- [`analysis-api-standalone/`](analysis-api-standalone) - CLI-based implementation of the Analysis API

87- [`analysis-api-fir/`](analysis-api-fir) - K2 implementation based on FIR

88- [`analysis-api-impl-base/`](analysis-api-impl-base) - Shared implementation utilities

89- [`low-level-api-fir/`](low-level-api-fir) - K2-specific infrastructure for lazy/incremental analysis

90- [`symbol-light-classes/`](symbol-light-classes) - Java PSI view of Kotlin declarations for interop

91- [`decompiled/light-classes-for-decompiled`](decompiled/light-classes-for-decompiled) - Light classes for decompiled/library code

92- [`test-data-manager/`](test-data-manager) - Infrastructure for managing test data files with variant chains

94## Detailed Documentation

96WHEN adding or modifying API endpoints:

97→ READ [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md)

99WHEN deprecating API or understanding stability categories:

100→ READ [`docs/contribution-guide/api-evolution.md`](docs/contribution-guide/api-evolution.md)

101

102WHEN implementing platform components:

103→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md)

104

105WHEN working with light classes:

106→ READ [`symbol-light-classes/README.md`](symbol-light-classes/README.md)

107

108WHEN working with lazy resolution (LL API):

109→ READ [`low-level-api-fir/README.md`](low-level-api-fir/README.md)

110

111WHEN writing or managing test data files:

112→ READ [`test-data-manager/AGENTS.md`](test-data-manager/AGENTS.md)

113

114WHEN seeking historical context on design decisions:

115→ READ [`docs/design-documents/README.md`](docs/design-documents/README.md) (these are historical snapshots, not necessarily up to date)

116

117WHEN working with stubs:

118→ READ [`stubs/README.md`](stubs/README.md)

119

@@ −1 +1 @@

1−---

2−project: Kotlin

3−languages: [Kotlin, Java]

4−build-system: Gradle

5−repository: monorepo

6−---

1+# Analysis API Guidelines

8−# CLAUDE.md - Guidelines for Kotlin Development

3+A library for analyzing Kotlin code at the semantic level, providing structured access to symbols, types, and semantic relationships.

10−## Project Guidelines

5+**Entry point:** Use [`analyze()`](analysis-api/src/org/jetbrains/kotlin/analysis/api/analyze.kt) to start an analysis session. See [Analysis API documentation](https://kotl.in/analysis-api) for a usage guide.

116

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

7+## Architecture

138

14−## Individual Preferences

9+- **Platform** — Provides declarations, project structure, and modification events (IntelliJ, Standalone)

10+- **Engine** — Performs code analysis using platform-provided information (K1, K2)

11+- **User** — Code that calls `analyze()` to work with symbols and types

1512

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

13+→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md) for detailed architecture overview

1714

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

15+## Relationship with PSI

16+

17+Analysis API builds on top of Kotlin PSI (`compiler/psi/`):

18+- **PSI** provides syntax (structure of code): `KtElement`, `KtExpression`, `KtDeclaration`

19+- **Analysis API** provides semantics (meaning of code): `KaSymbol`, `KaType`

20+

21+```

22+PSI (syntax) → Analysis API (semantics) → Symbols, Types, Resolution

23+```

24+

25+**Both PSI and Analysis API follow shared development principles** documented in [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md).

26+

27+WHEN working with PSI elements:

28+→ READ [`compiler/psi/AGENTS.md`](../compiler/psi/AGENTS.md) for PSI-specific rules and conventions

29+

30+## Key Conventions

31+

32+- `Ka` prefix for Analysis API types, `Kt` for PSI types

33+- Prefer interfaces to classes for better binary compatibility

34+- Properties for attributes, functions for actions with parameters

35+- Return nullable types for operations that can fail (avoid exceptions for non-exceptional cases)

36+- All implementations must validate lifetime ownership with `withValidityAssertion`

37+- Mark experimental APIs with `@KaExperimentalApi`, implementation details with `@KaImplementationDetail`

38+

39+## Working with Test Data

40+

41+When modifying test data files or running generated tests (`*Generated`) that compare output against `.txt` files, use `updateTestData` (to rewrite files) or `checkTestData` (to verify only) instead of standard test commands. Both take their options as `-P` properties, so changing filters between runs stays fast.

42+

43+### `updateTestData` — the only recommended way to update test data

44+

45+```bash

46+# Update test data by directory (preferred for iteration)

47+./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/

48+

49+# Update test data by test class pattern

50+./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testClassPattern=.*ResolveTest.*

51+

52+# Run only golden tests (useful for quick baseline updates)

53+./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.goldenOnly=true

54+

55+# Incremental update — only re-run variant tests for changed paths

56+./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.incremental=true

57+

58+# Limit to a subset of modules using task paths (Gradle task-name matching)

59+./gradlew :analysis:analysis-api-fir:updateTestData :analysis:stubs:updateTestData

60+```

61+

62+`updateTestData` is fixed to update mode. There is no `updateTestDataGlobally` — Gradle's task-name matching runs the task in every applicable subproject when invoked from the repo root.

63+

64+### `checkTestData` — verification only

65+

66+If you specifically need to verify that existing test data is consistent without modifying anything (e.g., sanity-checking generated files after an `updateTestData` run), use `checkTestData`. It is the exact `-P`-driven counterpart of `updateTestData` but fixed to check mode: it fails on any mismatch and writes nothing.

67+

68+```bash

69+./gradlew checkTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/singleByPsi/

70+```

71+

72+Use this only for verification. For any workflow that writes test data, use `updateTestData`.

73+

74+**Why use these tasks instead of plain `:test`?**

75+- Run only relevant tests (filtered by path or class pattern)

76+- Handle variant chains correctly (golden `.txt` files run before variant-specific `.js.txt`, `.wasm.txt`, etc.)

77+- Automatically discover all modules that use managed test data

78+- Detect and remove redundant variant files

79+

80+For full options, see [test-data-manager-convention](../repo/gradle-build-conventions/test-data-manager-convention/README.md).

81+

82+## Key Components

83+

84+- [`analysis-api/`](analysis-api) - User-facing API surface (`KaSession`, `KaSymbol`, `KaType`)

85+- [`analysis-api-platform-interface/`](analysis-api-platform-interface) - Platform abstraction (declaration providers, project structure, lifetime)

86+- [`analysis-api-standalone/`](analysis-api-standalone) - CLI-based implementation of the Analysis API

87+- [`analysis-api-fir/`](analysis-api-fir) - K2 implementation based on FIR

88+- [`analysis-api-impl-base/`](analysis-api-impl-base) - Shared implementation utilities

89+- [`low-level-api-fir/`](low-level-api-fir) - K2-specific infrastructure for lazy/incremental analysis

90+- [`symbol-light-classes/`](symbol-light-classes) - Java PSI view of Kotlin declarations for interop

91+- [`decompiled/light-classes-for-decompiled`](decompiled/light-classes-for-decompiled) - Light classes for decompiled/library code

92+- [`test-data-manager/`](test-data-manager) - Infrastructure for managing test data files with variant chains

93+

94+## Detailed Documentation

95+

96+WHEN adding or modifying API endpoints:

97+→ READ [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md)

98+

99+WHEN deprecating API or understanding stability categories:

100+→ READ [`docs/contribution-guide/api-evolution.md`](docs/contribution-guide/api-evolution.md)

101+

102+WHEN implementing platform components:

103+→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md)

104+

105+WHEN working with light classes:

106+→ READ [`symbol-light-classes/README.md`](symbol-light-classes/README.md)

107+

108+WHEN working with lazy resolution (LL API):

109+→ READ [`low-level-api-fir/README.md`](low-level-api-fir/README.md)

110+

111+WHEN writing or managing test data files:

112+→ READ [`test-data-manager/AGENTS.md`](test-data-manager/AGENTS.md)

113+

114+WHEN seeking historical context on design decisions:

115+→ READ [`docs/design-documents/README.md`](docs/design-documents/README.md) (these are historical snapshots, not necessarily up to date)

116+

117+WHEN working with stubs:

118+→ READ [`stubs/README.md`](stubs/README.md)

19119