Home › Scala › Scala 3 Windsurf rules

Scala 3 Windsurf rules

Windsurf rules for Scala 3 projects with sbt or scala-cli: immutable data, ADTs with enums, explicit effects, scalafmt, and MUnit tests.

WindsurfScala

Copy scala.md

How to use

Save this as .windsurf/rules/scala.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

---
trigger: glob
globs: **/*.scala,**/*.sbt,**/*.sc
---

# Scala 3

- Build with the repo's tool: `sbt compile test` (or `scala-cli test .`). Format with `scalafmt` (config in `.scalafmt.conf`) and fix `scalafix` warnings if configured.
- Scala 3 syntax: `enum` for ADTs, `given`/`using` for context parameters, extension methods instead of implicit classes. Follow the brace style already used in the repo (significant indentation or braces), don't mix them in one file.
- Immutable by default: `case class`, `val`, immutable collections. No `var` or mutable collections outside tight, local performance code.
- No `null`: use `Option`. No `.get` on `Option`/`Try`, and no `asInstanceOf`.
- Model errors as values: `Either[DomainError, A]` or the effect system's typed errors; exceptions only at boundaries.
- Effects: if the project uses Cats Effect (`IO`) or ZIO, keep side effects inside it, never call `unsafeRun*` except in `main`. Don't introduce a second effect library.
- Pattern matches on sealed types/enums must be exhaustive; treat the compiler warning as an error (`-Wunused:all`, `-Xfatal-warnings` or `-Werror` in scalacOptions if present).
- JSON with the repo's library (circe, jsoniter-scala, upickle) via derived codecs; validate input at the edge.
- Public APIs get explicit return types.

## Tests
MUnit (or the repo's framework) with property tests via ScalaCheck for pure logic.

## Done when
`sbt scalafmtCheckAll test` passes with no new warnings.