Claude Codeで作る社内開発ツール：安全なCLIダッシュボード

社内ツールが本当に解決すべき問題

社内ツールは往々にして近道として始まります：インシデント中の20分を節約するワンコマンドやワンページ。問題は、その近道が問題と境界を事前に定義しないまま、権限のあるバックドアに静かに変貌することです。

チームがツールを求めるのは、同じ痛みが毎日起きるときです。例えば：

• ログ検索が遅い、結果が一貫しない、または複数のシステムに分散している
• フィーチャートグルが危険な手動編集や直接DB書き込みを必要とする
• データチェックが特定の誰かが自分のノートパソコンからスクリプトを実行することに依存している
• オンコールの作業が単純だが、深夜2時でミスしやすい

これらの問題は小さく感じられますが、ツールが本番ログを読み、顧客データを照会し、フラグを切り替えられるようになると、アクセス制御、監査トレイル、誤操作による書き込みに対処する必要が出てきます。「エンジニア用だけ」のツールでも、広範なクエリを実行したり誤った環境に当たったり、明確な確認手順なしに状態を変更したりすると障害を引き起こします。

成功を狭く測定可能な形で定義してください：権限を広げずに運用を速くすること。優れた社内ツールは手順を減らし、セーフガードを取り除きません。疑わしい請求の問題を確認するために全員に広いDBアクセスを与える代わりに、次のような1つの質問に答えるツールを作りましょう：「アカウントXの本日の失敗した請求イベントを表示して」という、読み取り専用でスコープされた資格情報を使う例です。

インターフェースを選ぶ前に、人々がその瞬間に何を必要としているかを決めてください。繰り返しのタスクにはCLIが優れています。結果に文脈と共有の可視性が必要ならWebダッシュボードが向いています。両方を提供することもありますが、それらは同じガードされた操作に対する薄いビューであるべきです。目標は明確に定義された単一の機能であり、新しい管理の表面を増やすことではありません。

単一の課題を選び、スコープを小さく保つ

社内ツールを有用（かつ安全）にする最も速い方法は、1つの明確な仕事を選んでそれをうまくやることです。最初からログ、機能フラグ、データ修正、ユーザー管理をすべて扱おうとすると、隠れた振る舞いが増え、人々を驚かせます。

まずは実際の業務でユーザーが尋ねる1つの質問から始めてください。例：「リクエストIDが与えられたら、サービス間のエラーと前後の行を表示する」。それは狭く、テスト可能で、説明しやすいです。

ツールが誰のためのものかを明確にしてください。ローカルでデバッグする開発者はオンコール担当者とは必要なオプションが異なり、サポートやアナリストとも違います。受け手を混ぜると、ほとんどのユーザーが触るべきでない「強力な」コマンドを追加してしまいます。

入力と出力を小さな契約のように書き残してください。

入力は明示的に：request ID、時間範囲、環境。出力は予測可能に：一致した行、サービス名、タイムスタンプ、件数。"キャッシュをクリアする"や"ジョブを再試行する"のような隠れた副作用を避けてください。それらが事故を引き起こす機能です。

既定は読み取り専用に。検索、差分、検証、レポートでツールは十分に価値を提供できます。書き込みアクションは、本当に必要な実シナリオがあり、それを厳しく制約できる場合のみ追加してください。

チームの正直さを保つ単純なスコープ声明の例：

• 1つの主要タスク、1つの主要画面またはコマンド
• 1つのデータソース（または1つの論理ビュー）、“すべて”ではない
• 環境と時間範囲を明示するフラグ
• まずは読み取り専用、バックグラウンドアクションなし
• 書き込みがある場合は、確認を要求しすべての変更をログに記録する

データソースと機微な操作を早期にマッピングする

Claude Codeが何かを書き込む前に、ツールが触るものを書き出してください。ほとんどのセキュリティと信頼性の問題はUIではなくここで現れます。このマッピングを契約として扱ってください：レビュアーに何が範囲内で何が禁止かを伝えます。

まずはデータソースと責任者の具体的なインベントリから始めます。例：ログ（app、gateway、auth）とその保存先；ツールが照会する可能性がある正確なDBテーブルやビュー；フィーチャーフラグのストアと命名ルール；メトリクスやトレースで安全にフィルタできるラベル；チケットやインシデントシステムにメモを書き込むかどうか、など。

次に、ツールが許可される操作を明記します。“admin”という権限名は避け、監査可能な動詞で定義してください。一般的な例：読み取り専用の検索とエクスポート（制限付き）、注釈（履歴を編集せずにノートを追加）、TTL付きで特定のフラグを切り替え、日付範囲とレコード件数で制約されたバックフィル、影響を示すドライランモードなど。

機微なフィールドは明示的に扱う必要があります。マスクすべきもの（メール、トークン、セッションID、APIキー、顧客識別子）と、省略表示にすべきものを決めてください。例えばIDの末尾4桁だけ表示する、あるいは生の値を見せずに一貫したハッシュで相関させるなどです。

最後に、保持と監査ルールに合意してください。ユーザーがクエリを実行したりフラグを切り替えたりしたら、誰がいつ、どのフィルタを使い、結果件数がいくつだったかを記録します。監査ログはアプリログより長く保持してください。「クエリは30日保存、監査記録は1年」といった単純なルールでも、インシデント時の議論を防げます。

単純さを保つ最小権限モデル

最小権限はモデルを退屈に保つと最も簡単です。まずツールができることをリストアップし、各アクションを読み取り専用か書き込みかでラベル付けしてください。ほとんどの社内ツールは大多数のユーザーに対して読み取りだけで十分です。

Webダッシュボードでは既存のIDシステム（SSOとOAuth）を使い、ローカルパスワードを避けてください。CLIでは短寿命トークンを好み、速やかに期限切れにし、ユーザーが必要とするアクションだけにスコープしてください。長期間有効な共有トークンはチケットに貼られたりシェル履歴に残ったり個人マシンにコピーされたりしがちです。

RBACは小さく保ってください。数個以上のロールが必要なら、そのツールはおそらくやりすぎです。多くのチームは3つで十分です：

• Viewer: 読み取り専用、安全なデフォルト
• Operator: 読み取り＋低リスクなアクションの一部
• Admin: 高リスクなアクション、稀に使用

環境は早期に分離してください。UIが同じに見えても誤って"prodで実行"することが難しくなるように、環境ごとに別の資格情報、別の設定ファイル、別のAPIエンドポイントを使いましょう。ステージングだけを担当するユーザーが本番に認証できないようにするのが理想です。

高リスクなアクションには承認ステップを設けてください。データ削除、フラグ変更、サービス再起動、重いクエリなどです。ブラスト半径が大きい操作には二者承認を考えます。実用的なパターンとしては、ターゲット（サービス名と環境）を含むタイプ入力確認、誰が要求し誰が承認したかの記録、最も危険な操作に対する短い遅延やスケジュール化ウィンドウの追加などがあります。

もしClaude Codeでツールを生成するなら、すべてのエンドポイントとコマンドが事前に必要なロールを宣言するルールにしてください。その習慣があれば、ツールが成長しても権限をレビューしやすくなります。

事故と無効なクエリを防ぐガードレール

社内ツールの最も一般的な失敗モードは攻撃者ではなく、疲れた同僚が“正しい”コマンドを誤った入力で実行することです。ガードレールは仕上げではなくプロダクト機能として扱ってください。

安全なデフォルト

まずは安全な姿勢で始めましょう：既定は読み取り専用です。管理者であっても、ツールはデータ取得しかできないモードで開くべきです。書き込みアクションは目立つ形でオンにする必要があります。

状態を変える操作（フラグ切替、バックフィル、レコード削除）にはタイプ入力による確認を必須にしてください。「Are you sure? y/N」は筋肉反射で押しがちなので弱いです。環境名とターゲットIDのように特定の文字列を再入力させる方が効果的です。

厳格な入力検証でほとんどの事故を防げます。サポートする入力形だけを受け入れ（ID、日付、環境など）、その他は早期に拒否してください。検索では権限を絞りましょう：結果制限をかけ、妥当な日付範囲を強制し、任意パターンがログストアに届くのを許さないホワイトリスト方式を使います。

暴走クエリを避けるために、タイムアウトとレート制限を追加してください。安全なツールは素早く失敗して理由を説明し、ハングしてDBを叩き続けることを避けます。

実務で効くガードレールのセット例：

• 既定は読み取り専用、明瞭な「書き込みモード」スイッチ
• 書き込みはタイプ入力による確認（環境＋ターゲットを含める）
• ID、日付、制限、許可パターンの厳格な検証
• クエリタイムアウトとユーザーごとのレート制限
• 出力とツール内ログでのシークレットのマスク

出力の衛生管理

ツールの出力はチケットやチャットに貼られる前提で作ってください。デフォルトでシークレットをマスク（トークン、クッキー、APIキー、必要ならメールも）し、保存するものも洗浄してください：監査ログには返された生データではなく、試行された内容を記録します。

ログ検索ダッシュボードなら、まず短いプレビューと件数を返し、ペイロード全体は返さないようにしてください。どうしてもフルイベントが必要な場合は、明確にゲートされた別アクションにして独立した確認を要求します。

Claude Codeと協働するときにコントロールを失わない方法

Claude Codeは有能だが万能ではない新人同僚のように扱いましょう：役に立つが心を読めるわけではありません。仕事を境界付け、レビュー可能にし、元に戻しやすくするのがあなたの役目です。それが安全に感じるツールと深夜2時に驚くツールの違いです。

モデルが従える仕様から始める

コードを頼む前に、ユーザーアクションと期待される結果を名前で書いた小さな仕様を書いてください。振る舞いについてで、フレームワークの細かい話は不要です。良い仕様は半ページに収まることが多く、次をカバーします：

• コマンドや画面（正確な名前）
• 入力（フラグ、フィールド、形式、制限）
• 出力（何が表示され、何が保存されるか）
• エラーケース（無効入力、タイムアウト、結果なし）
• 権限チェック（アクセス拒否時の挙動）

例えばログ検索CLIを作るなら、1つのコマンドをエンドツーエンドで定義します：logs search --service api --since 30m --text \"timeout\"、結果数にハードキャップをかけ、「アクセスなし」の明確なメッセージを定義する、といった具合です。

検証しやすい小さなインクリメントを要求する

まず骨組みを出させてください：CLIのワイヤリング、設定読み込み、スタブ化したデータ呼び出し。その後で、検証とエラー処理を含めた1つの機能を完全に実装してもらいます。差分が小さいとレビューが現実的になります。

変更ごとに、何がなぜ変わったかを平易な言葉で説明させてください。その説明が差分と合致しなければ、そこで止めて振る舞いと安全制約を言い直してください。

機能を増やす前にテストを早めに生成してください。最低でもハッピーパス、無効入力（不正な日付、フラグ欠如）、権限拒否、結果なし、レート制限やバックエンドのタイムアウトをカバーしてください。

CLI対Webダッシュボード：適切なインターフェースの選び方

CLIと社内Webダッシュボードは同じ問題を解けますが、失敗の仕方が異なります。安全な道を最も簡単にするインターフェースを選んでください。

スピードが重要でユーザーがやりたいことを既に分かっている場合、CLIが通常良い選択です。CLIは読み取り専用ワークフローに合いやすく、権限を狭く保ち、誤ってボタンで書き込みを発動するリスクを減らせます。

CLIはオンコールでの迅速なクエリ、スクリプトや自動化、明示的な監査トレイル（コマンドがそのまま記録される）、およびローンチの低コスト（1つのバイナリ、1つの設定）に向きます。

共有の可視化やガイド付きステップが必要な場合はWebダッシュボードの方が向きます。安全なデフォルト（時間範囲、環境、事前承認アクション）に人を誘導でき、チーム全体のステータスビューや確認付きのエクスポートなどに適しています。

可能なら同じバックエンドAPIを両方で使ってください。認証、レート制限、クエリ制限、監査ログをAPI側に置けば、CLIとダッシュボードは異なるクライアントになるだけです。

また、どこで実行するかも決めてください。これによってリスクが変わります。ノートパソコン上のCLIはトークン漏洩のリスクがあります。バスチオンホストや内部クラスタで実行すると露出を減らし、ログやポリシー適用を容易にします。

例：ログ検索では、オンコールのエンジニアが直近10分の特定サービスを引くならCLIが優れます。共有のインシデントルームで同じフィルタビューを全員に見せたいなら、ダッシュボードが向きます。ダッシュボードでは「ポストモーテム用にエクスポート」などの権限チェック済みのアクションを案内できます。

現実的な例：オンコール向けログ検索ツール

時刻は02:10、オンコールに「ある顧客の支払い時にたまに失敗する」という報告が入りました。サポートはリクエストIDのスクリーンショットを持っていますが、誰も管理権限でランダムなクエリをログシステムに投げたくありません。

小さなCLIはこれを安全に解決できます。重要なのは狭く保つこと：エラーを素早く見つけ、必要なものだけを表示し、本番データは変更しないことです。

最小限のCLIフロー

時間の上限と特定の識別子を強制する1つのコマンドから始めてください。リクエストIDと時間ウィンドウを必須にし、短いウィンドウをデフォルトにします。

oncall-logs search --request-id req_123 --since 30m --until now

まず要約を返します：サービス名、エラークラス、件数、上位3つの一致メッセージ。ユーザーが明示的に展開を要求したときだけ完全なログ行を表示する段階を設けてください。

oncall-logs show --request-id req_123 --limit 20

この2段設計は偶発的なデータダンプを防ぎます。また、ツールが安全をデフォルトにする明確なパスを持つためレビューもしやすくなります。

オプションの追跡アクション（書き込みなし）

オンコールは次の担当者のために痕跡を残す必要があります。DBを書き換える代わりに、チケットのノート用ペイロードを作る、またはインシデントシステムにタグを付けるオプションを追加できますが、顧客レコードに触れてはなりません。

最小権限を守るため、CLIは読み取り専用のログトークンを使い、チケットやタグ付けアクションには別の限定的なトークンを使うべきです。

実行ごとに監査記録を保存してください：誰が実行したか、どのrequest IDか、どの時間範囲を使ったか、詳細を展開したかどうか。監査ログは問題発生時やアクセスレビュー時の安全網になります。

セキュリティと信頼性の問題を生む一般的な誤り

小さな社内ツールは往々にして「ちょっとしたヘルパー」として始まります。それが事故を招く典型的な原因です。信頼を失う最速の方法は1回の重大なインシデントです：読み取り専用のはずがデータを削除してしまうツールなど。

よくある誤り：

• 読み取りだけで良いのに本番DBの書き込み権限を与え、「慎重に扱う」と仮定してしまう
• 監査トレイルを省略し、後で誰がどの入力で何を実行したか答えられない
• 生のSQLや正規表現、アドホックフィルタを許して巨大なテーブルやログをスキャンしてしまう
• 環境が混ざってステージングの操作が本番に届く（設定、トークン、ベースURLの共有）
• シークレットを端末やブラウザコンソール、ログに出力してしまい、その出力がチケットやチャットに貼られる

現実的な失敗例：オンコールエンジニアがログ検索CLIを使う。ツールが任意の正規表現を受け付けログバックエンドに送る。ある高負荷パターンが数時間分のログを走査してコストと遅延を発生させる。同じセッションでCLIがデバッグ出力にAPIトークンを表示し、それが公開のインシデント文書に貼られる。

ほとんどの事故を防ぐ安全なデフォルト

読み取り専用を本当の境界として扱い、設計で危険を除いてください。環境ごとに別の資格情報を使い、ツールごとにサービスアカウントを分けます。

効くガードレールの例：

• 生のSQLではなく許可されたクエリ（テンプレート）を使い、時間範囲と行数に上限をかける
• すべてのアクションをリクエストID、ユーザーID、対象環境、正確なパラメータとともにログに残す
• 本番選択には明示的な環境選択と大きな確認を要求する
• デフォルトでシークレットをマスクし、デバッグ出力は特権フラグが使われた場合のみ有効にする

ツールが設計上危険な操作をできないなら、深夜3時に全員の注意力に頼る必要はありません。

リリース前の簡単チェックリスト

社内ツールを実際のユーザーに提供する前に（特にオンコール向けの場合）、それを本番システムのように扱ってください。アクセス、権限、セーフティリミットが暗黙ではなく実際に機能していることを確認します。

アクセスと権限から始めます。多くの事故は「一時的」なアクセスが恒久化することや、ツールが徐々に書き込み権限を得ることで起きます。

• 認証とオフボーディング： 誰がサインインできるか、アクセスはどう付与されるか、チーム変更時に同日中に取り消されるか確認する
• ロールは少数に： 2〜3ロールに抑え、それぞれ何ができるかを書き出す
• 既定は読み取り専用： 表示がデフォルトで、データ変更に対しては明示的なロールを要求する
• シークレットの扱い： トークンやキーはレポジトリ外に保管し、ツールがログやエラーメッセージに出力しないことを検証する
• ブレイクグラスフロー： 緊急アクセスは時間限定かつログに残す

次に、一般的な誤りを防ぐガードレールを検証します：

• 危険な操作の確認： 削除、バックフィル、設定変更に対してタイプ入力の確認を要求する
• 制限とタイムアウト： 結果サイズに上限を設定し、時間ウィンドウを強制し、クエリはタイムアウトするようにする
• 入力検証： ID、日付、環境名を検証し、“全環境で実行”のように見えるものを拒否する
• 監査ログ： 誰がいつどこから何をしたかを記録し、インシデント時に検索しやすくする
• 基本的なメトリクスとエラー： 成功率、遅延、主要なエラー種別を追跡して早期に壊れを検知する

変更管理も他のサービス同様に行ってください：ピアレビュー、危険パスの焦点を絞ったテスト、そして誤動作時にツールを素早く無効化するためのロールバック計画を用意します。

次のステップ：安全に展開して改善を続ける

初回リリースは管理された実験のように扱ってください。1チーム、1ワークフロー、少数の実タスクで始めます。オンコール向けログ検索ツールは良いパイロットです。節約時間を測定し、危険なクエリを早く見つけられるからです。

展開を予測可能に：3〜10人のパイロット、まずはステージングで開始、共有トークンではなく最小権限のロールでアクセスを制御、使用制限を設定し、すべてのコマンドやボタン操作の監査ログを記録します。設定や権限の変更を素早くロールバックできることを確認してください。

ツールの契約を平易な言葉で書き残してください。各コマンド（またはダッシュボードアクション）、許可されたパラメータ、成功の定義、エラーの意味を列挙します。出力が曖昧だと人々はツールを信頼しなくなります。

実際にチェックするフィードバックループを作ってください。遅いクエリ、よく使われるフィルタ、混乱を招くオプションを追跡します。繰り返しの回避策が見えたら、それは安全なデフォルトが欠けている兆候です。

保守にはオーナーとスケジュールが必要です。依存関係を誰が更新するか、資格情報を誰がローテーションするか、ツールがインシデント中に壊れたら誰にページを飛ばすか決めてください。AI生成の変更も本番サービスと同様にレビューしてください：権限の差分、クエリの安全性、ログ出力を確認します。

チームがチャット主導の反復を好むなら、Koder.ai (koder.ai)は会話から小さなCLIやダッシュボードを生成し、既知の良好な状態のスナップショットを保持し、変更がリスクをもたらしたときに素早くロールバックする実用的な方法になり得ます。