| name | gotchas-curator |
| description | Capture learnings, edge cases, and pitfalls from completed tasks and maintain Gotchas sections in Agent Skills for Memory Persistence. Use when finishing a task, resolving a bug, completing a review, or when an agent made a mistake that should be prevented in future sessions.
|
| metadata | {"author":"coreclaw","version":"1.0"} |
Gotchas Curator
タスク完了時やエージェントのミス発生時に学びを収集し、関連スキルの Gotchas セクションに反映するスキル。Harness 7軸の Memory Persistence を実践する。
収集手順
-
対象イベントを特定:
- エージェントのミスを修正した
- 予期しない動作が発生した
- ワークアラウンドが必要だった
- レビューで改善点が見つかった
- タスクが完了した
-
学びを構造化:
- 何が起きたか: 具体的な状況の説明
- なぜ問題か: 影響範囲と深刻度
- どう防ぐか: 具体的な対策(コマンド、ルール、チェック)
- 関連スキル: この Gotcha を追記すべきスキル名
-
Gotcha エントリを生成:
- 1項目 = 1〜2行で完結
- 具体的なコマンド、ファイル名、設定値を含める
- 汎用的な注意事項ではなくプロジェクト固有の知識を記載
-
関連スキルの Gotchas セクションに追記
-
重複チェック:
- 同じ内容の既存 Gotcha がないか確認
- ある場合は統合または詳細化
良い Gotcha の例
## Gotchas
# ✅ 具体的で実行可能
- `users` テーブルはソフトデリートを使用。クエリには必ず
`WHERE deleted_at IS NULL` を含めること
- JWT トークンの `exp` クレームなしのトークンを許容してはならない。
必ず有効期限を検証すること
# ❌ 汎用的で価値が低い
- セキュリティに注意すること
- テストを忘れないこと
蓄積先の優先順位
- 関連する SKILL.md の Gotchas セクション — 最優先。スキル起動時に自動読み込みされる
- copilot-instructions.md — プロジェクト全体に適用すべきルールの場合
.github/learnings/ — スキルに紐づかない汎用的な学びの場合
コンパクション耐性
Gotchas はファイルに書き出されるため、セッションのコンパクション後も保持される。
以下のものはコンパクションで失われるため、重要なものは必ずファイルに書き出すこと:
| ✅ 保持される | ❌ 失われる |
|---|
| SKILL.md の Gotchas | セッション中の推論・分析 |
| ファイルに書き出した学び | 過去に読んだファイル内容 |
| Git にコミットした変更 | ツール呼び出し履歴 |
Gotchas
- Gotcha は「汎用的な注意」ではなく「プロジェクト固有の落とし穴」を書く。LLM は一般的な知識をすでに持っている
- 同じ Gotcha を複数のスキルに重複記載すると保守コストが増大。最も関連性の高い1箇所に書く
- Gotchas セクションが10項目を超えたら、カテゴリ分け(例: DB関連、API関連、認証関連)を検討する
- 学びの収集タイミングは「ミス発生直後」が最も効果的。タスク完了後にまとめて振り返ると詳細を忘れる
- Gotcha の追記後は対象スキルが500行以内に収まっているか確認すること
検証ループ
- Gotcha エントリを生成
- チェック:
- 具体的なコマンド・ファイル名・設定値が含まれるか
- 1〜2行で完結しているか
- 既存の Gotcha と重複していないか
- 追記先スキルが500行以内に収まるか
- 不合格なら修正
- 合格後に追記を実行