detool

作成元のスタックを超えて使われることを想定した成果物から、偶発的なツール依存を取り除きます。

目標

エージェント、ハーネス、オペレーティングシステム、ベンダー、モデル、ツールチェーンが変わっても、長く使える成果物の正確さと実用性が保たれるようにします。detool は、持ち運び可能なコンテンツに含まれるスタック固有の名詞を見つけ、そこで実現されていた操作を維持したまま、その背後にある仕組みを表す表現に書き換えます。

目的は汎用的にすることであり、曖昧にすることではありません。書き換え後も、何を調べ、実行し、測定し、比較し、検証すべきかが読み手に伝わる必要があります。

ワークフロー

1. 対象の成果物を最初から最後まで読みます。
2. 編集前に役割を判定します。成果物全体を、または内容が混在する場合は各セクションを、長く使える／持ち運び可能なコンテンツ、出所情報／運用記録、または名称のあるツールに関する主張に分類します。
3. 長く使えるコンテンツを確認し、偶発的な依存を探します。対象には、ハーネスのパス、ベンダーの CLI とフラグ、仕組みとして使われているモデル名や製品名、ツール固有の環境変数、クォータ、UI の手順、キャッシュの保存先、セッションファイル、そしてバージョンに依存する挙動を普遍的な事実として記したものが含まれます。
4. 婉曲表現ではなく仕組みを示すようにします。長く使えるコンテンツで見つかった依存箇所は、操作性を損なわない中立的な仕組みの表現に置き換えます。中立的な表現では操作性が失われる場合は、一般化できるふりをせず、その具体的な詳細を仕組みの一例として残します。
5. 出所情報や運用情報は具体的なままにします。ビルド記録、カプセル、ベンチマークログ、インストールガイド、ランブック、特定のツールを対象としたハウツー、コマンドの実行記録、厳密な再現手順では、成果物を作成したスタックを明記する必要があります。
6. 比較に関する主張や、特定のツールを主題とする主張は具体的なままにします。文の主題が名称のあるツール、ベンダー、モデル、バグ、先行研究の出典、測定された制限である場合、その名称は偶発的な依存ではなく、主題そのものです。
7. 異なるスタックを使う読み手の視点で読み直します。成果物は引き続き正確で、持ち運び可能であり、操作を約束している箇所では実行可能である必要があります。
8. 中立化した内容、意図的に残した内容、それぞれを残す判断の根拠を報告します。

ルール

• 編集前に役割を判定します。 テキストが持ち運び可能なコンテンツ、出所情報、運用手順、または特定のツールを主題とする主張のいずれかを判断する前に、依存を取り除いてはいけません。
• 婉曲表現ではなく仕組みを示します。 「セッションの実行ログを使い、使用量の記録を合計する」は仕組みを示しています。「ログを確認する」は、必要な作業を失わせる婉曲表現です。
• 実行可能な詳細を保持します。抽象化するのは依存の部分だけとし、手順、証拠、比較、制約は抽象化しないでください。
• 出所情報や運用記録は正確なままにします。何が起きたかを記録する場合や、特定のツールの操作方法を説明する場合は、具体的なパス、コマンド、フラグ、バージョン、製品、UI の手順を残します。
• 比較や特定のツールを主題とする場合は、名称を残します。CLI に関するバグ報告、モデルとのベンチマーク比較、先行研究の引用、ベンダー固有の制限では、対象の名称を残します。
• 確認の結果、偶発的な依存が見つからない場合は、何も変更しません。
• 編集時は安全性を確保します。各対象箇所の存在を確認し、対象がなければ何もせずに済ませるのではなく MISS を報告します。Unicode に対応した方法で編集し、全体に一括置換を適用せず、箇所ごとに置き換えます。大規模な構造変更にはスクリプトを使います。

検証

完了する前に、次の点を確認します。

1. 変更した箇所がすべて、長く使えるコンテンツまたは持ち運び可能なコンテンツに含まれていたこと。
2. すべての書き換えで、実行可能な仕組みが維持されていること。
3. 残したツール名がすべて、出所情報、運用手順、または主張の対象であること。
4. 報告に、中立化した依存、意図的に残した内容、判断が必要だった箇所が記載されていること。