skill-evolution

Evolution

このスキルは、スキルライブラリを自動編集せずに、実際の開発シグナルに基づいてスキルライブラリを進化させます。デフォルトの出力はパッチの提案のみです。

存在理由（「受け身すぎる」問題の解決）

デフォルトのフックは、経験をスキルに自動的に集約することなく、「イベントを記録する」ことしかできません。

このスキルの目的は、振り返りを終了時の固定アクションにすることです。

• 各「大きなタスク」の終了時に、スキルを最適化するかどうか、また優先する領域について、60 秒間の質疑応答で確認します
• ユーザーが「最適化する」を選んだ場合は、実際の実行アーティファクトに基づいて、skill-improver を使って最小限のパッチ提案を生成します（スキルライブラリの自動編集は引き続き行いません）

デフォルトの戦略

• コンテキストと失敗を実行アーティファクトに記録します
• 進化候補を生成します
• skill-improver を使って最小限のパッチを提案します
• 人間がパッチを確認して適用します

グローバルフック（推奨）

フックの保存先：~/.claude/skills/skill-evolution/hooks/

フックが自動的に実行されるよう、グローバル設定（またはプロジェクト設定）に追加します。

例：~/.claude/settings.json または <project>/.claude/settings.json にマージします。

Evolution の設定

~/.claude/skills/skill-evolution/hooks/settings.json で動作を設定します。

{
  "min_fail_count": 2,
  "ignore_tool_errors": true,
  "noise_filters": {
    "ignore_patterns": [
      "typescript: type.*already exists",
      "eslint:.*no-unused-vars.*react",
      "prettier:.*prettier-ignore"
    ],
    "max_failures_per_run": 20,
    "recent_only": true,
    "recent_window_minutes": 60
  },
  "output_format": {
    "summary_only": false,
    "include_context": true,
    "include_recent_failures": 20,
    "sort_by": "frequency"
  }
}

設定の説明：

• min_fail_count：候補を生成する前に必要な、単一のエラー種別の最小発生回数
• ignore_tool_errors：ツールレベルのエラー（ユーザーコードのエラーではなく）を無視するかどうか
• noise_filters.ignore_patterns：無視する正規表現パターンのリスト
• max_failures_per_run：セッションごとに記録する失敗の最大数（過剰な記録を防止）
• recent_only：直近の時間枠内の失敗のみを対象にするかどうか
• recent_window_minutes：直近 N 分間の失敗のみをカウントします
• output_format：evolution-candidates.md の出力形式を制御します

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/pre-tool.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/post-bash.sh \"$TOOL_OUTPUT\" \"$EXIT_CODE\""
          }
        ]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/post-tool.sh \"$TOOL_OUTPUT\" \"$EXIT_CODE\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/session-end.sh"
          }
        ]
      }
    ]
  }
}

実行アーティファクト

フックはプロジェクトローカルの実行フォルダーに書き込みます。

<project-root>/runs/evolution/<run_id>/
  logs/
    events.jsonl
    failures.jsonl
    state.json
    context.json
  evolution-candidates.md
  evolution-review.md

run_id は <project-root>/runs/evolution/.current に保存されるため、セッション内のすべてのフックが同じ実行に書き込みます。

Evolution チェックポイント（大きなタスクの終了時に行うデフォルトのアクション）

「成果物を伴う大きなタスク」（たとえば、すでに final.md を作成した、または実行の tasks.md の納品概要を記入した場合）を完了した直後には、終了時に簡単な振り返りを必ず行い、ユーザーに選択肢を提示してください。

会話では、質問は次の 3 つだけにします（負担を減らすため、選択式を推奨します）。

1. この実行に基づいてスキルを最適化しますか？

   • A. はい。今すぐパッチを提案します（まず skill-improver を使って最小限のパッチを生成することを推奨）
   • B. まず問題を記録し、後で最適化します
   • C. 必要ありません

2. 今回、最大の障害となったものは何ですか？

   • A. 入力／コンテキスト項目の不足（入出力の契約を明確にする必要がある）
   • B. 計画や粒度が不明確で大きすぎた（分割するか、検証手順を明確にする必要がある）
   • C. 環境／依存関係／コマンドの問題（スクリプト化またはコマンドの固定が必要）
   • D. UI／デザインの反復（デザインシステムの明確化、または UI サブタスクへの分割が必要）
   • E. 外部サービス／権限／設定（確認ポイントと検証を明確にする必要がある）
   • F. その他（1 文で説明）

3. 最適化で優先したい方向はどれですか？

   • A. 入出力の契約：アーティファクト名、項目、パスを修正する
   • B. インデックス／概要：コンテキストを減らし、再開時のナビゲーション（提案／タスク）を改善する
   • C. スクリプト／テンプレート：繰り返しの手順を決定論的なスクリプトにする
   • D. 確認ポイント：リスクのあるアクションを減らし、より早く、より明確に確認する

実行ルール：

• ユーザーが 1A を選んだ場合：skill-improver を直ちに実行し、入力には run_dir のパスのみを使います（ログを会話に貼り付けないでください）
• ユーザーが 1B を選んだ場合：「障害となった点＋希望する最適化の方向」を evolution-review.md（または対応するワークフロー実行の final.md／tasks.md）に記録し、次回まとめて処理します
• ユーザーが 1C を選んだ場合：中断せず、そのまま終了します（今後の振り返りに備えて、実行アーティファクトは保持します）

進化させるタイミング（Ship Faster を重視）

• Next.js のアップグレードまたは移行に関する問題を解決した
• ガードレールの問題を修正した（lint／typecheck／build）
• Supabase のエラーやマイグレーションのパターンを学んだ
• Stripe のセットアップや課金フローの問題を解決した
• Vercel のデプロイや GitHub CI の問題を解決した
• AI SEO のセットアップやインデックス登録の問題を解決した

進化させる方法

1. フックが最新のシグナルを含む evolution-candidates.md と evolution-review.md を作成します。
2. 大きなタスクの終了時に、3 つのチェックポイントの質問（上記）を尋ね、ユーザーに判断してもらいます。
3. ユーザーが進化させることを選んだ場合：最適な run_dir を指定して skill-improver を実行します（通常、ワークフローの run_dir のほうが進化の run_dir より適しています）。
4. パッチを手動で適用し、スキルを再検証します。

イベントの例

{"ts":"2026-01-11T12:00:00Z","event":"post-bash","category":"build","exit_code":1,"summary":"next build failed: Module not found","artifacts":["logs/failures.jsonl"]}

出力

• evolution-candidates.md（自動生成）
• evolution-review.md（自動生成。3 つの質問を含みます）
• skill-improver が提案するパッチ（手動で適用）

スキルが自動で編集されることはありません。