kubell Creator's Note

株式会社kubellのエンジニアのブログです。

ビジネスチャット「Chatwork」のエンジニアのブログです。

読者になる

Spec Kit × Claude Codeで挑むリアーキテクチャ

こんにちは！kubellのiOS開発グループ機能開発チームの田川です。 この記事はkubell Advent Calendar 2025の25日目の記事です。 25卒として今年の4月に入社したばっかりだと思っていたのに、もう1年が経とうとしています...早い...。

ChatworkのiOSアプリでは先日のChatwork LiveのZoomVideoSDKへの移行に合わせて通話機能のリアーキテクチャも行っています。 変更された行の数は約1万行あり（削除するだけのコードも含む）、そこそこ規模の大きいリファクタリングとなっています。 今回、自分はこのリアーキテクチャの設計を任せていただいたのですが、新たな試みとしてGithubの提供している仕様駆動開発ツールであるSpec KitとClaude Codeを使用して現在の通話機能の仕様の洗い出しと新設計の策定を行いました。使ってみて得た知見や有効だった部分、使いづらかった部分などを書き記していこうと思います。

Spec Kitの使い方

Spec Kitのインストール方法や詳しい使い方は公式のREADMEを見ていただくのが良いと思うので割愛します。 流れを簡単に説明すると /speckit.constitutionでプロジェクトの絶対原則を策定 /speckit.specifyで要件の整理 /speckit.planで要件や原則をもとに、アーキテクチャやデータ構造を決定 /speckit.tasksでタスク分割 /speckit.implementでタスクに沿って実装 といった流れになります。 /speckit.clarifyのような、要件の不明瞭な部分を質問して明確にしてくれる便利なコマンドも存在します。 また今回はClaude Codeを使用しましたが、gemini CLIやCodex CLIなど主要なコーディングエージェントは大体対応しています。仕様書のフォーマットは共通なので設計はgeminiやCodexで行い、実装はClaude Codeで行う、といったことも可能です。

実際に使ってみた所感

現在の仕様調査、要件整理

思ったよりもしっかりと仕様や要件の洗い出しをしてくれました。通話機能には発信の導線や通話の制限などChatwork特有のドメイン知識も多く含まれており、コールバックも多い複雑なコードでしたが、あらかたの仕様は初回の実行で列挙することができました。一方でどのタイミングでWeb APIを呼ぶか、制限をどうかけるかなど細かい部分での抜け漏れが発生する印象です。現時点では仕様の調査を全て任せることは難しそうです。抜けていた仕様に関しては「通話の導線毎にWeb APIを呼び出しているタイミングをまとめて」のように明示的に指示を出せば問題なく調査してくれます。また、調査のアウトプットとしてデフォルトではアスキーアートによるフロー図を出力することが多かったですが、アスキーアートだと壊れることが多く手作業による修正も困難であったため、自分はPlantUMLで出力させていました。

設計

設計に頭の中にある程度の形があったので、それをSpec Kitの指示に従って文書化していく作業でした。基本的にはplan.mdに記述していきますが、今回のように巨大なリファクタの場合にはplan.mdが肥大化してしまうのが難点です。設計を微修正する度にこれまで作成したmdファイルにも修正が入ることになります。ドキュメントの修正自体はAIが行なってくれますが、それが意図通りか確認する作業が後半になればなるほど辛くなってきます。テーマに合わせて文書を分割するとplan.mdの肥大化をある程度抑えることができます。ドキュメントが増えてくると被りや冗長な表現が増えてきがちなので、適度なタイミングでドキュメントのスリム化や整合性の確認を行うことがオススメです。チームメンバーにレビューしてもらう際はmiroに図を書き出して全体像を掴んでもらい、細かい部分はmdファイルのドキュメントを読んでもらう形式にしました。

タスク分割

/speckit.tasksでこれまで作成したドキュメントをもとにタスクの分割を行うことができますが、Spec Kitが用意したテンプレートと私たちのチームが日々使用している形式が異なるので、一度tasks.mdを作成した後、チームのテンプレートにマイグレーションする方法を取りました。Spec Kitはgithubのissueにのみ対応していましたが、私たちが使用しているJIRAのチケットへのパースもMCPを使用することで簡単に作成することができました。

実装

実装に関してはほとんどSpec Kitの/speckit.implementを使用せずに実装しました。このコマンドを使用するとtasks.mdに書かれたタスクを元にブランチをworktreeで作成して進めようとしてしまいます。逆にブランチ名がSpec Kitの用意した形式に沿った形になっていないとエラーになってしまうため、都度指示する必要があります。/speckit.implementのスラッシュコマンドのプロンプトは基本的にSpec Kitの用意したレールに沿って実装する指示になっているので、このレールに乗らない場合はこれまで作成したドキュメントを読み込んで実装してもらうだけで十分な場合が多いと思います。設計段階で細かくドキュメント化されているため、実装はかなりスムーズに行えました。また、実装段階で設計の不備が分かった場合も、その場でAIにドキュメントを書き換えてもらうことができる点も便利でした。

まとめ

今回はSpec Kitを使用したリファクタリングについて説明しました。 設計の壁打ちをAIと行いドキュメント化できるためAIと壁打ちしながらスムーズな設計を行うことができます。一方で実装に関してはSpec Kitの用意した手法に乗ることを強制されるため、実務に完全に組み込むには難しい印象を受けました。また実装時に都度ドキュメントを更新する場合、プロジェクトにドキュメントが含まれている場合はコンフリクトが頻発する点も注意が必要です。実装時に注意点はいくつかあるものの、設計をAIと壁打ちしながら行える点に関しては非常に強力なツールだと思います。皆さんもぜひ使ってみてください。