opinions-md-dotfiles

name	opinions-md-dotfiles
description	OPINIONS.local.md を入力に、全マシン共通の要約版 (dotfiles 版) を蒸留する。

OPINIONS.md ジェネレータ

すでにある OPINIONS.local.md (opinions-md スキルが対話ログから蒸留した、ドメイン固有の内容込み・Evidence 付きの詳細版) を唯一の入力に、ドメイン固有の個別具体と Evidence を全部落とした 全マシン共通の要約版 (dotfiles 版) を蒸留する。dotfiles にチェックインできる状態にするのがゴール。

前提

• 入力となる local 版が既に存在すること。既定パスは <workspace>/.claude/OPINIONS.local.md (opinions-md スキルの出力。<workspace> は入力元ワークスペースのルートで、今 opinions-md-dotfiles を実行しているワークスペースと同じとは限らない)。パスをユーザーに確認する。

• 出力先の既定は ~/.claude/OPINIONS.md (全マシン共通の要約版の置き場。ワークスペーススコープの local 版に対し、こちらはユーザーグローバルスコープ)。ただし ~/.claude/OPINIONS.md 直書きは不可逆寄りなので、まず作業ディレクトリ $OUT に OPINIONS.dotfiles.md として出し、ユーザー確認後に配置する一段クッションを既定にする。$OUT は入出力いずれのワークスペースにも依存しない中間ファイルなので、mktemp -d で作った一時ディレクトリに置く:

  OUT="$(mktemp -d -t opinions-md-dotfiles)"
  

手順

フェーズ 0: 入力の確認と通読

1. 入力となる local 版のパスと、出力先をユーザーに確認する (前提の既定値を提示して差分だけ詰める)。
2. local 版を 頭から最後まで通読し、章立て (h2 セクションと各 h3 信念、前書き、末尾のドメイン固有章の有無) を把握する。複数箇所を編集するので、着手前に全体像を持つ (markdown-editing ルールに従う)。

フェーズ 1: 前書きの中立化

local 版の前書きには蒸留元の環境・件数・時期・分野が書かれている (例: 「このマシンで行った」「primary セッション N 本」「各項目の Evidence は…」「> 蒸留元の時期: …, <ドメイン>まわりの対話」)。これらを落とし、代わりに 2 層構成の相互補完を説明する中立な注記に差し替える。

• 冒頭の位置づけ一文 (「自分が実際に信じていることの、簡潔で生きた地図」等) は残してよい。

• 「Claude Code との対話ログから durable な信念だけを蒸留した」旨は残すが、マシン名・件数・分野の固有情報は消す。

• 引用注記を次のような中立版にする:

  このファイルは全マシン共通の要約版。個別の作業環境には、その環境での対話から蒸留した詳細版 (具体的な事例・出典への参照付き) が別に存在する。作業環境によっては、そちらの詳細版と補い合って読むことで、より解像度の高い像が得られる。

フェーズ 2: Evidence 行を全削除

local 版の各信念には - Evidence: 「本人発話の引用」(8 桁ハッシュ) 形式の行がぶら下がっている。これがドメイン固有の内容の主要な漏洩源なので 全行削除する。引用文にドメイン固有名詞が最も濃く残るため、1 行も残さない。

削除の取りこぼしがないか、後のフェーズ 5 の grep で担保する。

フェーズ 3: 見出し・本文から固有名詞を除去/一般化

見出しの信念文と本文 (補足段落) に残る固有名詞を、意味を保ったまま一般語に置換する。

• 一般化する例 (意味は保つ):
  • 見出し エラーは…扱う (errors-as-values, errore.org) → …(errors-as-values) (ドメイン URL を落とす)
  • 見出し 可読性のためにシェル/awk より Python を選ぶ → …ワンライナー職人芸より高級言語を選ぶ
  • 見出し インフラ知識は呼び出し側が抱え、バッチジョブは最小責務に留める → …末端は最小責務に留める
  • 本文の具体名 → 一般語: S3 バケット名→「置き場所」/ Airflow の DAG→「実行環境」/ BATCH_ID・RUN_DATE→「変数名」/ isDuplicate→「判定名」/ Great Expectations→「自動評価ツール」/ ETL バッチ変換→「ある変換処理」など。抽象的な言い換えで信念の骨格を保つ。
• 残してよい一般概念名 (ドメイン固有ではない技術用語):
  • errors-as-values / open/closed / YAGNI / single source of truth / fail-fast / instanceof / union / registry / trap / dry-run など。これらは普遍的な設計語彙なので消さない。
• 判断基準: 「その語を見て、特定のドメインでの作業だと推測できるか」。できるなら一般化、できない汎用語彙なら残す。

フェーズ 4: ドメイン固有章の解体と溶かし込み

local 版の末尾に「データ基盤/パイプライン (ドメイン固有)」のようなドメイン専用の h2 章がある場合、章ごと消してから、その中の普遍化できる信念だけ既存の汎用章へ溶かし込む。ドメイン章を丸ごと残すと分野が丸わかりになるため。

溶かし先の対応 (実績):

ドメイン章の信念	溶かし先の汎用章
設定値・デフォルトは明確な根拠を持つべき / 既存実装を権威扱いしない	設計と抽象化
移行ではサイレントな挙動変化を避け現行互換を優先	エラーと堅牢性
比較対象のベースラインは常に残す / 実運用上の影響と理論上の厳密さを切り分ける	検証と真因特定

• 溶かし込む際は、既に汎用章に近い信念があれば統合し、無ければ新しい h3 として一般語で立てる。
• 普遍化できない固有ルール (例: 特定ツールの特定パラメータの運用ルール) は普遍化せず破棄する。無理に残さない。

フェーズ 5: 検証

ドメイン固有語が 1 語も残っていないことを grep で確認する。パターンは入力の分野に合わせて自分で組み立てる。local 版で実際に使われている固有語 (プロジェクト名・ツール名・型名・環境変数名・ドメイン語) を、フェーズ 0 の通読で洗い出してからパターン化すること。

# <ここに local 版で見つけた固有語を | 区切りで並べる。例: プロジェクト名/ツール名/型名/環境変数名/ドメイン語>
grep -niE '<project-name>|<tool>|<type-name>|<env-var>|<domain-term>' "$OUT/OPINIONS.dotfiles.md"

• ヒットがゼロであることを確認する (errors-as-values のような一般概念名だけが残っている状態が正)。

• ヒットしたら該当箇所をフェーズ 3/4 に戻って一般化する。

• 加えて - Evidence: が 1 行も残っていないことも確認する:

  grep -nE '^\s*-\s*Evidence:' "$OUT/OPINIONS.dotfiles.md" && echo "残っている: フェーズ 2 に戻る" || echo "Evidence なし: OK"
  

フェーズ 6: 通読と配置

1. 生成物をもう一度頭から通読し、前書き→章→信念の流れがツギハギになっていないか、見出しの信念文が痩せすぎて意味を失っていないかを確認する。普遍化・一般化の結果として内容が痩せるのは許容だが、信念そのものが読み取れなくなってはいけない。
2. ユーザーに中身を確認してもらう。
3. OK なら $OUT/OPINIONS.dotfiles.md を出力先 (既定 ~/.claude/OPINIONS.md) へ配置する。既存ファイルがある場合は上書き前に必ず退避を確認する (不可逆)。

中間・最終成果物

• 入力: local 版 (<workspace>/.claude/OPINIONS.local.md、ドメイン固有の内容込み・Evidence 付き)。本スキルは入力を一切変更しない (温存する)。
• 中間: $OUT/OPINIONS.dotfiles.md (mktemp -d で作った一時ディレクトリ配下、配置前の作業ファイル)。
• 出力: ~/.claude/OPINIONS.md (配置後、全マシン共通)。