utility-self-improving

name	utility-self-improving
description	過去セッション履歴 (~/.claude/archive/) からユーザーが繰り返し指摘したパターン (3 回以上観測) を抽出し、dotfiles の Claude 設定 (CLAUDE.md/rules/skills/agents/hooks) を改善する Draft PR を作成する。「自己改善」「過去履歴から改善を抽出」「最近の指摘を rules に反映したい」「ハーネスを継続改善」などで起動。引数で解析期間 (日数、省略時は直近 7 日) を指定可能。
allowed-tools	Read, Edit, Write, Glob, Bash, Agent

utility-self-improving

目的

Claude Code を日常的に使うなかで、ユーザーが繰り返し指摘する内容を過去セッション履歴 (~/.claude/archive/*.jsonl) から自動抽出し、dotfilesリポにある Claude 設定 (CLAUDE.md / rules/ / skills/ / agents/ / hooks/) の改善 Draft PR を作成する。

なぜ「繰り返し」だけを対象にするか: 一回限りの指摘 (場面依存の好み・気分・誤読) を恒久ルール化すると、誤った"反省"が積み上がり Claude の挙動が硬直化する。3回以上の観測閾値は、偶発的な指摘とパターン化した不満を切り分けるための実効的なフィルタである。閾値を緩めるとノイズが増え、厳しくすると改善機会を逃す。3 は経験則として保守側に置いている。

なぜ自動マージしないか: ヒューリスティック抽出も主題クラスタリングも判定誤りを含む。誤った"反省"を恒久ルールにすると逆効果になるため、Draft PR で人間レビューを必ず挟む。スキルの責務は「候補を提示すること」であって「決定すること」ではない。

起動

/utility-self-improving [日数]

• 日数 省略時: 直近 7 日
• 例: /utility-self-improving 14 で直近 14 日、/utility-self-improving 30 で直近 30 日

なぜ 7 日か: 直近の指摘だけを対象にして 1 回の PR を小さく保つため (ガードレールの「1 PR あたり最大 5 件」と同じ意図)。観測閾値 (3 セッション以上) を満たすかどうかは履歴の濃さ次第なので、引数で 14 や 30 に広げてよい。

引数の解析:

DAYS="${1:-7}"
# 数値以外は弾く
if ! [[ "$DAYS" =~ ^[0-9]+$ ]]; then
  echo "Error: 日数は正の整数で指定してください"; exit 1
fi

前提

• dotfilesリポは ~/dev/github.com/skanehira/dotfiles に clone 済み
• gh CLI が認証済み (gh auth status で確認)
• ~/.claude/archive/ 配下に jsonl が archive されている (settings.json の SessionEnd hook + claude/hooks/archive-transcript.ts が各セッション終了時に自動コピー、保持期間 90 日。同時に古いファイルは自動削除されるため掃除不要)
• 作業前に dotfilesリポが clean な状態である (uncommitted な変更があれば中断して報告)

なぜ ~/.claude/projects/ を直接見ないのか: 公式は jsonl 形式を「内部形式、将来変更あり」と明言しており、claude-history-sync の bisync 進行中だと中途半端な行を読む可能性もある。SessionEnd hook で確定済みのファイルを ~/.claude/archive/ に immutable コピーすることで、解析対象の安定性と整合性を確保する。

アーキテクチャ

main session が orchestrator、重い処理は subagent に分担:

段階	担当	model	役割
§ 2 抽出	self-improving-extractor subagent	haiku	jsonl の機械的処理。Python スクリプトで強いシグナル候補を絞り込み
§ 3 判定	self-improving-judge subagent	sonnet	クラスタリング + 改善対象判定。言語理解と分類が要
§ 1 § 4-7	main session	(呼び出し元と同じ)	前提チェック・git/gh 操作・PR 文面生成

subagent はそれぞれ fresh context で起動するため、main セッションは大量の jsonl 内容や個別の発言を context に積まずに済む (機密情報の漏出リスクと token cost の両方を抑える)。

進捗ログの記録 (実行中の状況可視化)

extractor / judge は fresh context の subagent なので、実行中の細かい進捗は main セッションの画面に出ない。これを補うため、起動形態にかかわらず ~/.claude/logs/self-improving-progress.log に主要マイルストーンを追記する。claude -p でヘッドレス実行する場合は stdout が完了時に 1 度しか書かれないため、このログが実行中の唯一の可視情報になる。

書き込みルール

main session も subagent も、以下のタイミングで Bash で 1 行追記する:

PROGRESS_LOG="$HOME/.claude/logs/self-improving-progress.log"
mkdir -p "$(dirname "$PROGRESS_LOG")"
echo "[$(date '+%Y-%m-%d %H:%M:%S')] [<role>] <message>" >> "$PROGRESS_LOG"

<role> は main / extractor / judge。<message> は段階名と要点を 1 行で。

マイルストーン

Role	タイミング	メッセージ例
main	§ 1 開始/完了	§ 1 前提チェック完了 (archive: N files, dotfiles: clean)
main	§ 2 extractor 起動前/復帰後	§ 2 extractor 復帰 (typed=761, strong=46)
main	§ 3 judge 起動前/復帰後	§ 3 judge 復帰 (clusters_adopted=N, rule_audit=M)
main	§ 4 ブランチ作成・各クラスタ反映	§ 4 cluster 1/3 applied (CLAUDE.md L11)
main	§ 5 コミット完了ごと	§ 5 commit (SHA short)
main	§ 6 PR 作成	§ 6 PR #N created (draft)
main	§ 7 インラインコメント完了	§ 7 inline comment posted (line N)
main	§ 8 rule-audit 集計	§ 8 rule-audit recorded (duplicates=N, conflicts=M, new=K)
main	全工程完了	全工程完了 (PR=#N or なし)

失敗時の書き込み

例外発生・中断時にも [<role>] FAILED: <理由> を書く。これがあれば「どこで止まったか」が即わかる。

進捗の確認

実行中の状況は別ペインで追う:

tail -f ~/.claude/logs/self-improving-progress.log

処理フロー

全体は次の 7 段階。途中で失敗したらロールバックして報告する。半端な PR を残さない。各段階の境界で進捗ログを書く (詳細は前章)。

1. 前提チェック

# archive ディレクトリ
test -d ~/.claude/archive && find ~/.claude/archive -name "*.jsonl" -type f -mtime -${DAYS} | head -1

# dotfiles リポの状態
(cd ~/dev/github.com/skanehira/dotfiles && git status --porcelain)

• archive が存在しない or 空: 「SessionEnd hook (claude/hooks/archive-transcript.ts) が動作してから再実行してください」と報告して終了。エラー扱いではない
• dotfiles リポが dirty: 中断して人間に対応を依頼

2. 指摘の抽出 (subagent 委譲)

Agent ツールで self-improving-extractor (model: haiku) を起動する。

入力:

• days: 解析期間 (引数)
• output_path: scratchpad 配下の strong-signals.jsonl

extractor が担当する処理:

1. ~/.claude/archive/ の jsonl 走査
2. promptSource: "typed" な純粋ユーザー発言の抽出
3. <command-message> や <local-command-stdout> で始まる発言の除外
4. heuristics.md のシグナルパターンに合致する候補のフィルタ
5. 強いシグナル (direct_neg / stop / correction / retry / expectation_gap / dissatisfaction / negative_question) を含むものだけ残す

extractor は Python スクリプトを scratchpad に書き出して python3 で実行する。500MB 級のログでも数秒で完走するメカニカル処理。main session は extractor が返す統計値だけを受け取る (件数・期間)。生データは scratchpad の jsonl に残し、context には載せない。

詳細は ~/.claude/agents/self-improving-extractor.md を参照。

3. クラスタリングと改善対象判定 (subagent 委譲)

Agent ツールで self-improving-judge (model: sonnet) を起動する。

入力:

• input_path: extractor が書き出した strong-signals.jsonl
• output_path: scratchpad 配下の clusters.json

judge が担当する処理: 0. 起動時準備: MEMORY.md ロード + gh pr list で過去自己改善 PR の状態 (adopted / rejected / pending) を確認し、MEMORY.md に状態マークを反映する

1. (session_id, content) でデデュープ
2. 引用ブロック内のレビューコメントを heuristics.md の判別基準で取り扱う (Claude 出力へのレビュー → 学習対象、顧客資料の貼り付け → 除外)
3. 主題ごとのクラスタリング (Claude の言語理解で判断)
4. 観測セッション数 3 件未満は skipped へ
5. 上位 5 件採用、観測数の多い順にソート (ただし MEMORY.md の [rejected] [pending] と意味照合一致するクラスタは採用せず previously_rejected / pending_review で skip)
6. classification.md のフローで各クラスタの更新対象を決定
7. 機密情報を含まない clusters.json を出力 (プロジェクト名・セッションID・発言抜粋は持ち込まない)

main session は judge の clusters.json を Read で読み込み、§ 4 以降に進む。

詳細は ~/.claude/agents/self-improving-judge.md を参照。

4. 変更の適用

clusters.json の clusters_adopted を順に処理する:

• 作業ディレクトリ: ~/dev/github.com/skanehira/dotfiles
• git checkout master && git pull --ff-only origin master で最新化
• ブランチ作成: chore/self-improvement-YYYY-MM-DD
  • 同名ブランチが既に存在する場合は -2, -3 のサフィックスを付ける
• 各クラスタについて:
  1. target_file を Read で読む
  2. anchor (既存テキスト) を Edit ツールの old_string の手がかりにする
  3. anchor を含む行の直後に proposed_addition を挿入

既存テキストとの整合性に注意: 重複・矛盾が出ないようにマージする (judge が一定の整合を見ているが、main 側で再確認)。

5. コミット

/workflow-commit を呼び出すか、直接 Conventional Commit 形式で commit する。

• 複数クラスタは複数コミットに分割 (1クラスタ = 1コミット)。後段のインラインコメントを hunk 単位で付けやすくするため
• メッセージ例: 📝 docs(claude): avoid 'any' type in TypeScript edits
• body には観測回数 (匿名化済み) と観測パターンの類型を含める。プロジェクト名・セッションID・ユーザーの生の発言抜粋・コード引用は含めない (§ 7「機密情報の取り扱い」と同じ原則。コミットメッセージも git log で永続化されるため同等)

6. Draft PR 作成

/workflow-create-draft-pr を呼び出して PR を作成する。

• ターゲットブランチ: master
• 必ず Draft で作成 (gh pr create --draft)。直接マージは禁止
• PR 本文テンプレート:

## 解析サマリ

| 項目 | 値 |
|---|---|
| 解析期間 | YYYY-MM-DD ~ YYYY-MM-DD |
| 対象セッション数 | N |
| 抽出された指摘の総数 | M |
| クラスタ数 (3回以上) | K |
| PR採用件数 | J / K |

## 採用クラスタ

1. **<クラスタ名1>** (N回観測) → `<更新対象ファイル>`
2. **<クラスタ名2>** (M回観測) → `<更新対象ファイル>`
...

## 確認方法

各 hunk のインラインコメントに観測根拠を記載しています。誤った"反省"を採用していないか確認してから ready for review に切り替えてください。

7. インラインコメントの追加

PR 作成後、各 hunk に gh api 経由でインラインコメントを追加する。

gh api -X POST \
  /repos/skanehira/dotfiles/pulls/<PR番号>/comments \
  -f body="<コメント本文>" \
  -f commit_id="<コミットSHA>" \
  -f path="<ファイルパス>" \
  -F line=<行番号> \
  -f side=RIGHT

コメント本文の必須要素:

**観測回数**: N セッション (M 個の異なる作業対象)

**観測パターン**:
<指摘の類型を抽象化した記述。具体的な依頼内容・引用・固有名詞は含めない>

**推定根本原因**:
<なぜユーザーが繰り返し指摘したのか、観察された行動の要約>

これは「自動学習が誤っていないか」を人間がレビューするための判断材料である。観測根拠が無いと、ユーザーが PR を見ても採否を判断できない。observation_pattern と estimated_root_cause は judge が生成した clusters.json の同名フィールドをそのまま使う。

機密情報の取り扱い (絶対遵守):

PR コメント・コミットメッセージ・PR 本文はすべて GitHub に永続化され、リポジトリへのアクセス権を持つ第三者が閲覧可能。dotfiles リポジトリは公開設定の可能性があり、解析対象のセッションには顧客名・要件詳細・社内固有名詞・契約情報が含まれることがある。以下は PR コメント・コミットメッセージ・PR 本文 に絶対に含めない:

• プロジェクト名・リポジトリ名・組織名 — owner/repo 形式の具体名は禁止。「N 個の異なる作業対象」のように匿名化する
• セッションID (UUID) — 一意の識別子は GitHub に永続化されるため記載しない (内部処理のメタデータとしては保持してよいが、外に出さない)
• ユーザーの生の発言抜粋 — 引用ブロック (> ...) での発言転載は禁止。発言の内容は 指摘の類型 に抽象化してから記述する
• コードや設計書の引用 — 機密情報を含むことがあるため一切引用しない
• ファイルパス・URL・ドメイン名・人名 — 解析対象セッションに出てきたものは記載しない (dotfiles リポ自身のパスは除く)

抽象化の原則: 「観測パターン」セクションでは指摘の 行動カテゴリ だけ記述する。「ユーザーが具体例の追加を繰り返し指示するパターン」「ユーザーが依頼スコープ外の論点を出した点を繰り返し指摘するパターン」のように、原文や事例固有の文脈は捨てる。judge が生成する clusters.json はこの原則に沿って書かれているはずだが、main 側で最終チェックする。

この制約を守れない場合は、コメントを付けない。インラインコメントは判断材料の補助であって必須ではない。守れない方が悪い。Draft PR で人間レビュアーがマージ判断する仕組みは残るので、コメント無しでも運用は破綻しない。

行番号の決定: 各コミットの diff から、追加行 (+) の最初の行に付ける。ファイル全体の追記なら追加ブロックの先頭行。

8. ルール監査結果のローカル蓄積 (PR は作らない)

judge の出力 clusters.json の rule_audit (duplicates / conflicts) は PR にしない。差分ゼロの PR は GitHub の慣行に反するし、観察結果は既に judge subagent の MEMORY.md (~/.claude/agent-memory/self-improving-judge/MEMORY.md) の「ルール監査で検出した整理候補」セクションに蓄積されている (judge が § 6 で curate する)。

main session は 最終応答の markdown サマリ に rule_audit を含めるだけにする:

### ルール監査結果

判定段階で検出された既存ルール (CLAUDE.md / rules/) の整理候補。詳細は `~/.claude/agent-memory/self-improving-judge/MEMORY.md` の「ルール監査で検出した整理候補」セクションを参照。

| 種別 | 件数 | うち新規 | うち継続 (previously_reported) |
|---|---|---|---|
| duplicates | D | D_new | D_prev |
| conflicts | C | C_new | C_prev |

これにより:

• 観察結果は MEMORY.md と最終応答のサマリの 2 箇所で確認できる
• 差分ゼロの PR が積み上がらない
• 整理 (削除・統合) の判断と作業は人間が必要なときに MEMORY.md を見て手作業で行う

人間が rule_audit を整理したい場合は、自分で個別のコミットを切って master に直接 push するか、専用 PR を出す。utility-self-improving はそこには介入しない。

ガードレール (再掲)

• Draft PR 必須: 自動マージは絶対にしない
• 観測閾値 3 セッション: それ未満は skipped ログに残すのみ
• 1 PR あたり最大 5 件: 認知負荷とレビュー品質のバランス
• failure-stops-pipeline: 途中で gh がエラー、ブランチ作成失敗、commit 失敗、subagent 失敗のいずれかが起きたらロールバックして報告
• 既存変更の保護: dotfilesリポに uncommitted な変更があれば最初に中断
• subagent の責務範囲を守る: extractor は jsonl 抽出のみ、judge は判定のみ、Edit/commit/PR は main の担当。subagent から git 操作はしない
• PR が大きすぎる場合の自己抑制: 1 クラスタの diff が 200 行を超えるなら、それは「ルール追記」ではなく「リファクタ」になっている可能性が高い。スコープを切って分割する

出力サマリ

完了時にユーザーへ次を報告する:

解析期間: YYYY-MM-DD ~ YYYY-MM-DD
対象セッション数: N
抽出された指摘の総数: M
クラスタ数 (3 セッション以上): K
PR採用件数: J / K
スキップ記録: <scratchpad/self-improvement-skipped-YYYY-MM-DD.jsonl>
PR URL: https://github.com/skanehira/dotfiles/pull/XXX

失敗時の挙動

失敗ケース	振る舞い
archive が空 (SessionEnd hook 未実行)	報告して終了。エラー扱いではない
3 セッション以上のクラスタが 0 件	「学習対象の繰り返しパターンが見つかりませんでした」と報告。skipped ログのパスを案内
dotfilesに uncommitted な変更がある	中断して人間に対応を依頼
extractor / judge subagent が失敗	エラー内容を報告して中断。retry はせず、人間の判断を仰ぐ (誤った "成功扱い" を防ぐため)
git push 失敗・gh API 失敗	ローカルブランチは残したまま中断、エラー内容を報告
インラインコメント API がレート制限	コメント済みのものは残し、未完了分を sleep + retry。3 回失敗で諦めて報告

ドライランモード

破壊的操作なしで動作確認したい場合:

/utility-self-improving 7 --dry-run

• § 1〜§ 3 (前提チェック・抽出・判定) までは実行
• § 4 以降 (ブランチ作成・コミット・PR 作成・インラインコメント) はスキップ
• 結果サマリと clusters.json の内容を標準出力に表示するのみ

これは最初の数回 (スキルの挙動を確かめる段階) で使う。挙動を確認できたら省略してよい。

参考

• 判定ヒューリスティック: references/heuristics.md
• 改善対象の振り分け基準 (どのファイルに書くか): references/classification.md
• 施策選択ガイド (強制レベル・公式準拠の決定木): references/treatment-guide.md
• subagent (extractor): ~/.claude/agents/self-improving-extractor.md
• subagent (judge): ~/.claude/agents/self-improving-judge.md