振り返り観点追加ガイド

ユーザーからの指摘や問題発見時に、類似問題を将来の振り返りで検出できるよう観点を追加する手順。

使用タイミング

[ACTION_REQUIRED: /add-perspective] が表示されたとき
ユーザーから「動いてる？」「正常？」等の指摘を受けたとき
振り返りで新しいチェック観点が必要と判断したとき

手順

1. 問題の分析

まず、指摘された問題の根本原因を特定する。

| 項目 | 内容 |
|------|------|
| 問題の概要 | 何が起きたか |
| 根本原因 | なぜ発生したか |
| 検出方法 | どうすれば事前に気づけたか |

2. 既存観点の確認

新しい観点が本当に必要か確認する。

# 既存の観点を確認（PERSPECTIVES配列全体を表示）
grep -A 100 "PERSPECTIVES = \[" .claude/hooks/reflection_self_check.py | head -150

既存観点で検出可能な場合は追加不要。キーワードの拡充で対応できる場合はキーワード追加のみ。

3. 観点の定義

新しい観点が必要な場合、以下を定義する。

| フィールド | 説明 | 例 | |-----------|------|-----| | id | 一意の識別子（snake_case） | ci_failure_analysis | | name | 日本語の表示名 | CI失敗分析 | | description | 確認すべき内容 | CI失敗時に根本原因を分析したか | | keywords | 検出用キーワード（正規表現） | [r"CI.*失敗", r"根本原因"] |

4. reflection_self_check.py への追加

.claude/hooks/reflection_self_check.py の PERSPECTIVES 配列に追加:

# Issue #XXXX: [問題の説明]
{
    "id": "new_perspective_id",
    "name": "観点の表示名",
    "description": "確認すべき内容の説明",
    "keywords": [
        r"キーワード1",
        r"キーワード2",
        r"複合.*パターン",
    ],
},

5. reflect SKILL.md への追加

reflection_self_check.pyのPERSPECTIVESに追加した新観点を、.claude/skills/reflect/SKILL.mdのセクション6「改善点の洗い出し」の観点チェックテーブルにも反映する:

| N | 新観点の名前 | 確認すべき内容 | #XXXX |

6. テストの追加

.claude/hooks/tests/test_reflection_self_check.py にテストを追加:

def test_detects_new_perspective(self):
    """新観点が正しく検出される."""
    transcript = "キーワード1を含むテキスト"
    missing = get_missing_perspectives(transcript)
    perspective_ids = [p["id"] for p in missing]
    assert "new_perspective_id" not in perspective_ids

7. Issueの作成（任意）

大きな変更の場合はIssueを作成してからworktreeで作業する。

キーワード設計のベストプラクティス

| 項目 | 推奨 | |------|------| | 複合パターン | 単一キーワードより r"CI.*失敗" のような複合が誤検知を減らす | | 正規表現 | r"(Pre|Post|Stop)" でOR条件も可能 | | 網羅性 | 同じ意味の異なる表現を含める（例: 失敗、エラー、問題） | | テスト | 実際のtranscriptでキーワードが検出されることを確認 |

追加しない方が良いケース

| ケース | 理由 | |--------|------| | 一回限りの特殊な問題 | 再発可能性が低い | | 既存観点のキーワード拡充で対応可能 | 観点の重複を避ける | | 主観的な評価基準 | キーワードで検出困難 |

実例

Issue #2289: 「対応済み」判断の検証

問題: 「既に対応済み」と判断したが、実際には仕組みが有効に機能していなかった。

追加した観点:

{
    "id": "already_handled_check",
    "name": "「対応済み」判断の検証",
    "description": "「対応済み」と判断した場合、その仕組みの実行タイミング（Pre/Post/Stop）を確認し、実際に有効か検証したか",
    "keywords": [
        r"対応済み.*検証",
        r"実行タイミング",
        r"(Pre|Post|Stop)",
        r"フック.*確認",
        r"仕組み.*有効",
        r"対応済み.*なし",
    ],
},

チェックリスト

[ ] 既存観点で対応できないか確認した
[ ] id, name, description, keywords を定義した
[ ] reflection_self_check.py の PERSPECTIVES に追加した
[ ] execute.md のセクション8に追加した
[ ] テストを追加した
[ ] Pythonの構文エラーがないことを確認した