ベストプラクティス

効果的なスキルとワークフローを設計するための指針です。

スキル設計の原則

1. 単一責任

一つのスキルは一つの明確なタスクを担当します。

<!-- 良い例 -->
---
name: check-broken-links
description: サイト内のリンク切れを検出する
---

<!-- 悪い例 -->
---
name: check-and-fix-everything
description: サイト全体をチェックして修正する
---

2. 明確なゴール

スキルのプロンプトは期待する成果物を明示します。

以下の手順で実行してください：

1. `src/` ディレクトリのTypeScriptファイルを対象に型エラーを検出
2. エラー一覧をMarkdownテーブルで出力
3. 自動修正可能なものは修正を適用

## 出力フォーマット
| ファイル | 行 | エラー内容 | 修正済み |
|---------|------|----------|---------|

ワークフロー設計の原則

ワークフローはHQのビジュアルエディタで構築するDAG（ノード/エッジのグラフ）です。ノードの一覧はDAGノードを参照してください。

グラフは小さくまとめる

1つのワークフローのノードは少数に保つのが理想です。肥大化したグラフはエラーリカバリも見通しも悪くなります。関係のない処理は別のワークフローに分割してください。

レビューノードを適切に配置

破壊的な操作（デプロイ、データ変更等）の前にはレビューノードを挟みます。レビューノードは差し戻しループに対応しており、却下された出力を上流のノードに戻してやり直させることができます。

独立した処理は並列化する

互いに依存しないステップは、一本道にせずグラフを分岐させて並列実行します。リストの各要素に同じサブグラフを適用するにはfan-outノードを、その結果をまとめるにはjoinノードを使います。

cronは控えめに

高頻度の実行（5分未満の間隔）はリソースを消費します。本当に必要な頻度を検討してください。

プロジェクト構成のヒント

ロール分担

• PM — ワークフロー設計、コンテキスト管理、レビュー承認
• Engineer — スキル実装、ワークフローの実行

コンテキスト活用

プロジェクトコンテキストに共通知識を記載すると、所属するすべてのミニオンが参照できます。スキル内で毎回同じ説明を繰り返す必要がなくなります。