Imported from langcore-org/united-productions-web (.claude/skills/feature-cleanup/SKILL.md). Install upstream with npx skills add langcore-org/united-productions-web --skill feature-cleanup. Copyright stays with the author.

Feature Cleanup Skill

機能を安全に削除・移行するためのエージェント行動指針。

⚠️ 重要な原則: スクリプトは補助ツール。最終判断は常にエージェントが行う。スクリプトの結果を鵜呑みにせず、臨機応変に対応すること。

バージョン: 3.0 最終更新: 2026-03-05

参照ガイド

• dialog-templates.md - Phase 4の詳細対話例（削除実行時に参照）
• practical-guide.md - 実例・エラー対応・スキル改善方法（トラブル時・学習時に参照）

🆕 v2.0 の新機能

🎯 エージェンティック対応の原則（最重要）

「スクリプト頼み」になっていないか定期的に確認

❌ 悪い例（スクリプト頼み）:
   スクリプト結果 → 「削除候補はありません」と報告 → 終了

✅ 良い例（エージェンティック）:
   スクリプト結果 → 「あれ？これは変だ」と違和感を持つ
   → grepで実際に検索
   → ファイルを開いて内容確認
   → 「実はこういう状態」と判断
   → ユーザーに「こういう理由で削除可能/不可」と説明

臨機応変な対応パターン

対話の流れ（理想形）

ユーザー: 「未使用機能を整理したい」

エージェント:
1. スクリプト実行（候補発見）
2. 結果を見て「あ、これはおかしい」と違和感を持つ
3. 追加調査（grep, ファイル確認）
4. 「調査した結果、以下の3パターンがあります：
    A. 即座に削除可能（空ディレクトリ）
    B. 確認が必要（Sidebarにないが参照あり）
    C. 残すべき（将来的に使用予定）
    推奨は A を先に処理し、B は詳細調査後に判断」
5. ユーザーと対話しながら進行

重要な思考パターン

スクリプト実行後、必ず自問する:

• 「この結果、本当に正しいか？」
• 「違和感はないか？」
• 「見落としはないか？」
• 「ユーザーが納得する説明ができるか？」

違和感があれば、躊躇なく追加調査:

# スクリプトでは検出できないケースを手動で確認
grep -rn "怪しいキーワード" app/ lib/ --include="*.tsx"
find app/ -type d -empty  # 空ディレクトリ
ls -la app/(authenticated)/  # ディレクトリ一覧確認

ユーザーの意図を汲み取る:

• 「整理したい」→ 削除だけでなく、分類・優先順位付けも提案
• 「この機能不要？」→ なぜ不要と思ったかを確認（技術的負債？仕様変更？）
• 「安全に削除したい」→ 慎重アプローチ（DRY RUN→段階的削除）

スクリプトとエージェントの役割分担（再確認）

結論: スクリプトは「手を動かす」、エージェントは「頭を使う」

エージェントの基本姿勢

判断基準：いつこのスキルを使うか

臨機応変な対応パターン

重要：スクリプトとエージェントの役割分担

基本原則：スクリプトは「候補発見」、エージェントが「最終判断」

エージェンティック調査の重要性:

❌ 悪い例:
   audit-unused.mjs の結果だけを見て「削除候補はありません」と報告

✅ 良い例:
   audit-unused.mjs を実行 → 結果を確認
   → 「na-scriptはSidebarにないがページがある。実際に使われているか確認が必要」
   → grep で使用箇所を確認
   → page.tsx を開いて内容を確認
   → 「実際には無効化されており、直接URLアクセスのみ可能」と判断
   → ユーザーに「完全削除か無効化か」を確認

エージェンティック調査ワークフロー

Phase 0: 候補発見（スクリプト実行）

# 基本調査（空ディレクトリも自動検出）
node .claude/skills/feature-cleanup/scripts/audit-unused.mjs

# 深層調査（prisma/schema, types/, config/ も含む）
node .claude/skills/feature-cleanup/scripts/audit-unused.mjs --deep

# 対話的削除モード
node .claude/skills/feature-cleanup/scripts/audit-unused.mjs --interactive

# DB削除スクリプト自動生成
node .claude/skills/feature-cleanup/scripts/audit-unused.mjs --generate-delete "機能ID"

スクリプト出力の読み方:

• 【✅ アクティブ機能】→ 無視
• 【⚠️ 非表示だが使用中】→ エージェント詳細調査対象
• 【📄 設定のみ】→ エージェント詳細調査対象
• 【🗑️ 削除候補】→ 即座に削除検討
• 【💬 コメントアウト済み】→ 即座に削除検討
• 【🔍 空のディレクトリ】→ 即座に削除可能

Phase 1: エージェントによる詳細調査（必須）

スクリプトの結果だけで判断してはいけない。

Step 1: 定義ファイルを確認

# 機能IDがどこで定義されているか確認
grep -rn "featureId.*\"機能ID\"" lib/ types/ config/ --include="*.ts"

該当ファイルを開いて：

• 型定義のみか、実際の設定オブジェクトもあるか
• 他の設定とどう関連しているか

Step 2: コード参照を確認

# どこから参照されているか
grep -rn "機能ID" app/ lib/ components/ --include="*.ts" --include="*.tsx" | head -30

該当ファイルを開いて：

• import されているか、文字列リテラルとしてのみ使われているか
• 実際のロジックで使用されているか、型定義のみか

Step 3: 実際の使用状況を判断

判断チェックリスト:

Phase 2: リスク評価と方針決定

node .claude/skills/feature-cleanup/scripts/analyze-risk.mjs "[機能ID]"

エージェント判断ポイント:

• スクリプトの「🔴重大」は本当に重大か？
• 「🟡中」は実際に影響があるか？

Phase 3-5: 以降は従来通り

Phase 3以降は「Phase 0-5: 削除ワークフロー」セクションを参照。

対話型ワークフロー

削除作業は対話的に進行。ユーザーの判断を仰ぐポイントを明示。

特別モード: 未使用機能の発見と選択的削除

「未使用機能を整理したい」などの要望があった場合：

# まずスクリプトで候補発見
node .claude/skills/feature-cleanup/scripts/audit-unused.mjs

# 違和感があれば深層調査
node .claude/skills/feature-cleanup/scripts/audit-unused.mjs --deep

エージェントによる詳細調査（必須）:

スクリプト結果:
【⚠️ 非表示だが使用中】
  na-script
    参照: 11件 (app: 4, lib: 6)
    ページ: あり | API: なし

エージェントの対応:
→ 「na-script は Sidebar にないがページがあります。詳細を確認します。」
→ grep -rn "na-script" app/ --include="*.tsx"
→ page.tsx を開いて内容確認
→ 「実際には isActive=false で無効化されています。完全削除できます。」

ユーザーへの提示と選択後のフロー：

• A/B/C（削除選択）→ 通常の削除ワークフロー（Phase 2以降）へ
• D（個別確認）→ 各機能の詳細調査（analyze.mjs + エージェント調査）を実行
• E（削除しない）→ 理由を確認して記録

未使用機能の判断基準

エージェンティック調査の実践例

ケース1: 「参照0件」だけど実は使われている

# スクリプト結果: 「参照0件（未使用）」
# エージェントの対応:
→ 「本当か？動的に呼び出されている可能性を確認」
→ grep -rn "featureId" app/ --include="*.tsx" | grep -v "import"
→ 「あ、query parameterで動的に指定されている！使用されている」

ケース2: 「削除候補」だけど実は重要

# スクリプト結果: 「Sidebarなし、参照1件（削除候補）」
# エージェントの対応:
→ 「どこから参照されているか確認」
→ grep -rn "機能ID" lib/ --include="*.ts"
→ 「lib/settings/db.ts から参照されている...これは重要ファイル」
→ 「削除すると他機能に影響する可能性がある」と判断

ケース3: スクリプトが検出できないケース

# スクリプト結果: 「問題なし」
# エージェントの対応:
→ 「本当に？手動で確認してみる」
→ ls -la app/(authenticated)/
→ 「あ、na-script という空ディレクトリがある！」
→ 「これはスクリプトの検出パターンに含まれていなかった」
→ ユーザーに報告して削除を提案

ケース4: ユーザーの真意を汲み取る

ユーザー: 「general-chat 必要？」

スクリプト的対応:
→ Sidebarにないが参照あり
→ 「詳細調査が必要です」

エージェンティック対応:
→ 「general-chat を確認しました」
→ 「実はデフォルト機能として /chat で使用されています」
→ 「ユーザーがagent指定なしでアクセスした時のfallbackです」
→ 「削除すると /chat?new=1 が動作しなくなります」
→ 「残すことを推奨します。削除する場合は代替機能の設計が必要です」

🔄 削除ワークフロー（承認制）

原則: 削除実行は必ずユーザー承認後。事前に徹底的な調査・解説を行う。

[Step 1] 候補発見 → [Step 2] 詳細調査 → [Step 3] 影響分析 → [Step 4] リスク解説作成
                                                            ↓
[Step 6] 削除実行 ← [Step 5] ユーザー承認 ← ユーザーへの提示（一覧+解説+推奨）
                                                            ↓
                                              [中止/保留/修正依頼]

Step 1: 候補一覧作成（発見）

目的: 削除対象になりうるものを網羅的に発見する

# 1.1 未使用機能の発見
node .claude/skills/feature-cleanup/scripts/audit-unused.mjs

# 1.2 深層調査（必要に応じて）
node .claude/skills/feature-cleanup/scripts/audit-unused.mjs --deep

# 1.3 特定キーワードの検索（ユーザー指定時）
grep -rn "キーワード" app/ lib/ --include="*.ts" --include="*.tsx" | head -50

候補一覧の作成基準:

エージェントの判断（スクリプト結果を鵜呑みにしない）:

❌ 「audit-unused.mjs の結果: 削除候補2件」→ そのまま報告

✅ 「スクリプト結果を確認 → これは実際には使われているか？
    → grepで追加検索 → ファイルを開いて確認
    → 「削除候補2件、うち1件は実際に使用されている可能性あり」」

Step 2: 詳細調査（コード・設定・データ）

目的: 各候補について、実際の使用状況と影響範囲を正確に把握する

2.1 コード参照の徹底調査

# 定義場所の特定
grep -rn "featureId.*\"候補ID\"" lib/ types/ config/ --include="*.ts"

# 全コードベースでの参照検索
grep -rn "候補ID" app/ lib/ components/ --include="*.ts" --include="*.tsx"

# import関係の確認
grep -rn "import.*候補ID\|from.*候補ID" app/ lib/ components/ --include="*.ts" --include="*.tsx"

# 動的参照の確認（query parameter, localStorage等）
grep -rn "query\|params\|localStorage\|sessionStorage" app/ --include="*.tsx" | grep -i "候補関連"

2.2 設定・型定義の確認

# 型定義の確認
grep -rn "type.*FeatureId\|interface.*Feature" types/ lib/ --include="*.ts"

# 設定オブジェクトの確認
grep -rn "FEATURES\|featureConfigs\|AGENTS" lib/ --include="*.ts"

# Sidebar設定の確認
grep -rn "sidebar\|navigation\|menu" lib/ components/ --include="*.ts" --include="*.tsx"

2.3 DB関連の調査

# プロンプトキーの確認
node prompt-tuning/scripts/get.mjs "候補ID" 2>/dev/null || echo "プロンプトなし"

# DBスキーマでの確認
grep -rn "候補ID\|Enum.*Feature" prisma/ --include="*.prisma"

2.4 実際のファイル確認（最重要）

該当ファイルを1つずつ開いて確認:

調査結果の記録テンプレート:

### 候補: [機能ID]

**発見経緯**: audit-unused.mjs / 手動検索 / ユーザー指定

**定義場所**:
- `lib/settings/db.ts` - FEATURES配列
- `types/feature.ts` - FeatureId型

**参照箇所**:
- `app/(authenticated)/[feature]/page.tsx` - ページ（未使用と判断）
- `lib/chat/agent-config.ts` - エージェント設定（他機能と共有）

**DB関連**:
- SystemPrompt: あり（key: FEATURE_ID）
- Chat/Message: 15件の会話履歴

**使用状況判断**: 
- [ ] 実際に使用されている
- [x] 未使用（Sidebarなし、直接URLのみ）
- [ ] 判断保留（要追加調査）

**備考**: 
- isActive=falseで無効化済み
- 2024-12に最後に使用

Step 3: 影響分析（リスク特定）

目的: 削除時の影響範囲と重大度を特定し、対策を検討する

3.1 依存関係の可視化

# 削除対象ファイルの依存関係を分析
node .claude/skills/feature-cleanup/scripts/analyze-risk.mjs "機能ID"

# 手動での依存確認（スクリプトでは検出できないケース）
grep -rn "import.*from.*機能関連" app/ lib/ --include="*.ts" --include="*.tsx"

3.2 影響カテゴリの評価

3.3 削除パターンの選定

Step 4: リスク解説ドキュメント作成

目的: ユーザーが削除の判断を下せるよう、分かりやすく解説する

4.1 解説ドキュメントの構成

## 削除候補レポート
作成日: YYYY-MM-DD
調査者: AI Agent

### サマリー
削除候補 N件（🔴即座削除可能: X件 / 🟡要確認: Y件 / 🟢保留推奨: Z件）

---

### 候補1: [機能ID] - 🔴 即座削除可能

**概要**:
空のディレクトリ。コード・設定・DB参照なし。

**調査詳細**:
- 定義場所: なし
- 参照: 0件
- DB関連: なし
- 最終使用: 不明（作成のみ）

**リスク評価**: ✅ リスクなし
- 機能停止: なし
- データ損失: なし
- 型定義崩壊: なし

**推奨アクション**: 
🗑️ **即座に削除可能**です。実行しますか？

[削除する] [スキップ] 

---

### 候補2: [機能ID] - 🟡 要確認

**概要**:
Sidebarにないが、コード参照あり。実際の使用状況要確認。

**調査詳細**:
- 定義場所: `lib/settings/features.ts` - FEATURES配列
- 参照: 5件
  - `app/(authenticated)/[feature]/page.tsx` - ページ（コメントアウト済み）
  - `lib/hooks/useFeature.ts` - Hook（他機能でも使用）
- DB関連: SystemPromptあり（key: FEATURE_ID, version: 3）
- 最終使用: 2025-01（3ヶ月前）

**リスク評価**: ⚠️ 中リスク
- 機能停止: 🟡 なし（コメントアウト済み）
- データ損失: 🔴 **15件の会話履歴が失われます**
- 型定義崩壊: 🟡 `lib/hooks/useFeature.ts` で共用（修正必要）

**推奨アクション**:
🟡 **無効化（isActive=false）を推奨**。完全削除は履歴失うため。

選択肢:
- [ ] A) 完全削除（履歴も削除）
- [ ] B) 無効化のみ（履歴保持、機能非表示）
- [ ] C) 保留（判断保留）
- [ ] D) 詳細調査（追加調査が必要）

---

### 候補3: [機能ID] - 🟢 保留推奨

**概要**:
Sidebarにないが、計画中の機能で使用予定あり。

**調査詳細**:
- 参照: 2件（設定ファイルのみ）
- 最終使用: 未使用
- 備考: `docs/plans/future-feature.md` で将来使用と記載

**リスク評価**: 
- 削除自体は問題ないが、将来再作成が必要

**推奨アクション**:
🟢 **保留**。docs/backlog/に記録し、将来の判断材料に。

[保留して記録] [削除する] [詳細確認]

Step 5: ユーザーへの提示と承認

目的: 分かりやすく解説し、明確な承認を得る

5.1 提示のポイント

ユーザーへの提示フォーマット:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 削除候補レポート（N件）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【即座削除可能】🔴
1. [機能ID1] - 空ディレクトリ
2. [機能ID2] - コメントアウト済み

【要確認】🟡
3. [機能ID3] - 履歴15件あり、無効化を推奨
4. [機能ID4] - 他機能と型を共有、修正必要

【保留推奨】🟢
5. [機能ID5] - 将来使用予定

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 推奨アクション:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

A) 🔴 のみ削除（安全）
B) 🔴+🟡 を無効化 or 削除（要詳細説明）
C) 全て保留（調査のみ）
D) 個別に確認（1つずつ判断）

どれを選択しますか？
または、特定の候補について詳細を知りたい場合はお知らせください。

5.2 個別詳細説明（ユーザー要求時）

ユーザー: 「[機能ID3]について詳しく」

エージェント:
「[機能ID3]の詳細です：

📍 現状:
- Sidebarには表示されていません
- しかし、過去に15回の会話が記録されています
- 最後の使用は3ヶ月前（2025-01）

⚠️ 削除の影響:
- 15件の会話履歴が完全に消えます
- ユーザーが「過去の相談を見たい」ときに見られなくなります

💡 代替案:
- 完全削除 → 履歴も消える
- 無効化（isActive=false）→ 履歴は残る、新規使用のみ不可
- どちらをご希望ですか？」

5.3 承認の明確化

承認を得る際のチェックリスト:

• 削除対象を具体的に明示（ファイル名、DBテーブル等）
• 影響範囲を説明（「〜が使えなくなります」）
• リスクを提示（「〜が失われます」）
• 代替案を提示（無効化、部分削除等）
• 推奨を明確に述べる（「〜を推奨します」）
• 明確なYes/Noを求める（「削除してよろしいですか？」）

Step 6: 削除実行（承認後）

目的: 承認された対象のみを、安全に削除する

6.1 実行前最終確認

# DRY RUNで最終確認（必須）
node .claude/skills/feature-cleanup/scripts/delete-feature.mjs "機能ID" --dry-run

# または個別に確認
echo "=== 削除対象ファイル ==="
find app/ -name "*機能ID*" -type f
echo "=== 削除対象ディレクトリ ==="
find app/ -name "*機能ID*" -type d

6.2 段階的削除実行

パターンA: 完全削除（承認済み）

# Step 1: ファイル削除
node .claude/skills/feature-cleanup/scripts/delete-feature.mjs "機能ID" --only-files

# Step 2: 検証
npx tsc --noEmit 2>&1 | grep -v node_modules | head -10

# Step 3: 問題なければDB削除
node .claude/skills/feature-cleanup/scripts/delete-feature.mjs "機能ID" --only-db

# Step 4: 最終検証
node .claude/skills/feature-cleanup/scripts/verify.mjs "機能ID"

パターンB: 無効化（推奨時）

# DBのisActiveフラグをfalseに（実装依存）
# または設定ファイルで無効化

6.3 実行中の問題対応

Step 7: 検証と記録

目的: 削除が正しく完了したことを確認し、記録を残す

7.1 検証チェックリスト

# コード検証
grep -rn "機能ID" app/ lib/ --include="*.ts" --include="*.tsx" | wc -l
# → 0件であること

# 型チェック
npx tsc --noEmit 2>&1 | grep -v node_modules

# Lint
npx biome check . 2>&1 | grep -E "error|warning" | head -10

# ビルド
npm run build 2>&1 | tail -20

7.2 削除完了レポート

## 削除完了レポート
実行日: YYYY-MM-DD

### 実行サマリー
- 削除候補: N件
- 削除実行: X件
- 無効化: Y件
- 保留: Z件

### 削除詳細
| 機能ID | アクション | 結果 | 備考 |
|--------|-----------|------|------|
| feature-1 | 完全削除 | ✅ 成功 | ファイル3件、DBレコード1件 |
| feature-2 | 無効化 | ✅ 成功 | isActive=falseに設定 |
| feature-3 | 保留 | ⏸️ - | 将来使用予定のため |

### 検証結果
- [x] コード参照: 0件（クリア）
- [x] 型チェック: 通過
- [x] Lint: 通過
- [x] ビルド: 成功

### コミット

git add . git commit -m "cleanup: remove feature-1, disable feature-2

• feature-1: 未使用のため完全削除
• feature-2: 履歴保持のため無効化
• feature-3: 将来使用予定のため保留"

7.3 削除履歴の記録（重要）

# backlogに記録
node .claude/skills/feature-cleanup/scripts/verify.mjs "機能ID" --record

# または手動で記録
cat > docs/backlog/cleanup-removed-$(date +%s).md << 'EOF'
# 削除実行記録

## 削除対象
- feature-1
- feature-2

## 理由
未使用機能の整理

## 影響
- feature-1: 影響なし
- feature-2: 新規使用不可、履歴は保持

## 実行日
YYYY-MM-DD
EOF

対話例：ワークフロー実践

シナリオ: 「整理したい」→ 承認制ワークフロー

ユーザー: 「未使用機能を整理したい」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1: 候補発見
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: audit-unused.mjs を実行
→ 候補3件発見

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2: 詳細調査
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: 各候補を詳細調査
- feature-a: 空ディレクトリ → 🔴 即座削除可能
- feature-b: 参照あり、履歴あり → 🟡 要確認
- feature-c: 将来使用予定 → 🟢 保留

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 3: 影響分析
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: 影響を分析
- feature-b: 15件の履歴失う、型定義共有あり

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 4: 解説ドキュメント作成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: レポート作成

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 5: ユーザー提示・承認
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント:
「調査完了しました。

📋 削除候補レポート:
🔴 feature-a: 即座削除可能（リスクなし）
🟡 feature-b: 履歴15件あり、無効化を推奨
🟢 feature-c: 将来使用予定、保留

🎯 推奨: feature-aを削除、feature-bを無効化
実行しますか？」

ユーザー: 「feature-bは完全削除で」

エージェント:
「feature-bは履歴15件が失われます。
本当に完全削除でよろしいですか？
（無効化なら履歴は保持されます）」

ユーザー: 「あ、じゃあ無効化で」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 6: 削除実行（承認後）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: DRY RUN → 実行 → 検証

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 7: 完了記録
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: 完了レポートを作成

ユーザー介入が必要なポイント（承認制ワークフロー）

必ず承認を得るポイント

自動実行可能（承認不要）

決して自動実行しない（必ず承認を得る）

承認を得る際の必須要素

✅ 削除対象の明確な特定（ファイル名、DBレコード等）
✅ 影響範囲の説明（「〜が使えなくなります」）
✅ リスクの提示（「〜が失われます」）
✅ 代替案の提示（無効化、部分削除等）
✅ 推奨の明確化（「〜を推奨します」）
✅ Yes/Noの明確化（「削除してよろしいですか？」）

スクリプト一覧

🆕 v2.0 スクリプト使用方法

audit-unused.mjs:

# 基本調査（空ディレクトリ自動検出）
node audit-unused.mjs

# 深層調査
node audit-unused.mjs --deep

# 対話的削除モード
node audit-unused.mjs --interactive

# 削除スクリプト生成
node audit-unused.mjs --generate-delete "機能ID"

delete-feature.mjs (NEW):

# DRY RUN
node delete-feature.mjs "機能ID" --dry-run

# 完全削除
node delete-feature.mjs "機能ID"

# ファイルのみ
node delete-feature.mjs "機能ID" --only-files

# DBのみ
node delete-feature.mjs "機能ID" --only-db

verify.mjs:

# 通常の検証
node verify.mjs "機能ID"

# 削除履歴を自動記録
node verify.mjs "機能ID" --record

スクリプト使用時の注意

重要: --deep や --generate-delete でも網羅的ではない。エージェントによる追加調査が必要。

削除対象カテゴリと対応

1. フロントエンドファイル

2. コード（修正必須）

3. DBデータ

4. ドキュメント

典型的な削除パターン（承認制ワークフロー適用）

すべてのパターン共通:

• Step 1-4は自動実行（調査・分析・解説作成）
• Step 5（承認）は必ず実施
• Step 6は承認後のみ実行
• gitコミットも承認後

実践ガイド・エラー対応・スキル改善

詳細は references/practical-guide.md を参照

参照タイミング：

• 削除実行中に問題が発生した時 → practical-guide.md の「トラブルシューティング」
• 具体的な削除例が知りたい時 → practical-guide.md の「実例：na-script削除」
• スキルを改善・カスタマイズしたい時 → practical-guide.md の「スキルの継続的改善」
• 人間による最終確認が必要な時 → practical-guide.md の「目視確認チェックリスト」

対話例：承認制ワークフローの実践

シナリオ1: 「未使用機能を整理したい」→ 7ステップワークフロー

ユーザー: 「未使用機能を整理したい」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1: 候補発見（自動）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: audit-unused.mjs を実行
→ 候補3件を発見
- feature-a: 空ディレクトリ
- feature-b: Sidebarなし、参照あり
- feature-c: 設定のみ

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2: 詳細調査（自動）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: 各候補を詳細調査
- feature-a: 参照0件、DBなし → 🔴 即座削除可能
- feature-b: 参照5件（うち4件はコメントアウト）、DBあり（履歴15件）
- feature-c: 参照1件（設定ファイルのみ）、未使用

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 3: 影響分析（自動）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: 影響を分析
- feature-b: 履歴15件失う、型定義を他と共有（修正必要）
- feature-c: 影響なし（設定のみ）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 4: 解説ドキュメント作成（自動）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: レポート作成完了

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 5: ユーザー提示・承認（承認ポイント①）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント:
「調査完了しました。削除候補レポートです：

🔴 【即座削除可能】
- feature-a: 空ディレクトリ（リスクなし）
- feature-c: 設定のみ（リスクなし）

🟡 【要確認】
- feature-b: 履歴15件あり
  → 完全削除: 履歴が失われます
  → 無効化: 履歴は保持、新規使用のみ不可

🎯 推奨アクション:
A) 🔴を削除、🟡を無効化
B) 🔴のみ削除
C) 個別に確認
D) 保留

どうしますか？」

ユーザー: 「Bで。feature-bはまた今度考える」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 6: 削除実行（承認後）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント:
「承認ありがとうございます。DRY RUNで最終確認します...」
→ DRY RUN実行
→ 「以下を削除します：
   - app/(authenticated)/feature-a/（空ディレクトリ）
   - lib/settings/feature-c.ts（設定ファイル）
   実行しますか？」

ユーザー: 「はい」

エージェント: 削除実行 → 検証
→ 「✅ 削除完了しました」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 7: 完了記録（承認ポイント②）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント:
「完了レポートです：
- feature-a: ✅ 削除完了
- feature-c: ✅ 削除完了
- 型チェック: 通過
- Lint: 通過

コミットしますか？

git add . && git commit -m "cleanup: remove feature-a, feature-c"

」

ユーザー: 「OK」
エージェント: コミット完了

シナリオ2: 「na-script削除して」→ 詳細調査の重要性

ユーザー: 「na-script削除して」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1-4: 調査・解説作成（自動）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント:
- ls -la app/(authenticated)/na-script/
→ 空のディレクトリを確認
→ grep -rn "na-script" app/ lib/
→ 参照なしを確認

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 5: ユーザー提示・承認（承認ポイント）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント:
「na-script を調査しました：

📍 状況:
- 空のディレクトリ: app/(authenticated)/na-script/
- コード参照: 0件
- DB関連: なし

⚠️ リスク: なし

🗑️ 即座に削除可能です。実行しますか？」

ユーザー: 「お願い」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 6-7: 実行・検証・記録
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: 削除 → 検証 → コミット承認 → 完了

シナリオ3: 「transcript機能削除したい」→ 誤検出防止

ユーザー: 「transcript機能削除したい」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1-3: 調査（自動）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: audit-unused.mjs
→ 「⚠️ 非表示だが使用中: transcript」「参照: 15件」

エージェント: （違和感）「15件も参照がある...」
→ grep -rn "transcript" lib/ --include="*.ts"
→ 「あ、これは TRANSCRIPT プロンプトキー」
→ 「minutes 機能で使用されている！」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 4: 解説ドキュメント作成（自動）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント: 重要な発見を記録

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 5: ユーザー提示・承認（承認ポイント）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
エージェント:
「⚠️ 重要な発見があります：

調査した結果、transcript（TRANSCRIPT）は
議事録作成機能で使用されているプロンプトです。

🔴 削除の影響:
- 議事録作成機能が動作しなくなります
- 過去の議事録履歴が参照できなくなります

💡 選択肢:
A) 完全削除（議事録作成も削除）
B) 削除しない（推奨）
C) 議事録作成からTRANSCRIPT参照を削除してから実施

※ 推奨は B) です。議事録作成機能は現在使用中です。」

ユーザー: 「Bで。気づいてよかった」

エージェント: 「保留として記録します。調査結果は 
docs/backlog/ に保存しておきます。」

スキルの継続的改善

このスキルを使用する際、以下の改善機会があれば即座に更新してください：

1. 「この手順がない」 → SKILL.md に追加
2. 「このスクリプトがほしい」 → scripts/ に作成
3. 「説明がわかりにくい」 → SKILL.md を書き換え
4. 「エラーが出た」 → トラブルシューティング追加
5. 「もっと効率的な方法がある」 → ベストプラクティス更新
6. 「スクリプトに頼りすぎた」 → エージェンティック対応の例を追加

改善例:

使用中: 「audit-unused.mjs が [xxx] を検出できていない」
↓
即座に修正: スクリプトに [xxx] の検出ロジックを追加
↓
コミット: git commit -m "refactor(skill): improve audit-unused - add [xxx] detection"

v3.0 改善の記録（承認制ワークフロー）

v2.0 改善の記録