Skip to main content
rule CX Codex

0-error-handling — Claude Code rule: errors and setup

The 0-error-handling rule gives TypeScript failures one path: a typed exception moves outward and is handled at the command boundary.

MIT ★ 571 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/0-error-handling.md
Open on GitHub

What 0-error-handling does

The rule targets src/**/*.ts. A use case throws a typed exception and leaves it uncaught; it also does not encode failure as a return value. An adapter may catch an error only to assign a type to an I/O failure through kernel/errors.ts.

kernel/errors.ts is the single error catalog, and every class in it must be thrown somewhere. The command layer is the sole catch point: it calls errorHandler.handle(error) and exits with code 1. An empty catch is allowed only for an explicit best-effort case or failure.

An error message that names a command acts as a contract. The errors-that-instruct.arch.test.ts test checks that command against the CLI. The update-check hook is the one intentional swallow, so another silent catch conflicts with this rule’s flow.

What it helps with

  • pass a use-case failure to the command boundary
  • type an I/O failure inside an adapter
  • keep one catalog of application error classes
  • verify that catalog errors are actually thrown
  • check command names in error messages against the CLI

Example prompts for the agent

  • Review src/**/*.ts and move use-case error handling to the command layer.
  • Replace the local catch with errorHandler.handle(error) and exit 1.
  • Find empty catch blocks and compare thrown classes with kernel/errors.ts.

How to install 0-error-handling

Manually: put the files in place

.claude/rules/0-error-handling.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about 0-error-handling

How do I install 0-error-handling in Claude Code?

Add the rule at .claude/rules/0-error-handling.md.

What does 0-error-handling do?

It keeps typed failures moving from a use case to the command boundary, where the error is handled once. Adapters may catch I/O failures to type them.

When is an empty catch allowed?

Only for a listed best-effort case or failure. The update-check hook is the one deliberate swallow covered by the rule.

Source text

0-error-handling.md · MIT
---
description: Apply when handling a failure; a typed exception travels inward and is caught once, at the command edge.
paths:
  - "src/**/*.ts"
---

# Errors

## Flow

- A use case throws.
- It never catches its own errors.
- It never returns a failure as a value.
- An adapter catches only to type an I/O error (`kernel/errors.ts`).
- Never `catch {}` into a default: unreadable is not absent.
- An empty catch is a listed best effort or a failure (`catches-that-swallow.arch.test.ts`).
- The command layer is the only catcher: `errorHandler.handle(error)`, exit 1.
- The update-check hook is the one deliberate swallow.

## Catalog

- `kernel/errors.ts` is the one catalog.
- Every class in it is thrown (`errors-that-are-thrown.arch.test.ts`, empty baseline).

## Instructing

- A message naming a command is a contract.
- `errors-that-instruct.arch.test.ts` checks each named command against the CLI.
- Descriptive prose is not pinned.

© ai-driven-dev · MIT · ai-driven-dev/framework

Similar IDE rules

All IDE rules for Backend and APIs →
error-handling affaan-m error-handling — a skill that sets one way to handle errors in TypeScript, Python and Go: typed errors, retries, circuit breakers, user-facing messages. CX Codex +1 6,600installs run-relevant-tests-after-adding-error-handling-wrappers ZaxbyHub run-relevant-tests-after-adding-error-handling-wrappers is a Claude Code skill that prompts an agent to run relevant tests after adding error handling and check the success path's original return type and value. CX Codex +1 ★ 539repo stars golang-error-handling samber golang-error-handling — a skill for idiomatic Go error handling: wrapping with context, chain inspection, structured logging, and samber/oops integration. Apply when creating, wrapping, inspecting, or logging errors in Go code. CX Codex +1 46,400installs correctness-and-error-handling cognitedata correctness-and-error-handling is a Claude Code skill that finds and fixes runtime errors, unhandled promises, and empty states in Cognite Flows React apps. CX Codex +1 1,900installs error-handling-standardizer patricio0312rev error-handling-standardizer is a skill that standardizes application errors across custom classes, HTTP responses, and structured logs for consistent API exception handling. CX Codex +1 269installs error-handling-patterns curiositech The error-handling-patterns skill for Claude Code designs error handling in TypeScript and Python, supporting the choice between exceptions and Result types and the design of recovery flows. CX Codex +1 140installs

From the same set80

The whole set →
01-ticket-info 01-ticket-info is a Claude Code skill that fetches ticket details from a configured issue tracker and displays its fields in the agent chat. It reads the ticket identified in the prompt or conversation context. CX Codex +1 ★ 571repo stars 0-shared-modules The 0-shared-modules rule sets a bar for moving code into shared/: callers must come from two application areas. Use it when reviewing modules under src/contexts/. CX Codex +1 ★ 571repo stars 01-hello 01-hello is a Claude Code skill that runs the greet action to confirm the aidd-ui plugin is loaded. It checks plugin availability. CX Codex +1 ★ 571repo stars 7-auth 7-auth governs how assistant code reads and saves auth credentials: lazy GitHub token lookup, tight file permissions, and delayed error handling. CX Codex +1 ★ 571repo stars 00-onboard 00-onboard walks a project through AIDD: reads the repo, picks the next step, shows it on screen, then acts on your reply. CX Codex +1 ★ 571repo stars 04-skill-generate 04-skill-generate generates router-based skills across AI tools through structured scoping and validation. Use it to scaffold new skills, turn manual workflows into skills, or refactor existing ones. CX Codex +1 ★ 571repo stars 03-context-generate The 03-context-generate skill routes requests to create skills, rules, agents, commands, or hooks to the matching generator. If you leave out the artifact type, it asks which one you mean. CX Codex +1 ★ 571repo stars 04-spec 04-spec writes spec.md, the contract for a single feature, from a request, a PRD or review notes. Or rewrites a spec that already exists. CX Codex +1 ★ 571repo stars

Project sponsors

Companies that keep this analytics open