外部ツールは機構でなく規律を移植する
良い外部ツール/スキルを自環境に入れたいとき、丸ごと install するとその道具が ハードコードした副作用(どこへ・いつ書くか)まで一緒に入ってくる。副作用が自環境の 不変条件と衝突すると、install した瞬間に「使えるが使えない」状態になる。
分解すると、外部ツールの価値はふつう2層に割れる:
- 規律(何を捕まえるか) … 例:設計中に用語集を鋭らせる・不可逆決定を ADR に残す。 これが本当に欲しいもの。
- 機構(どこへ・いつ書くか) … 例:repo ルートの
CONTEXT.mdにセッション中インライン書き込み。 ツール作者の環境に最適化された実装詳細で、移植しなくていい。
→ 規律だけを fork し、書き込み先を自環境の既存スコープへ向け直す。機構は模写しない。 これで不変条件を1つも壊さずに利得だけ取れる。判断材料:
- 上流鮮度が0なら追従の価値はない → vendored(
npx等で更新経路維持)でなく fork(模写)で十分。 エンジンが自前の既存手法と同等なら、なおさら追う理由がない。 - 衝突の正体はたいてい1点 … 対照表を作ると「同等 / 自環境のみ / 上流のみ / 衝突」に割れて、 本質的な差分(=衝突行)が1〜数行に絞れる。そこだけが設計判断で、残りは薄いラッパー移植。
- 向け直し先は「既に承認済みの draft スコープ」を使う … 新しい canon スコープを新設すると
不変条件(例:canon は1箇所)を崩す。既存の
canon:falseステージングへ流し、正典化は ライフサイクルの確定点(serve 等)で一度だけ行う。
実例:GrillWithDocs(上流 grill-with-docs)の導入。尋問エンジンは既存 GrillMe と同等で、
衝突は「inline で repo ルートへ書く」1点のみ。機構は捨て、用語集/ADR を
CurePit/reports/<stub>.CONTEXT.md(既存の承認済み draft)へ向け直して即実働化した。
→ sandbox/手法/grill-meで設計を詰める.md §with-docs モード、CurePit/DESIGN.md §5。