self-improve

# Self-Improve スキル (Claude Code) blueprint パイプラインの使用ログを分析し、改善案を PR として提出するスキル。 ログは SessionEnd Hook で自動収集され、このスキルで分析・改善サイクルを回す。 ## 仕様参照 分析ポリシーは `core/self-improve.md` に定義。 ログスキーマは `{baseDir}/references/log-schema.md` を参照。 分析サマリースキーマは `{baseDir}/references/analysis-schema.md` を参照。 ## 前提条件 | 条件 | 必須 | 説明 | |------|------|------| | 未分析ログ | ○ | `~/.claude/blueprint-logs/` に `triage.status: open` のログが 1 件以上 | | `gh` CLI | △ | PR 作成時のみ必要 | | blueprint-plugin リポジトリ | △ | PR 作成時のみ。パスは自動検出（`$CLAUDE_PLUGIN_ROOT`） | ## ツール | ツール | 用途 | |--------|------| | Bash | `analyze_logs.sh` 実行、`gh pr create`、git 操作 | | Read | ログファイル読み込み、改善対象ファイル読み込み | | Write/Edit | 改善案の適用 | | Glob | ログファイルの検索 | | AskUserQuestion | 改善案のユーザー承認 | ## 出力 | 出力 | 説明 | |------|------| | 統計レポート | YAML 形式のログ分析サマリー（stdout 表示） | | 改善 PR | `sizukutamago/blueprint-plugin` への GitHub PR | | 分析サマリー | `~/.claude/blueprint-logs/analysis/analysis-{YYYYMMDD}.yaml` | | トリアージ更新 | 対象ログの `triage.status` を `pr_created` に更新 | ## コマンドオプション | オプション | 説明 | ワークフロー | |-----------|------|-------------| | `/blueprint-improve` | 分析 → 改善案提示 → PR 作成 | Step 1〜6 全実行 | | `/blueprint-improve --stats` | 統計レポートのみ表示 | Step 1 のみ実行して終了 | | `/blueprint-improve --cleanup` | 期限切れログの削除 | 専用フローを実行（下記参照） | ## ワークフロー ### Step 0: モード判定 引数を確認し、モードに応じて分岐する: - `--stats` → Step 1 のみ実行して統計レポートを表示し終了 - `--cleanup` → 期限切れログ削除フローへ（下記「cleanup モード」参照） - 引数なし → Step 1〜6 を順に実行 ### Step 1: ログ読み込みと統計レポート生成 ```bash # 未分析ログ数の確認 bash "${baseDir}/scripts/analyze_logs.sh" --count # 統計レポートの生成 bash "${baseDir}/scripts/analyze_logs.sh" --details ``` 未分析ログが 0 件の場合は「分析対象のログがありません」と報告して終了。 統計レポートの出力を読み取り、以下を把握: - ログ件数と期間（log_range の from / to） - Gate findings の P0/P1/P2 分布 - エラー数とユーザー修正数 - category 別・phase 別・stage 別の分布 `--stats` モードの場合はここで統計レポートをユーザーに表示して終了。 ### Step 2: パターン分析 `core/self-improve.md` の分析ポリシーに従い、統計レポートから改善パターンを特定する。 1. **recurring_findings の検出**: category 別集計から閾値（3 回以上）を超えるパターンを抽出 2. **common_errors の検出**: phase 別集計から反復エラーを抽出 3. **user_corrections の検出**: stage 別修正頻度から生成品質の問題を特定 検出したパターンから、改善対象ファイルを `core/self-improve.md` の「改善案のカテゴリ」表に従い特定する: | パターン種別 | 対象ファイル | 改善カテゴリ | |-------------|-------------|-------------| | Gate の category 反復 | `core/review-criteria.md` | review_criteria_update | | /requirements 関連の修正 | `core/requirements.md`, `skills/requirements/SKILL.md` | requirements_update | | /spec 関連の修正 | `core/spec.md` | spec_update | | Contract 関連の指摘 | `core/contract-schema.md` | schema_update | | 実装規約のエラー | `core/defaults/` | default_update | | テンプレート品質 | `skills/*/references/` | template_update | | スキル手順の問題 | `skills/*/SKILL.md` | skill_update | 改善対象ファイルを Read ツールで読み込み、具体的な改善案を生成する。 ### Step 3: 改善案提示 + ユーザー承認 AskUserQuestion で改善案を一覧提示する。以下のフォーマットで提示: ``` ## 改善案一覧（{count} 件） 分析期間: {from} ~ {to}（{log_count} セッション） ### [1] {改善タイトル} ⬆ {priority} - 根拠: {category} が {count} 回検出 - 対象: {target_file} - 内容: {description} ### [2] ... --- 採用する改善案の番号を選択してください（例: 1,3） 全て採用: all / 全て棄却: none ``` ユーザーが採用/棄却を選択。全棄却の場合はログの triage.status を `analyzed` に更新して終了。 ### Step 4: 変更適用 + PR 作成 ブランチ作成前に、blueprint-plugin リポジトリの状態を確認する: ```bash PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}" # 作業ディレクトリの状態確認（未コミット変更があれば警告） git -C "$PLUGIN_ROOT" status --short # feature branch を作成（日時で一意性を保証） BRANCH_NAME="self-improve/$(date +%Y%m%d-%H%M%S)" git -C "$PLUGIN_ROOT" checkout -b "$BRANCH_NAME" ``` 未コミット変更がある場合はユーザーに警告し、続行するか確認する。 承認された改善を Edit/Write ツールで適用した後: ```bash # 変更したファイルのみを明示的に add（git add -A は使わない） git -C "$PLUGIN_ROOT" add <変更したファイルパス1> <変更したファイルパス2> ... git -C "$PLUGIN_ROOT" commit -m "$(cat <<'EOF' self-improve: [改善の要約] EOF )" # push + PR 作成 git -C "$PLUGIN_ROOT" push -u origin "$BRANCH_NAME" PR_URL=$(gh pr create --repo sizukutamago/blueprint-plugin \ --title "self-improve: [改善の要約]" \ --body "$(cat <<'EOF' ## Summary Blueprint self-improvement: {改善の要約} ## Evidence - 分析期間: {from} ~ {to} ({count} セッション) - 検出パターン: {patterns} ## Changes - {file}: {変更概要} --- Auto-generated by `/blueprint-improve` EOF )") ``` `PR_URL` を後続の Step 5 で使用するため保持する。 ### Step 5: トリアージ更新 Step 1 で分析対象となったログのみを更新する。統計レポートの `log_range.from` / `log_range.to` を使い、対象範囲を特定する: ```bash # Step 1 で取得した対象ログ一覧を使用（analyze_logs.sh が処理した open ログ） FIRST_LOG="<log_range.from の値>" LAST_LOG="<log_range.to の値>" # 対象ログのみ更新（全 open ログではなく、分析対象に含まれたもののみ） for log_file in ~/.claude/blueprint-logs/bl-*.yaml; do [ -f "$log_file" ] || continue LOG_ID=$(basename "$log_file" .yaml) # log_range 内のログのみ対象 if [[ "$LOG_ID" >= "$FIRST_LOG" && "$LOG_ID" <= "$LAST_LOG" ]] && grep -q 'status: open' "$log_file"; then sed -i '' 's/status: open/status: pr_created/' "$log_file" sed -i '' "s/analysis_range: \"\"/analysis_range: \"${FIRST_LOG} ~ ${LAST_LOG}\"/" "$log_file" sed -i '' "s|pr_url: \"\"|pr_url: \"${PR_URL}\"|" "$log_file" fi done ``` ### Step 6: 分析サマリー保存 `~/.claude/blueprint-logs/analysis/analysis-{YYYYMMDD}.yaml` に分析結果を保存。 ディレクトリが存在しない場合は作成する。 スキーマは `{baseDir}/references/analysis-schema.md` を参照。 --- ## cleanup モード `/blueprint-improve --cleanup` で実行。期限切れログ（`privacy.expires_at` が現在日時より前）を削除する。 ```bash # 期限切れログの検出 EXPIRED_COUNT=0 for log_file in ~/.claude/blueprint-logs/bl-*.yaml; do [ -f "$log_file" ] || continue EXPIRES=$(grep 'expires_at:' "$log_file" | head -1 | sed 's/.*: *//' | tr -d '"') if [ -n "$EXPIRES" ] && [[ "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$EXPIRES" ]]; then echo "期限切れ: $(basename "$log_file") (expires: $EXPIRES)" EXPIRED_COUNT=$((EXPIRED_COUNT + 1)) fi done ``` 期限切れログがある場合、AskUserQuestion で削除確認を取ってから `rm` で削除する。 `triage.status` が `analyzed` 以降のログは TTL に関わらず保持する（`core/self-improve.md` のポリシーに従う）。 ## 原則 - **ユーザー承認必須**: PR 作成前に必ず改善案の承認を取得する - **最小変更**: 1 PR に含める改善は関連するパターンのみ。無関係な改善は分割する - **エビデンス駆動**: 全ての改善案に検出パターンと件数の根拠を添える - **重複防止**: fingerprint と analysis_range で同一ログの再分析を防ぐ - **明示的ステージング**: `git add` は変更したファイルのパスを明示的に指定する（`-A` は使わない） ## エラーハンドリング | 状況 | 対応 | |------|------| | ログ 0 件 | 「分析対象のログがありません」と報告して終了 | | `gh` CLI 未インストール | 改善案の表示まで行い、PR 作成はスキップ。手動手順を案内 | | blueprint-plugin リポが見つからない | `$CLAUDE_PLUGIN_ROOT` でフォールバック | | 分析スクリプトエラー | エラー内容を表示し、ログファイルの直接読み込みにフォールバック | | リポに未コミット変更あり | ユーザーに警告し、続行するか確認 | | ブランチ名衝突 | 日時ベースの命名（`%Y%m%d-%H%M%S`）で回避 |