Haskell Functional skill for Claude Code

Done well means: illegal states are unrepresentable in the types, every function is total (no head, fromJust, incomplete patterns), effects live at the edges, records and data use strict fields by default, and the project builds with -Wall -Werror in CI with hlint clean and tests passing.

Ground rules

• Write the type signature first for every top-level binding. Let the compiler check your design before you write bodies; use typed holes (_) to ask GHC what fits.
• No partial functions in application code: head, tail, !!, fromJust, read, maximum on possibly-empty lists. Use pattern matching, Data.List.NonEmpty, listToMaybe, readMaybe.
• Text for human text, ByteString for bytes and wire data; String only for tiny scripts or APIs that demand it. Turn on OverloadedStrings.
• Strict fields on data types (!Int) or StrictData per module unless you need laziness deliberately.
• newtype for every domain identifier and unit (newtype UserId = UserId Int).
• Pure core, IO shell: business logic takes and returns plain data; main and handlers do the IO.

Project setup

ghcup install ghc --set recommended     # ghcup manages GHC, cabal, HLS, stack
ghcup install cabal latest
ghcup install hls latest
cabal init --interactive                 # or: stack new myproj
cabal build all && cabal test all
cabal run myproj -- --flag
cabal repl                               # :r reload, :t type, :i info, :doc

Choose	When
cabal (default)	Most new projects; Hackage-native; cabal.project + cabal freeze for pinning
stack	Team already uses it, or you want curated Stackage LTS snapshots out of the box
Nix (haskell.nix / nixpkgs)	Org already standardizes on Nix

Keep one GHC version per project and pin it (with-compiler: ghc-9.x.y in cabal.project, or the Stackage resolver). HLS must match the GHC version exactly.

-- myproj.cabal (excerpt)
common shared
  default-language: GHC2021            -- GHC2024 on GHC >= 9.10
  default-extensions: OverloadedStrings DerivingStrategies LambdaCase StrictData
  ghc-options: -Wall -Wcompat -Widentities -Wincomplete-uni-patterns
               -Wincomplete-record-updates -Wredundant-constraints -Wunused-packages

library
  import: shared
  hs-source-dirs: src
  exposed-modules: Billing.Invoice
  build-depends: base >=4.18 && <5, text, containers, mtl

test-suite spec
  import: shared
  type: exitcode-stdio-1.0
  main-is: Spec.hs
  hs-source-dirs: test
  build-depends: base, myproj, hspec, QuickCheck

Add -Werror in CI only (cabal build --ghc-options=-Werror), not in the package file uploaded to Hackage.

Modelling with types

data PaymentState
  = Pending
  | Paid !ReceiptId !UTCTime
  | Failed !FailureReason
  deriving stock (Eq, Show)

data FailureReason = CardDeclined | InsufficientFunds | ProviderError !Text
  deriving stock (Eq, Show)

newtype ReceiptId = ReceiptId Text
  deriving newtype (Eq, Ord, Show)

-- Smart constructor: the only way to build a valid Email
newtype Email = Email Text
mkEmail :: Text -> Either Text Email
mkEmail t
  | "@" `T.isInfixOf` t = Right (Email (T.toLower t))
  | otherwise           = Left ("invalid email: " <> t)

• Export the type but not its constructor (module M (Email, mkEmail)) to enforce the invariant.
• Sum types over boolean flags: data Visibility = Public | Private instead of Bool.
• Use DerivingStrategies to say whether an instance is stock, newtype, or anyclass.
• Records: enable OverloadedRecordDot (user.name) and DuplicateRecordFields if field names repeat across types; avoid partial record fields on multi-constructor types.

Maybe, Either, and composing failures

import Text.Read (readMaybe)

parseAge :: Text -> Either Text Int
parseAge t = case readMaybe (T.unpack t) of
  Nothing -> Left ("not a number: " <> t)
  Just n
    | n < 0 || n > 150 -> Left ("out of range: " <> t)
    | otherwise        -> Right n

mkUser :: Text -> Text -> Either Text User
mkUser rawEmail rawAge = do         -- Either is a Monad: first Left short-circuits
  email <- mkEmail rawEmail
  age   <- parseAge rawAge
  pure User {email, age}            -- NamedFieldPuns

Need	Use
Optional value	Maybe a + maybe, fromMaybe, mapMaybe
Failure with a reason	Either e a; e is a sum type in libraries, Text in scripts
Collect all validation errors	Validation (from validation / either packages) via Applicative
Failure inside IO	ExceptT e IO a locally, or throw typed exceptions at the edge
Many independent effects	traverse, sequenceA, for_

• traverse parseAge inputs :: Either Text [Int] fails on the first bad input.
• when, unless, for_, traverse_ (from Data.Foldable) for effects without results.

Typeclasses

• Define a typeclass only when you have several real instances and laws to state. A record of functions is often simpler for “interfaces” (dependency injection, mocking).
• Lawful instances: Semigroup/Monoid for combinable data (<>, mempty), Functor, Foldable, Traversable via deriving stock.
• Orphan instances (instance defined in neither the class’s nor the type’s module) cause conflicts; wrap in a newtype instead.
• Show is for debugging; write explicit rendering functions (renderInvoice :: Invoice -> Text) for user-facing output.

Application structure

Size	Pattern
Scripts, small tools	Plain IO with pure helpers
Services	ReaderT Env IO (“ReaderT pattern”): config, logger, DB pool in Env; IORef/TVar for state
Library needing abstract effects	mtl-style classes (MonadReader, custom MonadDB), or an effect library (effectful, bluefin) when the team agrees

data Env = Env { envPool :: Pool Connection, envLog :: LogAction IO Text }

newtype App a = App (ReaderT Env IO a)
  deriving newtype (Functor, Applicative, Monad, MonadIO, MonadReader Env)

runApp :: Env -> App a -> IO a
runApp env (App m) = runReaderT m env

Avoid StateT over IO for shared mutable state in concurrent code: it is lost on exceptions and not shared across threads. Use IORef or STM (TVar) inside Env.

Exceptions and resources

• Pure code returns Either/Maybe; IO code can throw. Catch at boundaries with try @SomeException sparingly; catch specific types (IOException, your own).
• Use bracket, finally, or withFile-style functions for resources; never manual open/close pairs.
• Asynchronous exceptions (killThread, timeouts) must not be swallowed: use safe-exceptions or unliftio whose catch rethrows async exceptions.
• error and undefined are for impossible states only; prefer an Either or a total type.

Laziness, strictness, and performance

• Space leaks usually come from lazy accumulators. Use foldl' (never foldl), strict fields, Data.Map.Strict, modifyIORef', and bang patterns on loop accumulators.
• length, nub (O(n²)), and ++ in a left-nested loop are common slow spots; use Data.Set/Data.HashSet for dedupe and Data.Text.Builder or Data.ByteString.Builder for output.
• String concatenation is a linked list of chars; switch to Text before optimizing anything else.
• Profile before guessing: cabal run --enable-profiling -- +RTS -p -hT -RTS, read the .prof file, view heap profiles with eventlog2html.
• +RTS -s prints GC stats; a high GC percentage points to allocation or leak issues.
• Use -O1 (cabal default) for release; -O2 only with measured benefit.

Concurrency

• async package: concurrently, mapConcurrently, race, withAsync — they cancel siblings on exception. Avoid bare forkIO in application code.
• STM (TVar, atomically) for shared state with invariants across several variables.
• Build with -threaded and run with +RTS -N for multicore.

Testing

-- test/Spec.hs
import Test.Hspec
import Test.QuickCheck

main :: IO ()
main = hspec $ do
  describe "parseAge" $ do
    it "rejects negative numbers" $
      parseAge "-1" `shouldSatisfy` isLeft
    it "round-trips valid ages" $ property $ \(n :: Int) ->
      (n >= 0 && n <= 150) ==> parseAge (T.pack (show n)) === Right n

• QuickCheck properties for parsers, serializers (decode . encode == Just), and algebraic laws; hspec examples for business rules.
• hspec-discover for automatic test discovery in larger suites.
• doctest or cabal-docspec keeps Haddock examples honest.

Reading GHC errors

Read the first error only, fix it, rebuild. Later errors are often consequences. For a catalog of the common messages (“Couldn’t match type”, “Ambiguous type variable”, “No instance for”, rigid type variables, monomorphism restriction) with cause and fix, read references/ghc-errors.md when the error text is not obvious.

Gotchas

• foldl builds thunks; foldl' from Data.List (re-exported by Prelude in base ≥ 4.20).
• Data.Map (lazy) values accumulate thunks under repeated insertWith; import Data.Map.Strict.
• show on Text adds quotes; use the text itself or T.unpack for display.
• read crashes on bad input; readMaybe from Text.Read.
• OverloadedStrings can make literals ambiguous in polymorphic code; annotate ("x" :: Text).
• lazy IO (readFile, getContents) can close handles late or read after a write; use strict Data.Text.IO / Data.ByteString reads or streaming libraries.
• Integer is arbitrary precision; Int overflows silently. Pick deliberately for money and IDs.

Verification

1. cabal build all --ghc-options=-Werror (or stack build --pedantic) succeeds.
2. hlint . clean, or justified {- HLINT ignore -} annotations.
3. cabal test all passes; QuickCheck properties run with enough cases (--qc-max-success=1000 for parsers).
4. Format with fourmolu or ormolu (whichever the project uses) in check mode.
5. For performance work: compare +RTS -s totals and profiles before and after.