【20260319 AI×DevOpsStudy #8】POSシステム開発におけるClaude Codeエージェント設計と成果物の差分検証

■AI×DevOps Study #8 の概要
2026年3月19日に開催した「AI×DevOps Study」第7回の勉強会資料です。

「AI×DevOps Study」は、AI駆動開発やそこに関係するマイクロサービスについて理解を深める場になります。
株式会社ScalarではAIを使ったチーム開発を進めており、参画しているメンバーや協力会社の方から、具体的なAI駆動開発を実施する方法、その中で生まれたマイクロサービスアーキテクチャを使用したAI駆動開発の事例や実際に使えるエージェントについてお話頂き、参加者の皆様と知識の共有や交換を目的としています。
（弊社製品であるScalarDBも絡んだお話も一部出てきますが、汎用的な内容となっておりますのでフラットにお楽しみいいただけます）

■今回のテーマ
「POSシステム開発におけるClaude Codeエージェント設計と成果物の差分検証」

複雑な要件下でのAI駆動開発において、個人のプロンプト力に依存せず、 チーム全体で高品質なコードを安定して出力するための「エージェント設計（ガードレール構築）」に焦点を当てます。

1. イントロダクションとエンジニアの役割の変化
AI能力の脱・属人化：AIによるコーディングが普及する中、個人の「プロンプト力」によるアウトプット品質のバラツキが新たな課題となっています。
新しい開発スタイル：AIを単なる「実行役」とし、人間は「コンテキストとガードレールの設計」に責任を持つという、これからのエンジニアの役割のシフトと、チーム全員が一定品質を出せる仕組み作りについて提示します。

2. Vibe Codingの限界と「エージェント設計」の必要性
複雑な要件への対応課題：ScalarDBを用いた分散トランザクション（2PC）やマイクロサービス構成といった高度なアーキテクチャにおいて、事前のコンテキスト共有がない単なるAIへの指示出し（Vibe Coding）では、解釈のブレや規約違反が発生しやすい問題を解説します。
暗黙知の明文化（仮説）：プロジェクトの暗黙知をClaude Codeのプロジェクト設定（.claude/）に明文化し、絶対ルール（rules/）と標準ワークフロー（skills/）を持たせる「ガードレール設計」の有効性について説明します。

3. デモ検証：ガードレール設計による成果物の差分（Before/After）
差分比較デモ：POSシステム（在庫引当・決済等の注文サービス）の実装を題材に、「設定を持たないClaude Code（Before）」と「プロジェクト設計を反映したClaude Code（After）」に対して同一の指示を出し、出力を比較します。
検証のポイント：株式会社ScalarやEvery社のツールを活用しつつ、OCCリトライロジック、分散トランザクションのシーケンス、独自の例外処理規約などが、設定の有無でどれだけ正確に実装されるかを実演します。

4. 結果と考察：設定ファイル（.claude/）の資産化
設計が品質に直結する：デモの結果を通じて、エージェントの「設計（作り込み）」がいかに成果物の品質向上とブレの排除に直結するかを実証します。
チーム資産としての運用：整備された .claude/ ディレクトリが、単なる設定ファイルを超えて「プロジェクトの資産（チームの共通言語）」として機能し、持続的な品質担保に繋がることを考察としてまとめます。

■登壇者情報（敬称略）
鹿島司
札幌の株式会社マーベリックスでWebエンジニアとして勤務しています。フロントエンド領域を得意とし、主にReactの経験が豊富です。 AI駆動の開発案件にジョインし、今回のPOSシステムの開発を通じて「AIとの協働をいかに効率よく行うか」について現場のエンジニア目線で実践と探究をしています。

中堀翔太
札幌の株式会社マーベリックスでWebエンジニアを務めています。 JavaやAWS、フロントエンドなど、要件定義から保守まで一貫して担ってきた経験を活かし、現在はAI駆動型の開発案件にて、コーディングエージェントを活用したバックエンド開発を担当しています。 マイクロサービスやScalarDBを用いた分散トランザクションといった複雑な実装に対し、AIといかに協働して挑むかを実践しています。

箱崎一輝
札幌の株式会社マーベリックスで、Webエンジニア兼リーダーを務めています。 これまで社内のGoogle Workspace全社導入を推進し、組織の働きやすい環境づくりに貢献しました。 今年からはAI駆動型の開発案件に本格的にジョイン。リーダーとしてチームをまとめながら、実際の現場で「AIをどうUI/UX開発に組み込むか」、日々の実践を通じて探求しています。

Transcript

1. POSシステム開発における Claude Codeエージェント設計と 成果物の差分検証 2026/03/19 株式会社マーベリックス 中堀 翔太、⿅島 司
2. 発表者 ⾃⼰紹介① • ⽒名：中堀 翔太 • 株式会社マーベリックス • Webエンジニア（主にバックエンド） 約13年 • AI活⽤歴：約半年 ◦ Cursor / Claude Code ◦ Google Workspace（Gemini） 2
3. 発表者 ⾃⼰紹介② • ⽒名：⿅島 司 • 株式会社マーベリックス • Webエンジニア（主にフロントエンド）約5年 • AI活⽤歴：約半年 ◦ Cursor / Claude Code ◦ Google Workspace（Gemini） 3
4. 今回のアジェンダ • 背景 ◦ AI駆動開発でチーム全員が "⼀定品質を出せる仕組み作り" • 課題 ◦ 同⼀のClaude Codeでも設計次第で "出⼒内容に統⼀性がない" • 仮説 ◦ "AIへのガードレールと⼿順書" を整備すれば解決できるのではないか • 検証‧結果 ◦ "AIへのガードレール整備‧⼿順書整備" の効果を Before/After で検証 • 考察と展望 ◦ 属⼈化ではなくなることを実証し、"チームへの展開⽅法" を考える 4
5. この発表で伝えたいこと • プロジェクトの暗黙知を型に落とし込んでAIに渡せば、AIの出⼒は安定する • AIの挙動は環境（コンテキスト）次第。ガードレールを設計し、迷わせないのが⼈間の役割 5
6. 背景 6 このPOSシステムができるまで
7. POSとは？ POS（Point of Sale）= 商品が売れる瞬間を管理するシステム コンビニやスーパーのレジがイメージしやすい 今回デモ開発したのは以下の通り • 中規模⼩売店を想定したマイクロサービス型 POS デモアプリ • 顧客：バーコードスキャン → 在庫確認 → ⽀払い → レシート発⾏ • 管理者：商品‧在庫管理、売上確認 • 商品‧在庫‧注⽂‧⽀払‧レシートの 5 サービス構成 7
8. マイクロサービスアーキテクチャとは？ システムを「⼩さく独⽴したサービスの集まり」とし て構築する設計⼿法 • モノリス（従来型） ◦ 全機能が1つのアプリにまとまっている ◦ 変更‧スケールが全体に影響する • マイクロサービス ◦ 機能ごとに独⽴したサービスに分割 ◦ サービスは互いに連携して1つのシステム を構成する ◦ 今回の POS は商品‧在庫‧注⽂‧⽀払‧ レシートの 5 サービスが該当する 8 モノリス/マイクロサービスのイメージ図 出典：https://mercart.jp/contents/detail/85
9. 開発の背景：2回⽬のPOS開発 9 人がすべて開発した場合（推定） POS 1回目（AI駆動） POS 2回目（今回） 期間 推定 6〜9ヶ月 約3ヶ月 約3週間（2/18〜） 工数 推定 1,220時間 約 900時間 約 56時間 1回⽬の課題： AIが⽂脈なしにコードを⽣成すると、OrderService が責務過多な巨⼤クラス化し 「物理的には分散‧論理的には密結合」な分散モノリスになっていた 2回⽬のアプローチ： 計画フェーズを⾒直し、設計段階で分散モノリスを防ぐ構造を整えた上で再開発。 ただし、実装品質のブレという新たな課題が浮上した ℹ この発表は「2回目をどう設計したか」の記録でもある
10. フェーズごとの担当分担の変化 10
11. 利⽤ツール① coding-agent-for-scalardb • 株式会社Scalar 深津さん開発の Claude Code 向けツール https://github.com/wfukatsu/codin g-agent-for-scalardb • ScalarDB 設計ドキュメント （Phase1〜4）を⾃動⽣成 11 ⾃ 動 ⽣ 成 https://zenn.dev/scalar_sol_blog/articles/d29e83ccd61209
12. 利⽤ツール② compound-engineering-plugin • Every社が提唱する 「作るほど開発が加速する」 開発⼿法のClaude Code 拡張プラ グイン https://github.com/EveryInc/co mpound-engineering-plugin • 4ステップのループで AI の学びを チームの資産として蓄積する 12
13. 利⽤ツール② compound-engineering-plugin • 計画 (Plan) ◦ AIが課題を調査し、詳細な実装計画を策定 ◦ 構築前に⼈間とAIで「何を作るか」の共通認識を築く • 実⾏ (Work) ◦ AIが計画をToDoに分解し、⾃律的にコーディングとテストを遂⾏ ◦ 私たちは指⽰と⾒守りを担当する • 評価 (Review) ◦ 私たちとAI（複数のサブエージェント）が成果物を多⾓的に検証 ◦ 単なる動作確認だけでなく、得られた教訓も抽出する • 複利化 (Compound) ◦ このループの核⼼部分 ◦ 抽出した教訓を指定のディレクトリに永続化し、チームの共通資産とする 13
14. POSシステム概要 • 13リポジトリ構成（5マイクロサービス + フロントエンド + BFF + 共有ライブラリ + インフラ） • 各サービスは独⽴してデプロイ可能なマイクロサービス設計 14
15. 本システムの技術スタック 15 カテゴリ 技術 AI コーディングエージェント Claude Code, モデル：Claude Sonnet 4.6 / Haiku 4.5 バックエンド Java 21 / Spring Boot 3.2.5 DB ミドルウェア ScalarDB 3.16.0 データストア PostgreSQL / Cassandra / DynamoDB BFF Hono（Node.js / TypeScript） メッセージング Apache Kafka インフラ Docker / Kubernetes
16. ScalarDB概要 • 異種 DB をまたいで ACID トランザクションを実現する DB ミドルウェア • DBミドルウェア固有の書き⽅（OCC/2PC）があり、通常の Spring コードとは異なる 16 出典：https://scalardb.scalar-labs.com/ja-jp/docs/latest/overview
17. なぜ ScalarDB を使うのか • 並列開発：サービス間の独⽴性が保たれ、複数 AI エージェントが同時に実装できる ◦ 各サービスが独⽴したスキーマを持つため、他サービスの変更を気にせず実装を進められる • トランザクション保証：複雑な Saga/TCC を書かずに、サービスをまたいだ整合性を保てる ◦ AI エージェントは例外処理が苦⼿で、Saga/TCC の補償処理まで指⽰するとオーケストレータを含む⼤きなコン テキストが必要になる ◦ ScalarDB の 2PC を使うと AI は「呼び出すだけ」で整合性が保証され、コンテキストを⼩さく保てる • 境界の保護：ScalarDB 経由のアクセスに限定されるため、AI がサービス境界を越えにくい ◦ 他サービスの DB が⾒える状態だと、AI が直接アクセスして境界を壊してしまうことがある • 環境差異の吸収：異種 DB を抽象化することで、ローカル〜本番の差異を最⼩化できる ◦ ローカルは OSS の PostgreSQL/Cassandra、本番はクラウドサービスを使っても同じコードで動く 17
18. 課題 18 同じAIなのに、なぜ差が出るのか
19. plan があっても参照は保証されない • CLAUDE.md に plan の場所（output/phase1/ 〜 phase4/）は記載されている ◦ Claude は「plan がどこにあるか」は知っている • ただし「知っている」≠「必ず読む」 ◦ 実装タスクが来たとき、plan を読むかどうかは Claude がその場で判断する • コンテキストが⼗分に⾒えていると判断した場合、読まずに実装を進めてしまう • 「必ず plan を読む」という仕組みを設けていないため、読むかどうかは Claude 次第で ブレる 19 ⚠ 場所を知っている ≠ 必ず読む。確実性がないことがブレの原因
20. 知っている ≠ 必ず読む 20
21. 仮説 21 AIへの設定を整備すれば変わるのでは
22. AI設定の整備の⽅針 「Claude 次第」の余地を減らし、「必ず読む」状態を設計することを⽬指した • rules/：paths 条件で該当ファイルを触ったとき⾃動読み込み ◦ 実装中に制約が確実に伝わる • skills/：「いつ使うか」のトリガーを description に明⽰ ◦ AI が⾃律的に参照タイミングを判断できる ◦ 特に「ユーザーが実際に⾔いそうな⾔葉」を含めると スキル名を知らなくても AI が能動的に選択できる 22
23. AIへの指⽰書置き場（.claude/） • Claude Code が会話開始時‧ファイル編集時に⾃動で読み込む設定ディレクト リ • 「このプロジェクトの常識」を AI に教えるための場所 • ここに書いた知識‧ルール‧⼿順が、AI の判断基準になる • つまり `.claude/` の中⾝が、AI の出⼒品質を決める 23 ℹ .claude/ の中身を設計することが、AI の出力品質を決める
24. .claude/ の構成 • rules/：17ファイル • skills/：実装前準備‧ノウハウ永続化などのワークフロー定義 24
25. .claude/ の中⾝：何を⼊れるか 25 機能 定義するもの 使うとき CLAUDE.md 前提条件 常に適用されるプロジェクト全体の設定やルールを定義したいとき Subagents どんな専門家か 特定の領域（コーディング、テスト等）を専門とする人格に委託・並列 実行させたいとき Skills どうやるか 複雑な手順、専門知識、ベストプラクティスを具体的に定義して再利 用したいとき Commands 何をやるか よく使う定型的な指示を短縮コマンドとしてまとめたいとき Rules パス別の前提 特定のディレクトリやファイル種別ごとに異なる設定やルールを適用 したいとき • 今回の発表では rules/ と skills/ を中⼼に解説します。 • 出典：https://speakerdeck.com/scalar/2-dezaintoshi-zhuang?slide=34
26. AIへのガードレール設計（rules/） • DBミドルウェア固有の制約‧コーディング規約‧アーキテクチャパターンを記 述する • AI は「知らない」だけで制約違反コードを⽣成する。知識を渡せば防げる • フロントマターの paths 条件でファイル編集時に⾃動読み込みされる仕組み • 本プロジェクトでは17ファイル • ⼀度書けばチーム全員‧全モデルで再現できる 26
27. rules/ 設計事例①：リポジトリ実装 • ルールファイル：repository.md • 仮説との紐づけ：DBミドルウェア 固有 の知識がなければ、AI は Spring Data JPA で実装してしまう • 例）ScalarDB ではリポジトリを Spring Data JPA ではなく ScalarDB API で実装 する必要がある 27 paths 条件にマッチした場合のみ⾃動で読み込まれる
28. rules/ 設計事例②：複数サービスをまたぐデータ更新 • ルールファイル：two-phase-commit.md • 仮説との紐づけ：複数サービスにまたがる取引の⼿順 を知らなければ、AI は途中のフェーズを省略してしま う • 例）注⽂確定では begin → join → prepare → validate → commit の全フェーズを踏む必要がある 28
29. skills/ とは：AIへの⼿順書置き場 • SKILL.md に「いつ使うか（トリガー）」「何をするか（⼿順）」「何を出す か（出⼒）」を定義する • 3ステップ以上かかる、複数ファイルをまたぐ、専⾨知識が必要な業務が対象 • スラッシュコマンド（/skill-name）で呼び出すと、AI が毎回同じ⼿順で実 ⾏してくれる • rules は「やってはいけないこと」を守るガードレール、skills は「やるべき⼿ 順」を定義するワークフロー 29
30. skills/ 設計事例①：実装前準備スキル • スキル名：/impl-prep • 実装開始前に実⾏するだけでよい • 設計ドキュメントから DBミドルウェア 固 有の実装パターンを⾃動で抽出してくれる • トランザクション境界‧ API の使⽤パターン‧ リポジトリ設計をサマリー出⼒ 30
31. skills/ 設計事例②：ノウハウの永続化スキル • スキル名：/solutions-reflect • 実装中に解決した問題とその解決策をド キュメントとして記録しておく • スキルが記録内容を分析し、rules/ や skills/ へ⾃動で落とし込む • ⼀度解決した問題はルール化され、同じミ スが繰り返されない 31
32. 検証‧結果 32 設定の効果を検証する
33. 今回の検証の前提とスコープ • 対象は5サービス（order / product / inventory / payment / receipt） • 変える条件は .claude/rules/ と .claude/skills/ の有無だけ • モデルは Claude Haiku（最軽量モデル）固定、各5回試⾏、コマンドは 実装コードの⾃動⽣成 のみ • 評価スキルで8観点チェック、5サービス × 各5試⾏ × before / after 計50回分 • 動作テストやコードレビューは対象外 33 判定 意味 PASS 実装計画の仕様を満たしている CONDITIONAL PASS 方向性は正しいが仕様と一部食い違う（要改善） FAIL ScalarDB の制約を根本的に誤っており、本番で障害・データ不整合に直結する
34. 評価の8観点（前半） 34 # 観点 概要 rules, skillsなしの場合 1 TX管理 トランザクションマネージャーの使い分け @Transactional を全処理に一律適 用 2 OCC リトライ 競合例外の種別キャッチとリトライ制御 汎用 Exception で一括処理・リトライなし 3 CRUD API Insert / Update の正しい使い分け 旧 API（Put）や JPA 風の書き方を使用 4 Repository インタフェース型の正しい使用 具象クラスを直接受け取る実装 2PC：分散DB間でのデータ整合性が100%保証される OCCリトライ：高並列な注文が入ってもエラーにならず、自動で再試行される
35. 評価の8観点（後半） 35 # 観点 概要 rules, skillsなしの場合 5 Entity 設計 イミュータブル設計の遵守 @Data で可変オブジェクトを生成 6 ディレクトリ構 成 ScalarDB DDD 準拠のパッケージ構造 汎用的な技術名ディレクトリを使用 7 DB設定 database.properties の必須設定 application.yml の JPA 設定のみ 8 例外処理 UnknownCommitStatusException の適 切な処理 汎用 Exception → HTTP 500 で処理 ※ この8観点は本検証用の独自基準です UnknownCommitStatusException：トランザクションのコミット結果が 不明な状態（ネットワーク障害など）をハンドリングできる
36. 設定ありでコードはどう変わるか • デモ動画‧⽐較表の指⽰は「注⽂サービスを実装して」で before / after 共通 ◦ afterのデモ動画は次スライド • 実際の検証は対象の5サービスで実施し、⽐較表の後に集計結果を掲載 36 同条件でbeforeで実装した際のスクショ
37. デモ動画：設定ありでコードはどう変わるか 37
38. ルールの効果(⼀例)：2PC 実装の before / after 「2PC サポートは将来の拡張として検討が必要」とコメントを残 したまま、通常のトランザクション処理で代替実装 38 participantService.join(txId) で正しく 2PC に参加し、 原⼦性が保証される ↑ ルールなし ↑ ルールあり
39. コード⽐較：観点別の結果（1/2） 39 観点 Before（rules, skills なし） After（rules, skills あり） TX 管理 照会にも TwoPhaseCommitTX を使用 （Coordinator 書き込みが発生）→ CP TX マネージャーを用途別に分離。読み取りは DistributedTX、2PC は TwoPhaseCommitTX OCC リトライ UncommittedRecordException 未キャッチ → CP 例外種別ごとに独立カウンターでリトライ CRUD API Put API（旧 API）使用 → FAIL Insert / Update 使い分け Repository DistributedTransaction 型を直接受け取り → CP TransactionCrudOperable 第1引数（2PC 対 応） Entity 設計 @Dataで全フィールドに setter 生成・非 final → FAIL final フィールド・状態変更は新インスタンス返却 ※ order-service 1試行の抜粋
40. コード⽐較：観点別の結果（2/2） 40 観点 Before（rules, skills なし） After（rules, skills あり） ディレクトリ infrastructure/grpc/ 等（技術名）→ FAIL infrastructure/scalardb/（ScalarDB DDD 準拠） database.properties scalar.db.transaction_manager=clust er 含む → PASS scalar.db.transaction_manager=cluste r 含む 例外処理 UnknownCommitStatusException 未キャッ チ → FAIL UnknownCommitStatusException → HTTP 503 総合判定 FAIL（4 FAIL / 3 CP / 1 PASS） PASS（8/8） ※ order-service 1試行の抜粋
41. order-service：5試⾏の傾向 41 観点 Before PASS率 After PASS率 傾向 TX管理 3/5（60%） 5/5（100%） 改善 OCC リトライ 0/5（0%） 2/5（40%） 改善 CRUD API 0/5（0%） 5/5（100%） ⼤幅改善 Repository 0/5（0%） 5/5（100%） ⼤幅改善 Entity 設計 0/5（0%） 5/5（100%） ⼤幅改善 ディレクトリ 3/5（60%） 4/5（80%） 改善 DB設定 3/5（60%） 5/5（100%） 改善 例外処理 0/5（0%） 3/5（60%） 改善 ⚠ CRUD / Repository / Entity は完全再現。OCC リトライ・例外処理は after でも改善余地あり
42. 5サービス集計結果 42 サービス Before After 改善幅 備考 order-service 23% 85% +62pt product-service 3% 65% +62pt inventory-service 22% 82% +60pt payment-service 50% 73% +23pt before-3〜5 が元から高品質 receipt-service 20% 53% +33pt ScalarDB 非適用（3観点のみ）
43. 各サービスの傾向 43 サービス 良い点 注目点 order CRUD / Repository / Entity が after で完全再現 （5/5 PASS） 例外処理は after でも不安定 product TX管理・Repository が完全再現 DB設定の設定値ゆれが課題 inventory ほぼ全観点で大幅改善 例外処理は after でも全 FAIL payment TX管理・Entity が高品質 before-3〜5 が元から高品質で差が小さい receipt ディレクトリ構成が after で全 PASS ScalarDB 非適用のため before/after で大きな差なし
44. 検証まとめ：仮説は正しかったか • 仮説は検証で裏付けられた • CRUD / Repository / Entity の3観 点は after で 5/5 PASS（完全再 現性） • ただし 100% ではない。 例外処理はafter でも 平均 40% 程度 にとどまった 44 +62pt +62pt +60pt +23pt +33pt
45. この検証でエンジニアがやったこと AI は「コードを⽣成」、エンジニアは「AI がよいコードを⽣成できる状態の設 計」という役割分担をした • rules/ に制約‧禁⽌パターンを記述した • skills/ に⼿順‧トリガーを定義した • これらは「コードを書く」のではなく「AI への知識と⼿順の設計」 45
46. 考察と展望 46 エンジニアの役割はどう変わるか
47. エンジニアの仕事はどう変わるか • これまで：実装者として直接コードを書く • これから：AI が正しく動ける環境を整える側に回る • これからのAI時代の仕事は「何を守らせるか」を設計すること • rules/ と skills/ を整備することが、チームのエンジニアリング⼒につな がる 47 ℹ 「AI に任せる」のではなく「AI が正しく動ける環境を作る」が私たちの仕事
48. チームへの展開：ノウハウをチームの資産に • 解決した問題は解決策とともにドキュメントとして記録する • ノウハウ永続化スキルがその内容を rules/ や skills/ に⾃動で反映する • 蓄積されたノウハウは次回も参照するので、同じ失敗を繰り返さない • 新メンバーが⼊っても .claude/ を参照すればすぐキャッチアップできる • 「個⼈の経験」から「チームの資産」へ 48
49. 本⽇のまとめ • ① ガードレール設計（rules/） • DBミドルウェア固有の制約をテキストに落とし、AI が⾃然に守れる環境をつくる • ⼀度書けばチーム全員‧全モデルで再現できる • ② ⼿順の構造化（skills/） • 属⼈化していた複雑な⼿順をスキルとして定義し、誰でも同じ品質で実⾏できる • 解決した問題を永続化する仕組みで、チームは学び続けられる • ③ 品質の⼀貫性（.claude/） • rules/ と skills/ の組み合わせで「知識」と「⼿順」の両⽅を AI に渡せる • AI に任せるのではなく、AI が正しく動ける環境を私たちが設計する 49 ✅ rules/skills の整備が、1回目（約609時間）→ 2回目（約56時間）という結果にも繋がる
50. Next Step • 繰り返し発⽣しているコードレビュー指摘を rules/ に書き出してみる • 属⼈化している複雑な⼿順を skills/ に定義してみる • 解決した問題を記録する習慣をつけ、チームの資産として積み上げる 50
51. GitHub scalar-labs/scalardb connpass Scalar Please give us a star on GitHub! AIxDevOps Study 毎週⽕曜開催