dmmulroy/skills/coding-standards
Claude Code and agent skill by dmmulroy/skills
- community
Checking that the SKILL.md file is still in the repository.
Correct-by-construction TypeScript standards. Use for TypeScript engineering or when another skill needs the user's coding standards.
Install
npx vskill@latest install dmmulroy/skills/coding-standardsSKILL.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:
- Preserve correctness, safety, and debuggability.
- Apply these standards to all new code and to the full behavior being refactored.
- Follow compatible project architecture and conventions.
- Contain incompatible existing patterns at the nearest boundary rather than copying them into new code.
- Avoid changing unrelated old code unless a broader migration is explicitly requested.
- 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:
- Effect, when the codebase already uses Effect.
better-result, when available and appropriate.- A small local tagged union:
Prefer:
not:
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
notYetImplementedpaths - 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:
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:
ErrorTaggedErrorfrombetter-resultSchema.TaggedErrorClassin Effect codebases
Custom errors should include:
- stable tag using 'as const'
- useful message
- structured contextual fields
- safe telemetry fields
- optional
cause: unknown
Example:
Keep error unions precise at module boundaries:
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:
Otherwise, parse directly into the application input:
Do not pass a schema-inferred transport shape throughout the application:
Use names that preserve meaning:
parseX(input): Result<X, ParseXError>for untrusted or less-structured inputmakeX(...)/createX(...)for smart constructors from already-typed piecesisX(value): value is Xfor true predicatesassertX(...)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:
Avoid:
Avoid boolean parameters that control behavior:
Prefer named options or domain types:
Booleans are fine as clear predicate return values:
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:
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:
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:
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingcoding-standards/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/dmmulroy/skills/coding-standards)