メニュー
後からキャプチャ・レビュー可能な開発インサイトを記録するための標準プロトコル。 以下の場合に使用: - 再利用可能なパターンやアンチパターンの発見時 - コードベースについて予期しないことを学んだ時 - 明確な根拠に基づく重要な判断を下した時 - 将来の参照のために記録する価値のあるインサイトを見つけた時 このスキルは insight_capture フックが自動的に抽出するインサイトマーカーを定義する。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | insight-recording |
| description | 後からキャプチャ・レビュー可能な開発インサイトを記録するための標準プロトコル。 以下の場合に使用: - 再利用可能なパターンやアンチパターンの発見時 - コードベースについて予期しないことを学んだ時 - 明確な根拠に基づく重要な判断を下した時 - 将来の参照のために記録する価値のあるインサイトを見つけた時 このスキルは insight_capture フックが自動的に抽出するインサイトマーカーを定義する。 |
| allowed-tools | Read |
| model | sonnet |
| user-invocable | false |
自律的な作業中に開発インサイトを記録するための標準化プロトコル。マークされたインサイトは insight_capture.sh フック（SubagentStop 経由）により自動的にキャプチャされ、/review-insights でレビューできる。
サブエージェント出力 transcript.jsonl insight_capture.sh /review-insights
│ │ │ │
├─ PATTERN: ... ─────►│ │ │
├─ LEARNED: ... ─────►├──────────────────────►├─► pending/INS-*.json ►│
└─ その他のテキスト │ │ ├─► CLAUDE.md
│ (コードブロックは │ (アトミック書き込み、 ├─► .claude/rules/
│ フィルタ除外) │ 重複排除) └─► ワークスペースのみ
フックはトランスクリプト JSONL ファイル（SubagentStop メタデータの transcript_path 経由）から読み取り、アシスタントメッセージを抽出し、コードブロックをフィルタリングし、インサイトマーカーを検索する。
以下のマーカーでインサイトを出力する（大文字小文字を区別しない）。マークされたコンテンツのみキャプチャされる。
| マーカー | 使用場面 | 例 |
|---|---|---|
PATTERN: | 再利用可能なパターンを発見した時 | PATTERN: Repository pattern with Unit of Work at src/repositories/base.ts:15 |
ANTIPATTERN: | 避けるべきアプローチを発見した時 | ANTIPATTERN: Global state in config.js makes testing difficult |
LEARNED: | 予期しないことを学んだ時 | LEARNED: The legacy auth module is deprecated but still used by admin |
DECISION: | 根拠を伴う重要な判断をした時 | DECISION: Chose event-driven over direct calls due to async patterns |
INSIGHT: | 記録する価値のある一般的な観察 | INSIGHT: Error handling uses custom AppError class consistently |
インサイトは複数行にわたることができる。コンテンツは次のマーカーまたはテキストの終わりまでキャプチャされる。
1 行:
PATTERN: Repository pattern at src/repositories/base.ts:15
複数行（複雑なインサイトに推奨）:
PATTERN: This codebase uses Repository pattern with Unit of Work for all
database operations. Each repository extends BaseRepository which handles
transactions - see src/repositories/base.ts:15
LEARNED: The user.status field uses magic numbers (1=active, 2=inactive) -
no documentation exists, discovered through characterization testing
重要: 複数行インサイトは次のマーカーで終了する。空行は可読性のために使用できるが、キャプチャには影響しない。
| 制約 | 値 | 根拠 |
|---|---|---|
| 最小長 | 11 文字 | ノイズやプレースホルダーマーカーをフィルタ |
| 最大長 | 10,000 文字 | ストレージの肥大化を防止。... [truncated] で切り詰め |
| キャプチャあたり最大数 | 100 インサイト | DoS 防止のレート制限 |
| コードブロックフィルタリング | 有効 | ```...``` 内のマーカーは無視 |
| インラインコードフィルタリング | 有効 | `...` 内のマーカーは無視 |
| 重複排除 | コンテンツハッシュによる | 同一インサイトは一度だけキャプチャ |
| アトミック書き込み | temp + fsync + rename | 部分的な書き込みや破損を防止 |
コードブロック内のマーカーは無視される（誤検出防止のため）:
パターンの文書化の例:
```python
# PATTERN: これはキャプチャされない（コードブロック内）
def example():
pass
PATTERN: これはキャプチャされる（コードブロック外）
これにより、例を文書化する際に誤ってキャプチャすることを防げる。
## ロール別マーカー選択
異なるロールは通常、異なるマーカーを重視する:
| ロール | 主要マーカー |
|--------|-----------|
| 探索（code-explorer） | PATTERN, LEARNED, INSIGHT |
| アーキテクチャ（code-architect, system-architect） | PATTERN, DECISION, INSIGHT |
| セキュリティ（security-auditor） | PATTERN, ANTIPATTERN, LEARNED |
| 品質（qa-engineer） | PATTERN, ANTIPATTERN, LEARNED |
| 検証（verification-specialist） | PATTERN, LEARNED, INSIGHT |
| レガシー（legacy-modernizer） | PATTERN, ANTIPATTERN, LEARNED, DECISION |
| DevOps（devops-sre） | PATTERN, LEARNED, DECISION |
| フロントエンド（frontend-specialist） | PATTERN, LEARNED, DECISION |
| バックエンド（backend-specialist） | PATTERN, ANTIPATTERN, DECISION |
| デザイン（ui-ux-designer） | PATTERN, DECISION, LEARNED |
| ドキュメント（technical-writer） | PATTERN, DECISION, LEARNED |
### このスキルを持たないエージェント
以下のエージェントは insight-recording を持たない:
| エージェント | 根拠 |
|------------|------|
| `product-manager` | コードレベルのパターンではなく、ユーザー向け要件に焦点。判断は PRD/仕様書にキャプチャされる。 |
## 出力形式の例
```markdown
PATTERN: This codebase uses Repository pattern with Unit of Work for all
database operations - see src/repositories/base.ts:15
LEARNED: The user.status field uses magic numbers (1=active, 2=inactive) -
no documentation exists, discovered through characterization testing
DECISION: Chose Strangler Fig pattern for migration due to existing
/api/v1/ that can coexist with new /api/v2/ endpoints
インサイトキャプチャシステムが提供するもの:
get_workspace_stats 関数でステータス別のインサイト数をカウントarchive/ ディレクトリに移動可能ディレクトリ構造:
.claude/workspaces/{id}/insights/
├── pending/ # レビュー待ち
│ ├── INS-20250121143000-a1b2c3d4.json
│ └── INS-20250121143500-e5f6g7h8.json
├── applied/ # CLAUDE.md またはルールに適用済み
├── rejected/ # ユーザーが却下
└── archive/ # 参照用の古いインサイト
個別インサイトファイル形式:
{
"id": "INS-20250121143000-a1b2c3d4",
"timestamp": "2025-01-21T14:30:00Z",
"category": "pattern",
"content": "Error handling uses AppError class...",
"source": "code-explorer",
"status": "pending",
"contentHash": "a1b2c3d4e5f6",
"workspaceId": "main_a1b2c3d4"
}
設定ファイルとソースコードからプロジェクトの技術スタックを自動検出。 Use when: 新規コードベースでの作業開始、言語/フレームワーク/ツールの特定。 Trigger phrases: detect stack, what framework, identify technology, project setup
REST、GraphQL、gRPC の API 設計パターン。 Use when: API の新規設計、OpenAPI 仕様作成、バージョニング/ページネーション設計。 Trigger phrases: API design, REST endpoint, GraphQL schema, OpenAPI, gRPC, pagination
エバリュエーター・オプティマイザーのフィードバックループによる反復改善。 Use when: 出力品質の反復改善、明確な評価基準がある複雑な出力の最適化。 Trigger phrases: iterate, refine, improve quality, feedback loop, evaluate and optimize
ルール遵守と創造的な問題解決のバランスを取るためのフレームワーク。 Anthropic のエージェント設計に関する研究に基づく。 使用場面: - 複数の有効なアプローチがある複雑な判断に直面した場合 - 状況に対して指示が過度に規範的に感じられる場合 - ガイドラインを特定のコンテキストに適応させる必要がある場合 - 精度要件と革新的なソリューションのバランスを取る場合 Trigger phrases: think creatively, use judgment, adapt approach, better solution, flexibility
曖昧なリクエストを明確にするための構造化された要件インタビューフレームワーク。使用場面: - ユーザー要件が不明確または不完全な場合 - 新機能を開始し要件を収集する必要がある場合 - ユーザーのニーズ、制約、優先順位を理解する必要がある場合 - ビジネスリクエストを技術仕様に変換する場合 - ユーザーが詳細なしに「～したい」「～を追加して」と言う場合 Trigger phrases: gather requirements, clarify request, what do you need, interview user, requirements gathering, unclear request
すべてのユーザー向けコンテンツに日本語出力を強制する。 使用場面: - エージェント出力を日本語にする必要がある場合 - レスポンス全体の言語の一貫性を検証する場合 - 仕様書やドキュメントを日本語で生成する場合 Trigger phrases: Japanese, 日本語, language mode, output language