---
title: CLI Scope Definition and Explicit Storage Linkage
status: Accepted
date: 2026-02-17
context: Ensuring Data Safety in Maintenance Operations
---

# CLI Scope Definition and Explicit Storage Linkage

## Context and Problem Statement / コンテキスト

`beautyspot` の `clean` コマンドやガベージコレクション機能は、DBファイルとBlobストレージディレクトリの対応関係が「自明」であることを前提としています。標準構成（`.beautyspot/` 配下）ではこの前提は成立しますが、ユーザーがカスタムパスを設定したり、外部バックエンド（S3等）を使用した場合、CLIツールは安全に依存関係を特定できません。この状態で推測に基づく削除を行うと、誤って無関係なデータを削除するリスクがあります。

## Decision Drivers / 要求

* **Data Safety**: 管理対象外のデータや、他のプロジェクトが使用しているデータを誤って削除しないこと。
* **Predictability**: CLI ツールがどの範囲までを安全に管理できるかを明確に定義すること。
* **Extensibility**: 将来的にカスタム構成であっても安全にメンテナンスが行えるような道筋を立てること。

## Considered Options / 検討

* **Option 1**: パス構造や設定から対応関係を推測し、ベストエフォートでクリーンアップを試みる。
* **Option 2**: CLI の自動クリーンアップ機能を標準構成に限定し、カスタム構成についてはユーザー管理とする。あわせてメタデータによるリンクを将来的に導入する。

## Decision Outcome / 決定

Chosen option: **Option 2**.

### 1. CLI Scope Limitation (Policy)
CLIが提供する「ストレージの自動クリーニング・削除機能」のサポート範囲を、**標準ディレクトリ構成（`.beautyspot/` 配下）を使用しているプロジェクト** に限定します。カスタム構成を利用している場合は、CLI による自動削除は保証されず、ユーザー自身の責任で管理を行う必要がある旨を明記します。

### 2. Explicit Storage Linkage (Roadmap)
「対応関係が自明でない」問題を根本解決するため、将来のバージョンで **TaskDB内に使用しているStorageの情報をメタデータとして記録する** 仕組みを導入します。DB初期化時に `storage_uri` を保存し、メンテナンス時に「操作対象のDBが参照しているストレージと、今操作しようとしている実体が一致するか」を検証可能にします。

## Consequences / 決定

* **Positive**:
    * **安全性:** 推測による誤削除を確実に防ぐことができる。
    * **明確な責任分界点:** ツールが面倒を見る範囲と、ユーザーが管理すべき範囲が明確になる。
    * **将来の拡張性:** メタデータ記録が実装されれば、カスタム構成でも安全なGCが可能になる。
* **Negative**:
    * **ユーザーの負担:** カスタム構成を利用する上級ユーザーは、`beautyspot clean` などの恩恵をフルには受けられない場合がある。
