A CLAUDE.md Template for Kotlin Projects

A useful CLAUDE.md for Kotlin tells Claude Code which module to change, which Gradle tasks to run, and how your project handles missing values and concurrent work. It should describe verified project choices, with short examples where a convention would otherwise be ambiguous.

Keep the changing work elsewhere. fenbs holds implementation tasks, approved choices, and recurring lessons, so your Kotlin instructions can stay focused on guidance that applies beyond the current session.

What should you inspect before using the template?

Read the repository instructions, build files, version catalog if present, and an ordinary source file with its tests. Identify whether you are working in a JVM service, an Android app, or a multiplatform library. Do not assume that a task from one kind of Kotlin project exists in another.

Gradle recommends using the project’s Gradle Wrapper↗ (opens in a new tab), which runs the declared Gradle version. Record the actual wrapper command for your shell and verify the task in the relevant module. A remembered command from another repository is a suggestion to investigate, not evidence.

• Find the intended module, source sets, and generated files that should remain untouched.
• Confirm the declared Kotlin and Java requirements without upgrading them as part of setup.
• Identify the existing formatter, test framework, and static checks, if the repository has them.
• Find one example each of error handling, a suspending function, and a test that maintainers consider representative.

If the instruction mechanism is new to you, read the CLAUDE.md file guide separately. The goal here is a Kotlin-specific working agreement, rather than a second explanation of how instruction files load.

What does a useful starter file look like?

The following is an example for a hypothetical JVM service with a module named service. Its paths and commands are examples, not a claim about your repository. Replace them only after checking the build and source files; remove sections that do not apply.

# Kotlin project instructions

## Scope
Work only in the requested module. Do not edit generated sources.
Do not change Kotlin, Gradle, Java, or dependency versions incidentally.

## Verified commands for this example repository
Run from the repository root.
macOS/Linux: ./gradlew :service:test :service:check
Windows PowerShell: .\gradlew.bat :service:test :service:check
Use the targeted test task while iterating; report which checks ran.

## Kotlin conventions
Follow the neighboring public API and error-handling conventions.
Model a genuinely absent value with a nullable type.
Do not add !! to silence a nullable-type error. Explain the invariant instead.
Keep Java interoperability checks at the boundary where practical.

## Concurrent work
Use the caller or application-owned coroutine scope.
Do not introduce unowned background work or blocking calls into a suspend path.
Preserve cancellation and the established dispatcher policy.

## Tests and review
Test the changed behavior, relevant null cases, and failure paths.
Use the existing coroutine test utilities when the module has them.
Report the changed behavior, executed commands, results, and unchecked cases.

For each line, ask what a reviewer could inspect. “Preserve cancellation” needs a neighboring implementation or test that makes the project’s convention visible. “Write good Kotlin” offers no such check. The CLAUDE.md examples offer more ways to turn broad preferences into observable instructions.

Give the file a small first assignment. Ask Claude to explain which instructions would apply to a proposed change before editing. A command that cannot be found or a convention with two conflicting examples is a setup question to resolve with a maintainer.

How should the instructions handle nullability?

Kotlin distinguishes nullable and non-nullable types. Its null-safety documentation↗ (opens in a new tab) explains safe calls and other ways to handle nullable values. Your instruction file should state the project’s policy for choosing among those mechanisms, rather than reciting the whole language reference.

For example, ask whether an absent delivery date is a valid business state, a malformed input, or an internal defect. Those meanings may require different behavior even if the compiler sees a nullable value in each case. A blanket instruction to replace every missing value with an empty string hides that distinction.

Name the boundary that owns validation and the existing error form. Then ask for tests that demonstrate the intended absent-value behavior. If a Java library is involved, point to a relevant adapter so Claude can follow the way this project contains uncertainty at that boundary.

A new business choice about what “missing” means belongs in an approved decision. Keeping it with project decisions in fenbs gives later assistants the reason, while the file carries the short rule they need during implementation.

Which coroutine conventions need to be explicit?

Coroutines are Kotlin’s way to express work that can pause and continue without blocking a thread while it waits. The official coroutine introduction↗ (opens in a new tab) provides the underlying concepts. The project-specific questions are who owns the work, how it stops, and where it is allowed to run.

Point to the existing scope owner and dispatcher convention. A coroutine scope groups work under a lifetime; a dispatcher determines where it runs. Explain whether a request, a screen, or the application owns a particular operation, and what should happen when that owner ends.

Ask Claude to preserve cancellation and avoid adding background work simply to make an operation appear faster. For a hypothetical download flow, the review question might be whether leaving the screen ends the download or transfers ownership elsewhere. A person must decide that product behavior before an assistant chooses an implementation.

How do you define evidence that a change works?

Separate the targeted behavior check from the wider module checks. A focused test can show that an empty response is handled correctly; it does not prove that every supported platform compiles. Require the final report to name the command, the environment, and any checks that were not run.

When the module already uses coroutine test utilities, point to its existing setup. Kotlin’s coroutine testing documentation↗ (opens in a new tab) describes tools such as runTest and a test scheduler for controlling simulated time. Avoid an instruction to wait real seconds when a deterministic test is available in the project.

• For nullable input, test the meaningful absent case and the ordinary present case.
• For asynchronous behavior, check cancellation or failure when the changed behavior depends on them.
• For public APIs, check the affected callers and any compatibility requirement.
• For environment failures, report the blocker precisely instead of marking the behavior as verified.

If a rule seems ignored, first check that the file was read before rewriting the Kotlin advice; the instruction troubleshooting guide covers that diagnosis. Keep findings tied to the task so a later session does not repeat a check that was already inconclusive.

How to do this with fenbs

1. Create a free account and add your Kotlin project to a kanban board.
2. Record the approved null-handling and coroutine ownership choices in Decisions and rules, including who chose them.
3. Save the adapted template in Skills and prompts, then add the actual implementation task with its plan and intended checks.
4. Connect your supported assistant using Integrations and ask it to read project context before the repository instructions.
5. Save progress with the tests actually run, remaining platform checks, and the next step. Add a lesson when a repeated mistake reveals a useful improvement.

fenbs does not compile Kotlin or run Gradle for you. If you only need a small instruction file for occasional local edits, a repository document may be enough; use fenbs when decisions, lessons, and handoffs need to survive individual chats.

Browse the AI prompts collection when you need a separate review or debugging prompt. Keep this file centered on the Kotlin project agreement, then update it when someone approves a lasting change to that agreement.