ベストプラクティス
ベストプラクティス
このドキュメントでは、Oh My OpenCodeを使用するためのベストプラクティスと効率的なパターンを共有し、マルチエージェント・コラボレーションの力を最大限に活用できるようにします。
ultrawork 魔法のキーワード
ultraworkとは？
ultrawork（略して ulw）は、Oh My OpenCodeの魔法のキーワードです。タスクの説明にこの単語を追加すると、すべての高度な機能が自動的に有効になります。
有効になる機能
ultrawork を使用すると、システムは自動的に以下を有効にします：
- ✅ すべての構成済み専門エージェント
- ✅ バックグラウンドタスクの並列実行
- ✅ 完全な LSP ツール統合
- ✅ インテリジェントなコンテキスト管理
- ✅ AST-Grep コード検索
- ✅ 自動タスク分解と調整
使用例
# フル形式
opencode "ultrawork: ユーザー認証システムをリファクタリングし、OAuth2サポートを追加して"
# 短縮形式
opencode "ulw: プロジェクト全体に TypeScript 型を追加して"
# エージェントとの組み合わせ
opencode "ultrawork: @oracle マイクロサービスアーキテクチャを設計して"いつ使用するか
ultrawork の使用が推奨される場面:
- 🏗️ 大規模なリファクタリングタスク
- 🌐 フルスタック機能開発
- 📚 複雑な問題の分析
- 🎯 マルチステップの実装タスク
ultrawork が不要な場面:
- 🔍 単純なクエリ
- ✏️ 小規模な修正
- 📖 単一ファイルの編集
- ❓ Q&A 形式のリクエスト
マルチエージェント・コラボレーションパターン
パターン 1：順次コラボレーション
ユースケース：明確な順次依存関係があるタスク
# ステップ 1：アーキテクチャ設計
opencode "@oracle ユーザー権限システムのアーキテクチャを設計して"
# ステップ 2：ドキュメント調査
opencode "@librarian RBAC と ABAC のベストプラクティスを調査して"
# ステップ 3：実装
opencode "@backend-engineer @oracle の設計に基づいて権限システムを実装して"利点:
- 責任分担が明確
- 各ステップの結果を個別にレビュー可能
- 問題の追跡が容易
パターン 2：並列コラボレーション
ユースケース：サブタスクが比較的独立しており、同時に進行可能な場合
# ultrawork を使用して自動並列化
opencode "ulw: フロントエンド UI とバックエンド API を含むユーザーダッシュボード機能を開発して"
# Sisyphus が自動的に割り当て：
# - @frontend-engineer: UI コンポーネントの実装
# - @backend-engineer: API エンドポイントの実装
# - @librarian: ベストプラクティスの調査利点:
- 効率が劇的に向上
- 自動的な調整と統合
- 時間に制約のあるタスクに適している
パターン 3：階層的コラボレーション
ユースケース：異なるレベルの意思決定と実装が必要な場合
# レイヤー 1：戦略的意思決定
opencode "@oracle REST から GraphQL への移行を評価して"
# レイヤー 2：技術調査
opencode "@librarian GraphQL エコシステムとツールチェーンを調査して"
# レイヤー 3：プロトタイプ開発
opencode "@backend-engineer GraphQL プロトタイプを実装して"
# レイヤー 4：検証テスト
opencode "@explore プロトタイプのパフォーマンスと保守性を分析して"適切なエージェントの選択
| タスクの種類 | プライマリエージェント | 代替案 | 備考 |
|---|---|---|---|
| アーキテクチャの決定 | @oracle | - | 最強のシステム思考 |
| ドキュメント作成 | @document-writer | @librarian | Document Writer は技術ライティングに集中 |
| ドキュメント調査 | @librarian | - | 情報の検索と整理に優れている |
| UI/UX デザイン | @frontend-ui-ux-engineer | @frontend-engineer | ユーザーエクスペリエンスに焦点を当てる |
| フロントエンド開発 | @frontend-engineer | @frontend-ui-ux-engineer | フロントエンドの技術エキスパート |
| API 開発 | @backend-engineer | - | バックエンドのエキスパート |
| バグのデバッグ | @explore | @oracle | Explore はコード分析に優れている |
| パフォーマンス最適化 | @oracle | @explore | Oracle が戦略を提供し、Explore が詳細を分析 |
| ビジュアル分析 | @multimodal-looker | - | デザインカンプや UI スクリーンショットを分析 |
コンテキスト管理のベストプラクティス
AGENTS.md 階層システム
階層的なコンテキストルールを適切に使用します：
グローバルルール (プロジェクトルート)
<!-- project/AGENTS.md -->
# グローバル開発基準
## 一般的なルール
- TypeScript の厳格モードを使用する
- すべての関数に型注釈を付ける
- ESLint と Prettier を使用する
## コミット基準
- Conventional Commits に従う
- すべてのコミットはすべてのテストに合格する必要があるモジュールルール (src ディレクトリ)
<!-- project/src/AGENTS.md -->
# ソースコード基準
## コードの整理
- 型ごとではなく、機能モジュールごとに整理する
- 各モジュールには index.ts のエクスポートを含める
## テスト要件
- コアビジネスロジックにはユニットテストが必要
- カバレッジは 80% 以上コンポーネントルール (components ディレクトリ)
<!-- project/src/components/AGENTS.md -->
# React コンポーネント基準
## when: file.ext == "*.tsx"
- 関数コンポーネントと Hooks を使用する
- Props は TypeScript インターフェースを定義する必要がある
- スタイル管理には CSS Modules を使用する
## when: agent == "@frontend-engineer"
- 会社の UI デザインシステムに従う
- Storybook でコンポーネントをドキュメント化する条件付きルールの使用
ファイルタイプによるアクティブ化
## when: file.ext == "*.test.ts"
Jest と React Testing Library を使用する
AAA パターンに従う (Arrange, Act, Assert)
## when: file.ext == "*.spec.ts"
E2E テストに Cypress を使用するエージェントタイプによるアクティブ化
## when: agent == "@oracle"
詳細な技術的決定の根拠を提供する
長期的な保守性を考慮する
## when: agent == "@frontend-engineer"
ユーザーエクスペリエンスを優先する
アクセシビリティ (a11y) 基準に従うタスクフェーズによるアクティブ化
## when: phase == "design"
アーキテクチャ図と技術選定ドキュメントを出力する
## when: phase == "implementation"
テスト可能なコードを書く
必要なコメントを追加するバックグラウンドタスクの使用ヒント
同時実行数を適切に設定する
サブスクリプションプランに応じて調整します：
Claude Max20 の設定:
{
"sisyphus": {
"max_concurrent_tasks": 3
}
}ChatGPT Plus / Gemini の設定:
{
"sisyphus": {
"max_concurrent_tasks": 2
}
}無料または制限付きプラン:
{
"sisyphus": {
"max_concurrent_tasks": 1
}
}バックグラウンドタスクのユースケース
バックグラウンド実行に適しているもの:
- 📖 ドキュメント調査
- 🔍 コードベース分析
- 📊 パフォーマンスベンチマーク
- 🧪 テスト実行
- 📝 補助的なドキュメント生成
バックグラウンド実行に適さないもの:
- ✏️ 直接的なコード修正
- 🚀 クリティカルパスのタスク
- 👤 ユーザーの確認が必要な操作
バックグラウンドタスクの監視
# 現在実行中のバックグラウンドタスクの状態を表示
opencode "すべてのバックグラウンドタスクの状態を表示して"
# 特定のバックグラウンドタスクをキャンセル
opencode "タスク ID: abc123 をキャンセルして"
# すべてのバックグラウンドタスクが完了するのを待つ
opencode "すべてのバックグラウンドタスクが完了するまで待ってから続けて"コード品質管理戦略
コメントの自動チェック
必要なコメントを自動的に追加するようにエージェントを構成します：
{
"code_quality": {
"enforce_comments": true,
"comment_rules": {
"functions": "複雑度 > 10 の場合はコメントが必要",
"classes": "パブリッククラスにはコメントが必要",
"exports": "エクスポートされた関数/クラスにはコメントが必要"
}
}
}コードレビューの統合
エージェントにコードレビューを依頼します：
# 特定のファイルをレビュー
opencode "@oracle src/auth/login.ts のコード品質をレビューして"
# PR 全体をレビュー
opencode "ulw: 現在のブランチのすべての変更をレビューして"
# セキュリティ問題のチェック
opencode "@explore コードのセキュリティ脆弱性をチェックして"Todo 継続実行器
Todo システムを使用して長期的なタスクを追跡します：
# Todo を作成
opencode "todo を作成：ユーザー認証モジュールのリファクタリング"
# Todo を表示
opencode "未完了の todo をすべてリストして"
# Todo の実行を継続
opencode "todo の実行を継続：ユーザー認証モジュールのリファクタリング"パフォーマンス最適化の推奨事項
モデル選択の最適化
タスクごとに異なるモデルを使用します：
{
"agents": {
"oracle": {
"model": "claude-sonnet-4", // 複雑な決定には最強のモデルを使用
"temperature": 0.7
},
"explore": {
"model": "claude-sonnet-3.5", // コード分析には中級モデルを使用
"temperature": 0.3
},
"librarian": {
"model": "gpt-4-turbo", // ドキュメント調査には他のモデルを使用可能
"temperature": 0.5
}
}
}トークン使用量の制御
{
"token_management": {
"max_context_tokens": 4096,
"summarize_long_context": true,
"cache_common_queries": true
}
}タスク説明の最適化
❌ 曖昧な説明:
opencode "コードを改善して"✅ 明確な説明:
opencode "@explore UserService.ts のパフォーマンスのボトルネックを分析し、その後 @backend-engineer がデータベースクエリを最適化して"キャッシュの使用
{
"caching": {
"enabled": true,
"cache_lsp_results": true,
"cache_duration": 3600, // 1時間
"cache_directory": ".opencode/cache"
}
}よくある落とし穴と解決策
落とし穴 1：ultrawork の使いすぎ
問題: 単純なタスクにも ultrawork を使用し、リソースを浪費する
解決策:
# ❌ 使いすぎ
opencode "ulw: package.json の内容を表示して"
# ✅ 単純なタスクの直接実行
opencode "package.json を表示して"落とし穴 2：不適切なエージェントの選択
問題: 不適切なエージェントにタスクを実行させる
解決策:
# ❌ 不適切な選択
opencode "@librarian React コンポーネントを実装して"
# ✅ 適切な選択
opencode "@frontend-engineer React コンポーネントを実装して"落とし穴 3：コンテキスト管理の無視
問題: プロジェクトに AGENTS.md を構成していない
解決策: 階層的な AGENTS.md ファイルを作成して必要なコンテキストを提供します
落とし穴 4：同時実行タスクが多すぎる
問題: max_concurrent_tasks を高く設定しすぎて API レート制限が発生する
解決策: 実際のサブスクリプションプランに基づいて同時実行数を調整します
実践的なヒントのまとめ
クイックスタートテンプレート
# 新機能開発
opencode "ulw: @oracle が [機能名] のアーキテクチャを設計し、 @librarian が関連技術を調査し、 @frontend-engineer と @backend-engineer が並行して実装して"
# バグ修正
opencode "@explore [バグの説明] の根本原因を分析し、その後修正して"
# コードレビュー
opencode "@oracle 現在の PR のアーキテクチャの妥当性をレビューし、 @explore が潜在的な問題をチェックして"
# ドキュメント作成
opencode "@librarian プロジェクト構造を調査し、その後完全な README.md を書いて"効率向上のチェックリスト
- ✅ プロジェクトに AGENTS.md 階層ルールを構成した
- ✅ サブスクリプションプランに基づいて同時実行数を調整した
- ✅ 複雑なタスクに ultrawork を使用した
- ✅ タスクに合わせて適切なエージェントを選択した
- ✅ バックグラウンドタスクを活用して効率を高めた
- ✅ Todo システムを使用して長期的なタスクを追跡した
- ✅ 定期的にキャッシュとセッションをクリーンアップした
次のステップ
ベストプラクティスをマスターした後は、以下のことをお勧めします：