safe-error-handling-plus

Built on affaan-m/ECC by @affaan-m (254,945 stars, MIT). All credit for the original idea to them. This fork improves and repackages it; upstream license preserved in UPSTREAM_LICENSE.

A Claude Code skill that helps developers write safe, clear errors for TypeScript, Python, Go, APIs, logs, retries, and user messages.

💡 Why

Bad errors can leak secrets and private data.
Text checks break when a message changes.
Lost root errors make bugs hard to fix.
Blind retries can repeat a write or charge.
This skill gives Claude clear rules for each case.

🚀 Install

Run this one command:

mkdir -p ~/.claude/skills/error-handling && curl -fsSL https://raw.githubusercontent.com/safe-error-handling-plus/safe-error-handling-plus/main/skill/SKILL.md -o ~/.claude/skills/error-handling/SKILL.md

The skill is one file. It needs no extra package.

🧭 Usage

Ask Claude Code to use the skill while you work:

Use the error-handling skill to review this API route.

Add typed errors and one safe JSON error shape.
Keep public error codes stable.
Do not leak secrets, stack traces, SQL, file paths, or service replies.
Preserve the first error when wrapping it.

Expected result:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found",
    "details": []
  }
}

Claude should also:

1. Use error types or codes instead of text checks.
2. Keep the first error as the cause.
3. Log an unknown error once at the service edge.
4. Test both success and failure paths.
5. Check if a retry could repeat a write or charge.

The skill plugs into your normal Claude Code flow. Use it when you add a service, review an API, call a database, add retries, or fix hidden errors.

🔧 What we changed vs upstream

• Rewritten from Japanese into simpler English, with clearer activation guidance and more direct, testable rules.
• Added explicit security guidance forbidding secrets, private data, stack traces, SQL, paths, and upstream service replies in errors or logs.
• Added an upfront error-design checklist plus a standard public JSON error shape and guidance to keep error codes stable.
• Enhanced TypeScript errors with native cause chaining and stressed preserving the original error when wrapping it.
• Changed the Result example from a database call to input parsing and added a rule against mixing result values with thrown errors in one layer without a clear convention.

📄 License

Released under the MIT License. The upstream MIT license and credit are preserved in UPSTREAM_LICENSE.