# API/インターフェース設計 (api-and-interface-design)

> 契約優先、一貫したエラー、境界での検証、追加による拡張で、安定して誤用しにくい API とインターフェースを設計します。

- カテゴリ: [アーキテクチャ設計](https://www.myskills.tools/ja/categories/architecture/)
- 提供元: コミュニティ · Addy Osmani
- リポジトリ: https://github.com/addyosmani/agent-skills/tree/main/skills/api-and-interface-design (commit 63128d0)
- SKILL.md: https://github.com/addyosmani/agent-skills/blob/main/skills/api-and-interface-design/SKILL.md
- インストールコマンド: `npx skills add addyosmani/agent-skills --skill api-and-interface-design`
- ライセンス: MIT
- 対応ツール: Claude Code, Codex, Cursor, Copilot, Gemini CLI
- 権限: read-repo ✓, write-files ✓, shell ✗, network ✗
- 状態: スキャン済み
- ルールスキャンですべてのリスクを検出できるわけではありません。インストール前にこのスキルの SKILL.md を読み、権限を確認してください。

## 基本ルール

ハイラムの法則により観測できる挙動はすべて誰かに依存されるため、公開するものを意図的に選びます。

## 実行フェーズ

1. **契約を先に定義** — 実装前に型付きの入出力インターフェースを定義し、契約を仕様とします。
2. **エラーと検証を統一** — 全エンドポイントで同じエラー形式を使い、入力の検証はシステム境界だけで行い、外部 API の応答は常に信頼しません。
3. **拡張前提で設計** — 新しいフィールドは任意にし、型変更や削除はしません。単一バージョンの原則、一貫した命名、一覧エンドポイントのページングを守ります。
4. **冪等キーを守る** — 冪等キーは試行ではなく意図から作り、一意制約で原子的に確保し、同じキーで本文が違えば明示的に失敗させ、保持期間は最長の再試行経路に合わせます。
5. **チェックリスト確認** — 各エンドポイントに型付きの入出力があり、エラー形式が統一され、変更が後方互換で、型やドキュメントが実装と一緒にコミットされていることを確認します。

## 権限の説明（SKILL.md より）

| 機能 | 必要か | 説明 |
|---|---|---|
| ファイル書き込み | 必要 | インターフェースの型、スキーマ定義、API の処理コード、付随するドキュメントを書きます。 |
| コマンド実行 | 不要 | コマンドの実行は求めていません。 |
| 外部通信 | 不要 | ネットワークにはアクセスしません。 |

## SKILL.md のフロントマター（YAML）

```yaml
---
name: api-and-interface-design
description: Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
---
```

ホーム: https://www.myskills.tools/ja/ · URL: https://www.myskills.tools/ja/skills/api-and-interface-design/