> ## Documentation Index
> Fetch the complete documentation index at: https://ccsafetynet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# カスタムルール：追加のコマンド引数パターン
> JSON 設定ファイルを使い、CC Safety Net で project scope と user scope のカスタムブロックルールを定義します。command、subcommand、literal argument pattern を照合し、独自の理由を示してコマンドをブロックします。
カスタムブロックルールを使い、チーム規約やプロジェクト固有の安全ポリシーを強制します。ルールは **rulebook ベースの layout** を使い、user scope と project scope から merge します。これにより、個人の既定値を維持しながら project override を適用できます。
**破壊的変更** — legacy inline config file（`.safety-net.json` と `~/.cc-safety-net/config.json`）は runtime で読み込まれなくなりました。ルールが含まれる場合、**移行するまでそのルールは無効です**。runtime は legacy file を暗黙に無視します。`rule verify` は warning を表示します。通常のコマンドは引き続き動作します。`npx -y cc-safety-net rule migrate` を実行して、legacy rule を rulebook layout に変換してください。[Legacy 設定を移行する](#migrate-legacy-configuration)を参照してください。
カスタム ルールを作成する最も速い方法は、エージェント内で\*\*`/cc-safety-net` スキル\*\*を使用して、自然言語を使用して対話的にルールを作成することです。例:
```text theme={"dark"}
/cc-safety-net read my package.json and suggest blocking rules
/cc-safety-net set up rules to block all terraform destroy commands
/cc-safety-net verify my rules and fix any errors
```
エージェントがスキルをサポートしていない場合は、次のプロンプトを表示します。
```text theme={"dark"}
run npx -y cc-safety-net rule doc and help me set up custom rules
```
## ルール設定ファイルの場所
CC Safety Net は 2 つのスコープからルールブックをロードし、それらをマージします。
1. **ユーザー スコープ**— `~/.cc-safety-net/rules/rule.json` (`rule init --global`) で作成されました。これは、すべてのプロジェクトに適用される個人的なデフォルトとして使用します。
2. **プロジェクト スコープ**— プロジェクト ルートの `.cc-safety-net/rules/rule.json`。これを、ソース管理にコミットできるチームまたはプロジェクト固有のルールに使用します。
ローカル ルールブック ソースは、`project-rules` のような裸の名前で参照されます。 GitHub ルールブック ソースは `owner/repo#ref/` を使用し、そのリポジトリ内の `.cc-safety-net/rules//rulebook.json` を指します。
### スコープのマージ動作
* 両方のスコープのルールブックが、最初にユーザー スコープで結合されます。
* \*\*重複したアクティブなルールブック名は最初の要求によって解決されます。\*\*ユーザー スコープが最初にロードされるため、要求される名前は同じ名前のプロジェクト ルールブックをシャドウします。後のルールブックは最初のルールを部分的に影付けするのではなく、まったくルールを提供しません。衝突は警告として報告され、ランタイムが `degraded` 状態になります。いずれかの名前を変更して `rule sync` を実行します。衝突は致命的ではなく解決されたため、一方のスコープの `rule sync` は、もう一方のスコープがすでに使用している名前でも引き続き成功します。
* \*\*各スコープの `overrides` は、そのスコープ独自のルールに適用されます。\*\*ユーザー スコープのルールを指定するプロジェクト オーバーライドは警告とともに無視され、ルールはユーザー構成の状態を維持します。プロジェクト構成はユーザー ルールを無効にしたり書き換えたりすることはできません。
* 既知のルールに一致しないオーバーライド キーは無視され、警告が表示されます。他のオーバーライドとルールは、構成された状態を維持します。
* 両方のスコープの `transparent_wrappers` が結合されます。
どちらの場所にも構成が見つからない場合は、組み込みルールのみが適用されます。
## ルールブックソースの管理
ルールブックのソースは、`rule.json` の `rules` 配列内のエントリによって参照されます。次の 2 種類があります。
* **ローカル ソース**— `project-rules` のような裸の名前。ルールブックは `.cc-safety-net/rules/project-rules/rulebook.json` (project) または `~/.cc-safety-net/rules/project-rules/rulebook.json` (user) にあります。ローカル ソースは、config ディレクトリ内に存在する必要があります。
* **GitHub source**— `owner/repo#ref/`、そのリポジトリと ref 内の `.cc-safety-net/rules//rulebook.json` を指します。
`rule.json` とロックファイルを手動で編集するのではなく、`rule` コマンドを使用してソースを追加、更新、削除します。
```bash theme={"dark"}
# Add a local rulebook source and sync
npx -y cc-safety-net rule add project-rules
# Add a GitHub rulebook source (creates a lock entry pinned by SHA-256 digest)
npx -y cc-safety-net rule add kenryu42/cc-safety-net#main/example-rules
# Refresh the lock and cache after editing sources
npx -y cc-safety-net rule sync
# Update a single source, or all sources when no source is given
npx -y cc-safety-net rule update example-rules
# List active rulebooks and their resolved sources
npx -y cc-safety-net rule list
# Remove a source (--delete-source also deletes a local source directory)
npx -y cc-safety-net rule remove example-rules --delete-source
```
`--global` (`-g`) を追加して、プロジェクト スコープではなくユーザー スコープで動作します。すべての `rule` サブコマンド、そのオプション、およびその終了動作については、[CLI コマンド](/docs/ja/reference/cli-commands) を参照してください。
### リソース制限
`rules` 配列は、スコープごとに最大**64**ソースを保持します。より多くのエントリを持つ `rule.json` は、単一エラー `Rule config exceeds CC Safety Net's safe source limit.` で検証に失敗します。サイズ超過の配列はエントリごとに項目化されず、他の無効な `rule.json` と同様に scope 全体の設定が active runtime snapshot から drop されます。
`rule sync` は固定バジェットの下で実行されます。最大で**4**ソースを同時に処理し、1 回の実行で最大**131**GitHub リクエストを作成し、すべてのソースにわたって最大**64 MiB**の応答バイトを読み取ります。予算を超過すると、`Rule synchronization exceeds CC Safety Net's safe resource limits.` で実行が停止されます。
### ロックとキャッシュ
構成されたすべてのソースは、SHA-256 ダイジェストによって `rule.lock` ファイルに固定され、そのルールブックは `.cc-safety-net/cache/rulebooks/` の下にキャッシュされます。実行時に、CC Safety Net はキャッシュされたルールブックをダイジェストと照合して検証しますが、検証中は何も書き込んだり、取得したり、キャッシュしたりすることはありません。
検証が失敗したときに何が起こるかは、どちらの側が壊れているかによって異なります。
* **ロックファイルの欠落、ロックエントリの欠落、キャッシュエントリの欠落、ダイジェストの不一致、または解析不可能なキャッシュされたルールブック**がある場合、その source を active runtime snapshot から drop します。`rule sync` を実行するまで、ルールは提供されません。他のすべての検証済み source とすべての組み込み保護は適用され続け、通常のコマンドは実行され続けます。drop された source は、作業をブロックするのではなく、runtime を `degraded` にします。
* ピン留めされたダイジェスト**からドリフトする**local ソース (ディスク上で欠落しているもの、解析できないもの、またはスキーマが無効なものを含む) は、障害状態ではありません。ランタイムはダイジェスト検証された**cached**ルールブックのみを読み取り、ローカル コピーを再読み取りすることはありません。保留中のローカル編集は、`rule sync` を実行するまでアクティブになりません。完全な `rule sync` および `rule verify` は、無効なローカル ソースまたはシンボリックリンクされたローカル ソースを拒否します。
完全な state model、正確な diagnostic string、repair sequence については、[設定の復旧](/docs/ja/configuration/recovery)を参照してください。
## Transparent wrapper
チームが `rtk` などのラッパーを介してコマンドを実行する場合、分析では、その下のコマンドではなく、デフォルトでラッパーが参照されます。 `transparent_wrappers` にラッパーをリストすると、CC Safety Net はそれを参照して、表示されている保護された子コマンドを参照できるようになります。そのため、組み込みの分析とカスタム ルールの両方が、裸のコマンドとまったく同じように `rtk git reset --hard` と `rtk docker system prune` に適用されます。
`rule.json` を手動で編集するのではなく、`rule wrapper` サブコマンドを使用してラッパーを構成します。
```bash theme={"dark"}
# List configured wrappers for the project scope
npx -y cc-safety-net rule wrapper list
# Trust a wrapper, or stop trusting it
npx -y cc-safety-net rule wrapper add rtk
npx -y cc-safety-net rule wrapper remove rtk
# Operate on the user scope instead
npx -y cc-safety-net rule wrapper add rtk --global
```
フィールドのルール:
* \*\*組み込みのデフォルトはありません。\*\*意図的に信頼するラッパーのみを構成します。
* ラッパー名は `^[a-zA-Z][a-zA-Z0-9_-]*$` と一致し、ファイル内で一意である必要があります。
* **予約されたコマンドをラッパーにすることはできません**: `git`、`busybox`、分析された組み込みコマンド `rm`、`find`、`xargs`、および `parallel`、すべてのシェル ラッパー、すべてのインタープリター、および awk インタープリター。
* unwrap は、wrapper flag と `VAR=value` assignment の後にある最初の *protectable* child command、または明示的な `--` の直後にある token を見つけます。child 自体が protectable でない場合は unwrap しません。
* ここに記載されて**いない** wrapper、または表示される child を exec せず、child command を書き換えるか隠す wrapper は unwrap しません。このようなコマンドを検出できる可能性があるのは、top-level の dangerous-text fallback scan だけです。
`transparent_wrappers` は、lock や digest を持たない `rule.json` 内にあります。scope の `rule.json` が読み取り不能になると、その scope の wrapper は適用されなくなります。これは、設定が active runtime snapshot から drop されると組み込み coverage が減る唯一の場所です。**rulebook** が drop されても（cache entry の欠落、lock entry の欠落、digest mismatch）、`rule.json` は読み取り可能なため wrapper は維持されます。
## 最初のカスタム ルールを作成する
スターター プロジェクト ルール構成を作成します。
```bash theme={"dark"}
npx -y cc-safety-net rule init
```
これにより、**inert**`.cc-safety-net/rules/rule.json` が作成されます — ルールブック ソースはまだ構成されていません。
```json theme={"dark"}
{
"version": 1,
"rules": [],
"overrides": {},
"transparent_wrappers": []
}
```
`--example` を追加して、非アクティブなサンプル ルールブックも `.cc-safety-net/rules/example-rules/rulebook.json` に記述します。これは、そのファイルがまだ存在しておらず、`rule init` がそのファイルを参照していない場合にのみ書き込まれるため、アクティブにするためにソースとして追加する必要があります。
```bash theme={"dark"}
npx -y cc-safety-net rule init --example
npx -y cc-safety-net rule add example-rules
```
独自のルールブックを作成するには、`.cc-safety-net/rules/project-rules/rulebook.json` を作成し、`npx -y cc-safety-net rule add project-rules` に登録します。これにより、`rule.json` は次のようになります。
```json theme={"dark"}
{
"version": 1,
"rules": ["project-rules"],
"overrides": {},
"transparent_wrappers": []
}
```
ルール定義はそのルールブック ファイル内に存在します。
```json theme={"dark"}
{
"rulebook_version": 1,
"name": "project-rules",
"version": "1.0.0",
"description": "Project-specific CC Safety Net rules.",
"author": "project",
"allowed_commands": ["git"],
"rules": [
{
"name": "block-git-add-all",
"command": "git",
"subcommand": "add",
"block_args": ["-A", "--all", "."],
"reason": "Use 'git add ' instead of blanket add."
}
],
"tests": [
{
"command": "git add -A",
"expect": "blocked",
"rule": "block-git-add-all"
},
{
"command": "git add README.md",
"expect": "allowed"
}
]
}
```
ルールブックを編集した後、次を実行します。
```bash theme={"dark"}
npx -y cc-safety-net rule sync
npx -y cc-safety-net rule verify
```
`rule sync` は編集されたルールブックをアクティブにします。次に、`rule verify` はアクティブな構成をチェックします。
これで、`git add -A`、`git add --all`、および `git add .` がカスタム メッセージでブロックされます。
## `rule.json` スキーマ
最上位の `rule.json` は、アクティブなルールブックを選択し、オーバーライドを適用し、透明なラッパーを宣言します。これは、安全レベル、組み込みの保護、パスの許可と拒否、監査保持を構成する `policy.json` とは別のものです。このファイルについては、[Policy](/docs/ja/configuration/policy) を参照してください。
スキーマのバージョン。 `1` である必要があります。
rulebook source string の一覧です。既定値は空の配列です。source name はファイル内で一意である必要があり、最大 64 個の source を指定できます。[リソース制限](#resource-limits)を参照してください。
`/` をキーとするルールの上書き。値は、ルールを無効にする `"off"`、またはルールのブロック メッセージを置き換えるオブジェクトのいずれかです。オブジェクト フォームには `reason` が必要で、オプションの `intent` を受け入れます。 `intent` を省略すると、ルール自体の意図は変更されません。
表示される protected child command を透過的に実行する command name です。analysis はこれらを通して child を確認します。既定値は空の配列です。項目は一意で、reserved command ではない必要があります。[Transparent wrapper](#transparent-wrappers)を参照してください。
メッセージとエージェント側のインテントの両方を変更するオーバーライドは次のようになります。
```json theme={"dark"}
{
"version": 1,
"rules": ["project-rules", "owner/repo#main/team-rules"],
"overrides": {
"project-rules/block-docker-system-prune": {
"reason": "Use targeted Docker cleanup commands.",
"intent": "use_alternative"
},
"team-rules/block-npm-global": "off"
},
"transparent_wrappers": ["rtk"]
}
```
### `rule.json` エディタのサポート
CC Safety Net は、ランタイムが検証するのと同じスキーマから生成された、`rule.json` の JSON スキーマを公開します。完成と検証のためにエディターにそれを指示します。
```json theme={"dark"}
{
"$schema": "https://raw.githubusercontent.com/kenryu42/cc-safety-net/main/assets/cc-safety-net.schema.json",
"version": 1,
"rules": [],
"overrides": {},
"transparent_wrappers": []
}
```
上記の `rule.json` フィールド (`version`、`rules`、`overrides`、および `transparent_wrappers`) を正確にカバーしています。 `rule verify` を実行すると、この `$schema` 参照が不足している有効なルール構成に追加されます。 `policy.json` の公開されたスキーマはありません。
## ルールブックのスキーマ
各ルールブックは独自の `rulebook.json` ファイル内に存在します。
ルールブックのスキーマのバージョン。 `1` である必要があります。
ルールブック名。ローカル ディレクトリ名または GitHub ソース名と一致する必要があります。
ルールブックのバージョン文字列。
人間が読めるルールブックの説明。
ルールブックの著者。
このルールブックでルールを定義できるコマンド。
カスタムブロックルールです。[ルール schema](#rule-schema)を参照してください。
任意の rulebook fixture です。[Fixture schema](#fixture-schema)を参照してください。fixture は意図する動作を文書化します。CC Safety Net は形式を検証しますが、実行しません。
## ルールスキーマ
ルールブック内でユニーク。文字で始まり、その後に文字、数字、ハイフン、またはアンダースコアが続く必要があります。最大64文字。
一致する基本コマンド。 `allowed_commands` にリストされている必要があります。
照合するサブコマンド (例: `add` または `install`)。省略した場合は、任意のサブコマンドと一致します。
ブロックをトリガーする引数です。1 つ以上必要です。
ブロックされたときに表示されるメッセージ。最大 256 文字。
ブロック メッセージ フッターに追加されるエージェントの動作の意図。 `hard_stop`、`use_alternative`、`scope_down`、`manual_only`、または `stop_and_explain` のいずれか。デフォルトは `manual_only` です。
## フィクスチャスキーマ
フィクスチャは、意図された動作のオプションのドキュメントです。形状検証のみが行われます。 CC Safety Net はそれらを実行しません。
シェルコマンドフィクスチャ。
`blocked` または `allowed` のいずれか。
ルールはコマンドをブロックすることが予期されています。ブロックされたフィクスチャに必要です。
## マッチング動作
CC Safety Net は次の一致ルールを使用します。
* **コマンドの正規化**: コマンドは照合する前にベース名に変換されます。 `/usr/local/bin/npm` は、ルールが `"command": "npm"` と一致します。
* **サブコマンド検出**: サブコマンドは、コマンドに続く最初の非オプション引数です。 `git --no-pager add -A` のサブコマンドは `add` です。
* **引数の一致**: `block_args` の引数は文字通り一致します。正規表現やグロブはサポートされていません。
* **Short option の展開**：`-Ap` のようにまとめられた short flag は、照合前に分割されます。`-Ap` は `-A` と `-p` として扱われます。
* **Long option の照合**：long option は exact string match を使います。`--all-files` は `--all` に一致**しません**。
* **任意の引数一致**: `block_args` に単一の引数が存在する場合、コマンドはブロックされます。
* **追加のみ**: カスタム ルールは新しい制限を追加することしかできません。組み込みの保護機能をバイパスすることはできません。
**既知の制限事項**: `-Cfoo` は、`-C foo` ではなく、`-C -f -o -o` として扱われます。 `-f` をブロックすると、添付されたオプション値で誤検知が発生する可能性があります。
## 例
エージェントがパッケージをグローバルにインストールできないようにします。
```json theme={"dark"}
{
"rulebook_version": 1,
"name": "project-rules",
"version": "1.0.0",
"allowed_commands": ["npm"],
"rules": [
{
"name": "block-npm-global",
"command": "npm",
"subcommand": "install",
"block_args": ["-g", "--global"],
"reason": "Global npm installs can cause version conflicts. Use npx or local install."
}
],
"tests": [
{
"command": "npm install -g typescript",
"expect": "blocked",
"rule": "block-npm-global"
},
{
"command": "npm install typescript",
"expect": "allowed"
}
]
}
```
ブロック `docker system prune`:
```json theme={"dark"}
{
"rulebook_version": 1,
"name": "project-rules",
"version": "1.0.0",
"allowed_commands": ["docker"],
"rules": [
{
"name": "block-docker-system-prune",
"command": "docker",
"subcommand": "system",
"block_args": ["prune"],
"reason": "docker system prune removes all unused data. Use targeted cleanup instead."
}
],
"tests": [
{
"command": "docker system prune",
"expect": "blocked",
"rule": "block-docker-system-prune"
},
{
"command": "docker ps",
"expect": "allowed"
}
]
}
```
```json theme={"dark"}
{
"rulebook_version": 1,
"name": "project-rules",
"version": "1.0.0",
"allowed_commands": ["git", "npm"],
"rules": [
{
"name": "block-git-add-all",
"command": "git",
"subcommand": "add",
"block_args": ["-A", "--all", ".", "-u", "--update"],
"reason": "Use 'git add ' instead of blanket add."
},
{
"name": "block-npm-global",
"command": "npm",
"subcommand": "install",
"block_args": ["-g", "--global"],
"reason": "Use npx or local install instead of global."
}
],
"tests": [
{
"command": "git add -A",
"expect": "blocked",
"rule": "block-git-add-all"
},
{
"command": "npm install -g typescript",
"expect": "blocked",
"rule": "block-npm-global"
}
]
}
```
## ブロックメッセージの形式
[ブロック結果の形式](/docs/ja/guides/how-it-works#ブロック結果の形式)では、block message の完全な layout を説明します。custom rule は rulebook name と rule name を含む prefix を追加するため、どの rulebook が block を生成したかを確認できます。
```text theme={"dark"}
BLOCKED by CC Safety Net
Reason: [project-rules/block-git-add-all] Use 'git add ' instead of blanket add.
Command: git add -A
```
プレフィックスは `/` です。これは、ルール (`"off"`) を無効にするか、その理由を置き換えるために `rule.json` `overrides` で使用するキーでもあります。
## ルールブックを検証する
ルールブックを作成または編集した後、次の方法でルールブックを検証します。
```bash theme={"dark"}
npx -y cc-safety-net rule sync
npx -y cc-safety-net rule verify
```
* `rule sync` は、設定されたルールブック ソースのロックとキャッシュを再構築します。
* `rule verify` は、構成、ロックとキャッシュの状態、ローカル ルールブック、および共有可能な GitHub ソース ルールブック ディレクトリをチェックします。リモートコンテンツは取得しません。
## レガシー構成を移行する
従来のインライン構成ファイル (`.safety-net.json` および `~/.cc-safety-net/config.json`) は**実行時にロードされなくなりました**。
| 従来のファイル状態 | 新しい動作 |
| --------------- | ------------------------------------------------------------- |
| 空のレガシー ファイル | 黙って無視 — 組み込みルールのみ |
| ルールのあるレガシー ファイル | `rule migrate` で移行されるまで、そのルールは**inert**です。ランタイムはファイルを黙って無視します |
| 無効なレガシー ファイル | 同じ - 修正され、移行されるか、削除されるまで不活性 |
従来のルールは古い場所から強制されることはなく、作業をブロックすることもありません。ランタイムはレガシー ファイルをまったく検査しないため、ガードタイムには何も表示されません。`npx -y cc-safety-net rule verify` は、残っているレガシー ファイルについて警告します。アップグレード後に実行してください。
```bash theme={"dark"}
# Convert legacy inline rules into the rulebook layout
npx -y cc-safety-net rule migrate
# Optionally delete verified legacy files after migration
npx -y cc-safety-net rule migrate --cleanup
# Validate the migrated rules
npx -y cc-safety-net rule verify
```
**Before**— ルールが埋め込まれた単一のインライン設定:
```text theme={"dark"}
.safety-net.json # project rules (inline)
~/.cc-safety-net/config.json # user rules (inline)
```
**After**— `rule migrate` はルールブックベースのレイアウトを自動的に作成します。
```text theme={"dark"}
.cc-safety-net/rules/rule.json # project rulebook sources + overrides
.cc-safety-net/rules/project-rules/rulebook.json # migrated project rules
~/.cc-safety-net/rules/rule.json # user rulebook sources + overrides
~/.cc-safety-net/rules/user-rules/rulebook.json # migrated user rules
```
## 無効なカスタムルール構成
検証できない custom rule 設定は active runtime snapshot から **drop され、適用されず、それ自体が拒否に変換されることもありません**。通常のコマンドは実行を続け、他のすべての検証済み source は強制を続け、すべての組み込み保護も引き続き適用されます。runtime は `degraded` を報告するため、状況を確認できます。
drop された source は拒否を追加せず、以前に提供していた拒否が active runtime snapshot から**外れる**ため、この種類の failure 自体が friction を発生させることはありません。`npx cc-safety-net status` は負荷が低い日常的な check です。完全な failure-to-fallback matrix、diagnostic string、reporting surface、repair sequence については、[設定の復旧](/docs/ja/configuration/recovery)を参照してください。
カスタムルール設定は**耐タンパー性を備えていません**。`rule.json`、rulebook、lockfile、cache は best-effort です。正式な user `policy.json` だけが protected path です。カスタムルールを手動で追加または変更する場合は、必ず `npx -y cc-safety-net rule verify` で検証してください。