【要約】5 サービスで Claude Agent SDK を呼ぶことになって、共通化した部分と意図的に揃えなかった部分 [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
開発チームが5つのサービスでClaude Agent SDKを個別に実装した際、保守性の低下に直面した。
- ・サービスごとに実装が異なり、メンテナンスの破綻が懸念された。
- ・SDKの仕様変更により、レスポンスの抽出ロジックがサービス間で不一致となった。
- ・共通ライブラリ化しすぎると、各サービスの特殊な要件を阻害する恐れがあった。
// Approach
開発チームは、共通化の範囲を「インターフェース」と「データ形式」に限定する戦略を採用した。
- ・クラス構造と起動シーケンスを統一し、実装の型を揃えた。
- ・戻り値を model と usage を含む dict に固定し、課金系サービスとの連携を容易にした。
- ・例外を投げず、エラー内容を含む dict を返すことで、タスク管理との親和性を高めた。
- ・allowed_tools をホワイトリストで指定し、セキュリティを確保した。
- ・env マージ順序を制御し、APIキーの安全な注入を実現した。
// Result
共通基盤の導入により、開発チームの生産性と運用の安定性が向上した。
- ・新サービスの立ち上げがテンプレート利用により迅速化された。
- ・課金管理（Billing）へのデータ連携が、スキーマ変更なしに安定して行えるようになった。
- ・セキュリティ対策が定型化され、コードレビューの品質が向上した。
Senior Engineer Insight
> 共通化の「境界線」の引き方が極めて実戦的である。全てを抽象化してライブラリ化するのではなく、インターフェース（戻り値のdict形式）とセキュリティ（env注入順序）に絞って共通化し、実行ロジックの差異を許容する設計は、変化の激しいAI領域において極めてスケーラブルである。