# Gotchas Curator

> 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.

- Skill: `nahisaho/gotchas-curator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nahisaho/gotchas-curator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nahisaho/gotchas-curator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nahisaho (https://skillmd.com/u/nahisaho)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nahisaho/gotchas-curator

---


# Gotchas Curator

タスク完了時やエージェントのミス発生時に学びを収集し、関連スキルの Gotchas セクションに反映するスキル。Harness 7軸の Memory Persistence を実践する。

## 収集手順

1. 対象イベントを特定:
   - エージェントのミスを修正した
   - 予期しない動作が発生した
   - ワークアラウンドが必要だった
   - レビューで改善点が見つかった
   - タスクが完了した

2. 学びを構造化:
   - **何が起きたか**: 具体的な状況の説明
   - **なぜ問題か**: 影響範囲と深刻度
   - **どう防ぐか**: 具体的な対策（コマンド、ルール、チェック）
   - **関連スキル**: この Gotcha を追記すべきスキル名

3. Gotcha エントリを生成:
   - 1項目 = 1〜2行で完結
   - 具体的なコマンド、ファイル名、設定値を含める
   - 汎用的な注意事項ではなくプロジェクト固有の知識を記載

4. 関連スキルの Gotchas セクションに追記

5. 重複チェック:
   - 同じ内容の既存 Gotcha がないか確認
   - ある場合は統合または詳細化

## 良い Gotcha の例

```markdown
## Gotchas

# ✅ 具体的で実行可能
- `users` テーブルはソフトデリートを使用。クエリには必ず
  `WHERE deleted_at IS NULL` を含めること
- JWT トークンの `exp` クレームなしのトークンを許容してはならない。
  必ず有効期限を検証すること

# ❌ 汎用的で価値が低い
- セキュリティに注意すること
- テストを忘れないこと
```

## 蓄積先の優先順位

1. **関連する SKILL.md の Gotchas セクション** — 最優先。スキル起動時に自動読み込みされる
2. **copilot-instructions.md** — プロジェクト全体に適用すべきルールの場合
3. **`.github/learnings/`** — スキルに紐づかない汎用的な学びの場合

## コンパクション耐性

Gotchas はファイルに書き出されるため、セッションのコンパクション後も保持される。
以下のものはコンパクションで失われるため、重要なものは必ずファイルに書き出すこと:

| ✅ 保持される | ❌ 失われる |
|-------------|------------|
| SKILL.md の Gotchas | セッション中の推論・分析 |
| ファイルに書き出した学び | 過去に読んだファイル内容 |
| Git にコミットした変更 | ツール呼び出し履歴 |

## Gotchas

- Gotcha は「汎用的な注意」ではなく「プロジェクト固有の落とし穴」を書く。LLM は一般的な知識をすでに持っている
- 同じ Gotcha を複数のスキルに重複記載すると保守コストが増大。最も関連性の高い1箇所に書く
- Gotchas セクションが10項目を超えたら、カテゴリ分け（例: DB関連、API関連、認証関連）を検討する
- 学びの収集タイミングは「ミス発生直後」が最も効果的。タスク完了後にまとめて振り返ると詳細を忘れる
- Gotcha の追記後は対象スキルが500行以内に収まっているか確認すること

## 検証ループ

1. Gotcha エントリを生成
2. チェック:
   - 具体的なコマンド・ファイル名・設定値が含まれるか
   - 1〜2行で完結しているか
   - 既存の Gotcha と重複していないか
   - 追記先スキルが500行以内に収まるか
3. 不合格なら修正
4. 合格後に追記を実行