Guide

---
title: "ガイド：単一スキル実行"
description: oh-my-agentの単一ドメインタスク詳細ガイド。使用条件、プリフライトチェックリスト、プロンプトテンプレート、フロントエンド・バックエンド・モバイル・データベースの実例、実行フロー、品質ゲートチェックリスト、エスカレーションシグナルを解説します。
---

# ガイド：単一スキル実行

単一スキル実行は最短経路です。1つのエージェント、1つのドメイン、1つの集中したタスク。オーケストレーションのオーバーヘッドもマルチエージェント協調もありません。自然言語プロンプトからスキルが自動アクティベートされます。

---

## 使うべきタイミング

タスクが以下のすべての基準を満たす場合に使用します：

- **1つのドメインが所有**: タスク全体がフロントエンド、バックエンド、モバイル、データベースなど単一ドメインに属する
- **自己完結**: クロスドメインのAPIコントラクト変更なし
- **スコープが明確**: 出力が明確（コンポーネント、エンドポイント、スキーマ、修正）
- **協調不要**: 他のエージェントの事前/事後実行が不要

**マルチエージェント**（`/work`または`/orchestrate`）に切り替えるべき場合：
- UI作業に新しいAPIコントラクトが必要（フロントエンド + バックエンド）
- 1つの修正がレイヤーをまたいで波及（デバッグ + 実装エージェント）
- 機能がフロントエンド、バックエンド、データベースにまたがる
- 最初のイテレーション後にスコープが1つのドメインを超えて拡大

---

## プリフライトチェックリスト

プロンプト前に以下の4要素を確認します（[プロンプト構造](/docs/core-concepts/skills)の4要素に対応）：

| 要素 | 質問 | 重要な理由 |
|---------|----------|----------------|
| **Goal** | 何を作成または変更するか？ | 曖昧さを排除 |
| **Context** | どのスタック、フレームワーク、規約が適用されるか？ | エージェントはプロジェクトファイルから検出するが、明示する方が確実 |
| **Constraints** | どのルールに従うべきか？（スタイル、セキュリティ、パフォーマンス） | 制約なしではプロジェクトに合わないデフォルトが使用される |
| **Done When** | どの受入基準で確認するか？ | エージェントに目標を、あなたに検証チェックリストを提供 |

## プロンプトテンプレート

```text
<スタック>を使って<具体的な成果物>を構築してください。
制約: <スタイル/パフォーマンス/セキュリティの制約>。
受入基準:
1) ...
2) ...
以下のテストを追加: <重要なケース>。
```

### テンプレートの分解

- **スタック宣言**: エージェントがプロジェクトを解析する手間を省きます。
- **明示的な制約**: 既定のフォームライブラリやアーキテクチャパターンを禁止します。
- **番号付き受入基準**: エージェントの検証チェックリストになります。
- **テスト要件**: 適切な振る舞いを保証するエッジケースを規定します。

## 実例

### Frontend：ログインフォーム

```text
React + TypeScript + Tailwind CSSでログインフォームコンポーネントを作成してください。
制約：アクセシブルなラベル、Zodによるクライアントサイドバリデーション、@tanstack/react-form以外の外部フォームライブラリ不使用、shadcn/uiのButtonとInputコンポーネントを使用。
受入基準：
1) 意味のあるエラーメッセージ付きのメールバリデーション
2) フィードバック付きで最低8文字のパスワード
3) フォームが無効な間はサブミットボタンを無効化
4) キーボードとスクリーンリーダーに対応（ARIAラベル、フォーカス管理）
5) 送信中のローディング状態
有効な送信パス、無効なメール、短いパスワード、ローディング状態のユニットテストを追加。
```

**想定される実行フロー：**

1. **スキルアクティベーション：** `oma-frontend`がアクティベート（キーワード：「form」「component」「Tailwind CSS」「React」）
2. **難易度評価：** Medium（2〜3ファイル、バリデーションUXまわりの設計判断）
3. **ロードされるリソース：** `execution-protocol.md`、`snippets.md`（フォーム + Zodパターン）、`component-template.tsx`
4. **CHARTER_CHECK出力：** clarification LOW、ドメインfrontend、Must NOT doはバックエンドAPI/データベース/モバイル
5. **実装：** `src/features/auth/components/login-form.tsx`（`"use client"`付きClient Component）、Zodスキーマ、Skeleton、`@tanstack/react-form`、shadcn/ui、絶対インポート`@/`
6. **検証：** ARIAラベル、キーボードナビゲーション、320pxビューポート、CLSなし、Vitestテスト

### Backend：REST APIエンドポイント

```text
認証済みユーザーのタスクを返すページネーション付きGET /api/tasksエンドポイントを追加してください。
制約：Repository-Service-Routerパターン、パラメータ化クエリ、JWT認証必須、カーソルベースのページネーション。
受入基準：
1) 認証済みユーザーが所有するタスクのみ返す
2) next/prevカーソル付きカーソルベースページネーション
3) ステータス（todo、in_progress、done）でフィルタ可能
4) レスポンスにtotal countを含む
認証必須、ページネーション、ステータスフィルタ、空結果のテストを追加。
```

**想定される実行フロー：**

1. **スキルアクティベーション：** `oma-backend`がアクティベート（キーワード：「API」「endpoint」「REST」）
2. **スタック検出：** `pyproject.toml`または`package.json`を読んで言語/フレームワークを判定。`stack/`が存在すればそこから規約をロード
3. **難易度評価：** Medium（route、service、repository、テストの2〜3ファイル）
4. **CHARTER_CHECK：** ドメインbackend、Must NOT doはフロントエンドUI/モバイル/スキーマ変更
5. **実装：** Repository（`TaskRepository.find_by_user`、パラメータ化クエリ）、Service（ビジネスロジックラッパー）、Router（JWT認証ミドルウェア、入力バリデーション）
6. **テスト：** 認証なしは401、ページネーションのカーソル、フィルタ動作、空配列の200

### Mobile：設定画面

```text
プロフィール編集（名前、メール、アバター）、通知設定（トグルスイッチ）、ログアウトボタン付きの設定画面をFlutterで構築してください。
制約：状態管理にRiverpod、ナビゲーションにGoRouter、Material Design 3、オフライン時の優雅な処理。
受入基準：
1) ユーザーデータからプロフィールフィールドを事前入力
2) ローディングインジケーター付きで送信時に保存
3) 通知トグルをローカルに永続化（SharedPreferences）
4) ログアウトでトークンストレージをクリアしてログインに遷移
5) オフライン：「offline」バナー付きでキャッシュデータを表示
プロフィール保存、ログアウトフロー、オフライン状態のテストを追加。
```

**想定される実行フロー：**

1. **スキルアクティベーション：** `oma-mobile`がアクティベート（キーワード：「Flutter」「screen」「mobile」）
2. **難易度評価：** Medium（設定画面 + 状態管理 + オフライン処理）
3. **ロードされるリソース：** `execution-protocol.md`、`snippets.md`、`screen-template.dart`
4. **CHARTER_CHECK：** ドメインmobile、Must NOT doはバックエンドAPI変更/Webフロント/スキーマ
5. **実装：** Screen（Stateless Widget + Riverpod）、Providers、Repository、オフライン処理（DioインターセプターでSocketExceptionを捕捉してキャッシュにフォールバック）、すべてのコントローラーは`dispose()`で破棄

### Database：スキーマ設計

```text
マルチテナントSaaSプロジェクト管理ツールのデータベーススキーマを設計してください。エンティティ：Organization、Project、Task、User、TeamMembership。
制約：PostgreSQL、3NF、deleted_atによるソフト削除、監査フィールド（created_at、updated_at、created_by）、テナント分離のための行レベルセキュリティ。
受入基準：
1) すべてのリレーションを文書化したERD
2) 外部・概念・内部スキーマ層を文書化
3) 一般的なクエリパターン（プロジェクト別タスク、担当者別タスク）のためのインデックス戦略
4) 1万org、10万ユーザー、100万タスク向けのキャパシティ見積もり
5) フル + 増分のバックアップ戦略
データ標準テーブル、用語集、マイグレーションスクリプトを成果物に追加。
```

**想定される実行フロー：**

1. **スキルアクティベーション：** `oma-db`がアクティベート（キーワード：「database」「schema」「ERD」「migration」）
2. **難易度評価：** Complex（アーキテクチャ判断、複数エンティティ、キャパシティ計画）
3. **ロードされるリソース：** `execution-protocol.md`、`document-templates.md`、`examples.md`、`anti-patterns.md`
4. **CHARTER_CHECK：** ドメインdatabase、Must NOT doはAPI実装/フロントUI/インフラ
5. **ワークフロー：** 探索（エンティティ、リレーション、アクセスパターン、ボリューム）→ 設計（外部/概念/内部スキーマ、制約、ライフサイクル）→ 最適化（インデックス、パーティショニング、バックアップ、アンチパターンレビュー）
6. **成果物：** 外部スキーマサマリ（ロール別ビュー）、ERD付き概念スキーマ、物理DDLとインデックスの内部スキーマ、データ標準テーブル、用語集、キャパシティ見積もり、バックアップ戦略、マイグレーションスクリプト

---

## 品質ゲートチェックリスト

### 全エージェント共通

- [ ] **動作が受入基準に合致**: プロンプトのすべての基準を満たしている
- [ ] **テストがハッピーパスと主要なエッジケースをカバー**
- [ ] **無関係なファイル変更なし**: タスクに関連するファイルのみ変更
- [ ] **共有モジュールが壊れていない**: インポート、型、インターフェースが正常
- [ ] **チャーターが遵守された**: 「Must NOT do」の制約が守られている
- [ ] **lint、typecheck、ビルドがパス**

### フロントエンド固有

- [ ] アクセシビリティ：`aria-label`、セマンティック見出し、キーボードナビゲーション
- [ ] モバイル：320px、768px、1024px、1440pxで正しくレンダリング
- [ ] パフォーマンス：CLSなし、FCPターゲット達成
- [ ] Error BoundariesとLoading Skeletons実装
- [ ] shadcn/uiコンポーネントを直接変更していない（ラッパーを使用）

### バックエンド固有

- [ ] クリーンアーキテクチャ維持：ルートハンドラにビジネスロジックなし
- [ ] すべての入力がバリデーション済み
- [ ] パラメータ化クエリのみ（SQLでの文字列補間なし）
- [ ] 認証エンドポイントにレート制限

### モバイル固有

- [ ] すべてのコントローラーが`dispose()`で破棄
- [ ] オフラインが適切に処理
- [ ] 60fpsターゲット維持

### データベース固有

- [ ] 3NF以上（非正規化の場合は根拠を文書化）
- [ ] 3つのスキーマ層すべてを文書化（外部、概念、内部）
- [ ] アンチパターンレビュー完了

---

## エスカレーションシグナル

| シグナル | 意味 | 対応 |
|--------|--------------|--------|
| エージェントが「バックエンドの変更が必要」と言う | クロスドメイン依存関係 | `/work`に切り替え |
| CHARTER_CHECKの「Must NOT do」に実際に必要な項目がある | スコープが1ドメインを超過 | `/plan`で機能全体を計画 |
| 修正が3つ以上の異なるレイヤーのファイルに波及 | 複数ドメインに影響 | `/debug`でスコープ拡大、または`/work` |
| APIコントラクトの不一致を発見 | フロントエンド/バックエンドの不整合 | `/plan`でコントラクト定義後、両エージェントを再スポーン |
| 品質ゲートが統合ポイントで失敗 | コンポーネントが正しく接続されない | QAレビュー追加：`oma agent:spawn qa "Review integration"` |
| タスクが「1コンポーネント」から「3コンポーネント + 新ルート + API」に膨張 | 実行中のスコープクリープ | 停止、`/plan`で分解、`/orchestrate`で実行 |
| エージェントがHIGH明確化でブロック | 要件が根本的に曖昧 | エージェントの質問に回答、または`/brainstorm`で方針を明確化 |

### 一般ルール

同じエージェントを修正付きで2回以上再スポーンしている場合、タスクはおそらくマルチドメインであり、`/work`または少なくとも`/plan`での分解が必要です。