dry-ssot-text

DRY/SSOT Text Refactor

Overview

AI が生成した長文 (plan, design doc, RFC, PR description, README 等) は、しばしば同一概念を複数箇所で繰り返す。これは読み手の認知負荷を上げ、後の修正コストを高め (3 箇所更新するうち 1 箇所を忘れる)、トークン消費を増やす。

本 skill は冗長な説明を 1 箇所に集約 (Single Source of Truth) し、他箇所はクロスリファレンスに置換する。同時に「必要重複」(TOC, checklist, progress table 等の navigation aid) は残す。

核心原則: 「同じ事実を 2 度書かない」だが「ナビゲーション目的の重複は別物」。

When to Use

主条件 (どれかに該当):

• 同一概念の説明が 3+ 箇所 で発生している (文書サイズによらず)
• レビュアーから「冗長」「読みづらい」「重複多い」と指摘された

副条件 (上記に加えて以下のいずれかなら効果が高い):

• 文書が長文 (200 行+)、メンテナンスで「片方だけ更新した」状態が生じやすい
• 文書をプロジェクトのコンテキスト窓に何度もロードする (AI が後で参照する) ため、トークン効率を上げたい

When NOT to use:

• 重複が 2 箇所以下 (集約しても 1 箇所減るだけでメリット薄い)
• 文書が外向きの説明資料 (顧客向けドキュメント、ブログ記事) で、各セクションが自己完結すべき場合
• API リファレンスのような 網羅的列挙が目的 の文書

Core Pattern: 必要重複 vs 不要重複 の判定

すべての重複が悪ではない。以下の判定表に従う:

種類	例	DRY 化するか	理由
不要重複: 説明文	同じ設計判断を PR1/PR2/PR3 セクションで再記述	する	1 箇所更新で済むメリット > navigation コスト
不要重複: 表/コード	同じ table が 2 箇所、片方に「再掲」と書く	する	1 箇所更新で済む
不要重複: 引用文	公式ドキュメントの同一一節を 2 箇所引用	する	引用元 1 箇所に集約
必要重複: TOC / 進捗 table	章立て一覧、PR 進捗表 (タイトルと状態)	しない	俯瞰 navigation の機能
必要重複: checklist サマリ	AC リストの 1 行 + 詳細は §設計詳細で詳述	しない	確認用 checklist の機能
必要重複: header + body 同名	「§Provider 内吸収型」の見出しと本文冒頭	しない	見出しは index の機能

Workflow

1. 重複の特定 (Identify)

• 文書全文を Read
• 同一概念 (= 同じ事実、同じ table、同じコード片) が複数箇所で出現するパターンを列挙
• 各パターンを 上記判定表で「不要重複」「必要重複」に分類

2. Canonical location の決定 (Decide SSOT)

不要重複ごとに、唯一の真実源を 1 箇所に決める:

選定ルール:

• 文書末尾の §設計詳細 / §参照 に専用セクションを設けて集約 (推奨、文書全体を散歩しなくて済む)
• 例外: 概念が 文書冒頭の前提知識 に該当する場合は冒頭近くに配置 (例: 「ゴール」「アーキテクチャ」)

避けるべき配置:

• 最初に出現する PR/章のセクション内に置く → 後の章で「§PR1 を参照」と書かれ、PR1 が更新されたとき他章の意味が崩壊
• 文書の途中の任意箇所 → 読み手が forward/backward 両方ジャンプ必要

3. クロスリファレンス置換 (Replace with refs)

他箇所の説明文を markdown アンカーリンク で置換:

<!-- Before (各 PR セクションに同じ説明) -->
重要な設計判断: AuthGateway は単一の責務に閉じ込め、ユーザ管理や権限管理は別サービスに委譲する。

<!-- After (1 箇所に集約後の参照) -->
**設計判断**: §[重要な設計判断](#重要な設計判断) 参照

置換時の注意:

• セクション参照は必ず markdown アンカーリンク [表示文字列](#anchor) 形式
• 参照は その PR セクションの冒頭近く に置く (実装の前に設計を読ませる)
• 各 PR セクションは「スコープ 1 文 + 設計判断リンク + 実装ファイル table」の三段構造を維持し、スコープ説明まで削らない (過 DRY 防止)
• 関連が弱い PR の扱い: PR の内容が SSOT に直結しない場合 (例: 「機能 X 削除」PR と「機能 Y の設計判断」)、default は省略 (リンクを貼らない)。例外: 関連性が補完的に有用 (読み手の理解の助けになる) と判断した場合のみ、1 句で関連性を補足 (例: **設計判断**: §X 参照 (新経路への完全切替の前提))。迷ったら省略を選ぶ (過 DRY 防止より過リンク防止を優先)
• 既存表記スタイルの維持: 元文書の表記スタイル (散文 / list / table) は DRY/SSOT 化のスコープ外。「実装ファイル table」は skill 例示であって、元文書が散文ならそのまま散文で残す。表記スタイル変更は別 task として切り分ける
• AC / checklist 内のクロスリファレンス: 元文書が (<参照テキスト>参照) のような括弧書きで参照していた場合、括弧構造を保ちつつ中身をアンカーリンクに置換する (例: 元 (Token rotation の挙動表参照) → refactor 後 (§[Token rotation 挙動表](#token-rotation-挙動表) 参照))

4. Dry-run レポート (推奨)

大規模文書 (300 行+) または共有前文書では、いきなり書き換えず 提案レポート を先に作る:

## DRY 化提案レポート

### 不要重複 (集約候補)
1. **「AuthGateway 単一責務」** (3 箇所: L40, L75, L105) → §設計詳細 に集約
2. **Token rotation 表** (2 箇所: L120-128, L145-153) → §設計詳細 に集約

### 必要重複 (維持)
1. **PR 進捗 table** (L25-32) → index 機能、維持
2. **AC checklist** (L180-200) → 確認用、維持 (詳細は §設計詳細 参照リンク追加で代替)

### 想定される行数削減
元: 250 行 → 後: 約 180 行 (28% 削減)

### 確認ポイント
- canonical location を §設計詳細 (文書末尾) に置く案で問題ないか？
- 各 PR セクションのスコープ説明 (1 文) は維持するか？

承認をいただければ書き換えを実施します。

5. 実適用 (Apply)

承認後、Edit / Write で書き換え。書き換え後に:

• grep -c "<重複していた canonical フレーズ>" <file> で 1 件のみヒットすることを確認 (重複の集約検証)
• 文書を冒頭から線形に読み、参照リンクが機能しているか確認
• wc -l で行数を確認 (ただし行数は増減両方ありうる。canonical セクションと参照リンクの追加で小規模文書は微増しうる。重視するのは 同一情報の重複箇所数の減少、行数ではない)

Quick Reference

操作	コマンド / パターン
重複検出	grep -nE "<重複候補フレーズ>" <file> で出現箇所列挙
行数測定	wc -l <file>
アンカーリンク形式	[表示文字列](#anchor)。anchor は見出しを小文字 + スペースをハイフン化
dry-run トリガ	300 行+ または レビュー前 → dry-run レポート先行
SSOT 配置先	文書末尾の §設計詳細 / §参照 章 (推奨)

Common Mistakes

❌ 過 DRY: 各セクションがリンクだらけになり線形読みが破綻

症状: PR セクションを開いても「§X 参照 / §Y 参照」しか書かれていない。読み手が複数セクションをジャンプしないと意味が掴めない。

修正: 各セクションは 「スコープ 1 文 + 設計判断リンク + 実装ファイル table」 の三段構造を維持。スコープ説明まで削らない。

❌ TOC / index の削除

症状: 「PR 進捗 table の各行が PR セクション header と重複している」と判断して table を削除。

修正: TOC / 進捗 table / checklist は navigation 機能。文章の重複でなく構造の重複なので維持。判定表 §Core Pattern 参照。

❌ Canonical location を本文中の任意位置に置く

症状: 「§PR1 の説明文中に」設計判断を置いて、後で「§PR1 参照」と書く。PR1 が将来更新されたら他章の意味が崩壊。

修正: SSOT は 専用セクション (§設計詳細 / §参照 等) に切り出す。本文の説明文中に置かない。

❌ Dry-run なしで大規模文書を直接書き換え

症状: 300 行の plan を一気に書き換え、後で「この削除は意図と違う」とレビューで指摘される。

修正: 300 行+ の文書では必ず提案レポート先行。

❌ 必要重複と不要重複の判定漏れ

症状: 「AC リストの『§X 参照』は冗長」と判断して全削除。後で AC 確認時に毎回詳細セクションへジャンプが必要に。

修正: AC / checklist の 1 行サマリ + 詳細セクションリンクは 確認用 navigation aid として必要重複。判定表 §Core Pattern で確認。

Real-World Impact

実証例: 1074 行の plan.md を本 skill の手順で refactor → 328 行 (約 1/3 圧縮)。

• 設計判断の説明箇所: 3-5 箇所 → 1 箇所 (§設計詳細)
• Single Source of Truth セクション: 0 → 5 (4 層担保 / nil 戦略 / Single Switch / 4 象限 / rescue 拡張)
• AC リスト: 1 行 checklist + 詳細リンク table 形式に再構成
• 行数削減で約 60% のトークン節約を達成 (AI が文書を後で参照する際の累積効果)