Claude-skill-registry error-handling-and-messages

Next.js(App Router) の Server Actions を前提とした、エラーハンドリングと表示メッセージの統一ルール。

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/error-handling-and-messages" ~/.claude/skills/majiayu000-claude-skill-registry-error-handling-and-messages && rm -rf "$T"

manifest: skills/data/error-handling-and-messages/SKILL.md

source content

エラーハンドリング & メッセージ設計（SSoT）

このスキルは、Network Boundary を跨ぐエラーの扱いと、ユーザー向けメッセージの一元管理を徹底するための規約です。アプリ全体のエラーメッセージは

src/domain/errors/error-messages.ts

を単一の正解 (SSoT) とします。

1. 基本方針（必須）

例外をそのままクライアントに渡さない
Server Action から
```
Error.message
```
を直接表示しない。Network Boundary を跨いだ
```
Error
```
は production で秘匿される。
Server Action は「表示可能なエラー」を値として返す
例外は
```
Result
```
形式（
```
success
```
/
```
failure
```
）に畳み込み、
```
message
```
は 安全に表示できる文言に限定する。
表示メッセージは必ず
ERROR_MESSAGES
を経由
直接の日本語文字列を散在させない。
内部詳細はログに集約
スタックトレースや技術情報はサーバー側でログ化し、ユーザー表示には出さない。

2. 推奨パターン

2.1 Server Action の戻り値

返却は

ServerActionResult<T>

を基本形とする（

src/lib/async-handler.ts

）。

成功時は
```
{ success: true, data?: T }
```
（削除系などは
```
data
```
省略可）。

失敗時は

{ success: false, error: string }

とし、

error

は

ERROR_MESSAGES

から生成する。

必要に応じて
```
needsReauth
```
/
```
requiresSubscription
```
などの追加フィールドを許容する。
参考:
```
ServerActionResult
```
の型定義

export interface ServerActionResult<T> {
  success: boolean;
  data?: T;
  error?: string;
}

2.2 クライアント側の共通ハンドリング

取得/更新の実行は
```
handleAsyncAction
```
で統一する（
```
src/lib/async-handler.ts
```
）。
```
onSuccess
```
/
```
setLoading
```
/
```
setMessage
```
で UI 状態とメッセージを集中管理する。
参考: 実装例（
```
src/hooks/useGscSetup.ts
```
と同型の最小パターン）

await handleAsyncAction(fetchGscStatus, {
  onSuccess: data => setStatus(data as GscConnectionStatus),
  setLoading: setIsSyncingStatus,
  setMessage: setAlertMessage,
  defaultErrorMessage: ERROR_MESSAGES.GSC.STATUS_FETCH_FAILED,
});

2.3 メッセージ管理

表示メッセージは
```
ERROR_MESSAGES
```
を唯一の参照元とする。
Server Action 側で文言を確定し、クライアントは
```
result.error
```
を表示するだけに留める。

2.4 例外の扱い（Server Action 側）

例外は
```
try/catch
```
で捕捉し、
```
{ success: false, error }
```
に畳み込む。
技術的詳細はログに集約し、ユーザー向けには安全な文言のみ返す。

3. 実装ルール（必須）

メッセージ追加は
src/domain/errors/error-messages.ts
に集約
Server Action は
Error
を throw せず
{ success: false, error }
を返す
クライアントは
result.error
を表示するだけに留める
handleAsyncAction
を使い UI 状態とメッセージ処理を統一する

4. アンチパターン

Client Component で
```
Error.message
```
を直接表示する
Server Action で例外をそのまま throw する
メッセージ文字列を任意のファイルに直接書く
```
handleAsyncAction
```
を使わずに各所でエラーハンドリングを分散させる

5. セルフレビュー項目

```
ERROR_MESSAGES
```
に追加した文言が他用途で重複しないか
Server Action の返却が
```
ServerActionResult
```
の形に沿っているか
Network Boundary 越しに
```
Error.message
```
を使っていないか
```
handleAsyncAction
```
で UI 側の処理が統一されているか