本記事に登場する HUMAN_INPUT マーカーとは、AI 執筆 skill が記事本文に残す「ここは人間が後で確定値を埋めるべき」を示すプレースホルダー（形式例: <!-- HUMAN_INPUT: 数値を記入 -->）。

permission の事前整備が前提 — skill が他 repo にアクセスするための allow-list 設計

→ AI エージェントを使った業務設計の全体像 でこのトピックの背景を確認する

skill が他リポジトリの git log にアクセスする設計を組んだとき、実行すると途中で止まった。Claude Code が permission ダイアログを表示して、その Bash コマンドを許可するか確認を求めたからだ。ダイアログが出ると pipeline は中断する。再開するには手動でダイアログに応答しなければならず、その時点で「skill が自律的に動く」という前提が崩れる。

具体的にいつ・どの skill・どのコマンドで止まったかの記録は残っていない。retro に「同じパターンが複数回再発した」と記録されてはいるが、各セッションの個別事象は記録対象外だった。本記事の関心は「個別の事故」ではなく「事故が再発する設計フロー」の方なので、特定セッションの再現可能性に依存しない形で構造を扱う。

この記事では、skill が他 repo にアクセスするときの permission allow-list を skill を書く前（設計時）に整備する方針と、.claude/settings.local.json の具体的な設計パターンを解説する。後付けで追加すると同じ落とし穴が繰り返される。

なぜ permission が事前整備でなければならないか

skill 実行中に止まることの pipeline 上の問題

Claude Code の permission 制御は「この操作を許可しますか」という対話で機能する。人間がセッション内で操作するときは止まっても対応できる。しかし pipeline の一 step として skill が動くとき、ダイアログへの応答は自動化できない。

DAG の途中で止まると、後続の step が全て実行されない。blog-fill-ssot が phase 1、blog-tech-write が phase 3 として動くとして、phase 1 で permission ダイアログが出て止まると phase 3 には到達しない。途中再開もできない（手動で permission に応答した後、skill を最初からやり直す必要がある）。

過去の skill upgrade での同じ落とし穴

この問題は今回が初めてではない（retro に記録済み）。skill の機能を拡張するとき、新しい Bash コマンドを追加した後で permission ダイアログが出ることを実行時に初めて知る、という パターンが繰り返される。

root cause は「permission の確認を後回しにする」設計フローにある。skill に新しい Bash コマンドを追加する場合、そのコマンドが現在の allow-list でカバーされているかを追加前に確認するフローが標準でなかった。

.claude/settings.local.json の allow-list 設計

Bash(git -C …) のパターン記法

.claude/settings.local.json の allowedTools に Bash のパターンを追加する。パターン記法は Bash({glob}) 形式だ。

{
  "allowedTools": [
    "Bash(git -C /Users/t.morimoto/Desktop/yakumo/internal/**)",
    "Bash(git -C /Users/t.morimoto/Desktop/yakumo/internal/** log*)",
    "Read(/Users/t.morimoto/Desktop/yakumo/internal/**)"
  ]
}

Bash(git -C /Users/t.morimoto/Desktop/yakumo/internal/**) は「/yakumo/internal/ 配下の任意のパスを引数とする git -C コマンド」を許可する。ダブルスター ** は任意のサブディレクトリにマッチする glob パターン。

現在の .claude/settings.local.json に追加された cross-repo 系のエントリは以下の通り:

"Bash(git -C /Users/t.morimoto/Desktop/yakumo/internal/**)",
"Bash(ls /Users/t.morimoto/Desktop/yakumo/internal/**)",
"Bash(cat /Users/t.morimoto/Desktop/yakumo/internal/**)",
"Read(/Users/t.morimoto/Desktop/yakumo/internal/**)",
"Bash(cd /Users/t.morimoto/Desktop/yakumo/internal/**)"

これにより internal/ 配下のすべての repo への git / ls / Read アクセスが許可されている。

ワイルドカードの使い方と範囲の考え方

allow-list の範囲はできるだけ広くとり、後から絞るのが運用しやすい。理由は「後から追加するたびに permission ダイアログの落とし穴に当たるリスクが増える」ためだ。

範囲の考え方:

八雲の用途では /yakumo/internal/** のパターンが妥当だ。社外の repo へのアクセスは含まれないため、範囲として過剰にはならない。

global settings vs project settings の分担

Claude Code には global settings（~/.claude/settings.json）と project settings（.claude/settings.local.json）がある。分担の考え方:

• global settings: 全プロジェクト横断で使う汎用ツール（Read、Bash(ls*) 等）
• project settings: このプロジェクト固有のパス・コマンド（Bash(git -C /yakumo/internal/**) 等）

/yakumo/internal/** のパスは yakumo プロジェクト固有なので project settings に置く。global settings に入れると、他のプロジェクトで不必要なパスが許可されることになる。

cross-repo skill を設計するときのチェックリスト

skill SKILL.md に参照 repo を明記する

skill が他 repo を参照する場合、SKILL.md の先頭または参照セクションに以下を明記する:

## 参照する外部 repo

この skill は `blog-ops/config/related-repos.json` が指す以下の repo にアクセスする:
- synapse: `/Users/t.morimoto/Desktop/yakumo/internal/synapse`
- montage: `/Users/t.morimoto/Desktop/yakumo/internal/montage`

**前提条件**: `.claude/settings.local.json` に `Bash(git -C /Users/t.morimoto/Desktop/yakumo/internal/**)` が登録されていること。

この記述が SKILL.md にあれば、skill を使う前に「permission が整備されているか」を確認するきっかけになる。

SKILL.md 作成前に allow-list を更新する手順

cross-repo skill を新規に作成する場合の標準フロー:

1. skill が使う Bash コマンドを洗い出す（設計段階）
2. 各コマンドが現在の allow-list でカバーされるか確認する

   cat .claude/settings.local.json | python3 -m json.tool | grep allowedTools -A 20

3. カバーされていなければ先に allow-list に追加する
4. SKILL.md を作成し、参照 repo と前提条件を明記する
5. 実際に skill を実行して permission ダイアログが出ないことを確認する

ステップ 3 と 4 の順序が重要だ。SKILL.md を書いてから permission を追加するのではなく、permission を整備してから SKILL.md に前提条件として記録する。

このフローを意識的に運用し始めて以降、実際に細かい改善点はあった（例えば step 2 の cat | grep 確認をスキップして skill 実行に進み、step 5 でダイアログが出て気付いたケースなど）。ただし個別の差分は記録に残しておらず、現時点で参照できる形では残っていない。次の skill 追加時に retro に小さく append する運用に切り替える方が現実的だ。

allow-list の運用 — 追加・棚卸しのタイミング

allow-list は作って終わりではない。skill が増えるほどエントリも増え、使われなくなったエントリが残り続けるリスクもある。

追加タイミング: 新しい cross-repo skill を設計するとき（上記フロー通り）。

棚卸しのタイミング: 大きめの skill リファクタリングのタイミングか、年次の設定見直しタイミングで実施する。棚卸しの手順:

1. allowedTools の各エントリを確認する
2. 対応する skill が削除・変更されていないか確認する
3. 使われていないエントリを削除する

現在の .claude/settings.local.json の allow エントリ総数は 137 件（2026-05-21 時点）。内訳: Bash 系 83 件 / WebFetch・WebSearch 系 31 件 / その他（mcp・Skill 等）22 件 / Read 系 1 件。

allow-list の設計原則は「事前整備、事後確認」だ。permission ダイアログで止まる落とし穴を繰り返さないためには、skill を書く前に permission を確認する習慣を設計フローとして組み込むことが有効だ。

→ product / system の SSOT 化については 話題に上げる product / system は SSOT 化して常時追跡できる状態を保つ を参照
→ 執筆 skill の git log 参照設計については 執筆 skill は他 repo の git log を参照して事実ベースで書く を参照

関連記事

• AI エージェントハーネスの設計原則 — 責任分担・スキル委譲・フォールバック — Pillar