DEV Community: Olivia Craft

CLAUDE.md for C++: 13 Rules That Make AI Write Safe, Modern, Idiomatic C++

Olivia Craft — Sat, 16 May 2026 06:58:19 +0000

CLAUDE.md for C++: 13 Rules That Make AI Write Safe, Modern, Idiomatic C++

C++ is the language where AI assistance can either save you thousands of hours — or introduce bugs that hide in production for months. The difference comes down to whether you've told your AI assistant which C++ you're writing.

Without a CLAUDE.md, the model might write C++98 in a C++20 codebase, reach for raw pointers when you expect smart pointers, or generate undefined behavior that passes every test until the wrong CPU architecture exposes it.

These 13 rules have emerged from real projects — the patterns that matter most for keeping AI-generated C++ safe, modern, and idiomatic.

Rule 1: Pin the standard — C++20 or C++23 only

Standard: C++20 minimum. Use C++23 features where available.
Enable: concepts, ranges, coroutines, std::span, std::format.
Forbidden: C++98/11/14 idioms when modern equivalents exist.

AI models have seen enormous amounts of legacy C++ code. Without this rule, you'll get a mix of std::bind and lambdas, printf next to std::format, and iterators where ranges would be cleaner.

Why it matters: C++20 concepts alone eliminate entire classes of template error messages and make intent explicit. std::span replaces the pointer+size anti-pattern. The standard pin prevents the model from defaulting to the lowest common denominator.

// Without rule — AI might generate this
template<typename T>
void process(T* data, size_t n) { ... }

// With rule — AI generates this
template<std::ranges::range R>
void process(R&& range) { ... }

Rule 2: Smart pointers only — raw owning pointers banned

Memory: std::unique_ptr / std::shared_ptr for ownership.
Raw pointers: observer pointers only (never owning).
Forbidden: new/delete in application code. malloc/free never.
Use std::make_unique and std::make_shared exclusively.

The most common AI-generated C++ mistake is mixing ownership models. A function that accepts T* when it means "I own this" is a memory leak waiting to happen — and AI generates this pattern constantly without explicit instruction.

// Banned — raw owning pointer
Widget* createWidget() {
    return new Widget();  // Who deletes this?
}

// Required — ownership explicit
std::unique_ptr<Widget> createWidget() {
    return std::make_unique<Widget>();
}

The observer pointer exception: T* and T& are fine as non-owning references — they communicate "I borrow this, I don't own it."

Rule 3: RAII for every resource — no manual cleanup

Resources: wrap every resource in a RAII type.
File handles → std::fstream. Locks → std::lock_guard / std::unique_lock.
Network/OS handles → custom RAII wrapper with destructor.
No resource acquired without a destructor that releases it.

AI will generate fclose(file) at the end of a function. It won't always generate it on every early return. RAII removes the entire problem.

// AI without rule — leak on early return
FILE* f = fopen("data.bin", "rb");
if (!validate()) return;  // leak
process(f);
fclose(f);

// With rule — RAII, always closed
{
    std::ifstream f("data.bin", std::ios::binary);
    if (!validate()) return;  // destructor runs
    process(f);
}

Rule 4: No undefined behavior — ever

UB rules:
- No signed integer overflow. Use checked arithmetic or unsigned where wrap is expected.
- No out-of-bounds access. Use .at() in non-hot paths. Assert bounds in hot paths.
- No uninitialized reads. Initialize all variables at declaration.
- No dangling references. No returning references to locals.
- No strict aliasing violations. Use std::bit_cast instead of reinterpret_cast.

This is the rule AI needs most explicitly. UB that "works" on x86 can crash on ARM. UB that passes tests can be exploited by compilers doing aggressive optimization. Models will generate UB because it compiles.

// UB — uninitialized variable
int result;
if (condition) result = compute();
return result;  // undefined if !condition

// Required — always initialized
int result = 0;
if (condition) result = compute();
return result;

Rule 5: Prefer value semantics — move is free

Value semantics: pass by value when moving is cheap.
Return by value — NRVO/RVO makes this free.
std::move explicitly only when transferring ownership.
Const references for large objects you only read.
Avoid output parameters — return structs or std::tuple instead.

AI defaults to C-style output parameters and reference-heavy signatures. Modern C++ with move semantics makes value semantics fast and clean.

// AI without rule — output parameter style
void getResult(std::vector<int>& out) {
    out = compute();
}

// With rule — value semantics
std::vector<int> getResult() {
    return compute();  // NRVO, zero copy
}

Rule 6: Concepts for every template constraint

Templates: constrain with concepts, never unconstrained.
Use standard concepts: std::integral, std::floating_point, std::ranges::range, std::invocable.
Define project concepts in a concepts.hpp header.
No typename T without a constraint.

Unconstrained templates produce error messages that span 50 lines. Concepts produce one clear diagnostic at the call site.

// Without rule — unconstrained template
template<typename T, typename Func>
auto transform(T container, Func f) { ... }

// With rule — concepts constrain intent
template<std::ranges::input_range R, std::invocable<std::ranges::range_value_t<R>> F>
auto transform(R&& range, F&& f) { ... }

Rule 7: Error handling with std::expected or exceptions — no error codes

Error handling:
- Functions that can fail: return std::expected<T, Error> (C++23) or throw typed exceptions.
- No int return codes. No errno. No output parameters for errors.
- Exception types: derive from std::runtime_error or std::logic_error.
- Error type: define a project Error enum or variant.
- No catch(...) without rethrow or logging.

AI generates error codes because of the enormous volume of C legacy code in training data. C++ deserves typed error handling.

// Banned — C-style error code
int readFile(const std::string& path, std::string& out);

// Required — typed result
std::expected<std::string, FileError> readFile(const std::filesystem::path& path);

Rule 8: const everywhere it can be

const rules:
- All variables that don't change: const.
- All member functions that don't mutate: const.
- All parameters you don't modify: const ref.
- Prefer constexpr for compile-time constants over const.
- consteval for functions that must compute at compile time.

const communicates intent, enables optimizations, and prevents a class of bugs. AI forgets it unless you insist.

// Without rule — missed const opportunities
std::string getName(User user) {
    std::string result = user.name;
    return result;
}

// With rule — const-correct
std::string getName(const User& user) {
    const std::string result = user.name;
    return result;
}

Rule 9: std::span and std::string_view — not raw arrays or const char*

Buffers: std::span<T> for contiguous ranges. Never T* + size.
Strings: std::string_view for read-only string parameters. Never const char*.
Ownership strings: std::string. Never char[].
No C string functions: strlen, strcpy, sprintf banned.

std::span and std::string_view are zero-cost abstractions that express intent precisely. const char* parameters can't communicate lifetime or bounds.

// Banned — raw C-style
void process(const char* data, size_t len);

// Required — expressive and safe
void process(std::span<const std::byte> data);
void log(std::string_view message);

Rule 10: Structured bindings and pattern matching — use them

Structured bindings: use for tuple/pair/struct decomposition.
std::visit with overloaded lambdas for std::variant.
if constexpr for compile-time branching in templates.
Avoid index-based tuple access (std::get<0>).

This makes AI-generated C++ readable. Index-based access and manual pair.first/pair.second are noise.

// Without rule — index access
auto result = getCoordinates();
double x = std::get<0>(result);
double y = std::get<1>(result);

// With rule — structured binding
auto [x, y] = getCoordinates();

Rule 11: Thread safety is explicit — no implicit sharing

Concurrency:
- Shared mutable state: protected by std::mutex always.
- Prefer std::atomic for single-value shared state.
- No global mutable state. No static mutable locals in multithreaded code.
- std::jthread over std::thread (automatic join).
- std::latch / std::barrier / std::counting_semaphore over manual condition variables.

AI generates code with races because races don't crash on the first test run. Making thread safety explicit in the config catches it before review.

// Without rule — silent data race
static int counter = 0;
void increment() { ++counter; }

// With rule — explicit atomic
static std::atomic<int> counter{0};
void increment() { counter.fetch_add(1, std::memory_order_relaxed); }

Rule 12: Build with warnings-as-errors — the compiler is a reviewer

Build flags (required):
-Wall -Wextra -Wpedantic -Werror
-Wconversion -Wshadow -Wnull-dereference
Sanitizers in debug: -fsanitize=address,undefined
clang-tidy: enabled with modernize-*, cppcoreguidelines-* checks

AI-generated code that compiles is not finished. Warnings-as-errors forces the model to generate cleaner code when you describe the constraint explicitly in CLAUDE.md.

Rule 13: Modules or namespaces — never pollute global scope

Namespaces: every symbol in a project namespace. No using namespace std in headers.
Modules (C++20): prefer over #include where toolchain supports.
Anonymous namespaces: for translation-unit-local symbols.
No #define for constants — use constexpr.
No using namespace X in headers — ever.

AI loves using namespace std; because it appears in every tutorial. It's banned in production headers.

// Banned in headers
using namespace std;

// Required
namespace myproject {
    constexpr std::size_t kMaxBufferSize = 4096;

    class DataProcessor {
        std::vector<std::byte> buffer_;
    public:
        std::expected<void, ProcessError> process(std::span<const std::byte> input);
    };
}

The CLAUDE.md block for C++

## C++ Standards

**Standard:** C++20 minimum (C++23 where available)
**Compiler:** Clang 16+ or GCC 13+
**Build:** -Wall -Wextra -Wpedantic -Werror -Wconversion -Wshadow

### Memory
- std::unique_ptr / std::shared_ptr for ownership. std::make_unique / std::make_shared only.
- Raw pointers = non-owning observer only. new/delete banned in application code.
- RAII for all resources — file handles, locks, OS handles.

### Types and APIs  
- std::span<T> for buffers (never T* + size).
- std::string_view for read-only strings (never const char*).
- std::expected<T, E> for fallible operations (C++23). Typed exceptions otherwise.
- No C string functions: strlen/strcpy/sprintf banned.

### Templates
- Constrain every template parameter with concepts. No bare typename T.
- Structured bindings over index access. if constexpr over SFINAE.

### Safety
- No UB: initialize all variables. Use .at() outside hot paths. No signed overflow.
- const everywhere possible. constexpr for compile-time constants.
- No using namespace in headers. Every symbol in project namespace.

### Concurrency
- std::mutex for shared mutable state. std::atomic for single values.
- std::jthread over std::thread. No global mutable state.

Why this matters

The 13 rules above don't describe a style preference. They describe the line between C++ that a senior engineer would ship and C++ that would be flagged in review — or worse, that ships and fails under sanitizers.

AI models have internalized decades of C++ code, most of it pre-C++11. Without explicit constraints, they'll default to the mean of that training distribution: raw pointers, error codes, unconstrained templates, and platform-specific assumptions.

The CLAUDE.md block above shifts that default. It doesn't eliminate review — but it raises the floor so that AI-generated C++ starts from a position worth reviewing.

The cost of writing this config once is about 15 minutes. The cost of reviewing AI-generated C++ without it is every sprint.

CLAUDE.md for Haskell: 13 Rules That Make AI Write Idiomatic, Type-Safe Haskell

Olivia Craft — Fri, 15 May 2026 06:59:37 +0000

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.

CLAUDE.md for Scala: 13 Rules That Make AI Write Idiomatic, Type-Safe Scala

Olivia Craft — Thu, 14 May 2026 06:58:09 +0000

Scala has a well-known problem: it can be written in many styles, from Java-with-semicolons to pure functional with category theory abstractions. AI assistants without explicit guidance default to the most common patterns in their training data — which is often Java-style Scala from older codebases.

The result: mutable variables, null checks, raw Future.map chains without proper error handling, and classes where case classes belong.

A CLAUDE.md file tells the AI which Scala you're writing. Here are the 13 rules that matter most.

Rule 1: Scala version and style target

Scala version: 3.x (Scala 3 syntax — no Scala 2 `implicit` keyword, use `given`/`using`).
Style: functional-first. Immutable by default. Effects tracked explicitly.
Framework: [Akka / ZIO / Cats Effect / Play — specify yours]
Build: sbt with explicit dependency versions pinned in build.sbt.

Scala 3 changed the syntax for implicits, extension methods, and type classes significantly. AI trained on pre-Scala 3 material generates Scala 2 syntax. Make the version explicit.

Rule 2: Case classes for data — not plain classes

Use case classes for all data transfer objects, domain models, and value objects:
  `case class User(id: UserId, name: String, email: Email)`

Benefits the AI must leverage:
- Automatic `equals`, `hashCode`, `copy`, `toString`
- Pattern matching support
- Immutability by default
- `unapply` for destructuring

Use `@derive` (Scala 3) for additional typeclass derivation (Show, Codec, Schema).
Use `opaque type` for type-safe wrappers: `opaque type UserId = Long`.

AI often generates plain classes or Java-style beans for domain data. Case classes are the idiomatic Scala choice and unlock pattern matching throughout the codebase.

Rule 3: Pattern matching — exhaustive and expressive

Use pattern matching as the primary dispatch mechanism:

  response match
    case Success(user) => process(user)
    case Failure(e: NotFoundException) => notFound(e.message)
    case Failure(e) => internalError(e)

Rules:
- Always handle all cases — enable `-Wnonexhaustive-match` compiler warning
- Use guard clauses in patterns: `case user if user.active => ...`
- Destructure deeply: `case User(id, _, Email(addr)) => ...`
- Prefer `match` expressions that return values over `match` with side effects

Pattern matching in Scala is more powerful than in most languages — AI underuses it. Exhaustive matching with compiler warnings is a major correctness tool.

Rule 4: Option, Either, Try — no null, no exceptions for flow

Error and absence handling:
- `Option[A]` for values that may be absent — never `null`
- `Either[Error, A]` for operations that can fail with a meaningful error
- `Try[A]` only at the boundary with exception-throwing Java libraries
- Never throw exceptions for business logic — use `Left(error)` or `Option.empty`
- Chain with `map`, `flatMap`, `fold`, `getOrElse`, `recover`

For complex chains: use for-comprehensions over nested flatMap calls.

null and exceptions as control flow are Java habits that leak into Scala. AI without guidance uses them. Option/Either with for-comprehensions is idiomatic.

Rule 5: For-comprehensions over nested flatMap

Use for-comprehensions for sequential monadic operations:

  for
    user    <- findUser(id)
    account <- findAccount(user.accountId)
    _       <- validateBalance(account, amount)
  yield Payment(user, account, amount)

Not:
  findUser(id).flatMap(user =>
    findAccount(user.accountId).flatMap(account =>
      validateBalance(account, amount).map(_ => Payment(user, account, amount))
    )
  )

For-comprehensions work with any monad: Option, Either, Future, IO, ZIO.

For-comprehensions are syntactic sugar for flatMap/map chains. They're dramatically more readable for sequential operations. AI often generates nested lambda chains.

Rule 6: Immutability — val over var, immutable collections

Immutability rules:
- `val` by default — `var` only when mutation is genuinely required and documented
- Immutable collections: `List`, `Vector`, `Map`, `Set` from `scala.collection.immutable`
- Never import `scala.collection.mutable` without an explicit comment explaining why
- Use `copy` on case classes instead of mutating: `user.copy(name = "Alice")`
- Prefer `foldLeft`/`foldRight` over accumulator variables

If you need a mutable cell: use `Ref` (ZIO), `IORef` (Cats Effect), or `AtomicReference`.

Mutable state is the source of most concurrency bugs. Scala's type system enables functional immutability — AI needs to be told to use it.

Rule 7: Type classes — given/using, not implicit magic

Scala 3 type class pattern:

  trait Show[A]:
    def show(a: A): String

  given Show[User] with
    def show(u: User) = s"User(${u.id}, ${u.name})"

  def display[A: Show](a: A): String = summon[Show[A]].show(a)

Rules:
- Use `given` for instances, `using` for parameters (not `implicit`)
- Derive type class instances where possible: `derives Show, Encoder, Decoder`
- Keep given instances in companion objects or dedicated `given` files
- Never use `implicit` — Scala 2 syntax is banned in Scala 3 style

The implicit → given/using migration is one of the biggest Scala 2 → Scala 3 changes. AI trained on Scala 2 generates implicit val and implicit def everywhere.

Rule 8: Collections — right tool for the operation

Collection selection:
- `List`: prepend-heavy workloads, pattern matching, recursive algorithms
- `Vector`: indexed access, append, large collections (O(log n) operations)
- `Map`/`Set`: lookups and membership tests
- `LazyList`: potentially infinite sequences, streaming data
- `Array`: only when interoperating with Java libraries that require it

Operations:
- `map`, `flatMap`, `filter`, `foldLeft` for transforms
- `groupBy`, `partition`, `span`, `takeWhile` for splitting
- `zipWithIndex` instead of index-based loops
- `traverse` (Cats) for `List[F[A]] => F[List[A]]` (effects in collections)

AI sometimes uses Array for everything (Java habit) or List where Vector is more appropriate. The right collection type matters for performance and idiomatic code.

Rule 9: Futures and concurrency

If using Scala Futures:
- Always provide an explicit `ExecutionContext` — never use `global` in production
- Use `Future.successful`, `Future.failed` for already-complete values
- Chain with `map`, `flatMap`, `recover`, `recoverWith`
- Use `Future.sequence` for parallel execution: `Future.sequence(List(f1, f2, f3))`
- Set timeouts at the boundary — Future itself has no timeout

If using ZIO or Cats Effect (preferred for new code):
- Use `ZIO[R, E, A]` / `IO[E, A]` instead of Future
- Effects are values — compose them without executing until the `main` method
- Use `ZIO.foreachPar` / `IO.parSequence` for parallel effects
- Structured concurrency: `ZIO.scoped` / `Resource` for resource management

Futures with implicit execution contexts are a common AI default. Specify which concurrency model your project uses — ZIO and Cats Effect have very different conventions.

Rule 10: Testing — ScalaTest or MUnit with property-based testing

Testing:
- Framework: ScalaTest (FlatSpec or FunSuite style) or MUnit
- Property-based testing: ScalaCheck for invariant verification
- Style: `"description" should "behavior"` (FlatSpec) or `test("description")` (MUnit/FunSuite)
- Async tests: use `Future`-aware or `IO`-aware test runners
- No `Thread.sleep` in tests — use async assertions or test schedulers
- Fixture setup: `beforeEach`/`afterEach` or `fixture.test`

For ZIO: use `zio-test` with `ZIOSpecDefault`.
For Cats Effect: use `munit-cats-effect`.

Scala testing frameworks are diverse. Without specifying, AI may mix styles or generate blocking tests for async code.

Rule 11: Error types — sealed hierarchies, not strings

Define errors as sealed traits:

  sealed trait AppError
  case class NotFound(id: String) extends AppError
  case class ValidationError(field: String, message: String) extends AppError
  case class DatabaseError(cause: Throwable) extends AppError

Use these as the Left side of Either[AppError, A].
Pattern match on them exhaustively — the compiler will warn if a case is missing.
Never use `String` or `Exception` as an error type in business logic.

String errors are untyped and non-exhaustive. Sealed trait hierarchies give compile-time completeness checking and make error handling explicit and safe.

Rule 12: sbt and dependency hygiene

sbt conventions:
- Pin all dependency versions explicitly in `build.sbt` — no `latest.release`
- Use `dependencyOverrides` for transitive version conflicts
- Organize: `libraryDependencies` grouped by: compile / test / provided
- Enable compiler flags: `-Wunused`, `-Wvalue-discard`, `-Xfatal-warnings` in CI
- Separate modules in a multi-project build for clean dependency boundaries
- Use `scalafmt` for formatting — config in `.scalafmt.conf`, enforced in CI

AI sometimes generates %% version ranges or omits important compiler flags. Strict compiler settings catch bugs before runtime.

Rule 13: Logging with structured context

Logging:
- Use SLF4J + Logback (or ZIO Logging / log4cats for effect systems)
- Structured logging preferred: JSON output in production
- Every log call includes context: `logger.info("Payment processed", Map("userId" -> userId, "amount" -> amount))`
- Log levels: trace/debug (dev), info (normal), warn (degraded), error (failure)
- No `println` or `System.out.println` in production code
- Correlation IDs: propagate via MDC (SLF4J) or ZIO FiberRef / Cats Effect IOLocal

Your CLAUDE.md starting point

# Scala Project — AI Coding Rules

## Version
Scala 3.x. No implicit keyword — use given/using.

## Data
Case classes for domain models. opaque type for type-safe wrappers.
Immutable by default. val over var. copy() over mutation.

## Error Handling
Option for absence. Either[AppError, A] for fallible operations. No null. No exceptions for business logic.
Sealed trait hierarchies for error types — exhaustive pattern matching enforced.

## Style
For-comprehensions over nested flatMap. Pattern matching as primary dispatch.
Immutable collections: List/Vector/Map/Set.

## Effects
[ZIO / Cats Effect / Future — specify]. Effects are values. No Thread.sleep. Structured concurrency.

## Testing
[ScalaTest FunSuite / MUnit / zio-test]. Property-based with ScalaCheck. Async-aware.

## Build
sbt. Pinned dependency versions. scalafmt enforced. -Wunused -Xfatal-warnings in CI.

The gap this closes

The same Scala code compiles whether it's idiomatic or not. The difference between Java-in-Scala and real Scala shows up in maintainability, performance characteristics, and how well the compiler catches bugs.

CLAUDE.md is what makes AI output land on the right side of that line — consistently, across sessions and team members.

The full rules pack across 14+ languages is at gumroad — $27.

CLAUDE.md for Elixir: 13 Rules That Make AI Write Idiomatic, OTP-Aware Elixir

Olivia Craft — Wed, 13 May 2026 08:57:49 +0000

Elixir has a sharper gap between working code and idiomatic code than most languages. AI assistants can write Elixir that compiles and passes tests — but misses the OTP patterns, function head dispatch, supervision trees, and pipe conventions that experienced Elixir developers use as a matter of course.

The result: code that works in dev, breaks under load, and doesn't behave like the Elixir ecosystem expects.

A CLAUDE.md at your project root closes this gap. Here are the 13 rules with the highest impact.

Rule 1: OTP first — processes, not objects

This is an OTP application. Model concurrent behavior with:
- GenServer for stateful processes
- Supervisor for fault tolerance and restart strategies
- Task for one-off concurrent work
- Agent for simple shared state (prefer GenServer for anything non-trivial)

Do NOT model concurrency with shared mutable state, mutexes, or global variables.
The process is the unit of concurrency and isolation.

Elixir's concurrency model is built on the Actor model via OTP. AI without this context tends to reach for abstractions from other languages. GenServer + Supervisor is how Elixir systems are built — this needs to be explicit.

Rule 2: Function head dispatch — not cond or case at the top

Use pattern matching in function heads for branching:

  def process(%{status: :active} = user), do: ...
  def process(%{status: :inactive} = user), do: ...
  def process(%{status: status}), do: {:error, "unknown status: #{status}"}

Not:
  def process(user) do
    cond do
      user.status == :active -> ...
      user.status == :inactive -> ...
    end
  end

Reserve `case` for local branching within a function. Reserve `cond` for boolean expressions without a matching value.

This is the most common idiom gap. AI defaults to cond or case at the function level when function head dispatch is cleaner and more idiomatic. Elixir developers read function head dispatch as the primary dispatch mechanism.

Rule 3: Pipe operator discipline

Pipe rules:
- Use `|>` when transforming data through 3+ steps
- Each pipe step should be a single operation (avoid anonymous functions in pipes unless necessary)
- The first argument of every piped function must be the data being transformed
- Don't pipe into `IO.inspect/2` in production code — use Logger
- Break long pipes into named intermediate values when readability suffers

Avoid:
  result = transform(filter(validate(data)))  # nest style

Prefer:
  result = data
    |> validate()
    |> filter()
    |> transform()

The pipe operator is central to Elixir's readability. AI sometimes generates nested function calls or breaks the single-data-flow rule by adding extra arguments mid-pipe.

Rule 4: Pattern matching on with — not nested case

Use `with` for sequential operations where any step can fail:

  with {:ok, user} <- fetch_user(id),
       {:ok, account} <- fetch_account(user),
       {:ok, _} <- charge(account, amount) do
    {:ok, "charged"}
  else
    {:error, :not_found} -> {:error, "user not found"}
    {:error, reason} -> {:error, reason}
  end

Not nested case/if chains.
Return `{:ok, value}` and `{:error, reason}` tuples from all functions that can fail.

with is the idiomatic way to chain fallible operations. Nested case blocks grow quickly and are hard to extend. AI often generates nested case because it's the more universally recognizable pattern.

Rule 5: Supervision trees — crash and restart, don't defend

Supervision strategy:
- Use `:one_for_one` for independent workers
- Use `:one_for_all` when workers have shared state that becomes inconsistent on crash
- Use `:rest_for_one` when workers have ordered dependencies
- Start supervised processes in application.ex or a dedicated Supervisor module
- Do NOT rescue exceptions in GenServer callbacks to avoid crashes — let it crash, let the supervisor restart

The supervisor IS the error handler. Writing defensive rescue clauses in worker processes fights the design.

"Let it crash" is a core Elixir/Erlang philosophy that AI without guidance will work against. AI tends to add rescue blocks everywhere. The OTP pattern is to let processes crash and recover via supervision.

Rule 6: Ecto — changesets and queries

Database access: Ecto only.
- All data validation in changesets: `cast`, `validate_required`, `validate_format`
- Queries built with Ecto.Query DSL — no raw SQL except for complex queries using `fragment/1`
- No `Repo.get!` in business logic — use `Repo.get` and handle nil explicitly
- Preload associations explicitly: `Repo.preload(user, [:posts])` — no lazy loading
- Use `Repo.transaction` for operations that must be atomic
- Schema changesets are the single validation point — not controllers or context functions

Ecto's design is opinionated. AI without guidance uses get! everywhere (raising on nil), forgets preloads (causing N+1-equivalent issues), and puts validation in the wrong layer.

Rule 7: Contexts — bounded modules, not one schema one module

Organize with Phoenix contexts (even outside Phoenix):
- One context module per domain: `Accounts`, `Payments`, `Inventory`
- Context functions are the public API: `Accounts.get_user(id)`, `Accounts.create_user(attrs)`
- Schema modules are private to contexts — not called directly from controllers or other contexts
- No cross-context direct schema access — only through the owning context's API

This is the Phoenix 1.3+ architecture. Do not use the older one-schema-one-controller pattern.

Phoenix Contexts were introduced specifically to solve the "fat model" problem. AI trained on older Phoenix material generates the pre-context pattern. Specify the version explicitly.

Rule 8: Atoms — safe usage

Atom discipline:
- Never convert user-provided strings to atoms with `String.to_atom/1`
  (atoms are not garbage collected — unlimited creation = memory leak / DoS vector)
- Use `String.to_existing_atom/1` when converting known strings to atoms
- Module names, function names, map keys in your own code: atoms are fine
- JSON parsing: use string keys by default, not atom keys (Jason default is correct)

String.to_atom/1 with user input is a security and stability vulnerability unique to Erlang/Elixir. AI generates it without this context. This rule needs to be explicit.

Rule 9: Message passing — send, receive, and GenServer calls

Process communication:
- Use `GenServer.call/3` for synchronous requests (returns a value)
- Use `GenServer.cast/2` for asynchronous fire-and-forget (no return)
- Use `send/2` + `receive` only for ad-hoc message passing not managed by OTP
- Always set timeouts on `call`: `GenServer.call(pid, msg, 5_000)`
- Handle unexpected messages in `handle_info/2` — don't let them accumulate in the mailbox

Never use `Process.sleep/1` for coordination — use `GenServer.call` or `Task.async/await`.

Process communication patterns are Elixir-specific. AI without guidance uses send/receive where GenServer is correct, or forgets to handle handle_info for system messages.

Rule 10: Testing with ExUnit — async and isolation

Testing:
- All tests: `use ExUnit.Case, async: true` unless they share global state (database)
- Database tests: use `Ecto.Adapters.SQL.Sandbox` for transaction isolation
- Test setup: `setup` blocks, not module attributes
- Use `assert {:ok, _} = MyModule.function(args)` — match on the structure
- Factory: ExMachina for test data, not hand-built maps
- No `Process.sleep` in tests — use `assert_receive` with a timeout for async assertions
- Mock external services with `Mox` — define behaviors and verify expectations

Elixir's async testing and Ecto sandbox require specific setup. AI without guidance creates sequential tests that run slowly or break isolation.

Rule 11: Telemetry and structured logging

Observability:
- Use `:telemetry` for emitting metrics from library/application code
- Use `Logger.metadata/1` to attach context to log entries: `Logger.metadata(user_id: id, request_id: req_id)`
- Log levels: debug (verbose dev), info (normal ops), warning (degraded), error (failure)
- No bare `IO.puts` or `IO.inspect` in production code — use Logger
- Attach telemetry handlers in application startup, not inline

Telemetry is the standard instrumentation library in the Elixir ecosystem. AI often uses IO.inspect for debugging without switching to Logger for production code.

Rule 12: Structs over bare maps for domain data

Domain data:
- Define structs for all domain entities: `defstruct [:id, :name, :email]`
- Use `@enforce_keys` for required fields: `@enforce_keys [:id, :name]`
- Structs provide compile-time key checking — bare maps do not
- Use `%User{}` not `%{id: ..., name: ...}` when the shape is known
- Typespec every public function: `@spec create_user(attrs :: map()) :: {:ok, User.t()} | {:error, Ecto.Changeset.t()}`

Structs with typespecs make dialyzer useful. AI often generates bare maps for domain data, losing the documentation and static analysis benefits.

Rule 13: Mix tasks and releases

Deployment:
- Use `mix release` for production deployments — not `mix run`
- Config: `config/runtime.exs` for runtime configuration (env vars read at startup)
  `config/config.exs` for compile-time only
- Never hardcode secrets — use `System.fetch_env!/1` in `config/runtime.exs`
- Health checks: implement a simple HTTP endpoint, not a Mix task that shells out
- Migrations: always run with `--no-start` in CI: `mix ecto.migrate --no-start`

Release configuration is a common stumbling block. AI often suggests config/config.exs for runtime values, which means env vars are read at compile time and baked into the release — not what you want in Docker deployments.

Your CLAUDE.md starting point

# Elixir Project — AI Coding Rules

## Architecture
OTP application. GenServer + Supervisor for concurrency. Let it crash — supervisors handle recovery.
Contexts for domain boundaries. Schema modules private to their context.

## Patterns
Function head dispatch over cond/case at function level.
with for sequential fallible operations — {:ok, val} / {:error, reason} tuples everywhere.
Pipe operator for 3+ step data transforms.

## Ecto
Changesets for all validation. Explicit preloads. Repo.get not Repo.get!.
Raw SQL only via fragment/1. Transactions for atomic operations.

## Atoms
Never String.to_atom/1 on user input. String.to_existing_atom/1 for known strings only.

## Testing
async: true where possible. Ecto.Adapters.SQL.Sandbox for DB tests.
Mox for external service mocks. assert_receive for async. No Process.sleep in tests.

## Observability
Logger with metadata. Telemetry for metrics. No IO.puts/IO.inspect in production.

## Deployment
mix release. runtime.exs for env vars. System.fetch_env!/1 for secrets.

Why Elixir especially needs this

Elixir has unusually strong conventions — OTP patterns, the pipe operator, with, contexts — that diverge significantly from how imperative languages solve the same problems. AI trained on a broad corpus defaults to the more common patterns.

CLAUDE.md is how you tell the AI which decade and which paradigm it's working in.

The full rules pack across 13+ languages is at gumroad — $27.

CLAUDE.md for Ruby: 13 Rules That Make AI Write Idiomatic, Production-Ready Ruby

Olivia Craft — Tue, 12 May 2026 06:58:41 +0000

Ruby has a distinct culture around idiomatic code. The language is designed so that well-written Ruby reads almost like English — concise, expressive, and elegant. AI-generated Ruby often misses this: the code works, but it reads like Ruby written by someone who learned Python first.

A CLAUDE.md file at your repo root tells your AI assistant what "good Ruby" looks like for your project. Here are 13 rules that matter most.

Rule 1: Ruby version and runtime environment

Ruby version: 3.3+. Use YJIT in production (`RUBY_YJIT_ENABLE=1` or `--yjit`).
Bundler manages all gems — no manual `require` for anything in the Gemfile.
`.ruby-version` file is authoritative for local development.

Ruby 3.x has significant performance improvements and new syntax. AI often generates code compatible with Ruby 2.x. Specifying the version prevents outdated patterns like proc { } where -> {} (lambda) is cleaner, or missing pattern matching syntax available since 3.0.

Rule 2: Idiomatic conditionals — trailing and ternary

Prefer trailing conditionals for single-line guards:
  `return if invalid?` not `if invalid? then return end`
  `notify! unless silent?` not `if !silent? then notify! end`

Use ternary only for simple value selection:
  `status = active? ? :online : :offline`

Avoid nested ternaries — extract to a method instead.

This is the most visible Ruby idiom gap in AI output. Ruby developers read return if condition as a natural guard clause. Multi-line if/end for single conditions is considered verbose and non-idiomatic.

Rule 3: Symbols over strings for keys

Hash keys: use symbols for internal data structures.
  `{ name: "Alice", role: :admin }` not `{ "name" => "Alice", "role" => "admin" }`

String keys only when the key comes from external input (JSON parsing, HTTP params) or when
the key must be dynamic.

Use `Hash#fetch` with a default or block when the key might be absent:
  `config.fetch(:timeout, 30)` not `config[:timeout] || 30`

Symbols are immutable and memory-efficient. The || fallback for missing keys is a common bug when the value can legitimately be false or nil. fetch is the correct idiom.

Rule 4: Blocks, procs, and lambdas — use the right tool

Blocks: for one-off iteration and DSL construction (`each`, `map`, `tap`, `yield`).
Lambdas (`-> {}`): when you need to store callable behavior, check arity, or return from within.
Procs (`proc {}`): rarely — only when you explicitly need loose arity behavior.

Prefer `&method(:name)` over a block that just calls a method:
  `users.map(&method(:transform))` not `users.map { |u| transform(u) }`

Use `Symbol#to_proc` for simple field extraction:
  `names.map(&:upcase)` not `names.map { |n| n.upcase }`

AI frequently generates verbose blocks where &:method_name or &method(:name) is cleaner. These patterns are central to Ruby's functional style.

Rule 5: Enumerable over manual loops

Use Enumerable methods instead of index-based loops:
- `map` / `flat_map` for transformations
- `select` / `reject` for filtering
- `reduce` / `each_with_object` for aggregation
- `find` for first match
- `group_by`, `tally`, `chunk_while` for grouping
- `any?`, `all?`, `none?`, `count` for predicates

Never use `for` loops — use `each`.
Avoid `inject(:+)` when `sum` is available.

Ruby's Enumerable module is one of its greatest strengths. AI sometimes generates C-style index loops or nested conditionals where a chain of Enumerable methods is cleaner and more idiomatic.

Rule 6: Method visibility and attr_* macros

Use `attr_reader`, `attr_writer`, `attr_accessor` instead of manual getter/setter methods.
Mark methods private when they're implementation details — default to private, not public.
Use `protected` only for methods called by instances of the same class (rare).

Order in class body: class methods → initialize → public instance methods → private methods.
Separate sections with `private` keyword, not comments.

AI often generates explicit def name; @name; end getters. attr_reader :name is the Ruby convention. Correct visibility also matters — AI tends to leave everything public.

Rule 7: Error handling — rescue, not rescue Exception

Error handling:
- Rescue `StandardError` or specific subclasses — never `Exception`
  (`Exception` catches `SignalException`, `Interrupt`, `NoMemoryError` — almost always wrong)
- Prefer inline rescue for simple defaults: `value = risky_call rescue default_value`
  (only when the rescue is genuinely a simple fallback, not for flow control)
- Use `ensure` for cleanup, not rescue blocks
- Custom exceptions: inherit from `StandardError`, name with `Error` suffix
  `class PaymentFailedError < StandardError; end`
- Raise with a message: `raise PaymentFailedError, "Card declined: #{reason}"`

rescue Exception is a common AI mistake that catches signals and system errors, preventing clean process shutdown. Always rescue specific errors.

Rule 8: Frozen string literals

Add `# frozen_string_literal: true` at the top of every Ruby file.
This makes all string literals immutable and reduces object allocation.

When a mutable string is genuinely needed: `String.new("mutable")` or `+"mutable"`.
Use string interpolation (`"#{var}"`) over concatenation (`str + other`).
Prefer `<<` (shovel) for in-place string building only when mutation is intentional and documented.

Frozen string literals are a free performance win and a convention in modern Ruby gems. AI omits this unless specified.

Rule 9: Rails conventions (if using Rails)

If this is a Rails project:

- Fat models, thin controllers — business logic belongs in models or service objects
- Service objects in `app/services/` for operations that cross model boundaries
- Scopes over class methods for chainable queries: `scope :active, -> { where(active: true) }`
- `find_each` / `in_batches` for large dataset iteration — never `.all.each`
- Avoid N+1: use `includes`, `eager_load`, or `preload` — add Bullet gem to detect
- Strong parameters in controllers, not models
- `before_action` for authentication/authorization, not inline checks
- No raw SQL — use Arel or query interface; raw SQL only with `sanitize_sql`

Rails conventions are dense. Without explicit guidance, AI generates controllers with business logic, models with SQL injection risk, and queries that cause N+1 problems at scale.

Rule 10: Testing — RSpec conventions

Testing: RSpec with FactoryBot for fixtures.

- Describe behavior, not implementation: `describe '#charge'` not `describe 'PaymentsController line 42'`
- Use `let` and `let!` for setup — not instance variables in `before` blocks
- `subject` for the object under test
- One assertion per example (generally) — exceptions: related state changes
- `context` blocks for branching: `context 'when payment fails'`
- Shared examples for common behavior across multiple classes
- `described_class` over hardcoded class names in specs
- VCR or WebMock for external HTTP — never hit real APIs in tests

AI generates verbose, procedural RSpec that doesn't use let, nests before blocks unnecessarily, and creates brittle specs tied to implementation details.

Rule 11: Dependency injection and module composition

Prefer module mixins over inheritance for shared behavior:
  `include Auditable` not `class User < AuditableBase`

Use dependency injection for external services:
  `def initialize(mailer: UserMailer)` not `UserMailer.deliver` inside methods

Avoid monkey-patching core classes — use refinements (`refine String do`) when extension is necessary.
No `method_missing` without `respond_to_missing?`.

Ruby's module system is powerful. AI tends toward inheritance hierarchies where mixins are more flexible. Dependency injection makes testing trivial — pass a mock mailer in tests, real mailer in production.

Rule 12: Pattern matching (Ruby 3.x)

Use pattern matching for complex conditional dispatch:

  case response
  in { status: 200, body: { user: { id: Integer => id } } }
    process_user(id)
  in { status: 422, errors: [*, String => first_error, *] }
    handle_validation_error(first_error)
  in { status: (400..499) }
    handle_client_error(response)
  end

Use `in` (one-armed pattern match) for destructuring:
  `response => { user: { name:, email: } }`

Ruby 3.x pattern matching is underutilized in AI output because it's relatively new. It eliminates chains of if response[:status] == 200 && response[:body][:user] conditions.

Rule 13: Gemfile and dependency hygiene

Gemfile conventions:
- Pin major versions for stability: `gem 'rails', '~> 7.1'`
- Group gems correctly: `:development`, `:test`, `:development, :test`
- `bundle audit` before any update — check for security advisories
- No gems with `require: false` unless you manually require them
- Prefer gems with active maintenance — check last commit date on GitHub before adding
- Lock Ruby version in Gemfile: `ruby '~> 3.3'`

What goes in your CLAUDE.md

# Ruby Project — AI Coding Rules

## Runtime
Ruby 3.3+. frozen_string_literal: true on every file.

## Style
- Trailing conditionals for guards: `return if invalid?`
- Symbols for internal hash keys
- Enumerable over loops: map/select/reduce/find
- &:method_name and &method(:name) over verbose blocks

## Error Handling
rescue StandardError (specific subclasses preferred). Never rescue Exception.
Custom errors inherit StandardError, named with Error suffix.

## Architecture
attr_reader/writer/accessor over manual getters/setters.
Private by default — public only what callers need.
Service objects in app/services/ for cross-model operations.

## Rails (if applicable)
Fat models, thin controllers. Scopes for chainable queries.
find_each for large sets. includes/eager_load to prevent N+1.

## Testing
RSpec + FactoryBot. let/let! for setup. One assertion per example.
context blocks for branching. VCR/WebMock for external HTTP.

## Dependencies
bundle audit on every update. Pin major versions.

Why Ruby needs explicit rules

Ruby's design philosophy is that there are many ways to do the same thing, but idiomatic Ruby has strong preferences. AI assistants default to the most common patterns in their training data — often older Ruby or patterns from other languages.

CLAUDE.md makes the AI's behavior predictable session to session: the same idioms, the same conventions, the same patterns — whether you're working alone or with a team.

The full rules pack covering 12+ languages is at gumroad — $27.

CLAUDE.md for PHP: 13 Rules That Make AI Write Modern, Secure, Idiomatic PHP

Olivia Craft — Mon, 11 May 2026 13:00:30 +0000

If you're using Claude or another AI assistant for PHP development without a CLAUDE.md, you've seen this pattern: the AI generates working code, but it's PHP 5-era style — no type hints, mysql_* functions, procedural globals, or die() error handling.

PHP has evolved dramatically. PHP 8.x has union types, enums, fibers, named arguments, match expressions, and readonly properties. Modern PHP is a different language from what most AI training data contains. Without explicit rules, AI defaults to the lowest common denominator.

A CLAUDE.md file at your repo root tells the AI which decade you're working in. Here are the 13 rules that have the highest impact.

Rule 1: Enforce strict types on every file

Every PHP file must start with `declare(strict_types=1);` immediately after the opening tag.
No exceptions — including scripts, controllers, helpers, and test files.

Without strict_types, PHP silently coerces values. A function expecting int accepts "42" without warning. With strict types enabled, type errors throw TypeError at call time, not at some downstream point where the symptom is unrelated to the cause.

AI tends to omit this declaration unless you make it explicit.

Rule 2: PHP 8.x minimum — use modern syntax

Target PHP 8.2+. Use:
- Named arguments for clarity over positional guessing
- Match expressions instead of switch/case with break
- Nullsafe operator (?->) instead of nested null checks
- Readonly properties for immutable data
- Enums instead of class constants for finite value sets
- First-class callable syntax where it improves readability

AI often generates switch where match is cleaner, nested isset() chains where ?-> works, and class constant arrays where typed enums are correct. Specify the PHP version and the syntax you expect.

Rule 3: Type hints everywhere — no mixed, no omissions

All function parameters, return types, and class properties must have type declarations.
- Use union types (int|string) rather than omitting types
- Use intersection types when a parameter must satisfy multiple interfaces
- Use never return type for functions that always throw or exit
- Avoid `mixed` except at true boundaries (serialization input, external API payloads)
- Use `void` for methods with no meaningful return value

PHP 8 supports rich type systems. A function signature like function process($data) tells the AI nothing about intent. A signature like function process(array $data): ProcessedResult locks in both the contract and the shape.

Rule 4: No legacy database patterns

Database access: PDO with prepared statements only.
- No `mysql_*` functions (removed in PHP 7)
- No `mysqli_*` procedural API
- No raw string interpolation in SQL queries: `"SELECT * FROM users WHERE id = $id"` is forbidden
- Always use `?` placeholders or named `:param` placeholders
- Wrap PDO in a repository class — no direct PDO calls from controllers or views

SQL injection is still the most common PHP vulnerability. AI will generate raw interpolated queries if you don't prohibit them explicitly. The PDO pattern should be the only pattern in your codebase.

Rule 5: Error handling — exceptions, not die()

Error handling:
- No `or die()`, no `exit()` for flow control
- No `@` (error suppression operator) — fix the root cause instead
- Throw domain-specific exceptions that extend `\RuntimeException` or `\LogicException`
- Use `set_exception_handler()` at the application boundary, not try/catch everywhere
- Log exceptions with context (request ID, user ID, stack trace) — not bare `error_log()`

Legacy PHP code is littered with or die("connection failed"). AI perpetuates this because it's common in training data. Exceptions with structured logging are the modern pattern.

Rule 6: Dependency injection — no static state

Object construction:
- No static methods for business logic (static is acceptable for pure utility functions)
- No service locator pattern (`App::make()`, `Container::get()` inside domain classes)
- Constructor injection for required dependencies
- No `new ClassName()` inside methods — receive dependencies via constructor
- No global state: no `$_GLOBALS`, no static class properties that mutate

Static methods and service locators make code untestable and create hidden coupling. AI gravitates toward them because they're "easy." Constructor injection is the pattern that survives growth.

Rule 7: Namespaces and PSR-4 autoloading

Namespace conventions:
- All classes must be in a namespace matching the directory structure
- Follow PSR-4: `App\Http\Controllers\UserController` maps to `src/Http/Controllers/UserController.php`
- No procedural files at the root level except `index.php` (the bootstrap)
- One class per file, always
- Use Composer autoloading — no manual `require_once` chains

AI sometimes generates self-contained procedural scripts. Modern PHP is object-oriented with Composer. Make the file structure convention explicit.

Rule 8: Security defaults — output escaping and CSRF

Security rules (non-negotiable):
- All output in templates must be escaped: `htmlspecialchars($var, ENT_QUOTES, 'UTF-8')` or the framework equivalent
- CSRF tokens required on all state-mutating forms (POST, PUT, DELETE, PATCH)
- No `eval()`, no `shell_exec()`, no `system()` unless explicitly required (and reviewed)
- Passwords: `password_hash($pass, PASSWORD_ARGON2ID)` + `password_verify()`  — never MD5/SHA1
- Sessions: `session_regenerate_id(true)` after login
- File uploads: validate MIME type server-side, never trust the client-provided Content-Type

Security defaults must be stated explicitly. AI generates working code first, secure code only if you specify.

Rule 9: Array functions over loops

Prefer functional array operations over manual loops:
- `array_map()`, `array_filter()`, `array_reduce()` for collection transforms
- `array_column()` for plucking a field from a list of associative arrays
- Spread operator `[...$a, ...$b]` for merging instead of `array_merge()` in expressions
- Do not use `for ($i = 0; ...)` when `foreach` reads better
- Keep closures short — extract named functions if the closure exceeds 5 lines

This is a readability rule. Dense for loops with index arithmetic are harder to review than array_filter($users, fn($u) => $u->active). AI can write either; specify which you want.

Rule 10: Immutable value objects for domain data

Domain data:
- Use readonly classes (PHP 8.2) or readonly properties for value objects
- Value objects compare by value, not by reference — implement `equals()` if comparison is needed
- DTOs (Data Transfer Objects) must be readonly — no setters
- Money values: integer cents, never floats
- Dates: `\DateTimeImmutable` only — never mutable `\DateTime`

Mutable state is a common source of bugs. PHP 8.2 readonly classes make immutability first-class. AI defaults to mutable data unless you establish the rule.

Rule 11: Testing — PHPUnit with real assertions

Testing conventions:
- PHPUnit for unit and integration tests
- Test file: `tests/Unit/UserServiceTest.php` maps to `src/Service/UserService.php`
- No `assertTrue(true)` — every test must assert observable behavior
- Avoid mocking internal implementation — mock only external boundaries (database, HTTP, filesystem)
- Data providers for edge cases, not copy-pasted test methods
- Test names must describe behavior: `test_throws_when_email_is_invalid()` not `test1()`

AI writes tests that pass but don't catch regressions. A test that mocks everything and asserts assertTrue(true) is worse than no test — it creates false confidence.

Rule 12: Composer and package hygiene

Dependency management:
- All dependencies via Composer — no manual vendor directory manipulation
- Lock the exact PHP version in `composer.json` under `require`: `"php": "^8.2"`
- Separate `require` (production) from `require-dev` (testing, analysis tools)
- Run `composer audit` before any dependency update — check for known vulnerabilities
- No packages abandoned on Packagist without a forked/maintained alternative

AI sometimes suggests packages that are years out of maintenance. Specifying composer audit as a required step catches this automatically.

Rule 13: Logging with context — not bare strings

Logging:
- Use PSR-3 logger (Monolog or framework logger) — no bare `error_log()`
- Every log call must include context: `$logger->error('Payment failed', ['user_id' => $userId, 'amount' => $amount])`
- Log level discipline: debug (development only), info (normal operations), warning (degraded), error (failure requiring attention), critical (system down)
- No sensitive data in logs: mask card numbers, passwords, tokens before logging
- Structured logs preferred (JSON) for log aggregation

error_log("something went wrong") is useless in production. Context-rich structured logs are the difference between a 5-minute debug session and a 2-hour war room.

What goes in your CLAUDE.md

Drop this into a CLAUDE.md at your PHP project root:

# PHP Project — AI Coding Rules

## Language Version
PHP 8.2+. All files start with `declare(strict_types=1);`.

## Types
Full type declarations on all functions and properties. No `mixed` except at serialization boundaries.

## Database
PDO + prepared statements only. No raw SQL interpolation. Repository pattern.

## Security
- Output: htmlspecialchars on all user data
- Passwords: password_hash(ARGON2ID) + password_verify
- Sessions: regenerate ID after login
- CSRF tokens on all mutating forms

## Error Handling
Throw domain exceptions. No or die(), no @ suppression, no exit() for control flow.

## Architecture
Constructor injection only. No static business logic. No service locator inside domain classes.

## Testing
PHPUnit. Mock only external boundaries. Behavioral test names.

## Logging
PSR-3 with context arrays. Structured JSON preferred. Never log raw sensitive data.

Why this works

CLAUDE.md isn't configuration for the AI's personality — it's the same thing as your team's coding standards document, except the AI reads it before every session instead of once at onboarding.

The rules above fix the specific failure modes that show up most often in AI-generated PHP: legacy syntax, security shortcuts, untestable architecture, and missing type information.

Once they're in place, AI output matches what you'd expect from a senior PHP developer on your team — not a developer who learned PHP in 2009 and never updated their patterns.

The full rules pack (all stacks, team license, configuration templates) is at gumroad — $27.

CLAUDE.md for C# and .NET: 13 Rules That Make AI Write Modern, Idiomatic Production Code

Olivia Craft — Sat, 09 May 2026 13:00:50 +0000

Ask Claude Code to "add an endpoint that returns paged orders for a customer" and the output compiles. It also ignores nullable warnings, hides an async void, blocks the thread pool with .Result, wraps everything in try/catch (Exception), reaches for a static DbContext, and sprinkles IConfiguration["..."] strings like glitter. It runs fine on your laptop. It deadlocks in staging.

C# in 2026 is not the C# the model was trained on. NRTs, records, pattern matching, minimal APIs, file-scoped namespaces, and IAsyncEnumerable are table stakes. Half the model's training is .NET Framework era; half the rest is "Hello World" tutorials. A CLAUDE.md next to your .csproj is the cheapest way to drag it forward.

Get the full CLAUDE.md Rules Pack — oliviacraftlat.gumroad.com/l/skdgt. The 13 rules below are a free preview.

1. Nullable reference types on, warnings as errors

<Nullable>enable</Nullable> and <TreatWarningsAsErrors>true</TreatWarningsAsErrors> go in every .csproj for new code. Without NRTs, the model emits string parameters that secretly mean "string or null", forces you to add ?. everywhere downstream, and quietly swallows NullReferenceException at runtime.

<PropertyGroup>
  <Nullable>enable</Nullable>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <LangVersion>latest</LangVersion>
</PropertyGroup>

Annotate intent: Customer? means may be null; Customer means it never is. Don't chase warnings with ! — the null-forgiving operator is a paper-over.

2. Records for DTOs, events, and value-equal types

When the type is "data, plus equality, plus immutability", reach for record (or record struct). AI defaults to mutable classes with hand-rolled Equals/GetHashCode that drift the moment a property is added.

public sealed record OrderDto(
    Guid Id,
    Guid CustomerId,
    decimal Total,
    IReadOnlyList<OrderLine> Lines);

with-expressions handle the "modify one field" case without mutation. Use class for entities with identity and behavior (EF Core aggregates); use record for transport, requests, responses, and domain events.

3. Switch expressions over `if`/`else` chains

Pattern matching is the C# 8+ killer feature, and the model still writes if (x is Foo f && f.Bar > 0) ladders. Switch expressions are exhaustive (the analyzer flags missing cases), shorter, and read top-to-bottom.

public decimal CalculateFee(Payment p) => p switch
{
    { Method: PaymentMethod.Card, Amount: > 1000m } => p.Amount * 0.015m,
    { Method: PaymentMethod.Card }                  => p.Amount * 0.025m,
    { Method: PaymentMethod.BankTransfer }          => 0m,
    _ => throw new ArgumentOutOfRangeException(nameof(p))
};

Property patterns, list patterns, and is not null over != null — they read as English and the analyzer reasons about them.

4. `async`/`await` only — no `.Result`, no `.Wait()`, no `async void`

Task.Result and Task.Wait() deadlock under any sync context (ASP.NET legacy, WPF, WinForms) and starve the thread pool elsewhere. async void swallows exceptions and crashes the process. AI reaches for them whenever a sync interface needs to call async code; the fix is to make the interface async, not to block.

public async Task<Order> GetOrderAsync(Guid id, CancellationToken ct)
{
    var order = await _db.Orders
        .Include(o => o.Lines)
        .FirstOrDefaultAsync(o => o.Id == id, ct);

    return order ?? throw new OrderNotFoundException(id);
}

async void is reserved for event handlers. ConfigureAwait(false) in shared libraries; skip it in ASP.NET Core (no sync context to capture).

5. `CancellationToken` everywhere — propagate, don't drop

Every async method that does I/O takes a CancellationToken and passes it down. Minimal API handlers and controllers get one for free. AI omits the token and turns client disconnects into 30-second hangs.

app.MapGet("/orders/{id:guid}", async (
    Guid id,
    IOrderService svc,
    CancellationToken ct) =>
{
    var order = await svc.GetOrderAsync(id, ct);
    return Results.Ok(order);
});

Name it ct or cancellationToken, never with a default that callers ignore. EF Core, HttpClient, Stream all accept tokens — use them.

6. LINQ for transformation — but no double enumeration

LINQ is idiomatic, but IEnumerable<T> from LINQ is deferred: enumerating twice runs the source twice. Materialize with .ToList() / .ToArray() once when crossing a layer boundary. AI defaults to repeated .Count() and .Any() against the same query — on EF Core that's N extra round-trips.

var unpaid = await db.Orders
    .AsNoTracking()
    .Where(o => o.Status == OrderStatus.Pending)
    .OrderBy(o => o.CreatedAt)
    .Select(o => new OrderDto(o.Id, o.CustomerId, o.Total, o.Lines))
    .ToListAsync(ct);

if (unpaid.Count == 0) return Results.NoContent();
return Results.Ok(unpaid);

EF Core: AsNoTracking() for reads, Include deliberately, project to DTOs with Select instead of fetching whole entities. Never call .ToList() mid-query and then keep filtering — that materialises the world.

7. Dependency injection via constructor — no `Service.Instance`, no static state

Every collaborator is injected through the constructor. No HttpClient.SharedInstance, no static readonly DbContext, no ServiceLocator.Get<T>(). AI loves singletons because tests are out of scope; you live with them when those services need to be replaced for tests, integration runs, or per-tenant overrides.

public sealed class OrderService(
    AppDbContext db,
    IClock clock,
    ILogger<OrderService> logger) : IOrderService
{
    public async Task<Order> CreateAsync(CreateOrderCommand cmd, CancellationToken ct)
    {
        logger.LogInformation("Creating order for {CustomerId}", cmd.CustomerId);
        // ...
    }
}

Primary constructors keep wiring tight. Lifetimes: Scoped for request-bound work, Singleton for stateless utilities, Transient only when justified.

8. Minimal APIs with typed results — not anonymous-object soup

Minimal APIs (or controllers — pick one per project, don't mix) own routing, model binding, and validation. AI sprinkles Results.Ok(new { ... }) and anonymous types; lock it down with Results<Ok<T>, NotFound> so OpenAPI generation and client codegen actually match what you return.

app.MapGet("/orders/{id:guid}",
    async Task<Results<Ok<OrderDto>, NotFound>> (
        Guid id, IOrderService svc, CancellationToken ct) =>
    {
        var order = await svc.FindAsync(id, ct);
        return order is null
            ? TypedResults.NotFound()
            : TypedResults.Ok(OrderDto.From(order));
    })
.WithName("GetOrder")
.WithOpenApi();

Group endpoints with MapGroup, share auth and validation with IEndpointFilter, and return ValidationProblem for 400s — not by sprinkling ifs inside the handler.

9. Exceptions are specific — no `catch (Exception)` Pokémon catches

Catch the exception you can handle: DbUpdateConcurrencyException, HttpRequestException, OperationCanceledException. Anything else bubbles to the global handler. AI wraps every block in try/catch (Exception ex) { _logger.LogError(ex, ...); return null; } and you spend Friday debugging silent failures.

try
{
    await db.SaveChangesAsync(ct);
}
catch (DbUpdateConcurrencyException ex)
{
    logger.LogWarning(ex, "Concurrency conflict on {Id}", id);
    return TypedResults.Conflict();
}

Re-throw with throw; — never throw ex;, which resets the stack trace. OperationCanceledException propagates; don't swallow it, or you'll mask client cancellations as success.

10. Configuration via `IOptions<T>` — no `IConfiguration["Key"]` strings

String-keyed configuration scattered across services is untyped, untestable, and validated nowhere. Bind to a typed options class once, register with AddOptions<T>().BindConfiguration(...).ValidateDataAnnotations().ValidateOnStart(), and inject IOptions<T> (or IOptionsSnapshot<T> for reload).

public sealed class StripeOptions
{
    [Required] public string ApiKey { get; init; } = "";
    [Range(1, 60)] public int TimeoutSeconds { get; init; } = 10;
}

builder.Services
    .AddOptions<StripeOptions>()
    .BindConfiguration("Stripe")
    .ValidateDataAnnotations()
    .ValidateOnStart();

Bad config crashes startup, not the first paid request at 2 a.m.

11. Structured logging via `ILogger<T>` — message templates, not interpolation

logger.LogInformation($"User {userId} did {action}") boxes the values into a single string and destroys structured search. Use the message template form: positional placeholders, named parameters preserved as fields in JSON logs.

logger.LogInformation(
    "Order {OrderId} settled in {ElapsedMs} ms for {CustomerId}",
    order.Id, elapsed.TotalMilliseconds, order.CustomerId);

Levels: Information for business events, Warning for handled anomalies, Error for unhandled failures, Debug for noisy local-only output. No Console.WriteLine in production paths. Use LoggerMessage source generators on hot loops.

12. Tests use xUnit + FluentAssertions — and exercise the public surface

xUnit ([Fact], [Theory]), FluentAssertions for readable failures, and WebApplicationFactory<TProgram> for HTTP-level integration tests. AI writes 200 unit tests against private helpers and zero tests that boot the actual app; flip the ratio.

public class GetOrderTests(OrdersWebAppFactory factory)
    : IClassFixture<OrdersWebAppFactory>
{
    [Fact]
    public async Task Returns_404_when_order_missing()
    {
        var client = factory.CreateClient();
        var resp = await client.GetAsync($"/orders/{Guid.NewGuid()}");
        resp.StatusCode.Should().Be(HttpStatusCode.NotFound);
    }
}

Mock at the seam (IOrderService, IClock), not at DbContext. Use Testcontainers for real Postgres in CI when the schema matters. Snapshot tests for response shapes are fine.

13. Build hygiene: analyzers on, warnings on, formatting enforced

Add Microsoft.CodeAnalysis.NetAnalyzers, enable EnforceCodeStyleInBuild, drop an .editorconfig with the team's rules, and run dotnet format --verify-no-changes in CI. AI will silence analyzers with #pragma warning disable to "ship" — don't let it.

<PropertyGroup>
  <AnalysisMode>AllEnabledByDefault</AnalysisMode>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

# .editorconfig
[*.cs]
csharp_style_namespace_declarations = file_scoped:error
dotnet_style_qualification_for_field = false:warning
dotnet_diagnostic.CA1062.severity = error  # validate args in public APIs

File-scoped namespaces, ImplicitUsings, and Nullable enabled in every new project template. Suppressing analyzer rules requires a justification comment, reviewed in PR.

A starter `CLAUDE.md` snippet

# CLAUDE.md — .NET service

## Stack
- C# 13 / .NET 9, NRTs on, warnings as errors, file-scoped namespaces
- ASP.NET Core minimal APIs, EF Core, xUnit + FluentAssertions

## Hard rules
- NRTs enabled; no `!` to silence warnings; warnings = errors.
- Records for DTOs/events/value types; classes for entities and behavior.
- Switch expressions and pattern matching over `if`/`else` chains.
- async/await only. No `.Result`, no `.Wait()`, no `async void` outside event handlers.
- Every async I/O method takes and propagates `CancellationToken`.
- LINQ materialised once at layer boundaries; EF reads use `AsNoTracking`.
- Constructor DI only. No `static` state, no service locator.
- Minimal APIs return `TypedResults`; `MapGroup` + `IEndpointFilter` for shared concerns.
- Catch specific exceptions; rethrow with `throw;`; let `OperationCanceledException` bubble.
- `IOptions<T>` for config with `ValidateDataAnnotations().ValidateOnStart()`.
- Structured logging via `ILogger<T>`; message templates, not interpolation.
- Tests: xUnit, FluentAssertions, `WebApplicationFactory<T>` for HTTP tests.
- Analyzers + `dotnet format --verify-no-changes` in CI.

What Claude gets wrong without these rules

Ignores nullability, sprinkles !, ships an NRE on the first edge case.
Returns mutable classes with hand-rolled equality that breaks on the next field.
Calls .Result inside a sync wrapper and deadlocks the request pipeline.
Catches Exception, logs, returns null — silent failure, no signal.
Reads config via IConfiguration["Stripe:ApiKey"] in three different services.
Writes 200 tests for private helpers and zero tests against the real app.

Drop these 13 rules into CLAUDE.md and the next AI PR looks like a 2026 .NET service, not a 2017 ASP.NET MVC tutorial. Your CI stops failing on warnings and your staging stops deadlocking.

Want this for 20+ stacks with 200+ rules ready to paste? Grab the CLAUDE.md Rules Pack at oliviacraftlat.gumroad.com/l/skdgt.

— Olivia (@OliviaCraftLat)

CLAUDE.md for Java: 13 Rules That Make AI Write Modern, Production-Ready JVM Code

Olivia Craft — Thu, 07 May 2026 18:57:22 +0000

Java developers have a particular problem with AI assistants: the models have seen fifteen years of StackOverflow answers, legacy tutorials, and pre-Java-11 patterns. Without guidance, Claude will write new ArrayList<>() where you want List.of(), null checks where you want Optional, and raw Exception catches where you want specific error types.

A well-written CLAUDE.md fixes this. Here are 13 rules that push AI-generated Java from Java 8-era code to modern, idiomatic production Java.

1. Use modern collection factory methods

// Bad — verbose, mutable
List<String> tags = new ArrayList<>();
tags.add("java");
tags.add("api");
Map<String, Integer> codes = new HashMap<>();
codes.put("OK", 200);

// Good — Java 9+, immutable by default
List<String> tags = List.of("java", "api");
Map<String, Integer> codes = Map.of("OK", 200, "NOT_FOUND", 404);

Rule for CLAUDE.md: "Use List.of(), Set.of(), Map.of() for immutable collections. Use new ArrayList<>(List.of(...)) only when mutation is required."

2. `Optional` instead of null returns

// Bad
public User findUser(String id) {
    return userMap.get(id); // returns null if missing
}

// Good
public Optional<User> findUser(String id) {
    return Optional.ofNullable(userMap.get(id));
}

// Usage
findUser(id)
    .map(User::getEmail)
    .orElseThrow(() -> new UserNotFoundException(id));

Rule: "Never return null from public methods. Return Optional<T> for values that may be absent. Never use Optional.get() without checking — use orElse, orElseThrow, or ifPresent."

3. Records for data carriers (Java 16+)

// Bad — verbose POJO
public class OrderSummary {
    private final UUID id;
    private final int totalCents;
    // constructor, getters, equals, hashCode, toString...
}

// Good
public record OrderSummary(UUID id, int totalCents) {}

Rule: "Use record for immutable data carriers. No manual getters/setters/equals/hashCode for records. Extend with compact constructors for validation."

4. Sealed classes for closed type hierarchies (Java 17+)

// Good — exhaustive, compiler-enforced
public sealed interface PaymentResult
    permits PaymentResult.Success, PaymentResult.Failure, PaymentResult.Pending {}

public record Success(UUID transactionId) implements PaymentResult {}
public record Failure(String reason, int errorCode) implements PaymentResult {}
public record Pending(String reference) implements PaymentResult {}

// Pattern matching switch (Java 21)
String message = switch (result) {
    case Success s -> "Paid: " + s.transactionId();
    case Failure f -> "Failed: " + f.reason();
    case Pending p -> "Pending: " + p.reference();
};

Rule: "Use sealed interface + record implementations for closed domain hierarchies. Use pattern matching switch for exhaustive dispatch — no default needed."

5. Stream API over imperative loops for transformations

// Bad
List<String> result = new ArrayList<>();
for (User user : users) {
    if (user.isActive()) {
        result.add(user.getEmail().toLowerCase());
    }
}

// Good
List<String> result = users.stream()
    .filter(User::isActive)
    .map(user -> user.getEmail().toLowerCase())
    .toList(); // Java 16+ — immutable

Rule: "Use streams for filter/map/reduce/collect operations. Use .toList() (Java 16+) for immutable result lists. Reserve imperative loops for side effects."

6. Specific exception types, never raw `Exception`

// Bad
try {
    processOrder(order);
} catch (Exception e) {
    log.error("Error", e);
    throw new RuntimeException("Failed");
}

// Good
try {
    processOrder(order);
} catch (InventoryException e) {
    log.warn("Inventory check failed for order {}", order.id(), e);
    throw new OrderProcessingException("Inventory unavailable", e);
} catch (PaymentException e) {
    log.error("Payment failed for order {}", order.id(), e);
    throw new OrderProcessingException("Payment declined", e);
}

Rule: "Catch specific exception types only. Always pass the original exception as the cause. Never swallow exceptions with empty catch blocks."

7. `var` for local type inference where it improves readability

// Good — type is obvious from the right side
var users = userRepository.findAllActive();
var orderMap = new HashMap<UUID, Order>();

// Bad — type is not obvious
var result = process(data); // What type is result?

Rule: "Use var when the type is obvious from the right-hand side. Never use var for method return types or when the inferred type would be unclear to a reader."

8. Constructor injection, not field injection

// Bad — field injection (not testable without Spring context)
@Service
public class OrderService {
    @Autowired
    private OrderRepository repo;
    @Autowired
    private PaymentGateway payment;
}

// Good — constructor injection
@Service
public class OrderService {
    private final OrderRepository repo;
    private final PaymentGateway payment;

    public OrderService(OrderRepository repo, PaymentGateway payment) {
        this.repo = repo;
        this.payment = payment;
    }
}

Rule: "Constructor injection always. No @Autowired on fields. Mark injected fields final. This enables plain-Java unit tests without Spring context."

9. SLF4J with parameterized messages — never string concatenation

// Bad — allocates string even if DEBUG is off
log.debug("Processing order " + order.getId() + " for user " + userId);

// Also bad
System.out.println("Order processed: " + orderId);

// Good
private static final Logger log = LoggerFactory.getLogger(OrderService.class);
log.debug("Processing order {} for user {}", order.getId(), userId);
log.error("Payment failed for order {}", orderId, exception);

Rule: "SLF4J only — no System.out.println. Parameterized log messages ({}) always. Pass exceptions as the last argument to preserve stack traces."

10. `Instant` and `Duration` for time — never `Date` or `long` milliseconds

// Bad
long createdAt = System.currentTimeMillis();
Date expiresAt = new Date(createdAt + 86400000L);

// Good
Instant createdAt = Instant.now();
Instant expiresAt = createdAt.plus(Duration.ofDays(1));
ZonedDateTime displayTime = createdAt.atZone(ZoneId.of("America/Santiago"));

Rule: "Java Time API (java.time.*) exclusively. Instant for storage/comparison, ZonedDateTime for display, Duration/Period for intervals. Never java.util.Date or raw millisecond longs."

11. Immutability by default

// Bad — mutable everywhere
public class Config {
    public String apiKey;
    public int timeout;
}

// Good
public final class Config {
    private final String apiKey;
    private final int timeoutSeconds;

    public Config(String apiKey, int timeoutSeconds) {
        this.apiKey = Objects.requireNonNull(apiKey, "apiKey required");
        this.timeoutSeconds = timeoutSeconds;
    }

    public String apiKey() { return apiKey; }
    public int timeoutSeconds() { return timeoutSeconds; }
}

Rule: "Classes immutable by default: final class, final fields, no setters. Use Builder pattern for objects with many optional fields. Validate in the constructor with Objects.requireNonNull."

12. JUnit 5 with `@DisplayName` and Arrange-Act-Assert

// Bad
@Test
public void test1() {
    assertTrue(service.process(input) != null);
}

// Good
@Test
@DisplayName("processOrder returns SUCCESS when inventory and payment both succeed")
void processOrder_success() {
    // Arrange
    var order = OrderFixture.validOrder();
    when(inventory.check(order)).thenReturn(InStock.of(order));
    when(payment.charge(order)).thenReturn(ChargeResult.success("txn-123"));

    // Act
    var result = orderService.processOrder(order);

    // Assert
    assertThat(result).isInstanceOf(PaymentResult.Success.class);
    assertThat(((PaymentResult.Success) result).transactionId()).isEqualTo("txn-123");
}

Rule: "JUnit 5 with AssertJ assertions. @DisplayName on all tests describing the scenario. Arrange-Act-Assert structure, clearly separated. No assertTrue(x != null) — use assertThat(x).isNotNull()."

13. Checkstyle + SpotBugs + `--enable-preview` awareness

Rule: "Generated code must pass Checkstyle (Google style) and SpotBugs with no HIGH/MEDIUM bugs. When using Java 21+ preview features (--enable-preview), note the flag explicitly. Never generate deprecated API usage (Date, Vector, StringBuffer) without acknowledging it."

<!-- pom.xml -->
<plugin>
    <groupId>com.github.spotbugs</groupId>
    <artifactId>spotbugs-maven-plugin</artifactId>
    <configuration>
        <effort>Max</effort>
        <threshold>Medium</threshold>
    </configuration>
</plugin>

Your CLAUDE.md block

## Java Standards

- Target: Java 21 LTS. Use preview features only if `--enable-preview` is documented.
- Collections: `List.of()`, `Set.of()`, `Map.of()` for immutable; mutable only when needed
- No null returns from public methods — use `Optional<T>`
- `record` for immutable data carriers; `sealed interface` for closed hierarchies
- Streams for filter/map/collect; `.toList()` for immutable result (Java 16+)
- Catch specific exceptions; always chain cause; never swallow
- `var` for obvious local types only
- Constructor injection; `final` fields; no `@Autowired` on fields
- SLF4J parameterized logging; no System.out; exceptions as last log arg
- `java.time.*` only — no `java.util.Date` or raw millisecond longs
- Immutable by default: `final` class + fields, `Objects.requireNonNull` in constructor
- JUnit 5 + AssertJ; `@DisplayName`; AAA structure; no `assertTrue(x != null)`
- Code must pass Checkstyle (Google) and SpotBugs Medium threshold

These 13 rules give AI the context it needs to write Java that actually belongs in a 2026 codebase — not a 2012 tutorial. Combined with the rules for other languages, you get consistent AI behavior across your entire stack.

The CLAUDE.md Rules Pack includes 50+ production rules for Java, Python, TypeScript, Go, Rust, Swift, and more — $27 one-time.

CLAUDE.md for Python: 13 Rules That Make AI Write Idiomatic, Type-Safe Production Code

Olivia Craft — Thu, 07 May 2026 16:57:01 +0000

You've set up Claude Code or Cursor. You ask it to write a FastAPI endpoint. It comes back with dict everywhere, bare except Exception, and a function that mutates a list default argument. It works, but it's not Python — it's Python-shaped code that will hurt you in six months.

The fix is a CLAUDE.md that tells the model exactly what "good Python" means on your project. Here are 13 rules that turn AI-generated Python from plausible to production-ready.

1. Always use type hints — including `Annotated` and `TypeVar`

# Bad
def get_user(user_id):
    ...

# Good
from typing import Annotated
from uuid import UUID

UserId = Annotated[UUID, "user primary key"]

def get_user(user_id: UserId) -> User:
    ...

Rule for CLAUDE.md: "All functions must have fully annotated signatures. Use Annotated for domain-specific constraints. Define TypeVar for generic utilities."

2. Use Pydantic models, not raw dicts

Dicts are untyped bags. Pydantic models are contracts.

# Bad
def create_order(data: dict) -> dict:
    ...

# Good
from pydantic import BaseModel, Field

class OrderCreate(BaseModel):
    product_id: UUID
    quantity: int = Field(gt=0)

class OrderResponse(BaseModel):
    id: UUID
    total_cents: int

Rule: "Never use dict for structured data at function boundaries. Define Pydantic models for all request/response shapes."

3. Use `pathlib`, not `os.path`

# Bad
import os
config_path = os.path.join(os.path.dirname(__file__), "config.json")

# Good
from pathlib import Path
config_path = Path(__file__).parent / "config.json"

Rule: "pathlib.Path for all filesystem operations. Never import os.path."

4. f-strings for all string formatting

# Bad
msg = "User %s has %d items" % (name, count)
msg = "User {} has {} items".format(name, count)

# Good
msg = f"User {name} has {count} items"

Rule: "f-strings exclusively. No % formatting, no .format() calls."

5. `dataclasses` or `attrs` for data containers

When you don't need Pydantic validation, use dataclasses for lightweight containers:

from dataclasses import dataclass, field
from typing import List

@dataclass
class Pipeline:
    name: str
    steps: List[str] = field(default_factory=list)
    enabled: bool = True

Rule: "Use @dataclass for internal data containers that don't need Pydantic validation. Always use field(default_factory=...) for mutable defaults."

6. Never use mutable default arguments

This is Python's most famous footgun. AI models reproduce it constantly.

# Bad — shared across all calls
def add_item(item: str, items: list = []) -> list:
    items.append(item)
    return items

# Good
def add_item(item: str, items: list | None = None) -> list:
    if items is None:
        items = []
    items.append(item)
    return items

Rule: "No mutable default arguments ([], {}, custom objects). Use None and initialize inside the function body."

7. Proper `async`/`await` — no sync blocking in async functions

# Bad — blocks the event loop
async def fetch_data(url: str) -> bytes:
    import urllib.request
    return urllib.request.urlopen(url).read()

# Good
import httpx

async def fetch_data(url: str) -> bytes:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        response.raise_for_status()
        return response.content

Rule: "Async functions must never call blocking I/O. Use httpx.AsyncClient for HTTP, asyncio.to_thread for CPU-bound work."

8. Exception chaining with `raise X from Y`

# Bad — loses original traceback
try:
    result = db.query(sql)
except Exception:
    raise RuntimeError("Database query failed")

# Good
try:
    result = db.query(sql)
except psycopg2.Error as e:
    raise DatabaseError(f"Query failed: {sql[:100]}") from e

Rule: "Always chain exceptions with raise NewError(...) from original_error. Never use bare except Exception: raise RuntimeError(...)."

9. `logging`, never `print`

# Bad
print(f"Processing {item_id}...")
print(f"ERROR: {e}")

# Good
import logging
logger = logging.getLogger(__name__)

logger.info("Processing item", extra={"item_id": item_id})
logger.exception("Processing failed", extra={"item_id": item_id})

Rule: "No print() statements in production code. Use module-level logger = logging.getLogger(__name__). Use logger.exception() inside except blocks to capture tracebacks."

10. Virtual environments and explicit dependency pinning

Rule: "Always assume a virtual environment. Dependencies go in pyproject.toml (preferred) or requirements.txt with pinned versions. Never suggest pip install X without adding to dependency file."

# pyproject.toml
[project]
dependencies = [
    "fastapi>=0.111.0,<0.112",
    "pydantic>=2.7.0,<3",
    "httpx>=0.27.0,<0.28",
]

11. pytest fixtures over setup/teardown

# Bad
class TestUserService(unittest.TestCase):
    def setUp(self):
        self.db = create_test_db()

# Good
import pytest

@pytest.fixture
def db():
    database = create_test_db()
    yield database
    database.rollback()

def test_create_user(db: Database) -> None:
    user = create_user(db, email="test@example.com")
    assert user.id is not None

Rule: "pytest only — no unittest.TestCase. Use fixtures for setup/teardown. Test functions are plain functions, never methods."

12. Google-style docstrings, one-liners only for simple functions

def calculate_discount(price: float, rate: float) -> float:
    """Apply discount rate to price."""
    return price * (1 - rate)

def process_order(order: OrderCreate, db: Database) -> OrderResponse:
    """Create an order and return the persisted result.

    Args:
        order: Validated order input from the request body.
        db: Active database session, injected by FastAPI dependency.

    Returns:
        Persisted order with generated ID and computed totals.

    Raises:
        ProductNotFoundError: If `order.product_id` does not exist.
    """
    ...

Rule: "Google-style docstrings for public functions. One-liner for simple helpers. Never generate NumPy-style docstrings."

13. `ruff` and `mypy` are the law

Rule: "All generated code must pass ruff check (E, F, I rules) and mypy --strict. Never disable type checks with # type: ignore without a comment explaining why."

# These must pass before any code is considered done
ruff check src/
mypy src/ --strict

Suggested pyproject.toml section:

[tool.mypy]
strict = true
ignore_missing_imports = false

[tool.ruff]
select = ["E", "F", "I", "UP", "B"]

Your CLAUDE.md block

Drop this into your project's CLAUDE.md:

## Python Standards

- Type hints required on all functions; use `Annotated` for domain types
- Pydantic models for all structured data at boundaries — no raw dicts
- `pathlib.Path` for filesystem; never `os.path`
- f-strings only; no `%` or `.format()`
- `@dataclass` with `field(default_factory=...)` for mutable defaults
- No mutable default arguments — use `None` sentinel
- Async functions: no blocking I/O; use `httpx.AsyncClient`, `asyncio.to_thread`
- Exception chaining: `raise NewError(...) from original`
- `logging.getLogger(__name__)` only; no print statements
- Dependencies in `pyproject.toml` with pinned ranges
- pytest fixtures; no `unittest.TestCase`
- Google-style docstrings on public functions
- Code must pass `ruff check` and `mypy --strict`

These 13 rules push AI from "writes Python" to "writes your Python." The goal isn't to restrict the model — it's to give it enough context that it makes the right call the first time, every time.

These rules are pre-applied in the CLAUDE.md Rules Pack — 50+ production rules for Python, TypeScript, Go, Rust, Swift, and more. $27 one-time.

CLAUDE.md for Swift and iOS: 13 Rules That Stop AI From Writing Unsafe, Non-Idiomatic Apple Code

Olivia Craft — Thu, 07 May 2026 12:20:12 +0000

Ask Claude Code to "add a screen that loads a user profile and shows their orders" and the output compiles. It also strong-captures self in three closures, blocks the main thread on a network call, mutates @State from a background actor, and leaks a coordinator. Nothing crashes in the simulator. Everything crashes in TestFlight.

Swift is hostile to AI defaults: ARC, the SwiftUI lifecycle, Combine, structured concurrency, and a decade of UIKit history coexist in the same target. Half the model's training data is Objective-C, half is pre-async/await Swift, and the rest is SwiftUI tutorials that ignore actor isolation. A CLAUDE.md next to Package.swift is the cheapest way to pull it back to current Apple practice.

Get the full CLAUDE.md Rules Pack — oliviacraftlat.gumroad.com/l/skdgt. The 13 rules below are a free preview.

1. `[weak self]` in every escaping closure that touches `self`

ARC retain cycles are the canonical iOS leak, and AI writes them constantly: a closure captured by a long-lived publisher, Task, URLSession handler, or NotificationCenter observer that strongly references self. Every @escaping closure that mentions self opens with [weak self] in and unwraps via guard let self else { return }.

viewModel.$user
    .sink { [weak self] user in
        guard let self else { return }
        self.titleLabel.text = user.name
    }
    .store(in: &cancellables)

Non-escaping closures (map, filter, forEach) don't need it — capture is bounded by the call.

2. Force-unwrap `!` and `try!` are banned outside tests

user.profile!.name and try! JSONDecoder().decode(...) are the top crash signature in production iOS apps. Use guard let, if let, optional chaining, ??, or do/try/catch. Reserve ! for IBOutlet and test setup where failure is the test failing.

guard let url = URL(string: endpoint) else {
    throw APIError.invalidURL(endpoint)
}
let (data, _) = try await URLSession.shared.data(from: url)
let user = try JSONDecoder().decode(User.self, from: data)

fatalError is allowed only for genuinely impossible states, with a message explaining why.

3. `async/await` only — no completion handlers in new code

If the deployment target is iOS 15+, every new async API returns async throws or uses AsyncSequence. Completion-handler closures leak callbacks, scatter error handling, and don't compose with Task cancellation. Bridge legacy APIs once via withCheckedThrowingContinuation and never again.

func loadOrders(for userID: UUID) async throws -> [Order] {
    let request = try ordersRequest(userID: userID)
    let (data, response) = try await session.data(for: request)
    try OrdersAPI.validate(response)
    return try decoder.decode([Order].self, from: data)
}

No DispatchQueue.global().async { DispatchQueue.main.async { ... } } pyramids.

4. UI mutations run on `@MainActor`, full stop

Updating UIKit views or @State from a background context is a Swift 6 concurrency error and a flicker bug today. Annotate view models with @MainActor so the compiler enforces it. AI defaults to DispatchQueue.main.async — which works, but skips the actor isolation guarantee and breaks under strict concurrency.

@MainActor
final class OrdersViewModel: ObservableObject {
    @Published private(set) var orders: [Order] = []

    func refresh() async {
        do { orders = try await api.loadOrders() }
        catch { /* surface to UI */ }
    }
}

Heavy decoding or image work goes in a non-isolated helper (or Task.detached) and the result is awaited back on the main actor.

5. Pick the right SwiftUI property wrapper, once

@State, @StateObject, @ObservedObject, @Binding, @Environment are not interchangeable, but AI uses them as if they were:

@State — value types owned by this view.
@StateObject — reference-type view models created by this view.
@ObservedObject — view models passed in from a parent.
@Binding — two-way value bindings from a parent.
@Environment / @EnvironmentObject — dependencies injected up the tree.

struct OrdersScreen: View {
    @StateObject private var viewModel = OrdersViewModel()  // owned here

    var body: some View {
        OrdersList(viewModel: viewModel)
    }
}

struct OrdersList: View {
    @ObservedObject var viewModel: OrdersViewModel  // passed in
    var body: some View { /* ... */ }
}

Wrong wrapper = state thrown away on parent re-render, lifecycle bugs only visible in TestFlight.

6. Shared mutable state lives in an `actor`

Whenever AI writes private let queue = DispatchQueue(label: "...") to synchronize access, replace it with an actor. Locks (NSLock, os_unfair_lock) are reserved for non-async hot paths or C interop.

actor ImageCache {
    private var storage: [URL: UIImage] = [:]
    func image(for url: URL) -> UIImage? { storage[url] }
    func store(_ image: UIImage, for url: URL) { storage[url] = image }
}

Calls become await cache.image(for: url). Data races become compile errors, not Sentry alerts.

7. Errors are typed enums conforming to `LocalizedError`

throw NSError(domain: "...", code: -1) is AI that gave up. Stable error conditions get an enum case; errors that cross boundaries conform to LocalizedError so they're safe to surface in UI.

enum APIError: Error, LocalizedError {
    case invalidURL(String)
    case http(status: Int)
    case decoding(underlying: Error)

    var errorDescription: String? {
        switch self {
        case .invalidURL(let s): return "Invalid URL: \(s)"
        case .http(let code):    return "Server error (\(code))"
        case .decoding:          return "Couldn't read server response"
        }
    }
}

Callers branch on cases, not string matching.

8. Protocols + `struct` value types — inheritance is the last resort

AI loves class hierarchies — BaseViewController, BaseViewModel, AbstractRepository. Swift prefers protocol-oriented composition and value-type models. Use class only for real reference semantics (long-lived VMs, ARC observers, UIKit subclasses).

protocol OrdersRepository {
    func loadOrders(for userID: UUID) async throws -> [Order]
}

struct LiveOrdersRepository: OrdersRepository { /* ... */ }
struct StubOrdersRepository: OrdersRepository { /* tests */ }

Domain models (Order, User, Money) are struct with Codable/Equatable/Sendable where applicable.

9. SwiftUI views are small, dumb, and pure

A View body that scrolls past one screen is doing too much. Extract @ViewBuilder helpers, child views, and ViewModifiers; keep state and side effects in the view model. AI defaults to god-views with inline networking — that path produces non-deterministic previews and untestable UI.

struct OrderRow: View {
    let order: Order
    var body: some View {
        HStack {
            Text(order.title).font(.body)
            Spacer()
            Text(order.total.formatted(.currency(code: "USD")))
                .monospacedDigit()
        }
        .padding(.vertical, 8)
    }
}

No network, no @StateObject, no business logic in row views. Previews work offline.

10. UIKit interop: `UIViewRepresentable` for one widget, not whole flows

When something has to drop to UIKit (camera, mail composer, third-party SDK), wrap that one view in UIViewRepresentable or UIViewControllerRepresentable. AI wraps entire flows and reinvents navigation inside SwiftUI — that produces double nav stacks, broken back buttons, and coordinators that outlive their views.

struct ScannerView: UIViewControllerRepresentable {
    let onResult: (String) -> Void

    func makeUIViewController(context: Context) -> ScannerViewController {
        let vc = ScannerViewController()
        vc.onResult = onResult
        return vc
    }
    func updateUIViewController(_ vc: ScannerViewController, context: Context) {}
}

Coordinator types exist only when you need a delegate target — and they hold self weakly.

11. Dependency injection via initializer — no singletons, no `Resolver`

UserDefaults.standard, URLSession.shared, and homemade ServiceLocators are the AI's go-to dependencies and they make tests impossible. Inject collaborators through the initializer; default the parameter for production. Sub them out for tests and previews.

@MainActor
final class OrdersViewModel: ObservableObject {
    private let repository: OrdersRepository
    init(repository: OrdersRepository = LiveOrdersRepository()) {
        self.repository = repository
    }
}

@Environment carries cross-cutting concerns (theme, feature flags); everything else is constructor-injected.

12. Tests cover async paths with XCTest's async APIs — no `XCTestExpectation` for new code

XCTestExpectation and wait(for:timeout:) are how you tested completion handlers in 2019. New tests await directly. Use XCTUnwrap instead of !, snapshot tests for view layouts, and mock at the protocol boundary — not at URLSession.

@MainActor
final class OrdersViewModelTests: XCTestCase {
    func test_refresh_populatesOrders() async throws {
        let repo = StubOrdersRepository(orders: .sample)
        let sut = OrdersViewModel(repository: repo)

        await sut.refresh()

        XCTAssertEqual(sut.orders.count, 3)
    }
}

CI runs xcodebuild test -enableThreadSanitizer YES on a matrix including the lowest supported iOS version.

13. Build hygiene: SwiftPM, SwiftLint, strict concurrency on

Dependencies live in Package.swift, pinned to exact or up-to-next-minor versions. SwiftLint runs in a build phase with project rules. Turn on -strict-concurrency=complete before Swift 6 forces you to. AI will add CocoaPods, disable warnings, and set SWIFT_TREAT_WARNINGS_AS_ERRORS=NO "to ship" — that's how 200-warning codebases happen.

// Package.swift
.package(url: "https://github.com/apple/swift-collections", from: "1.1.0"),

# .swiftlint.yml
opt_in_rules:
  - force_unwrapping
  - implicit_return
  - explicit_init
disabled_rules:
  - line_length

Warnings are errors. Force-unwrap is a lint failure. Strict concurrency catches the @MainActor violation before TestFlight does.

A starter `CLAUDE.md` snippet

# CLAUDE.md — iOS app

## Stack
- Swift 5.10+, iOS 16+, SwiftUI primary, UIKit only via Representable
- async/await, actors, Combine for legacy publishers, SwiftPM, XCTest

## Hard rules
- `[weak self]` + `guard let self else { return }` in every escaping closure that uses self.
- No `!`, no `try!` outside tests and IBOutlets. Use `guard let` / `do try catch`.
- New async APIs are `async throws` or `AsyncSequence`. Bridge legacy via continuation once.
- All UI mutations run on `@MainActor`. Heavy work in detached tasks, await result back.
- Pick the right wrapper: `@State` value-owned, `@StateObject` view-owned VM, `@ObservedObject` injected VM.
- Shared mutable state = `actor`. Locks only for non-async hot paths.
- Errors are typed enums conforming to `LocalizedError`. No `NSError(domain:)`.
- Protocols + `struct` first. `class` only for reference semantics.
- SwiftUI views: small, pure, no network, previews must work offline.
- UIKit via `UIViewRepresentable` for one widget, not whole flows.
- DI via initializer. No singletons, no service locators.
- Tests use async/await, `XCTUnwrap`, mock at protocol boundary, ThreadSanitizer in CI.
- SwiftPM only. SwiftLint enforced. Strict concurrency on. Warnings = errors.

What Claude gets wrong without these rules

Strong-captures self in Combine sinks → view models leak forever.
Force-unwraps decoded JSON → first malformed payload crashes the app.
Updates @Published from a URLSession callback → flickers, Swift 6 errors.
Uses @ObservedObject instead of @StateObject → state resets on parent rerender.
Wraps a UIKit flow in UIViewControllerRepresentable → double back buttons.
Reaches for URLSession.shared everywhere → repository is impossible to test.

Drop the 13 rules above into CLAUDE.md and the next AI PR looks like an iOS app, not a SwiftUI tutorial. TestFlight stops paging you.

Want this for 20+ stacks with 200+ rules ready to paste? Grab the CLAUDE.md Rules Pack at oliviacraftlat.gumroad.com/l/skdgt.

— Olivia (@OliviaCraftLat)

CLAUDE.md for TypeScript and Node.js: 13 Rules That Make AI Write Type-Safe, Production-Ready Code

Olivia Craft — Thu, 07 May 2026 10:15:17 +0000

CLAUDE.md for TypeScript and Node.js: 13 Rules That Make AI Write Type-Safe, Production-Ready Code

TypeScript exists to catch bugs the compiler can prove. Node.js exists to ship them to production fast. When you let an AI assistant write either, the default output drifts toward any, untyped Express handlers, and validation skipped at the boundary "for now." It compiles. It runs. It explodes when a string shows up where a number was expected.

A CLAUDE.md at the repo root fixes this. It's the file Claude Code reads on every session — the contract that says: this codebase does not accept loose types, throw strings, or trust req.body. Below are 13 rules I've shipped in production TypeScript repos that make AI-generated code merge-ready instead of review-ready.

1. Strict TypeScript config is non-negotiable

Problem: AI defaults to permissive tsconfig.json and silently leans on implicit any.

CLAUDE.md instruction:

tsconfig.json MUST have "strict": true, "noImplicitAny": true, "noUncheckedIndexedAccess": true, and "exactOptionalPropertyTypes": true. Never relax these flags to make code compile. If a flag fights you, fix the type, not the config.

Why it works: Strict mode is the contract. Once Claude knows it can't escape via implicit any or unchecked array access, it generates type guards and narrowing logic up front instead of leaving holes you discover at 2 AM.

2. Ban `any` — use `unknown` plus type guards

Problem: When Claude doesn't know a shape, it reaches for any. That single keyword erases every type guarantee downstream.

CLAUDE.md instruction:

any is forbidden. Use unknown for values of unknown shape and narrow with type guards (typeof, in, custom predicates) or zod parsing. The only acceptable any is in a // @ts-expect-error block with a written justification.

Why it works: unknown forces the next reader (or AI iteration) to prove the shape before using it. Type guards become the documentation. The codebase stops accumulating silent escape hatches.

3. Branded types for IDs

Problem: function transfer(from: string, to: string, amount: number) — AI happily swaps from and to because the compiler sees three primitives, not three roles.

CLAUDE.md instruction:

All entity IDs must be branded types: type UserId = string & { readonly __brand: "UserId" }. Construct via a single toUserId() factory. Never pass raw strings to functions expecting an ID. Same rule for currency amounts, timestamps, and slugs.

Why it works: Branded types are zero-cost at runtime but make ID-swap bugs uncompilable. Claude follows the pattern once it sees one branded type defined — it'll brand new IDs without being asked.

4. `async/await` only — no Promise chains

Problem: AI freely mixes .then() chains with await, producing code where error paths and return values diverge between styles in the same file.

CLAUDE.md instruction:

Use async/await exclusively. No .then(), .catch(), or .finally() chains in application code. The only exception is Promise.all / Promise.allSettled for concurrency. Errors propagate via try/catch, not .catch() callbacks.

Why it works: One async style means one error-handling story. Stack traces become readable. Refactors stop introducing race conditions where a .then() was missed.

5. Validate inputs with zod at every boundary

Problem: AI trusts incoming data because TypeScript types are erased at runtime. req.body is typed as your DTO, but it's actually whatever the client sent.

CLAUDE.md instruction:

Every external input — HTTP requests, environment variables, JSON files, message queue payloads — must be parsed through a zod schema at the boundary. The parsed result is the only typed value that flows inward. No casting req.body as CreateUserDto.

Why it works: zod gives you the type AND the runtime check from one declaration. Once Claude sees a CreateUserSchema.parse(req.body) pattern, it replicates it on every new endpoint instead of trusting incoming JSON.

6. Typed errors, never thrown strings

Problem: throw "user not found" — Claude does this when it's in a hurry. Catch blocks then need String(err) everywhere and the caller can't distinguish a NotFound from a Forbidden.

CLAUDE.md instruction:

Errors must be class instances extending a base AppError with a discriminant code field. Never throw a string, number, or plain object. Catch blocks narrow on err instanceof AppError and switch on code. Unknown errors rethrow.

Why it works: Typed errors give you exhaustiveness checks in switch statements. Logging becomes structured. The HTTP layer maps code → status without sniffing error messages with regex.

7. Barrel exports — use sparingly

Problem: AI loves index.ts files re-exporting everything. They look tidy but break tree-shaking and create circular dependency landmines.

CLAUDE.md instruction:

No barrel index.ts files inside feature modules. Import from the specific file: import { User } from "./user/user.entity", not from "./user". The only barrels allowed are at package boundaries (packages/*/src/index.ts) and must be manually curated, not auto-generated.

Why it works: Direct imports keep the dependency graph shallow and make circular imports a compile error you can locate. Bundlers ship less code. Refactors don't cascade through unrelated modules.

8. Validate environment variables at boot

Problem: process.env.DATABASE_URL! — that ! is a lie. AI uses it because it shuts the compiler up. The app boots, reaches for the URL during the first request, and crashes with undefined is not a function.

CLAUDE.md instruction:

All environment access goes through a single env.ts module that parses process.env with zod at startup and exits the process if validation fails. No process.env.X references anywhere else in the codebase. No non-null assertions on env vars.

Why it works: The app fails to start instead of failing in production. The schema is the documentation of what your service needs. New team members (and Claude) can see the full env contract in one file.

9. Tests use real types — no `ts-ignore`

Problem: AI reaches for // @ts-ignore in tests when mocking gets awkward. The test passes, the production type drifts, and the test no longer proves anything.

CLAUDE.md instruction:

Test files must compile under the same strict config as production code. No @ts-ignore, no as any, no as unknown as Foo. Use proper test factories that return correctly typed fixtures. If a mock is hard to type, the production interface is wrong.

Why it works: Tests become a second pass of type-checking against your real shapes. When a refactor breaks a test type, you caught a real regression before runtime did.

10. Explicit return types on exported functions

Problem: Claude relies on inference, which means changing an internal helper silently changes the public API of a module.

CLAUDE.md instruction:

All exported functions, route handlers, and class methods must declare explicit return types. Inference is allowed only for local variables and arrow callbacks. Async functions return Promise<T> explicitly, not Promise<void> by accident.

Why it works: Explicit return types lock the contract. A change inside the function body that would alter the inferred return becomes a compile error at the signature, where the breaking change is visible in code review.

11. Dependency injection over direct imports

Problem: import { db } from "./db" inside business logic. Now every test needs to mock the module system, and swapping the database in staging means editing application code.

CLAUDE.md instruction:

Business logic receives dependencies via constructor parameters or function arguments — never imported directly. Side-effect modules (db, http clients, loggers, clocks) are wired in main.ts / server.ts. Domain functions take typed interfaces, not concrete implementations.

Why it works: Tests pass in fakes without jest.mock gymnastics. The dependency graph becomes explicit in function signatures. Claude stops generating code that's only testable via runtime monkey-patching.

12. Typed request and response in Express/Fastify

Problem: app.post("/users", (req, res) => { const body = req.body; ... }) — body is any. AI proceeds as if it weren't.

CLAUDE.md instruction:

Every route handler must declare typed Request and Response generics (Express: Request<Params, ResBody, ReqBody, Query>; Fastify: schema-typed routes). Bodies, params, and queries are parsed through zod inside the handler. res.json() payloads are constrained by the response type.

Why it works: The HTTP boundary stops being a type hole. Auto-generated OpenAPI docs (via zod-to-openapi or TypeBox) become trustworthy. Frontend clients consuming the API get end-to-end type safety.

13. Path aliases instead of `../../../../`

Problem: AI generates import { foo } from "../../../../utils/foo" because that's what the file system suggests. Move the file once and every import breaks.

CLAUDE.md instruction:

Use tsconfig.json paths aliases for cross-feature imports: @/lib/*, @/features/*, @/shared/*. Relative imports allowed only within the same feature folder (max one ../). Configure tsc-alias or your bundler so the aliases resolve at build time.

Why it works: Aliases survive refactors. Imports become readable. The visual depth of ../../../.. no longer hides architectural problems — when you see a cross-feature import, you can name the boundary it crosses.

The pattern

These 13 rules share one premise: TypeScript's value is the contract, not the syntax. AI assistants will happily satisfy the syntax and break the contract. CLAUDE.md is where you write down the contract in language the AI reads on every session, so it stops "helpfully" reaching for any, as, !, and @ts-ignore to make red squiggles disappear.

Drop these rules into your repo, watch the next AI-generated PR, and notice what doesn't show up: untyped handlers, unvalidated bodies, swapped IDs, and process.env.WHATEVER! scattered across the codebase.

Want the full Gist with these 13 rules ready to paste into your project? Grab it here → oliviacraftlat.gumroad.com/l/skdgt

Free, no email gate, MIT-licensed. Fork it, adapt it, ship it.

CLAUDE.md for Rust: 13 Rules That Make AI Write Safe, Idiomatic Systems Code

Olivia Craft — Thu, 07 May 2026 08:25:58 +0000

Ask Claude Code to "add a small async cache to this crate" and the default output looks fine: a tokio::spawn, an Arc<Mutex<HashMap<...>>>, a .unwrap() on the lock, a ? that flattens five error types into Box<dyn Error>. It compiles. It passes cargo test. Then it deadlocks across .await, panics on the first miss in prod, and the error reads Custom { kind: Other, error: "..." }.

The borrow checker stops a lot, but it doesn't stop unwrap(), fire-and-forget tasks, or unsafe blocks with no // SAFETY: comment. A CLAUDE.md next to Cargo.toml is the cheapest leverage you have on a Rust codebase.

Get the full CLAUDE.md Rules Pack — oliviacraftlat.gumroad.com/l/skdgt. The 13 rules below are a free preview.

1. Own at the API boundary, borrow inside

The most common AI mistake in Rust public APIs is leaking lifetimes: pub fn parse<'a>(s: &'a str) -> Doc<'a> when the caller wants an owned Doc. Public signatures take and return owned types (String, Vec<T>, PathBuf); borrowing stays inside the impl.

// ✅ owned in, owned out — caller lifetimes don't leak in
pub fn parse(input: &str) -> Result<Doc, ParseError> { ... }

// ❌ AI default — every caller now juggles 'a
pub fn parse<'a>(input: &'a str) -> Result<Doc<'a>, ParseError<'a>> { ... }

Use Cow<'_, str> only when the zero-copy path actually matters and you've measured. Default: String.

2. Errors: `thiserror` for libraries, `anyhow` for binaries

Libraries return a typed enum deriving thiserror::Error — #[from] for transparent conversion, #[source] for chains. Binaries return anyhow::Result<T> with .with_context(|| ...)? at every I/O boundary. Mixing them — anyhow in lib.rs, Box<dyn Error> elsewhere — strips callers of any way to branch on the error.

#[derive(Debug, thiserror::Error)]
pub enum StoreError {
    #[error("user {0} not found")]
    NotFound(i64),
    #[error("database error")]
    Db(#[from] sqlx::Error),
}

fn main() -> anyhow::Result<()> {
    Store::open(&path).with_context(|| format!("opening {path:?}"))?;
    Ok(())
}

No Box<dyn Error> in pub signatures.

3. `unsafe` is forbidden by default — opt in with `// SAFETY:`

#![deny(unsafe_code)] lives at every crate root. When a module genuinely needs unsafe, scope it with #![allow(unsafe_code)] at the top of that file only. Every unsafe { ... } block has a // SAFETY: comment explaining which invariants hold; every unsafe fn documents its preconditions in a # Safety doc section.

// SAFETY: `ptr` came from `Box::into_raw` above, untouched since; non-null,
// properly aligned, and we own the allocation.
let value = unsafe { Box::from_raw(ptr) };

Hard to write the comment? The unsafe is wrong.

4. No `unwrap()` or `expect()` in production paths

unwrap() is a panic with no message. CI greps for \.unwrap and \.expect\( on *.rs outside tests/, examples/, benches/ and fails the build. expect("...") is allowed only when the message documents an invariant the type system can't express — "checked above by the regex match," not "should never fail."

// ❌
let port: u16 = std::env::var("PORT").unwrap().parse().unwrap();

// ✅
let port: u16 = std::env::var("PORT")
    .context("PORT must be set")?
    .parse().context("PORT must be a u16")?;

Library code: return a typed error. Binaries: anyhow it.

5. No `panic!`, `todo!`, `unimplemented!` reachable from `pub` APIs

Library code returns Result; it does not panic for runtime conditions. todo!() and unimplemented!() are scaffolding — CI fails if any reach a pub item. Indexing user-controlled offsets panics on miss — prefer .get(i).

fn first_word(s: &str) -> &str { s.split_whitespace().next().unwrap() }     // ❌
fn first_word(s: &str) -> Option<&str> { s.split_whitespace().next() }      // ✅

Untrusted integer math uses checked_*/saturating_*/wrapping_* explicitly — debug-only overflow checks are not a security boundary.

6. Async: one runtime, no `Mutex` guard across `.await`

One async runtime per process — tokio, multi-thread for servers, current_thread for CLIs and tests. Never hold a std::sync::Mutex guard across .await: the compiler may not catch it; the runtime deadlock will. Use tokio::sync::Mutex when the guard must span an await, or restructure to drop it first.

// ❌ blocks the runtime, can deadlock
let g = state.lock().unwrap();
let row = db.fetch(g.id).await?;

// ✅ scope the std lock, then await
let id = { state.lock().unwrap().id };
let row = db.fetch(id).await?;

Spawned tasks keep their JoinHandle and are awaited or aborted on shutdown. Long loops honor cancellation via tokio::select!.

7. Logging is `tracing`, structured, never `println!`

println! and eprintln! are forbidden in library code. Use tracing with structured fields and #[tracing::instrument(skip(secrets))] on functions whose arguments include credentials or large payloads. Levels: debug opt-in, info steady state, warn needs human follow-up, error pages someone.

#[tracing::instrument(skip(pool), fields(user_id = %id))]
async fn charge(pool: &PgPool, id: i64, amount: Money) -> Result<(), ChargeError> {
    tracing::info!(?amount, "charging user");
    Ok(())
}

JSON output in production. Never log secrets or PII — #[serde(skip)] secret fields, redact at the boundary.

8. Module visibility is intentional — `pub` is a contract

pub items are part of the crate's semver contract. Default everything to private; promote to pub(crate) when another module needs it; mark pub only what you commit to keeping. AI defaults to pub on every new fn and struct — every refactor becomes a breaking change.

pub(crate) fn normalize_path(p: &Path) -> PathBuf { ... }  // ✅ scoped
pub struct Config { ... }                                  // ✅ semver applies
pub fn internal_helper(x: &str) -> String { ... }          // ❌ accidental commitment

Re-export the public surface from lib.rs. Module trees are implementation detail.

9. Custom error types — `Display` reads like a sentence

A typed error enum lives close to the type that produces it. Its Display is one short lowercase sentence — no trailing period, no leading "Error:" — tracing and anyhow frame it. Never match on error strings; the type system is right there.

#[derive(Debug, thiserror::Error)]
pub enum ConfigError {
    #[error("config file not found at {0}")]
    Missing(PathBuf),
    #[error("invalid TOML in {path}: {source}")]
    Parse { path: PathBuf, #[source] source: toml::de::Error },
}

Branch with if let ConfigError::Missing(p) = err, never err.to_string().contains(...).

10. Tests: unit inside the module, integration in `tests/`

Unit tests live in a #[cfg(test)] mod tests { use super::*; ... } block — they touch private items. Integration tests live in tests/; each tests/foo.rs is a separate crate that imports only the public API. That split catches "I made it pub(crate) but the integration test can't see it" before the user does.

// src/parse.rs
#[cfg(test)]
mod tests {
    use super::*;
    #[test] fn empty_input() { assert!(tokenize("").is_empty()); }
}

// tests/end_to_end.rs — only public API
use mycrate::parse;
#[test] fn parses_a_real_doc() { parse(SAMPLE).unwrap(); }

Async tests use #[tokio::test]. Repository tests run against a real database via testcontainers — mocked queries pass while broken SQL ships. CI runs cargo test with and without --all-features so feature-gated code compiles both ways.

11. `clippy::pedantic` clean, no blanket `#[allow]`

Crate root: #![warn(clippy::pedantic, clippy::nursery, missing_docs, rust_2018_idioms)]. CI runs cargo clippy --all-targets --all-features -- -D warnings and cargo fmt -- --check. Warnings are errors. No blanket #[allow] — narrow allows on the offending item only, with a comment explaining why.

// ✅ scoped, justified
#[allow(clippy::cast_possible_truncation)] // bounded above by MAX_FRAME (u32::MAX)
fn frame_index(offset: u64) -> u32 { (offset / FRAME) as u32 }

Can't justify it in a sentence? Fix the code.

12. Workspace structure: thin binary, fat library, one `Cargo.lock`

An 800-line src/main.rs is an AI smell. The library does the work and exposes a typed API; the binary parses arguments, builds config, and calls the library. Multi-crate workspaces share one Cargo.lock at the root and pin shared deps under [workspace.dependencies] so members can't drift.

# Cargo.toml (workspace root)
[workspace]
members  = ["crates/core", "crates/cli", "crates/wasm"]
resolver = "2"

[workspace.dependencies]
tokio   = { version = "1", default-features = false, features = ["rt-multi-thread", "macros"] }
serde   = { version = "1", features = ["derive"] }
tracing = "0.1"

Library crates set default-features = false on every dep. WASM targets gate Instant, threads, and blocking I/O behind #[cfg(not(target_arch = "wasm32"))].

13. Docs with examples that compile

Every pub item carries a /// summary on the first line. Functions returning Result document # Errors; functions that can panic document # Panics. Every pub fn has a # Examples block — cargo test --doc runs it. Doc-tests are the canary for API drift.

/// Parses a TOML config file from `path`.
///
/// # Errors
/// [`ConfigError::Missing`] if `path` doesn't exist;
/// [`ConfigError::Parse`] if the file is not valid TOML.
///
/// # Examples
/// ```
{% endraw %}

/// # use mycrate::{load_config, ConfigError};
/// let cfg = load_config("examples/sample.toml")?;
/// assert_eq!(cfg.port, 8080);
/// # Ok::<(), ConfigError>(())
///
{% raw %}

pub fn load_config(path: impl AsRef) -> Result { ... }




CI runs `cargo doc --no-deps -- -D warnings`. Missing docs and broken intra-doc links fail the build.

## A starter `CLAUDE.md` snippet



```markdown
# CLAUDE.md — Rust crate

## Stack
- Rust stable, edition 2021, MSRV pinned in `Cargo.toml`
- thiserror, anyhow, tokio, tracing, sqlx, testcontainers

## Hard rules
- Public APIs take/return owned types. Borrow inside the impl.
- Libs: `thiserror` enum errors. Bins: `anyhow::Result` + `.context(...)`.
- `#![deny(unsafe_code)]` at crate root. `unsafe` blocks need `// SAFETY:`.
- No `unwrap()`/`expect()` outside tests. CI greps and fails.
- No `panic!`/`todo!`/`unimplemented!` reachable from `pub` APIs.
- One async runtime. Never hold `std::sync::Mutex` across `.await`.
- `tracing` for logging, JSON in prod. No `println!` in libs.
- Default-private. `pub(crate)` before `pub`. `pub` = semver commitment.
- Unit tests in-module, integration in `tests/`. Real DB via testcontainers.
- `cargo clippy --all-targets --all-features -- -D warnings` clean.
- Thin binary, fat library. One `Cargo.lock` at workspace root.
- Every `pub` item: `///` summary, `# Errors`/`# Panics`/`# Examples`.

What Claude gets wrong without these rules

unwrap() and Box<dyn Error> everywhere — every error becomes a string.
std::sync::Mutex guard held across .await — runtime deadlock.
tokio::spawn with no JoinHandle — tasks outlive the request.
Every new fn marked pub — every refactor breaks semver.
unsafe blocks with no // SAFETY: and stale assumptions.

Drop the 13 rules above into CLAUDE.md and the next AI PR looks like the codebase, not a tutorial. cargo clippy -- -D warnings stays green.

Want this for 20+ stacks with 200+ rules ready to paste? Grab the CLAUDE.md Rules Pack at oliviacraftlat.gumroad.com/l/skdgt.

— Olivia (@OliviaCraftLat)