AI
AI エージェントの設計と運用、モデルの使い分け、実装して分かったことをまとめています。
コーディングエージェントのhooksを共通のプロトコルに寄せる
社内で試験的に開発中のターミナルアプリで、Claude Code・Codex CLI・OpenCode・Grok Build の 4 つがタブの状態(実行中・承認待ち・完了・失敗)をどこまで自分から知らせてくるかを、生の PTY バイト列と各 CLI の hooks で測りました。ターミナルに流れてくるシグナルだけで 4 状態が揃う CLI は 1 つもなく、揃えるには CLI ごとの hooks を 1 つのプロトコルに変換するしかありませんでした。2026 年 9 月時点のバージョンでの結果です。
PrefectのSecretブロックは暗号鍵の管理で注意していること
Prefect の Secret ブロックは、環境変数で鍵を渡さない限り、暗号化に使う Fernet 鍵を暗号文と同じ SQLite に平文で書きます。ドキュメントには「保存時に暗号化される」としかありません。ソースと実機で確かめた内容と、社内の自動化基盤で AI エージェント用の資格情報を置くときに決めた 2 つのルールを書きます。
git restoreがgit reset --hardの抜け道になっていたので、askで塞いだ
claude-bash-guardに、破壊的だが正当な理由で使うこともあるgit操作をask判定で5本追加しました。git reset --hardを止めるdenyメッセージ自身が代替として勧めていたgit restoreに、実はガードが掛かっていなかったという発見と、git checkoutを対象から外した理由を書きます。
ルールを増やす前に、ガードの迂回経路を塞いだ
gh向けのルールを積む前に、claude-bash-guard自体のコマンド解釈層に5つの迂回経路が見つかりました。モデルの素直な迂回を防げるかと、敵の難読化まで見抜く必要があるかという2軸に沿って3件を塞ぎ、2件は見送っています。実装の途中で見つかったコメント除去とlocalhost判定の既存バグ2件も書きます。
Bash実行ガードのテストに変異チェッカを足す
claude-bash-guardのテストスイートに、ソース文字列を1つずつ壊した変異体を作りテストが落ちるか確かめる変異チェッカを新設しました。テストが通ることとテストが効いていることは別だという前提のもと、実際に見つかった2つの穴と、あえてCIには組み込まなかった判断を書きます。
gh apiが全ルールの抜け道だったので、ホスト判定に割り切る
Claude CodeのBash実行ガードにghコマンドのルールを追加したところ、gh apiが全ルールの抜け道になることが分かりました。メソッド推論による判定案を検討したものの、最終的にはgithub.com以外のホストだけを見る形に単純化しています。実データに当てて見つかった3件の誤検知も書きます。
自社スキルにプロンプト監査をかける
Claude Fable 5 向けのプロンプト監査を社内標準のスキルとエージェントに当てた記録です。指示が丸ごと削られることを警戒して後回しにしていましたが、削除対象になったのは古いモデル向けに強い言い方をしていた文だけでした。
SKILL.md に必須の参照ファイルを注入する
SKILL.md に「この参照を読むこと」と書いても、読むかどうかはモデルの裁量です。毎回必要な参照は動的コンテキスト注入で本文に埋め込む形へ切り替えました。公式ドキュメントの記述、報告されている類似の症状、プラグインで配ったときの挙動を並べます。
AIは眠らない
Claude Code のメモリ機能を無効にしています。機能を否定しているのではなく、私の利用量では使うほうのコストが上回るためです。人間の睡眠が記憶に対して何をしているかを一次資料で確かめ、エージェント側に何が入っていないのかを並べました。
Bash実行ガードにask判定を追加する
Claude CodeのBash実行ガードはdenyしか返せず、破壊的だが正当な理由のある操作の置き場がありませんでした。Ruleにdecisionフィールドを足してask判定を追加し、メッセージの長さをdenyはモデルが読む詳しい説明に、askはユーザーが読む一文に分けています。実装の過程で見つかったテストの穴も書きます。
沈黙は語らない
「誰も何も言わない」を問題なしと読む運用が、エージェントを入れたあとで最初に壊れました。沈黙がそのまま通っていたのは、読み手がコストを払っていたからではなく、払ったと信じられる与信が相手に積まれていたからだった、という整理です。
他人の目は、同じ場所しか見なかった
エージェントのレビューゲートに人間のレビューの形をそのままなぞったところ、著者が自分で検証していることと同じ場所を見ていました。持ち込めるのは原理で手順ではないという整理と、AI向けに書いた指示は効いているかどうかを人間が読んでも判定できないという話です。
削れと言われたのは、道しるべではなかった
「規定的な作り込みを削れ」という助言は、禁止形や思考手順のことを指しています。ヒントやフックやワークフローまで削れと読むと、裁量を渡したのに黙るエージェントが残ります。制約と整備を分けた上で、依存していた挙動を数え直した記録です。
囲いを作れば、手綱は要らない？
エージェントの成果を決めているのは、モデルの賢さより何を観測できるかと何を触れるかでした。書き込み権限を取り返しがつくかどうかで層に分け、壊せない場所を先に作って承認そのものを減らした設定を、公開している dotfiles の実物とロボティクス側の議論に突き合わせます。
規約は、規約について嘘をつく
エージェントに読ませる規約が、実際の挙動と食い違ったまま残っていました。参照ファイルを読めと明示的に書いた指示が、その通りには動いていなかった件を起点に、規約そのものを検査した記録です。
自律ループを作って、測って、消した
「ループエンジニアリング」という語ができる4か月前に、自律的な精製ループを実装していました。半年近く後に利用ゼロを実測して削除し、残したのは上限つきリトライだけです。提唱側と批判側の議論に照らして、その判断がどこに位置するかを整理します。
落ちないテストは、何も証明しない
検証の規約を明文化して3週間後、レビュー担当がそれを実行していなかったことが分かりました。答えは規約をもう1つ足すことではなく、検査を人の手から外して、通らなければマージそのものを止めることでした。
「保存した」は検証ではない
エージェントに作らせた画面の見た目を、数値ゲート・オフスクリーンのPNG・実際の導線の三段で確認しています。撮影までは自動化できても、撮った絵を見て判断する行為だけは自動化できていません。
Claude Code の Auto mode では Edit ツールが使われなくなる
Claude CodeのAuto modeでは、ファイル編集をsedやヒアドキュメントで済ませるよう指示するブロックがシステムプロンプトに入り、sed -iを止めてEditツールへ誘導するPreToolUseフックと矛盾します。この指示はA/B実験のフラグで出し分けられていて設定キーもドキュメントもなく、settings.jsonのenvにCLAUDE_CODE_THRIFTY_SONIC=0を置くと消えます。EditとWriteを前提にしたフックや/rewindが黙って空振りする構図と、--settingsで3通りを試した結果も書きます。
その決定、出自不明につき
設計判断をADRとして積む運用で、サブエージェントが「ユーザー決定」と書いて自分で起票したADRが混ざりました。本文を書き換えず撤回ADRを足して取り消し、ADRには誰が決めたかを書かせる規約を足した話です。
PreToolUseフックで代替手段まで返す
Claude Codeのpermissions.denyはブロックするだけで理由を返せないため、代替手段の探索をモデルに任せることになり、そのぶんトークンを使います。Bash向けのdenyをPreToolUseフックに移し、exit 2でstderrに書いた文を返すことで、ルールごとに止めた理由と代替手段を伝えられるようにしました。プレフィックス一致では見えなかった回避経路と、止める範囲を引き直した基準も書きます。
見つけさせて、直させない
PRのレビューで担保しきれずに漏れるものを拾うため、週次でコードベースを走査するだけのサブエージェントを立てています。修正はさせず検知と報告に限り、報告はレビュー側で裏を取る運用を1か月ほど回した記録です。
ターミナルにリマインダー権限を渡さずにMCPからEventKitを触る
Claude Desktop経由でMCPサーバーを起動するとReminders権限が通らない問題を、独立したLaunchAgentのdaemonへEventKitアクセスを集約して解決しました。結果として、ターミナルやClaude Desktopに権限を与えず、アプリ本体だけに絞れる構成になっています。
サブエージェントに報告ルールを守らせる
サブエージェントに計画と途中経過を報告させるルールの届け方を、hookで4通り試しました。同じ文章でも、ツールの結果に付いてくる形とCLAUDE.mdに書く形は埋め込み指示として退けられ、指示文の一部に混ぜる形と、ハーネスがサブエージェントに渡すコンテキストに入れる形だけが通っています。
Claude Codeの使用率ガードをTeamシートで止める
Claude Codeを任意の使用率で止めるガードについて、残していたTeamプレミアムシートでの確認を済ませ、UserPromptSubmitとPreToolUseをしきい値を下げて実際に発火させました。その過程で、セッション最初のレンダーがrate_limitsを持たないせいで前のセッションの観測値を消していたセンサー側の穴が見つかっています。
SVGのラスタライズをsipsとresvgとChromeで比べる
エージェントに書かせたSVGをPNGにして目視させる確認ループで、sipsだけ太字が出ませんでした。sipsがfont-weightを無視しているのではなく、boldキーワードとfont-familyの先頭が解決できない場合の2つで落ちていた話と、resvg・ヘッドレスChromeと比べた結果をまとめます。
Claude Codeに書かせたSVGをsipsでラスタライズして自分で目視させる
Claude CodeにSVGで図を描かせる手法は既にありますが、書かせた図が実際にどう見えるかは書いた本人が確認していません。macOS同梱のsipsでPNGに変換し、そのPNGをエージェント自身に読ませて確認させる運用と、sipsが黙って落とす属性の実例をまとめます。
Claude Codeを任意の使用率で止めるガードを作っている
Claude Codeのrate_limitsはstatusLineにしか渡らず、実行を止められるhookには渡ってきません。この非対称をstate fileで橋渡しし、5時間枠・週次枠を任意のパーセンテージで止めるガードを試作した記録です。
Claude Codeのsandboxが1Password SSHエージェントのUnixソケットを塞ぎ署名が失敗する
Claude Codeのsandboxed Bashから1Password SSH鍵で署名付きコミットを実行すると失敗します。原因はUnixソケット接続の遮断で、sandboxを無効化しなくてもallowUnixSockets設定でソケットパスだけを許可すれば解決します。
MCPのレスポンスをMarkdownからTOONに変えたら、ツールの説明文まで書き直すことになった
Vigilare・Chimr・PortusのMCPサーバーで、ツールのレスポンスをMarkdownからTOONへ変えました。nilをnullとして書かないと表形式が崩れること、Markdownの表を前提に書いたツールの説明文を直すことになったこと、Markdownを残したVigilareでは同じ修正を2箇所に入れ続けていることを書きます。
Apple Foundation Models で意図分解を4層に積み直したら 3B モデルのクセが見えた
macOS 26 の Apple Foundation Models で自然言語アシスタントを試作する中で、1-pass の Guided Generation を「意図 → 動詞/条件 → 詳細」の4層に再帰分解し直しました。3B オンデバイスモデルの hallucination は instructions では消えず、Swift 側の post-validation で span 単位に潰しています。
Claude Codeのコミットメッセージ生成が遅いのでツール呼び出しをゼロにした
Claude Codeスキルの動的コンテキスト注入でgit diffを事前に本文へ埋め込み、サブエージェントの推論パスを3回から1回に減らした手順を紹介します。
ChimrのMCPセットアップを手で書かせないために --mcp-install と --mcp-config を足した
Chimr を Claude Code や Claude Desktop の MCP サーバーとして使うときの設定を、ユーザーに手で書いてもらう前提から、Chimr 自身が `claude mcp add` コマンドや JSON を吐く前提に切り替えました。`--mcp-install` `--mcp-config` `--mcp` の3つの CLI フラグの実装と、bundle path を `CommandLine.arguments[0]` から取る判断をまとめます。
「埋まっているか」だけ知りたいこともあるので、ChimrのMCPが返す情報を4段階にした
MCPで予定を返すとき、呼び出し元がどこまで詳しい情報を必要とするかは、用途で違います。Chimrでは最初に3段階を用意し、2日後に時刻と出席ステータスだけを返す「厳格」を足して4段階にしました。各段階が何を返して何を落とすか、そして段階に分けた判断を書きます。