| 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: 入力の確認と通読
- 入力となる local 版のパスと、出力先をユーザーに確認する (前提の既定値を提示して差分だけ詰める)。
- local 版を 頭から最後まで通読し、章立て (h2 セクションと各 h3 信念、前書き、末尾のドメイン固有章の有無) を把握する。複数箇所を編集するので、着手前に全体像を持つ (
markdown-editing ルールに従う)。
フェーズ 1: 前書きの中立化
local 版の前書きには蒸留元の環境・件数・時期・分野が書かれている (例: 「このマシンで行った」「primary セッション N 本」「各項目の Evidence は…」「> 蒸留元の時期: …, <ドメイン>まわりの対話」)。これらを落とし、代わりに 2 層構成の相互補完を説明する中立な注記に差し替える。
フェーズ 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 の通読で洗い出してからパターン化すること。
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: 通読と配置
- 生成物をもう一度頭から通読し、前書き→章→信念の流れがツギハギになっていないか、見出しの信念文が痩せすぎて意味を失っていないかを確認する。普遍化・一般化の結果として内容が痩せるのは許容だが、信念そのものが読み取れなくなってはいけない。
- ユーザーに中身を確認してもらう。
- OK なら
$OUT/OPINIONS.dotfiles.md を出力先 (既定 ~/.claude/OPINIONS.md) へ配置する。既存ファイルがある場合は上書き前に必ず退避を確認する (不可逆)。
中間・最終成果物
- 入力: local 版 (
<workspace>/.claude/OPINIONS.local.md、ドメイン固有の内容込み・Evidence 付き)。本スキルは入力を一切変更しない (温存する)。
- 中間:
$OUT/OPINIONS.dotfiles.md (mktemp -d で作った一時ディレクトリ配下、配置前の作業ファイル)。
- 出力:
~/.claude/OPINIONS.md (配置後、全マシン共通)。