kudo-cowork-code-handoff-protocol¶

このスキルの正体¶

工藤拓真が Claude を Cowork と Code の2系統で並走運用するときに、どの作業をどちらに振り、どう引き継ぐかを決定論的に運用するためのメタプロトコル。動詞群5（Skillを管理する）に所属。

2026-05-05 の48スキル＋17スケジュールタスク棚卸し（Cowork→Code→Cowork→工藤さんの4段ハンドオフ）で得られた知見を完全に型化。同種の大規模作業が再発したとき、ゼロから作戦を組み直さずに済むようにする。

§1 環境差マップ（一次ソース・SSOT）¶

1-1. 物理アクセス層¶

観点	Cowork	Code
実行基盤	Linux sandbox	macOSネイティブ
ホーム配下R/W	❌ mount経由のみ	✅ 全域
既存CLI（git, gh, brew, python等）	sandbox内のみ	直接利用可
ステート保持	bash call毎に独立	連続セッション可

1-2. MCP・ツール層¶

観点	Cowork	Code
scheduled-tasks MCP	✅ 完全可視	❌ 0件返答（スコープ外）
plugin系認証MCP	✅ 大量	△
WorkFlowy MCP	✅	△
Chrome MCP（Claude_in_Chrome / Control_Chrome）	✅（不安定だが利用可）	❌
通常MCP（Slack/Gmail/Calendar 等）	✅	✅
Edit/Write/Read で直接到達できる範囲	mount内	ホーム配下すべて

1-3. UI層¶

観点	Cowork	Code
artifacts／widget rendering	✅	❌
computer:// リンク	✅	❌
ターミナル指示出力	△（テキストのみ）	✅（実行まで担当可）
画面前並走	✅	△
バックグラウンド／長時間処理	△	✅

1-4. コンテキスト層¶

観点	Cowork	Code
コンテキスト窓	標準	Opus 4.7 1M
大量ファイル並列処理	△	✅
1セッション内での反復改修	△	✅

§2 タスク振り分け判断マトリクス¶

新規タスクが来たら、下記4軸で判定：

軸A：このタスクは ~/.claude/ ／~/Library/ ／~/Documents/ への直接R/Wを伴うか？
  Yes → Code（Cowork は到達不可）
  No  → 軸B

軸B：このタスクは MCP（scheduled-tasks／WorkFlowy／Chrome／plugin認証）駆動か？
  Yes → Cowork（Code 側で見えない可能性）
  No  → 軸C

軸C：このタスクは大量ファイル新規生成（>10件）か？
  Yes → Code（コンテキスト効率）
  No  → 軸D

軸D：このタスクは UI rendering（artifact／computer://）が成果物か？
  Yes → Cowork
  No  → どちらでも可（着手中の側で完結が効率的）

典型例（2026-05-05 案件で実証）¶

タスク	振り分け	理由
scheduled-tasks の cron 復元	Cowork	scheduled-tasks MCP は Cowork 独占
21参照ファイルの新規生成	Code	大量ファイル＋ ~/Library/ 配下書込
description 圧縮	Code	SKILL.md 直接書込
~/.claude/skills/ 古複製退避	Code	~/.claude/ R/W
メモリ7ファイル更新	Code	~/.claude/projects/ R/W
MCP認証	Cowork（または工藤さん）	OAuth URL生成は Cowork、クリックは工藤さん
結果検証・整合性チェック	Cowork	hostloop ランタイム読込で並走確認
工藤さん向けクリックアブル指示書	Cowork	computer:// link 必要

§3 ハンドオフ標準フロー（5 Phase）¶

Phase 1: Cowork 棚卸し（事実収集）
  - 現状把握、件数確認、スコープ確定
  - 出力：診断レポート＋指示プロンプト・mdファイル
  - リスク：Cowork 側測定バグの混入（§4-1で対策）

Phase 2: Code 実作業（作業実行）
  - Cowork指示プロンプトを Code にコピペ
  - Code は事実を再検証してから着手（Phase 1 の誤りを訂正）
  - 出力：HANDOFF.md（次節§4-3 のフォーマット）

Phase 3: Cowork 検証（独立確認）
  - Code HANDOFF.md を読み込み
  - hostloop ランタイム経由で結果実測
  - 食い違いがあれば原因特定
  - 出力：VERIFICATION.md

Phase 4: 工藤さん UI処理（人間介入）
  - claude.ai UI／ターミナル経由でしかできない作業
  - 出力：作業完了報告

Phase 5: Cowork 最終確認（クローズ）
  - 全項目PASS確認
  - 残課題リスト整理
  - スキル化機会の発掘

§4 失敗回避の鉄則（2026-05-05 で実証）¶

4-1. SKILL.md description 字数測定は Python 必須（awk禁止）¶

awk スクリプトは YAML frontmatter の閉じ --- を境界認識しないため、本文を取り込んで字数を膨張させる。正しい測定は kudo-skill-md-format-validator の validate_skill.py 一択。

# 正しい抽出ロジック（multi-line YAML literal block 対応）
import re
end = txt.find("\n---", 4)
fm = txt[4:end]
m = re.search(r'(?m)^description:\s*(\|[-+]?|>[-+]?)?\s*(.*)$', fm)
# 以下、style に応じて分岐...

4-2. Cowork で「N件」と言われた数字を Code が信じ込まない¶

Cowork 側の MCP 可視範囲と Code 側のそれは異なる。Cowork が「16件」と言い、Code が「0件」と返ってきたら、それは Code 側が見えていないだけ の可能性が高い。Code は「Code 側で見えなかった」と明記し、Cowork 側の数字を信頼するのが安全。

4-3. Phase 2 Code は冒頭で Phase 1 Cowork の事実訂正を行う¶

ハンドオフ時、Cowork 側の認識違いをそのまま実行すると無駄な作業が発生する。Code は着手前に独立検証して、ズレを冒頭セクションに明記。今回は description 字数のズレ（38件超過 → 0件超過）を訂正したことで圧縮対象が38件→2件に縮減。

4-4. 削除系操作は必ず mv 退避（rm 直行禁止）¶

~/.claude/skills/{name}/ を削除する場合：

# OK
mv ~/.claude/skills/{name} ~/.claude/skills.deprecated-YYYY-MM-DD/

# NG
rm -rf ~/.claude/skills/{name}

1週間の観察期間後に削除。今回は 2026-05-05 退避→ 2026-05-12 削除予定だったが、工藤さん判断で当日削除。

4-5. cloud SSOT との同期方向を確認するまでローカル直接編集は staging 経由¶

ローカルで編集 → cloud から上書きされて消える、というリスクがある。実証経験では cloud→local の単方向同期が確認されたが、それまでは：

staging に作成 → Application Support にコピー → cloud は別途 UI 経由で同期、というワークフロー推奨

§5 ハンドオフ書類フォーマット¶

5-1. Cowork→Code 指示プロンプトの構成¶

## 0. 必読：Cowork側で完了した作業と確定した事実
   - 0-1. 事実訂正テーブル（Code側前回ミスの修正）
   - 0-2. Cowork側完了済（再実行禁止リスト）
   - 0-3. Code側で要確認の項目

## 1〜N. タスク群（タスクごとに：）
   - X-1. 確定事実（Cowork側で実測済データ）
   - X-2. 重要な前提条件・SSOT問題
   - X-3. 各ファイルの判断指針
   - X-4. 作業手順（Step列挙）

## 最終アウトプット（Cowork が読む報告フォーマット）
## 失敗回避チェックリスト（着手前必読）
## 着手順序の推奨

5-2. Code→Cowork HANDOFF.md の構成¶

## 0. TL;DR 表（30秒読み版）
## 1. Code側で確認した環境構造
## 2. 事実訂正（Cowork ブリーフとの差分）
## 3〜N. 各タスクの詳細結果
## 最終アウトプットファイル一覧
## 残課題・要 Cowork 判断項目
## 注意点（Cowork が誤解しないために）
## 検証コマンド集（再現可能性）
## Cowork 推奨アクション順

5-3. Cowork VERIFICATION.md の構成¶

## 0. TL;DR
## 1. 事実訂正（Cowork が誤っていた点を認める）
## 2. Code側 HANDOFF の各セクション検証結果
## 3. 残課題（工藤さん対応必要）
## 4. 横展開機会（仮説）
## 5. 検証コマンド集
## 6. ステータスサマリ

§6 検証コマンド集（再利用可能）¶

6-1. SKILL.md description 字数の正しい測定¶

scripts/validate_skill.py を使う：

SK="<skills directory>"
python3 "$SK/kudo-skill-md-format-validator/scripts/validate_skill.py" --dir "$SK"

6-2. staging↔hostloop バイト整合性¶

SK="<hostloop side>"
STAGING="<staging side>"
for path in $(find "$STAGING" -type f \( -name "*.py" -o -name "*.md" \)); do
    rel="${path#$STAGING/}"
    if diff -q "$path" "$SK/$rel" >/dev/null 2>&1; then
      echo "OK $rel"
    else
      echo "DIFF $rel"
    fi
done

6-3. md5 一致チェック（同一スクリプトの複数コピー）¶

md5sum path/to/qa_check.py path/to/another_qa_check.py

6-4. scheduled-tasks の cron 復元（Cowork 専用）¶

# update_scheduled_task で cronExpression を設定し fireAt をクリア
mcp__scheduled-tasks__update_scheduled_task(
    taskId="...",
    cronExpression="30 16 * * *",
    enabled=True
)

§7 学んだ非対称性パターン（横展開可能）¶

7-1. 「片側の数字を疑う」原則（v1.6 拡張・2026-05-07）¶

複数システム（Cowork／Code／claude.ai cloud）にまたがる事実は、1つのシステムの測定だけを正としない。最低2つで照合。

7-1-a. MCPツール可視性の非対称性パターン（v1.6新設）¶

同じ名前の MCP ツール（例：mcp__scheduled-tasks__list_scheduled_tasks）でも、Cowork 側と Code 側でアクセス権限・スコープ・接続先が異なる。「片側で 0件／該当なし／空」と見えたら、必ずもう一方の環境で再検証する。

実害事例： - 2026-05-05：Code「scheduled-tasks 0件」報告 → Cowork で17件検出（1件目） - 2026-05-07：Code「scheduled-tasks 4本全失」報告 → Cowork で17件全部健全（2件目） - 2回連続で同型事象 → パターンとして型化

型化ルール： - ❌ 反パターン：Code（または Cowork）の MCP 応答 0件を「全失」「未登録」と即断する - ✅ 正パターン：「私の MCP では 0件と見える」と限定し、もう一方に確認依頼を出す - ✅ 工藤さん報告時には「Cowork 視点と Code 視点の両方で確認した上で結論」と明示する

typical 文章テンプレート（HANDOFF/報告で使用）：

「MCP <tool-name> を Cowork で呼んだ結果は N 件、Code で呼んだ結果は M 件。差分の原因は MCP スコープの非対称性であり、実体は{Cowork 側／Code 側／両方}の表示で{確認できる／できない}」

7-1-b. その他の数字を疑う原則¶

ファイル件数（find / ls / wc -l の使い分け、隠しファイル・dotfile・symlink で数字がブレる）
byte サイズ（macOS の resource fork で du と ls -l がズレる）
スキル件数（Anthropic built-in 含む／含まないでブレる）

7-2. 「staging を必ず作る」原則¶

ローカル直接編集は cloud 同期で消えるリスクあり。staging（~/working/ 等）に作成→Application Support にコピー、を標準フローにする。

7-3. 「validate_skill.py を最終ゲートにする」原則¶

スキル形式の整合性は人間判断ではなく機械検査で。Cowork 側の awk バグも、最初から validate_skill.py を使えば発生しなかった。

7-4. 「人間介入をピンポイント化」原則¶

claude.ai UI クリック・ターミナル rm・OAuth クリックなど、自動化できない作業は最後にまとめて指示書化。途中で人間に何度も依頼しない。

§8 トリガーパターン¶

このスキルは以下のシチュエーションで起動：

工藤さんから「Code側にも依頼したい」「Cowork↔Code連携で」「ハンドオフで」「並走で進める」
Cowork が単独で完了できないタスクが発見された瞬間（軸Aで Code 必須と判定）
Code が単独で完了できないタスクが発見された瞬間（軸Bで Cowork 必須と判定）
大規模棚卸し・大規模改修・複数ファイル横断作業の冒頭
工藤さんから「指示プロンプト作って」「HANDOFF.md書いて」

§9 関連スキル¶

kudo-persist-settings：スキル運用ルール（このスキル自身も §3 軸A判定で Code 側書込が必要）
kudo-project-state-recovery：セッションまたぎの状態再構成（このスキルと併用で長期プロジェクトの引き継ぎ完成）
kudo-skill-md-format-validator：§6-1 の validate_skill.py 提供元
kudo-workflowy-double-save：状態再構成時の読込先優先順位

§10 既知の制約・★仮説¶

★scheduled-tasks MCP のスコープ差は将来 Anthropic 側で解消される可能性あり。その場合 §1-2 表を更新する
★cloud→local 同期方向は単方向で確認したが、双方向化される可能性あり。再検証必要
★1M context Code のメリットは大量ファイル処理で実証したが、複雑な依存関係を持つコード生成では別ベンチマークが必要
本スキル v1.0 は 2026-05-05 案件1件からの抽出。複数案件で運用してパターンを検証してから v2.0 に昇格すべき

§11 macOS 固有ガッチャ集 SSOT（v1.1 新設・2026-05-07）¶

11-1. NFD/NFC Unicode 正規化問題¶

症状：「絶対あるはずの日本語キーが見つからない」「ファイル名がほぼ同じなのに突合できない」「grep で見えるのに Python の dict.get() で None」「Spotlight 検索ヒットするのに直接パス指定で開けない」

原因：macOS の APFS（旧HFS+）は伝統的に NFD（分解形式） で日本語ファイル名・JSONキーを保存する。一方、Python・JavaScript 等のソースコード文字列リテラルは NFC（合成形式） が標準。両者は見た目同じだが、バイト列が異なるため文字列比較は失敗する。

例：「ど」（U+3069） - NFC：単一コードポイント 0x3069 - NFD：2コードポイント 0x3068（と） + 0x3099（結合濁点）

影響範囲： - ファイルシステムから取得したパス／ファイル名と、ハードコード文字列との比較 - macOS の APFS に保存された JSON 内の日本語キー検索 - os.listdir() の結果と固定文字列のマッチング - shell の find 結果に対する grep パターンマッチ - 特に「OneDrive-くどう商店」のような濁点・半濁点・拗音を含む名前で頻発

対策（Python）：

import unicodedata

# 比較前に必ず正規化
target_normalized = unicodedata.normalize('NFC', filename_from_fs)
expected = "OneDrive-くどう商店"
if target_normalized == expected:
    ...

# 辞書キー検索でも同じ
matched_key = next(
    (k for k in data if unicodedata.normalize('NFC', k) == expected),
    None
)

対策（Bash）：

# find の結果を Python 経由で NFC 正規化
find ~/Library -type d | python3 -c "
import sys, unicodedata
for line in sys.stdin:
    print(unicodedata.normalize('NFC', line.rstrip()))
"

事例：2026-05-07 の OneDrive→GoogleDrive 移行作業で、Code が ~/.claude.json から「OneDrive-くどう商店」キーを検索した際、JSON 内のキーが NFD 保存だったため raw 比較で「キーが見つからない」エラーに。unicodedata.normalize('NFC', k) で正規化比較に切り替えて解決。

11-2. macOS の File Provider 拡張・サンドボックスコンテナは `rm` から保護される¶

症状：rm -rf でクラウド同期フォルダ（CloudStorage 配下）や Containers 配下を削除しようとすると Operation not permitted で失敗する。sudo を付けても拒否される場合がある。

原因：macOS は CloudStorage 配下（OneDrive/iCloud Drive/Dropbox等の File Provider 拡張のマウントポイント）と ~/Library/Containers/ 配下のサンドボックスコンテナを、ファイルシステム保護で rm から守っている。これは TCC（Transparency, Consent, and Control）の一部。

対策：Finder の権限を借りて削除する。osascript で Finder にゴミ箱送りを依頼すると、ファイルシステム保護を回避できる（root 所有のファイルもパスワード不要で動く）。

# NG（権限拒否）
rm -rf ~/Library/CloudStorage/OneDrive-くどう商店

# OK（Finder 経由）
osascript -e 'tell application "Finder" to delete POSIX file "/Users/foo/Library/CloudStorage/OneDrive-くどう商店"'

# OK（Applications 配下の root 所有アプリも）
osascript -e 'tell application "Finder" to delete POSIX file "/Applications/OneDrive.app"'

事例：2026-05-07 OneDrive アンリンク作業で、~/Library/Containers/com.microsoft.OneDrive* 配下4ディレクトリと /Applications/OneDrive.app の削除に Finder 経由が必須だった。

11-3. ACL の `group:everyone deny delete` で削除拒否¶

症状：rm -rf が "Operation not permitted" で失敗するが、ls -le で見ると Unix permission は 755 で書き込み可能なはず。

原因：macOS の ACL（Access Control List）に group:everyone deny delete が設定されている場合がある。クラウドプロバイダや一部アプリは「ユーザーが誤って消さないように」この防御 ACL を仕掛ける。Unix permission より優先される。

検出：

ls -le /path/to/folder | grep deny

対策：

# ACL をすべて解除してから削除
chmod -N /path/to/folder
rm -rf /path/to/folder

# または再帰的に
chmod -RN /path/to/folder
rm -rf /path/to/folder

事例：2026-05-07 OneDrive アンリンクで、~/Library/CloudStorage/OneDrive-くどう商店/ 自体に deny delete ACL が設定されていて削除拒否。chmod -N で解除後に削除成功。

11-4. Claude Code が cwd を `~/.claude.json` に自動再登録する¶

症状：クリーンアップ作業中、~/.claude.json から旧パス（例：OneDrive 配下）のプロジェクトキーを削除したのに、しばらく経つと再度同じキーが現れる。

原因：実行中の Claude Code セッションが、自分の cwd（current working directory）を ~/.claude.json に自動登録する仕様。セッションが旧パス配下で動いていると、削除しても再生成される。

対策： 1. 旧パス配下から起動した Claude Code セッションをすべて終了 2. 新しいセッションを ~/working（抽象パス）から起動 3. その状態で ~/.claude.json のキーを削除すれば再発しない

# 望ましい起動方法
cd ~/working
claude code

事例：2026-05-07 OneDrive アンリンク中、旧 OneDrive パス配下から実行されていた Claude Code セッションが ~/.claude.json にキーを再登録し続けた。セッションを ~/working から起動し直して解決。

11-5. シェルセッションの cwd が削除されるとシェルが `/private/tmp` にリセットされる¶

症状：作業中に「シェルが急に /private/tmp に移動した」「相対パスが効かなくなった」「環境変数が変な値を返す」。

原因：実行中のシェルセッションの cwd（カレントディレクトリ）を別プロセス／別操作で削除すると、シェルは「もういない場所」にいることになり、macOS は安全のために /private/tmp に強制移動させる。bash/zsh ともに同じ挙動。

対策： - 削除対象フォルダ配下からシェルを起動しない（事前に cd ~ 等で退避） - 削除作業の前に pwd で確認、必要なら別の安全な場所に cd - シェルが /tmp にリセットされた場合は、新セッションを起動するか cd ~/working で復帰

事例：2026-05-07 OneDrive アンリンクで、Code セッションの元 cwd が OneDrive-くどう商店/working だったため、フォルダ削除と同時に Code のシェルが /private/tmp にリセットされた。

11-6. macOS の File Provider 配下は Spotlight インデックス対象外（仕様）¶

症状：mdutil -s ~/Library/CloudStorage/GoogleDrive-.../ を実行すると Error: unknown indexing state. が返る。「インデックスが壊れた？」と思いがちだが、これは正常。

原因：macOS は ~/Library/CloudStorage/ 配下（OneDrive/iCloud Drive/Google Drive/Dropbox 等の File Provider マウントポイント）を Spotlight インデックスから意図的に除外している。理由はクラウド側の動的マウント挙動を考慮したパフォーマンス／消費電力対策。

意味： - クラウド配下のファイルは macOS の Spotlight 検索（Cmd+Space）に出てこないことがある - mdfind でもヒットしないことがある - Finder の検索バー（フォルダ内検索）は別ロジックで動くので使える - 各クラウドアプリ内の検索（Google Drive アプリの検索バー等）も使える

対策： - macOS Spotlight でクラウドファイルを横断検索したい場合は、symlink でホーム直下にマウント（例：~/working）すると、シンボリックリンク先がインデックス対象になることがある（環境依存） - 確実なのは Google Drive Web の検索 or Finder のフォルダ内検索 - 検索 UX を強化したいなら NotebookLM や Gemini Workspace 連携を活用

事例：2026-05-07 OneDrive→GDrive 移行後の Phase 6 検証で、~/working/ と ~/Library/CloudStorage/GoogleDrive-.../ の両方で "unknown indexing state" 表示。当初は「インデックス再構築が必要？」と疑ったが、これが macOS の標準仕様と判明。

11-7. クラウドプロバイダ独自ゴミ箱 ≠ Mac の `~/.Trash/`¶

症状：クラウド同期フォルダ内のファイルを Finder/AppleScript でゴミ箱送りにしたのに、ls ~/.Trash/ には出てこない。「削除されたのか？」と不安になる。

原因：File Provider 経由でマウントされたフォルダ（OneDrive/iCloud Drive/Google Drive/Dropbox 等）からファイルを削除すると、macOS の ~/.Trash/ ではなく 各クラウドプロバイダ独自のゴミ箱に送られる。 - OneDrive：onedrive.live.com の「ごみ箱」 - Google Drive：drive.google.com の「ゴミ箱」 - Dropbox：Dropbox Web の「削除済みファイル」 - iCloud Drive：iCloud.com の「最近削除した項目」

意味： - Mac のディスク容量はその場で解放される（クラウド側に行ったので） - 復元したい場合は Web 側のゴミ箱から - ~/.Trash/ を空にしても、クラウド側ゴミ箱は別途空にする必要がある

対策： - Mac 側で「削除＝完全に手放す」つもりなら、Web 側ゴミ箱も忘れずに空にする - 「とりあえず取り除きたいだけ」なら Web 側ゴミ箱から復元可能なので安心

事例：2026-05-07 Phase 4 で 4.7GB の 2411dof望年会用photo.zip を osascript "tell Finder to delete" で削除。~/.Trash/ は空のまま、Mac ディスク容量はその場で解放。OneDrive Web 側のごみ箱に存在（30日後自動削除 or 手動空き）。

11-8. Claude Code の「セッション再開」機能が旧 cwd を参照する¶

症状：Claude Code を完全終了→新規起動したのに、起動時に "Working directory no longer exists: {旧パス}" エラーが出てチャットが動かない。新セッションのつもりが古い状態を引きずっている。

原因：Claude Code はセッション終了時に 「最後に開いていたフォルダ／チャット状態」を保存し、次回起動時に自動復元しようとする。前回のセッションが既に削除されたフォルダ（例：OneDrive アンリンク前のパス）にいた場合、復元時にそのフォルダを参照しに行って失敗する。

対策（完全リセット手順）：

# 1. Claude Code を完全終了
# Cmd+Q 推奨（Dock からの ✕ ではアプリが残る場合あり）

# 2. ~/.claude.json から旧パスのプロジェクトキーを削除
python3 << 'EOF'
import json, os, unicodedata
path = os.path.expanduser("~/.claude.json")
with open(path) as f: d = json.load(f)
removed = [k for k in list(d.get('projects', {}).keys())
           if 'OneDrive' in unicodedata.normalize('NFC', k) 
           or '消したい旧クラウド名' in unicodedata.normalize('NFC', k)]
for k in removed:
    del d['projects'][k]
with open(path, 'w') as f: json.dump(d, f, indent=2, ensure_ascii=False)
print(f"Removed: {removed}")
EOF

# 3. ターミナルから新規起動（Recent / Dock 経由は避ける）
cd ~/working && claude

# 4. それでもダメなら Claude Code のキャッシュごとリセット
# rm -rf ~/Library/Caches/com.anthropic.claudecode

重要：Step 2 では unicodedata.normalize('NFC', k) を使う（§11-1 の NFD/NFC ガッチャと連動）。raw 比較では日本語フォルダ名がヒットしない。

事例：2026-05-07 OneDrive アンリンク後、Code を再起動しても旧 OneDrive パスを参照して動かなかった。Cmd+Q → ~/.claude.json クリーン → ターミナル経由起動で完全復旧。Claude Code の「Recent Projects」リストや「最後のセッション復元」機能が悪さをしていた。

§11-4 との関係：§11-4 は「セッション継続中の自動再登録」、§11-8 は「終了→起動時の自動復元」。両方が組み合わさると「削除しても復活する」現象になる。完全解消には両方の対処が必要。

11-9. sync-skills.sh の「変更なし」表示は失敗ではなく既に同期済みのサイン¶

症状：bash sync-skills.sh --install を実行したのに、期待していた「(更新)」「(新規)」の緑チェックが出ず、全スキルが「(変更なし)」と表示される。「同期されていないのでは？」「失敗したか？」と誤認しがち。

原因：claude.aiの裏側にある staging↔skills-plugin SSOT の自動同期メカニズム が、Google Drive上のstaging（working/claude/kudo-skill-sync/skills/）への編集を、数秒〜数分以内に真のSSOT（~/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin/*/*/skills/）へ自動反映している。sync-skills.sh --install が diff -rq で両者を比較した時点で既に同一だったため、「(変更なし)」と判定された。これは成功のサインであって失敗ではない。

検証方法：

# 1. staging 側に新パスが残っているか
grep -rn "新しいパス文字列" \
  ~/Library/CloudStorage/GoogleDrive-*/マイドライブ/working/claude/kudo-skill-sync/skills/ \
  --include=SKILL.md | head -5

# 2. 真のSSOT側にも同じ新パスが入っているか
grep -rn "新しいパス文字列" \
  "$HOME/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin/"*/*/skills/ \
  --include=SKILL.md | head -5

# 両方ヒット = 同期完了

判定マトリクス：

出力パターン	意味	対処
全スキル「(変更なし)」	自動同期が既に走った＝成功	何もしなくてよい（grepで念のため確認）
一部「(更新)」「(新規)」+ 残り「(変更なし)」	自動同期がまだ走っていない or 一部のみ走った	正常。スクリプトが残りを反映
エラー出力	真のSSOTへのパス解決失敗	sync-skills.sh の SSOT_MATCHES 解決を確認

注意：自動同期のラグはクラウド・OS状況により数秒〜数分。staging 編集直後（30秒以内）に sync-skills.sh を走らせた場合は「(更新)」が出る可能性が高い。両ケースを区別したい場合は staging と SSOT の SKILL.md mtime を比較する。

事例：2026-05-07 Claudeフォルダ統合作業（claude-reference / kudo-skill-sync / code-handoffs を working/claude/ 配下に統合し14スキルのパス参照を一括更新）の最終 sync で、全49スキルが「(変更なし)」表示となった。最初は失敗を疑ったが、staging に新パス27件が残存している事実 + 真のSSOT側にも同じパスが入っている事実から、claude.ai の自動同期が先行して走り終えていたと判明。以後「(変更なし)」を成功と認識する判定基準を本セクションに型化。

11-10. （将来追加）¶

このセクションは macOS 固有の罠を蓄積していく場所。発見したら追加。

§12 ハードウェア過剰でも重い Mac の診断パターン SSOT（v1.4 新設・2026-05-07）¶

「PCが重い／Excel・PowerPointが固まる／Chromeタブ多いと激重」系の依頼が来たとき、Cowork と Code でどう分業し、どう順番に潰すかの定型プロトコル。M3 Pro/36GB/4TB のような高スペック機で「それでも重い」が起きる状況を想定した型。

12-1. 「ハード十分→ソフト主犯」確定の初動3ステップ¶

スペック不足を疑う前に、必ずこの順で潰す。Cowork 側で完結。

Step 1：スペック確認（Cowork）
  - システム設定 > 一般 > 情報 から チップ／RAM／ストレージ／macOS バージョン取得
  - 外部ディスプレイ解像度を取得（4K以上か）
  - 判定：M1/M2/M3 系＋16GB以上＋ストレージ50%以上空き → ハード十分
  - → Step 2 へ

Step 2：症状の物的証拠を取る（Cowork）
  - 「重い」と感じる具体ファイル／タブ／操作を1つ受領
  - そのファイルの構造を bash で解剖（Excel/PPT は xlsx/pptx を unzip）
  - 数式数／条件付き書式数／結合セル数／長文テキストセル数／画像数／チャート数を数値化

Step 3：3要因仮説で切り分け（Cowork→Code 分業）
  A. 表示系：4K/Retina の描画コスト        → Cowork で設定確認
  B. アプリ固有：Mac版 Excel/PPT 特有の遅延 → Cowork でレシピ提示
  C. 常駐系：LaunchAgents/キャッシュ蓄積    → Code に丸投げ

12-2. Cowork×Code 標準分業（Mac高速化版）¶

タスク	担当	理由
スペック取得（システム設定 GUI）	Cowork	screenshot で確認
重いファイルの内部構造解剖	Cowork	sandbox bash で unzip + 解析
4K ディスプレイ設定確認・誘導	Cowork	設定画面の screenshot 必須
Chrome/Excel/PPT のアプリ内設定	Cowork	GUI 操作
`~/Library/Caches` 容量計測	Code	ホーム直接アクセス
`LaunchAgents` `LaunchDaemons` 棚卸し	Code	`launchctl list` 必要
`memory_pressure` `vm_stat` 実測	Code	CLI 限定
`top -l 1 -o mem` 上位プロセス	Code	CLI のみ
クリーンアップコマンドの実行	工藤さん（Code 提案後）	rm 系は要承認

12-3. Excel 重さ診断の数値テンプレート（Cowork sandbox bash）¶

xlsx は zip。unzip して xml を grep するだけで主要メトリクスが取れる。

# 0. 解凍
mkdir -p /tmp/xlsx_x && unzip -o "対象.xlsx" -d /tmp/xlsx_x/ > /dev/null
cd /tmp/xlsx_x

# 1. 構造メトリクス
echo "範囲：" && grep -oE '<dimension ref=\"[^\"]*\"' xl/worksheets/sheet1.xml
echo "セル数：" && grep -o "<c " xl/worksheets/sheet1.xml | wc -l
echo "数式：" && grep -o "<f " xl/worksheets/sheet1.xml | wc -l
echo "条件付き書式：" && grep -o "<conditionalFormatting" xl/worksheets/sheet1.xml | wc -l
echo "結合セル：" && grep -o "<mergeCell " xl/worksheets/sheet1.xml | wc -l

# 2. 文字描画コスト（ここがMac版Excelの主犯）
python3 << 'PY2'
import re
with open('xl/sharedStrings.xml','r',encoding='utf-8') as f: data=f.read()
strs=re.findall(r'<t[^>]*>([^<]*)</t>',data)
lens=[len(s) for s in strs if s.strip()]
print(f'長文セル(200字+): {sum(1 for l in lens if l>=200)}件')
print(f'描画総文字数: {sum(lens):,}字')
PY2

判定基準： - 長文セル200字超 × 100件以上 → Mac版Excelの長文描画ボトルネック確定 - 数式 1万超 → 計算負荷主犯 - 条件付き書式 100超 → スクロール時再評価で重い - 画像（xl/media/）数MB超 → ファイル分割推奨

12-4. 4K高解像度ディスプレイ仮説の検証チェックリスト¶

Cowork で必ず確認： - [ ] 外部ディスプレイの解像度（システム設定 > ディスプレイ） - [ ] 4K以上ならスケーリング設定を1段階「文字を大きく」寄りに移動して比較 - [ ] リフレッシュレート（60Hzか／可変か） - [ ] HDR/True Tone/Night Shift の ON/OFF - [ ] 内蔵＋外部の同時駆動でピクセル総数計算（>1500万px なら描画起因疑い濃厚）

12-5. 成果物テンプレート4点セット¶

Mac高速化案件は最終的に以下4ファイルで完結する。outputs/ 配下に出力：

00_PC高速化_診断レポート.html：工藤さんの濃紺カラー（#242530）で視覚的ダッシュボード。スペック表＋3要因仮説＋アクション一覧
01_即効改善チェックリスト.md：工藤さん向け7項目（5〜20分で完了する手順）
03_重いファイル軽量化レシピ.md：診断対象ファイルに特化した個別対処（Excel/PPT/PDF 等）
HANDOFF_to_Claude_Code.md：Code 側に丸投げする5タスク指示書

このセットで「Cowork 側完結部分の提示」と「Code 側への引継」が同時に完了する。

12-6. 既知の罠（横展開）¶

Activity Monitor が installed-apps に出ないことがある：その場合 Code 側の memory_pressure vm_stat top -l 1 で代替
「このMacについて」ウィンドウは com.apple.SystemProfiler 別プロセスで grant 不可：システム設定 > 一般 > 情報経由が確実
ハイスペ機ほど「ハード不足」を疑いがちだが大抵は逆：「ハード十分→ソフト主犯」を最初に確定させると以後の判断が速い

事例：2026-05-07 工藤さん MacBook Pro M3 Pro/36GB/4TB+MateView 4K案件。Excel 4_23課題.xlsx（124KB・数式0なのに重い）→ 解剖で「238セルに1セル400字級長文＝総94,400字描画」と判明。Cowork で診断レポート＋Excelレシピ＋Chrome設定誘導、Code 側に常駐物棚卸し＋キャッシュ計測を分業発注。本 §12 はその案件から型化。

§13 HANDOFF配置先 SSOT（v1.5新設・2026-05-07 / v1.13 集中原則統合・2026-05-15）¶

本セクションが「Cowork↔Code HANDOFF文書の配置先」の唯一の正本（SSOT）。 各スキル・補足ドキュメントは「kudo-cowork-code-handoff-protocol §13 HANDOFF配置先 SSOT」で参照する。

v1.13（2026-05-15）以降の SSOT 統合：本 §13 は kudo-shared-storage-protocol v1.2 §5.5 および CLAUDE.md §3.1 の集中原則ガバナンスに準拠する（HANDOFF は「Claude 関連管理ファイル」として _claude_workspace_global/handoffs/ 配下が第一選択）。

なぜ必要か¶

2026-05-05〜2026-05-07 の3案件（skill-recovery／skill-folder-unification／onedrive-migration）で生成された HANDOFF 文書が working/ 配下の3カ所に散在した：

散在状態（2026-05-07 整理前）：
working/outputs/HANDOFF_PHASE2〜6_RESULT.md      ← OneDrive移行5本
working/claude/kudo-skill-sync/HANDOFF-TO-CODE-*.md     ← Skill統合2本（現役）
working/claude/kudo-skill-sync/archive/2026-05-05_recovery/HANDOFF*.md  ← May 5 recovery 4本

「以前同じ作業をした実績ある？」を遡ろうとしても、保管場所がバラバラで見つからず、再発明や同じ罠の踏み直しが起きる。v1.13 で集中原則ガバナンス導入後は、3 環境（Chat / Cowork / Code）が同じ _claude_workspace_global/handoffs/ を見るため、散在の構造的原因が解消された。

配置ルール（v1.13 確定・現行）¶

【現行 SSOT（v1.13・第一選択）】
~/working/_claude_workspace_global/handoffs/HANDOFF-{phase}-{slug}-vN.md
                                              （Chat / Cowork / Code すべての発信源で共通）

【完了後アーカイブ】
~/working/_claude_workspace_global/handoffs/archive/YYYY-MM-DD_案件名/
├── HANDOFF-{phase}-{slug}-vN.md
├── completion-report-*.md（reports/ から複製しない・cross-link する）
└── README.md（任意・案件サマリ）

旧 SSOT（v1.5–v1.12）の扱い¶

旧 SSOT（kudo-skill-sync/HANDOFF-TO-CODE-*.md ／ code-handoffs/YYYY-MM-DD_案件名/）は v1.13 で廃止予定だが、過去ファイルは履歴として残置する（rm 禁止）：

【旧 SSOT・履歴保持のみ・新規追加禁止】
~/working/claude/kudo-skill-sync/HANDOFF-*.md       ← 履歴のみ
~/working/claude/code-handoffs/YYYY-MM-DD_案件名/    ← 履歴のみ

新規 HANDOFF は 必ず _claude_workspace_global/handoffs/ へ。旧 SSOT 継続が必要な特例ケース（例：Cowork セッション内で kudo-skill-sync/ パスをハードコードしている自動化が残存する場合）は、kudo-shared-storage-protocol §5.5-3 の相談プロトコルを通すこと。

命名規則¶

文書種別	ファイル名フォーマット	説明
案件横断 HANDOFF（v1.13 標準）	`HANDOFF-{phase}-{slug}-vN.md`	例：`HANDOFF-phase3-shu-chu-gen-soku-v1.md`。Chat / Cowork / Code いずれの発信源でも同一形式
Cowork→Code 依頼（旧 v1.5・v1.13で廃止）	`HANDOFF-TO-CODE-YYYY-MM-DD.md`	履歴のみ・新規追加禁止
Code→Cowork 報告（旧 v1.5・v1.13で廃止）	`HANDOFF-FROM-CODE-YYYY-MM-DD.md`	履歴のみ・新規追加禁止
中間フェーズ報告	`HANDOFF_PHASE{N}_RESULT.md`	多段階作業のフェーズ単位中間報告
完了報告	`reports/YYYY-MM-DD-{案件名}-completion.md`	`_claude_workspace_global/reports/` 配下（kudo-shared-storage-protocol §5.5-2）
案件サマリ	`README.md`	任意。案件全体の文脈を1ページで把握できる索引

案件名フォルダ命名：YYYY-MM-DD_{kebab-case-topic}/ - 例：2026-05-05_skill-recovery/ 2026-05-07_onedrive-migration/ 2026-05-07_skill-folder-unification/

移送タイミング¶

Working中→完了後への移送は、以下のいずれかのトリガーで実行：

案件完全終了（Code側からHANDOFF-FROM-CODE着・Cowork側でVERIFICATION完了・WorkFlowy記録完了）
新規案件着手の前夜（前案件の文書が次案件の作業ノイズにならないよう片付ける）
月次クリーンアップ（月末などの定期点検）

移送方式：原則 cp（コピー）で原本残置＋code-handoffs/ にも保管。重複ストレージ消費は許容（HANDOFF は数十KB単位なので無視できる）。理由： - 現役のkudo-skill-sync/側にも残しておくとそのセッションの直近文脈で参照しやすい - code-handoffs/側は「過去実績アーカイブ」として案件横断検索の対象になる

code-handoffs/ 配下のINDEX運用¶

claude/code-handoffs/
├── README.md                                       ← 全案件の年表＋命名規則
├── 2026-05-05_skill-recovery/
│   ├── HANDOFF-TO-COWORK-2026-05-05.md
│   └── HANDOFF-FROM-CODE-*.md（複数）
├── 2026-05-07_onedrive-migration/
│   ├── HANDOFF_RESULT.md（整合性検証）
│   └── HANDOFF_PHASE2〜6_RESULT.md
└── 2026-05-07_skill-folder-unification/
    ├── HANDOFF-TO-CODE-2026-05-07.md
    └── HANDOFF-FROM-CODE-2026-05-07.md

違反時の挙動¶

新規 HANDOFF 発行時に以下の違反を検出した場合、即座に修正する：

違反パターン	修正アクション
新規 HANDOFF を `~/Downloads/` ／ Desktop ／ outputs/ 直下／ kudo-skill-sync/ に置く	`_claude_workspace_global/handoffs/HANDOFF-{phase}-{slug}-vN.md` へ移送
案件横断作業の HANDOFF をクライアント案件直下 `_claude_workspace/02_work/` に混入	global 側 `handoffs/` へ移送（案件越境禁止・kudo-shared-storage-protocol §5.5-4）
案件完了済みなのに `handoffs/` 直下に滞留	`handoffs/archive/YYYY-MM-DD_案件名/` へ移送
YYYY-MM-DD なし、案件名が曖昧（HANDOFF.md とだけ）	必ず `HANDOFF-{phase}-{slug}-vN.md` 形式に統一
旧 SSOT（`kudo-skill-sync/` / `code-handoffs/`）に新規 HANDOFF を発行	新規は global へ。旧 SSOT は履歴保持のみ・rm 禁止

code-handoffs/ から得られる横展開メリット¶

再発明回避：「以前同じ案件で何やった？」を案件名で grep 一発（例：grep -r "rsync --delete" code-handoffs/）
失敗事例DB：過去の HANDOFF を検索することで、同じ罠（例：NFD/NFC問題、ACL deny delete、空placeholder直下のSSOT誤認）を踏まないナレッジが溜まる
テンプレート化：似た性質の作業（例：マイグレーション系、棚卸し系、recovery系）は過去案件の HANDOFF を雛形として再利用できる

実証例（2026-05-07）¶

3案件のHANDOFF文書11本を code-handoffs/ 配下の3つの案件サブフォルダに集約。詳細は code-handoffs/README.md（v1.5プロトコル準拠で同時生成）参照。

§14 HANDOFF同梱物 vs 外部参照物の明示プロトコル（v1.7新設・2026-05-08）¶

本セクションが「HANDOFF文書に登場するファイル群を、Code Claudeが着手前に確実に発見できるようにする」ための SSOT。 各HANDOFF.mdは「kudo-cowork-code-handoff-protocol §14 HANDOFF同梱物 vs 外部参照物の明示プロトコル」を冒頭で参照する。

14-1. なぜ必要か（実害事例）¶

2026-05-08 Cowork→Code 連携の実害： Cowork が「kudo-skill-cross-reference-resolver/SKILL.md v1.0 と HANDOFF を同梱」と HANDOFF §1 に記述したが、Code Claude が ~/working/claude/kudo-skill-sync/skills/ を探しても SKILL.md v1.0 が見当たらず、Stage 1 着手前にブロッカー停止。

Code Claude の判断は完全に正当：「同梱」と明記された本体ファイルが現環境に存在しない以上、推測実装は本番48スキルへの破壊リスクが大きすぎる、として QUESTIONS.md を起票して停止。これは kudo-source-verification の原則（一次ソース照合）と一致した、模範的な慎重さである。

真因：HANDOFF.md側の表記「同梱」が、実態（Cowork outputs/ 配下に作成・claude.ai cloud sync 経由で配布予定・手動コピーで物理配置）と乖離していた。Cowork sandbox と Code 実環境のファイル配置非対称性を、HANDOFF文書が明示していなかった。

14-2. 2カテゴリの定義¶

HANDOFF.md に登場する「Code Claude が読むべきファイル」は、必ず以下2カテゴリのいずれかに分類して明示する：

カテゴリ	定義	例
【同梱物】	HANDOFF.md と同じディレクトリに物理存在するファイル	HANDOFF と同じフォルダにある参考スクリプト、テストデータ
【外部参照物】	別経路（claude.ai cloud sync／手動コピー／Cowork outputs／別リポジトリ等）で配置されるファイル	Cowork起草SKILL.md、claude.ai上のスキル本体、Web上のリファレンス

14-3. HANDOFF.md冒頭の必須テンプレート¶

すべての HANDOFF.md（Cowork→Code 依頼／Code→Cowork 報告）は、以下のセクションを§1直後に必ず含める：

## §0 ファイル配置マップ（着手前に必ず実在検証すること）

### 【同梱物】HANDOFF.mdと同じディレクトリに存在
- `./HANDOFF_xxx.md`（本ファイル）
- `./SUPPORTING_yyy.md`
- `./fixtures/zzz.json`

### 【外部参照物】別経路で配置・取得
| ファイル | 配置経路 | 取得方法 |
|---|---|---|
| `kudo-skill-cross-reference-resolver/SKILL.md` | Cowork起草 → 工藤さんが手動コピー | `~/working/claude/kudo-skill-sync/skills/kudo-skill-cross-reference-resolver/SKILL.md` に存在するか `ls` で確認。無ければCoworkに照会 |
| `kudo-persist-settings#config-file-location-map` | claude.ai cloud sync スキル本体 | `/var/folders/.../claude-hostloop-plugins/.../skills/kudo-persist-settings/SKILL.md` の anchors frontmatter を grep。**ただし Stage 1 でanchor付与する未来参照の場合は §14-5 参照** |

### 着手前検証チェックリスト
- [ ] 【同梱物】すべて `ls` で存在確認
- [ ] 【外部参照物】すべて配置経路で実在確認、または「未来実体化」マーク確認
- [ ] 不在ファイルがあれば即 QUESTIONS.md 起票・着手停止

14-4. Code Claude の初動プロトコル¶

HANDOFF を受領した Code Claude は、以下を厳守：

Step 1：HANDOFF §0 ファイル配置マップを最初に読む（§1〜本文より先）
Step 2：同梱物の存在を ls で確認
Step 3：外部参照物の存在を、配置経路に従って確認
Step 4：未来実体化マークがある参照（§14-5）は「現時点で未存在」を許容
Step 5：上記いずれかで不在検出 → QUESTIONS.md 起票・着手停止
Step 6：すべて存在確認OK → §1 から本作業着手

この初動プロトコルが、本HANDOFFのStage順序と矛盾するように見える場合は、§14-5 で例外処理する。

14-5. 「未来実体化参照」のマーク方式¶

Stage 順序で実装中に anchor / セクション / ファイルが順次実体化される設計の場合、HANDOFF 内の参照には 【未来実体化】マーク を必ず付ける：

| `kudo-persist-settings#config-file-location-map` | 【未来実体化】Stage 1.2 のパイロット適用で実体化される | Stage 1.2 完了前にこの参照を解決する必要がある場合は、Stage順序が間違っているのでHANDOFF設計者に照会 |

このマークがあれば、Code Claude は「現時点で不在」を正しく許容できる。マークが無いのに不在 → 即停止。

14-6. Cowork起草時のチェックリスト¶

Cowork が HANDOFF.md を起草する際は、保存前に以下を必ず確認：

HANDOFF §0 ファイル配置マップを記述したか
§0 内のすべてのファイルが【同梱物】【外部参照物】どちらかに分類されているか
【外部参照物】の配置経路と取得方法が、Code Claudeが機械的に検証できる粒度で書かれているか
Stage 順序で順次実体化されるものに【未来実体化】マークを付けたか
HANDOFF.md と同じディレクトリに、すべての【同梱物】を実際に配置したか

これを怠ると、本セクションの起点となった2026-05-08事例が再演する。

14-7. 関連スキル¶

kudo-skill-cross-reference-resolver §reference-syntax — 【外部参照物】のうち anchor 形式参照（kudo-XXX#anchor）の解決はこちらに委任
kudo-source-verification — Code Claude が一次ソース確認を貫く際の判断指針。本§14と精神を共有
kudo-cowork-code-handoff-protocol §13 HANDOFF配置先 SSOT — 配置先は §13、配置物の宣言は §14、で役割分担

§15 Cowork起草spec drift防止＋二段監視構成パターン（v1.8新設・2026-05-08）¶

本セクションが「Cowork起草spec の腐敗を未然に防ぎ、自動再生成パイプラインを二段で監視する」ための SSOT。

15-1. 起点（実害事例）：HIGH 4件が全 Cowork 責務だった¶

2026-05-08 の kudo-skill-cross-reference-resolver Stage 1〜7 完走時、Code Claude による腐敗検出で HIGH severity 4件が発見されたが、全件が Cowork 起草 spec の drift（パイロット frontmatter §13.1/§13.2 の heading 不一致・§5.1 例示文の架空 anchor 名）だった。

Code Claude は実体本文を grep して frontmatter を実装したが、Cowork（私）は spec 起草時に実体本文を確認せず記憶ベースで heading を書いたため、両者に drift が発生した。

15-2. Cowork起草spec drift 防止プロトコル¶

Cowork が他スキルのセクションを参照する spec / HANDOFF / 個人設定を起草する際は、以下を厳守：

ルール	内容
記憶で書かない	「§4 ★仮説マーカー規範」のような外部スキルのセクション名は、必ず実体本文を grep してから記述する
anchor_id は記憶でOK	設計判断（自分が決めるもの）なので記憶ベース可。ただし実体に既存の anchor_id がある場合はそれを優先
heading は実体verbatim	実体本文の「## §N XXX」をそのままコピー。§番号・括弧書き・末尾接尾辞も含めて1文字一致
パイロット例示も実体grep必須	pilot frontmatter / 例示の例文に登場する全 heading を grep で実体確認
未確認は★仮説マーク	grep できなかった場合は anchor 行に `# ★仮説：実体未確認・要verify` コメントを残す

これは kudo-source-verification の精神（一次ソース照合）を spec 起草段階に拡張したもの。kudo-skill-cross-reference-resolver §13 の v1.0 → v1.1 改訂で 4件の drift を解消したのが実証ケース。

15-3. 二段監視構成パターン（LaunchAgent + scheduled-tasks）¶

自動再生成パイプライン等の重要な定期処理は、以下の二段構成で監視を組む：

段	役割	担当	強み
第1段：実行層	実際の処理を確実に走らせる	LaunchAgent（macOS native cron）／Code 側で plist 配備	実行確実性・OSレベルで保証
第2段：監視層	第1段の実行結果を検査し、異常時のみ通知	scheduled-tasks（Cowork独占）／週次cron	通知能力（Slack DM・WorkFlowy）・工藤さん可視性

ポイント： - 第1段は黙々と走る（成功時は通知しない） - 第2段は第1段のレポートファイルや mtime を読み、異常時のみ Slack DM - 二段に分けるのは「実行確実性」と「通知能力」の責務分離（単一プラットフォームで両立しない）

実証ケース：2026-05-08 確立。kudo-skill-cross-reference-resolver の週次再生成パイプライン。LaunchAgent が Sunday 03:00 に regenerate_ssot_map.py 実行、scheduled-tasks の skill-ssot-monitor が Sunday 09:00 にレポート確認＋異常時 Slack DM。

判定基準（scheduled-tasks 監視層）： - ファイル不存在 → ALERT_TYPE = "監視対象消失" - mtime が8日以上前 → ALERT_TYPE = "LaunchAgent停止疑い" - HIGH severity 検出 → ALERT_TYPE = "腐敗検出" - 上記すべて該当せず → 沈黙（通知なし）

15-4. ★H3確定：scheduled-tasks は prompt 実行型¶

2026-05-08 の Code Claude による Stage 7 実装で確定：scheduled-tasks MCP は 「Claude セッションを起動して prompt を実行する」型 であり、shell script を直接実行する型（cron / LaunchAgent）とは別物。

運用上の意味： - script を直接走らせたい → LaunchAgent - Claude の判断・MCP連携・Slack送信を含めたい → scheduled-tasks - 両方欲しい → §15-3 の二段構成

15-5. 関連スキル¶

kudo-skill-cross-reference-resolver §schema-spec — 本パターンの起源案件
kudo-source-verification — Cowork起草段階での一次ソース照合の精神
kudo-persist-settings #reference-link-integrity — 月次クリーンアップとの統合点（本パターンは週次・参照リンク整合性は月次の二重ガード）

§16 環境指定の上書きプロトコル（最速安定優先・v1.9新設・2026-05-15）¶

本セクションが「工藤さんから『coworkで』『codeで』『chatで』と環境指定があっても、自動受諾せず最速安定の観点で再評価する」ための SSOT。

16-1. 起点（実害事例）¶

2026-05-15 命名統一プロジェクト初動：工藤さんから「NotebookLM／claude.ai Project を Cowork でやって」と指示。Chat Claude は当初 Plan A（Cowork ブラウザ自動化）/ Plan B（工藤さん手動＋手順書HTML）の二段構えを提案したが、再評価により Plan B 単独が圧勝（自動化オーバーヘッド > 手動所要時間）。

その後工藤さんから「coworkじゃなくてcodeがいい内容あれば、ちゃんとふりわけてね。今回に限らず、『coworkでやって』といわれても、cowork と code、chat の組み合わせで、もっともスピーディーかつ安定の運用を提案してきて」という運用方針指示。指定の自動受諾を禁ずる規範として永続化要請が発生。

16-2. 規範¶

工藤さんから環境指定（「coworkで」「codeで」「chatで」または特定環境を前提とした指示）があった場合、自動受諾しない。必ず以下の3軸で再評価し、より速く・安定で・副作用の少ない選択肢があれば上書き提案する。

最速：実時間で完了するまでの分数
安定：成功率・再試行コスト
副作用最小：半端な状態で止まった時の復旧容易さ

16-3. 判断マトリクス（v1.12 SSOT・2026-05-15 修正）¶

作業タイプ	推奨環境	理由
ローカルファイル直接編集（~/.claude/、~/Library/、~/working/）	Code	Chat/Coworkからアクセス不可（§1-1 物理アクセス層）
Python スクリプトのロジックテスト（FS操作はモックで再現可能）	Chat（Linux コンテナ）（v1.11新設）	bash_tool で `mkdir`/`python3` 実行可能。HANDOFFを渡す前のbug 潰しに必須（kudo-ai-error-watchlist Entry #11）
Python スクリプトの本番配置（~/.claude/scripts/）	Code	ローカルFS書込権限
Python スクリプトの venv 環境構築（pandas/openpyxl 等の依存ライブラリ含む）（v1.12新設）	Code	システム Python 汚染回避。LaunchAgent ProgramArguments を `~/.claude/venv-XXXXX/bin/python` に指定（kudo-ai-error-watchlist 関連）
LaunchAgent cron 永続登録	Code	~/Library/LaunchAgents/ 書込権限
Google Drive 読み取り（search/fetch/get_metadata/download/create_file新規/copy）	Chat	drive_search 等 MCP 稼働中（Chat 在地）
Google Drive 既存ファイル書き込み（rename / update / move / patch）	Code（Mac ローカル `mv` 経由 + Drive for desktop 自動同期）	Chat の Drive MCP には書き込み系が存在しない（2026-05-15 発覚・kudo-ai-error-watchlist Entry #10）
WorkFlowy API操作（読み書き両方）	Cowork	workflowy MCPはCoworkでのみ稼働（§1-2 MCP層）
Webブラウザ自動化（10件未満・単発UI操作）	工藤さん手動＋手順書HTML	Cowork自動化のオーバーヘッドより速く安定（2026-05-15 NotebookLM事例）
Webブラウザ自動化（10件超＋認証維持必要＋反復構造一定）	Cowork	自動化のメリットがオーバーヘッドを上回る
議論を交えたSKILL.md / HTML起草	Chat	テキスト生成と対話の組み合わせが最速
表計算・データ整形	Chat	xlsx skill利用
認証セッション維持が必要な反復作業	Cowork	Chrome MCP稼働
conversation_search / WebSearch	Chat	ツール在地
scheduled-tasks（朝ブリーフ等）	Cowork	scheduled-tasks MCPはCoworkでのみ稼働
Slack DM／scheduled-tasks自己更新	Cowork	同上
Calendar / Gmail / Slack の書き込み系（メール送信・予定作成・update_event 等）	要 tool_search 個別確認	MCP 機能網羅性はサービスごと非対称。Drive MCP の轍を踏まない

重要原則（2026-05-15 追記・4つ）： 1. MCP の機能を仮定して判断マトリクスに書き込む前に、必ず tool_search で読み取り系と書き込み系の両方を実機確認（Entry #10） 2. Python スクリプトを HANDOFF で Code に渡す前に、必ず Chat 環境（Linux コンテナ）で bash_tool 経由で実機テストする（Entry #11）。FS 操作はモックフォルダで再現可能 3. 「○○ API操作」と単一カテゴリで書かない。読み取り／書き込みを必ず分離して明示 4. Python スクリプトの永続化は venv を必須化（v1.12 新設・2026-05-15 Code v3 reasonable assumption で実証）。理由：システム Python は pandas/openpyxl 等の依存ライブラリを持たない場合があり、依存ライブラリのインストールがシステム汚染になる。Code 側で ~/.claude/venv-XXXXX/ を作成し LaunchAgent ProgramArguments を venv の python に指定する運用が安全。今回の事例：~/.claude/venv-naming/（pandas 3.0.3 + openpyxl 3.1.5）

16-3-A. ★NEW★ HANDOFF 逸脱時の reasonable assumption 補正プロトコル（v1.12 新設）¶

起点：2026-05-15 Code v3 完了報告で 3 件の HANDOFF 逸脱が発覚（v0.5 ファイル不在 / pandas 未導入 / カラム名半角・全角）。Code Claude が作業を停止せず、reasonable assumption で補正＋報告することで全 Stage が完走した

プロトコル： 1. Code/Cowork 側が HANDOFF の前提と実態の差異を発見した場合、作業を止めずに以下を実施： - 補正の根拠（reasonable assumption の内容）を明示 - 補正の影響範囲を限定（本タスクのみ vs 永続的影響） - 完了報告に「HANDOFF からの逸脱（reasonable assumption での補正・N件）」セクションを追加 2. Chat 側は逸脱報告を受領したら： - 逸脱内容を kudo-ai-error-watchlist に Entry として永続化 - 関連 SKILL の HANDOFF テンプレを更新（次回再発防止） 3. 絶対補正禁止のもの： - 破壊的操作（rm -rf 等） - 意図しない他リソースへの波及 - 永続的なシステム改変（SIP 設定変更等）

これらは作業停止＋報告が原則

16-4. 判定例¶

「NotebookLM の20件改名やって」 → 反復UI操作10件超だが、1件あたり10秒で工藤さん手動なら3-5分。Cowork自動化は認証セッション維持＋セレクタ変動で5-30分ブレるため、工藤さん手動＋手順書HTMLが勝つ。
「Google Drive 200フォルダリネーム」 → Chat 不可（Drive MCP に rename ツール不在・Entry #10）。Code 一択：Mac ローカル ~/working/ で mv 実行 → Google Drive for desktop が自動同期。所要時間：mv コマンド数秒＋同期数分。
「Google Drive 検索して PowerPoint 一覧出して」 → Chat（search_files / google_drive_search が動く）。読み取り系は Chat で完結。
「validate_naming_consistency.py をcronに登録」 → ローカルFS書込＋LaunchAgent → Code一択。
「過去chatから命名揺れパターン抽出」 → conversation_search が動く → Chat。
「WorkFlowy #project ノードを全部リネーム」 → workflowy MCPはCoworkでのみ動く → Cowork一択。
「SKILL.md改訂案を全文出して」 → 議論型起草 → Chat（Code でも書けるが対話ループの遅さで負ける）。

16-5. 上書き伝達フォーマット¶

工藤さんから「○○でやって」と指定があった時、最速安定の観点で別環境が優位なら、即座に以下のフォーマットで上書き提案：

「了解です。ただし、最速・安定の観点で再評価すると、この作業は [推奨環境] の方が [N倍速い／安定] です。理由：[根拠1〜2行]。[推奨環境] で進めてよろしいですか？」

工藤さんが「いや、○○でやりたい」と再指定したら、その判断を尊重して指定通り実行する（上書き提案は1往復まで）。

16-6. 既存セクションとの関係¶

§1 環境差マップ：判断マトリクスの根拠データ。§16の判断は §1 を一次ソースとして参照する
§2 タスク振り分け判断マトリクス：軸A〜Dの判定基準。§16は §2 の機械的判定に「人間（工藤さん）が環境指定した場合の上書き機能」を追加
§7-1-a MCPツール可視性の非対称性：可視性差から推奨環境が決まる根拠
§13 HANDOFF配置先 SSOT：上書き提案で環境変更したらHANDOFF配置も変わる
§15 Cowork起草spec drift防止：Chat→Cowork間ハンドオフの安定化と精神を共有

16-7. 関連スキル¶

kudo-persist-settings — 個人設定項目14 から本セクションへ参照（kudo-cowork-code-handoff-protocol#environment-override）
kudo-ai-error-watchlist — 「自動受諾」によるアンチパターンを Entry として永続化

16-8. アンカーID¶

environment-override（個人設定項目14 からの参照解決用）

改訂履歴¶

v1.13（2026-05-15・集中原則ガバナンス Phase 3 Part B-2）：§13 HANDOFF配置先 SSOT を全面改訂し kudo-shared-storage-protocol v1.2 §5.5 および CLAUDE.md §3.1 の集中原則ガバナンスに統合。第一選択を ~/working/_claude_workspace_global/handoffs/HANDOFF-{phase}-{slug}-vN.md に統一。旧 SSOT（kudo-skill-sync/HANDOFF-TO-CODE-*.md ／ code-handoffs/YYYY-MM-DD_案件名/）は履歴保持のみ・新規追加禁止に変更（rm 禁止・移送ではなく停止運用）。命名規則表に新形式 HANDOFF-{phase}-{slug}-vN.md を追加、HANDOFF-TO-CODE-* / HANDOFF-FROM-CODE-* を「廃止」と明記。違反時の挙動表を集中原則違反パターン（Downloads/Desktop/案件越境）に対応するよう刷新。関連スキルに kudo-shared-storage-protocol §5.5 と CLAUDE.md §3.1、kudo-context-routing §1.3 二層ワークスペース規範 を追記。
v1.12（2026-05-15）：§16-3 判断マトリクスに「Python スクリプトの venv 環境構築 → Code」行を新設＋ §16-3-A HANDOFF 逸脱時の reasonable assumption 補正プロトコルを新設。2026-05-15 Code v3 完了報告で 3 件の HANDOFF 逸脱（v0.5 ファイル不在／pandas 未導入／カラム名半角・全角）が発覚し、Code Claude が ~/.claude/venv-naming/（pandas 3.0.3 + openpyxl 3.1.5）を自律的に作成して完走した実例を型化。重要原則を 3 から 4 へ拡張（④に venv 必須化原則を新設）。kudo-ai-error-watchlist Entry #14 と双方向参照。
v1.11（2026-05-15）：§16-3 判断マトリクスに「Python スクリプトのロジックテスト → Chat（Linux コンテナ）」行を新設。工藤さんから「codeとかコンピューターユーズとか使ったら、君の方で実装できそうじゃない？」と指摘を受け、Chat の手元（bash_tool で mkdir/python3 実行可能な Linux コンテナ）でスクリプトを実機テストできることに気づいた。validate_naming_consistency.py を Chat 環境内テストして v1→v2 のバグ（動的例外集合化漏れ）を Code に渡す前に発見・修正。重要原則を 2 から 3 へ拡張（②に Chat 実機テスト原則を新設）。kudo-ai-error-watchlist Entry #11 と双方向参照。
v1.10（2026-05-15）：§16-3 判断マトリクスの「Google Drive API操作 → Chat」を分割修正。Chat の Drive MCP には書き込み系（rename/update/move/patch）が存在しない事実が、命名統一プロジェクトの Phase 2 着手直前に発覚（tool_search で2回確認）。「Drive 読み取り → Chat」「Drive 既存ファイル書き込み → Code（Mac mv + Drive 同期）」に分離。同時に「MCP の機能を仮定する前に必ず tool_search で実機確認」を§16-3 末尾に重要原則として追記。判定例にも Drive リネーム vs Drive 検索の対比を追加。kudo-ai-error-watchlist Entry #10 と双方向参照。
v1.9（2026-05-15）：§16 環境指定の上書きプロトコル を新設。工藤さんからの「coworkで」「codeで」等の環境指定を自動受諾せず、最速・安定・副作用最小の3軸で再評価する規範を型化。判断マトリクス13行（GDrive/WorkFlowy/Webブラウザ自動化10件未満/script永続化/cron登録/scheduled-tasks 等）と判定例6件・上書き伝達フォーマット・既存セクションとの関係を内蔵。2026-05-15 命名統一プロジェクト初動での「NotebookLM Cowork自動化提案→手動手順書HTMLが圧勝」事例を起点に永続化。
v1.8（2026-05-08）：§15 Cowork起草spec drift防止＋二段監視構成パターン を新設。kudo-skill-cross-reference-resolver Stage 1〜7 完走時に HIGH 4件全件が Cowork 起草 spec の drift（記憶ベースで書いた heading が実体不一致）だった事例から「Cowork起草spec drift 防止プロトコル」を型化。同時に LaunchAgent（実行層）+ scheduled-tasks（監視層）の二段構成パターンを実証ケース（skill-ssot-monitor task）と共に内蔵。★H3確定（scheduled-tasks は prompt 実行型・script 実行型ではない）も明文化。
v1.7（2026-05-08）：§14 HANDOFF同梱物 vs 外部参照物の明示プロトコル を新設。Cowork起草HANDOFFが「同梱」と書いた本体ファイルが Code 実環境に不在で、Code Claude が Stage 1 着手前にブロッカー停止した実害から型化。HANDOFF.md冒頭に §0 ファイル配置マップ（同梱物／外部参照物の2カテゴリ分類・着手前検証チェックリスト）を必須化。「未来実体化」マークで Stage 順序による段階的実体化を許容。Code Claude の初動6ステップを規定。Cowork起草時の保存前チェックリスト6項目を内蔵。
v1.6（2026-05-07）：§7-1「片側の数字を疑う」原則を §7-1-a MCPツール可視性の非対称性パターン として拡張。Cowork/Code 同名MCPの応答スコープ非対称性を型化。2026-05-05 の scheduled-tasks 0件誤認＋2026-05-07 の同事象再演を実害事例として記録。HANDOFF/報告で使う文章テンプレートを内蔵。
v1.5（2026-05-07）：§13 HANDOFF配置先 SSOT を新設。Cowork↔Code 連携で生成される HANDOFF 文書（依頼／報告／中間フェーズ）の配置ルールを一次ソース化。Working中＝kudo-skill-sync/HANDOFF-*.md、完了後＝code-handoffs/YYYY-MM-DD_案件名/ の二段配置と命名規則・移送タイミング・違反検出・横展開メリットを完全規定。2026-05-05〜2026-05-07 の3案件（skill-recovery／skill-folder-unification／onedrive-migration）で HANDOFF 11本が3カ所に散在した実害を起点に新設。code-handoffs/README.md と二重持ち（README.md は人間用ナビ・本SSOTはClaude参照用）。
v1.4（2026-05-07）：§12「ハードウェア過剰でも重い Mac の診断パターン SSOT」を新設。Mac高速化／Excel/PPT 重さ／Chrome タブ過多系の依頼に対する初動3ステップ・Cowork×Code 分業表・Excel 解剖の数値テンプレート（unzip+grep+Python）・4Kディスプレイ仮説検証・成果物4点セットを内蔵。MacBook Pro M3 Pro/36GB+MateView 4K + 重いExcel（4_23課題.xlsx 124KB なのに固まる）案件から抽出。
v1.3（2026-05-07）：§11 に macOS／Code ガッチャ3件を追加。(11-6) File Provider 配下は Spotlight 非インデックス＝仕様 / (11-7) クラウド独自ゴミ箱 ≠ Mac ~/.Trash/ / (11-8) Code セッション再開時の旧cwd参照→完全リセット手順。Phase 6 検証＋Phase 5 後 Code 再起動トラブルから抽出。
v1.2（2026-05-07）：§11 に macOS 削除ガッチャ4件を追加。(11-2) File Provider拡張/サンドボックスコンテナの rm 保護→Finder経由 / (11-3) ACL deny delete→chmod -N で解除 / (11-4) Claude Code cwd 自動再登録→新セッションを~/working から起動 / (11-5) cwd削除で /private/tmp リセット。OneDrive→GDrive 全面アンリンク作業（2026-05-07 Phase 5）の Code 報告から抽出。
v1.1（2026-05-07）：§11「macOS 固有ガッチャ集 SSOT」を新設し、NFD/NFC Unicode 正規化問題を内蔵。Code が ~/.claude.json 内の日本語キー検索で発生した実害（2026-05-07 OneDrive→GDrive 移行作業）を起点に追加。kudo-persist-settings §ストレージ抽象化原則 SSOT v3.4 と並行。
v1.0（2026-05-05）：初版。48スキル＋17 scheduled-tasks 棚卸し案件の経験を完全型化。Cowork↔Code 4段ハンドオフ、staging→hostloop バイト整合検証、cloud→local 単方向同期の実証を内蔵。