2026.1.26

Claude Codeを用いたSDD開発の実践

技術

こんにちは！AIサービス開発室の鈴木生雄です。今回はAIコーディングエージェントの一つであるClaude Codeを用いたSDD（Spec Driven Development）を実践した際の所感をお届けします。SDDについては昨年11月に投稿した以下のエントリーで説明していますのでこちらもぜひお読みください。

AIエージェントを用いたSDDに挑戦

結論から言うと、Claude Codeは「ジュニアエンジニアレベル」というには無理があるくらい「優秀」です。もし、役に立たないという人がいたらそれはClaude Codeがダメなのではなくて、使う側である人間がやるべきことをできていないからだと思います。人間がやるべきこととは「開発環境（コードベース・手順・ルール）を整備してその秩序を守り続けること」です。そして、その実現を支援する開発手法がSDDだと考えています。

本稿では、Claude Codeを約3週間使ってみて、私が上記の感想を持つに至った経緯を記したいと思います。ちなみに私のエンジニアとしての自己評価は以下のとおりです。

SIのSE歴15年くらい。
プログラミング経験あり（Java、JavaScript、Bash）だけど得意ではない。フレームワークは作る側ではなく、使う側。
Gitの概念は理解しているが、コマンドは使いこなせない。
ITの知識レベルとしては、IPAのNW、DB、SC、SAを保有。

世の中には10代から「9-9-6」（週6日、午前9時から午後9時まで）でコードを書いて、20代半ばには10年分の実務経験があるエンジニアも存在するようですが、誰もがそんなスーパーエンジニアではないと思うので、凡人にもわかりやすいをモットーに等身大で書いてみたいと思います。

制作物の紹介

開発の内容に入る前にまずは作ったものを紹介させてください。特筆すべき点は、私はこれらの制作物を開発するための要素技術をほとんど知らないという点です。お客様に提供するシステム開発においてはそれではダメ（後でも述べますがレビューできないからです。）なのですが、個人利用のツールであれば簡単に作れてしまいます。

DocFlow

PDF や画像をAIフレンドリーな Markdown 形式に変換するデスクトップアプリケーション

技術スタック：Electron / TypeScript / Node.js / React / CodeMirror / Mistral OCR API
レポジトリ：GitHub – ikuo5710/DocFlow

daily-english-gym

AIニュースで毎日英語スピーキング力を鍛えるWebアプリケーション

技術スタック：TypeScript / Node.js / Vue.js / Hono / OpenAI API (GPT-5.2, TTS, Transcribe)
レポジトリ：GitHub – ikuo5710 / daily-english-gym

Claude Codeとは

Claude Codeとは、Anthropic社が自社のAIモデル「Claude」を使って、実際にコードを書いたり修正したり、開発作業を進めるための「開発者向けツール」（AIコーディングエージェント）です。2025年5月に一般提供されて以来、多くの開発者の支持を得て、今や最も人気があるAIコーディングエージェントです。ちなみに、その他、OpenAI社のCodexやGoogle社のGemini CLI等があります。（ちなみに、私は昨年7月にGemini CLIを使ってちょっとしたツールを作成したことがあります。）

Claude Codeの機能

ここでは最低限のみ記載します。より網羅的かつ詳細な情報が知りたい方は、Claude Code Docs をご参照ください。

基本機能

ターミナル常駐のCLI … ターミナルから自然言語による対話でタスクを依頼できる。
内蔵ツール … ファイル操作・検索・実行・Webアクセス等のタスクを実行するための基本ツールセット。

コンテキスト管理

CLAUDE.md … プロジェクトのルールや背景知識をClaude Codeにコンテキストとして渡すためのMarkdown形式の文書。
Skills（Slash Command） … Claudeに特定の専門知識や手順を覚えさせるMarkdown形式の文書。Slash Commandはユーザーが明示的にSkillsを呼び出すための手段。元々は別々の機能だったが、v2.1.3で両者は統合された。

分業と自動化の仕組み

Subagents … タスク特化の専門家エージェントを作ってタスクの一部を委譲できる。（大元のClaude Codeとは独立したコンテキストで動かせる）
Hooks … 特定のタイミング（e.g. ファイル編集後）で必ず動作させる決定論的な自動化ができる。SkillsはClaude Codeが確率推論的に実施判断をするに対して、Hooksは決定論的な点が異なる。

外部ツール連携

MCP（Model Context Protocol） … 最新文書参照/ブラウザ操作/E2Eテスト等の外部ツールを利用できる。

Claude CodeによるSDDの実践

Claude CodeによるSDD（Spec Driven Development）の実践に入る前に、前回のブログでも記載したSDDの定義を再掲しておきます。

SDDとは、AIエージェントとの協働を前提に、まず仕様（What/Why）→計画（How）→タスク化→AI実装という流れで随時文書を作成（あるいは更新）しながら開発を行う開発手法です。

やってみて分かったのですが、SDDの肝は自然言語によるプロンプトと先に紹介したようなAIコーディングエージェント（今回の場合はClaude Code）の機能を駆使して、上記の開発のライフサイクルを効率的に実行するところにあります。

なお、前回のブログでは、GitHubが提供するspec-kitというフレームワークを紹介しましたが、今回は勉強のために購入した実践Claude Code入門―現場で活用するためのAIコーディングの思考法（株式会社ジェネラティブエージェンツ著）がとてもわかりやすかったので、同書籍内で紹介されているフレームワーク（以降、単にF/Wと記します。）を使うことにしました。

株式会社ジェネラティブエージェンツのレポジトリ
GitHub – GenerativeAgents / claude-code-book-chapter8

なお、spec-kitは汎用ツールキット（15以上のAIエージェント対応）として提供されているのに対し、このF/WはClaude Code向けに特化した実装という違いがあるものの、「自然言語プロンプトで開発ライフサイクルをAIコーディングエージェントに指示する」という本質は同じです。

具体的な手順

F/WによるSDDのライフサイクルは以下のとおりです。初回に1.のドキュメント作成をおこない、2回目以降は2.～5.を繰り返します。

ドキュメント作成（「何を作るか」と「どう作るか」を以下の文書で定義する）
製品要求仕様書（PRD） / 機能設計書 / アーキテクチャ設計書 / レポジトリ構造定義書 / 開発ガイドライン / 用語集
作業計画（1.のドキュメントに基づき「今回何をするか」を計画する）
実装（2.の作業計画に基づき実装する）
検証（3.の実装をテストする）
更新（作業を振り返って、適宜、ドキュメントを更新する）

F/WにはこれらをおこなうためのCLAUDE.mdと、作業開始のトリガーとして独自のSlash Command（とその中で使われるskills）が複数定義されています。

CLAUDE.md

Claude Codeのセッション開始時に自動で読み込まれるCLAUDE.mdにSDDのF/Wとしての全体像が記載されています。以下はその一部分を抜粋したものですが、これをみると/setup-projectでドキュメントを作成し、/add-featureで個別機能を実装する手続きが記されています。（CLAUDE.mdの全文はこちら）

### 初回セットアップ

1. このテンプレートを使用
2. `/setup-project` で永続的ドキュメント作成(対話的に6つ作成)
3. `/add-feature [機能]` で機能実装

/setup-project

1.ドキュメント作成をおこなうSlash Commandです。元ネタの文書があればそれに沿って、なければClaude Codeが上手にインタビューをしてくれる（ちなみに、AskUserQuestionToolという機能らしいです。）のでそれに応えると、製品要求仕様書（PRD）を作成してくれます。できた製品要求仕様書はレビューをします。もし問題があればClaude Codeとの対話で洗練させることももちろん可能です。製品要求仕様書が固まったら、それを基にして設計書類を作成するフローが流れます。

/add-feature [タスク内容（機能名など）]

2.作業計画～5.更新をおこなうSlash Commandで実装内容を引数に取ります。タスク内容は製品要求仕様書に記載されたのと同じ単語で指示すれば通じます。実装の事前に、作業計画として「要求内容」(requirements.md)「設計」(design.md)「タスク（TODO）リスト」(tasklist.md)の文書が作られ、その文書に沿って、実装→Subagentによるレビュー→自動テスト→振り返りというフローが流れます。

つまり基本的に人間は、初回に/setup-projectでドキュメント作成をおこない、2回目以降は/add-featureによってタスクを段階的に渡すだけで実装作業がおこなえます。ただし、その後に出来上がってきた成果物のレビューは人間がおこなう必要があります。（出荷責任は人間にありますから当然ですね。）

気づいた点

ここでは、みなさまにとってClaude Codeを深堀調査するためのフックになることがあればいいなという思いで、気づいた点を徒然なるままに書いてみます。

イシュー管理がカギ

今回使ってみたSSDのF/Wには、特定のフォルダ（.steering/）以下に作業単位でフォルダを切って、その中に「要求内容」(requirements.md)「設計」(design.md)「タスク（TODO）リスト」(tasklist.md)の文書を作ってタスク（イシュー）管理をするようになっているのですが、これだと二つの点で不都合があると思いました。

イシューとソースコードの関連付けを後から追跡できない

GitHubであれば、Issueに対するPR(Pull Request)を関連付けることができるのですが、ローカル管理だけだとこの関連付けができません。この点はClaude CodeにIssueの発行とPRの作成を指示して、人間がMergeするという流れを作ればよいのかなと思っています。正直言って個人向けツールだと面倒なだけですが、継続的に保守をする本格的なシステム開発では関連付けは必要だと思います。なお、以下はGitHubでそのとおりにやってみたときのログです。

feat: ページ遷移時の生成済みコンテンツキャッシュ機能を実装 #2

コンテキストウィンドウに情報が乗り切らないことがある

Claude Codeの頭脳に当たるClaudeでは、コンテキストウィンドウと呼ばれる短期記憶容量が決まっています。（これはClaudeに限った話ではなく、GPTもGeminiも同様です。）そのため、新しいセッション開始時には改めてCLAUDE.md等の文書や関連するソースコードを読みこませてタスクの内容を把握させる必要があります。また、大きなタスクの場合には、コンテキストウィンドウに載るように小さな複数のタスクに分割する必要があります。しかし、この分割したタスク同士が関係を持っている場合に、問題が起こる可能性があります。例えば、Aの実装をする際に、後からBの実装を追加できるようにAを実装しなければならない場面で、Aのことしか短期記憶に載っていないと当然Bのことは度外視した実装になってしまいます。

こうしたタスク間の関係性の申し送りは、Markdownによる文書で引き継ぐようにすることで実現することも可能ですが、新規セッションで始めたときはそのMarkdownが読まれるかどうかは確率推論的になりますし、同一セッション内であってもコンテキストの残容量次第ではあふれる可能性があります。（なお、コンテキストを圧縮する/compactという仕組みもありますが、自然言語を要約するという仕組みから圧縮効果は限定的なのではないかと思っています。完全に個人的な推察です…。）いずれにしても、なかなか悩ましい問題ですが、これについては「Beads」という「AIコーディングエージェントのための外部記憶（メモリ）兼タスク管理ツール」が役に立つかもしれません。軽くみてみたところ、Beadsではグラフ構造を持ったJSONLというAIフレンドリーな形式でタスクを管理するようなので、自然言語に比べて関係把握の確実性が高く、コンテキストウィンドウの消費量も少ないのではないかと期待しています。Beadsについては今後に検証してみたいと思っています。

GitHub – steveyegge / beads

レビューできないとエージェントに言われるがまま

これは先の点とは種類が異なるより根本的な問題です。Claude Codeが作成する成果物（文書、コード）をレビューする技術力がないと、当然ながら人間の役割である出荷責任を果たせません。今回の場合、私はTypeScriptは全く書けないですし、Node.jsのエコシステムもほとんど知りません。そのため、Claude Codeが成果物を提出してきた際に、ほとんどの場面で「Yes」以外言えませんでした。結局のところ、設計力や実装力がないとダメなのです。ただコードを書くだけならAIに任せればよいため、今後、システムエンジニアに対する技術力の高度化の競争圧力は増していくことになりそうです。当社にとっても大きな課題だと感じています。

まとめ・所感

最初に述べたように、今のClaude Code（頭脳はClaude Opus 4.5）を「ジュニアエンジニアレベル」というのは無理があると思います。コードベースや規約、手順の品質が悪い、または、それらが存在しないとClaude Codeの成果物の品質も悪くなりがちという話だと思うのですが、それをもって、まだ「ジュニアエンジニアレベル」なんていう人がいたら、それはお門違いだと思います。

このことが身に染みたということを臨場感を持って伝えたかったのですが、読み返してみると満足する文章にはなっていないなあと思いつつも、力尽きました…。そこで月並みではありますが、百聞は一見に如かずという諺を持ち出して、ぜひやってみることをおすすめします。AIほど世界中が投資をしている分野はありませんので、今後も信じられない速度で進化するものを思われます。実際のところ、Claude CodeがGA（一般提供）されたのは昨年5月であることを考えると恐ろしいです。煽り気味ですみませんが、「エアプ（レイ）している猶予はないぞ。」と言いたい気持ちです。

追加検証のバックログ

結構、危機感を持っているので、今後も検証を続けていきます。

AIコーディングエージェントに合ったイシュー管理（「Beads」を試す）
E2Eテストの実行（「Playwright MCP」を試す）

GROUP