https://tech.algomatic.jp/entry/2025/08/21/162924

1. はじめに

こんにちは、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に関する知見を共有します。

2. Claude Code SDKの概要

Claude Code SDKとは何か

開発者がターミナルで対話的にClaudeとやり取りするClaude CodeのCLI利用は、皆さんイメージできると思います。

Claude Code SDKは、CLIと同様のclaude実行ファイルをアプリケーション側から操るためのライブラリです。

イベントやストリームを受け取りながら、計画から適用、ツール実行まで非対話（ヘッドレス）でプログラム制御できる仕組みを提供しており、アプリケーションとして作り込みやすいです。

docs.anthropic.com

なお、claude -pを使えば、CLIでも非対話（ヘッドレス）で実行は可能です。本プロダクトでは、アプリケーション側でのオーケストレーションによる拡張性と制御性を優先し、Claude Code SDKを採用しています。

TypeScript版とPython版の特徴

Claude Code SDKは現在、TypeScriptとPythonの2つの言語で提供されています。

TypeScript SDK

npmパッケージ@anthropic-ai/claude-codeでCLIと一緒にインストール
CLIと同様のclaude実行ファイルを直接扱うので、無駄な処理なくよりネイティブな操作感

Python SDK

pip install claude-code-sdkに加え、Node.jsと@anthropic-ai/claude-codeの導入が必須
内部でCLIを起動し、JSONストリームをパースする仕組み
CLI未導入時にはCLINotFoundErrorなど専用例外でエラーハンドリング

3. Claude Code SDKを使って得られたこと

Permission Modesによる安全な実行計画

Claude Codeでは、以下の4つのPermission Modesが利用可能で、それぞれ安全性や利用シーンに応じて選択できます。

Mode	説明	使用シーン
`default`	標準動作 - 各ツールの初回使用時に権限確認	通常の開発作業、手動確認を重視したい場合
`acceptEdits`	セッション中のファイル編集権限を自動承認	開発効率を重視、ファイル変更が頻繁な作業
`plan`	分析のみ可能、ファイル変更・コマンド実行は禁止	コードレビュー、設計検討、安全な事前確認
`bypassPermissions`	全ての権限プロンプトをスキップ（安全な環境必須）	CI/CD、完全自動化された環境での実行

Identity and Access Management - Anthropic

私のPoC自動化プロダクトでは、3つのエンドポイントのモードを個別設定して実装することで 「計画 → 承認 → 継続改修」のフローを自動化しつつ、安全性と柔軟性を両立 しています。

POST /api/poc/build
- モード: plan
- 計画のみを生成し、ファイル編集やコマンド実行は行わない。
POST /api/poc/approve
- モード: default
- 承認後、同じセッションで実行に移行。ツール使用時には初回のみ確認が入り、以降はセッション内で承認済みとして進行。
POST /api/poc/extend
- モード: default
- 追加改修も同一セッションのまま行われ、同じ権限制御が適用される。（まだ不安定…）

さらに、defaultモードで権限確認が発生した場合でも、同じ approve エンドポイントを介して応答することで、セッションを途切れさせずに継続できるように設計しています。

コマンドレベルで制御を実現

allowedToolsと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)"  // 本番設定の変更を禁止
  ]
}

Hooksによる確実な実行

Claude Code hooksは、各ツールの実行前後に外部コマンドを自動実行する機能です。

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: 全体構成と設計意図

4. まとめ

今回は、PoCの自動化を目指す中でClaude Code SDKを活用した実装知見を共有しました。
本記事はClaude Code SDKの紹介がメインでしたが、PoC自動化プロダクトについてはまた別の機会に共有したいです。
引き続き形にしていく取り組みを進めてまいりますので、ご意見やフィードバックをいただければ幸いです。

最後にAlgomaticは一緒に働くメンバーを募集しています！以下よりお気軽にカジュアル面談をお申し込みいただけると幸いです！

jobs.algomatic.jp