Typed Service Contracts

This is a strict architectural pattern for TypeScript services that treats inputs as untrusted data requiring parsing (via Zod schemas) and errors as typed return values instead of exceptions. You define a spec.ts with input/output/error schemas and a discriminated union Result type, then implement it in handler.ts that never throws. The split is deliberate: contract tests validate your Zod schemas catch bad data, logic tests mock dependencies and assert on Result objects. It's overkill for CRUD apps but makes sense for CLIs, libraries, or anything where unhandled exceptions are unacceptable. The "parse don't validate" philosophy and exhaustive error enums force you to think through failure modes upfront rather than discovering them in production.

skills.sh installs: 754
GitHub stars: 28.8K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add google-labs-code/design.md --skill typed-service-contracts --agent claude-code

Installs into .claude/skills of the current project.

Files

Typed Service Contracts (Spec & Handler Pattern)

This skill defines a Vertical Slice Architecture backed by Design by Contract (DbC) principles. It treats application logic as rigorously defined Units of Work where inputs are parsed (not just validated) and errors are treated as values (Result Pattern) rather than exceptions.

When to use this skill

Building CLIs or Libraries: When you need strict boundaries between user input and system logic.
Complex Validation: When inputs require transformation (parsing) before being useful (e.g., ensuring a string is a valid file path).
High-Reliability Requirements: When you cannot afford unhandled runtime exceptions and need exhaustive error handling.
Testing Focus: When you want to separate data validation tests from business logic tests.