fable-config

Fable Config

明示的な優先順位、最小権限、シークレットを安全に扱う方法、検証済みのロールバック手順を用いて、ハーネス／設定の動作を変更します。

ミッション

設定は実行可能な動作です。構文的に正しい JSON／TOML／YAML ファイルでも、ガードを無効にしたり、権限を拡大したり、誤ったスコープに書き込んだり、別のソースの優先順位が高いために無視されたりすることがあります。

このスキルでは、設定の妥当性と実際の動作の両方を証明する必要があります。

有効化する場合

• ホスト／ハーネスの設定、権限、フック、キーバインド、モデル／ツール設定、環境変数の参照を変更する場合。
• ライフサイクルの強制処理を追加／削除する場合。
• 設定が反映されない理由を調査する場合。
• 安全なコマンド／ツールの許可リストを設定する場合。
• 設定形式／スコープを移行する場合。

有効化しない場合

• 認証情報／シークレットをそのまま保存する場合。
• 実際の変更対象がアプリケーションのビジネスロジックである場合。
• ホストの機能が不明で、まず調査／確認が必要な場合。
• エラーの内容を理解せずに回避するためだけに、安全上の境界を弱める変更が求められている場合。

設定の分類

変更	主なリスク
権限／許可リスト	過剰な権限／ワイルドカードによる広範なスコープ
フック登録	フックが存在しても呼び出されない／誤ったフェーズをブロックする
環境設定	優先順位、シークレットの漏えい、型／形式
ホスト設定	ユーザー／プロジェクトのスコープが誤っている、未対応のキー
モデル／ツール設定	動作／コスト／アクセスが予期せず変わる
キーバインド／UI	競合／上書き
生成された設定	手動編集した内容がジェネレーターによって上書きされる

手順

ステージ 1 — ソースと有効なスコープを特定する

以下を特定します。

• 対象のホスト／バージョン。
• プロジェクト単位か、ユーザー／グローバル単位か。
• すべての設定ソースと優先順位。
• 生成ファイルか、手動で管理されているファイルか。
• 保持すべき既存のユーザー設定。

有効な設定であると確認するまでは、名前が合っている最初のファイルを編集しないでください。

ステージ 2 — 望ましい動作と最小権限を定義する

どの機能を許可／ブロック／実行するのか、また何を変更せずに維持するのかを正確に記述します。

権限については、対象を絞ったコマンド／ツール／パスのパターンを優先します。ワイルドカードを使う場合は、明確な根拠と脅威への考慮が必要です。

ステージ 3 — シークレットを保護する

設定では環境変数名やセキュアストアを参照できますが、対象の安全な形式で保護された暗号化ストレージが明示的に必要とされていない限り、生のトークン／パスワード／秘密鍵を埋め込んではいけません。

既存のシークレットが平文で見つかった場合は、その内容を表示せず、適切な手順で漏えいへの対処を行います。

ステージ 4 — 最小限のマージを行う

不明な設定やユーザー定義の設定を保持します。スコープを絞ったキーをマージできる場合は、設定オブジェクト／ファイル全体の置き換えを避けます。

生成された設定の場合は、ソース／ジェネレーターを変更してから再生成します。

ステージ 5 — 構造とセマンティクスを検証する

利用可能なパーサー／スキーマ／ホストの診断機能を実行します。以下を確認します。

• 構文。
• キーの型／列挙値。
• 重複／競合するエントリー。
• 未対応／非推奨のキー。
• 権限パターンのスコープ。
• フックのコマンド／パスの存在。

ステージ 6 — 実際の動作を証明する

ファイルが有効であるだけでは不十分です。設定した動作を安全にテストします。

• 対象のコマンドは許可され、より広範なコマンドは引き続き拒否される。
• フックが意図したライフサイクル上の時点で実行される。
• プロジェクトのオーバーライドが期待どおりに優先される。
• 対象のホストから設定を確認できる。
• ロールバックによって以前の動作が復元される。

ステージ 7 — ロールバック手順を記録して引き継ぐ

変更したソース、有効なスコープ、検証結果、動作の証明、再起動／更新後にホストが機能しない場合の元に戻す方法を記録します。

判断ルール

• タスクの対象外である既存のユーザー設定は維持します。
• *、シェルのワイルドカード、ルート／グローバル権限よりも、厳密な許可リストを優先します。
• パーサーが受け入れてもホストが無視する設定キーは、変更が成功したことにはなりません。効果を検証してください。
• ホストの統合レベルはそれぞれ異なります。ホストが助言的なルールしかサポートしていない場合、フックや強制適用を主張しないでください。
• 環境変数名は保存してもかまいませんが、シークレット値は安全な環境または認証情報ストアに保管してください。
• 設定の優先順位が不明な場合は、さらにファイルを編集する前に調査してください。
• 安全でない操作を阻止されているという理由だけで、セキュリティ／承認チェックを無効にしないでください。
• 不適切な編集によってホストから締め出される可能性がある場合は、元に戻せるバックアップ／アトミックな書き込み戦略を用意してください。

不変条件

• 最小権限を維持するか、権限の拡大を明示して正当化します。
• 生のシークレットをリポジトリや設定ログに持ち込みません。
• 既存の無関係なユーザー設定を維持します。
• 編集したソースが実際に有効な信頼できる情報源です。
• 構文／スキーマと、実際のホストの動作の両方を検証します。
• 重要な変更をロールバックできる状態にします。

障害の分類

優先順位の不一致

編集したファイルが別のスコープ／ソースによって上書きされています。有効な設定を追跡してください。

スキーマ上は有効だが無視される

ホストはファイルを受け入れますが、そのキーをサポートしていないか使用していません。ホストのバージョン／機能を確認してください。

権限の過剰な付与

パターンによって、要求以上の操作が許可されています。範囲を絞り、否定ケースをテストしてください。

フックの登録ミス

スクリプトは存在しますが、ライフサイクルから呼び出されていません。登録先のパス／イベントと権限を検証してください。

シークレットの漏えい

認証情報が埋め込まれているか、ログに記録されています。安全に削除し、漏えいが発生した場合はローテーションしてください。

ユーザー設定の上書き

ファイル全体を書き換えたため、既存の設定が失われています。必要な箇所だけを復元／マージしてください。

生成物の差分

手動編集が上書きされます。生成元／ソースを変更してください。

アンチパターン

• 承認プロンプトを止めるために "allow": ["*"] を設定する；
• プロジェクトスコープで十分なのに、グローバル設定を編集する；
• API トークンを設定例にコピーする；
• JSON の構文を検証しただけで、フックの設定が完了したと判断する；
• 統合が助言のみのホストで、ライフサイクル全体への強制適用を主張する；
• 1 つのキーを変更するために設定ファイル全体をリセットする；
• コマンドを実行可能にするためにセキュリティ制御を無効にする；
• 生成された設定を手動で修正する。

設定パケット

Target host/version/scope:
Effective config sources + precedence:
Desired behavior:
Settings changed:
Permissions before/after:
Secret handling:
Syntax/schema validation:
Behavioral proof + negative case:
Preserved user settings:
Rollback:

完了条件

以下を満たしたとき、設定は完了です。

• 正しく有効なソース／スコープを最小限の変更で修正している；
• 設定が解析され、スキーマ／機能の制約を満たしている；
• 権限が最小権限のまま維持されている；
• シークレット／無関係な設定が安全に保たれている；
• 重要な否定ケースを含め、対象の動作を実際に確認している；
• ロールバック方法とホストの制限が明示されている。

段階的なリソース

• 詳細ガイド：references/config-precedence-permissions-and-hooks.md
• 既存のルール：references/harness-configuration-rules.md
• 例：examples/configure-allowlist.md