Haskell has the largest gap between code that compiles and code that's actually idiomatic of any mainstream language. The type system is powerful enough that AI can generate Haskell that type-checks but uses head on empty lists, catches errors with error "", and avoids the very abstractions that make Haskell valuable.
A CLAUDE.md at your project root tells the AI which Haskell you're writing. Here are 13 rules with the highest impact.
Rule 1: GHC version and language extensions
GHC version: 9.6+ (GHC2021 language set or explicit extensions).
Enable these extensions in package.yaml or cabal file (not per-file pragmas except for unusual cases):
OverloadedStrings, ScopedTypeVariables, LambdaCase, TupleSections,
DeriveFunctor, DeriveGeneric, GeneralizedNewtypeDeriving,
FlexibleInstances, FlexibleContexts
Do NOT enable: PartialTypeSignatures (forces you to complete type signatures).
Do NOT use extensions that enable unsafe operations unless documented.
GHC's language extension system is powerful but needs explicit guidance. AI sometimes adds extensions ad-hoc or omits ones that would enable cleaner code.
Rule 2: No partial functions — totality is the goal
Partial functions are banned:
- Never use `head`, `tail`, `init`, `last` — use pattern matching or `NonEmpty`
- Never use `fromJust` — use `maybe`, `fromMaybe`, or pattern match
- Never use `read` on untrusted input — use `readMaybe` from `Text.Read`
- Never use `error` for recoverable failures — use `Either` or `ExceptT`
- Never use `undefined` except as a temporary compile placeholder with a TODO comment
Prefer total alternatives:
`headMay`, `atMay` from the `safe` package, or pattern matching.
Partial functions are the #1 source of runtime crashes in Haskell. head [] throws an exception that the type system didn't catch. AI uses partial functions because they're shorter and common in tutorials.
Rule 3: Maybe and Either — explicit absence and failure
Absence and failure:
- `Maybe a` for values that may not exist
- `Either e a` for operations that can fail with an error
- `ExceptT e m a` for monadic computations that can fail
- `MaybeT m a` for monadic computations that may produce nothing
Chain with `>>=`, `<$>`, `<*>`, `maybe`, `either`, `fromMaybe`.
Never throw exceptions for business logic — use `Left err`.
For error types: define a sum type, not `String`:
`data AppError = NotFound Text | InvalidInput Text | DatabaseError Text`
error "something went wrong" is Haskell's equivalent of unchecked exceptions. The type system is there to make errors explicit — use it.
Rule 4: Type signatures on all top-level definitions
Every top-level function and value must have an explicit type signature:
`processUser :: UserId -> IO (Either AppError User)` — not inferred.
Type signatures serve as:
- Documentation (the primary kind)
- Compiler-checked contracts
- Guidance for type inference in complex expressions
Use `newtype` for type safety around primitives:
`newtype UserId = UserId { unUserId :: Int } deriving (Show, Eq, Ord)`
Not: `type UserId = Int` (type aliases provide no safety)
Type inference is powerful but type signatures are still mandatory for top-level definitions. AI sometimes omits them to save space — they're not optional.
Rule 5: Pattern matching — exhaustive and expressive
Pattern matching rules:
- Always handle all constructors — enable `-Wincomplete-patterns` in GHC options
- Use `LambdaCase` for concise single-argument matches:
`\case { Just x -> ...; Nothing -> ... }`
- Deconstruct in function arguments, not in the body:
`processUser (User uid name) = ...` not `processUser u = let uid = userId u in ...`
- Use `@` patterns to bind the whole value while matching: `processUser u@(User uid _) = ...`
- Wildcards `_` only when the value is genuinely unused
Exhaustive pattern matching with compiler warnings turns runtime errors into compile errors. AI often uses incomplete patterns or reaches for field accessors where destructuring is cleaner.
Rule 6: Functors, Applicatives, Monads — use the right abstraction
Abstraction selection:
- `fmap` / `<$>` when transforming a value inside a context (Functor)
- `<*>` when applying a wrapped function to a wrapped value (Applicative)
- `>>=` / `do` notation for sequential effects where each step depends on the previous (Monad)
- `traverse` for `t a -> (a -> f b) -> f (t b)` (effects over a traversable)
- `sequence` for `t (f a) -> f (t a)`
Prefer `do` notation for readability when there are 3+ monadic steps.
Prefer point-free style for simple compositions: `f . g . h` not `\x -> f (g (h x))`.
The Functor/Applicative/Monad hierarchy exists to express precisely how much power you need. AI often reaches for Monad/do when Applicative or fmap is sufficient — the less powerful abstraction is usually clearer.
Rule 7: Text, not String
String handling:
- Use `Text` (from `Data.Text`) everywhere, not `String` ([Char])
- Enable `OverloadedStrings` so string literals work as `Text`
- Use `Data.Text.pack`/`unpack` only at system boundaries (IO, legacy APIs)
- For building text: `Data.Text.Builder` or `fmt` library — not `++` concatenation
- For parsing: `attoparsec` or `megaparsec` — not manual `String` manipulation
- ByteString for binary data — never treat `ByteString` as text
String = [Char] is a linked list of characters. It's the default for historical reasons and is terrible for performance. Text is the correct type for textual data. AI uses String because tutorials use String.
Rule 8: Records and lenses
Record conventions:
- Use record syntax for data types with multiple fields
- Prefix field names with the type name to avoid ambiguity:
`data User = User { userId :: UserId, userName :: Text, userEmail :: Email }`
- Use `lens` or `optics` for nested record access/update
- Avoid the `RecordWildCards` extension — it makes imports invisible
- For large records: use `Generic` + `lens` derivation
When using lenses:
`user ^. userName` not `userName user`
`user & userName .~ "Alice"` not `user { userName = "Alice" }`
Record field names in Haskell pollute the module namespace without prefixing. Lenses provide composable access and update for nested data.
Rule 9: IO and effects — keep pure code pure
Effect discipline:
- Maximize pure functions — if it doesn't need IO, don't put it in IO
- Use `ReaderT env IO` as the application monad (not raw IO or a complex mtl stack)
- Keep the `IO` boundary at the edges: parse input, process purely, render output
- Use `IORef` only when mutation is genuinely required (rare)
- For config: pass explicit records, not global IORef or unsafePerformIO
For concurrent code: use `async` + `stm` (Software Transactional Memory).
Never use `unsafePerformIO` outside of FFI boundaries.
"IO everywhere" is a beginner pattern. Pure functions are easier to test, reason about, and compose. The discipline of keeping IO at the edges is one of Haskell's greatest design patterns.
Rule 10: Testing with Hspec and QuickCheck
Testing:
- Hspec for unit and integration tests (BDD-style: `describe`/`it`/`shouldBe`)
- QuickCheck for property-based testing — generate invariants, not just examples
- `hspec-discover` for automatic spec discovery
- Test pure functions without IO — makes tests fast and deterministic
- For IO: use `hspec` with `before`/`after` for setup/teardown
- Golden tests: `hspec-golden` for output comparison
Property patterns to always write:
roundtrip: `encode . decode = id`
idempotence: `f (f x) = f x`
commutativity where applicable
QuickCheck is one of Haskell's most valuable tools and is underused in AI-generated test suites. Property-based tests catch edge cases that example-based tests miss by definition.
Rule 11: Cabal/Stack and dependency management
Build system: Cabal with cabal.project, or Stack with stack.yaml — pick one and be consistent.
cabal conventions:
- Pin GHC version in cabal.project: `with-compiler: ghc-9.6.x`
- Use `cabal freeze` for reproducible builds
- Separate library, executable, and test stanzas in .cabal file
- Enable warnings in all stanzas: `-Wall -Wcompat -Widentities`
HLS (Haskell Language Server): configure in hie.yaml for IDE support.
Do NOT use `cabal install` globally — use `cabal run` or add to PATH via nix/ghcup.
Rule 12: Deriving and Generic
Use `deriving` to avoid boilerplate:
`deriving (Show, Eq, Ord, Generic)`
For JSON: use `aeson` with Generic derivation:
`instance ToJSON User; instance FromJSON User` — no manual instances unless customizing.
For other typeclasses: prefer `deriving` via `GeneralizedNewtypeDeriving` or `DerivingVia`.
Do NOT write manual `Show` instances unless the output format is specifically required.
Do NOT write manual `Eq` instances unless the equality semantics differ from structural equality.
Boilerplate Show/Eq/Ord instances are noise. deriving is the correct default. AI sometimes writes them manually.
Rule 13: Haddock and documentation
Documentation:
- All exported functions must have Haddock comments
- Format: `-- | Description. Example: @functionName arg@`
- Document the invariants and preconditions, not the implementation
- Use `@since` tags for API additions
- Run `cabal haddock` to verify documentation builds
Module exports: explicit export lists on all modules — no `module Foo where` without an export list.
Explicit exports make the API surface clear and prevent accidental exports.
Your CLAUDE.md starting point
# Haskell Project — AI Coding Rules
## Safety
No partial functions: no head/tail/fromJust/read/error/undefined.
Use Maybe/Either/ExceptT for absence and failure. Total functions only.
## Types
Explicit type signatures on all top-level definitions.
newtype over type aliases for domain types.
Text not String. OverloadedStrings enabled.
## Style
Exhaustive pattern matching (-Wincomplete-patterns enforced).
LambdaCase for single-argument matches.
Pure functions maximized — IO only at edges.
ReaderT env IO as application monad.
## Abstractions
Use fmap/Applicative when Monad is not needed.
traverse for effects over traversables.
Point-free for simple compositions.
## Records
Prefix field names with type name. lens/optics for nested access.
## Testing
Hspec + QuickCheck. Properties: roundtrip, idempotence. Pure functions tested without IO.
## Build
GHC 9.6+. -Wall -Wcompat -Wincomplete-patterns. Explicit export lists on all modules.
Why Haskell especially needs this
Haskell's type system can catch an enormous class of bugs at compile time — but only if you use it correctly. Partial functions, String instead of Text, and avoiding the abstraction hierarchy all leave power on the table.
CLAUDE.md is the difference between AI that uses Haskell and AI that uses Haskell well.
The full rules pack across 15+ languages is at gumroad — $27.