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
.claude/rules/0-error-handling.mdWhat 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/**/*.tsand move use-case error handling to the command layer. - Replace the local catch with
errorHandler.handle(error)and exit1. - Find empty
catchblocks and compare thrown classes withkernel/errors.ts.
How to install 0-error-handling
Manually: put the files in place
.claude/rules/0-error-handling.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/0-error-handling.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/0-error-handling.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/0-error-handling.mdManually: put the files in place
.clinerules/0-error-handling.mdStep 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