claude-code-spec-workflow の紹介

“弁護士ドットコム株式会社 Creators’ blog 2025-09-03 claude-code-spec-workflowで始める仕様書駆動開発 クラウドサイン LLM活用 フロントエンド  はじめに クラウドサイン Product Engineering 部で主にフロントエンドエンジニアとして活動している山下慧です。 さて、この記事をご覧になっている方は、Claude Code などの AI エージェントを用いて開発していることが多いでしょう。しかし、使っている中で「AI エージェントが自分の意図とは違う仕様で開発し始めた！」「途中で寄り道を始めて収拾がつかなくなった！」といった経験をしたことも多いのではないでしょうか。 本記事ではこういった問題を解決するための手法として、まずは Kiro が提唱する仕様書駆動開発について説明します。そのうえで、この仕様書駆動開発を Claude Code で利用できるようにした claude-code-spec-workflow について紹介します。 以降は以下の環境下を前提に説明していきます：Claude Code、Node.js 18+、macOS Kiroが提唱する仕様書駆動開発 2025 年 7 月中旬に AWS は新たな AI IDE である Kiro を発表しました。Kiro は AI エージェントと統合した新たな開発手法として「Spec-driven Development（仕様書駆動開発）」を提唱しています。 Kiro が示す「仕様書駆動開発」は、仕様の基盤として 3 つのファイルをユーザーと対話しながら用意するところから始まります。requirements.md（ユーザーストーリーと受け入れ基準）、design.md（アーキテクチャやシーケンス、設計上の注意）、tasks.md（実装計画）です。これらをユーザーと対話しながら生成する過程で、ユーザーが指示したプロンプトと具体的な実装の間に認識の溝ができがちな部分を、橋渡ししていく考え方です。 この発想自体は他の AI エージェントでも適用可能で、Claude Code においてもテンプレートやカスタムコマンドを使って同様の流れを再現する取り組みがすでに複数あります。 claude-code-spec-workflow の紹介 今回紹介するのは、Claude Code でこの仕様書駆動開発のフローを CLI として実装した claude-code-spec-workflow です。ツールの機能は大きく 2 つ。ひとつは仕様書駆動の新機能開発（要件→設計→タスク→実装）、もうひとつはバグ修正（報告→分析→修正→検証）を、それぞれユーザーとの対話を通して具体化しながら回せることにあります。 他の仕様書駆動開発を行う取り組みと比較して優れていると感じた点は主に三点あります。 claude-code-spec-workflow 自身がサブエージェントによる自己レビュー機能を持っており、ユーザーレビュー前に自律的に仕様書を改善する 実装計画を元に小規模な task 単位に分割されたカスタムコマンドを生成する。このカスタムコマンドを実行するとサブエージェント内で task を実行します。このためコンテキストを圧迫せず、AI エージェントの暴走も引き起こしにくい点において優れています ダッシュボードで進捗や仕様の情報を GUI で確認できる  要件・受け入れ基準の到達度や未完タスクが可視化されます claude-code-spec-workflow の利用例 claude-code-spec-workflow の利用例のデモとして、Obsidian のサンプルプラグインを改修して「コマンド実行で、日付・時刻を挿入する」プラグインを作っていきます。 claude-code-spec-workflow の導入 claude-code-spec-workflow の導入は簡単です。 npm i -g @pimzino/claude-code-spec-workflow グローバルインストールしたうえで、実装対象のプロジェクトのディレクトリルートで、 claude-code-spec-workflow を実行すると、必要なカスタムコマンド・テンプレート・エージェントが導入されます。 仕様書の作成 Claude Code を起動したうえで、仕様書の作成を指示するコマンドを実行します。 /spec-create timestamp “このサンプルプラグインを改修して以下の要件を満たすようにしてください – コマンドを実行することで現在カーソルが選択している場所に現在の日付・時刻を`2025年8月19日 15:30` の形式で入力する” このコマンドで Claude Code は、.claude/specs/timestamp に requirements.md（ユーザーストーリーと受け入れ基準）を作成し始めます。  余談ですが、Claude Code をずんだもんっぽい喋り方をするように設定しています。 頓珍漢なことをしても「まあずんだもんだしなぁ」と思えるだけでなく、コンテキストが長引いたときにずんだもんの人格が消えることがあるので、/clear の目安を知らせる「炭鉱のずんだもん」として活躍しています。 作成後はサブエージェントによるレビューが走り、改善したものをユーザーに提案します。ユーザーは作成された requirements.md を確認して適宜修正の指示を出し、最終的に承認します。  *spec-requirements-validatorが品質改善を先に行うため、開発者がレビューしやすくなります  この時点で受け入れ基準が具体化し、後工程の事故を減らす土台になります なお、claude-code-spec-workflow が .claude/templates/ に生成する仕様書テンプレートは英語です。標準のままでも動きますが、英語交じりの仕様書になるためテンプレートを日本語化しておいたほうがレビューしやすいでしょう。 design.md（アーキテクチャやシーケンス、設計上の注意）、tasks.md（実装計画）についても同様に生成・レビュー・承認のフローを実施します。最終的に実装計画が完成すると、claude-code-spec-workflow は tasks.md の実装タスクに基づいてカスタムコマンドを生成します。  生成されたカスタムコマンドのリスト カスタムコマンドの実行による実装 いよいよ実装を開始します。tasks.md に書かれたタスクはカスタムコマンドとして生えるので、/timestamp:task-1、/timestamp:task-2……のように順番に実行するだけで実装が進みます。これらの実装もサブエージェント内で実行されるため、コンテキストの圧迫を抑えつつ、1 コマンド ＝ 1 目的で因果を追いやすいのが特徴です。  カスタムコマンドはサブエージェント内で実行されます 全体の進捗は /spec-status timestamp で確認できます。ダッシュボード側でも、どのタスクがどこまで進んだかが一覧できます。 最後までタスクを実行することで、プラグインを完成させることができます。 実際に使用してみての感想 2 週間ほど claude-code-spec-workflow を使った仕様書駆動開発を進めてみて、一番の効果は「今 AI が何を意図して何を作業しているのか」が理解できることにあったと感じています。作業がタスク単位のカスタムコマンドに分かれるため AI エージェントの暴走や寄り道が激減し、もしも寄り道してもユーザーが事前に作業を認識しているためすぐに気づいて訂正できるようになりました。 また実装の意図・作業が仕様書という形式で残る点も優れています。大規模開発で「以前実装された特定の機能の実装意図がわからない」というのはよくある経験でしょう。しかしこの仕様書を何らかの形で残しておけば、実装意図の把握に大きく役立つでしょう。理想としては、開発フローに組み込み、Git の管理下に置いて参照しやすくすると活用が進むと考えています。 一方で欠点もいくつか感じました。例えばタスクの数が増えやすい（中規模の機能だと 10 個程度）ため、カスタムコマンドの実行が面倒になる場合があります。これは tasks.md を作る時点で細かすぎるタスクをまとめるよう指示することで軽減できます。tasks.md のレビュー時には粒度が細かすぎないかも見ておくと良いでしょう。また AI が過度に厳しいテストや性能要件を掲げたり、大規模リポジトリの改修では現実的に実装が困難なテストを実装しようとするケースもあります。こちらについても design.md・tasks.md のレビューで現実的なラインに落とすことが必要です。 またツールの便利さだけでなく仕様書駆動開発というアプローチそのものもとても新鮮に感じました。AI エージェントの開発においてテストを通して仕様を具体化する設計手法としてテスト駆動開発をさせようという取り組みもしばしば見かけます。この文脈において、仕様書駆動開発が AI エージェント特有の仕様を具体化する設計手法としてテスト駆動開発と代替、もしくは共存できるケースも多いのではないでしょうか。 余談：claude-code-spec-workflow の MCP 版が開発中のようです spec-workflow-mcp というclaude-code-spec-workflow の MCP が現在開発中で、今後はこちらに移行していくようです。私は spec-workflow-mcp を試していないため、カスタムコマンドやエージェントで実行する claude-code-spec-workflow と同等の機能が提供されているのかは把握できていません。ですが、今から導入してみるほうはこちらを試してみるのも良いでしょう。MCP なので Claude Code 以外からでも使えるのが魅力です。 おわりに 仕様書駆動開発、そしてclaude-code-spec-workflow は、AI 時代の開発にありがちな「何をしているかわからないまま猛スピードで突き進む」を「事前に合意した仕様を土台に素早く進む」へ寄せてくれる手法だと感じました。手法自体はシンプルですが効果は実感しやすいはずです。冒頭で触れたような AI エージェントの難しさを感じたことがある方は、ぜひ試してみてください。 # claude-code-spec-workflow # Claude Code # AIエージェント # Kiro # 開発効率化 s-yamashita12 1日前    関連記事  2025-08-19 弁護士ドットコムのAIコーディングツール活用の現在地（2025年8月版） こんにちは、CTO の田中（@stanaka）です。 最近は趣味で LLM …  2025-07-16 ドロップダウンメニューに対するアクセシビリティリンターを用いたAIコーディング比較 こんにちは、弁護士ドットコムでクラウドサインというサービス…  2025-06-26 Claude Code: VSCode のターミナルで実行中のタスク完了を OS 通知させたい クラウドサインのエンジニアをしている辻@t0daaayです。 Claude…  2025-06-09 TypeScript開発者が試すOrval活用術：OpenAPIからMCPサーバーを自動生成しCla… はじめに こんにちは、砂川(@misdo_tabeyo)です。 普段は『弁…  2025-05-30 TSKaigi2025 協賛&参加レポート こんにちは。技術広報のsakutaroです。 2025年5月23日(金)・24… Salesforce人事異動時のレポートライン変… » プロフィール  弁護士ドットコム (id:bengo4) はてなブログ for DevBlog 読者になる70 このブログについて 検索  検索 採用情報  リンク クラウドサイン note ~Inside~  Publication List (研究論文活動)  最新記事  2025-09-03 claude-code-spec-workflowで始める仕様書駆動開発  2025-09-01 Salesforce人事異動時のレポートライン変更とロール管理の作業手順  2025-08-29 恐怖！ ビルドされたnpmパッケージ内のd.tsにパスエイリアス(~)！  2025-08-27 AI への適切なタスク割り振りのためのコード品質可視化 〜カバレッジレポートとリンターの活用〜  2025-08-25 CRE × AI で「課題の真因」を解く — AIを活用した問い合わせの振り返りサイクル 月別アーカイブ ▼ 2025 2025 / 9 2025 / 8 2025 / 7 2025 / 6 2025 / 5 2025 / 4 2025 / 3 2025 / 2 2025 / 1 ▶ 2024 ▶ 2023 ▶ 2022 カテゴリー LLM活用 (20) フロントエンド (23) クラウドサイン (68) コーポレートIT (2) 弁護士ドットコム (31) バックエンド (6) エンジニアリング (10) CRE (4) 新卒採用 (7) AI (3) 弁コムな人々 (25) イベント・カンファレンス (24) SRE (9) アクセシビリティ (5) BUSINESS LAWYERS LIBRARY (1) 弁護士ドットコムLIBRARY (1) データエンジニアリング (3) データ本部 (1) お知らせ (1) セキュリティ (2) リーガルブレイン開発 (5) 弁護革命 (1) アドベントカレンダー (46) インターンシップ (2) 税理士ドットコム (3) QA (2) 部活動 (2) 情報ガバナンス本部 (1) 人事本部 (1) BUSINESS LAWYERS (1) Professional Tech Lab (1) © Bengo4.com, Inc. 2005″ https://creators.bengo4.com/entry/2025/09/03/080000#:~:text=%E3%81%93%E3%81%AE%E7%99%BA%E6%83%B3%E8%87%AA%E4%BD%93%E3%81%AF-,%E4%BB%96%E3%81%AE,-AI%20%E3%82%A8%E3%83%BC%E3%82%B8%E3%82%A7%E3%83%B3%E3%83%88%E3%81%A7%E3%82%82