novice — 非開発者向けの Claude Code プラグイン

実際にやることは三つだ

非開発者が Claude Code を初めて開くと、三か所で止まる。答えに出てくる用語が分からない。答えが長すぎて何から手を付ければよいか分からない。そしてコマンドをターミナルに貼る瞬間、何かが取り返しのつかないことになるのではないかと手が止まる。novice はこの三つを別々の層で扱う。

学習層は用語を扱う。commit や branch といった語をやさしい言葉に置き換えず、そのまま書いて括弧で意味を添える。そして同じ用語がそのセッションで十分に出たら、説明を静かに外す。最初は毎回付いてきた括弧が、あるときから消えている、という具合だ。

focus は答えの形を扱う。入れると一行目がそのまま実行できるコマンドやパスになり、二段階以上は番号付きリストになり、前置きと結びが禁止される。レベルとは別のスイッチなので、novice を off にしても focus はそのまま動く。

安全ゲートはコマンドを扱う。ただし脅かす方向ではなく逆だ。確実に破壊的で取り返しがつかないものだけを止め、それ以外は判定そのものをしない。なぜそう作ったかは後で別に書いた。

ここに外部サービス CLI のブートストラップが加わる。Vercel や GitHub CLI を入れてログインする過程を、段階ごとに承認を取りながら代わりに踏む。ただし境界は明確だ。アカウントを作り、値を入力し、デプロイするのは利用者自身が行う。

導入 — marketplace と npm の二経路

推奨は marketplace だ。Claude Code を起動した状態で、下の三行を順に入力する。ターミナルではなく Claude Code の中で打つコマンドである。

/plugin marketplace add hjsh200219/novice
/plugin install novice@novice
/reload-plugins

入ったかの確認と、あとで更新する方法

確認は二段階だ。`/plugin` の一覧で novice が enabled になっているかを見て、`/novice` を実行して状態ダッシュボードが出れば正常である。ダッシュボードには現在のレベル、学習層の状態、安全ゲートが動いているか、mute の一覧が一緒に出る。

ここに誰もが一度は引っかかる落とし穴がある。入るのは原本ではなくキャッシュされた複製なので、自動では更新されない。新しい版が出ても古い版が静かに動き続ける。`/plugin` メニューで novice の marketplace を update したうえで、プラグインを入れ直す必要がある。

削除は `/plugin uninstall novice` だ。削除すると学習層だけでなく安全ゲートも一緒に消える。always-on という言い方は、プラグインが有効な間だけ意味を持つ。

GitHub の短縮形の代わりに git URL やローカルのクローンパスでも、同じコマンドで登録できる。`/plugin marketplace add https://github.com/hjsh200219/novice.git` のように書く。

npm で入れる経路 — 同じプラグイン、別の配送

novice は npm にも `claude-novice` という名前で公開されている。marketplace 側とバージョンが揃って上がる別チャネルだ。marketplace の導入が GitHub リポジトリのツリーから取るのに対し、こちらは npm レジストリから取る。プロキシやファイアウォールで GitHub へのアクセスが塞がれている環境や、CI イメージのように npm がすでに標準の配送手段になっている環境で使う経路である。

いちばん単純な形は、グローバルに入れてからセッションへ直接読み込ませることだ。これらはターミナルで打つコマンドで、Claude Code の中ではない。

npm install -g claude-novice
claude --plugin-dir "$(npm root -g)/claude-novice"

{
  "name": "novice",
  "source": { "source": "npm", "package": "claude-novice" }
}

二つの経路のどちらを選ぶか

個人の環境なら marketplace の三行がいちばん短い。Claude Code の外に出る必要がなく、npm や Node のバージョンを気にする必要もない。

npm 経路は二つの場合に使う。GitHub への直接アクセスが塞がれている環境と、バージョンを固定したい場合だ。自前 marketplace の項目の source に `version` を書けば、最新追従ではなくその版に留まる。コンテナや CI にあらかじめ仕込む必要があるなら、`CLAUDE_CODE_PLUGIN_SEED_DIR` でイメージのビルド時にプラグインのキャッシュを埋めておくこともできる。

入れずに今回のセッションだけ試したい場合は `claude --plugin-dir <クローンパス>` がある。セッションが終われば消える。ホストされた ZIP を一度だけ試すなら `claude --plugin-url <ZIP の URL>` を使う。

してはいけないことが一つある。スキルのファイルだけを手で `~/.claude/skills/` へコピーするやり方は対応していない。そうするとスキルは読み込まれるが hook が読み込まれないため、安全ゲートも学習層も動かない。入っているように見えて実際には何の保護もない状態になる。

チームに配るとき — メンバーはコマンドを覚えなくてよい

非開発者のメンバーに `/plugin` コマンドを教えること自体が、すでに入口の壁だ。そこで別の経路がある。作業リポジトリの `.claude/settings.json` に次を commit しておくと、そのリポジトリを信頼した人に対して Claude Code が novice の導入を自分から提案する。

{
  "extraKnownMarketplaces": {
    "novice": { "source": { "source": "github", "repo": "hjsh200219/novice" } }
  },
  "enabledPlugins": { "novice@novice": true }
}

用語をやさしい言葉に置き換えない理由

入門者向けの道具がよく取る道は、難しい言葉をなくすことだ。commit を保存と呼び、branch を写しと呼べば、その場は楽になる。問題はその人が検索を始めた瞬間に来る。保存では何も出てこない。

novice は逆に進む。本物の用語をそのまま書き、その後ろに意味を添える。下が実際に出てくる形だ。

commit（現在の変更を一つの保存地点として記録すること）完了 — 3 ファイルを記録。

レベル 1・2・3・off — 説明がどこまで付いてくるか

レベルが決めるのは説明の量ではなく、説明がいつ外れるかだ。既定は 1 で、`/novice:mode 2` のように変える。プロンプト全体がちょうど `novice 2` のときも同じ動きをする。

off は学習層だけを切る。口調も説明も可視化も消えるが、安全ゲートはそのまま動く。ここは設定でも切れないようになっている。プラグイン設定の `novice_enabled` を切ってもゲートは動き続ける。

mute と reset — どこまでがセッションで、どこからがプロジェクトか

すでに知っている用語にまで説明が付けば、それはもう雑音だ。だから用語ごとに切り替える命令がある。プロンプト全体がちょうどその形のときだけ働き、前後の空白と句点一つまでしか許さない。もっと簡単に説明して、のような一般の文はその回の答えにだけ効き、設定は変えない。

reset と mute は向きが逆だ。reset はカウンタを 0 に戻して再び N 回説明させ、mute は今すぐ説明を止めて止めたままにする。

保存の範囲も違う。mute はプロジェクト単位で保存されセッションをまたいで残り、reset と用語カウンタはセッションの範囲だ。用語は韓国語の別名でも指定でき、`novice mute 커밋` も同じ意味になる。辞書にない用語はそのまま無視される。

focus — 答えが長くなるときに入れる形の規則

0.4.0 で付いたダイヤルだ。`/novice:focus on` で入れる。答えが長く正確なのに、それでも何から手を付ければよいか分からない状況を狙っている。

入れると規則が十個強制される。一行目はそのまま実行できる行動かコマンドかパスでなければならず、背景はその後ろに回る。二段階以上なら番号付きリストになり、一項目には一動作だけを入れる。残っている作業があれば、末尾に二分以内でできる次の一手が付く。脇道は抑えられ、二つ目の論点は一つ目を終えてから別に出る。そして毎ターン現在の状態を書き直す。五段階のうち三段階完了、という具合だ。

残りの五つは、時間の見積もりを具体的な単位で出すこと、終わった作業は今何ができるようになったかで見せること、エラーは淡々と原因と直し方だけ書くこと、リストは五つを上限にすること、前置きと事後要約と結びを禁じることだ。よい質問ですで始まり、お役に立てば幸いですで終わる回答が消える。

規則には例外が六つ、文書として書き込まれている。説明してほしいという要求には十分に長く書く。破壊的な作業の前には先に確認する。三ターン続けてまだ直りませんが続いたらコードの修正を止め、間違っているかもしれない前提を名指しする。規則が答えそのものを消してしまう場合は答えが勝つ。選択肢は何かという問いに一つの道だけを出すのは、規則を守ったのではなく答えていないということだ。

focus はレベルとは別のダイヤルだ。`novice off` の状態でも動き、focus を切ってもレベルの指示は残る。二つがぶつかれば focus が勝つが、用語の括弧併記だけは例外として残る。`commit(…)` は前置きではなくインラインだからだ。すべてのプロジェクトで既定で入れておきたければ、プラグイン設定の `focus_default` を true にすればよく、プロジェクトごとの `/novice:focus off` のほうが優先される。

規則の体系そのものは新しく作ったものではなく、ayghri/i-have-adhd（MIT）から取って韓国語に移したものだ。原典は ADHD の読者に向けて書かれているが、その条件は入門者が長い答えの前で置かれる状況と重なる。作業記憶が狭く、知っていることと実際にやることの間の隙間で作業が死に、始めることがいちばん難しいという条件である。

安全ゲートは、止めるものと止めないものを分けて書く

ここがこのプラグインでいちばん慎重に書かれた場所だ。安全機能は大げさに言いやすく、大げさに言われた安全機能はない方がましになる。だから README にも明示的な非保証の節が別にあり、ここにも同じ内容を写す。

ゲートは最小の deny-only な中核だ。積極的に識別できた破壊的で不可逆な作業と、露出した秘密情報の値だけを止める。解析できないか曖昧なコマンドは判定せず、Claude Code 自身の権限プロンプトに渡す。

なぜ確認の問いかけを外したか

最初の版には確認の段があった。曖昧なコマンドなら本当に実行するかを尋ねる層だ。常識的には安全に見える。

実際は逆に行った。ゲートはパイプや `&&` のような文法を解釈しないので、`find . | sort` や `npm run build && npm test` のような何の問題もないコマンドのたびに確認が出た。確認が出続けると、人は読まずに押す。すると本当に危ない瞬間にも読まずに押す。警報が多くて警報を無視するようになれば、その安全装置は安全を削っている。

そこで 0.2.0 で確認の段をまるごと外した。今は確実なものだけを止め、曖昧なら意見そのものを出さない。代わりに Claude Code 自身の権限規則がその場所を担う。この選択には明記された代償がある。パイプを含む破壊的コマンドは novice が捕まえない。捕まえないという事実を文書に書いておく方が、捕まえるふりをするよりよいと考えた。

ほかにも保証しないことを文書に書いた。汎用のシェルパーサではなく、完全な DLP でも秘密情報の管理者でも悪意ある MCP への防御でもなく、既知のパターンに基づいてのみ検出する。利用者が全リスクを引き受けた `bypassPermissions` モードでは、ゲートは完全に退く。Git は追跡中のローカルファイルだけを守るので、追跡されていないファイルや外部の DB やデプロイ済みの資源は復旧の対象にならない。

外部サービスはどこまで代わりにやるか

入門者が実際にいちばん長く止まるのはコードではなく、アカウントと CLI だ。Vercel に配るには CLI を入れなければならず、それを入れるにはパッケージマネージャを知らなければならず、ログインにはブラウザとターミナルを行き来しなければならない。novice はこの区間を状態機械として踏む。

自動化の境界は一行に固定されている。検出、インストール、ログインの実行、認証状態の確認までだ。その先はやらない。資源を作って接続し、env や秘密情報の値を入れ、デプロイし、支払い、規約に同意することは、何をなぜどのコマンドで行うかを段階ごとに案内したうえで、利用者自身が実行する。

CLI は二段に分かれる。Tier 1 はあらかじめ検討してリポジトリに同梱した manifest で、現在は Vercel と GitHub CLI と Supabase の三つだ。インストールとログインをそれぞれ一度ずつ承認してもらい、固定されたパッケージ座標で進む。Tier 2 はそれ以外のすべての CLI だ。公式ドキュメントの URL とパッケージ座標と実際に実行するコマンド行を画面にそのまま示し、利用者が根拠を確かめて承認した場合にのみ同じエンジンで進む。公式の出所を確認できなければ、案内だけの手動経路へ下げる。

CLI のインストールを断ったり事前確認が失敗したりすると、経路が一段ずつ下がる。CLI から公式・同意済みの MCP へ、そこから目に見える Chrome の操作へ、最後は案内だけの手動だ。MCP は二つの場合にだけ使う。あらかじめ検討された allowlist の項目か、利用者がすでに Claude に登録したサーバに対し今回の作業に限って明示的に同意した場合である。既定の allowlist は空で、MCP サーバを自動で入れることはない。

資格情報の値は、どの経路でも要求・保管・転送・自動入力しない。安全な保管に対応した CLI が平文保存に落ちる環境では自動ログインをそもそも中止し、ファイル保存が公式の既定動作である CLI は、保存場所とログアウト経路をログイン承認の前に先に告知する。

何がどこに残り、何を外に出さないか

状態は `CLAUDE_PLUGIN_DATA` の下にだけ保存される。プラグインが入っているフォルダには何も書かない。保存されるのはプロジェクトごとの設定と、セッションごとの用語カウンタだ。

状態ファイルは atomic write で書き、権限は 0600、シンボリックリンクは拒否し、大きさの上限がある。セッションの状態は `/clear` のときに削除され、30 日で期限切れになる。

秘密情報のスキャナは候補のバイト列をメモリ上でのみ検査し、原文をログや状態ファイルや指標に残さない。ブートストラップの監査記録には、サービス ID と manifest のリビジョンと段階と終了状態だけが残る。

リモートの telemetry を送らない。このプラグインはサーバも cron もデプロイ基盤も持っていない。

今の状態と、まだ検証されていないこと

現在は 0.4.0 だ。実行時の外部依存はゼロ、Node は 18 以上、テストは 195 件が通る。最小の対応ランタイムは Claude Code 2.1.215 である。

安全ゲートはテストだけで終わらせず、mutation のハーネスでも検証する。危険なコマンド 35 件を 106 個の変異に変えて、検出をすり抜ける経路がないかを確かめる。遅延も回帰テストとして縛られている。利用者の入力を止める hook なので、p95 の予算が UserPromptSubmit で 300 ミリ秒、PreToolUse で 250 ミリ秒に強制されている。focus には別の eval ハーネスがあり、16 件のケースと 13 種の決定的な形の検査を回す。

コードでは検証できず残るものも書いておく。実際の CLI のインストールとログインの全区間は利用者の環境とアカウントが要り、破壊的な MCP のペイロードは画面なしでは再現できず、そして何より、人が本当に詰まらなくなるかは参加者がいて初めて測れる。今はチームの中で先に使いながら、引っかかる箇所を集めている段階だ。

だからこの記事は完成品の発表というより共有に近い。非開発者に Claude Code を渡す場面がある方なら、先に使ってみてどこで詰まったかを教えてもらうのが、今の段階ではいちばん役に立つ。

原典（MIT）: github.com/hjsh200219/novice · npm: claude-novice