コンテンツにスキップ
mild worksai-tools-kb

習熟マップ

facts は「これは何か」を書きます。ここは「使えていると言える状態」を書きます。各トピックに 3 つの段（触る / 入れる / 効かせる）があり、 それぞれに達成を確認する手段が付いています。

根拠は各ページが指す facts 1 件だけです。facts に書かれていないことは書けません （npm run lint:mastery が本文中のコマンド名・設定キーを照合します）。 どこまで登ったかは各自の手元（_meta/mastery-progress.json）に置き、 このサイトには載せません。

1. まず入れる13 トピック

  • Code タブの作業場所を組む

    Claude Codeデスクトップ限定
    1. 触るCmd+/ でショートカット一覧を出し、**Views** メニューから diff・terminal・file の各ペインを 1 回ずつ開いた
    2. 入れるチャット・diff・ターミナル・ファイルの配置を決めてあり、Ctrl + バッククォートでターミナルを開き、チャットのパスをクリックしてファイルペインで直せる
    3. 効かせるview mode を Normal / Verbose / Summary で切り替えて使い、ファイルパスの右クリックから **Attach as context** と **Copy path** を使っている

    根拠 claude-code/desktop ／ 前提なし

  • 対話セッションを手で操る

    Claude Code操作が異なる
    1. 触る空の入力で ? を押してヘルプパネルを出し、Ctrl+O の transcript viewer と ! の shell mode を 1 回ずつ使った
    2. 入れる自分のターミナルでの複数行入力の方法を 1 つ確定させ、Esc での中断と Shift+Tab でのモード切り替えを手が覚えている
    3. 効かせる会話を汚さずに済ませる手（/btw、Ctrl+B でのバックグラウンド化、Ctrl+R の履歴検索）を場面で使い分けている

    根拠 claude-code/interactive-mode ／ 前提なし

  • チェックポイントで巻き戻す

    Claude Codeターミナル限定
    1. 触る空のプロンプト入力で Esc を 2 回押して rewind メニューを開き、6 つのアクションを目で見た
    2. 入れる作業をやり直したい場面で Restore code と Restore conversation を使い分けている
    3. 効かせるrewind で戻せない変更（bash 経由・subagent・外部編集）を把握し、そこは git で守っている

    根拠 claude-code/checkpointing ／ 前提 interactive-mode

  • 起動オプションを持ち札にする

    Claude Codeターミナル限定
    1. 触るclaude doctor と claude auth status を実行し、claude -c で直前の会話を継続できることを確認した
    2. 入れる起動時に渡すフラグ（--model、--permission-mode、--add-dir など）を用途ごとに決めてある
    3. 効かせる不調の切り分けに --safe-mode と --bare を使い分け、--settings でこの起動限りの設定を差し込める

    根拠 claude-code/cli-reference ／ 前提 interactive-mode

  • コマンドを引き出しにする

    Claude Code操作が異なる
    1. 触る/help で一覧を出し、/status・/context・/usage を実行して今のセッションの状態を 3 方向から見た
    2. 入れる日常で回すコマンドを 8 個ほどに絞り、/clear と /compact、/resume と /branch を意識して使い分けている
    3. 効かせる同梱 skill（/code-review、/simplify、/verify、/doctor）と分岐系（/fork、/subtask、/background）を場面で選べる

    根拠 claude-code/commands ／ 前提 interactive-mode

  • コンテキストウィンドウを管理する

    Claude Code操作が異なる
    1. 触る作業中のセッションで /context を実行し、何がコンテキストを食っているかを内訳で見た
    2. 入れる自分の使い方に合わせて /autocompact の閾値を決め、/clear と /compact を使い分けている
    3. 効かせる大きな読み取りを subagent に逃がし、compaction で何が残り何が消えるかを踏まえて指示を配置している

    根拠 claude-code/context-window ／ 前提 interactive-mode

  • 差分を見てから通す

    Claude Codeデスクトップ限定
    1. 触る+12 -1 のような差分表示をクリックして diff ビューを開き、ファイル一覧と変更内容を目で見た
    2. 入れるdiff の行をクリックしてコメントを書き、Cmd+Enter でまとめて送って修正が新しい差分として返ることを確認した
    3. 効かせる**Review code** を実行して指摘を受け、PR を開いた後に CI ステータスバーの **Auto-fix** と **Auto-merge** を入れるか切るかを決めている

    根拠 claude-code/desktop ／ 前提 desktop-workspace

  • セッションを並べて回す

    Claude Codeデスクトップ限定
    1. 触るCmd+N で 2 つ目のセッションを作り、Ctrl+Tab で行き来した
    2. 入れるGit リポジトリでセッションごとに worktree が作られることを確認し、終わったセッションをアーカイブアイコンで片付けている
    3. 効かせるSettings → Claude Code で worktree の保存先とブランチ接頭辞を決め、**Auto-archive after PR merge or close** を入れるか切るかを選んである

    根拠 claude-code/desktop-sessions ／ 前提 desktop-workspace

  • CLAUDE.md と auto memory を使いこなす

    Claude Code両方で同じ
    1. 触るセッションを開き直し、/context の Memory files に自分が書いた CLAUDE.md が出ることを確認する
    2. 入れるプロジェクトの CLAUDE.md に、そのリポジトリでしか通じない規約だけが残っている（一般論が無い）
    3. 効かせる必ず守らせたい指示を CLAUDE.md から hook へ移し、/compact をまたいでも効くことを確認した

    根拠 claude-code/memory ／ 前提 interactive-mode

  • permission mode を選ぶ

    Claude Code操作が異なる
    1. 触るShift+Tab で default → acceptEdits → plan を一周し、ステータスバーの表示が変わることを見た
    2. 入れる調べもの・実装・危険な作業でどのモードから始めるかを決め、permissions.defaultMode か起動フラグで固定してある
    3. 効かせるモードでは緩められない境界（protected paths、deny ルール、会話で述べた境界）を説明でき、拒否されたときに /permissions の Recently denied から辿れる

    根拠 claude-code/permission-modes ／ 前提 interactive-mode

  • settings.json を層で使う

    Claude Code両方で同じ
    1. 触る/config で 1 項目を変え、/status の Setting sources 行にどの層が読み込まれているかを見た
    2. 入れるuser / project / local の 3 つに何を書くかを決め、チームに配る設定と自分だけの設定が別ファイルになっている
    3. 効かせる設定が効かないとき、優先順位と反映タイミングのどちらが原因かを /status と claude doctor で切り分けられる

    根拠 claude-code/settings ／ 前提 interactive-mode

  • モデルと effort を選び分ける

    Claude Code操作が異なる
    1. 触る/model のピッカーを開き、Enter（既定として保存）と s（このセッションのみ）の違いを実際に試した
    2. 入れる作業の種類ごとにモデルと effort level の組み合わせを決め、/effort か --effort で切り替えている
    3. 効かせるextended thinking・1M コンテキスト・fallback chain の要否を判断でき、モデルが勝手に変わったときに理由を説明できる

    根拠 claude-code/model-config ／ 前提 settings

  • コストの出どころを掴む

    Claude Code操作が異なる
    1. 触る/usage を開き、Session ブロックと（プラン利用なら）plan usage breakdown の内訳を d / w で切り替えて見た
    2. 入れる使用量を押し上げていた要因（長い履歴・未使用の MCP・thinking の水準）を 1 つ特定し、実際に減らす操作をした
    3. 効かせる上限に当たったときのメッセージの種類を読み分けられ、cache miss が起きる条件を踏まえて作業の区切り方を変えている

    根拠 claude-code/costs ／ 前提 model-config、context-window

2. 効いてくる20 トピック

  • ターミナルと併用する

    Claude Codeデスクトップ限定
    1. 触る同じプロジェクトで CLI と Desktop を同時に開き、片方で書いた CLAUDE.md がもう片方の新しいセッションにも効くことを確認した
    2. 入れるターミナルで /desktop を実行してセッションをデスクトップアプリへ移した
    3. 効かせるいつも渡すフラグの Desktop 側の相当を言えて、相当が無いもの（--print、--allowedTools）をどちらで回すか決めてある

    根拠 claude-code/desktop-vs-cli ／ 前提なし

  • アプリを見ながら直させる

    Claude Codeデスクトップ限定
    1. 触るClaude にアプリを起動させて Browser ペインで開き、Cmd+Shift+B で開閉した
    2. 入れる.claude/launch.json を自分の dev サーバーに合わせて直し、その設定でサーバーが起動することを確認した
    3. 効かせる外部サイトでの操作に **Allow once** と **Always allow** のどちらを選ぶか基準があり、autoVerify を入れるか切るかを決めてある

    根拠 claude-code/desktop-browser ／ 前提 desktop-workspace

  • 脇道とセッション間をつなぐ

    Claude Codeデスクトップ限定
    1. 触るCmd+; または /btw で side chat を開き、メインの会話に何も残らないことを確認した
    2. 入れるtasks ペインを開いて subagent とバックグラウンドコマンドを一覧し、そこから出力を読むか止めるかを実際に行った
    3. 効かせる他のセッションの状況を Claude に尋ねて答えが返ることを確認し、この面から見えないもの（cloud セッション、ターミナル CLI のセッション）を言える

    根拠 claude-code/desktop-sessions ／ 前提 desktop-sessions

  • 実行場所を選ぶ

    Claude Codeデスクトップ限定
    1. 触る環境ドロップダウンを開き、Local / Cloud / SSH（Windows では WSL）が並ぶことを見た
    2. 入れる**Local** の歯車から local environment editor を開き、dev サーバーにも渡したい変数をそこに置いた
    3. 効かせる重い作業を Cloud、リモートのコードベースを SSH、Linux 前提のリポジトリを WSL に振り分けていて、各環境で使えない機能を言える

    根拠 claude-code/desktop-environments ／ 前提 desktop-sessions

  • 環境変数で挙動を変える

    Claude Code操作が異なる
    1. 触る環境変数を 1 つ（API_TIMEOUT_MS など）シェルで設定して起動し、挙動が変わることを確認した
    2. 入れる恒常的に効かせたい変数を settings.json の env に移し、どのスコープのファイルに置くかを決めてある
    3. 効かせる環境変数・settings キー・CLI フラグの優先順位を機能ごとに確認でき、効かないときにどれが勝っているか特定できる

    根拠 claude-code/env-vars ／ 前提 settings

  • output style で応答の型を決める

    Claude Code両方で同じ
    1. 触る/config の **Output style** で Explanatory か Learning に切り替え、/clear 後に応答の形が変わることを見た
    2. 入れる毎ターン指示し直していた役割・トーン・出力形式を 1 つカスタム output style にして常用している
    3. 効かせるoutput style と CLAUDE.md・--append-system-prompt・skill の使い分けを説明でき、keep-coding-instructions の要否を判断できる

    根拠 claude-code/output-styles ／ 前提 settings

  • permission ルールを書く

    Claude Code両方で同じ
    1. 触る/permissions を開いて現在のルールと、それぞれの出所となる settings.json を一覧した
    2. 入れる毎回聞かれて煩わしい操作に allow ルールを、触られたくない場所に deny ルールを書き、意図どおり効くことを確認した
    3. 効かせるdeny → ask → allow の評価順とパスパターンの解決先を踏まえ、ルールが効かないときに原因を特定できる

    根拠 claude-code/permissions ／ 前提 permission-modes、settings

  • skill を書いて手順を残す

    Claude Code両方で同じ
    1. 触る.claude/skills/<name>/SKILL.md を 1 つ作り、/<name> で呼び出せることと /skills に出ることを確認した
    2. 入れる繰り返す手順を skill にして、description から Claude が自動で呼ぶ場面と自分で呼ぶ場面が分かれている
    3. 効かせる呼び出し制御（disable-model-invocation / user-invocable）と context: fork を用途で選べ、一覧のコンテキストコストを /doctor で見ている

    根拠 claude-code/skills ／ 前提 memory

  • ステータスラインに状態を出す

    Claude Codeターミナル限定
    1. 触る/statusline に自然言語で指示してステータスラインを 1 つ作り、実際に表示されることを確認した
    2. 入れる常に見えていてほしい情報（モデル・ディレクトリ・コンテキスト使用率など）を選んで、自分のステータスラインに出している
    3. 効かせる再実行のタイミングと stdin の JSON フィールドを把握し、必要なら refreshInterval を足して自分でスクリプトを書ける

    根拠 claude-code/statusline ／ 前提 settings

  • 不調を切り分ける

    Claude Code操作が異なる
    1. 触る/doctor を一度実行し、インストール・設定・拡張・コンテキスト使用量の点検結果を読んだ
    2. 入れる症状から見るべき場所（/doctor / /mcp / claude doctor）を選べ、claude --safe-mode で自分の設定が原因かを切り分けられる
    3. 効かせる重い・止まる・検索が当たらないときの手当てを順番に試せ、報告する場合に何を添えるべきかを挙げられる

    根拠 claude-code/troubleshooting ／ 前提 cli-reference

  • worktree でセッションを分ける

    Claude Code操作が異なる
    1. 触るclaude --worktree <name> で分離セッションを起動し、.claude/worktrees/<name>/ が作られたことを確認した
    2. 入れる並行して進めたい作業を worktree に分け、終了時の後片付け（保持するか削除するか）を毎回選べている
    3. 効かせるbase branch の決まり方と分離の強制範囲を把握し、.worktreeinclude や isolation: worktree を必要に応じて使える

    根拠 claude-code/worktrees ／ 前提 cli-reference

  • 定期実行に載せる

    Claude Codeデスクトップ限定
    1. 触るサイドバーの **Routines** から **New routine** → **Local** でタスクを 1 つ作り、**Run now** で実行してサイドバーの **Scheduled** に出ることを見た
    2. 入れる**Run now** の実行中に出た確認で always-allow を選び、隔離した worktree で走らせるかどうかをタスクごとに決めてある
    3. 効かせるスリープで実行が飛ぶこと、取りこぼしの追いかけが 1 回だけであることを踏まえ、時刻の前提をプロンプト本文に書いてある

    根拠 claude-code/desktop-scheduled-tasks ／ 前提 desktop-sessions、permissions

  • 非対話実行を仕事にする

    Claude Codeターミナル限定
    1. 触るclaude -p "..." を実行し、パイプで入力を渡した場合の出力と終了コードを確認した
    2. 入れる繰り返す作業を -p のコマンドにして、--allowedTools か permission mode で止まらずに完走する形にした
    3. 効かせる--output-format json と --json-schema で結果を機械可読にし、失敗が stdout に混ざる経路を踏まえた検査を入れている

    根拠 claude-code/headless ／ 前提 cli-reference、permissions

  • hook で仕組みにする

    Claude Code両方で同じ
    1. 触るSessionStart か PostToolUse の command hook を 1 つ書き、/hooks に出ることと実際に発火することを確認した
    2. 入れる毎回言わないと守られない規約を 1 つ hook に移し、matcher と if で対象を絞ってある
    3. 効かせる終了コード 0 / 2 と JSON 出力の使い分けを説明でき、hook が動かないときデバッグログで一致状況を追える

    根拠 claude-code/hooks ／ 前提 settings、permissions

  • MCP サーバーを繋ぐ

    Claude Code操作が異なる
    1. 触るclaude mcp add --transport http <name> <url> でサーバーを 1 つ足し、claude mcp list が ✔ Connected を返した
    2. 入れる常用するサーバーをスコープ（local / project / user）を選んで登録し、使わないものは /mcp で無効にしてある
    3. 効かせるtool search とタイムアウトの効き方を踏まえ、接続失敗や呼び出しが返らないときに claude mcp get <name> の詳細から切り分けられる

    根拠 claude-code/mcp ／ 前提 permissions

  • sandbox で境界を引く

    Claude Code両方で同じ
    1. 触る/sandbox パネルを開き、Mode / Overrides / Config（Linux では Dependencies）の各タブを確認した
    2. 入れる自分の環境でサンドボックスを有効にし、作業に必要な書き込み先とドメインを allowlist に足して常用できている
    3. 効かせるfilesystem と network の 2 層の効き方を説明でき、非互換なコマンドを excludedCommands に逃がす判断ができる

    根拠 claude-code/sandboxing ／ 前提 permissions

  • 組み込みツールの癖を知る

    Claude Code両方で同じ
    1. 触る自分のセッションで使えるツール名を Claude に尋ねて確認し、MCP の正確なツール名を /mcp で見た
    2. 入れるpermission ルールを書くとき、ツールごとに受け付ける specifier の形（Bash(...) / Read(...) / Edit(...) など）を見て書いている
    3. 効かせるBash の出力上限と cwd の引き継ぎ、Edit の 3 つのチェックを把握し、ツールが失敗したときに原因を切り分けられる

    根拠 claude-code/tools-reference ／ 前提 permissions

  • plugin にまとめて配る

    Claude Code操作が異なる
    1. 触るclaude --plugin-dir ./my-plugin でインストールせずに読み込み、/plugin-name:skill-name が呼べることを確認した
    2. 入れる複数プロジェクトで使い回している skill / agent / hook を 1 つの plugin にまとめ、/reload-plugins で反映を確認した
    3. 効かせるstandalone と plugin の使い分けを説明でき、移行時に元ファイルとの衝突が起きる箇所を挙げられる

    根拠 claude-code/plugins ／ 前提 skills、commands、hooks

  • 安全側に倒して使う

    Claude Code両方で同じ
    1. 触る/permissions で今の設定を一度監査し、既定では read-only から始まることを自分の目で確かめた
    2. 入れる信頼できないコンテンツを扱う作業の手順（レビューしてから承認、VM 内で実行）を決めて守っている
    3. 効かせるprompt injection に対する保護がどこまでで、どこからが自分の運用の責任かを説明できる

    根拠 claude-code/security ／ 前提 permissions、sandboxing

  • subagent に仕事を分ける

    Claude Code両方で同じ
    1. 触る調査を Explore に委譲させ、メイン会話に返るのが要約だけであることを /tasks と結果表示で見た
    2. 入れる.claude/agents/ に自分用の subagent を 1 つ置き、@agent-<name> で確実に呼べる状態にした
    3. 効かせるツールの 2 段フィルタ・permission の継承・バックグラウンド実行の挙動を踏まえて、委譲する仕事を選べる

    根拠 claude-code/sub-agents ／ 前提 tools-reference

3. 必要になったら10 トピック

  • Agent SDK を選ぶ

    Claude Code両方で同じ
    1. 触るPython か TypeScript の SDK を入れて、1 回のクエリを自分のプロセスから実行できた
    2. 入れる自分のアプリに組み込み、.claude/ の skill・command・memory が自動で読み込まれることを確認した
    3. 効かせるAgent SDK / CLI / Client SDK / Managed Agents の 4 択から、目的に合うものを理由付きで選べる

    根拠 claude-code/agent-sdk ／ 前提 headless

  • 自前のツールを渡す

    Claude Code両方で同じ
    1. 触る自前の関数を 1 つツールとして定義し、Claude に呼ばせて結果が返ることを確認した
    2. 入れる実務で使う API やデータベースをツールにして、description を読んだ Claude が意図した場面で呼ぶようになった
    3. 効かせるreadOnlyHint と isError、structuredContent を使い分け、失敗時に Claude が読む文面を自分で組んでいる

    根拠 claude-code/agent-sdk-custom-tools ／ 前提 agent-sdk

  • agent loop の 1 周を掴む

    Claude Code両方で同じ
    1. 触る1 回の実行で流れてくるメッセージを全部そのまま出力し、SystemMessage から ResultMessage までの並びを見た
    2. 入れるメッセージ型で分岐する処理を書き、ResultMessage の subtype で成功と上限到達を区別している
    3. 効かせるmax_turns と max_budget_usd の効き方を踏まえて上限を設計し、ストリームを最後まで反復する実装にしている

    根拠 claude-code/agent-sdk-loop ／ 前提 agent-sdk

  • SDK でツール使用を絞る

    Claude Code両方で同じ
    1. 触るallowed_tools と disallowed_tools を渡して実行し、拒否されたツールの挙動を確認した
    2. 入れる用途に合うパーミッションモードを選び、未解決のツールを canUseTool コールバックで処理している
    3. 効かせるhooks → deny → ask → mode → allow → canUseTool の評価順に沿って、意図した箇所で止まる構成にできる

    根拠 claude-code/agent-sdk-permissions ／ 前提 agent-sdk、permissions

  • Python SDK を使う

    Claude Code両方で同じ
    1. 触る仮想環境に claude-agent-sdk を入れ、query() でメッセージを非同期イテレータとして受け取れた
    2. 入れる単発なら query()、継続する会話なら ClaudeSDKClient と、用途で選び分けている
    3. 効かせるResultMessage の subtype と model_usage を読み、interrupt() 後のバッファ処理まで含めて実装できる

    根拠 claude-code/agent-sdk-python ／ 前提 agent-sdk

  • SDK から subagent を定義する

    Claude Code両方で同じ
    1. 触るquery() の agents オプションに AgentDefinition を 1 つ渡し、Claude がそれを起動するところまで確認した
    2. 入れる用途ごとに description と prompt を書き分け、tools と model を絞った subagent を運用している
    3. 効かせるコンテキスト継承の範囲とバックグラウンド実行の既定を踏まえ、必要なら session_id と agent ID で再開できる

    根拠 claude-code/agent-sdk-subagents ／ 前提 agent-sdk

  • TypeScript SDK を使う

    Claude Code両方で同じ
    1. 触る@anthropic-ai/claude-agent-sdk を入れ、query() の返すストリームを最後まで受け取れた
    2. 入れるOptions で必要なものだけを設定し、allowedTools が制限ではなく自動承認であることを踏まえた構成にした
    3. 効かせる起動時間や配布形態（startup()、Bun へのコンパイル、バイナリ解決）の問題に自分で対処できる

    根拠 claude-code/agent-sdk-typescript ／ 前提 agent-sdk

  • 画面を操作させる

    Claude Codeデスクトップ限定
    1. 触る**Settings > General** の **Computer use** トグルの場所を開き、自分のプランと OS で使えるかどうかを確かめた
    2. 入れる有効にしてアプリを 1 つ承認し、確認画面に出る階層（View only / Click only / Full control）が固定であることを見た
    3. 効かせるconnector → Bash → Chrome → iOS Simulator → computer use の順で試されることを言えて、**Denied apps** に触らせたくないアプリを登録してある

    根拠 claude-code/desktop-computer-use ／ 前提 security

  • エージェントを安全に配置する

    Claude Code両方で同じ
    1. 触る自分のデプロイ先で、エージェントがどの分離技術の内側にいるか（sandbox / コンテナ / gVisor / VM）を言える
    2. 入れる最小権限でファイルシステムとネットワークを絞り、機密ファイルをマウント対象から外した
    3. 効かせる認証情報をプロキシ経由で注入する形にし、分離とプロキシそれぞれの限界を挙げられる

    根拠 claude-code/agent-sdk-secure-deployment ／ 前提 agent-sdk-permissions、security

  • ユーザーへの確認を受け止める

    Claude Code両方で同じ
    1. 触るcanUseTool コールバックを実装し、未解決のツール呼び出しで実際に呼ばれることを確認した
    2. 入れる許可・拒否のレスポンスを正しい形で返し、拒否時の message が次の行動に効いていることを確認した
    3. 効かせるAskUserQuestion の扱いと updatedPermissions によるルール保存を含めて、承認フローを自分のアプリに載せられる

    根拠 claude-code/agent-sdk-user-input ／ 前提 agent-sdk-permissions