指示更新スキル

概要

Claudeの間違いの再発防止、または作業で得た知見の恒久化のため、user-level（AGENTS.md）/PJ-level（CLAUDE.md）の指示・context・スキルを更新する。

トリガー条件

• /update-inst <間違えた内容 or 追記したい知見> が実行された場合
• Claudeが指示に反した行動をした際に、ユーザーが再発防止を依頼した場合
• 作業中に得た運用知見（コマンドの落とし穴・環境固有の注意点等）をCLAUDE.mdやスキルに反映するよう依頼された場合

モード

引数	対象
間違い・知見を指定	指定された1件を修正する（下記「実行手順」）
retro	現在のセッション全体から恒久化すべき知見を洗い出す（下記「retroモード」→ 残った項目ごとに「実行手順」のPhase 2以降）

実行手順

Phase 1: 問題分析

1. 間違いの特定

   • 何が間違っていたか
   • どこで間違いが発生したか（どのPhase、どの処理）

2. 原因の特定

   • 指示が不明確だったか
   • 例示が誤解を招いたか
   • 指示が存在しなかったか
   • 優先度が不明確だったか

3. 関連ファイルの特定

ファイル	確認観点
~/.claude/AGENTS.md（実体。CLAUDE.mdは互換symlink）	全PJ共通の作業フロー、基本ルール
~/.claude/context/*.md	詳細ルール、フォーマット定義
~/.claude/skills/*/SKILL.md	スキル固有のルール（user-level）
./CLAUDE.md	PJ固有ルール・コマンド・環境情報
./.claude/skills/*/SKILL.md	PJ固有スキル（運用手順・ドメイン知識）
./.claude/context/*.md	PJ固有の詳細ルール

Phase 2: 修正方針の決定

1. 修正タイプの判断

タイプ	対応	例
指示の追加	新しいルールを追記	「〇〇の場合は△△すること」
指示の明確化	曖昧な表現を具体化	「yymmdd」→「システムプロンプトのToday's dateから取得」
例示の修正	誤解を招く例を修正	固定値の例示→動的な説明
優先度の明示	不可逆な操作・secret・承認ゲートに限りIMPORTANT/CRITICALを付ける	破壊的操作の事前確認

2. 修正対象の決定

• user-level（全PJ共通）か、PJ-level（特定PJのみ）かを判断
• 最小限の修正で最大の効果を狙う
• 既存の指示との整合性を確認

Phase 3: 修正の実施

1. 修正前の状態を記録

   • 変更するファイルと箇所
   • 変更前の内容

2. 修正を提案

## 修正提案

### ファイル: <パス>

**変更前:**

<現在の内容>

**変更後:**

<修正後の内容>

**理由:** <なぜこの修正が必要か>

3. ユーザーの承認を得る

   • ユーザーに確認する（Claude Code: AskUserQuestion）
   • 必要に応じて修正案を調整
   • ただし包括的な改修依頼（「見直して」「全部対応して」等）を受けている場合は個別承認を省略し、完了報告でまとめて提示する

4. 修正を適用

Phase 4: 検証

1. 整合性の確認

   • 他の指示と矛盾がないか
   • 過度に制限的でないか

2. 今回の間違いが防げるか確認

   • 修正後の指示で、同じ間違いが発生しないか
   • エッジケースも考慮

Phase 5: コミット

user-level（~/.claude/）に適用した場合は、そのターン内で /commit --push を実行し、コミットとpushまで完了させる（3PC間で同期しているため、変更を手元に残さない）。

project-level（<project>/.claude/・PJ CLAUDE.md）に適用した場合は、実装開始前ゲートの「直コミット可否の判定」（@context/workflow-rules.md）に従う。

retroモード（セッション全体から洗い出す）

1. 候補の収集: 会話全体から次を列挙し、各候補にセッション内の根拠を1行付ける
   • ユーザーからの訂正・好みの表明
   • Claudeの間違いと修正（指示があれば防げたもの）
   • 発見した非自明な事実（環境のクセ・コマンドの落とし穴・仕様の実挙動）
   • 2回以上繰り返された手動指示
   • スキルの発火漏れ・誤発火・手順不足
2. フィルタ: 次を全部満たしたものだけ残す。除外した候補は理由付きで報告に載せる
   • このセッションで実際に起きた（仮想のルールを足さない）
   • デフォルト挙動を変える（no-opでない）
   • 追記先候補をGrepして未記載（既存記述の不足なら「明確化」扱い）
   • 恒久的（今回限りの情報はメモリディレクトリへ）
3. 適用範囲: 「追加」と「明確化」はPhase 3の個別承認を省略して適用し、報告でまとめて示す。既存ルールの削除・弱体化・矛盾する変更・settings.jsonの変更・好みの推測に基づく変更は適用せず提案に回す
4. 候補ゼロは正常: 無理に変更を作らず「恒久化すべき知見なし」と報告する

修正のベストプラクティス

1. 強調・記述の原則は真実源に従う

• CLAUDE.mdのサイズ・強調（IMPORTANT/CRITICAL/YOU MUST）・命令形・理由付けの原則は @context/claude-customization-guide.md §3に従う（本スキルに重複定義しない。真実源を一つに保つため）
• 詳細ガイドは @ 参照でcontext/ に委譲する（常駐コストを避けたい参照はRead-when形式で誘導）

2. 例示の注意点

• 固定値（日付、ID等）を例示に使わない
• 「システムプロンプトから取得」等の動的な説明を使う
• 例示が誤解を招かないか確認

3. 追記の書き方

• 繰り返し発生する間違いは、望ましい動きの記述として追加する（禁止形の列挙は代替行動を伝えず、本体方針と衝突したときに抜け道ができる）
• 例外: 不可逆な操作・secret・承認ゲートは禁止形のまま残してよい（permissions.deny等での機械強制と二重化する）
• 発火条件は着手前に確認できる事実で書く（「重要な変更のとき」「複雑な場合」等のモデルの自己分類に依存させない）
• 本体system promptと逆を言う追記は、原文を引用して名指しで優先を宣言する（一般論の追記は原文と並ぶと原文が優先される）。逆に本体が既に言っていることは追記しない
• 簡潔に記載（理由は別ファイルに）

出力フォーマット

# 指示更新レポート

## 問題
- 間違い: <何が間違っていたか>
- 原因: <なぜ間違いが発生したか>

## 修正内容

### 1. <ファイルパス>
- 修正タイプ: <追加/明確化/例示修正/優先度明示>
- 変更内容: <概要>

## 検証
- 同じ間違いが防げるか: <Yes/No + 理由>
- 整合性: <問題なし/要注意点>

## 適用状態
- [ ] ユーザー承認済み
- [ ] 修正適用済み