|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Build Commands |
| 6 | +- Build: `./gradlew assemble` |
| 7 | +- Run all JVM tests: `./gradlew jvmTest` |
| 8 | +- Run specific test: `./gradlew :module-name:jvmTest --tests "fully.qualified.TestClassName"` |
| 9 | +- Run all tests: `./gradlew allTests` |
| 10 | +- Code coverage: `./gradlew koverHtmlReport` |
| 11 | +- Linting: `./gradlew lintKotlin` |
| 12 | +- Format code: `./gradlew formatKotlin` |
| 13 | + |
| 14 | +## Code Style Guidelines |
| 15 | +- Follow Kotlin [official style guide](https://kotlinlang.org/docs/coding-conventions.html) |
| 16 | +- Use star imports for `io.ktor.*` packages (configured in .editorconfig) |
| 17 | +- Max line length: 120 characters |
| 18 | +- Indent: 4 spaces (2 for JSON, YAML) |
| 19 | +- Include copyright header in new files |
| 20 | +- Document all public APIs including parameters, return types, and exceptions |
| 21 | +- Mark internal APIs with `@InternalAPI` annotation |
| 22 | +- Prefix commit messages with KTOR-{NUM} (YouTrack issue) |
| 23 | +- Write commit messages in present tense, imperative mood |
| 24 | + |
| 25 | +## Development Practices |
| 26 | +- Always use Test-Driven Development (TDD) approach |
| 27 | +- Write tests before implementing new features or fixing issues |
| 28 | +- Ensure all code is covered by appropriate tests |
| 29 | +- Follow test naming pattern: `DescribeWhatIsBeingTested` |
| 30 | +- Always verify compilation with `./gradlew assemble` before submitting changes |
| 31 | +- Run relevant tests with `./gradlew jvmTest` to verify functionality |
| 32 | +- Run `./gradlew lintKotlin` and fix all linting issues before giving control back to the user |
| 33 | +- Use `./gradlew formatKotlin` to automatically fix formatting issues |
| 34 | +- Run `./gradlew apiDump` after making API changes to update API signature files |
| 35 | +- CRITICAL: Never return control to the user without ensuring code compiles, tests pass, and ALL linting issues are fixed |
| 36 | +- Start with JVM-only implementation and tests unless the user specifically requests otherwise |
| 37 | +- Focus on core functionality first before expanding to other platforms (JS, Native) |
| 38 | + |
| 39 | +## Project Requirements |
| 40 | +- JDK 21 required for building |
| 41 | +- Multiplatform project (JVM, JS, Native) |
| 42 | +- Tests organized by platform in module's test directories |
| 43 | +- Error handling follows Kotlin conventions with specific Ktor exceptions |
| 44 | + |
| 45 | +## API Compatibility |
| 46 | +- Binary compatibility is enforced using the binary-compatibility-validator plugin |
| 47 | +- All public API changes must be tracked in the `/api/` directories |
| 48 | +- Run `./gradlew apiDump` to update all API signature files after making API changes |
| 49 | +- Module-specific API dumps: `./gradlew :module-name:apiDump` |
| 50 | +- Platform-specific dumps: `./gradlew jvmApiDump` or `./gradlew klibApiDump` |
| 51 | +- API changes must be intentional and well-documented |
| 52 | +- Breaking changes are only allowed in major version releases |
0 commit comments