error-message-design
ユーザーフレンドリーなエラーメッセージの設計を専門とするスキル。エラーコード体系、多言語対応（i18n）、アクション指向のメッセージ設計を提供。Anchors:- The Pragmatic Programmer / 適用: 実践的改善 / 目的: 品質維持- Nielsen Norman Group UX Guidelines / 適用: エラーメッセージ設計 / 目的: ユーザビリティ向上Trigger:Use when designing error messages, creating error code systems, implementing i18n for errors, or building user-friendly error responses.error message, error code, i18n, user-friendly, validation error, API error response
When & Why to Use This Skill
This Claude skill specializes in designing user-centric error messages and robust error code architectures. It bridges the gap between technical requirements and user experience by transforming cryptic system errors into clear, actionable, and multi-language (i18n) feedback. By following industry standards like the Nielsen Norman Group UX Guidelines, it ensures that error handling improves product usability and reduces customer support tickets.
Use Cases
- Standardizing API Error Systems: Designing a consistent error code hierarchy and response structure for complex backend architectures.
- Improving UX Microcopy: Rewriting technical stack traces or vague 'Internal Server Error' messages into helpful, human-readable instructions that guide users to a resolution.
- Internationalization (i18n) Planning: Implementing multi-language support for error messages to ensure a consistent experience for a global user base.
- Validation and Quality Assurance: Auditing existing error message catalogs against the three core principles: explaining what happened, why it happened, and how to fix it.
| name | error-message-design |
|---|---|
| description | | |
| - The Pragmatic Programmer / 適用 | 実践的改善 / 目的: 品質維持 |
| - Nielsen Norman Group UX Guidelines / 適用 | エラーメッセージ設計 / 目的: ユーザビリティ向上 |
Error Message Design
概要
ユーザーフレンドリーなエラーメッセージの設計を専門とするスキル。 エラーコード体系、多言語対応（i18n）、アクション指向のメッセージ設計を 通じて、ユーザー体験を向上させる。
ワークフロー
Phase 1: エラーメッセージ設計
目的: エラータイプを分類し、メッセージを設計する
アクション:
- エラー発生シナリオを分析
- エラーコード体系を設計
- ユーザー向けメッセージを作成
- 多言語対応を考慮
Task: agents/design-error-messages.md を参照
Phase 2: エラーシステム実装
目的: 設計に基づきエラーシステムを実装する
アクション:
- エラークラス/型を定義
- メッセージカタログを実装
- i18n翻訳リソースを作成
- エラーハンドラーを実装
Task: agents/implement-error-messages.md を参照
Phase 3: 検証と記録
目的: エラーメッセージの品質を検証する
アクション:
scripts/validate-error-messages.mjsで検証- ユーザビリティチェックを実施
scripts/log_usage.mjsで記録
Task仕様ナビ
| Task | 起動タイミング | 入力 | 出力 |
|---|---|---|---|
| design-error-messages | 設計時 | エラー要件 | エラーメッセージ仕様 |
| implement-error-messages | 実装時 | エラーメッセージ仕様 | エラーシステム実装 |
詳細仕様: 各Taskの詳細は agents/ ディレクトリを参照
エラーメッセージの3原則
1. 何が起きたかを説明
悪い例: "Error occurred" 良い例: "Your session has expired"
2. なぜ起きたかを説明
悪い例: "Invalid input" 良い例: "The email address format is incorrect"
3. どうすれば解決できるかを説明
悪い例: "Please try again" 良い例: "Please enter a valid email (example: user@domain.com)"
ベストプラクティス
すべきこと
- ユーザーが理解できる言葉を使用
- 具体的なアクションを提示
- エラーコードで問い合わせを容易に
- 多言語対応を考慮した設計
避けるべきこと
- 技術用語の露出（SQLException, NullPointer等）
- スタックトレースの表示
- ユーザーを責める表現
- 曖昧な表現（「問題が発生しました」）
リソース参照
agents/（Task仕様書）
| Task | パス | 用途 |
|---|---|---|
| 設計 | See agents/design-error-messages.md | メッセージ設計 |
| 実装 | See agents/implement-error-messages.md | システム実装 |
references/（詳細知識）
| リソース | パス | 用途 |
|---|---|---|
| ユーザーメッセージ | See references/user-friendly-messages.md | メッセージ設計指針 |
| エラーコード体系 | See references/error-code-system.md | コード設計 |
| i18n対応 | See references/i18n-error-handling.md | 多言語対応 |
| APIレスポンス | See references/api-error-responses.md | レスポンス形式 |
scripts/（決定論的処理）
| スクリプト | 用途 | 使用例 |
|---|---|---|
validate-error-messages.mjs |
メッセージ検証 | node scripts/validate-error-messages.mjs |
log_usage.mjs |
フィードバック記録 | node scripts/log_usage.mjs --result success |
assets/（テンプレート）
| テンプレート | 用途 |
|---|---|
error-system-template.ts |
エラーシステム実装テンプレート |
変更履歴
| Version | Date | Changes |
|---|---|---|
| 2.0.0 | 2026-01-01 | agents追加、Level1-4削除、18-skills.md仕様完全準拠 |
| 1.0.0 | 2025-12-24 | 初版作成 |