実装の中で育むClaude Code SDK理解：PoC自動化から得た学び
Algomatic は Claude Code SDK の権限制御機能とフックを活用し、PoC（概念実証）の自動化を実現するプロダクトを開発した実践報告である。
キーポイント
Claude Code SDK の非対話型制御機能
CLI 同様の操作感をアプリケーション側から提供し、イベントやストリームを受け取りながら計画から実行までヘッドレスでプログラム制御可能である。
権限モードによる安全な自動化フロー
標準動作、セッション中承認、分析のみ、bypassPermissions の 4 つのモードを組み合わせ、「計画→承認→継続改修」の安全かつ柔軟な自動化を実現している。
ツール許可・禁止リストによる細粒度制御
allowedTools と disallowedTools を設定することで、特定のファイル編集や危険コマンド（例：rm, sudo）を明示的に許可またはブロックし、セキュリティを担保している。
フック機能によるワークフロー拡張
PreToolUse や PostToolUse などのフックを活用してツール実行前後に外部コマンドを自動実行し、より柔軟な制御と確実なワークフローを実現している。
作り直し前提の開発サイクルの確立
本番開発への移行を容易にするため、PoC段階から作り直し前提の柔軟な開発サイクルを採用し、そのハードルを下げることを目指した。
検証速度と説明責任の両立
対象の検証スピードを高める一方で、実現可能性などの明確な結果を示すことで、開発における説明責任を果たすことを重視した。
影響分析・編集コメントを表示
影響分析
本記事は、生成 AI エンジニアリングにおける「PoC からプロダクトへ」の転換を具体化した実践例であり、LLM の自律的な実行制御におけるセキュリティと効率性のバランスを取るための具体的なアーキテクチャを示しています。特に権限制御やフック機能を活用した自動化パターンは、同様の PoC 自動化システムを構築する開発者にとって即座に適用可能な重要な知見となります。
編集コメント
PoC の自動化における「安全」と「効率」の両立を、Claude Code SDK の具体的な機能設定でどう実現したかが非常に参考になります。実務での導入を検討しているエンジニアにとって即戦力となる知見です。
実装の中で育てるClaude Code SDK理解：PoC自動化から得た学び
こんにちは、Algomatic AXの岩城祐作（@yukl_dev）です。 私は5月にAlgomaticに入社し、AIエンジニアとして働いています。 入社エントリに、転職の背景の1つとして以下を書きました。
PoCループの虚しさと危機感 一方で、技術検証やデモ作成にとどまるPoC（Proof of Concept）も少なくありませんでした。 LLMOps導入など、生成AIの現場でよく用いられる実践的な経験を積み重ねる機会が少なく、AI領域に関わっているにも関わらずエンジニアとして活かせていない現状に、危機感が募りました。
果たして自分は本当に価値を提供できているのか？そもそも今の開発は本当に求められていることか？という不安が大きくなっていました。
企業支援のみを目的としたエンジニアでいることの危機感と無力感が、日に日に大きくなりました。
良ければ入社エントリもご覧ください。 note.com
「技術検証やデモ作成にとどまるPoC（Proof of Concept）」が意味のないものとは思いません。 ただ、エンジニアと顧客の双方がより価値ある時間を過ごせるように、以下を目指してPoC自動化プロダクトの開発に取り組み始めました。
エンジニアが専門的な課題に価値投下できる状態を作る
属人化する必要のないPoCに必要な知見を集約し、同種PoCの初速を最大化する
各エンジニアや組織にとってより価値のある知見の蓄積につなげる
「Claude Code SDK」を使って実装を進めており、今回はその実装過程で得られたClaude Code SDKに関する知見を共有します。
- Claude Code SDKの概要
Claude Code SDKとは何か
開発者がターミナルで対話的にClaudeとやり取りするClaude CodeのCLI利用は、皆さんイメージできると思います。
Claude Code SDKは、CLIと同様のclaude実行ファイルをアプリケーション側から操るためのライブラリです。
イベントやストリームを受け取りながら、計画から適用、ツール実行まで非対話（ヘッドレス）でプログラム制御できる仕組みを提供しており、アプリケーションとして作り込みやすいです。
docs.anthropic.com
TypeScript版とPython版の特徴
Claude Code SDKは現在、TypeScriptとPythonの2つの言語で提供されています。
npmパッケージ@anthropic-ai/claude-code
CLIと同様のclaude実行ファイルを直接扱うので、無駄な処理なくよりネイティブな操作感
pip install claude-code-sdk
@anthropic-ai/claude-code
内部でCLIを起動し、JSONストリームをパースする仕組み
CLI未導入時にはCLINotFoundError
- Claude Code SDKを使って得られたこと
Permission Modesによる安全な実行計画
Claude Codeでは、以下の4つのPermission Modesが利用可能で、それぞれ安全性や利用シーンに応じて選択できます。
標準動作 - 各ツールの初回使用時に権限確認
通常の開発作業、手動確認を重視したい場合
セッション中のファイル編集権限を自動承認
開発効率を重視、ファイル変更が頻繁な作業
分析のみ可能、ファイル変更・コマンド実行は禁止
コードレビュー、設計検討、安全な事前確認
bypassPermissions
全ての権限プロンプトをスキップ（安全な環境必須）
CI/CD、完全自動化された環境での実行
Identity and Access Management - Anthropic
私のPoC自動化プロダクトでは、3つのエンドポイントのモードを個別設定して実装することで 「計画 → 承認 → 継続改修」のフローを自動化しつつ、安全性と柔軟性を両立 しています。
POST /api/poc/build
計画のみを生成し、ファイル編集やコマンド実行は行わない。
POST /api/poc/approve
承認後、同じセッションで実行に移行。ツール使用時には初回のみ確認が入り、以降はセッション内で承認済みとして進行。
POST /api/poc/extend
追加改修も同一セッションのまま行われ、同じ権限制御が適用される。（まだ不安定…）
さらに、defaultモードで権限確認が発生した場合でも、同じ approve
disallowedTools
allowedTools: 明示的に「利用を許可する操作」を列挙。指定した範囲内の操作は確認なしで実行される。
disallowedTools: 明示的に「禁止する操作」を列挙。指定にマッチする操作はセッション内でブロックされる。
現時点のPoC自動化プロダクト内のコマンドリストは、最低限のものを指定していますが、部署やチームと調整してアップデートする予定です。
// 設定例 const options = { allowedTools: [ "Read", "Bash(npm install)", "Bash(npm run test:*)", // test系コマンドを許可 "Edit(src/**)" // srcディレクトリ内の編集を許可 ], disallowedTools: [ "Bash(rm *)", "Bash(sudo *)", // 危険なコマンドを拒否 "Edit(config/production.json)" // 本番設定の変更を禁止 ] }
Claude Code hooksは、各ツールの実行前後に外部コマンドを自動実行する機能です。
Hooksは、複数のタイミングで処理を差し込むことができます。 代表的なイベントは次の通りです。
PreToolUse: ツール実行前に呼び出される
PostToolUse: ツール実行後に呼び出される
SessionStart: セッション開始時に呼び出される
Notification: 権限待ちなどの通知タイミングで呼び出される
UserPromptSubmit: ユーザーのプロンプト送信直後に呼び出される
そのほかに PreCompact / Stop / SubagentStop などのイベントがあります。
Hooks reference - Anthropic
これらを活用することで、より柔軟な制御と確実なワークフローの実行が可能になります。
その他Hooksの詳細と事例については、弊社の柗村@yu_mattznの記事もご覧ください。
tech.algomatic.jp
私のPoC自動化プロダクトでは、以下が実現したいことでした。
作り直し前提の開発サイクル：次フェーズ（本番開発）への移行を容易にし、作り直し前提とする開発サイクルのハードルを下げる
速度と検証の両立：対象の検証速度を早めつつ、検証結果（特に実現可能性）を明確にする。この説明責任を大切にする
そのため、PostToolUse
README.md: 生成したアプリケーションの全体像と使い方
POC_REQUIREMENTS.md: PoCの検証内容や要件
FEATURES_IMPLEMENTATION.md: 実装機能とその実現方法
ARCHITECTURE.md: 全体構成と設計意図
今回は、PoCの自動化を目指す中でClaude Code SDKを活用した実装知見を共有しました。 本記事はClaude Code SDKの紹介がメインでしたが、PoC自動化プロダクトについてはまた別の機会に共有したいです。 引き続き形にしていく取り組みを進めてまいりますので、ご意見やフィードバックをいただければ幸いです。
最後にAlgomaticは一緒に働くメンバーを募集しています！ 以下よりお気軽にカジュアル面談をお申し込みいただけると幸いです！
jobs.algomatic.jp
原文を表示
こんにちは、Algomatic AXの岩城祐作（@yukl_dev）です。 私は5月にAlgomaticに入社し、AIエンジニアとして働いています。 入社エントリに、転職の背景の1つとして以下を書きました。
PoCループの虚しさと危機感 一方で、技術検証やデモ作成にとどまるPoC（Proof of Concept）も少なくありませんでした。 LLMOps導入など、生成AIの現場でよく用いられる実践的な経験を積み重ねる機会が少なく、AI領域に関わっているにも関わらずエンジニアとして活かせていない現状に、危機感が募りました。
果たして自分は本当に価値を提供できているのか？そもそも今の開発は本当に求められていることか？という不安が大きくなっていました。
企業支援のみを目的としたエンジニアでいることの危機感と無力感が、日に日に大きくなりました。
良ければ入社エントリもご覧ください。 note.com
「技術検証やデモ作成にとどまるPoC（Proof of Concept）」が意味のないものとは思いません。 ただ、エンジニアと顧客の双方がより価値ある時間を過ごせるように、以下を目指してPoC自動化プロダクトの開発に取り組み始めました。
エンジニアが専門的な課題に価値投下できる状態を作る
属人化する必要のないPoCに必要な知見を集約し、同種PoCの初速を最大化する
各エンジニアや組織にとってより価値のある知見の蓄積につなげる
「Claude Code SDK」を使って実装を進めており、今回はその実装過程で得られたClaude Code SDKに関する知見を共有します。
- Claude Code SDKの概要
Claude Code SDKとは何か
開発者がターミナルで対話的にClaudeとやり取りするClaude CodeのCLI利用は、皆さんイメージできると思います。
Claude Code SDKは、CLIと同様のclaude実行ファイルをアプリケーション側から操るためのライブラリです。
イベントやストリームを受け取りながら、計画から適用、ツール実行まで非対話（ヘッドレス）でプログラム制御できる仕組みを提供しており、アプリケーションとして作り込みやすいです。
docs.anthropic.com
TypeScript版とPython版の特徴
Claude Code SDKは現在、TypeScriptとPythonの2つの言語で提供されています。
npmパッケージ@anthropic-ai/claude-code
CLIと同様のclaude実行ファイルを直接扱うので、無駄な処理なくよりネイティブな操作感
pip install claude-code-sdk
@anthropic-ai/claude-code
内部でCLIを起動し、JSONストリームをパースする仕組み
CLI未導入時にはCLINotFoundError
- Claude Code SDKを使って得られたこと
Permission Modesによる安全な実行計画
Claude Codeでは、以下の4つのPermission Modesが利用可能で、それぞれ安全性や利用シーンに応じて選択できます。
標準動作 - 各ツールの初回使用時に権限確認
通常の開発作業、手動確認を重視したい場合
セッション中のファイル編集権限を自動承認
開発効率を重視、ファイル変更が頻繁な作業
分析のみ可能、ファイル変更・コマンド実行は禁止
コードレビュー、設計検討、安全な事前確認
bypassPermissions
全ての権限プロンプトをスキップ（安全な環境必須）
CI/CD、完全自動化された環境での実行
Identity and Access Management - Anthropic
私のPoC自動化プロダクトでは、3つのエンドポイントのモードを個別設定して実装することで 「計画 → 承認 → 継続改修」のフローを自動化しつつ、安全性と柔軟性を両立 しています。
POST /api/poc/build
計画のみを生成し、ファイル編集やコマンド実行は行わない。
POST /api/poc/approve
承認後、同じセッションで実行に移行。ツール使用時には初回のみ確認が入り、以降はセッション内で承認済みとして進行。
POST /api/poc/extend
追加改修も同一セッションのまま行われ、同じ権限制御が適用される。（まだ不安定…）
さらに、defaultモードで権限確認が発生した場合でも、同じ approve
disallowedTools
allowedTools: 明示的に「利用を許可する操作」を列挙。指定した範囲内の操作は確認なしで実行される。
disallowedTools: 明示的に「禁止する操作」を列挙。指定にマッチする操作はセッション内でブロックされる。
現時点のPoC自動化プロダクト内のコマンドリストは、最低限のものを指定していますが、部署やチームと調整してアップデートする予定です。
// 設定例 const options = { allowedTools: [ "Read", "Bash(npm install)", "Bash(npm run test:*)", // test系コマンドを許可 "Edit(src/**)" // srcディレクトリ内の編集を許可 ], disallowedTools: [ "Bash(rm *)", "Bash(sudo *)", // 危険なコマンドを拒否 "Edit(config/production.json)" // 本番設定の変更を禁止 ] }
Claude Code hooksは、各ツールの実行前後に外部コマンドを自動実行する機能です。
Hooksは、複数のタイミングで処理を差し込むことができます。 代表的なイベントは次の通りです。
PreToolUse: ツール実行前に呼び出される
PostToolUse: ツール実行後に呼び出される
SessionStart: セッション開始時に呼び出される
Notification: 権限待ちなどの通知タイミングで呼び出される
UserPromptSubmit: ユーザーのプロンプト送信直後に呼び出される
そのほかに PreCompact / Stop / SubagentStop などのイベントがあります。
Hooks reference - Anthropic
これらを活用することで、より柔軟な制御と確実なワークフローの実行が可能になります。
その他Hooksの詳細と事例については、弊社の柗村@yu_mattznの記事もご覧ください。
tech.algomatic.jp
私のPoC自動化プロダクトでは、以下が実現したいことでした。
作り直し前提の開発サイクル：次フェーズ（本番開発）への移行を容易にし、作り直し前提とする開発サイクルのハードルを下げる
速度と検証の両立：対象の検証速度を早めつつ、検証結果（特に実現可能性）を明確にする。この説明責任を大切にする
そのため、PostToolUse
README.md: 生成したアプリケーションの全体像と使い方
POC_REQUIREMENTS.md: PoCの検証内容や要件
FEATURES_IMPLEMENTATION.md: 実装機能とその実現方法
ARCHITECTURE.md: 全体構成と設計意図
今回は、PoCの自動化を目指す中でClaude Code SDKを活用した実装知見を共有しました。 本記事はClaude Code SDKの紹介がメインでしたが、PoC自動化プロダクトについてはまた別の機会に共有したいです。 引き続き形にしていく取り組みを進めてまいりますので、ご意見やフィードバックをいただければ幸いです。
最後にAlgomaticは一緒に働くメンバーを募集しています！ 以下よりお気軽にカジュアル面談をお申し込みいただけると幸いです！
jobs.algomatic.jp
関連記事
今日のまとめ
AI日報で今日の重要ニュースをまとめ読み