К основному содержанию
скилл CX Codex

error-handling-patterns · curiositech — скилл для Claude Code

Скилл error-handling-patterns для Claude Code проектирует обработку ошибок в TypeScript и Python: помогает выбрать между исключениями и Result-типами и построить recovery-флоу.

MIT 140 установок ★ 274 обновлён 2026-10-30

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add curiositech/some_claude_skills --skill error-handling-patterns -a claude-code
Открыть на GitHub

Что делает error-handling-patterns

Скилл помогает спроектировать обработку ошибок так, чтобы сбои были явными, восстанавливаемыми и отлаживаемыми. Центральная идея — подбирать стиль обработки под семантику ошибки: не все ошибки одинаковы, и относиться к ним одинаково плохо. Внутри есть решающее дерево для выбора между исключением, Result-типом и кодом ошибки.

Классификация ошибок идёт по двум осям: временная/постоянная и исправимая пользователем/системой. От этого зависит, стоит ли повторять запрос, что показывать пользователю и нужно ли будить дежурного. Для ретраев скилл предлагает экспоненциальный backoff с полным джиттером, circuit breaker и dead letter queue.

Для TypeScript скилл даёт готовую иерархию: базовый AppError с code, statusCode и isOperational, от него наследуются ValidationError, NotFoundError, RateLimitError. Отдельно разбирается паттерн Result<T, E> — когда ошибка это ожидаемый исход операции, а не исключение. Для Python есть аналоги в references/error-hierarchy-examples.md. Ретраи описаны в references/retry-patterns.md. Скилл не предназначен для отладки конкретной ошибки в рантайме и не настраивает мониторинг или логирование.

Какие задачи решает

  • выбрать между исключением, Result-типом и кодом ошибки
  • спроектировать иерархию доменных ошибок в TypeScript или Python
  • решить, стоит ли ретраить конкретную ошибку
  • настроить backoff с джиттером и circuit breaker
  • различить ошибки пользователя и сбои системы

Примеры запросов агенту

  • Спроектируй обработку ошибок для API на TypeScript: иерархия исключений и ретраи
  • Покажи, как сделать Result-тип для запросов к базе в Python
  • Нужен circuit breaker для воркера: какие ошибки ретраить, а какие сразу в DLQ?

Как установить error-handling-patterns

1Через Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill error-handling-patterns -a claude-code

2Вручную: положить файлы

~/.claude/skills/error-handling-patterns/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/error-handling-patterns/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об error-handling-patterns

Как установить error-handling-patterns в Claude Code?

Выполни npx skills add curiositech/some_claude_skills --skill error-handling-patterns -a claude-code, затем открой ~/.claude/skills/error-handling-patterns/SKILL.md.

Что делает скилл error-handling-patterns?

Проектирует стратегии обработки ошибок для TypeScript и Python: иерархии исключений, Result/Either-типы, паттерны ретраев, error boundaries и структурированное логирование ошибок.

Чем скилл не занимается?

Не отлаживает конкретную ошибку в рантайме, не настраивает инфраструктуру логирования и не конфигурирует мониторинг. Для этого нужны другие скиллы.

Исходный текст

SKILL.md · MIT
---
name: error-handling-patterns
description: Design error handling strategies for TypeScript and Python applications — exception hierarchies, Result/Either types, retry patterns, error boundaries, and structured error logging. Use when
  designing error handling architecture, choosing between exceptions and Result types, implementing retry logic, or building error recovery flows. Activate on "error handling", "exception hierarchy", "Result
  type", "retry pattern", "circuit breaker", "error boundary", "Pokemon exception". NOT for debugging specific runtime errors, logging infrastructure setup, or monitoring/alerting configuration.
allowed-tools: Read,Write,Edit,Grep,Glob
argument-hint: '[language: typescript|python] [context: api|ui|worker|library]'
metadata:
  category: DevOps & Site Reliability
  tags:
  - error
  - handling
  - patterns
  - error-handling
  - exception-hierarchy
  pairs-with:
  - skill: typescript-advanced-patterns
    reason: Result/Either types and discriminated unions implement type-safe error handling in TS
  - skill: logging-observability
    reason: Structured error logging with correlation IDs enables effective error tracking and debugging
  - skill: background-job-orchestrator
    reason: Retry patterns and dead letter queues are error handling applied to job processing
---

# Error Handling Patterns

Design error handling strategies that make failures explicit, recoverable, and debuggable. The central skill is matching error handling style to error semantics: not all errors are equal, and treating them equally produces systems that are equally bad at handling all of them.

## When to Use

✅ Use for:
- Choosing between exceptions, Result types, or error codes for a domain
- Designing typed error hierarchies in TypeScript or Python
- Implementing retry logic with backoff, jitter, and circuit breaking
- Building React error boundaries and graceful degradation
- Structuring error information for both users and developers
- Python exception chaining and `__cause__` / `__context__` semantics

❌ NOT for:
- Debugging a specific runtime error (use debugger or domain skill)
- Logging pipeline infrastructure (use observability skill)
- APM/monitoring configuration (use site-reliability-engineer skill)
- Writing tests for error paths (use vitest-testing-patterns skill)

---

## Core Decision: Exception vs Result Type vs Error Code

```mermaid
flowchart TD
    Q1{Is this a programming error\nor contract violation?} -->|Yes| EX[Throw exception\nlet it crash]
    Q1 -->|No| Q2{Is the error part of\nnormal control flow?}
    Q2 -->|Yes| Q3{What is the call site context?}
    Q2 -->|No| Q4{Do callers need to\ndistinguish error types?}
    Q3 -->|Functional / monad-friendly| RT[Result or Either type]
    Q3 -->|Simple script or CLI| EC[Error code + message]
    Q4 -->|Yes| EH[Typed exception hierarchy]
    Q4 -->|No| GE[Generic exception\nwith structured message]
    EX --> NOTE1[Never catch at boundary —\nlet process restart]
    RT --> NOTE2[Compose with map/flatMap;\ncheck references/error-hierarchy-examples.md]
    EH --> NOTE3[See hierarchy design rules below]
```

**Rules of thumb**:
- Library code: prefer Result types — never force callers to handle your exceptions
- Application code: typed exception hierarchies work well; errors are exceptional
- CLI / scripts: error codes are fine; the user is the error boundary
- Async workers: Result types or structured error objects with retry metadata

---

## Error Classification

Classify every error along two axes before deciding how to handle it:

| | **Transient** (retry may succeed) | **Permanent** (retry won't help) |
|---|---|---|
| **User-actionable** | Rate limit, quota exceeded | Invalid input, unauthorized |
| **System-actionable** | Network timeout, DB connection | Data corruption, schema mismatch |

This classification determines:
- Whether to retry (transient only)
- What to show the user (user-actionable → message; system → generic error + tracking ID)
- Whether to alert on-call (system permanent → page; transient spikes → alert)

---

## Should This Error Be Retried?

```mermaid
flowchart TD
    E[Error occurs] --> C1{Is error transient?\nTimeout, 429, 503, connection reset}
    C1 -->|No| FAIL[Fail immediately\nReturn error to caller]
    C1 -->|Yes| C2{Have we exceeded\nmax retry attempts?}
    C2 -->|Yes| DLQ[Send to dead letter queue\nor return final failure]
    C2 -->|No| C3{Is circuit breaker OPEN?}
    C3 -->|Yes| CB[Return circuit-open error\nDo not attempt request]
    C3 -->|No| WAIT[Wait: exponential backoff\n+ full jitter]
    WAIT --> RETRY[Retry request]
    RETRY --> C1
    CB --> PROBE{After timeout:\nsend probe request}
    PROBE -->|Success| CLOSE[Close circuit\nResume normal traffic]
    PROBE -->|Fail| CB
```

Consult `references/retry-patterns.md` for backoff formulas, jitter strategies, and circuit breaker implementation.

---

## TypeScript: Error Hierarchy Design

```typescript
// Base application error — all domain errors extend this
class AppError extends Error {
  readonly code: string;
  readonly statusCode: number;
  readonly isOperational: boolean; // false = programmer error, crash process

  constructor(message: string, code: string, statusCode: number, isOperational = true) {
    super(message);
    this.name = this.constructor.name;
    this.code = code;
    this.statusCode = statusCode;
    this.isOperational = isOperational;
    Error.captureStackTrace(this, this.constructor);
  }
}

// Domain-specific errors
class ValidationError extends AppError {
  readonly fields: Record<string, string[]>;
  constructor(fields: Record<string, string[]>) {
    super('Validation failed', 'VALIDATION_ERROR', 422);
    this.fields = fields;
  }
}

class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} ${id} not found`, 'NOT_FOUND', 404);
  }
}

class RateLimitError extends AppError {
  readonly retryAfterMs: number;
  constructor(retryAfterMs: number) {
    super('Rate limit exceeded', 'RATE_LIMIT', 429);
    this.retryAfterMs = retryAfterMs;
  }
}
```

Consult `references/error-hierarchy-examples.md` for Python equivalents, Result type implementations, and full hierarchy patterns.

---

## Result Type Pattern (TypeScript)

When errors are expected outcomes of operations (parsing, API calls, DB queries), use Result instead of throw:

```typescript
type Result<T, E = AppError> =
  | { ok: true; value: T }
  | { ok: false; error: E };

// Helpers
const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
const err = <E>(error: E): Result<never, E> => ({ ok: false, error });

// Usage — caller is forced to handle both cases
async function fetchUser(id: string): Promise<Result<User, NotFoundError | NetworkError>> {
  try {
    const user = await db.users.findById(id);
    if (!user) return err(new NotFoundError('User', id));
    return ok(user);
  } catch (e) {
    return err(new NetworkError('DB unavailable', { cause: e }));
  }
}

// At call site — no silent failures
const result = await fetchUser(userId);
if (!result.ok) {
  if (result.error instanceof NotFoundError) return res.status(404).json(...);
  return res.status(500).json(...);
}
const user = result.value; // typed, safe
```

---

## React Error Boundaries

Error boundaries catch render-time exceptions. They do NOT catch async errors (fetch failures, setTimeout, event handlers).

```typescript
class RouteErrorBoundary extends React.Component<Props, State> {
  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, info: React.ErrorInfo) {
    // Log to error tracking, not console.error in production
    logger.error('Render error', { error, componentStack: info.componentStack });
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallback error={this.state.error} onRetry={this.reset} />;
    }
    return this.props.children;
  }
}
```

Place boundaries at route level (one per page) and around isolated expensive subtrees (charts, rich editors). Do not wrap every component — too granular breaks the benefit.

---

## Python: Exception Chaining

Python's `raise X from Y` syntax preserves causal chains — use it always when re-raising:

```python
class AppError(Exception):
    """Base error. All domain errors subclass this."""
    def __init__(self, message: str, code: str, status: int = 500):
        super().__init__(message)
        self.code = code
        self.status = status

class DatabaseError(AppError):
    def __init__(self, operation: str, cause: Exception):
        super().__init__(f"DB error during {operation}", "DB_ERROR", 503)
        self.__cause__ = cause  # explicit chain

# In application code
try:
    result = db.execute(query)
except psycopg2.OperationalError as e:
    raise DatabaseError("user_fetch", e) from e  # preserves full traceback
```

---

## Structured Error Logging

Log errors with enough context to diagnose without reading code:

```typescript
// Good: structured, queryable, developer-oriented
logger.error('Payment processing failed', {
  error: {
    code: error.code,
    message: error.message,
    stack: error.stack,
  },
  context: {
    userId,
    orderId,
    amount,
    paymentProvider,
    attempt: retryCount,
  },
  correlation: { requestId, traceId },
});

// Then surface a sanitized message to the user
// NEVER leak error.message to users — it may contain internals
return res.status(500).json({
  error: 'Payment could not be processed. Please try again.',
  errorId: requestId, // so support can look it up
});
```

---

## Anti-Patterns

### Anti-Pattern: Pokemon Exception Handling

**Novice**: "Wrap everything in `try/catch` and log the error. At least it won't crash."

**Expert**: Catching all exceptions unconditionally ("gotta catch 'em all") hides programmer errors, masks resource leaks, and converts loud failures into silent corruption. The system appears healthy while data is being silently dropped.

```typescript
// Wrong — swallows everything including programming errors
try {
  await processOrder(order);
} catch (e) {
  console.error('something went wrong', e); // lost forever
}

// Right — catch only what you can handle, let the rest propagate
try {
  await processOrder(order);
} catch (e) {
  if (e instanceof RateLimitError) {
    await queue.requeue(order, { delay: e.retryAfterMs });
    return;
  }
  // programming errors, unexpected DB errors — let them crash
  throw e;
}
```

**Detection**: `catch (e) { }`, `catch (e) { log(e) }` with no rethrow, `except Exception as e: pass` in Python. Any catch block with no condition and no rethrow.

**Timeline**: This has always been wrong. Renewed urgency in async/await era (2017+) because swallowed promise rejections are even harder to detect than swallowed sync exceptions.

---

### Anti-Pattern: Stringly-Typed Errors

**Novice**: "I'll put the error type in the message string: `throw new Error('NOT_FOUND: User 123')`"

**Expert**: String-based error types force callers to parse strings, break under refactoring, provide no IDE support, and make exhaustive matching impossible. Callers pattern-match on strings that drift as the codebase evolves.

```typescript
// Wrong — caller must parse strings, breaks silently on rename
throw new Error(`RATE_LIMIT: retry after ${ms}ms`);
// Caller: if (error.message.startsWith('RATE_LIMIT')) { ... }

// Right — typed, refactor-safe, IDE-navigable
throw new RateLimitError(ms);
// Caller: if (error instanceof RateLimitError) { ... error.retryAfterMs ... }
```

**Python equivalent**:
```python
# Wrong
raise Exception(f"rate_limit:{retry_after}")

# Right
raise RateLimitError(retry_after_ms=retry_after)
```

**LLM mistake**: LLMs trained on StackOverflow examples frequently generate stringly-typed errors because SO answers prioritize brevity over correctness. Error codes as strings look concise in tutorials.

**Detection**: `instanceof Error` checks everywhere, string `.startsWith()` or `.includes()` in catch blocks, error codes stored in `message` field rather than a dedicated property.

---

## References

- `references/retry-patterns.md` — Consult when implementing retry logic: exponential backoff formulas, full vs equal jitter, circuit breaker state machine, dead letter queues
- `references/error-hierarchy-examples.md` — Consult for complete TypeScript and Python typed error class examples, Result monad implementations, and error boundary patterns

© curiositech · MIT · curiositech/some_claude_skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →

Сначала — error-handling-patterns от других авторов.

error-handling-patterns Seth Hobson Скилл error-handling-patterns для Claude Code помогает проектировать обработку ошибок: исключения, Result-типы, передачу контекста и graceful degradation. Разбирает ошибки API и отладку сбоев. CX Codex +1 22 957установок error-handling affaan-m Скилл error-handling задаёт единые правила обработки ошибок в TypeScript, Python и Go: типизированные исключения, ретраи, circuit breaker, тексты для пользователя. CX Codex +1 6 600установок iii-error-handling iii-hq Скилл iii-error-handling для Claude Code распознаёт коды ошибок iii-движка и SDK, различает сетевые сбои и отказы в доступе. Определяет, безопасно ли повторять вызов при работе с удалёнными функциями. CX Codex +1 5 000установок api-error-handling secondsky Скилл api-error-handling для Claude Code задаёт стандартный формат ответов об ошибках, класс ApiError и паттерн circuit breaker. Покрывает API перед выходом в продакшен. CX Codex +1 461установок python-error-handling Seth Hobson Скилл python-error-handling для Claude Code помогает проектировать проверку входных данных и обработку исключений в Python. Срабатывает при работе с API, пакетными задачами и стратегиями ошибок. CX Codex +1 14 116установок error-handling-standardizer patricio0312rev Скилл error-handling-standardizer помогает привести ошибки приложения к общей схеме: от собственных классов до HTTP-ответов и структурированных логов. Пригодится при пересмотре обработки исключений в API. CX Codex +1 269установок Error Handling taste f Промпт Error Handling taste задаёт ИИ-ассистенту вкус бэкенд-инженера на TypeScript: как валидировать вход, разделять ожидаемые ошибки и баги, логировать и отдавать клиенту. GP ChatGPT ★ 178 201звёзд репо

Из того же набора180

Весь набор →
microservices-patterns Скилл microservices-patterns помогает выбирать границы микросервисов и способы связи между ними. Пригодится при разборе монолита или проектировании распределённой системы. CX Codex +1 142установок output-contract-enforcer Скилл output-contract-enforcer для Claude Code проверяет JSON-выход узлов DAG по схеме и выявляет несовместимость соседних узлов. Помогает найти причину неожиданных данных в следующем узле. CX Codex +1 141установок anthropic-technical-deep-dive Скилл anthropic-technical-deep-dive готовит к техническим интервью в Anthropic: Constitutional AI, RLHF, интерпретируемость, скейлинг-законы, MCP, агентные системы и безопасность ИИ. CX Codex +1 141установок human-gate-designer Скилл human-gate-designer проектирует точки human-in-the-loop для DAG-воркфлоу: что показать человеку, как собрать обратную связь и куда её направить. Пригодится при добавлении approval-гейтов в агентные пайплайны. CX Codex +1 141установок dependency-management Скилл dependency-management помогает выбирать, фиксировать и проверять сторонние библиотеки в кодовой базе. Направляет аудит уязвимостей и настройку обновлений. CX Codex +1 140установок component-template-generator Скилл component-template-generator для Claude Code создаёт шаблоны компонентов React, Vue и Svelte с дизайн-токенами. Он включается при разработке библиотеки компонентов или переносе дизайн-системы в код. CX Codex +1 139установок recursive-synthesis Скилл recursive-synthesis оркестрирует мультиагентный синтез документов через 6 фаз: от расходящихся позиций до финального документа. Подходит для конституций, хартий и архитектурных решений. CX Codex +1 138установок ultimate-seo-geo-skill Скилл ultimate-seo-geo-skill гоняет SEO-аудит сайта по 21 модулю и ставит оценку от 0 до 100, а потом собирает план правок и готовый код: schema, hreflang, robots.txt. CX Codex +1 121установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой