skillopt-sleep

SkillOpt-Sleep：ローカルの Claude エージェントを使用状況に応じて自己進化させる

SkillOpt-Sleep は、ユーザーのエージェントに睡眠サイクルを提供します。必要に応じて、または毎晩のスケジュールに従って、過去の Claude Code セッションを実際に確認し、選択したバックエンドで繰り返し行うタスクを再実行して、学んだ内容をメモリ（CLAUDE.md）とスキル（SKILL.md）に集約します。デフォルトで検証ゲートが有効な場合は、保留タスクのスコアを改善する変更のみを保持します。稼働中のファイルが変更されるのは、明示的に採用するか、ユーザーが --auto-adopt をリクエストした場合に限られます。モデルの重みを学習させることなく、このユーザーが繰り返し行う作業の改善を目指し、採用された各提案は、その実行で保留されたタスクを使って測定可能です。これは、デプロイ時に行う学習に相当します。短期的な経験 → 長期的な能力。

3 つのアイデアを組み合わせています。

• SkillOpt — スキル／メモリのドキュメントは学習可能なテキストです。追加／削除／置換の編集は範囲が限定され、保留データを使ったゲートを通過した場合にのみ採用されます。却下された編集は、確認用に実行レポートへ記録されます。
• Claude Dreams — 過去のセッションを読み込み、保護された学習済みブロック内で変更を提案する統合処理です。入力は変更されず、出力は採用前に確認されます。
• エージェントの睡眠 — 定期的なバックグラウンド再生によって、エピソードを永続的なスキルに変換します。

このスキルを使用する場面

ユーザーが次のいずれかを望んでいる場合に実行します。

• 「使い方からエージェントに学習させたい」／「使えば使うほど賢くしたい」／「セッションをまたいで自分の好みを覚えてほしい」
• 毎晩のスケジュールまたは必要に応じたオフラインでの自己改善／夢／睡眠の実行
• 過去のセッション／軌跡を確認し、繰り返し行うタスクを抽出する
• フィードバックを CLAUDE.md または管理対象のスキルに集約する
• サイクルをスケジュールする（cron）、または段階的に準備された提案を採用する

サイクル（6 段階）

1. 収集 — ~/.claude/projects/*/<session>.jsonl と ~/.claude/history.jsonl を読み込みます（読み取り専用）→ セッションの要約。
2. 抽出 — 要約 → TaskRecords（繰り返しの意図 + 結果ラベル + 可能な場合は検証可能な参照）。
3. 再実行 — 現在のスキルとメモリを適用し、選択したバックエンドでタスクを再実行 → （ハード、ソフト）スコア。
4. 統合 — 失敗を振り返る → 範囲を限定した編集を提案 → 保留データの一部でゲート判定。デフォルトのゲートが有効な場合、スコアが厳密に改善したときのみ採用します。
5. 準備 — 採用された proposed_CLAUDE.md および／または proposed_SKILL.md と、report.md、report.json、manifest.json、diagnostics.json を <project>/.skillopt-sleep/staging/<timestamp>/ に書き込みます。 稼働中のファイルは一切変更されません。 却下された実行でもレポートは作成されますが、稼働中ファイルの置き換え案は作成されません。
6. 採用 — 明示的に（またはオプトインによる自動採用で）ステージングされたファイルを稼働中のファイルにコピーします。事前にバックアップを作成します。

実行方法

/skillopt-sleep コマンドを優先してください。内部では、同梱のランナーを呼び出します。

"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" status                       # what's happened
"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" dry-run --project "$(pwd)"    # no-staging preview
"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" run --project "$(pwd)"        # full cycle, stages a proposal
"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" adopt --project "$(pwd)"      # apply staged proposal (with backup)

• デフォルトのバックエンドは mock です（決定的な動作で、API 利用料はかかりません）。一連の処理を試すのに適しています。
• モデル駆動型の最適化にユーザーの実際の利用枠を使うには、--backend claude または --backend codex を追加します。保留データでの改善は、その実行に固有の証拠であり、より広範な改善を保証するものではありません。結果はタスク、モデル、チェックに左右されます。
• スコープは、実行したプロジェクトがデフォルトです。--scope all を指定すると、すべての Claude プロジェクトからデータを収集し、現在の実行で設定されたターゲットに反映します。
• 実バックエンドを使うと、切り詰められたトランスクリプト／タスクの内容がプロバイダーに送信されます。機密性の高いセッションで使用する前に、以下のデータ境界ルールを確認してください。

スケジュール設定

"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" schedule --project "$(pwd)" --hour 3 --minute 17
"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" unschedule --project "$(pwd)"

毎晩実行する cron エントリーをインストールします。unschedule --all を実行すると、管理対象のエントリーがすべて削除されます。

共通 CLI フラグ

フラグ	デフォルト	説明
--project PATH	cwd	改善対象のプロジェクトディレクトリ
--scope all|invoked	invoked	収集範囲
--backend mock|claude|codex|copilot|handoff|azure_openai	mock	バックエンド（mock = プロバイダーへの呼び出しなし）
--model NAME	backend default	リプレイに使用するモデルを上書き
--source claude|codex|auto	claude	トランスクリプトのソース
--lookback-hours N	72	収集対象期間
--max-sessions N	derived	収集するセッション数の上限。デフォルトはタスク数の上限の 3 倍（現在のデフォルトでは 120）
--max-tasks N	40	抽出するタスク数の上限
--target-skill-path PATH	~/.claude/skills/skillopt-sleep-learned/SKILL.md	改善対象の SKILL.md を明示的に指定
--tasks-file PATH	—	レビュー済みの TaskRecord JSON（収集をスキップ）
--progress	off	フェーズの進捗を stderr に出力
--auto-adopt	off	ゲートを通過した場合に自動適用
--edit-budget N	4	夜間に実行する編集回数の上限
--preferences TEXT	empty	オプティマイザーの振り返りの事前情報にハウスルールを追加
--json	off	機械可読な JSON 出力

CLI には、ソース／ランタイムのパスを上書きするフラグ（--claude-home、--codex-home、 および --codex-path）と、アクション固有のフラグもあります。正式なインターフェースは python -m skillopt_sleep <action> --help で確認してください。

設定キー（~/.skillopt-sleep/config.json）

CLI フラグに加えて、高度な動作は次の設定で制御できます。

• preferences — オプティマイザーの振り返りステップに追加する自由形式のハウスルール（例：「常に async/await を使う」「回答は \boxed{} で囲む」）。
• gate_mode — on（デフォルト。検証ゲートあり）または off（貪欲方式。すべての編集を受け入れる）。
• gate_metric — hard、soft、または mixed（デフォルト）。保留データのゲートで使用するスコア方式を制御します。
• gate_no_regression — デフォルトは false です。true に設定すると、検証タスクのいずれかで設定済みのゲートスコアが低下した候補を却下します。
• dream_rollouts — 1 より大きい値にすると、タスクごとの複数ロールアウトによる対照的な振り返りが有効になります。
• recall_k — 0 より大きい値にすると、類似する過去のタスク K 件を夢に呼び戻します（長期記憶）。
• evolve_memory / evolve_skill — CLAUDE.md と SKILL.md の統合を個別に切り替えます。

メモリの統合

スリープサイクルでは、次の両方を統合できます。

• SKILL.md — 管理対象のスキルファイル（編集範囲を限定：追加／削除／置換）
• CLAUDE.md — プロジェクトのメモリ（同様に編集範囲を限定）

デフォルトで有効なゲートでは、どちらも同じ保留スコアで評価されます。 スキルのみを統合するには evolve_memory: false を設定し、メモリのみを統合するには evolve_skill: false を設定します。

厳守事項

• このスキルの一環として、ユーザーの CLAUDE.md / SKILL.md を手動で編集しては 絶対にいけません。エンジンの明示的な adopt、またはユーザーが要求した --auto-adopt の経路を使い、 ステージングマニフェストを適用する前に、既存の運用ファイルをバックアップしてください。
• 収集は読み取り専用です。mock リプレイでは副作用は発生しません。
• 実バックエンドでは、切り詰めたトランスクリプトの抜粋と派生タスクが、抽出、リプレイ、判定、振り返りのために 選択したプロバイダーへ送信されます。Claude のトランスクリプトパスでは、これらの呼び出しの前にすべての秘密情報が 必ず取り除かれるとは限りません。事前にプロバイダーポリシーとセッションの内容を確認してください。機密データを扱う場合は、 mock を使うか、harvest --output <file> を実行して JSON を確認・編集し、"reviewed": true を設定したうえで、 --tasks-file を使ってリプレイしてください。実バックエンドは、未レビューのタスクファイルを拒否します。
• 適用を提案する前に、保留ベースライン → 候補のスコアと、提案する編集の正確な内容を必ずユーザーに提示してください。適用の前に根拠を示してください。
• プロバイダーへの呼び出しなしで仕組みの実演を求められた場合は、次を実行してください。 python -m skillopt_sleep.experiments.run_experiment --persona researcher --json — 保留データでの改善とゲートによる却下を示す、決定論的な合成デモです。仕組みを検証するものであり、ユーザー自身のタスクに対する有効性を示すものではありません。

検証／デモ

# deterministic synthetic demo (no API): score rises and the gate blocks a regression
python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves
python -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves

記録された結果、制限事項、サポートされている統合対象については、SkillOpt-Sleep のドキュメントをご覧ください。