agentleFS
dmmulroydmmulroy/skills/coding-standards/SKILL.md

coding-standards

Skill428 starsChanged 4 months agoMITView on GitHub

Correct-by-construction TypeScript standards. Use for TypeScript engineering or when another skill needs the user's coding standards.

  • Reads credentials

127 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use everything-claude-code, everything-claude-code-conventions and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • InfopibeSkill

    everything-claude-code

    Also in 9 projects that use this

  • mryeastcodeSkill

    everything-claude-code-conventions

    Development conventions and patterns for everything-claude-code. JavaScript project with conventional commits.

    Also in 8 projects that use this

  • niloykumarbarmanSkill

    agent-sort

    Build an evidence-backed ECC install plan for a specific repo by sorting skills, commands, rules, hooks, and extras into DAILY vs LIBRARY buckets using parallel repo-aware review passes. Use when ECC should be trimmed to what a project actually needs instead of loading the full bundle.

    Also in 8 projects that use this

  • tpavanipradeepSkill

    nextjs-turbopack

    Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.

    Also in 15 projects that use this

  • CodeWithBehnamSkill

    dmux-workflows

    Multi-agent orchestration using dmux (tmux pane manager for AI agents). Patterns for parallel agent workflows across Claude Code, Codex, OpenCode, and other harnesses. Use when running multiple agent sessions in parallel or coordinating multi-agent development workflows.

    Also in 17 projects that use this

  • InfopibeSkill

    investor-outreach

    Draft cold emails, warm intro blurbs, follow-ups, update emails, and investor communications for fundraising. Use when the user wants outreach to angels, VCs, strategic investors, or accelerators and needs concise, personalized, investor-facing messaging.

    Also in 22 projects that use this

  • +1 more from Infopibe

The file

Show its rules and text

We split this skill into the rules it gives an agent

83 rules. 0 are common, 63 are distinctive, and 20 are very specific to this project.

  • 0

    Common

    Most of the 111 edited versions we read keep these.

  • 63

    Distinctive

    This author's own choices. Worth a look.

  • 20

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When rules pull in different directions, use this order:

    line 9
  2. Distinctive:

    Follow compatible project architecture and conventions.

    line 13
  3. Distinctive:

    Avoid changing unrelated old code unless a broader migration is explicitly requested.

    line 15
  4. Distinctive:

    Document meaningful trade-offs with comments or ADRs.

    line 16
  5. Very specific:

    Prefer errors as values over throw / rejected promises for expected failures.

    line 20
  6. Distinctive:

    Prefer correct-by-construction APIs over convention-based invariants.

    line 23
  7. Very specific:

    Use branded/refined/domain types when they prevent a realistic mistake, such as mixing identifiers or units, bypassing parsing, or …

    line 24
  8. Distinctive:

    Prefer composition over inheritance.

    line 25
  9. Distinctive:

    Prefer imperative shell / functional core.

    line 26
  10. Distinctive:

    Test behavior through real seams.

    line 28
  11. Distinctive:

    Keep code discoverable for humans and agents.

    line 29
  12. Distinctive:

    Before adding a new pattern or library, inspect the repo for existing choices around:

    line 33
  13. Distinctive:

    Use established shared defect helpers where available, or the panic helper from the project's result library:

    line 92
  14. Very specific:

    Use casesHandled for exhaustive union handling.

    line 100
  15. Distinctive:

    Keep error unions precise at module boundaries:

    line 134
  16. Very specific:

    Avoid broad AppError-style types except near entrypoints, orchestration, logging, and rendering layers.

    line 140
  17. Distinctive:

    Prefer end-to-end structured tracing across requests, jobs, workflows, application modules, adapters, and external calls.

    line 144
  18. Distinctive:

    Do not put secrets in errors, traces, logs, or snapshots.

    line 156
  19. Very specific:

    Use a Redacted<T> wrapper for sensitive values such as tokens, API keys, passwords, raw credentials, and secrets.

    line 158
  20. Distinctive:

    Do not pass a schema-inferred transport shape throughout the application:

    line 178
  21. Distinctive:

    Use names that preserve meaning:

    line 184
  22. Very specific:

    Avoid validateX when the function returns a refined value.

    line 191
  23. Distinctive:

    Use schema libraries as boundary parsers, not as ad-hoc validators sprinkled through core logic.

    line 195
  24. Distinctive:

    use the repo's established schema library if one exists

    line 199
  25. Distinctive:

    use Effect Schema in Effect codebases

    line 200
  26. Distinctive:

    prefer Standard Schema compatibility for generic helpers

    line 201
  27. Distinctive:

    use hand-written smart constructors/parsers for small domain types when clearer

    line 203
  28. Distinctive:

    Use branded/refined types when they prevent realistic misuse or invalid construction, especially for:

    line 209
  29. Very specific:

    Avoid optional/null/undefined values in functions that require a value.

    line 218
  30. Very specific:

    Avoid Partial<T> as an application/domain input unless partiality is the real domain concept.

    line 220
  31. Distinctive:

    When an entity has meaningful lifecycle states, model them with tagged unions or equivalent value classes.

    line 224
  32. Distinctive:

    Avoid boolean parameters that control behavior:

    line 246
  33. Distinctive:

    Prefer named options or domain types:

    line 252
  34. Distinctive:

    Only construction, configuration, or resource wiring changes: composition root.

    line 293
  35. Distinctive:

    Put intrinsic meanings, invariants, calculations, and transitions in Domain Modules.

    line 302
  36. Distinctive:

    Put application policy and effect ordering in an Application Service.

    line 303
  37. Distinctive:

    Put each protocol or technology translation in an inbound or outbound Adapter.

    line 304
  38. Distinctive:

    Verify each role through its public seam: domain results, application outcomes, and boundary records/responses.

    line 306
  39. Distinctive:

    Avoid shallow abstractions that merely forward calls, mirror tables, rename another API, or expose implementation steps.

    line 316
  40. Distinctive:

    Use the deletion test:

    line 318
  41. Distinctive:

    if deleting the module makes complexity disappear, it was probably pass-through waste

    line 320
  42. Distinctive:

    if deleting it spreads complexity across callers, it was probably earning its keep

    line 321
  43. Distinctive:

    Use one when the code has a meaningful domain distinction, invariant, calculation, decision, or lifecycle.

    line 327
  44. Distinctive:

    keep fields readonly/immutable from callers

    line 360
  45. Distinctive:

    keep methods cohesive over that value

    line 361
  46. Distinctive:

    do not hide dependencies or I/O inside domain value classes

    line 362
  47. Distinctive:

    avoid inheritance for domain behavior

    line 363
  48. Distinctive:

    Use one when an operation must coordinate authorization, domain decisions, persistence, external calls, transactions, messages, time, IDs, …

    line 369
  49. Distinctive:

    Before creating a new adapter or service, agents must audit existing adapters/services.

    line 430
  50. Distinctive:

    Create a new adapter only when reuse/extension would create bad coupling or an accidental interface.

    line 436
  51. Distinctive:

    Do not require an ADR for a routine feature-level Adapter or Application Service.

    line 438
  52. Distinctive:

    Avoid repository-per-table by default.

    line 446
  53. Distinctive:

    Treat raw database rows and ORM models as infrastructure DTOs.

    line 450
  54. Distinctive:

    Use ordinary function calls or database transactions for simple single-boundary operations.

    line 469
  55. Distinctive:

    Use a saga or durable workflow when progress must survive process loss or redelivery, or when the operation requires long delays, …

    line 471
  56. Distinctive:

    Do not hold database transactions open across network calls or long-running operations.

    line 475
  57. Distinctive:

    Add an end-to-end test whenever the behavior can be exercised through its real public entrypoint in the normal test environment without …

    line 489
  58. Very specific:

    Never use vi.mock or jest.mock for module mocking.

    line 498
  59. Distinctive:

    Prefer tests that assert observable input/output behavior:

    line 506
  60. Very specific:

    Avoid spy-driven tests like expect(sendEmail).toHaveBeenCalledWith(...) unless the interaction itself is the only observable behavior.

    line 514
  61. Very specific:

    Use fast-check where properties are clearer than examples, especially for:

    line 520
  62. Distinctive:

    Use arbitraries for mock/test data generation.

    line 529
  63. Distinctive:

    Use strict TypeScript settings where practical:

    line 542
  64. Very specific:

    Do not use !. Branch, parse, or refine instead.

    line 587
  65. Very specific:

    Prefer direct imports from the file that owns the abstraction.

    line 591
  66. Distinctive:

    Use named imports for classes and focused shared helpers:

    line 601
  67. Very specific:

    Use import type / export type for type-only imports and exports.

    line 607
  68. Very specific:

    Avoid TypeScript namespace unless there is a compelling interop reason.

    line 611
  69. Distinctive:

    Keep only helpers justified by the target project.

    line 641
  70. Distinctive:

    No arbitrary file-size limits.

    line 643
  71. Very specific:

    Do not use @inheritDoc, @inherit, or similar inheritance tags.

    line 651
  72. Distinctive:

    Use standard JSDoc syntax:

    line 653
  73. Very specific:

    Use @throws only for unrecoverable defects, framework-required behavior, or temporary notYetImplemented paths.

    line 681
  74. Very specific:

    Do not read process.env throughout the app.

    line 700
  75. Distinctive:

    Avoid top-level side effects except in true entrypoint/bootstrap files.

    line 702
  76. Distinctive:

    Avoid mutable singletons/global state.

    line 706
  77. Distinctive:

    Read existing conventions for errors, schemas, tests, adapters, telemetry, and module layout.

    line 714
  78. Very specific:

    Avoid raw DTOs, raw IDs, nullable bags, and Partial<T> in core/application logic.

    line 719
  79. Distinctive:

    Prefer typed errors as values for new expected failures.

    line 720
  80. Distinctive:

    Test through public interfaces and real seams.

    line 722
  81. Very specific:

    Use fast-check arbitraries for generated test data when practical.

    line 723
  82. Distinctive:

    Add JSDoc for exported symbols.

    line 724
  83. Distinctive:

    Add an ADR only for a lasting architectural boundary, shared pattern, provider strategy, or deliberate exception discovered through the …

    line 725

“Common” is measured: kept by at least 6 in 10 of the 111 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

These standards describe how to design and write TypeScript code in this codebase. They are especially intended for agents: inspect existing code before adding patterns, libraries, Adapters, or abstractions, but apply these standards to all new and refactored behavior. Follow existing conventions only when they are compatible with these standards.

Decision priority

When rules pull in different directions, use this order:

  1. Preserve correctness, safety, and debuggability.
  2. Apply these standards to all new code and to the full behavior being refactored.
  3. Follow compatible project architecture and conventions.
  4. Contain incompatible existing patterns at the nearest boundary rather than copying them into new code.
  5. Avoid changing unrelated old code unless a broader migration is explicitly requested.
  6. Document meaningful trade-offs with comments or ADRs.

Core principles

  • Prefer errors as values over throw / rejected promises for expected failures.
  • Parse don't validate. Parse early and as close to composition or application roots as possible. Do not merely validate and throw away the information learned.
  • Make illegal states unrepresentable where practical.
  • Prefer correct-by-construction APIs over convention-based invariants.
  • Use branded/refined/domain types when they prevent a realistic mistake, such as mixing identifiers or units, bypassing parsing, or constructing an invalid value.
  • Prefer composition over inheritance.
  • Prefer imperative shell / functional core.
  • Design deep, cohesive modules with low caller burden.
  • Test behavior through real seams; avoid module mocks and spy-driven tests.
  • Keep code discoverable for humans and agents.

Adapting to existing codebases

Before adding a new pattern or library, inspect the repo for existing choices around:

  • error handling
  • schema parsing
  • dependency injection
  • testing
  • observability
  • adapters/services
  • module layout

Apply these standards to all new code and to the full behavior being refactored. Do not preserve weaker patterns merely for consistency. Keep unrelated old code unchanged and translate incompatible patterns at the nearest boundary.

For example, if existing code uses exception-style errors, do not rewrite the whole system for an unrelated change. Represent known failures as typed values in new or refactored code, then translate them at the boundary into the outcome required by the existing framework. Preserve existing logging, tracing, metrics, and error-reporting hooks.

Errors and failures

Expected failures are values

Every known failure mode should appear in the return type as a custom tagged error, even when the immediate caller cannot recover. A caller must handle the error or return it upward. At the outermost boundary, translate it into a valid outcome such as an HTTP response, CLI exit code, retry decision, dead letter, or startup error message.

Known failures include domain, parsing, authorization, integration, I/O, persistence, configuration, and workflow failures.

Preferred order:

  1. Effect, when the codebase already uses Effect.
  2. better-result, when available and appropriate.
  3. A small local tagged union:
type Result<T, E extends Error> =
  | { readonly _tag: "ok"; readonly value: T }
  | { readonly _tag: "err"; readonly error: E };

Prefer:

Promise<Result<User, UserLookupError>>

not:

Promise<User> // rejects for ordinary lookup/storage failures

Promise rejection is equivalent to throwing. Catch unclassified third-party rejection inside the owning Adapter and translate it into a known tagged error before it crosses the Adapter boundary. Rejection may escape application code only for a defect.

Defects may throw or panic

Throw or panic only when a defect makes correct execution impossible, not merely because the current caller has no recovery strategy. Defects include:

  • violated internal invariants
  • impossible branches
  • temporary notYetImplemented paths
  • catastrophic runtime conditions

Known configuration failures are values; the composition root reports them safely and terminates startup.

Use established shared defect helpers where available, or the panic helper from the project's result library:

export function casesHandled(unexpectedCase: never): never;
export function shouldNeverHappen(msg?: string): never;
export function notYetImplemented(msg?: string): never;

Use casesHandled for exhaustive union handling. Avoid names like absurd or one-off assertNever helpers when the project already has these helpers.

Custom errors

Expected failures should use custom tagged errors, generally extending:

  • Error
  • TaggedError from better-result
  • Schema.TaggedErrorClass in Effect codebases

Custom errors should include:

  • stable tag using 'as const'
  • useful message
  • structured contextual fields
  • safe telemetry fields
  • optional cause: unknown

Example:

export class UserStoreUnavailable extends Error {
  readonly _tag = "UserStoreUnavailable" as const;

  constructor(
    readonly operation: "findActiveByEmail",
    readonly provider: "postgres",
    readonly cause: unknown,
  ) {
    super(`User store unavailable during ${operation}`);
  }
}

Keep error unions precise at module boundaries:

Result<User, UserNotFound | UserStoreUnavailable>

Avoid broad AppError-style types except near entrypoints, orchestration, logging, and rendering layers.

Sensitive data, telemetry, and debugging

Prefer end-to-end structured tracing across requests, jobs, workflows, application modules, adapters, and external calls.

Tracing/logging should make failures diagnosable with safe fields:

  • domain IDs
  • operation names
  • dependency/provider names
  • state tags
  • retry counts
  • typed error tags
  • safe summaries

Do not put secrets in errors, traces, logs, or snapshots.

Use a Redacted<T> wrapper for sensitive values such as tokens, API keys, passwords, raw credentials, and secrets. Prefer Effect's Redacted.Redacted in Effect codebases or a local shared Redacted<T> wrapper.

Wrap sensitive values at the boundary and unwrap only where the raw value is needed, usually inside an adapter making an external call.

Parse, don't validate

Boundary code should turn unknown or less-structured input into application or domain types before it enters inner code.

Use a separate protocol projection only when its shape or meaning differs enough to be useful. DTO describes a boundary role in prose; never use DTO or Dto in a symbol name. Name the symbol after its actual protocol or persistence meaning, such as CreateUserRequest, StripeCustomerResponse, or UserRecord:

unknown -> CreateUserRequest -> CreateUserInput -> EmailAddress/UserId/etc.

Otherwise, parse directly into the application input:

unknown -> CreateUserInput

Do not pass a schema-inferred transport shape throughout the application:

unknown -> z.infer<typeof CreateUserSchema>

Use names that preserve meaning:

  • parseX(input): Result<X, ParseXError> for untrusted or less-structured input
  • makeX(...) / createX(...) for smart constructors from already-typed pieces
  • isX(value): value is X for true predicates
  • assertX(...) rarely, mostly at tests/framework boundaries

Avoid validateX when the function returns a refined value. It parsed something.

Schemas

Use schema libraries as boundary parsers, not as ad-hoc validators sprinkled through core logic.

Preference:

  • use the repo's established schema library if one exists
  • use Effect Schema in Effect codebases
  • prefer Standard Schema compatibility for generic helpers
  • otherwise prefer Zod 4
  • use hand-written smart constructors/parsers for small domain types when clearer

Schema parsing should produce refined/domain types and typed custom errors where practical.

Branded types and correct construction

Use branded/refined types when they prevent realistic misuse or invalid construction, especially for:

  • IDs: UserId, OrgId, WorkflowId
  • parsed strings: EmailAddress, NonEmptyString, Url
  • constrained numbers: PositiveInt, Cents, Percentage
  • units: Milliseconds, Bytes, UsdCents

Construct branded values through parsers or smart constructors. Avoid passing raw strings/numbers where a domain type exists.

Avoid optional/null/undefined values in functions that require a value. Push optionality outward. Branch or parse before calling.

Avoid Partial<T> as an application/domain input unless partiality is the real domain concept. Prefer explicit input types for each operation.

State machines and boolean blindness

When an entity has meaningful lifecycle states, model them with tagged unions or equivalent value classes.

Prefer:

type Invoice =
  | { readonly _tag: "Draft"; readonly id: InvoiceId; readonly lines: NonEmptyArray<LineItem> }
  | { readonly _tag: "Sent"; readonly id: InvoiceId; readonly sentAt: Instant }
  | { readonly _tag: "Paid"; readonly id: InvoiceId; readonly paidAt: Instant };

Avoid:

type Invoice = {
  readonly isSent: boolean;
  readonly isPaid: boolean;
  readonly sentAt?: Date;
  readonly paidAt?: Date;
};

Avoid boolean parameters that control behavior:

createUser(input, true);

Prefer named options or domain types:

createUser(input, { emailVerification: "skip" });

Booleans are fine as clear predicate return values:

isExpired(token): boolean;
hasPermission(user, permission): boolean;

Modules and abstractions

Domain Module, Application Service Module, and Adapter Module name responsibilities, not required folders, suffixes, or TypeScript constructs. A module may be a function, object, class, file, or package with a cohesive public interface. Use the roles at any scale; do not create three layers when the behavior does not need them.

The normal dependency and call flow for an operation with application policy or effects is:

external input -> inbound Adapter -> Application Service -> Domain Module
                                           |
                                           +-> application-owned port
                                                 -> outbound Adapter -> external system

An inbound Adapter may call a Domain Module directly only for a pure operation with no authorization, application policy, persistence, external calls, or effect sequencing:

external input -> inbound Adapter -> Domain Module

The composition root constructs concrete Adapters and supplies them to Application Services. Dependencies point inward: Domain Modules know neither services nor Adapters; Application Services know application-owned port contracts, not concrete technologies; Adapters depend on those contracts and translate at the edge.

Choosing a role

Classify code by the responsibility that would make it change:

  • A business meaning, invariant, calculation, or legal state transition changes: Domain Module.
  • An application operation's policy, authorization, or effect sequence changes: Application Service Module.
  • A protocol, framework, database, runtime, or third-party API changes: Adapter Module.
  • Only construction, configuration, or resource wiring changes: composition root.

Split an abstraction when it owns more than one of these reasons to change. Do not split code merely to satisfy the taxonomy: a pure operation may need only a Domain Module, while a simple boundary may call an Application Service with no new domain type.

Applying the roles in any codebase

For a new feature or a local refactor:

  1. Trace one caller-visible operation from ingress to every effect.
  2. Put intrinsic meanings, invariants, calculations, and transitions in Domain Modules.
  3. Put application policy and effect ordering in an Application Service; define its dependencies as narrow ports.
  4. Put each protocol or technology translation in an inbound or outbound Adapter.
  5. Wire concrete Adapters to ports at the composition root.
  6. Verify each role through its public seam: domain results, application outcomes, and boundary records/responses.

Apply these responsibilities inside the project's existing layout and framework vocabulary. Migrate mixed code only across the feature's required semantic surface; otherwise contain the old convention at an Adapter seam rather than forcing a broad rewrite.

For example, in password reset: EmailAddress and ResetToken are Domain Modules; PasswordReset is the Application Service; an HTTP route is an inbound Adapter; Postgres and email-provider implementations are outbound Adapters; bootstrap performs the wiring.

Deep modules

A deep module hides substantial behavior, invariants, policy, sequencing, or translation behind a cohesive, low-burden interface. Low-burden does not necessarily mean few functions.

Avoid shallow abstractions that merely forward calls, mirror tables, rename another API, or expose implementation steps.

Use the deletion test:

  • if deleting the module makes complexity disappear, it was probably pass-through waste
  • if deleting it spreads complexity across callers, it was probably earning its keep

Domain Modules

A Domain Module is a pure, type-centric abstract data type in the OCaml tradition. It centers one primary domain type or tightly related type family and owns what values mean and which operations are legal.

Use one when the code has a meaningful domain distinction, invariant, calculation, decision, or lifecycle. Keep a primitive or local pure function when introducing a domain abstraction would prevent no realistic misuse and centralize no meaningful rule.

A Domain Module should:

  • co-locate its type, supporting types, parsers, smart constructors, combinators, predicates, legal transitions, domain projections, formatting, and test generators as applicable
  • return refined values from parsers and constructors so callers cannot create invalid instances
  • express expected failures as precise values
  • remain deterministic and independent of I/O, frameworks, persistence, ambient time, randomness, and mutable global state

It may define pure permission decisions over parsed domain values. It should not authenticate callers, gather authorization context, enforce permissions while carrying out an application operation, choose effect order, query storage, call a network, or expose transport/persistence DTOs. Callers use its operations instead of recreating its checks or branding values with casts.

Example:

// email-address.ts

/** A parsed, normalized email address. */
export type EmailAddress = Brand<string, "EmailAddress">;

/** Parse an email address from untrusted input. */
export function parse(input: string): Result<EmailAddress, InvalidEmailAddress>;

/** Render an email address as a string. */
export function toString(email: EmailAddress): string;

/** Compare two email addresses for equality. */
export function equals(left: EmailAddress, right: EmailAddress): boolean;

Domain Modules may use plain functions, immutable value classes, or static-style classes when cohesive. If using classes:

  • construct through parse / make / smart constructors
  • make invalid instances unconstructable
  • keep fields readonly/immutable from callers
  • keep methods cohesive over that value
  • do not hide dependencies or I/O inside domain value classes
  • avoid inheritance for domain behavior

Application Service Modules

An Application Service Module owns one cohesive application operation or capability, such as PasswordReset, Invitations, or SubscriptionLifecycle. It applies application policy and sequences effects through narrow, application-owned ports while delegating intrinsic business rules to Domain Modules.

Use one when an operation must coordinate authorization, domain decisions, persistence, external calls, transactions, messages, time, IDs, or telemetry—or when the same operation must be callable from multiple entrypoints. A direct Domain Module call is enough when no application policy or effect orchestration exists.

An Application Service should:

  • accept and return application/domain types with precise expected-error unions
  • define the smallest meaningful ports required by the operation
  • receive ports, configuration, clocks, randomness, and similar capabilities explicitly
  • own which effects occur, under what policy, and in what order
  • remain independent of HTTP, CLI, queue, ORM, vendor SDK, and runtime types

It should not parse protocol envelopes, render responses, execute SQL, translate vendor DTOs, or duplicate Domain Module invariants. Prefer constructor injection for dependency-bearing classes; in Effect codebases, use services/tags/layers. Avoid dependency bags passed into every call.

There is no arbitrary method limit. Split methods that represent unrelated capabilities, change for different reasons, or require unrelated dependencies. Avoid vague names such as Manager, Processor, Helper, or generic UserService unless established by the project.

Adapter Modules

An Adapter Module owns one boundary's translation and technology mechanics. Use one whenever application code crosses a framework, protocol, serialization, process, persistence, runtime, or third-party boundary.

There are two directions:

  • An inbound Adapter parses an external request/event/command, invokes an Application Service or a directly callable pure Domain Module as described above, and projects its result into the external protocol. Examples: HTTP route, GraphQL resolver, CLI command, queue consumer.
  • An outbound Adapter implements an Application Service port using a concrete technology and translates raw records, SDK values, and external failures into application/domain types and typed errors. Examples: Postgres store, Stripe client, email sender, system clock.

An Adapter should own schema/DTO translation, framework lifecycle, external error classification, and safe diagnostics for its boundary. It may retry a short-lived technical failure only when the operation is safely repeatable and the retry does not change the port's meaning. It should not decide business eligibility, authorization policy, legal state transitions, or application-operation ordering. Keep raw external types inside the Adapter or composition root.

A port is not an Adapter. A port is the application-owned contract that states what an operation needs; an outbound Adapter is one replaceable implementation. Do not add an Adapter that only forwards the same shape to another internal module without hiding real translation or mechanics.

Composition root

The composition root parses environment and configuration, acquires resources, constructs concrete Adapters, and injects them into Application Services. Keep framework bindings and concrete wiring here; do not turn the composition root into a place for domain rules, application policy, or reusable boundary translation.

Application-owned ports and Adapter reuse

Define ports beside the Application Service that needs them and in the application's language, not the provider's language. Depend on the smallest meaningful capability the operation uses; let a cohesive concrete Adapter be wider. Port inputs, outputs, and errors must be application/domain types rather than raw rows, SDK objects, or framework values.

Because TypeScript is structurally typed, this works well:

type UsersForPasswordReset = {
  findActiveByEmail(email: EmailAddress): Promise<Result<ActiveUser, UserLookupError>>;
};

export class PasswordReset {
  constructor(private readonly users: UsersForPasswordReset) {}
}

A wider adapter can satisfy it:

export class PostgresUsers {
  findActiveByEmail(...) { ... }
  findById(...) { ... }
  updateProfile(...) { ... }
}

This avoids both mega-repositories and one-method adapter sprawl.

Adapter reuse audit

Before creating a new adapter or service, agents must audit existing adapters/services.

Prefer, in order:

  1. Reuse an existing adapter as-is through a narrow dependency type.
  2. Extend an existing adapter if the new method fits its existing cohesive capability and changes for the same reason.
  3. Create a new adapter only when reuse/extension would create bad coupling or an accidental interface.

Do not require an ADR for a routine feature-level Adapter or Application Service. Create an ADR when the new module introduces a lasting architectural boundary, shared pattern, provider strategy, or deliberate exception to these standards. The ADR should explain:

  • what existing Adapters or Application Services were checked
  • why reuse or extension did not fit
  • why the new boundary or pattern is a separate cohesive capability

Repositories and persistence

Avoid repository-per-table by default.

Repository-like adapters are acceptable when they represent a cohesive domain persistence capability. They should expose meaningful domain operations and return parsed domain types / typed errors, not raw rows and ORM errors.

Treat raw database rows and ORM models as infrastructure DTOs. Parse them before application/core logic. Keep SQL/ORM details inside infrastructure adapters or persistence modules.

Functional core, imperative shell, and entrypoints

Domain Modules form the functional core. Application Service Modules and Adapter Modules form the imperative shell, but only Adapters contain technology-specific concerns. This keeps the same application operation reusable across REST, CLI, GraphQL, workers, and other entrypoints.

The functional core contains domain parsers, invariants, state transitions, calculations, combinators, and decision functions. It avoids I/O, hidden dependencies, ambient time/randomness, thrown expected failures, and framework-specific concerns.

The imperative shell has two distinct responsibilities:

  • Application Services apply application policy and sequence effects through explicit ports.
  • Adapters parse or project boundary values, classify external failures, and perform concrete I/O.

Entrypoint Adapters should be thin protocol translation layers. They parse protocol-specific input, call Domain Module parsers to obtain refined values, invoke an Application Service when application policy or effects are involved, and render protocol-specific output. A pure operation may call a Domain Module directly as described above. Do not duplicate business rules in controllers, resolvers, commands, or handlers.

Within authentication and authorization, inbound Adapters verify boundary credentials and produce a parsed identity such as Principal, Session, or CommandActor. Domain Modules may define pure permission decisions over parsed domain values. Application Services gather the required context and enforce those decisions while carrying out an application operation. Adapters project missing or invalid credentials and denied operations into protocol-specific outcomes; they do not define permission policy.

Workflows, transactions, and idempotency

Use ordinary function calls or database transactions for simple single-boundary operations.

Use a saga or durable workflow when progress must survive process loss or redelivery, or when the operation requires long delays, compensation, resumability, timers, human approval, cross-service coordination, or multiple transaction boundaries. A short-lived retry by itself does not require durable workflow machinery.

Adapters own safe, short-lived technical retries. Application Services decide whether an application operation should be attempted again. Durable workflows own retries that must survive crashes, delays, or redelivery.

Do not hold database transactions open across network calls or long-running operations.

Any externally observable mutation or state transition that may be retried needs an explicit idempotency strategy:

  • idempotency key
  • natural unique constraint
  • deduplication record
  • state-machine transition guard
  • transactional outbox/inbox

Retrying should not rely on “probably safe” side effects.

Testing

Add an end-to-end test whenever the behavior can be exercised through its real public entrypoint in the normal test environment without unreliable third parties or unreasonable setup, runtime, or cost. Add lower-level tests when they provide extra coverage for important cases.

Prefer confidence-oriented tests:

  1. end-to-end tests through real public entrypoints whenever possible
  2. integration tests through real seams
  3. focused/property tests for pure Domain Modules
  4. unit tests when they test meaningful behavior, not implementation details

Never use vi.mock or jest.mock for module mocking. Use real seams:

  • constructor-injected interfaces/classes
  • Effect services/layers
  • local database substitutes such as SQLite
  • in-memory adapters when behavior is simple
  • fake external adapters when needed

Prefer tests that assert observable input/output behavior:

  • returned value/error
  • persisted state
  • emitted event/message
  • rendered response
  • sent email record in a fake/local adapter

Avoid spy-driven tests like expect(sendEmail).toHaveBeenCalledWith(...) unless the interaction itself is the only observable behavior.

For persistence behavior, prefer SQLite/local DB-backed tests over hand-rolled in-memory fakes when SQL/schema/transaction behavior matters.

Property tests and arbitraries

Use fast-check where properties are clearer than examples, especially for:

  • parsers/smart constructors
  • branded/refined types
  • state machines
  • serialization roundtrips
  • normalization/idempotence
  • lawful combinators

Use arbitraries for mock/test data generation. Prefer exporting arbitraries near the domain module they support:

src/billing/
  invoice-number.ts
  invoice-number.test.ts
  invoice-number.arbitrary.ts

Tests should not bypass parsers, smart constructors, or invariants.

TypeScript style and safety

Use strict TypeScript settings where practical:

  • strict: true
  • noUncheckedIndexedAccess: true
  • exactOptionalPropertyTypes: true
  • noImplicitOverride: true
  • noFallthroughCasesInSwitch: true

Prefer immutable values:

type CreateUserInput = {
  readonly email: EmailAddress;
  readonly roles: ReadonlyArray<Role>;
};

Mutation is acceptable inside localized imperative shell code, performance-sensitive internals, builders, or adapters when hidden behind a precise interface.

Casts, any, and non-null assertions

Avoid:

  • any
  • non-null assertions (!)
  • casts with as Type

as const is fine.

Rare exceptions are allowed for highly generic helpers, branding internals, interop boundaries, or combinators where TypeScript cannot express the invariant.

Any non-as const cast requires a Rust-like safety comment:

// SAFETY: TypeScript cannot express the brand. parseEmailAddress checked the normalized string before branding. Callers cannot construct EmailAddress except through this parser.
return normalized as EmailAddress;

Rare any also requires a targeted oxlint ignore and justification:

// oxlint-disable-next-line no-explicit-any -- SAFETY: This helper preserves arbitrary function parameters; TypeScript cannot express this variadic constraint without any.
type Fn = (...args: any[]) => unknown;

Do not use !. Branch, parse, or refine instead.

Imports, exports, and files

Prefer direct imports from the file that owns the abstraction. Avoid barrel files / index.ts re-export layers by default.

For domain modules, namespace imports often preserve the module shape:

import * as EmailAddress from "./email-address";

EmailAddress.parse(input);

Use named imports for classes and focused shared helpers:

import { PasswordReset } from "./password-reset";

Use import type / export type for type-only imports and exports.

Export only what callers should use. Keep internal helpers unexported unless intentionally shared. Do not export internals just for tests.

Avoid TypeScript namespace unless there is a compelling interop reason.

Avoid vague files:

utils.ts
helpers.ts
common.ts
misc.ts

Use precise names:

email-address.ts
billing-period.ts
string-case.ts
array.ts

Tiny ubiquitous generic helpers/types may share one explicit module when no more precise owner exists. Appropriate contents include:

  • casesHandled
  • shouldNeverHappen
  • notYetImplemented
  • Redacted
  • Tags, ExtractTag, and ExcludeTag
  • common Result helpers when the project uses neither Effect nor better-result
  • broad type utilities

Keep only helpers justified by the target project. Keep domain and application policy with their owning modules.

No arbitrary file-size limits. Prefer cohesion and discoverability over small files for their own sake. Split when a file has multiple unrelated reasons to change or callers must understand unrelated concepts.

Comments and JSDoc

Comments should explain invariants, trade-offs, non-obvious domain rules, and safety justifications. Avoid comments that narrate obvious code.

Every exported symbol from a JavaScript or TypeScript module requires JSDoc. Public methods and properties of an exported class also require JSDoc. Private and otherwise internal code requires documentation only when its complexity warrants it. Put documentation on the original declaration; re-exports do not need duplicate documentation.

Do not use @inheritDoc, @inherit, or similar inheritance tags. Write the required documentation explicitly on each symbol or member.

Use standard JSDoc syntax:

/**
 * Parse an email address from untrusted input.
 *
 * @param input - The untrusted string to parse.
 * @returns A parsed email address, or `InvalidEmailAddress` when the input is invalid.
 */
export function parse(input: string): Result<EmailAddress, InvalidEmailAddress>;

For generics:

/**
 * Map the success value of a result.
 *
 * @template T - The original success type.
 * @template U - The mapped success type.
 * @template E - The error type.
 * @param result - The result to map.
 * @param fn - The function applied to the success value.
 * @returns A result with the mapped success value, or the original error.
 */
export function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;

Use @throws only for unrecoverable defects, framework-required behavior, or temporary notYetImplemented paths. Do not document expected typed errors as throws.

For complex exported object types, document fields when helpful:

/** Input required to create a user. */
export type CreateUserInput = {
  /** The actor creating the user. */
  readonly actor: AdminUser;

  /** The parsed email address for the new user. */
  readonly email: EmailAddress;
};

Configuration and resources

Parse environment/config at startup or the earliest boundary into typed config with branded/redacted values where appropriate. Return known configuration failures as tagged error values. The composition root should report a safe startup message and terminate rather than treating invalid configuration as an internal defect.

Do not read process.env throughout the app. Missing or invalid config is a startup failure with useful, safe context.

Avoid top-level side effects except in true entrypoint/bootstrap files. Modules should not start servers, open connections, read env, register handlers, or perform I/O at import time.

Resource creation and cleanup should be explicit and owned by bootstrap/imperative shell code or Effect layers when using Effect.

Avoid mutable singletons/global state. Constants and pure lookup tables are fine. If a singleton is required by a framework/runtime, isolate it at the boundary.

Inject Clock / Random services into dependency-bearing modules. Pure domain functions may accept explicit now / random values.

Quick agent checklist

Before coding:

  • Read existing conventions for errors, schemas, tests, adapters, telemetry, and module layout.
  • Classify each changed concern as Domain Module, Application Service Module, Adapter Module, or composition-root wiring.
  • Reuse existing Domain Modules, Application Services, and Adapters before creating new ones.
  • Define effect dependencies as narrow, application-owned ports; keep raw external types in Adapters or the composition root.
  • Parse inputs at the edge and use domain types internally.
  • Avoid raw DTOs, raw IDs, nullable bags, and Partial<T> in core/application logic.
  • Prefer typed errors as values for new expected failures.
  • Preserve existing observability/error mechanics.
  • Test through public interfaces and real seams.
  • Use fast-check arbitraries for generated test data when practical.
  • Add JSDoc for exported symbols.
  • Add an ADR only for a lasting architectural boundary, shared pattern, provider strategy, or deliberate exception discovered through the Adapter/Application Service reuse audit.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.