はじめに こんにちは。基幹システム本部・リプレイス推進部・リプレイス推進ブロックの岡本です。 私たちのチームでは、ZOZOの基幹システムリプレイスの一環として、会計領域のシステムを新規構築しています。アーキテクチャにはCQRS（Command Query Responsibility Segregation）+ES（Event Sourcing）を採用しました（以降、CQRS+ESと略記します）。 本記事では、CQRS+ESを実務へ適用する中で直面した「小さな集約を保ちながら、大量の集約をまたいだ業務出力をどう実現するか」という課題と、その解決で得られた知見を紹介します。 会計システムでは、決済に関連する明細データを決済ID単位の小さな集約（Aggregate）として設計しています。一方で、消込結果を月次でまとめた帳票を出力するようなユースケースでは数万件規模の集約を横断する必要があり、集約の境界と業務出力のスコープに不一致が生じます。この不一致により、Sagaによる協調の結果を1つのイベントでQuery側に届ける必要が生まれ、イベントペイロードの肥大化が問題となりました。私たちはこの問題を共有テーブルとシグナルイベントを組み合わせたパターンで解決しました。 なお、本記事で述べる会計システムの仕様は、実装上の問題構造を説明するために簡略化・抽象化したものであり、実際のシステム仕様とは異なります。CQRS+ESを実務に適用する中で同様の課題に直面している方々の一助となれば幸いです。 目次 はじめに 目次 背景 基幹システムリプレイスの概要 会計システムの概要 本記事のスコープと想定読者 なぜCQRS+ESを選んだか インフラ構成の選択 ── RDB 1つでCQRS+ESを実現する 集約の境界と業務出力のスコープの不一致 小さな集約と大きな出力 スコープの不一致が生む課題 Sagaで複数集約を協調させる Sagaによる協調の構成 協調の次に来る問題：Query側へのデータ伝達 Query側へのデータ伝達 ── イベントに載せきれないとき ベストプラクティス：イベントに全情報を載せてQuery側に渡す 数万件規模のデータをイベントに載せるべきか？ 採用したパターン：共有テーブル＋シグナルイベント このパターンの解釈 CQRS+ESを実践してみて まとめ 背景 基幹システムリプレイスの概要 ZOZOの基幹システムは、20年以上にわたり機能追加を重ねてきた大規模モノリスです。技術的負債の蓄積により保守・拡張コストが増大していたことから、現在、全社的な基幹システムリプレイスプロジェクトが進行しています。 このリプレイスでは、重要度と移行コストの両面を考慮した上で優先度をつけ、モノリスからの段階的な移行を進めています。リプレイスプロジェクトの背景や先行事例については「 モノリスからマイクロサービスへ─ZOZOBASEを支える発送システムリプレイスの取り組み 」で詳しく紹介しています。 最新の基幹システムリプレイスの状況については「 巨大モノリスのリプレイス──機能整理とハイブリッドアーキテクチャで挑んだ再構築戦略 」の発表資料にまとめています。発表の様子は「 アーキテクチャConference 2025 協賛&参加レポート 」で紹介しています。 会計システムの概要 私たちが取り組んでいる会計システムリプレイスは、発送システムと同様に基幹システムから独立したマイクロサービスとして新規に構築しています。 会計システムが扱うドメインの中核は、「弊社システムの売上実績のデータ」と「決済代行会社などの外部システムの入金実績のデータ」を突合する処理です。 会計用語でいう「入金の消込」にあたります。売上と入金の明細は各々任意のタイミングで到着します。その都度、決済ID単位で明細を照合し消込処理を実行する必要があります。 本記事のスコープと想定読者 このシステムのアーキテクチャとして、CQRS+ESを採用しました。本記事ではCQRS+ESの採用理由にも軽く触れますが、本題は Aggregateの整合性境界と業務出力のスコープが一致しない場合 に生じる設計課題と、その解法です。具体的には、数万件規模のデータをどのようにQuery側に届けるかという問題を扱います。 想定読者はCQRS+ESの基本的な概念を理解している方です。何らかのCQRS+ESフレームワークに触れたことがある方は、より興味深く読んでいただけます。 なぜCQRS+ESを選んだか 会計システムでは、すべての業務操作の履歴を厳密に記録し、後から追跡可能にすることが求められます。 Event Sourcing では、ビジネスエンティティの状態を「状態変更イベントの列」として永続化します。そのため、業務イベントの履歴がそのまま監査ログとして機能するという性質が、会計ドメインの要件と合致しました。 ここで重要なのは、ログとイベントの違いです。ログを記録するだけでは、ログと実際のシステムの動作が整合している保証はありません。一方、ESではイベント（事実）がすべての起点であり、イベントと動作が必ず整合します。会計システムにおいて「何が起きたか」を正確に追跡できることは、監査の観点から本質的な要件です。そのため、ESの採用が適切であると判断しました。 また、Queryの都合を気にしてドメインモデルを構築すると、最も重要なCommand側のロジック管理が複雑化します。CQRSによりCommandとQueryのモデルを分離することで、それぞれの関心事に集中した設計が可能になります。 社内の技術スタックをJavaに統一しており、Java上でCQRS+ESを実現するフレームワークとして Axon Framework を採用しました。Axon Frameworkを選定した理由の1つは、CQRS+ESの実践に必要なプラクティスがフレームワークレベルで用意されている点です。具体的には、以下のような仕組みがフレームワークとして提供されています。 イベントの永続化とリプレイ スナップショットによる集約の復元最適化 Sagaによる複数集約の協調 Processing Groupとセグメントによる並列処理の制御 これらを自前で実装する必要がないことで、CQRS+ESの基盤構築ではなく、ドメインの設計に集中できると判断しました。 インフラ構成の選択 ── RDB 1つでCQRS+ESを実現する 一般的なCQRSアーキテクチャでは、Command側とQuery側を別々のデータストアに分離し、メッセージブローカーを介してイベントを伝達する構成が採用されます。下図は、 Axon公式ドキュメント に示されている一般的なCQRSアプリケーションの技術概要を参考に再作成したものです 1 。 公式図では、Event Store・Event Bus・Query側のデータベースがそれぞれ独立したコンポーネントとして描かれています。これらのインフラ構成には複数の選択肢があります。たとえばイベントストアとメッセージルーティングを一体で提供するAxon Serverや、Event BusにKafkaなどのメッセージブローカーを採用する構成が考えられます。 私たちのシステムではESの主な採用動機が監査ログの実現であり、高いスケーラビリティや外部システムへのイベント連携は要件ではありませんでした。そのため、これらの選択肢を以下の2つの観点から評価した結果、いずれも採用を見送りました。 金銭的コスト ：Axon Serverのクラスタ構成のライセンス費用や、メッセージブローカーの追加インフラコストが発生する 学習コスト ：チームにとってなじみの薄い技術スタックを導入した場合、学習コストと運用負荷が高くなる チームに知見のあるRDBのみの構成でも要件を満たせることがわかり、 Event Store・Event Bus・Read Modelをすべて単一のRDB上で実現する構成 を採用しました。下図は、今回採用した単一RDB構成を示しています。 今回の構成では、独立したEvent Busコンポーネントは存在しません。Axon FrameworkがEvent Store（ domain_event_entry テーブル）をポーリングすることで、Event Busの役割を実現しています。また、RDB上でのパフォーマンスを確保するために、Axon公式の RDBMSチューニングガイド を参考にインデックス設定等のチューニングを行っています。 私たちの構成では、同一データベース内にCommand側テーブル、Query側テーブル、そして共有テーブルが同居しています。Command側のテーブル（ domain_event_entry や token_entry 等）はAxon Frameworkが内部的に利用するテーブルであり、フレームワークが必要とするスキーマをそのまま作成しています。Query側のテーブルはRead Modelを表す rm_ プレフィックスで管理しています。共有テーブルは標準構成ではなく私たちが独自に導入したものであるため、図中では点線で表記しています。詳細は次章以降で説明しますが、この「すべてが同一データベース内に存在する」という構成が、共有テーブルパターンの前提条件として重要な役割を果たします。 集約の境界と業務出力のスコープの不一致 小さな集約と大きな出力 私たちのシステムでは、 Aggregate（集約） を小さな単位で保つ設計を採用しています。Vaughn Vernon氏は「Effective Aggregate Design」の中で、集約の設計について以下のように述べています。 Limit the Aggregate to just the Root Entity and a minimal number of attributes and/or Value-typed properties. (...) A large-cluster Aggregate will never perform or scale well. （日本語訳）集約はルートエンティティと最小限の属性やValue型プロパティに限定すべきである。（中略）大きなクラスタの集約は、パフォーマンスもスケーラビリティも決して良くならない。 ── Vaughn Vernon, " Effective Aggregate Design Part I " この指針に従い、私たちのシステムでも集約を小さな単位で保っています。「背景」で述べた通り、売上と入金の明細を決済ID単位で照合するため、各集約も同じ粒度で設計しており、毎日膨大な数の集約インスタンスが生まれます。 決済ID単位の小さな集約にする必然性は、各明細が自身の状態に基づいて独立した判断・振る舞いを行う必要があるためです。各集約は消込に関するステータスを内部に保持しています。さらに、各明細に対しては削除コマンドを受け付ける要件があります。削除コマンドを受けた際、その明細がすでに帳票出力済みであれば打ち消しの帳票を出力してから削除するといった、明細単位の状態（消込ステータス、帳票出力済/未済等）に応じた振る舞いの分岐が求められます。このように、個々の明細が自身の状態に基づいて独立して判断する必要があるため、小さな集約としての設計が必然です。 一方で、帳票出力という業務処理は、これら数万件規模の集約を横断する大きなスコープで実行されます。 帳票出力時には数万件規模の集約のステータスを「出力済」に更新し、さらにQuery側（Read Model）では、ステータスが更新された数万件規模のデータをもれなく帳票として出力する必要があります。 スコープの不一致が生む課題 下図は、この「スコープの不一致」を示しています。各集約は決済ID単位の小さな境界を持っていますが、帳票出力のスコープは数万件規模の集約を横断します。 1つの集約のスコープと業務出力のスコープには大きなギャップが存在します。この構造は、小さな集約という設計が正しいからこそ生まれる問題です。集約を大きくすれば解消できますが、それはVernon氏が指摘する「大きな集約のアンチパターン」に陥ることを意味します。したがって、集約の境界はそのまま維持した上で、数万件規模の集約を横断的に協調させる仕組みが必要になります。 Sagaで複数集約を協調させる Sagaによる協調の構成 前章で示した「数万件規模の集約を横断的に協調させる」という課題に対して、 Saga を採用しました。Sagaは、複数のローカルトランザクションを協調させるパターンです 2 。 私たちの構成では、Sagaが数万件規模の集約にCommandを送信し、各集約が処理完了後にEventを返却し、Sagaがそれらを収集して全体の完了を判断します。実際にはSagaを親子に階層化し、親Sagaが子Sagaを複数起動して、子Sagaがバッチ単位で集約を管理する構成を採用しています。これにより、並列処理の流量制御も実現しています。下図は、この協調フローの概念を示しています。 子Sagaは各集約からの完了イベントを受け取るたびに処理済みの件数をカウントし、すべての集約の処理が完了した時点で親Sagaに完了を通知します。なお、集約が別のユースケースで削除済み、またはすでに帳票出力済みであった場合は、帳票出力の対象外であることを示すイベントを返却します。Sagaはこのイベントも処理済みとしてカウントし、帳票には出力しないものとして扱います。親Sagaはすべての子Sagaの完了をもって「全体完了」と判断します。数万件規模の集約を横断的に協調させるという課題自体は、このSagaの階層構造で解決できます。 協調の次に来る問題：Query側へのデータ伝達 Sagaが「全集約の処理が完了した」と判断した次のステップで、新たな問題が生まれます。数万件規模の処理結果を、Query側にどのように届ければよいのでしょうか。 Query側へのデータ伝達 ── イベントに載せきれないとき ベストプラクティス：イベントに全情報を載せてQuery側に渡す CQRS+ESにおけるベストプラクティスは、 イベントに必要な情報をすべて載せてQuery側に渡す ことです。 Microsoftの CQRS Patternガイド では、Command側とQuery側の同期について次のように述べています。 When you use separate data stores, you must ensure that both remain synchronized. A common pattern is to have the write model publish events when it updates the database, which the read model uses to refresh its data. （日本語訳）別々のデータストアを使用する場合、両方の同期を保つ必要があります。一般的なパターンは、書き込みモデルがデータベースを更新する際にイベントを発行し、読み取りモデルがそのイベントを使用してデータを更新するというものです。 ── Microsoft Azure Architecture Center, "CQRS Pattern" イベントがすべての情報を運ぶことにより、Query側はCommand側のデータストアを直接参照する必要がなくなります。この「イベントを通じた疎結合」こそがCQRSの根幹です。Query側のProjection（イベントからRead Modelを導出する処理）は、受信したイベントのペイロードだけでRead Modelを構築できます。そのため、Command側とQuery側の独立性が保たれます。 数万件規模のデータをイベントに載せるべきか？ 私たちのケースでこのベストプラクティスをそのまま適用できるでしょうか。前章で示した通り、Sagaが全集約の完了を検知した時点で数万件規模の処理結果をQuery側に届ける必要があります。ベストプラクティスに従えば、これらすべてのデータを完了イベントのペイロードに含めるべきです。 しかし、ここには2つの問題があります。1つ目は ペイロードの肥大化 です。数万件規模の集約に関するデータを1つのイベントに詰め込むことは、シリアライズ・デシリアライズのコストやメモリ使用量の観点から非効率です。2つ目は Query側での利用形態との不一致 です。帳票出力の後続処理では、前段のProjectionで構築済みの rm_ テーブルとのJOINが必要です。仮にイベントペイロードにデータを収められたとしても、Query側で結局テーブルに展開してJOINすることになるため、イベント経由で運ぶ利点は薄れます。 採用したパターン：共有テーブル＋シグナルイベント 先述の問題に対して、いくつかの方針を検討しました。 1つ目は Query側のProjectionで完結させるアプローチ です。各集約の処理完了イベントをProjectionが受信して rm_ テーブルに書き込み、すべての書き込みが終わった後に帳票を出力する方式です。 しかし、数万件規模のイベントを実用的な時間内に処理するにはProjectionの並列化が必須です。Axon FrameworkのTracking Processorでは、複数のセグメントがイベントを分担して並列に処理します。同一セグメント内ではイベントの処理順序が保証されますが、完了イベント（シグナルイベント）と各集約の処理完了イベントは異なるセグメントに振り分けられうることが問題です。 異なるセグメント間では処理の進行度が異なるため、あるセグメントが完了イベントを処理した時点で、別セグメントではまだ処理が完了していない可能性があります。 つまり、シグナルイベントがProjectionに届いた時点で rm_ テーブルへの書き込みが完了していない可能性があり、データの欠損が生じます。これを防ぐにはProjectionに協調ロジックが必要ですが、それはSagaの責務であり、Projectionの関心事の分離を崩すため、見送りました。 2つ目は イベントの分割送信 （チャンク化）です。数万件のデータをN件ずつ複数のイベントに分割して送信する方式です。しかし、この方式ではQuery側のProjectionが「すべてのチャンクが届いたか」を判定する協調ロジックを持つ必要があり、1つ目と同じ問題構造を抱えるため、見送りました。 3つ目は Claim Checkパターン です。イベントにはデータ本体を載せず、外部ストレージへの参照のみを含める方式です。技術的には実現可能ですが、以下の理由から見送りました。 外部ストレージの導入は「インフラ構成の選択」で述べた単一RDB構成の方針を崩す 外部ストレージへの書き込みはEvent Storeと別トランザクションになり、障害時の整合性担保が複雑化する これらの検討を経て、私たちは単一RDB構成の利点を活かした 共有テーブルとシグナルイベントを組み合わせたパターン を採用しました。前述の通り、個々の明細データは通常のProjectionでRead Modelに構築済みです。不足しているのは、どの明細がどの帳票に属するかという対応関係です。このパターンの構成は以下の通りです。 Sagaは帳票出力フローの開始時に帳票IDを採番し、各集約にCommandを送信する。処理完了イベントを受信するたびに、 同一トランザクション内で 帳票IDと明細IDの対応関係を 共有テーブル に逐次書き込む すべての集約の処理が完了したら、Sagaは 完了イベント を発行する（ペイロードは最小限のシグナルのみ） Query側のProjectionは完了イベントをトリガーとして受信し、帳票出力が可能になったことを示すRead Model（ rm_ テーブル）を作成する 後続のレポート生成処理がこのRead Modelを検知し、帳票のRead Model・共有テーブル・明細のRead Modelを順にJOINして帳票データを取得する ステップ1のポイントは、Axon FrameworkのSagaがイベントハンドラの処理をUnit of Work（UoW）パターンで管理している点です。イベントの受信と共有テーブルへの書き込みが同じトランザクションで実行されるため、すべての集約の処理が完了した時点では、対応するデータが共有テーブル上にも確実にそろっています。 ここで重要なのは、「インフラ構成の選択」で説明した 単一RDB構成 です。Command側テーブル、Query側テーブル、そして共有テーブルがすべて同一のデータベース内に存在するため、共有テーブルへの書き込みとJOINによる読み取りが自然に実現できます。もしCommand側とQuery側が異なるデータストアに分離されていたら、このパターンは成立しません。 先述のProjection完結アプローチで問題となったセグメント間の進行度の差は、本パターンでは構造的に発生しません。共有テーブルへの書き込みをSagaが担い、すべての書き込みが完了した後に初めて完了イベントを発行するためです。 このパターンの解釈 このパターンでは文字通りCommand側とQuery側でテーブルを共有しています。これはCQRSの原則「Command側とQuery側はイベントを通じてのみ情報をやり取りする」からの意図的な逸脱です。将来的なデータストアの物理分離が難しくなるトレードオフはありますが、以下の2点を考慮し採用しました。 現時点でCommand側とQuery側の物理分離は想定されないこと 共有テーブルは明示的に設計・管理されており、暗黙の依存ではないこと。将来的に物理分離が必要になった場合も、共有テーブルの参照箇所が明確であるため、段階的な移行が可能であること 実際にこの設計で運用してみて、Projectionのロジックがシンプルに保たれ、Event Storeのペイロード肥大化も回避できている点に手応えを感じています。一方で、共有テーブルのスキーマ変更がCommand側とQuery側の両方に影響する点には注意が必要です。通常のCQRSでは、Command側とQuery側のスキーマを独立に変更できることが利点の1つですが、共有テーブルに関してはこの利点が失われます。 CQRS+ESを実践してみて 本記事で紹介したSagaによる数万件規模の集約の協調は、Axon FrameworkのSagaサポートがなければ実現が困難でした。その場合、Sagaの状態管理やイベントとの紐付けといった基盤部分の実装から始める必要がありました。同様に、スナップショットによる集約の復元最適化やProjectionの進捗管理（Tracking Processor）も、自前で実装していたら多大な工数を費やしていたと考えられます。前述したこれらの基盤が揃っていたからこそ、アーキテクチャレベルの設計課題に対して検討と試行錯誤の時間を確保できました。 加えて、Axon FrameworkでESを実現する中で、集約内部のロジックが関数的な構造になる点にも良さを感じています。集約のCommand Handlerは、Commandを受け取ってEventを発行し、Event Sourcing Handlerは、Eventを受け取って集約の状態を更新します。テストも、Axon Frameworkが提供する テストフィクスチャ を用いて「Given（過去のイベント列）→ When（コマンド）→ Then（期待されるイベント）」という宣言的な形式で記述できます。この構造は、AIによるテスト駆動開発と相性が良いと感じています。入力と出力が明確に定義されているため、AIがテストケースを生成しやすく、またテストの意図が宣言的に表現されるため、AIが生成したテストコードのレビューもしやすいという実感があります。 一方で、ESを本格的に運用する難しさも実感しています。 ESではすべての状態変更が「コマンド → 集約 → イベント」のパイプラインを通ります。ステートソーシングであれば一括更新で済む処理も、集約ごとにコマンドを送信し、個別にイベントを発行しなければなりません。 本記事で扱った集約横断の協調は、まさにこの制約から生まれた設計課題です。 この課題に関連して、近年提唱されている Dynamic Consistency Boundary（DCB） という概念に注目しています。DCBは、一貫性の境界を集約に固定せず、イベントへ付与するタグに基づいて動的に伸縮させるアプローチです。従来のESでは集約の境界が設計時に固定されるため、本記事で扱ったようなSagaによる協調が避けられませんでしたが、DCBによってこの複雑さを軽減できる可能性があります。私たちのユースケースにどこまで適用できるかはまだ未知数ですが、ESの実践的な課題を構造的に解決しうるアプローチとして、今後の動向を追っています。 まとめ 本記事では、会計システムへのCQRS+ES適用において、小さな集約を保ちながら大量の集約をまたいだ業務出力を実現する過程で得られた知見を紹介しました。 小さな集約を正しく設計するほど、業務出力のスコープとの不一致が顕在化します。Sagaで数万件規模の集約を協調させることはできますが、その結果をQuery側に届ける段階で「イベントに載せきれない」という壁にぶつかりました。共有テーブルとシグナルイベントを組み合わせたパターンを採用し、CQRSの原則からは逸脱しつつも、実用的な解決策にたどり着きました。 CQRS+ESの実装事例はまだ多くなく、今回の実装についても正しいものであるかという不安と向き合いながら進めてきました。リリースしてみて大きな問題は発生しておらず、ポジティブな状況であると捉えています。しかし、ベストプラクティスがさらに確立されてきた際には、それに適応していく姿勢を持ち続けたいと考えています。 本記事では会計領域のリプレイスを紹介しましたが、同じ基幹システムリプレイスの物流領域でもメンバーを募集しています。大規模モノリスからのサービス分割に取り組むポジションで、ドメイン駆動設計やイベント駆動アーキテクチャの知識を活かせる環境です。物流システムの刷新に興味のある方は、ぜひご覧ください。 hrmos.co さらにZOZOでは、一緒にサービスを作り上げてくれる仲間を広く募集中です。ご興味のある方は、以下のリンクからぜひご覧ください。 corp.zozo.com この図はAxon公式ドキュメント「Architecture Overview」の図を参考に、本記事で必要な構成要素に絞って再作成したものです。 ↩ 厳密には、SagaとProcess Managerは 異なる概念 です。Sagaは補償トランザクションに焦点を当てたパターンであるのに対し、Process Managerは状態マシンとしてモデリングされ、受信イベントと現在の状態に基づいて判断を下します。Axon Frameworkでは @Saga アノテーションを使用して、Orchestration方式のProcess Managerを実装しています。本記事では、フレームワークの慣例に合わせて「Saga」と表記します。 ↩

はじめに こんにちは！サイオステクノロジーのなーがです。前回はGoogle CloudのVertex AIをAzureから使用するための手順ということで主にインフラ関連の内容を書きましたが、今回はAIコーディングエージェントの開発プロセスを強化するフレームワーク「obra/superpowers」について書こうと思います。 AIエージェントは本当に便利なのですが、使い込んでいると「あれ、テスト書かずにいきなり実装してる…」「原因調査なしにとりあえずパッチを当てようとしてる…」という場面に気づくことがあります。エージェントは高性能ですが、プロセスを省略するクセがあるんですよね。 そんな悩みを解決してくれるのが、今回紹介する obra/superpowers です。92K以上のGitHubスターを獲得している注目のフレームワークで、AIコーディングエージェントに規律ある開発プロセスを注入してくれます。 今回は、superpowersの概要からインストール方法、実際の活用シナリオまでを詳しく紹介します。 obra/superpowers とは obra/superpowers は、AIコーディングエージェント向けの アジャイルスキルフレームワーク です。 「スキル」と呼ばれるMarkdownベースの指示ファイルをエージェントに読み込ませることで、テスト駆動開発・体系的なデバッグ・コードレビューといった規律ある開発プロセスを強制します。 “coding agents produce better results when they follow systematic processes rather than ad-hoc approaches” この思想が、superpowersの根幹にあります。エージェントの能力を引き出すのではなく、 プロセスをガイドする というアプローチです。 誕生の背景 開発者の Jesse Vincent 氏（Prime Radiant）が、AIエージェントが以下のような「近道」を取ろうとする問題に直面したことがきっかけです。 テストを後回しにして実装を先に書く 根本原因を調査せずにパッチを当てる 完了確認なしに「できました」と報告する superpowers はこれらのアンチパターンを明示的にドキュメント化し、エージェントが自分でそれを認識・拒否できるように設計されています。 参照: obra/superpowers – GitHub 対応プラットフォーム superpowers は主要なAIコーディングプラットフォームすべてに対応しています。 プラットフォーム 対応状況 Claude Code 公式マーケットプレイス対応 Cursor プラグインマーケットプレイス対応 Gemini CLI Extension対応 Codex .codex/ ディレクトリ方式 OpenCode .opencode/ ディレクトリ方式 スキル一覧とアーキテクチャ 14種類のスキル一覧 superpowers には14種類のスキルが含まれており、4つのカテゴリに分類されています。 カテゴリ スキル名 目的 テスト・品質 test-driven-development テスト先行の RED-GREEN-REFACTOR サイクルを強制 systematic-debugging 4フェーズの根本原因分析を強制 verification-before-completion 証拠なき完了宣言を禁止 計画・実行 brainstorming 実装前の設計対話・仕様レビューを実施 writing-plans 2〜5分タスク単位の実装計画を作成 executing-plans 実装計画を順序通りに実行 subagent-driven-development サブエージェント×2段階レビューで高品質実装 dispatching-parallel-agents 独立タスクを並列サブエージェントへ委譲 Git・コラボレーション using-git-worktrees 独立したGit worktreeで安全に並列開発 finishing-a-development-branch テスト確認→マージ/PR/破棄の構造化フロー requesting-code-review 適切なタイミングでコードレビューを依頼 receiving-code-review レビューフィードバックを技術的に評価 メタ using-superpowers スキルの発見・呼び出しのメタプロトコル writing-skills 新しいスキルをTDDで作成 コアスキル12種に加え、フレームワーク自体を拡張するメタスキル2種（ using-superpowers ・ writing-skills ）が含まれています。 ディレクトリ構成 リポジトリのトップレベル構成は以下の通りです。 superpowers/ ├── skills/ # 14種類のスキルモジュール ├── agents/ # エージェント設定・振る舞い定義 ├── commands/ # CLIコマンド実装 ├── hooks/ # プラットフォーム統合フック ├── docs/ # プラットフォーム別ドキュメント ├── tests/ # テストスイート ├── .claude-plugin/ # Claude Code 統合 ├── .cursor-plugin/ # Cursor 統合 ├── .codex/ # Codex 統合 └── .opencode/ # OpenCode 統合 各スキルは skills/<スキル名>/ ディレクトリに格納されており、必須ファイル SKILL.md の他に必要に応じてテンプレートやスクリプトが含まれます。 アーキテクチャ図 superpowers の全体アーキテクチャを図で示します。AIコーディングプラットフォームからスキルレイヤーを通じ、フック・Git統合へと流れる構造になっています。 スキルはプロジェクトのコンテキストに応じて **自動的に発火** します。特別な構文や手動呼び出しは不要です。 次に、スキルのカテゴリ構成をマップで示します。 SKILL.md のフォーマット 各スキルは SKILL.md ファイル一枚で定義されます。構造は以下の通りです。 --- name: skill-name description: "Use when ... (最大1024文字、トリガー条件を記述)" --- ## Overview ## When to Use ## Core Pattern ## Quick Reference ## Implementation ## Common Mistakes フロントマターの description フィールドが特に重要で、エージェントがスキルを自動選択する際の判断基準になります。「Use when…」という形式でトリガー条件を記述することがベストプラクティスです。 Token効率も設計の考慮事項で、頻繁に読み込まれるスキルは200語以内に収めることが推奨されています。 インストール方法 Claude Code 公式マーケットプレイス経由（推奨）: /plugin install superpowers@claude-plugins-official カスタムマーケットプレイス経由: # ステップ1: マーケットプレイスを追加 /plugin marketplace add obra/superpowers-marketplace # ステップ2: インストール /plugin install superpowers@superpowers-marketplace インストール後、新しいセッションを開始して「この機能を計画したい」などと話しかけると、 brainstorming スキルが自動的に発火します。 アップデート: /plugin update superpowers Cursor Cursor のプラグインマーケットプレイスから検索してインストールするか、以下のコマンドを使用します。 /add-plugin superpowers Gemini CLI gemini extensions install https://github.com/obra/superpowers 参照: obra/superpowers – Installation 活用シナリオ 活用シナリオは無限に考えられますが、今回は下記の6つのシナリオを紹介します。 TDD を強制する test-driven-development スキルを使うと、エージェントはテストなしに実装コードを一切書かなくなります。 鉄則: “NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.” テストより先にコードを書いた場合は、そのコードをすべて削除して最初からやり直す。 サイクルは以下の通りです。 RED — 失敗するテストを書く RED確認 （必須）— テストが実際に失敗することを確認する GREEN — テストが通る最小限のコードを書く GREEN確認 （必須）— テストが通ることを確認する REFACTOR — コードを整理する 手動テスト済みであることを理由にテストを省略しようとすると、スキルがそのアンチパターンを認識して拒否します。 長時間の自律開発セッション executing-plans スキルと subagent-driven-development スキルを組み合わせると、2時間以上の自律開発セッションが可能になります。 各タスクは2〜5分単位に分割され、サブエージェントが1タスクずつ実装・レビューを繰り返します。人間が介入しなくても、スキルがプロセスの品質を担保します。 複数機能の並列開発 dispatching-parallel-agents スキルを使うと、互いに独立した複数のタスクを並列で処理できます。 適用条件: 3つ以上の独立した失敗ファイル・サブシステムがある タスク間で共有状態がない それぞれ異なる根本原因を持つ using-git-worktrees と組み合わせることで、各エージェントが独立したGit worktreeで安全に作業できます。 公式ドキュメントによると、6件の失敗を3つの並列エージェントで解決したケースでは、コンフリクトゼロで解決できたとのことです。 根本原因を特定してからデバッグする systematic-debugging スキルは、エージェントが「とりあえずパッチを当てる」近道を防ぎ、4フェーズの体系的なデバッグを強制します。 4フェーズ: Root Cause Investigation — エラーを読み込み、再現手順を確認し、直近の変更を調査する Pattern Analysis — 動いている似た箇所と比較して差分を特定する Hypothesis and Testing — 仮説を1つ立て、最小限の変更で検証する Implementation — 根本原因のみを修正し、再発防止のテストを追加する 原因が特定できていない段階で修正コードを書き始めようとすると、スキルの Iron Law「NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST」に引っかかり、Phase 1 に差し戻されます。「直ったと思ったらまた壊れた」という状況を根本から防げます。 実装前に設計を固める brainstorming スキルを使うと、エージェントはコードを書く前に設計対話フェーズを実施します。 対話の流れ: 要件の確認と曖昧な点の洗い出し 複数の実装アプローチを提示して比較 トレードオフ（速度・保守性・複雑度）を明示 合意した方針をドキュメント化 このスキルは writing-plans と連携しており、対話が終わると自動的に実装計画の作成に移行します。「とりあえず実装してみて後で考える」というエージェントの傾向を、設計ファーストに切り替えます。 1問ずつ丁寧に要件を深掘りし、合意が取れた段階で設計書を作成→ writing-plans スキルへ引き渡します。 コードレビューのサイクルを回す requesting-code-review と receiving-code-review の2スキルを使うと、エージェントがレビューの依頼から反映まで一貫して対応します。 レビュー依頼時（ requesting-code-review ）: PR の目的・変更の概要・テスト状況を整理してレビュアーに提示 レビューしやすい粒度に変更を分割 フィードバック受け取り時（ receiving-code-review ）: 指摘内容を「必須修正」「提案」「議論」に分類 技術的な根拠をもとに修正の要否を判断 反映した変更を明示してレビュアーに返答 感情的に反応したり、すべての指摘を無条件に受け入れたりするのではなく、技術的な評価に基づいて対応します。 技術的に不要な変更はプッシュバックし、根拠のある修正のみを行います。 さいごに 今回は obra/superpowers について紹介しました。 AIエージェントは非常に高性能ですが、プロセスを省略しがちという弱点があります。superpowers はそこに「規律」を注入することで、エージェントを本来の実力で動かし続けるための仕組みです。 特に test-driven-development スキルと systematic-debugging スキルは、エージェントが近道を取ろうとする典型的な場面で真価を発揮します。まずはこの2つからインストールして試してみることをおすすめします。 興味を持った方は、ぜひ公式リポジトリや writing-skills スキルを使って、自分だけのスキルを作ってみてください！ ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post AIコーディングエージェントの弱点を補う「obra/superpowers」 first appeared on SIOS Tech Lab .

エピソード紹介 Ep.1 – クリーンアーキテクチャとは Ep.2 – 認証方式の実践的な紹介 Ep.3 – ER設計と監査ログ Ep.4 – RepoScanner の実装とテスト ← 今回はこちら Ep.5 – Copilot プロンプトを効率化 こんな方へ特におすすめ クリーンアーキテクチャの理屈は分かったけど、どこから書き始めるの？と疑問な方 クリーンアーキテクチャで小さな MVP を実装するワークフローに興味がある方 TDD（テスト駆動開発）を実務に取り入れて、壊れにくいコードを書きたい方 概要 こんにちは。サイオステクノロジーのはらちゃんです！ シリーズ4本目となる今回は、いよいよ待望の実装編に突入します。 ここで大きな役割を果たすのが TDD（テスト駆動開発） です。テストファーストで進めることで、依存性の切り離しや境界の明確化が自然と行われます。 — 本シリーズでは、Copilotを活用しつつ、クリーンアーキテクチャに沿って小規模なプロダクト「RepoScanner」を設計・実装した経緯をまとめます。 このエピソードは、アプリのコア機能である「リポジトリ内のスナップショット一覧を取得する機能」に焦点を当てました。 さらに、「AIへの指示の出し方」や「テストの質の変化」についてもお伝えします。 実装前の準備 プロジェクトの全体像 実装作業を開始する前に、まずは「RepoScanner」の構成を整理しておきます。 目的 リポジトリのメタデータや集計結果を効率よく取得し、分析しやすくすること。 要件 スナップショット一覧のページング（limit / offset）、最大取得数の制限。 クリーンなユースケースを保つ「3つの設計ルール」 RepoScannerにおけるUse Cases層では、以下のルールを徹底しました。 入出力は DTO （Data Transfer Object） HTTPリクエストなどのオブジェクトは、そのまま使わず単純なデータクラスに変換する。 依存はインターフェースを介して注入（DI） DB処理などは、具体的な実装ではなく「Repository」などの抽象的な型に依存させる。 副作用の入り口を明示 「どこで外部APIを呼ぶ」など処理の流れがユースケースから分かる状態を保つ。 このように責務を分離することで、ユースケースが純粋なビジネスロジックだけに集中できる環境が整います。 クリーンアーキテクチャによる設計 コードの保守性を高めるため、クリーンアーキテクチャに従って責務を明確に分離しました。 Domain層 SnapshotSummary などのエンティティ Use Cases層 ListSnapshotSummariesUseCase Interface Adapters層 HTTP エンドポイントの制御 Infrastructure層 SnapshotQueryRepository ここで重要なのは、DBアクセスへの依存を必ず「インターフェース」経由にすることです。 その結果、内側のロジックが外側の技術的な詳細を知らなくて済む「依存性の逆転」が成立します。 設計上の要点 永続化（DBアクセス）への依存は、必ずリポジトリの「インターフェース」を経由させます。 これにより、内側（Use Cases層）が外側（Infrastructure層）の技術詳細を知らない状態となり、依存の逆転を保ちます。 →　詳細は エピソード1へ 階層ごとのテスト戦略 「どこからテストを書けばいいか分からない」という悩みは、クリーンアーキテクチャで解決します。 なぜなら、各階層の役割がはっきりしているため、テストの目的も自ずと定まるからです。 最優先: Use Cases層のユニットテスト ここでは「仕様としての正しさ」を検証します。 limit の上限クリッピングや、 offset の負値チェックなどが対象です。 このテストはフレームワーク更新や DB ドライバ変更に影響されない高速なフィードバックを得ることが可能です。 例えば、以下のような正常系のテストを用意してください。 /tests/use_cases/test_list_snapshot_summaries.py # 正常範囲の limit がそのままリポジトリへ渡されることを確認 class ListSnapshotSummariesUseCaseTest(unittest.TestCase): def test_execute_passes_limit_when_within_bounds(self) -> None: repository = FakeSnapshotQueryRepository() use_case = ListSnapshotSummariesUseCase(repository, max_read_limit=25) use_case.execute(limit=1, offset=0) self.assertEqual(1, repository.received_limit) use_case.execute(limit=25, offset=0) self.assertEqual(25, repository.received_limit) 外部依存はすべてモック化する ドメインモデルに正しく仕事を任せているか確認 優先: Infrastructure層のテスト 次に、 「 技術的な正しさ 」 を検証します。 SQLの組み立てが正しいか、LIMIT / OFFSETのパラメータ順序が間違っていないかといったパラメータ順序や DBから取得したデータをエンティティへ正しくマッピングできているかを確認できます。 /tests/frameworks&drivers/persistence/test_postgres_snapshot_query_repository.py # フィルタなしで LIMIT/OFFSET がパラメータに含まれ、`ORDER BY s.observed_at desc` が含まれる確認 class PostgresSnapshotQueryRepositoryTest(unittest.TestCase): def test_list_snapshot_summaries_without_filters(self) -> None: now = datetime(2026, 2, 24, tzinfo=UTC) cursor = _FakeCursor( rows=[ { "snapshot_id": UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"), "fetch_run_id": UUID("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"), "target_repo_id": UUID("cccccccc-cccc-cccc-cccc-cccccccccccc"), "owner": "owner", "name": "repo", "default_branch": "main", "requested_at": now, "observed_at": now, "head_sha": "deadbeef", "scan_scope": "full", "status": "succeeded", "trigger_type": "manual", } ] ) with patch( "application.backend.src.infrastructure.persistence.postgres_snapshot_query_repository.get_cursor", return_value=_CursorContext(cursor), ): repository = PostgresSnapshotQueryRepository() items = repository.list_snapshot_summaries( limit=10, offset=5, user_id=None, target_repo_id=None ) self.assertEqual([10, 5], cursor.executed_params) どのようなSQL（またはリクエスト）を組み立てたか検証 インターフェースの「型」と「変換」を確認 最終: 統合テスト／E2E 最後に、GitHub Actionsでのデータ抽出からDB保存、そしてアプリでの読み取りまで、システム全体のフローが本番に近い環境で動作するかを確かめます。 /tests/http/test_main_api.py # ユースケースのクリッピングを利用して 200 を返すことを確認 class MainApiTest(unittest.TestCase): def test_list_snapshots_clamps_limit_and_returns_200(self) -> None: repository = _RecordingSnapshotRepository() cast(Any, main).list_snapshot_summaries_use_case = ListSnapshotSummariesUseCase( repository, max_read_limit=5 ) response = self.client.get("/snapshots?limit=999&offset=0") self.assertEqual(200, response.status_code) self.assertEqual(5, repository.received_limit) 本物のデータベースを使用 セットアップとクリーンアップの仕組みが必須 実装 TDD（テスト駆動開発） 進め方 TDDは、単にバグを防ぐためだけでなく、「設計を洗練させるためのツール」です。 以下の3サイクルで進めます。 Red: 失敗 仕様の最小ケースを満たす「テストコード」を書く。まだ実装がないので当然エラー。 Green: 成功 そのテストが通るように、最小限の「実装コード」を書く。 Refactor: リファクタリング テストが通る状態を保ったまま「設計ルール」に合わせてコードをきれいに整理。 サイクルのイメージ図です。 例えば、「1回の取得上限は100件まで」というルールはAPIの仕様ではなくドメインの規則です。これをユースケース層で確実に担保することで、フレームワークに依存しない堅牢なロジックが完成します。 【実践】スナップショット取得ユースケース 前回設計した snapshot テーブルに対して、「スナップショットを取得する」というユースケースをTDDで作ってみましょう。 Use Cases層のユニットテスト tests/use_cases/test_register_snapshot.py import unittest from uuid import UUID from datetime import UTC, datetime from application.backend.src.domain.entities.snapshot_summary import SnapshotSummary from application.backend.src.use_cases.list_snapshot_summaries import ListSnapshotSummariesUseCase class _FakeRepo: def __init__(self): self.called = False self.last_params = {} def list_snapshot_summaries(self, *, limit, offset, user_id, target_repo_id): self.called = True self.last_params = dict(limit=limit, offset=offset, user_id=user_id, target_repo_id=target_repo_id) now = datetime.now(UTC) return [SnapshotSummary( snapshot_id=UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"), fetch_run_id=UUID("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"), target_repo_id=UUID("cccccccc-cccc-cccc-cccc-cccccccccccc"), owner="owner", name="repo", default_branch="main", requested_at=now, observed_at=now, head_sha="deadbeef", scan_scope="full", status="succeeded", trigger_type="manual" )] class ListSnapshotSummariesUseCaseTDD(unittest.TestCase): def test_offset_negative_raises_and_repo_not_called(self): repo = _FakeRepo() uc = ListSnapshotSummariesUseCase(repo, max_read_limit=100) with self.assertRaises(ValueError): uc.execute(limit=10, offset=-1) self.assertFalse(repo.called) def test_limit_zero_becomes_one(self): repo = _FakeRepo() uc = ListSnapshotSummariesUseCase(repo, max_read_limit=100) uc.execute(limit=0, offset=0) self.assertEqual(1, repo.last_params["limit"]) def test_limit_clamped_to_max(self): repo = _FakeRepo() uc = ListSnapshotSummariesUseCase(repo, max_read_limit=25) uc.execute(limit=999, offset=0) self.assertEqual(25, repo.last_params["limit"]) def test_passes_filters_and_offset(self): repo = _FakeRepo() uc = ListSnapshotSummariesUseCase(repo, max_read_limit=100) user_id = UUID("11111111-2222-3333-4444-555555555555") target_repo_id = UUID("66666666-7777-8888-9999-aaaaaaaaaaaa") uc.execute(limit=10, offset=5, user_id=user_id, target_repo_id=target_repo_id) self.assertEqual(5, repo.last_params["offset"]) self.assertEqual(user_id, repo.last_params["user_id"]) self.assertEqual(target_repo_id, repo.last_params["target_repo_id"]) if __name__ == "__main__": unittest.main() 仕上がったら想定するエラーかどうか、テストを走らせてみることをお勧めします。 Use Cases層 テストを書いた後で、初めて ListSnapshotSummariesUseCase クラスを実装します。 python class ListSnapshotSummariesUseCase: def __init__(self, snapshot_query_repository: SnapshotQueryRepository, max_read_limit: int) -> None: self.snapshot_query_repository = snapshot_query_repository self.max_read_limit = max_read_limit def execute(self, *, limit: int, offset: int, user_id: UUID | None = None, target_repo_id: UUID | None = None) -> list[SnapshotSummary]: if offset < 0: raise ValueError("offset must be greater than or equal to 0") safe_limit = max(1, min(limit, self.max_read_limit)) return self.snapshot_query_repository.list_snapshot_summaries( limit=safe_limit, offset=offset, user_id=user_id, target_repo_id=target_repo_id ) ペイロード検証をUse Cases層で記述 Interface Adapters層のバリデーションだけに依存せず、ドメインルールとしてテスト可能に このように1つテストを作成したら1つ実装するサイクルを作ると、意図したコード実装になりやすいです。 プロジェクトによって、1ファイルごとにするか全体のテストを先に作ってしまうかは調整すべきだと感じました。 Interface Adapters層 ユースケースの実装後、モック化していたDBへの具体的な接続処理は、後からインターフェースの中身として差し替えます。 python class PostgresSnapshotQueryRepository(SnapshotQueryRepository): def list_snapshot_summaries(self, *, limit: int, offset: int, user_id: UUID | None, target_repo_id: UUID | None) -> list[SnapshotSummary]: conditions: list[sql.Composable] = [] params: list[object] = [] if user_id is not None: conditions.append(sql.SQL("fr.user_id = %s")) params.append(user_id) if target_repo_id is not None: conditions.append(sql.SQL("fr.target_repo_id = %s")) params.append(target_repo_id) # where_clause 組み立て、limit/offset を params に追加して実行 Infrastructure層 さいごに、マイグレーションは以下のように追加します。 create table history_event ( history_event_id uuid primary key default gen_random_uuid(), user_id uuid not null references app_user(user_id) on delete restrict, fetch_run_id uuid references fetch_run(fetch_run_id) on delete set null, event_type text not null, happened_at timestamptz not null default now(), summary text not null ); create table operation_log ( operation_log_id uuid primary key default gen_random_uuid(), actor_user_id uuid references app_user(user_id) on delete set null, action text not null, target_type text not null, target_id text, happened_at timestamptz not null default now(), result text not null check (result in ('success', 'failure')), error_code text, trace_id text not null ); 監査・運用観点で operation_log を用意 CI 実行の失敗や権限エラーをすぐ追跡できる Copilotを活用するプロンプト術 クリーンアーキテクチャの骨格を作る際、AIにゼロからコードを書かせると、層の境界が曖昧になりがちです。 そこで、「型」と「依存関係」を明示することで、一発で実用的なコードを得ることができます。 実際のプロンプト例 以下のように指示を出すと、Copilotはビジネスロジックを純粋なPythonコードとして抽出し、テストしやすい構造で出力してくれます。 RepoScanner のスナップショット一覧を返す `ListSnapshotSummariesUseCase` を実装してください。 入力: limit, offset, optional filter 出力: SnapshotSummary のリストと total_count 既存エンティティ: SnapshotSummary(id, repo_name, observed_at, summary) 依存: SnapshotQueryRepository.list_snapshots(limit, offset, filter) -> (items, total) テスト（unittest スタイル）を先に示してください。 生成されたコード（抜粋） プロンプトの指示通り、まずはUse Cases層のコードが生成されます。 APIの検証とは別に、ビジネスロジックが純粋なPythonコードとして抽出され、テストしやすい構造になりました。 application/backend/src/use_cases/list_snapshot_summaries.py class ListSnapshotSummariesUseCase: def __init__(self, repo: SnapshotQueryRepository, max_read_limit: int = 100): self.repo = repo self.max_read_limit = max_read_limit def execute(self, limit: int, offset: int = 0): if limit <= 0: raise ValueError("limit must be > 0") if offset < 0: raise ValueError("offset must be >= 0") limit = min(limit, self.max_read_limit) return self.repo.list_snapshots(limit=limit, offset=offset) Interface Adapters層はリクエストを受け取り、ユースケースを呼び出すだけの「薄い」層になります。 Python @app.get("/snapshots") def get_snapshots(limit: int = 20, offset: int = 0, repo=Depends(get_snapshot_repo)): items, total = ListSnapshotSummariesUseCase(repo).execute(limit=limit, offset=offset) return {"items": [i.to_dict() for i in items], "total": total} おまけ: GitHub Actions エピソード2では、実行環境の分離や運用コストから、GitHub Actions による認証と実行をメインに据える決断をしました。 認証まわりのワークフロー（抜粋） permissions: contents: read pull-requests: read issues: read jobs: collect: steps: - name: Collect PR snapshot and persist env: GITHUB_TOKEN: ${{ github.token }} DATABASE_URL: ${{ secrets.DATABASE_URL }} permissions を明示し、 github.token （実行時トークン）を活用 外部 DB への書き込みには DATABASE_URL といった修飾済みのシークレットを利用 まとめ 今回は、「テストを先に書くことで、自然と依存を切り離す設計になる」という、TDDとクリーンアーキテクチャの相性の良さが伝わるご紹介をしました。 「どうテストするか」を考えるTDDは設計を導く最強のツール ユースケースは小さく、純粋に作り、外部の仕組みに依存しない純粋なビジネスロジックを保つ AI には型と依存関係を伝えることで、開発効率が劇的に向上する エピソード5では、さらに一歩踏み込んだCopilot運用術についてお話しします。お楽しみに！ 参考 あらためてDTOを学ぶ ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Copilot × Clean Architecture | 実装とテスト first appeared on SIOS Tech Lab .