スキルを43個作っても越えられない、仕様駆動開発の4つの壁

こんにちは、ラクス技術広報です。

開発本部では、各部署でのAI活用の取り組みを技術広報がインタビューし、記事としてお届けしています。今回お話を伺ったのは、楽楽請求開発部でバックエンド開発を担当する吉元和仁さんです。

楽楽請求のバックエンドチームは、昨年度の下期から仕様駆動開発（Spec-Driven Development、以下SDD）の導入を進めてきました。掲げた目標は「AIによる実装の完全自動化」です。

半年ほど回してみて、実装そのものは速くなりましたが、速くなったのは個人の作業で、チームとして再利用できる資産は積み上がっていませんでした。

この記事は成功事例の紹介ではありません。SDDを導入して4つの壁に当たり、一部のメンバーがClaude CodeのPlanモードでの開発に戻りはじめ、そこから打ち手を「SDDそのものの改善」から「SDDが回る環境の整備」へ切り替えるまでの、現在進行中の記録です。同じところで詰まっている方に、判断の材料として読んでいただければ幸いです！

なぜ請求のチームが、実装の自動化を目指すのか

楽楽請求は、請求業務を効率化するクラウドサービスです。請求業務には毎月必ず締めがあり、制度改正への対応も期日が決まっています。顧客の業務が止められない以上、改善を早く届けられるかどうかがそのまま顧客への価値になります。

SDDに取り組み始めたきっかけは2つでした。社内の別チーム（楽楽明細・楽楽自動応対）で先行して成果が出ていると聞いていたこと、そして全社としてAI活用を進める方針が出ていたことです。

フレームワークにはcc-sddを選びました。その理由を吉元さんはこう説明します。

「既存の設計ドキュメントと開発プロセスを作り変えずに導入できること、そして自社の工程やレビュー観点を組み込めること。この2点を最優先に評価し、cc-sddを採用しました。」

一方のcc-sddは、既存のプロダクトコードを起点に整合性を検証する仕組みを持っています。現行のプロセスやドキュメントを大きく作り変えずに導入でき、独自の工程やレビュー観点もSKILLを追加するだけで組み込める。稼働中のサービスに、既存の開発プロセスを活かしたままSDDを入れたいという狙いに、いちばん合っていたといいます。

目標として「実装の完全自動化」を掲げたときのチームの反応を、吉元さんはこう振り返ります。

「反対意見はありませんでしたが、前のめりに聞いてくれるメンバーもいない、という状況でした」

吉元さん自身、AIの進化が伴わなければ達成は難しい目標だと認識していたそうです。それでも掲げたのは、具体的にイメージできる目標を示さなければ、チームが同じ方向を向いて動きにくいと考えたためでした。

cc-sddに加えた5つのカスタマイズ

標準構成のままでは、自社の開発プロセスに乗りませんでした。現在までに加えたカスタマイズは、大きく5つあります。

1. 設計書をレイヤーごとに分割した

標準では設計を1枚の design.md にまとめますが、これをDB設計、ドメイン設計、API設計、その他設計の4ファイルに分けました。レイヤーごとにレビュアーが異なるため、各自が担当領域だけをレビューでき、完成した設計書から順にレビュー依頼を出せます。特に影響範囲の大きいDB設計を早い段階でレビューできるようになったことが、リードタイムの短縮と手戻りコストの抑制につながりました。

2. 工程ごとにプロジェクト固有のルールを読み込ませた

標準はプロダクト概要、技術スタック、ディレクトリ構成の3ファイルのみを前提にしています。これだけでは、命名規則やマイグレーション手順といった自社の規約が設計に反映されません。そこで各工程に、DB設計規約、API設計規約、実装ガイド、テスト実装ガイド、用語集といったルール集を必ず読み込ませるステップを足しました。

3. 大きな機能を親子構成で分割できるようにした

1機能が数か月規模になるとタスクを管理しきれません。大きな機能を要件のまとまりごとに親子構成で分割できるようにして、タスク管理のしやすさと、分業によるリードタイム短縮を両立させました。

4. AI向けと人間向けで設計書を分けた

design.md はAIエージェント向けの記述で、人間には読みにくいものです。しかも情報量が増えるとAIコーディングエージェントのコンテキストを圧迫し、生成物の品質が落ちます。そこで design.md はAIコーディングエージェント専用と位置づけ、人間向けにはHTML形式の設計書を別途生成する構成にしました。design.md はコンテキストを圧迫しない分量に抑える必要がありますが、人間しか読まないHTML設計書はその制約から外せます。図や表も使えるため、分量を割いて丁寧に書けます。
これは当初、詳細設計書の補助ツールという位置づけで入れたものでした。ところが開発者からのポジティブなフィードバックが多く、後述するとおり詳細設計レビューが一番のボトルネックになっていたこともあって、開発プロセス本体に組み込むことになりました。現在は詳細設計の担当者が、AIが生成した詳細設計書をレビューするタイミングで、HTML設計書を生成しています。

5. 独自スキルを追加した

仕様の分割、事前調査といった独自スキルを足していき、現在は43スキルを運用しています。

それでも残った、4つの壁

カスタマイズを重ねても、構造的に残る課題が4つありました。

品質の再現性

AIの生成物は確率的で、同じ指示でも実行のたびに違う結果が返ります。壊れているのにチェックが通ったり、通らなかったりする。

たとえばチームではAIによる自動コードレビューを導入していて、レビュー用のSKILLにコーディングルールやガイドラインを記述しています。ところがレビュー結果自体が確率的なため、1回のコードレビューですべての指摘を拾いきれない。ルールを書いたから守られる、という前提が成り立たないわけです。

レビューの肥大化

これは当初の想定と違っていた、と吉元さんは言います。レビューの総時間自体は、実は大きく変わっていませんでした。問題は別のところにありました。

AIが生成する詳細設計書には、コードの断片が埋め込まれることがあります。すると、レビュアーは詳細設計書のレビューに加えて、コードレビューまで同じタイミングで行うことになる。従来は詳細設計フェーズとコードレビュー（PR）フェーズに分かれていた作業が一箇所に集中し、レビューとフィードバックが直列につながってしまいます。結果としてリードタイムが長くなりました。

チーム内からは「これ全部見てたら、コードを見てレビューした方が早いんじゃないか」という声も出ました。

完了基準の不在

設計書の完了基準が決まっていない、という課題もありました。ここでチームは一度失敗しています。

人間による詳細設計書レビューの負担を下げようとして、「詳細設計書にコードを記述しない」「行数を500行に制限する」というルールを設けました。ところがその結果、設計判断に必要な情報が欠落したり、設計情報を聞き慣れない用語で圧縮したり、1行あたりの情報量が増えたりして、かえって認知負荷が高くなってしまったのです。

完了基準は「人がレビューしやすいか」と「AIハーネスとして機能するか」の両方から定義しないと決まりません。片方だけを見て基準を作ると、もう片方が壊れます。

プロセスの重厚さ

SDDのプロセスは重いため、小規模なタスクでは個別のツールを直接叩いた方が速い場合があります。

「Planモードのほうが速い」という声

4つの課題が残るなかで、チームからは「Planモードのほうが実装は速い」という声が上がるようになりました。実際にPlanモードで開発しているメンバーもいました。

吉元さんは、これ自体を悪いこととは考えていません。個人の生産性には確かに寄与していたからです。

引っかかったのは別の点でした。

「Planモードは設計内容等のコンテキストがセッション内に閉じてしまうため、規模の大きい開発案件ではスケールしません」

個人単位では生産性が上がる一方で、その成果や進め方が組織全体に展開されず、チームとして再利用できる資産が蓄積されていかない。「組織としてのスケールメリットが得られていない」と判断した決め手はここでした。

チームが目指しているのは「実装を自動化し、人間が上流工程へシフトする」という姿です。そこから逆算すると、Planモードへの回帰による効果は限定的だと感じた、と吉元さんは振り返ります。

打ち手を「SDDの改善」から「SDDが回る環境の整備」に変えた

そこで方針を切り替えます。SDDのプロセス自体をいじり続けるのをやめて、それが回るための環境を整える方向に戻る。取り組みは4つです。

取り組み	やること	対応する課題
ナレッジ化	ハーネスと暗黙知を体系化し、レビュー負荷を軽減して品質を底上げする	レビューの肥大化
出力の安定化	単一のAIに任せず、複数のエージェントが相互に評価し合う仕組みを整備する	品質の再現性
プロセス設計	SDDフレームワークを再定義し、タスクごとの適用基準と詳細設計基準を策定する	完了基準の不在、プロセスの重厚さ
基盤整備	ローカル依存から脱却し、AIエージェントが自律的に並列稼働できる実行基盤を作る	自動化の前提

レビュー指摘を、次に繰り返さない形に変える

出発点は「指摘がなかなか減らない」だった

背景にあったのは、暗黙知が多く、実装レビューでの指摘がなかなか減らないという問題でした。AIに実装やコードレビューを任せるうえでも、暗黙知を形式知にしてAIコーディングエージェントの品質の再現性を高める必要がありました。

取り組んだのが、PRのレビューコメントとIssueから繰り返し出ている指摘を集め、開発ガイドライン（Claude CodeのSKILL）に反映していくパイプラインです。社内リポジトリとして構築しています。

生データから知識へ、知識からSKILLへ

仕組みは3段階で、進むほど情報が絞り込まれます。

1. 集める（fetch）：PRのレビューコメント、Issue、Claude Codeのセッション情報を取得する
2. パターン化して残す（ingest）：繰り返し出ている指摘を、LLM用のWikiに蓄積する
3. ガイドラインへ上げる（promote → 承認 → apply）：条件を満たした指摘をSKILLに反映するPRを作る

これを週次で回し、月次で lint をかけて点検しています。
ちなみに、「1.集める」「2.パターン化して残す」「lint」というアイデアは、 Andrej Karpathy氏が「LLM Wiki」と呼んでいるパターンを採用しています。

「残す指摘」と「残さない指摘」を分けた

知識層に残すのは、確定した方針やルールがある指摘だけです。却下された指摘、「後続PRで対応」と先送りされたもの、返信がないまま流れたもの、未マージPR上の指摘は残しません。判断に迷うものは、残さない側に倒します。

直した証拠も決めた方針もない指摘をページにすると、実際には守られていないルールを知識として登録してしまうからです。知識層はAIが読む前提の場所なので、守られていないルールが溜まるほど、AIの実装がチームの実態から離れていきます。

SKILLへ昇格させる3つの条件

知識層からSKILLへ上げるときの条件は次の3つです。

1. 反復性：同じ指摘が3回以上、かつ指摘者が2名以上
2. 是正実績：実際に修正コミットが発生していて、かつ2回以上
3. 障害起因：incident / postmortem ラベル付きIssueの再発防止策なら1回で候補

この条件を置いた理由を、吉元さんはこう語ります。

「上がってきた指摘をそのまま採用すると、内容が具体的すぎたり、個人の設計スタンスが反映されたりして、AIのコーディングルールが膨大化し、品質に影響します。複数の指摘があることで、ルール化しにくい暗黙知を抽象化できると考え、この条件を設定しました」

1人の指摘なら個人の好みかもしれない。2人以上から同じ指摘が出ているなら、チームの規範として扱える。ルールが増えすぎて誰も守らなくなる事態を、この線引きで避けようとしています。

人間に残した仕事は「承認」と「マージ」だけ

取得も、抽出も、執筆も、起票もAIが行います。人間に残したのは、承認とマージの2つだけです。

では、なぜ全自動にしなかったのか。

「AIが出力する内容が、まだ承認なしで採用できる品質には至っていないためです」

そう説明したうえで、吉元さんは「LLMの進化に期待」とも付け加えます。現時点では、AIが提案してPRを作るところまでを自動化し、直接pushや自動マージはしません。

配布はPlugin Marketplaceに乗せた

作ったスキルは、別の社内リポジトリをClaude CodeのPlugin Marketplaceとして機能させ、/plugin install で各開発者に配布しています。自動更新を有効にしておくと、セッション開始後にバックグラウンドで最新のスキルを取得し、次にClaude Codeを立ち上げた時点で反映されます。各開発者が手動で更新する必要はありません。

このリポジトリを用意したのは、AI活用の事例を個人に閉じさせず、試して改善効果が得られた内容を共有する文化を作りたかったからでした。ただし全員が共有を始めると、開発プロセスに組み込まれているものとそうでないものの区別がつきにくくなります。そこで、安定運用の tools と試験運用の labs に分けています。

正直に言うと、まだ回しきれていない

ここまで紹介してきましたが、現状は道半ばです。

知識層のwikiには現在およそ700件が蓄積されています。一方、SKILLへの昇格は20件程度で、運用が十分に回っているとは言えない状態です。週1で回す設計にしているものの、そのサイクル自体をまだ回しきれていないといいます。

スキル修正提案のPRも大量に来ています。AIが投げたものと人が投げたものが混在した状態で、いまチームで手分けして選別しているところです。

工数削減については、詳細設計と実装の工程を対象に集計を始めており、段階的な削減を目標として置いています。手応えは出はじめているものの、継続して再現できるかはこれからの検証次第だと吉元さんは見ています。

他チームへの横展開にも課題があります。スキルの中にチーム固有のファイルパスやリポジトリパスが多く含まれているため、汎用的に使ってもらえる形にするにはもうひと段階のハードルがあります。

これから

基盤整備については、クラウド環境（Claude Code on the web）上での自動実装には対応済みです。ただし完全な並列実行には至っていません。実行環境の制約でビルドやテストの実行が難しいため、現状は「クラウド環境で実装してPRを作成する、CIでテストを実行する、結果を監視して修正する」という進め方を代替案として採っています。

最後に、同じところで悩んでいるエンジニアへのメッセージを吉元さんに伺いました。

「LLMの進化は速いため、それを見据えて、AI駆動開発の中長期的な戦略を立てるべきだと考えています」

目の前のプロセスを改善し続けても、半年後には前提が変わっているかもしれません。

品質の再現性、レビュー、完了基準、プロセスの重さ。楽楽請求のチームは、この4つを同時に潰す「環境」をいま整えている途中です。

開発本部では、他の部署でのAI活用の取り組みも順次記事にしてお届けしていく予定です。うまくいっていないことも含めて、また共有できればと思います。