豆蔵デベロッパーサイト

親心VSこども Wi-Fi大作戦！Raspberry Pi＆Pi-holeで徹底ペアレンタルコントロールしてみた

2026-04-09T00:00:00.000+00:00

はじめに

こんにちは。私の参加しているプロジェクトでは、毎朝の朝会で各自のコンディション（ニコニコ、ちょいニコ、普通、ちょいしんど、しんどめ、地獄など）を共有する「ニコニコカレンダー」を活用しています。
先日、私がその日の気分を「ちょいしんど」、理由に「寝不足」と入力していたことから、メンバーに「副鼻腔炎が悪化しましたか？」と心配されました。そこで「最近は副鼻腔炎は落ち着いているんですが、実は子供のネット制限のために徹夜で家庭内ネットワークをいじってまして……」と雑談をしたところ、「興味深いからぜひ記事にしてほしい！」と思わぬリクエストをいただきました。

これまでクラウド資格関連（全冠記など）の記事ばかり書いていたので、「たまには資格以外の息抜き記事も書いてみようかな」と思い立ち、今回筆をとりました。
当サイトの他の記事と違い、少し古い技術の組み合わせにはなりますが、ぜひ息抜きがてら読んでみていただけると嬉しいです。
とはいえ、今回扱っているような泥臭いネットワークの基礎知識（サブネット、DHCP、DNSの仕組みなど）を実際に手を動かして理解しておくことは、クラウド環境を設計・構築する際や、クラウド系の資格を受験する際にも非常に有用な土台となることを、 クラウド認定”ほぼ”全冠の私が保証します！

ITエンジニアの皆様におかれましては、お子さんのインターネットやゲームとの付き合い方に悩まれている方も多いのではないでしょうか。我が家で発生した問題と、エンジニアの親として実施した「本気のネットワーク対策」についてご紹介します。
（※なお、本記事に記載しているIPアドレスやサブネットなどのネットワーク情報は、セキュリティの観点から実際の数値から変更してぼかして記載しています）

我が家のネットワーク事情と事の発端

まずは前提となる我が家の状況（住環境や家族構成、働き方）は以下の通りです。

家族構成、働き方
- 子供: 中学生と小学生の2人
- 妻: たまに自宅からテレワークをする日がある
- 私（筆者）: 常に自宅の仕事部屋からフルテレワーク
住環境: 4DK
- 周辺住宅からの電波干渉が激しく、2.4GHz帯（11g等）は使い物にならない状態
- そのため、障害物に弱いが高速な5GHz帯（11a/ac/ax等）をメインにする必要がある
- また、夫婦のテレワーク（Web会議等）のため、家中のどこでも「安定したWi-Fi環境」が必須要件
- 結果として、それぞれの部屋までの物理的な距離や壁を網羅するため、Wi-Fiルータが合計3台必要

子供たちにはそれぞれ学校からタブレットが支給されており、小学生は週に一回、宿題用で持ち帰るのですが、中学生のタブレットは常に自宅に置いている状態です。
ちなみに、子供用のスマホはAndroidを持たせており、そちらはGoogleの「ファミリーリンク」機能を使って利用可能な時間をしっかりと制限しています。

しかしある日、子供が盲点となっていた「学校タブレット」をベッドに持ち込み、夜中にゲーム等をしていることが発覚しました。寝不足で朝起きられなくなり、部活も休みがちになるという悪循環に陥ってしまいました。
（なお、学校タブレットはGoogle Workspaceで管理されているのですが、「Google Workspace側でインストールするアプリや閲覧可能なサイトを制限してほしいものだが。。。」というのが親としての本音です）。

これはいけないと思い、スマホ以外の端末に対しても、最初は以下のような対策を実施しました。

Wifiルータのキッズコントロール機能を活用し、利用可能時間を制限
プロバイダ提供ルータと家庭用のBuffalo製ルータ（2台）を用いた計3台運用によるアクセスポイントの分離
- 中央ルータ（プロバイダ提供ルータ）と私の仕事部屋のルータは同じメインSSIDに設定
- 子供部屋のルータは別の「子供用SSID」に設定
ゲーム機、学校のタブレット、チャレンジタッチ（進研ゼミ）などの子供用端末は、すべて「子供用SSID」に接続させる

なお、この時点ではネットワークは分割しておらず、すべて同じメインのネットワーク（例：192.168.10.0/24）内で運用していました。

イタチごっこの始まり

初期対策で安心したのも束の間、平日の帰宅後にキッズコントロールで許可されている時間内は、勉強をせずにYouTubeを見たりゲームをしたりして過ごすようになってしまいました。

さらに悪いことに、いつの間にか子供が「メインのSSID」に接続しており、再びベッドへ端末を持ち込んでいるのを発見してしまったのです。
スマホはファミリーリンクで制限できていても、他の端末が抜け穴になっては意味がありません。寝不足で部活に行けない、勉強もできていない……。このまま子供の自制心に任せたままにするわけにはいかないと判断し、根本的なネットワーク改修を実施することにしました。

「DHCPの設定で、子供の端末にだけPi-holeのDNSを割り当てればいいのでは？」と思われるかもしれません。しかし、多くの家庭用ルータにはそこまで高度なDHCP機能はなく、また同じサブネット内にいると端末側でDNSを手動設定されるだけで簡単に突破されてしまいます。ネットワーク（サブネット）を物理的・論理的に完全に分けることで、逃げ場をなくす「境界での制御」を重視しました。

今回行った根本的な対策（ガチ構成）

ITエンジニアの親として、物理的・論理的に抜け穴を塞ぐためのネットワーク構成へと変更しました。

実は当初、賃貸物件に無償で付帯しているケーブルテレビ回線のルータがあり、子供用端末はそちらの別回線へ完全に追い出してしまう（物理的な回線分離）という強硬手段も考えました。しかし、無料回線ゆえに下り速度があまりにも遅く、本来の目的である学校の遠隔授業や調べ物に支障が出てしまっては本末転倒です。そのため、あくまでメインの高速回線を生かしつつ、論理的に安全なネットワークを構築する方向で設計しました。

なお、我が家の環境はプロバイダの提供ルータと、一般的な家庭用のBuffalo製ルータの組み合わせです。設計を考えながら、何度「ああ、VLANさえ使えればどんなに楽だったか……！」と天を仰いだことかわかりません。もし企業向けの多機能ルータなどを使っていれば、VLANを活用してスマートに論理分割できたのですが、今回はあくまで「できるだけ自宅にあるものを組み合わせて一晩で完成させる」ことを裏テーマとし、手持ちの民生機だけでそのまま徹夜で泥臭く一気に組み上げました。

Information

💡 補足: VLAN（仮想LAN）とは
物理的なLANケーブルの配線やルータの接続構成を変えずに、ネットワーク機器（スイッチやルータ）内部の設定だけで論理的にネットワークを安全に分割できる仕組みです。これがあれば、物理的なルータを複数台またがって繋ぎ、手作業で泥臭くサブネットを分離するような苦労は不要になります。

作業中、ふと「豆蔵入社以前に在籍していた会社での社内インフラ構築を思い出すな……」と深夜に我に返りつつも、実施した対策は以下の通りです。

MACアドレス制限の導入
中央のルータにMACアドレスのブラックリストを設定し、子供の端末がメインSSIDに直接繋がらないようにシャットアウトしました。
サブネットの隔離
子供用SSIDのルータを、メインサブネット配下に別のサブネット（例：192.168.20.0/24）として構築し、論理的にネットワークを隔離しました。なお、子供用サブネットをメインサブネットの下にぶら下げる構成（NAT）にしているため、メインサブネット側に置かれている家庭用プリンタなどへの通信は引き続き利用可能です。
Raspberry Piによる独自DNS（Pi-hole）の構築
特定のドメインをブラックリストで弾くこと自体は市販のルータの機能でも可能ですが、ルータの標準機能だけでは「有志がインターネット上で公開している膨大なブラックリストをそのまま継続的にインポートして使う」といった柔軟な運用が困難です。そこで、子供用のサブネット内にRaspberry Piを設置し、強力なドメインフィルタリング機能を持つ「Pi-hole」を利用して専用のDNSサーバーを構築しました。
（なぜ自宅にラズパイが転がっているのかは聞かないでください。徹夜で仕上げるために自宅の余り物を深夜にかき集めた結果、今回使用したのは少し古いRaspberry Pi 2Bです）。
DHCPによる独自DNSの強制
子供用ルータのDHCP設定を変更し、ラズパイのIPアドレスをDNSサーバーとして配布するようにしました。
特定ドメインの問い合わせ拒否と正常通信の転送（Upstream DNS）
Pi-holeのフィルタリング設定で、ゲームや動画サイトに関するDNS問い合わせをすべて拒否（ブラックホール化）しました。一方で、ブロック対象外の正常な問い合わせ（学習用サイトなど）については、Pi-holeから上位のパブリックDNS（Google DNSの 8.8.8.8 や Cloudflareの 1.1.1.1 など）へ転送させることで、安全な通信のみを許可する構成にしています。
暗号化DNS（DoH / DoT）への対策
実は学校のタブレットがDNS over HTTPS（DoH）などの暗号化されたDNS通信を使用していたため、通常のポート53のフィルタリングだけでは抜け道になってしまいます。そこで、Cloudflareなどの主要なパブリックDNSサービスに対する通信自体も拒否する設定を追加しました。
Information
💡 補足: 親（管理者）泣かせの DoH (DNS over HTTPS)
従来のDNS通信（ポート53）は暗号化されていないため、経路上に置いたPi-hole等で「どこにアクセスしようとしているか」を簡単に監視・遮断できました。しかし近年はプライバシー保護の観点から、OSやブラウザがDNS通信をHTTPS（ポート443）の暗号化通信に丸めてしまう機能（DoH）をデフォルトで利用するケースが増えています。これを使われると通信の中身がただのHTTPS通信に見えるため、ローカルのDNSサーバーが意図せずスルー・回避されてしまいます。セキュリティ的には素晴らしい技術ですが、家庭内ネットワークの管理者としては非常に悩ましい壁となります。

以上を踏まえた、最終的な我が家のネットワーク構成図は以下のようになります。

flowchart TD
    WAN((Internet)) --- CenterRouter[プロバイダ提供ルータ<br>兼 中央ルータ]
    
    subgraph MainNetwork[メインネットワーク: 192.168.10.0/24]
        CenterRouter --- WorkRouter[仕事部屋ルータ]
        
        CenterRouter -.- MainSSID((メインSSID))
        WorkRouter -.- MainSSID
        MainSSID --- ParentDevices[親・仕事用端末]
        MainSSID --- Printer[家庭用プリンタ]
        
        CenterRouter -.-x |MACアドレス制限で遮断| BlockedKids[子供用端末]
    end

    subgraph KidsNetwork[子供用ネットワーク: 192.168.20.0/24]
        CenterRouter --- KidsRouter[子供部屋ルータ]
        KidsRouter -.- KidsSSID((子供用SSID))
        
        KidsSSID --- KidsDevices[子供用端末<br>タブレット・ゲーム機等]
        KidsRouter --- PiHole[Raspberry Pi 2B<br>Pi-hole]
        
        KidsRouter -.-> |DHCPで独自DNSを強制| PiHole
        PiHole -.-x |特定ドメインの名前解決拒否<br>DoHの問い合わせもブロック| KidsDevices
    end

    KidsDevices -.-> |NAT経由で印刷可能| Printer

今後の展望と親の葛藤

これで現在のところ、子供の夜更かしネットサーフィンは完全に防ぐことができています。

親としては、本来であればこんなシステムでガチガチに管理するのではなく、できれば子供自身の自制に任せて成長を見守りたいというのが本音です。しかし現状では完全に自制に任せきりにすることができず、今回は苦渋の決断としてシステム的な制限を強めることになりました。

ただ、今回の構成も完璧ではありません。子供用サブネットから外部への標準的なDNS通信（UDP 53ポート）は通過させているため、もし今後、子供が知識を付けて、端末のネットワーク設定から自分でGoogle DNS（8.8.8.8や8.8.4.4）などを設定できるようになれば、この制限は突破されてしまいます。その場合は追加の検討が必要です。

……とはいえ、もしそこまでのネットワークの仕組みを自力で理解し、制限を突破できるほどの知識を身につけたのであれば、ITエンジニアの親としては「それはそれで喜ばしいことかもしれない？」と、少し複雑な感情も抱いています。いつかはこうした制限をすべて外し、自分自身の力でコントロールできるようになってくれることを願うばかりです。

おわりに

家庭内ネットワークも、要件（家族の働き方や子供の利用状況、リテラシー、手持ちの機材）に合わせてアーキテクチャを見直していく必要があると痛感しました。同じようなお悩みを持つ方の参考になれば幸いです。

豆蔵デベロッパーサイト 2026年1-3月のサマリー

2026-04-06T00:00:00.000+00:00

新年度が始まりました。2026年1-3月のサマリーです。

記事数・執筆者数

この3ヶ月で34本の記事が投稿され、記事数は876になりました。新たに2名が執筆デビューし、累計76名になりました。

連載

SysML モデリング連載

複雑なシステムをモデリングするための新しい言語である SysML v2。この SysML v2モデルを作成・編集するためのグラフィカル・モデリングツール、SysON を紹介するシリーズ。

/blogs/2026/01/08/sysmlv2-tool-syson-intro/

全6回の連載記事となっています。記事のインデックスは以下のリンクから参照してください。

無料のOSSツールSysONで始めるSysMLv2モデリング

スクラムマスターのAI活用

スクラムマスターの AI 活用に関する連載記事です。

/blogs/2025/12/04/scrum-ai-1/

全3回です。記事のインデックスは以下のリンクから参照してください。

スクラムマスターのAI活用を考える

記事の筆者石田がこのテーマで「豆寄席」に登壇しました。

https://mamezou.connpass.com/event/386346/

テーマ別の記事

さいごに

以上、2025年度第4四半期のサマリーでした。ロボットの記事が非常に多かった印象です。

よかったらフィードの購読、X や Bluesky でのフォローもお願いします。Facebook でも本サイトの注目記事をはじめ豆蔵に関するイベントを紹介しています。note にも時々本サイト関連の記事が掲載されています。

要件定義入門①：要件定義とはなにか　～現場での役割と全体像～

2026-04-01T00:00:00.000+00:00

要件定義入門①：要件定義とは何か　～現場での役割と全体像～

1. はじめに

要件定義という言葉はよく耳にするものの、
「実際に何をしているのか分からない」と感じる方が多いのではないでしょうか。

特に現場に入りたての頃は、実装やテストといった開発工程に関わることが多く、
要件定義については「最初にやる工程らしい」という程度の理解に留まりがちです。

そのため、
「要件定義って何をしているのだろう」
と疑問に思う場面も少なくありません。

本記事では、要件定義の役割について、
具体例を交えながら分かりやすく整理していきます。

2. 要件定義とは何か

要件定義とは、「システムが満たすべき条件（要件）を明確にし、関係者間で合意する工程」です。

ここでいう「要件」とは、
「システムが何を実現すべきか」という条件を指します。

なぜ要件定義が必要なのか

システム開発は、顧客の「やりたいこと（要望）」から始まります。

しかし、この要望を具体化せずに開発側へそのまま委ねてしまうと、
完成したものが「思っていたものと違う」という事態が発生しやすくなります。

さらに、「予算」「人員」「技術的な制約」といった要因により、そもそも実現が難しいケースもあります。

要件定義でやっていること

そのため、要件定義では以下のようなやり取りを繰り返します。

顧客の要望を整理する
実現可能性を開発側で検討する
実現方法や制約を踏まえて提案する
顧客が提案内容を確認・調整する

このプロセスを繰り返し、
最終的に「これを作る」という合意内容を定義します。

要件定義は、
「要望」と「現実（制約）」のすり合わせを行い、
実現可能な形に落とし込む工程とも言えます。

また、顧客がすべてを明確にできるとは限らないため、
開発側が質問や提案を通じて要件を具体化していくことが重要です。

3. 設計とはどう違うのか

要件定義とよく混同されるのが「設計」です。

両者の違いは、以下のように整理できます。

要件定義：何を作るか（What）
設計：どのように作るか（How）

具体例

例：ユーザーがログインできる機能。

要件定義
ユーザーがIDとパスワードでログインできる
設計
認証方式はJWTを使用する
パスワードはハッシュ化して保存する

要件定義の段階で設計の話をしてしまうと、
後から要件変更があった際に柔軟に対応できなくなります。

そのため、「What」と「How」を意識的に分けることが重要です。

4. 基本的な流れ

要件定義は、一般的に以下のような流れで進みます。

「要望」と「要求」は似ていますが、本記事では以下のように定義します。

要望：顧客の主観的なやりたいこと
要求：具体化されたニーズ

5. 具体例

例：勤怠管理システム。

本節では、要件定義の流れを具体的なケースに当てはめて整理します。

■ 要望（やりたいこと）

顧客の初期的な要望は、抽象的な状態で提示されることが一般的です。

（例）
「社員の勤怠を管理したい」

※この段階では、業務フローや必要な機能は明確になっていません。

■ 要求（具体化されたニーズ）

開発側がヒアリングを通じて、要望を具体的な要求へと整理します。

（例）

「出勤・退勤時刻を記録したい」
「スマートフォンから打刻できるようにしたい」
「月ごとの勤務時間および残業時間を集計したい」

■ 整理・検討（要求の整理・実現可能性の確認）

要求を整理し、開発側が以下のような観点で検討します。

業務要件として妥当か（業務フローとの整合性）
技術的に実現可能か
コスト・スケジュールに収まるか

必要に応じて、要求の取捨選択や優先度付けも行います。

■ 提案（実現案の提示）

検討結果を踏まえ、開発側から具体的な実現案を提示します。

（例）

「Webアプリケーションとして提供する」
→ PCおよびスマートフォンのブラウザから利用可能とする
「打刻方法はブラウザベースとする」
→ 専用アプリ開発は行わない（開発コスト・期間を考慮）
「既存の人事システムとの連携は行わない」
→ 初期リリースでは単体運用とし、将来的な拡張を検討する

また、必要に応じて以下のような観点も提示します。

機能の優先度（必須 / 任意）
スコープ（今回対応範囲）
トレードオフ（コスト・品質・スピード）

■ 検討（顧客側確認）

提案内容について、顧客側で妥当性を確認します。

業務上問題なく利用できるか
必要な機能が満たされているか
不足・過剰な要件がないか

必要に応じて、再度要望の修正・追加をします。

■ 合意（要件確定）

顧客と開発側で内容に合意し、
「何をどこまで実現するか」を確定します。

この合意内容が、以降の設計・実装の基準となる「要件」となります。

6. まとめ

要件定義は「何を作るか（What）」を決める工程
要望と制約をすり合わせ、実現可能な形にする
開発側が主体的に要件を具体化していくことが重要

要件定義は単なる前工程ではなく、
プロジェクト全体の品質を左右する重要な工程です。

次回は、実際に要件をどのように洗い出し、整理していくのかを解説します。

最先端ロボ×AIで遊ぼう！LeRobotとSO-101でマルチモーダルAIを体験＆環境構築ガイド

2026-03-31T00:00:00.000+00:00

こんなひとにおすすめ

マルチモーダルAI、フィジカルAI、模倣学習、強化学習などロボティクス分野のAIに興味はあるが、どこから手をつけたらいいのか分からない方
実機のロボットの価格が高くて試せないと感じている方
手を動かして学びたいが、低コストで始めたい方

はじめに

本記事では、オープンソースプロジェクトである LeRobot とオープンソースのアームロボットである SO-101 を題材に、マルチモーダル AI に関する技術紹介と環境構築の手順を解説します。
最終的なゴールは、片方のアームを動かすともう片方のアームが同じ動作を追従する動作を再現することです（下記GIF参照）。

用語の説明

マルチモーダルAI とは

従来のロボティクス開発では、ロボット本体、カメラ、通信規格など複数の技術（モダリティ）が個別に動作し、出力されるデータ形式も異なるため、それらを統合して1つのシステムとして運用するのは容易ではありませんでした。

近年、Transformer 系モデルなどの進展により、画像・音声・テキスト・センサー値など複数モダリティを統合して扱う「マルチモーダルAI」の研究・実装が進んでおり、異なるデータ形式の扱いや統合が以前より容易になっています。

これに伴い、ロボティクス領域では前述の問題点の解消が期待され、マルチモーダルAIを活用した開発が増えつつあります。

Information

似たような用語として「フィジカルAI」が存在します。こちらはロボットや物理世界での学習・意思決定に焦点を当てる用語で、マルチモーダルAIと重なる部分が多いですが、本記事では区別せず「マルチモーダルAI」として扱います。

LeRobot とは

公式リポジトリ：LeRobot

LeRobot は Hugging Face が公開しているオープンソースのロボティクスライブラリで、実ロボット向けのモデル、データセット、ツールを提供しています。LeRobot を使うことで多様なロボットの制御やデータ収集、学習ワークフローの構築が容易になります。
本記事ではLeRobotのインストールと設定に焦点を当て、最終的にSO-101を動作させる手順を説明します。^[1]

SO-101 とは

公式リポジトリ：SO-101


SO101 Follower の画像。実物のロボットに近しい構成となっている。	SO101 Leader の画像。人間が操作しやすいようにグリップ部分がある。

SO-101 は RobotStudio と Hugging Face が共同で開発した、低コストのオープンソース・ロボットアームで、ロボティクス分野への参入ハードルを下げることを目的としています。

SO-101 は「Leader（先導者）」と「Follower（従者）」の2台のロボットアームで構成されます。一般的な利用では Leader をユーザーが手動で操作してデータ収集をし、Follower はその記録や学習済みモデルに基づいて同じ動作を再現することを想定しています。

本記事では SO-101 の入手方法と、LeRobot で動かす際に必要な手順を解説します。

動作環境

本記事では環境構築の手順に重点を置くため環境要件は簡略化しますが、LeRobot の多くのチュートリアルが CLI 操作を前提としていることから OS は Linux または macOSを推奨します。
本記事では整合性を図るために、Linux を前提としています。

GPU に関して

将来的に LeRobot と SO-101 で学習するのであれば、VRAM容量が 8GB 以上の GPU も必要となります。

あると便利なもの

本記事の手順を遂行するのに必ずしも必要ありませんが、以下の物があると便利です。

2口以上の電源タップ：2台のロボットアームへの電源供給に必要なため。
2口以上で電源供給可能な USB3.0 ハブ：2台のロボットアームをPCに接続するため。
タックシール：複数のモーターや部品を管理しやすくするため。

タックシールに関しては、ダイソーのタックシールキレイにはがせるタイプ５２５枚をおすすめします。こちらは SO-101 のほぼ全てのパーツの大きさに対応しており、下記画像のようにラベリングが可能になります。


タックシールを用いて、モーターをラベリングしている時の画像。	タックシールを用いて、モーターバスをラベリングしている時の画像。

環境構築方法

こちらでは LeRobot と SO-101 を用いた環境構築の手順を解説します。
手順としては次のように進めますが…

事前に SO-101 の印刷（もしくは購入）を確認いただき、SO-101 のパーツを揃えることをおすすめします。

LeRobot の環境構築方法

LeRobot の環境構築方法は Hugging Face の Installation ページを参照しているため、重要な手順に絞って解説します。

0. 【任意】conda 系のパッケージがインストールされていない場合

LeRobot は複数の Python パッケージを扱うため、Conda を用いて仮想環境を構築することを勧めている。そのため、Conda がインストールされていない場合は下記コマンドでインストールします。

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

1. 仮想環境構築

Conda で仮想環境を構築する

# 下記の lerobot は構築する環境の名前なので、お好きなものに変えても構いません
# その場合、他の手順も同様に変更を加えてください
conda create -y -n lerobot python=3.12

Conda の仮想環境をアクティブする
```
conda activate lerobot
```
ffmpeg を仮想環境にインストールする
```
conda install ffmpeg -c conda-forge
```
LeRobot の現在のバージョンでは、ffmpeg のバージョン 8.x に対応していないので、前のコマンドでインストールされた ffmpeg のバージョンを確認します：
```
ffmpeg -version
```
このとき、ffmpeg のバージョン 8.x になっていれば、下記コマンドで ffmpeg のバージョンをダウングレードします：
```
conda install ffmpeg=7.1.1 -c conda-forge
```

2. LeRobot をインストールする

LeRobot はリポジトリのソース、もしくは PyPl からインストール出来ます。将来的に個人開発したい場合は、コードの編集が可能なソースからのインストールを推奨します。

リポジトリのソースからインストールする場合は下記コマンドを実行します。

git clone https://github.com/huggingface/lerobot.git
cd lerobot
# 編集可能モードで Conda 環境にインストールする
pip install -e .

PyPl からインストールする場合は下記コマンドを実行します。

pip install lerobot

SO-101 の環境構築

1. SO-101 の印刷（もしくは購入）

SO-101 のハードウェア構成は公式リポジトリで公開されています。
リポジトリの3Dデータを使ってパーツを3Dプリントするか、リポジトリで案内されている公認販売サイトからパーツキットを購入して、Follower と Leader の両アームを組み立てられます。

注意点として、公式リポジトリで入手できるのは主に外装・機構パーツで、サーボモーターなどの駆動部品は別途用意する必要があります。モーター購入時は公式リポジトリ内の Parts For Two Arms (Follower and Leader Setup): の記載を参照するか、公認販売元のキットを購入してください。

参考として、筆者の場合は公式リポジトリで紹介されていた秋月電子通商のサイトから、以下の2つのキットを購入しました。また、説明の整合性を図るために、これらのパーツを基準として手順を解説します。

2. SO-101 のセットアップ

SO-101 のはセットアップ Hugging Face の SO-101 ページを参照しているため、重要な手順に絞って解説します。また、前述でも触れましたが、SO-101 は Leader と Follower の2台のロボットアームで構成されるため、一部の手順が異なる点には留意してください。

初めに下記のコマンドで　SO-101 を動かすために必要な SDK をインストールします。

pip install -e ".[feetech]"

2.1. モーターの仕分け

参考リンク：Configure the motors

初めに前のセクションで用意したモーターを Leader と Follower 用に分けます。Leader 側は複数種類のギア比を持つモーターで構成されるのに対し、Follower 側は同一仕様（1 / 345）のモーターで構成されるためです。

Leader の各関節に割り当てるモーターID （後述を参照）とギア比は次の通りです。

Leader-Arm Axis	Motor	Gear Ratio
Base / Shoulder Pan	1	1 / 191
Shoulder Lift	2	1 / 345
Elbow Flex	3	1 / 191
Wrist Flex	4	1 / 147
Wrist Roll	5	1 / 147
Gripper	6	1 / 147

モーターの種類は本体のラベル（シール）で判別できます。Leader 用モーターにはギア比が明記されていることが多く、Follower 用は同一仕様のためギア比の表記がないことがあります。

2.2. MotorBus（モーターバス）のセットアップ

モーターの仕分けが終わりましたら、モーターバス（下記画像参照）の設定します。

モーターバスは複数のモーターをまとめて管理・通信するための機器です。
前セクションで分けた Leader 用の全モーターに対して1台、Follower 用の全モーターに対して1台のモーターバスを用意します。このとき、Leader と Follower のモーターを誤って混同すると後で修正が大変なので、タックシールなどで全モーターにラベルを貼り、どのモーターバスに対応させるかを明確にするといいです。

以降の手順では便宜上、次の略称を使います。

Leader用モーターバス：Leader_MB
Follower用モーターバス：Follower_MB

Leader_MB と Follower_MB の電源を入れ、PC に接続する。
各モーターバスの USB ポートを確認する。

両方のモーターバスを接続した状態で下記を実行する。
スクリプト実行中に指示が出たら、Leader_MB の USB ケーブルを抜いて Enter キーを押す。
```
lerobot-find-port
```
例）スクリプトの出力例：
```
Finding all available ports for the MotorBus.  
['/dev/ttyACM0', '/dev/ttyACM1']  
Remove the usb cable from your MotorsBus and press Enter when done.

#（対応する Leader_MB のケーブルを抜いて Enter を押す）

The port of this MotorsBus is /dev/ttyACM0
Reconnect the USB cable.

#（対応する Leader_MB のケーブルを差し直す）
```
Reconnect the USB cable. が表示された時点で Leader_MB のケーブルを差し直してください。上記例では /dev/ttyACM0 が Leader_MB のポートとなるので、こちらを記録してください。

同様に Follower_MB の USB ケーブルを抜いて、Follower_MB のポートを確認・記録してください。上記例では /dev/ttyACM1 が Follower_MB のポート番号になりますが、環境によっては異なることには注意してください。
Linux のデバイス権限に関して
Linuxではデバイスファイルのアクセス権が原因で認識できないことがあるため、必要に応じて以下を実行して権限を付与してください。下記例では ttyACM0 デバイスの権限を変更しておりますが、デバイス名は環境により変わることには注意してください。
```
sudo chmod 666 /dev/ttyACM0
```

2.3. モーターとモーターバスを連動させる

出荷時のモーター ID はすべて 1 に設定されているため、モーターバスと正しく通信・連動させるには各モーターに一意の ID を割り当てる必要があります。
まずは Leader_MB を設定するために、下記コマンドを実行してください。

lerobot-setup-motors \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 # Leader_MB のポート番号

--robot.port= には MotorBus（モーターバス）のセットアップで確認した Leader_MB のポートを入力します。確認しポートが/dev/ttyACM0 以外であれば、適切に変更してから実行してください。

PC と Leader_MB の通信が確率すると、下記メッセージが表示されます。

Connect the controller board to the '＜関節名＞' motor only and press enter.

ここで表示される <関節名> は、これから ID を割り当てるモーターが担当する関節名（例：gripper）を示します。手順は次の通りです。

モーターの仕分けで用意したモーターとその章のテーブルと照合して、該当する種類のモーターを準備する（例：gripper → ギア比 1 / 147 のモーター）
該当モーターをモーターバスに接続する（モーター付属ケーブルを使う）
ターミナルで Enter キーを押す

ID 割り当てが正常に行われると、次のように表示されます。

'＜関節名＞' motor id set to ＜ID＞

続けて他の Leader 用モーターにも同様に ID を設定してください。これら手順の一連の流れは下記の公式動画から確認できます。

Leader_MB の設定が終わったら、同じように Follower_MB の設定します。前述の通り、Follower 側のモーターは同一のギア比で構成されていることが多いので、モーターが担当する関節名を照合する必要はありません。ただ、設定した ID を混同しないよう、留意してください。

アドバイス

公式リポジトリの動画ではモーターを既にアームに取り付けた状態で ID を設定していますが、筆者は取り付け前に ID を設定することをおすすめします。Leader 側は複数のギア比の異なるモーターで構成され、取り付け済みだと種類判別が難しく、誤った位置に取り付けると分解・ID 再設定が必要になるためです。
事前にIDを振り、ラベル（タックシール等）で識別してからアームに組み付けるとトラブルを大幅に減らせます。

2.4. ロボットアームの組み立て

SO-101 の組み立て手順は多岐にわたるため、まずは公式チュートリアル動画や販売元の組み立て動画を参照してください。

Warning

組み立て後は、各公式ページやチュートリアルで案内されているキャリブレーション手順に従ってモーターの位置合わせを必ず行ってください。キャリブレーションが不十分だと関節角がずれて想定外の姿勢で動作し、周囲の物や人にぶつかるなど危険が生じます。

アドバイス

組み立てに関しては、上記のいずれかの動画を見ていけばいいのですが、サーボホーン（下記画像参照）でいくつかアドバイスをしたいと思います。

サーボホーンにロボットアームの外装・機構パーツを固定する際は、大きなネジを使います。モーター本体をロボットアームに固定するためには、小さなネジを使います。
サーボホーンは「凸部（突起）」が外側（表）に見える向きではなく、突起が見えないように裏返して取り付けてください（平らな面を表にする）。裏表を誤るとネジが最後まで締まらず、アームの可動域やスムーズさに影響することがあります。^[2]

3. 動作確認

参考リンク：Imitation Learning on Real-World Robots

最後に、LeRobot が提供する模倣学習のサンプルコードを使って、Leader から Follower へのテレオペレーションで動作確認を行います。モーターバスがPCに接続されていることを確認してから、下記コマンドを実行します。

lerobot-teleoperate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \ # MotorBus（モーターバス）のセットアップで確認した Follower_MB のポートを入力してください
    --robot.id=my_awesome_follower_arm \ # 好きな変数名を入力してください
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyttyACM0 \ # MotorBus（モーターバス）のセットアップで確認した Leader_MB のポートを入力してください
    --teleop.id=my_awesome_leader_arm # 好きな変数名を入力してください

今までの手順が正しく行われていれば、はじめにの章の GIF のように、Leader を動かすとFollower が追従して動作します。

最後に

本記事は LeRobot と SO-101 を使ったフィジカルAI入門として、環境構築と基本的な動作確認手順を紹介しました。今後も機会があれば、LeRobotを使った学習（模倣学習・強化学習）や、ロボティクス領域のAI手法の詳細について掘り下げていく予定です。

機会があれば、学習方法に関して記事を書くかもしれません。 ↩︎
著者はこれのせいで、組み立て済みのロボットアームを分解して、再度組み直すことになりました。 ↩︎

AWS QuickSightのCI/CD環境構築：第1章ダッシュボードの自動バックアップ（Git管理）

2026-03-30T00:00:00.000+00:00

はじめに

こんにちはDX戦の檜尾です。
初めての投稿になりますドキドキ。

日々の業務において、AWSQuickSightのダッシュボード定義をコードとして管理する「BI as Code」の重要性が高まっていると感じます。
従来のGUI上での直接編集はアジリティが高い反面、変更履歴の追跡や誤操作によるロールバックが困難になるという運用上の課題を抱えています。
AWSではこれらの問題に対してビジネスインテリジェンス運用 (BIOps)という考えを適用しようとしています。
DevOpsで行っていたことをBIでも適用できるのではないかということですね。

本記事では、QuickSightの定義ファイルをGitでバージョン管理し、安全に運用するためのCI/CDパイプライン構築手順を全3章に分けて解説します。

第1章：自動アップロード（本記事）
QuickSight上でのダッシュボード公開をトリガーとし、定義ファイル（JSON）を自動的にGitHubへバックアップする仕組みを構築。
第2章：自動テスト（次回予定）
エクスポートされた定義ファイルに対する静的解析や、依存するデータセットの整合性チェックを自動化する仕組みを解説予定。
第3章：自動デプロイ（次々回予定）
GitHub上でレビュー・マージされた定義ファイルを、別環境（本番環境等）のQuickSightへ自動でデプロイするパイプラインを解説予定。

今回はベースとなる第1章：自動アップロード環境の構築について、具体的なアーキテクチャと実装手順、および構築時に陥りやすい技術的な仕様（Tips）を解説します。

第1章：自動アップロード環境の構築

本章では、QuickSightの「Asset Bundle API」を活用し、イベント駆動型でダッシュボード定義を抽出・保存します。

1. 全体の流れ

AWS CloudTrail / Amazon EventBridge: QuickSightにおけるダッシュボードの公開（UpdateDashboard / CreateDashboard）を検知。
AWS CodeBuild: EventBridgeをトリガーとして起動し、Pythonスクリプトを実行。
AWS QuickSight (Asset Bundle API): CodeBuildからのリクエストに応じ、ダッシュボードの定義をJSON形式でエクスポート。
GitHub: 抽出されたファイルをCodeBuildが対象リポジトリへCommitおよびPush。

2. 実装手順

Step 1: GitHub認証情報のAWS Secrets Managerへの登録

CodeBuildがGitHubへアクセスするためのPersonal Access Token (PAT) を発行し、AWS Secrets Managerに保存します。

シークレットのタイプ: その他シークレットのタイプ
キー/値のペア: UIのキー・値入力ではなく、「プレーンテキスト」タブから以下のJSON形式で保存する必要がある。理由はCodeBuildのソースフェーズで ServerType is required エラーが発生する為。

{
  "ServerType": "GITHUB",
  "AuthType": "PERSONAL_ACCESS_TOKEN",
  "Token": "ghp_から始まるPAT"
}

シークレット名: QuickSightGitHubToken

Step 2: 実行スクリプトの配置

バックアップ先となるGitHubリポジトリの直下に、エクスポート処理を担うPythonスクリプトとCodeBuildのビルド仕様ファイルを配置します。

1. export.py
Boto3を使用してAsset Bundle Export APIを呼び出します。今回はダッシュボード定義のみを対象とするため、IncludeAllDependencies=False を指定しています。

import boto3
import time
import requests
import zipfile
import io
import os
import uuid

account_id = os.environ['AWS_ACCOUNT_ID']
raw_dashboard_id = os.environ['DASHBOARD_ID'] # EventBridgeからARNが丸ごと渡ってくる
region = os.environ['AWS_REGION']

dashboard_id = raw_dashboard_id.split('/')[-1]

client = boto3.client('quicksight', region_name=region)
job_id = str(uuid.uuid4())
arn = f"arn:aws:quicksight:{region}:{account_id}:dashboard/{dashboard_id}"

print(f"Exporting dashboard: {dashboard_id}")

# エクスポートジョブの開始
client.start_asset_bundle_export_job(
    AwsAccountId=account_id,
    AssetBundleExportJobId=job_id,
    ResourceArns=[arn],
    IncludeAllDependencies=False, 
    ExportFormat='QUICKSIGHT_JSON'
)

# 非同期処理の完了待機（ポーリング）
while True:
    response = client.describe_asset_bundle_export_job(
        AwsAccountId=account_id,
        AssetBundleExportJobId=job_id
    )
    status = response['JobStatus']
    if status == 'SUCCESSFUL':
        url = response['DownloadUrl']
        break
    elif status in ['FAILED', 'FAILED_PARTIAL']:
        raise Exception("Export failed!")
    time.sleep(5)

# アーカイブのダウンロードと展開
res = requests.get(url)
with zipfile.ZipFile(io.BytesIO(res.content)) as z:
    z.extractall("quicksight_backup")
print("Download and extraction complete.")

2. buildspec.yml
CodeBuildの動作を定義します。

version: 0.2

env:
  secrets-manager:
    GITHUB_TOKEN: "QuickSightGitHubToken:Token"

phases:
  install:
    runtime-versions:
      python: 3.11
    commands:
      - pip install boto3 requests
  build:
    commands:
      - python export.py
  post_build:
    commands:
      - git config --global user.name "QuickSight Auto Backup"
      - git config --global user.email "bot@example.com"
      - git remote set-url origin https://${GITHUB_TOKEN}@github.com/YourOrg/YourRepo.git
      - git add quicksight_backup/
      - git commit -m "Auto backup dashboard ID - ${DASHBOARD_ID}"
      - git push origin main

Step 3: IAMロールとCodeBuildプロジェクトの作成

CodeBuildに付与するIAMロールには、最小権限の原則に従い以下のポリシーをアタッチします。

quicksight:StartAssetBundleExportJob
quicksight:DescribeAssetBundleExportJob
quicksight:DescribeDashboard
secretsmanager:GetSecretValue

CodeBuildプロジェクトを作成し、ソースプロバイダとして対象のGitHubリポジトリを指定します。アカウント認証情報から接続をしておきます。また、環境変数に AWS_ACCOUNT_ID（12桁の数字）を設定します。

Step 4: EventBridgeルールの設定

CloudTrailが有効化されている前提で、EventBridgeルールを作成します。

イベントパターン:

{
  "source": ["aws.quicksight"],
  "detail-type": [
    "AWS API Call via CloudTrail",
    "AWS Service Event via CloudTrail" 
  ],
  "detail": {
    "eventSource": ["quicksight.amazonaws.com"],
    "eventName": ["CreateDashboard", "UpdateDashboard"]
  }
}

ターゲット設定:
作成したCodeBuildプロジェクトを指定し、「入力トランスフォーマー」機能を用いてダッシュボードIDを環境変数として渡します。
- 入力パス: {"dashboard_id": "$.detail.serviceEventDetails.eventRequestDetails.dashboardId"}
- 入力テンプレート:
```
{
  "environmentVariablesOverride": [
    {
      "name": "DASHBOARD_ID",
      "type": "PLAINTEXT",
      "value": "<dashboard_id>"
    }
  ]
}
```

ここまでの実装でダッシュボードを公開すると、自動的に裏側のGithubにダッシュボードのバックアップができるようになります。

3. Tips: 構築時におけるQuickSight APIの技術的制約と解決策

自動化パイプライン構築において、QuickSight特有の仕様によりエクスポートが FAILED となるケースがあります。以下に代表的な事象とその解決策を提示します。

事象: APIにおけるローカルファイルデータセットの非互換性

IncludeAllDependencies=Trueを指定時、File source type is not supported in Public API というエラーが発生する。

原因: Asset Bundle APIは、ユーザーが手動でアップロードしたローカルファイル（CSV/Excel等）の抽出に非対応。
対策: スクリプト側で IncludeAllDependencies=False を指定しダッシュボードのみを抽出する。もしくはデータソースをS3やAmazon Athena経由の参照モデルに改修する必要がある。

第2章・第3章に向けて

本章により、ダッシュボードの変更が自動的にGitリポジトリへコミットされる環境が整いました。これにより、変更履歴の可視化とバックアップの自動化が達成されます。

次回の第2章：自動テストでは、取得したJSON定義に対するスキーマ検証や、不要な変更が含まれていないかを自動検知する仕組みについて解説しようとおもいます。

参考資料

本環境を構築するにあたり、以下のAWS公式ドキュメントおよび公式ブログを参考にしています。さらに詳細な仕様やAPIのオプションについて知りたい方は、併せてご参照ください。

Amazon QuickSight BIOps – パート3 : API を使用したアセットのデプロイ (AWS公式ブログ)
Boto3 Documentation: QuickSight - start_asset_bundle_export_job
- Python (Boto3) からエクスポートジョブを実行する際の、詳細なパラメータ（IncludeAllDependencies 等）。
AWS CloudTrail を使用した Amazon QuickSight API コールのログ記録 (AWS公式ドキュメント)
- QuickSightでの操作がどのようにCloudTrailに記録されるか（API Call と Service Event の違いなど）の仕様が記載。
AWS CodeBuild の buildspec リファレンス (AWS公式ドキュメント)
- buildspec.yml 内で AWS Secrets Manager から安全に認証情報（GitHub PAT）を取得するための構文規則について解説。

🤖ABBロボットコントローラにPC-SDKで連携するときの落とし穴10選🕳️

2026-03-26T00:00:00.000+00:00

2025年10月8日、ロボット産業を揺るがす大きなニュースが飛び込んできました。
ソフトバンクグループがスイスの重電大手 ABB^[1] から、ロボティクス部門を買収する記事でした。

ちょうどそのころ私はABBのロボットコントローラと連携するプログラムの開発で日夜格闘していました。
ロボット制御APIである PC-SDK^[2] を使った連携を試みましたが、何度も落とし穴に落ちました。
まさに「死にゲー」をプレイしている感じです。何度も失敗を繰り返しながら、APIの動作を確認し、使い方を覚え、最適な手順を考えて１つ１つ問題やタスクを解決していきました。

この体験は今となってはPC-SDK攻略のための私のノウハウになっています。そこで印象に残った落とし穴を10個ピックアップしました。どのような落とし穴があるのか、どのようにして回避したのかを備忘録も兼ねて公開したいと思います。

ロボット開発の前提知識

オフラインティーチングやロボット制御APIとは何かを知りたい場合は「産業用ロボットの教示方法とその応用」をご覧ください。

PC-SDKとは

ここで紹介するPC-SDKとは、PCからABBのロボットコントローラ/ロボットを制御・監視するための開発キット(ライブラリ)を指します。
.NET Frameworkを使用して、Windows PC上で動作するカスタムアプリケーションを作成できます。.NET Framework依存かつ後述する通信ドライバがWindows専用のためLinuxには対応していないようです。

主な機能

コントローラ状態アクセス: ロボットコントローラの実行状態、ロボットの姿勢取得、I/O信号の読み書き
プログラム操作: プログラムのロード、開始、停止
データアクセス: ロボットプログラムの変数の読み書き
ファイル転送: PCとロボットコントローラ間でのファイル送受信処理

シミュレータ環境での利用

開発時に使用するツールとしては PC-SDK の他に RobotStudio^[3] があります。RobotStudioは仮想ロボットコントローラを内包し、GUIアプリケーションでオフラインティーチングが行えるアプリケーションです。PC-SDKは、この仮想ロボットコントローラに対しても接続できるためRobotStudioがあれば実機が無くてもPC-SDKによる開発ができます。

落とし穴ティア表

PC-SDK利用時に遭遇する落とし穴をダメージレベルごとにランク付けしました。これをベースに落とし穴を評価します。

ランク	ダメージレベル
S	あり得ないだろ！？どうやって回避するの？精神的ダメージを受けるレベル
A	え、何で？びっくりしたー。た、たぶん・・・なんとかなるよねレベル
B	なるほど、まあよくあるよね。やられたなぁレベル
C	事前に回避可能または落ちても痛くないレベル

あくまでも個人の感想です。

🕳️1. Web上の情報が少ない B

落とし穴
オープンソースのライブラリを使っているとき、解らないことがあればネットで検索しますよね。同じ要領でPC-SDKに関する情報やAPIを検索すると、ほとんど情報がなくABBのサイトかStack Overflowのようなプログラミングに関する題材を扱う英語のQAサイトが表示されます。

日本語で書かれた個人サイトやABB以外のテック企業による説明などはほとんどありません。ABBのサイトもサンプルコードは非常に少ないです。そのため、英語のQAサイトを丹念に調べ、翻訳^[4] しながら内容を確認します。
ただし、あまり有用な情報が得られない場合や5年～10年前の古い情報だったりすることもあります。

対策
オフィシャルサイト(またはネット検索)からAPIリファレンスや取説などがPDFファイルでダウンロードできます。手元に置いておき１次資料としてザックリと内容を把握しておき、解らないことがあればそこから調べます。

最近はGoogleのNotebookLMを使ったりしています。APIリファレンスや取説のPDF、情報として有益なサイトをNotebookLMに登録しておけば、プロンプトで質問ができます。また要約してくれてエビデンスも表示されるので自分で検索するよりも簡単に情報にアクセスできます。

🕳️2. AIが頻繁にハルシネーションを起こす B

落とし穴
最近は何か解らないことがあれば検索ではなくAIに問い合わせることが多いのですが、
「PC-SDKのAPI xxxx について使い方を教えて」
「xxxxを使ってxxxxxの処理のサンプルを提示して」
などプロンプト入力すると先ほどの「🕳️1. Web上の情報が少ない」の影響か、存在しないAPIや引数が間違えているコードサンプルを出力します。

さらっと自然に嘘をつきます。誤りを指摘しつつ再度プロンプト入力すると、今度は別の引数が間違っていたり、古いコードで動作しないものが出力されたりしてほとんど役に立たないことがあります。

対策

Visual Studioなどでプロジェクトを作成し、PC-SDKのライブラリを参照させ、オブジェクトブラウザでAPIを確認する
PC-SDKに付属する abb.robotics.controllers.pc.xml をエディタで開きAPIに関する説明情報を参考とする

🕳️3. ロボットコントローラが見つからないことがある A

落とし穴
APIではローカルネットワーク上で動作しているロボットコントローラを検索(UDPブロードキャスト)し、見つかったロボットコントローラに対してログインしてロボットコントローラに接続します。
RobotStudioはローカルPC上で動作しているため一瞬で接続できますが、運用環境ではロボットコントローラの検索でタイムアウトになったり、２回目の検索で検知するといった謎の現象が発生しました。

対策
ネットワークインタフェース(NIC)が複数ある環境(4とか8とか)ではどのネットワークを探せばよいのかわからないため検索時にタイムアウトとなり見つからない現象が発生していました。これを解決するには検索する前にロボットコントローラのIPアドレスを指定してあげます。

実機ロボットコントローラへの接続例

var scanner = new NetworkScanner();

// ロボットコントローラのIPアドレスを直接指定して、スキャナの探索リストに登録する
// これにより、どのNICを通すべきかPC-SDKが判断する
NetworkScanner.AddRemoteController("xxx.xxx.xxx.xxx");

// 事前に取得しておいたロボットコントローラのUUIDを指定して検索する
var systemId = Guid.Parse("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
// systemId, 待ち時間[msec], リトライ数
var controllerInfo = scanner.Find(systemId, 1000,3);

if (controllerInfo == null)
{
    throw new Exception("コントローラが見つかりませんでした。");
}

// 実機に接続
_controller = Controller.Connect(controllerInfo, ConnectionType.Standalone);

IPアドレスを指定するのならFind()を使う意義は薄いと思いますが、これで解決します。

🕳️4. 制御権の獲得し忘れ C

落とし穴
ロボットコントローラに接続し、下記のような状態変更を促す処理を行うとエラーになります。

RAPID^[5]変数の値を更新する
サーボモーターをOnにする
RAPIDプログラムをロード(タスク割り当て)する
RAPIDプログラムを開始する

対策
コントローラにMastershipのリクエスト(書き込み権限のリクエスト)して取得してから更新します。サンプルコードや検索すれば例はいくらでも出てきますので慌てることはありません。

Mastershipのリクエスト

using (Mastership.Request(_controller))
{
    // ここで更新処理を記述
}

ただし、Mastershipのリクエストに失敗することがあります。リトライ処理を入れたり、例外処理でエラー処理を記述するなどの仕組みが必要です。
なお、コントローラの状態の取得やRAPID変数の値取得などReadOnlyなものはMastershipのリクエストは必要ありません。

🕳️5. 運用環境でロボットコントローラと接続できない S

落とし穴
開発環境でRobotStudio上の仮想ロボットコントローラには接続できています。しかし、運用環境でロボットコントローラに接続するとIPアドレス等が正しく ping も通るのにロボットコントローラの状態が取得できない。

開発環境の構成

運用環境の構成

対策
RobotStudioをインストールすると、(裏で)ロボットコントローラと通信するためのドライバもインストールされます。これがないと通信できません。

運用環境ではRobotStudioは不要なのでインストールせず、PC-SDK(ライブラリ)だけを利用するとドライバがインストールされていないのでエラーになります。

ABBのサイトから RobotWare_Tools_and_Utilities_x.x.x.zip (x.x.xはバージョン)をダウンロードし、展開して RobotCommunicationRuntime/ABB Industrial Robot Communication Runtime.msi を実行するとドライバがインストールされPC-SDKで接続できるようになります。こんなん解らんて。

🕳️6. リモートPCから RobotStudio に接続できない C

落とし穴
先ほどの「🕳️5. 運用環境でロボットコントローラと接続できない」を開発環境で検証しました。

PCを2台用意する
一方(Aとする)をアプリケーション動作環境とする
もう一方(Bとする)をロボットコントローラとみなしてRobotStudio(仮想ロボットコントローラ)をインストールする
AとBに RobotWare_Tools_and_Utilities_x.x.x.zip のドライバをインストールする
AからPC-SDKでBの仮想コントローラに接続する

接続テスト環境の構成

上記を試みましたが、あえなく撃沈。接続できせんでした。

対策
RobotStudioはローカルPC上からのアクセスしか受け付けないためリモートPCからの接続はできない仕様のようです。
これはライセンスが絡んでいる(1 RobotStudio 1ライセンス)からではないでしょうか。仕方がないですね。

🕳️7. 運用環境でRAPID を実行できない A

落とし穴
RobotStudio上ではログインして問題なくRAPIDのロードや実行ができます。しかし、運用環境ではコントローラに接続できましたが、RAPIDのロードや実行を指示すると例外が発生します。何で？

対策
ロボットコントローラに接続する際のデフォルトユーザーは Default User ですが RobotStudioと運用環境とで権限が異なっています。
様々な権限がありますが実行権限とプログラムのロード権限に違いがありました。

権限	RobotStudio	実機
実行権限	あり	なし
ロード権限	あり	なし

Default UserでもRobotStudioではさまざまな権限が最初から付与されているようですが、実機では権限が付与されていないものがありました。
そのため、実機上に新しくユーザーを作成し、RobotStudio上と同じことができるように権限を付与し、そのユーザーでログインしたところ実行できました。

なお、RobotStudio上での仮想コントローラではユーザーの作成や権限を付与する機能はなく、実機コントローラでのみ可能となっているのもハマった理由として挙げられます。

🕳️8. デジタル出力ができない B

落とし穴
ロボットコントローラには各種デバイスとデジタル信号(0 or 1)で連携するための物理インタフェース(I/Oポート)があります。この出力ポートに0または1を書き出すと例外が発生し、出力できませんでした。

対策
ABB ロボットコントローラではI/O設定で物理インタフェースのどこにデジタル出力を割り当てるかを指定します。このとき Access Level を指定します。デフォルト値では Default となっています。

Access Level はレベル毎に制御する側のコンテキストでRead/Writeが有効かどうかが異なっています。

Access Level	Rapid	Local Client in Auto Mode	Remote Client in Auto Mode
All	Write Enabled	Write Enabled	Write Enabled
AWACCESS	Write Enabled	Write Enabled	Read Only
Default	Write Enabled	Read Only	Read Only
Internal	Read Only	Read Only	Read Only
ReadOnly	Read Only	Read Only	Read Only

Auto Mode とは人が操作するのではなくプログラムでロボットを動かすモードを指します。
ロボットコントローラが Auto Mode のとき、ロボットコントローラの外部からアクセスしてI/Oを操作するときは一番右の Remote Client in Auto Mode 列となります。
ロボットプログラムの実行はRapid列に相当します。

今回はPC-SDKを利用して外部からロボットコントローラをプログラムで制御しているので Remote Client in Auto Mode となっています。
Access Level は Default 行となり、動作モードは Remote Client in Auto Mode 列となります。その重なり部分は Read Only となっていることがわかります。
つまり Access Level が Default だったので書き込みができない状況でした。 Access Level が Allでないと書き込みできません。厳しいですね。

というわけで、デジタル出力を割り当てるときの Access Level を All にすることで無事書き込めるようになりました。

Information

Access Level は新しく追加もできるようです。

🕳️9. 配列のデータ転送が遅い A

落とし穴

RAPID側での配列の定義

MODULE MainModule
    PERS num dataArray{100};
ENDMODULE

配列に値を書き込む一般的な記述は下記となります。

// 最初に1回だけ取得しておく
RapidData rd = _controller.Rapid.GetRapidData(
        "T_ROB1", "MainModule", "dataArray");
  :
using (Mastership.Request(_controller))
{
    for (int i = 0; i < 100; i++)
    {
        rd.WriteItem(new Num(i), i);
    }
}

このとき、rd.WriteItem()をコールするたびにネットワークアクセスします。そのためトータルで数百[msec]～数[sec]掛かります。

対策
なるべくrd.WriteItem()のコール回数を少なくし、一括でデータを設定するようにします。
RAPID側で RECORD型 で構造体を定義します。

MODULE MainModule
    RECORD StructData
        num value1;
        num value2;
        num value3;
        num value4;
        num value5;
    ENDRECORD
    :
ENDMODULE

C#側はその構造体をUserDefined型として参照できます。
UserDefined型に値を設定するときは以下のようにします。

// 最初に1回だけ取得しておく(RAPID側のStructDataのコピーを作成)
UserDefined ud = new UserDefined(_controller.Rapid.GetRapidDataType(
            "T_ROB1","MainModule","StructData"));
// 最初に1回だけ取得しておく(RAPID側のStructDataの参照を作成)
RapidData rd = _controller.Rapid.GetRapidData(
            "T_ROB1","MainModule","StructData");
  :
using (Mastership.Request(_controller))
{
    int value1 = 1;
    int value2 = 2;
    int value3 = 3;
    int value4 = 4;
    int value5 = 5;

    // UserDefinedに設定するデータを作成
    structData = $"[{value1},{value2},{value3},{value4},{value5}]";

    // UserDefinedにデータを設定
    ud.FillFromString2(structData);

    // ロボットコントローラにデータ転送
    rd.Value = ud;
}

また、RAPIDのデータ型であるrobtargetやjointtargetは非常にデータサイズが大きいです。一部のデータのみ更新するのであればその値のみ転送し、RAPID側でデータを更新して利用することも有効です。

Caution

ud.FillFromString2("[0,1,2,3,4,5,.....]") のように文字列リテラルで全要素を直接設定できます。しかし、巨大な構造体や配列の場合、途中までしか値が設定されていないことがありましたので注意が必要です。また、パース処理に時間が掛かりますがネットワークアクセスに比べると無視できるレベルです。

Caution

AIでサンプルを提示してもらうと、おそらく古いAPIかと思われますが、存在しないAPIが提示されコンパイルエラーとなりました。

🕳️10. 実機でRAPIDを実行すると実行時エラーになる S

落とし穴
RobotStudio上のシミュレータでRAPIDを実行しても問題なく動作し、プログラムの構文チェックも問題なくパスするのに、同じものを実機で動作させると実行時にエラーとなってしまう。
下記の例外が出力されたら要注意!!

Operation is illegal in current execution state

実行時エラーなので状態に起因することは分かっていますが、何の状態なのかがさっぱりわかりません。コントローラのログを見ても直接的な原因が記述されていません。
「制御あるある」ですが原因不明の実行時エラーが一番辛いです。

対策
シミュレータ上では動くことから、運用環境との環境設定の違いに原因がありそうだと直感的にわかります。プログラムの開始からどこまで進むとエラーになるかをRAPIDプログラムのソースコードを全コメントアウトし、バイナリサーチ的にコメントアウトを解除して再実行する手順で探しました。(もしかしたらステップ実行で行けたかもしれません)

結果、２つ問題がありました。

I/Oの定義が実機ではされていなかった
- シミュレータ上で定義してあったI/Oの名前(参照するときは文字列で指定)が見つけられずに実行時エラーとなっていた
割り込みタイマーのトリガー時間が実機では早すぎた
- 10[msec]としていてシミュレータ上では動作していたが、実機では実行時エラーとなっていた

上記の問題の修正自体は簡単でしたが、見つけるのに手間が掛かりました。環境の違いに起因する実行時エラーにはご注意を。

リスクを軽減するための開発スケジュール

いかがだったでしょうか？大半は開発環境(RobotStudioのシミュレータ)で問題の無かったものが、運用環境(実機コントローラ)で問題となって現れたものとなっています。しかも、穴から這い上がったと思ったらまたすぐに落とされる状況がありました。挫けそうになりますよね。

開発環境では仮想コントローラに接続するユーザーに対して、セキュリティは緩く、大きな権限を持たせています。一方、運用環境ではセキュリティは厳しく、権限も最小限にしているため不具合発生するパターンがよくありました。

運用環境が遠隔地にある場合、現地での対応には人員、時間、移動距離、金銭の面で多大なコストを要する課題があります。そのため、開発・動作確認を開発環境で行い、システムテストのみを運用環境で一括実施する計画を立てた場合、不測の事態によって進捗に遅延が生じる懸念があります。

リスクを回避するため、スケジュール内に複数のマイルストーンを設け、現地での動作確認を段階的に実施することを強く推奨します。また、現地のエンジニアに検証を委託すること(なかなか難しいですが)も、費用対効果の観点から非常に有効な手段であると考えられます。

まとめ

日本ではFANUCや安川電機(YASKAWA)といった世界トップクラスのロボティクスメーカーのマーケットシェアが高いため、欧州の雄ABBのシェアは数%程度だそうです。

ABBのロボット開発拠点はスイスにあるため、高度な技術課題については日本国内のサポートを経由し、本国の技術者へエスカレーションする場合があります。その際、時差や拠点間の連携プロセスにより、回答までに時間を要した経緯がありました。

PC-SDKについて辛口の内容ではありましたが、ロボットやロボットコントローラの機能や性能は素晴らしく、RobotStudioでのオフラインティーチング環境もトップレベルで使いやすいです。ABBのロボット部門がソフトバンクグループとなったことで日本でのシェア拡大を狙っていてもおかしくはありません。そうなると営業やサポート部門の規模や質もより重厚になると思われます。今後のABBロボット事業の展開に期待します。

今回はPC-SDKの落とし穴と題して幾つか挙げましたがRAPIDにも落とし穴が潜んでいます。機会があればそちらも記事にできればと思います。

エー・ビー・ビーと呼びます。Asea社とBrown Boveri社の合弁で設立(アセア・ブラウン・ボベリ) ↩︎
PCからABB ロボットコントローラに接続するためのSDK(ライブラリ) ↩︎
ABBが提供しているオフラインティーチング(シミュレーション)ソフトウェア ↩︎
DeepL, Google翻訳, ブラウザで右クリックして「日本語に翻訳」など ↩︎
ABBの産業用ロボットを制御するために開発された専用のプログラミング言語 ↩︎

Google Cloud認定全制覇！……まであと一歩で跳ね返されたリアルな軌跡

2026-03-26T00:00:00.000+00:00

はじめに

これまで豆蔵デベロッパーサイトで、AWS認定に関する記事（2022年の12冠達成やその後の新認定取得など）をいくつか執筆してきました。現在、AWS認定は最新の「Generative AI Developer - Professional (AIP-C01)」以外はすべて取得しています。

そんなAWS偏重な私が、今回は「Google Cloud認定の全冠」に挑戦しました。結論から言うと、約2か月で一気に制覇しようと挑んだものの、あと1歩のところで失敗してしまいました。本記事では、Google Cloud認定を目指した経緯や、短期集中で受験した所感、おすすめの受験順番、そしてなぜ失敗したのかについてまとめます。

Information

秘密保持契約（NDA）があるため、詳細な試験内容については触れることができませんので、ご了承ください。
また記載の情報は2026年3月時点のものです。

Google Cloud認定を目指したきっかけ

事の発端は、2025年夏に携わったプロジェクトです。このプロジェクトではGoogle Cloud上で開発が行われていましたが、私の担当はAWS側でのAPI開発だったため、実際にはGoogle Cloud環境を触っていませんでした。しかし、「今後のためにも知っておいた方がいいだろう」と思い立ち、勉強がてらGoogle Cloudの「Associate Cloud Engineer (ACE)」を受験し合格しました。

ちょうどその頃はAWS認定の更新時期と重なっていたため、まずはそちらを優先しました。そして2025年12月に「Japan AWS All Certifications Engineers」の条件を満たしたのを区切りとして、本格的にGoogle Cloud認定の全冠を目指し始めました。

約2か月間の怒涛の受験ラッシュとテストセンター裏話

2025年12月末のProfessional Cloud Architectを皮切りに、全冠を目指して2026年1月〜2月にかけて約2か月間で一気に受験を進めました。

以下がその受験履歴です。既に取得済みだったAssociate Cloud Engineerも一覧に含めています。

No	受験日	認定名称	略称	受験言語	結果
1	2025-09-15	Associate Cloud Engineer	ACE	日本語	合格
2	2025-12-27	Professional Cloud Architect	PCA	日本語	合格
3	2026-01-12	Professional Cloud Developer	PCD	日本語	合格
4	2026-01-17	Professional Cloud DevOps Engineer	PCDOE	日本語	合格
5	2026-01-25	Professional Cloud Network Engineer	PCNE	日本語	合格
6	2026-01-29	Cloud Digital Leader	CDL	日本語	合格
7	2026-01-31	Professional Cloud Security Engineer	PCSE	日本語	合格
8	2026-01-31	Professional Security Operations Engineer	PSOE	英語	不合格
9	2026-02-05	Associate Google Workspace Administrator	AGWA	日本語	合格
10	2026-02-08	Associate Data Practitioner	ADP	日本語	合格
11	2026-02-08	Generative AI Leader	GAIL	日本語	合格
12	2026-02-11	Professional Data Engineer	PDE	日本語	合格
13	2026-02-13	Professional Cloud Database Engineer	PCDBE	英語	合格
14	2026-02-21	Professional Machine Learning Engineer	PMLE	日本語	合格

なお、Google Cloud認定の試験プロバイダは2026年2月23日までKryterionによる配信でしたが、3月からはPearsonVUEに変更になりました。

私が受験した地域では、Kryterion時代は特定のテストセンター一択でしたが、PearsonVUEに変わったことで複数のテストセンターが選択できるようになりました。また、Kryterionでは試験日時の変更が72時間前でロックされていましたが（手数料を払えば変更可能）、PearsonVUEでは24時間前まで変更可能になったのは受験者にとってかなりの朗報です。

ちなみに、私はこの2か月間で同じテストセンターに11回も通った（2回は同日受験）ので、すっかりスタッフの方に顔を覚えられてしまいました。スタッフの方と少し雑談した際に「PearsonVUEに対応する準備をしている」と聞いていたのですが、3月中旬からPearsonVUEにも対応したとのことで、今後も通い慣れたテストセンターを引き続き利用できそうです。

受験料は「米ドル決済」である点に注意

テストセンターについての余談に関連してもう一つ、実際に短期間で大量受験して痛感したのが 受験料の支払い通貨 の違いです。
AWS認定の受験料は日本円（JPY）で確定決済されますが、Google Cloud認定の受験料はプロバイダ画面上で 米ドル（USD）決済 となります。
Professionalレベルの試験は1回200ドルかかるため、これだけの数を短期間で一気に受験すると、クレジットカードの請求額が為替レートの影響をダイレクトに受けます。会社の資格取得支援制度などを利用して経費精算をする場合は、予算申請の際に為替変動分のゆとりを持たせておくことをお勧めします。

全体的な難易度：AWS認定との比較

これだけ短期間で多くの試験に合格できたのは、 「合格した認定のほとんどがAWSの知識の焼き直しでクリアできる内容だったから」 です。加えて、Googleが提唱するSRE（Site Reliability Engineering）をしっかりと理解しておくことが大事だと感じました。

また、文章量という点でも難易度に違いがありました。AWS認定のProfessionalやSpecialityは問題文も選択肢も文章が長く、内容を把握するのに苦労しましたが、Google Cloud認定のProfessionalはほとんどがAWS認定のAssociateレベルの長さであり、読み取るのにあまり苦労しませんでした。

Google Cloud試験の鍵を握る「SREの基本概念」

複数の試験（特にCloud ArchitectやDevOps Engineerなど）を通して、Googleが提唱する SRE（Site Reliability Engineering） のコア概念は共通言語として頻出します。ここをしっかり押さえておくと、シナリオ問題においてGoogle Cloudが推奨する「正解の行動」がすぐに選べるようになります。

SLI / SLO / SLA の違い：サービスの信頼性を測る指標（SLI）、開発チームと運用チームの共通の目標値（SLO）、顧客とのビジネス上の契約（SLA）の役割の違い。
エラーバジェット（Error Budget）： 100%の可用性を目指すのではなく「許容できる障害の予算」を定め、予算内であれば新機能のリリースを優先し、予算が尽きたら信頼性向上（バク修正など）を優先するという運用ルール。
トイル（Toil）の削減：手作業で反復的かつ自己修復されない運用作業（トイル）を、システム化や自動化によって徹底的に減らすこと。
非難なきポストモーテム（Blameless Postmortem）：障害発生時に特定の個人を責めるのではなく、システムやプロセスの欠陥を分析し、自社システムにおける再発防止の仕組みづくりにフォーカスする文化。

AWSとGoogle Cloudの概念の違い（試験で注意すべきポイント）

AWSの知識があれば解ける問題が多いとはいえ、アーキテクチャの基本概念においていくつか決定的な違いがあり、試験でもここが問われます。代表的なものをいくつか挙げます。

VPCのスコープ　： AWSのVPCは特定の「リージョン」内に作成されますが、Google CloudのVPCは「グローバル」リソースです。VPCの配下に作成するサブネットが各リージョンに紐づくため、複数リージョンにまたがるネットワーク構築の考え方が大きく異なります。
リソースの管理単位（アカウントとプロジェクト）　： AWSでは環境や権限の分離に「AWSアカウント」を境界として使用しますが、Google Cloudでは「プロジェクト」という単位が基本となり、これらを「フォルダ」や「組織」で階層化して管理します。
ロードバランサの配置　： AWSの主要なロードバランサ（ALBなど）はリージョンリソースですが、Google Cloudのグローバルロードバランサ（Cloud Load Balancing）は、単一のAnycast IPアドレスを使用して世界中のユーザーからのトラフィックを最も近いリージョンに振り分けることができます。

各レベル・特徴的な試験の所感

Google Cloud認定には、AWSのような「上位資格取得による下位資格の自動更新」の仕組みがありません。そのため、有効期限（2年または3年）が切れる前に各資格を個別に更新する必要があります。
ただし、有効期限が近づいた資格保持者向けには通常の新規受験とは異なる 「更新用の試験（Recertification Exam）」 が提供されているため、更新時期には公式の案内に従ってそちらを受験する形になりそうです。

Foundationレベル

50～60問。90分。$99（税別）。3年間有効。

Cloud Digital Leader (CDL) と Generative AI Leader (GAIL) は、Google Cloudのどのサービスが使えるかという基本的な内容や、AIの一般論などがメインでした。試験時間は90分ですが、45分くらいで解き終わるボリューム感です。

Associateレベル

50～60問。120分。$125（税別）。3年間有効。

Associate Cloud Engineer (ACE) と Associate Data Practitioner (ADP) は、AWSの知識を焼き直せばすぐに解ける内容でした。こちらは120分ですが、1時間もかからずに完了しました。

少し毛色が違うのが、Associate Google Workspace Administrator (AGWA) です。その名の通りGoogle Cloudに関する内容はなく、Google Workspaceの管理（監査対応、退職者対応、入職者対応、企業合併などで必要な作業等）がメインです。私は独自ドメインのメールアドレスを管理しており、Geminiなどを使うためにGoogle Workspaceに移行していたため、だいたいの概念は理解できておりスムーズに対応できました。

Professionalレベル

50～60問。120分。$200（税別）。2年間有効。

先に書きましたが、問題文はAWS認定のAssociateレベルの長さであり、読み取るのにあまり苦労しませんでした。ただし、たまに長文が出てくることもありますので油断は禁物です。

特徴的な問題

Professional Cloud Architect (PCA) では、画面の半分くらい（調整可能）に事例会社の説明が表示され、その内容を基に回答を選択するケーススタディ問題がありました。ただし、こちらは2026年3月30日に試験内容が更新される予定のため、今後形式が変更になる可能性があります。

また、Professional Cloud Network Engineer (PCNE) に関しては、公式が発表している問題数の上限（50〜60問）である「60問」がみっちり出題されました。他のProfessionalレベルの試験より問題数が多くなるケースがあるため、集中力を維持する体力的なハードルも少し高めでした。私は39問目の回答中に問題数に気づいたため心理的ダメージが大きかったです。最初に問題数を確認することをお勧めします。

唯一の壁、PSOEの難しさと反省点

順調に進んでいた全冠への道ですが、ちょうど折り返し地点であるProfessional Security Operations Engineer (PSOE) で不合格となり、ここで無敗記録がストップしてしまいました。

他の試験（AWS認定やPSOE以外のGoogle Cloud認定）は「どのように設計するか」が主に問われますが、PSOEは「問題が起きた時にどのように対処するか」に重きを置いています。扱われるセキュリティツールも特殊であり、そもそも英語が苦手なのに「英語の問題を解いて理解しようとした」のが間違いでした。

PSOEは日本語未対応です。PearsonVUEに移行するタイミングでついでに日本語化されることを願っていましたが、今のところその気配はありません。英語のみのProfessional Cloud Database Engineer (PCDBE) は内容が単調だったため何とか読み取れましたが、PSOEの複雑なシチュエーションは苦戦しました。

勉強方法の転換と「Google Cloud Skills Boost」の活用

これまで私は、サードパーティの教材（Udemyの演習問題など）を活用して対策を進めていました。しかし、演習に使用していたUdemyの教材の一部が削除されてしまったこともあり、今後は方針を転換します。

これからは、公式の学習プラットフォームである「Google Cloud Skills Boost」をしっかりと使用していく予定です。

Google Cloud Skills Boostとは？

Google Cloudが公式に提供しているオンデマンドの学習プラットフォームです。主に以下のような特徴があります。

実践的なハンズオンラボ：用意された一時的なGoogle Cloud環境を使って、実際のコンソール画面やCLIから手を動かしながら学ぶことができます。
認定試験向けの学習パス：各資格試験の出題範囲に合わせたコースやクエストが体系的にまとめられています。
日本語での概念理解：各種サービスの概念やベストプラクティスを解説する動画やドキュメントが充実しています。

PSOEのような実践的なトラブルシューティングが問われる試験では、単なる暗記ではなく実際の挙動を知っておく必要があります。そのため、Skills Boostのハンズオン等を活用して 「まずは日本語で概念と対処法を理解する → その後英語で読めるようにする」 という順番で対策を進めるべきだと痛感しました。

受験順	分野	認定名称	難易度	備考・おすすめの理由
1	インフラ系	Cloud Digital Leader	★☆☆☆☆	どこでも可。 ACEの前なら軽く知識が入る。上位の資格取得後ならほぼ勉強なしで合格できる。
2	インフラ系	Associate Cloud Engineer	★★☆☆☆
3	インフラ系	Professional Cloud Architect	★★★☆☆
4	インフラ系	Professional Cloud Developer	★★★☆☆
5	インフラ系	Professional Cloud DevOps Engineer	★★★☆☆
6	インフラ系	Professional Cloud Network Engineer	★★★★☆
7	インフラ系	Professional Cloud Security Engineer	★★★☆☆
8	インフラ系	Professional Security Operations Engineer	★★★★★	英語のみ。
9	データ系	Associate Data Practitioner	★★☆☆☆
10	データ系	Professional Data Engineer	★★★★☆
11	データ系	Professional Cloud Database Engineer	★★★☆☆	英語のみ。どこでも可。データを扱うという点でPDEの付近がおすすめ。
12	機械学習系	Generative AI Leader	★☆☆☆☆	どこでも可。 PMLEの前なら軽く知識が入る。 PMLEの後ならほぼ勉強なしで合格できる。
13	機械学習系	Professional Machine Learning Engineer	★★★★★
14	管理系	Associate Google Workspace Administrator	★★☆☆☆	どこでも可。

おわりに

約2か月での「無敗での全冠制覇」という目標は、唯一不合格となったPSOEによって阻まれてしまいましたが、AWSの知識ベースがあればGoogle Cloudのキャッチアップも非常にスムーズに行えることが実証できました。

当初は3月中のリベンジを考えていましたが、諸事情と教材の見直しにより4月に先延ばしにしました。4月にはSkills Boostを活用した新たな勉強方法でPSOEにリベンジし、次こそは「Google Cloud全冠達成」の記事を書けるように頑張ります！

テキストエディタ自作入門

2026-03-26T00:00:00.000+00:00

テキストエディタ難民

皆さん、テキストエディタは何を使っているでしょうか。

最近だと、VS Code ですかね。猫も杓子もといった感じですし。
でもわたし、VS Code は好きになれないんですよね。ゴチャゴチャしていて。

なので Sublime text をメインに使っていましたが、日本語の扱いが微妙な所があったり、巨大なファイルを開くのが遅かったりと不満もあり、状況に応じて色々なテキストエディタを切り替えて使う難民生活を送っていました。

コーディングには IDE を使えばいいので、日常のテキスト編集をストレスなく行える、ただそれだけのシンプルなエディタがほしかったのです。
具体的には以下のような感じです。

Markdown でメモ取り
- コードフェンスでシンタックスハイライトはほしい
- 表を Markdown テーブルとしてペーストしたい(特にペーストできないことで有名なパワポの表も貼り付けたい)
巨大なログ・ファイル確認
- 素早く開いてエラー箇所をフィルタリングしたい
- Grep して調査したい
SQL や JSON の加工
- マルチカーソルで編集したい
- インデント整形したい
巨大 CSV ファイル編集
- カラム毎に揃ったインデントで操作したい
マルチプラットフォーム
- 異なる環境でもキーバインドは同じにしたい
- 設定やプラグインをこねくりまわすことなくアウトオブボックスで使いたい
全角スペースやタブ表示
- キャレットのある行だけ表示したい
セッションの保存
- 未保存で閉じても前回内容を復元したい

難民からの脱却

難民生活にも疲れてきた折、自分でサクッと作ったほうが早いのではないか？
そう思い立ち、テキストエディタを自作して、現在は難民生活を抜け出すことができました。

しかし、全然「サクッと」とはいかず、思った以上に大変でした。

見返してみると、初回コミットは Sep 12, 2022 となっています。

単純なテキスト編集だけであれば割とすぐに動くのですが、普段使いできるレベルになるまでには1年以上かかった気がします。その上、未だに変更加えてます。

どうしても、夜に数十分だけ実装するという細切れの進め方になってしまうので、翌日には何をどこまで進めたかも忘れているという感じで、モチベーション維持を含め、ある程度まとまった時間で集中して作業しないと進まないなぁというのが印象です。

学生のように時間のある時期ならまだしも、この年になってやるものではないなと思いますが、ほしい機能があればすぐに追加できるので、思い通りにカスタマイズ可能なエディタが手に入ったと思うことにしています。

ということで本稿では、テキストエディタの自作をはじめるにあたって、知っておきたかった事柄について記しておこうと思います。

テキストバッファ

テキストエディタを自作するにあたり、最初に考えなければならないのが、文字シーケンスをどのようなデータ構造で扱うかになります。

世の中のテキストエディタは大抵、Gap Buffer、Linked List、Rope、Piece Table のいずれかのデータ構造を元にして、独自の工夫を施しているので、これらを見ていきましょう。

Array

最初は、最も単純な例から始めます。文字シーケンスを配列として扱う方法です。

以下のように文字シーケンスを単にバイト配列として扱うことを考えます。

byte[] bytes = Files.readAllBytes(path);

この時、This is apple. という文字シーケンスは以下のような連続したメモリレイアウトとして確保されます。

an という文字列を挿入するには、元のサイズより3大きい配列を再確保し、文字を新しい配列にコピーして設定する必要があります。

当たり前の話ですが、編集の度に新しいメモリ領域を確保しなおす必要があるため、非常に効率が悪いです。

そこで、メモリ領域を余分に確保しておき、バッファとして利用することを考えます。

Buffer

テキスト編集の度にメモリ領域を再確保するのは明らかに非効率なため、メモリ領域中に未使用のバッファ領域を用意します。

概念的には、以下のような Buffer を考えることになります。

class Buffer {
    byte[] bytes;
    int length;
}

5要素分の未使用領域(網掛け部分)をバッファとして確保した場合は以下のようになります。

文字列の挿入時には、新しい配列を作成することなく、値の設定と移動で編集操作が完結します(バッファ領域が不足した場合には、新たなメモリ領域を確保してコピーする必要があります)。

文字列の編集をバッファ領域で吸収することで、余計なメモリの確保が削減できました。

しかし、編集位置から末尾まで値を移動させる必要があり、もう少し工夫の余地がありそうです。

Gap Buffer

多くのテキスト編集操作は、カーソル位置に対して行われるという事実を利用したものが Gap Buffer です。

先程の例では、メモリの末尾にバッファを用意しましたが、 Gap Buffer では、カーソル位置(キャレット位置)にバッファを設けます。

概念的には、以下のような GapBuffer として考えます。

class GapBuffer {
    byte[] bytes;
    int gapIndex;
    int gapLength;
}

現在のカーソル位置がオレンジの矢印にあり、Gap として5要素分の未使用領域を割り当てた場合は以下のようになります。

カーソルを移動する際、その移動に合わせてバッファ位置を移動させていきます。

これにより、テキストの編集操作を常にバッファ位置で行うことができます。先の例で見た、編集点以降の値のシフトが不要になりました。

バッファの開始位置と長さがわかっているため、インデックスを指定したランダムアクセスも簡単に実現できます。
Gap Buffer は、Emacs でも使われている効率の良いテキストバッファの実現手法になります。

さて、ここまでは文字シーケンスを1つの塊として扱う例を見てきましたが、これらを複数の小さな塊として分割統治することも考えられそうです。

Linked List

文字シーケンスを1つの連続した領域として管理するのではなく、小さな塊として分割統治できれば、編集操作を局在化して扱うことができます。

そこで真っ先に思いつくのは、文字シーケンスを特定サイズのチャンクに分割したノードとして扱い、連結リストとして管理する方法です。

概念的には、以下のようなクラスを考えることになるでしょう。

class LindedList {
    Node head;
    Node tail;
}
class Node {  
    byte[] chunk;  
    Node next;  
    Node prev;
}

例えば、先の例を、単語単位のチャンクとして扱った場合は以下のような構造になります。

テキストの編集処理は、新しいノードを作成してリンクの張り替えを行うだけで済むため効率も良さそうです。

ここでは説明のため単語単位のチャンクとして扱いましたが、細かくし過ぎるとリンクポインタのメモリ使用量が多くなるため、通常は1行をチャンクとして扱う実装が現実的です(改行の挿入でノードの分割、行の削除でノードの結合)。

文字シーケンスを連結リストとして扱うのは、実装が簡単ですが、要素へのランダムアクセスが遅いという欠点があります。

インデックスアクセスを行う場合は、先頭からリストを辿る必要があり、大きなテキストファイルでは特に非効率です。通常は、キャレット位置をカーソルとして、カーソルベースで要素にアクセスするなどの工夫が必要です。

では、文字シーケンスをチャンクに分割した上で、インデックスによるランダムアクセスを効率的に行うことはできないでしょうか。

Rope

文字シーケンスをチャンクに分割し、インデックスアクセスを二分木で追尾できるようにしたものが Rope です。紐(String)を強化した縄(Rope)というわけです。

概念的には、以下のようなクラスを考えます。

class Rope {
    Node root;
}

interface Node {
    int weight();
    int totalLength();
}

record Branch(Node left, Node right, int weight) implements Node {
	Branch(Node left, Node right) {
		this(left, right, left.totalLength());
	}
	public int totalLength() {
		return left.totalLength() + right.totalLength();
	}
}

record Leaf(String text) implements Node {
	public int weight() { return text.length(); }
	public int totalLength() { return weight(); }
}

ここで、weight は、左側ノードの文字列長の合計を表します。
Leaf ノードには文字シーケンスのチャンクを保持し、Branch ノードで weight を管理します。

単語単位のチャンクとして扱った場合は以下のような二分木として管理します。

weight は、そのノードが分割する文字シーケンスの先頭からのインデックス位置となるため、例えばインデックス10の位置は、以下のように木を辿ることで到達できます。

ルートノードは、左側のthis is と右側のapple. に分割した中央部分のインデックスを表すため、10 のインデックス位置は右側木の 2 の位置に存在し、2 の位置は 5 より小さいため、その左側のノードに存在するといった具合です。
連結リストで問題だった、ランダムアクセスの効率が改善されていることがわかると思います。

前述までと同様に an を挿入する場合は以下のように木を更新することになります。

この更新による weight の更新範囲は、対象ノードを上に辿ったノードに対してのみに限定できるという点に注目してください。apple と . を含む右側のノードにはなんの影響も及ぼしません。

元の木構造はそのままに、テキストの更新後の木構造を更新箇所を上に辿ったノードに限定してリンクし直すことで、変更後の文字シーケンスを表現できるのです。つまり、以下のように、文字シーケンスの変更をイミュータブルに扱うことができるということです。

テキストエディタでのUndo操作は、1つ前のルートノードに戻すだけで実現できる点にも注目してください。

このように Rope は文字シーケンスを表現する強力なデータ構造ですが、木構造を維持するためのオーバーヘッドが必要であり、木のバランシング操作も必要です。
加えて、テキストファイルを開いた際に木を構築する必要があるため、巨大なファイルを開くのには時間を要します。

巨大なファイルを効率よく編集できるデータ構造は考えられないでしょうか。それが次に紹介する Piece Table です。

Piece Table

Piece Table は、テキストの変更操作を追記管理するデータ構造です。

Piece Table では、元の文字シーケンスを read only なバッファで管理し、そこに加えられた変更を append only なバッファに配備し、それらのバッファのインデックス位置をテーブルで管理します。

This is apple. というファイルを開いた直後は以下のようになります。

インデックス8の位置に an を挿入する場合は、以下のようにテーブルのインデックスを更新することで変更を扱います。

概念的には、以下のようなクラスを考えることになるでしょう。

record Piece(Buffer target, int index, int length) {
    int end() { return index + length;  }
}

class PieceTable {
    List<Piece> pieces;
    Buffer appendBuffer;
    PieceTable(Buffer readBuffer) {
        this.pieces = new ArrayList<>();
        this.pieces.add(new Piece(readBuffer, 0, readBuffer.length()));
        this.appendBuffer = AppendBuffer.of();
    }
}

元のファイルが巨大でも、 read only なバッファは直接ファイルやメモリマップドファイルとして扱うことで、メモリ確保がほぼ不要になり、編集内容は変更分の Piece の管理だけで済みます。

ただし、変更を繰り返すと Piece の数が増加したり、append only なバッファが断片化するデメリットがあります。

テキストバッファのデータ構造まとめ

これまで見てきたデータ構造をまとめると以下の様になります。

データ構造	特徴
Gap Buffer	実装が非常にシンプルカーソル位置での入力が極めて高速(`O(1)`) カーソル位置の大きな移動・マルチカーソル操作で遅延が生じる可能性があるバッファ領域の枯渇でメモリの再割り当てが必要 Emacs で利用されている
連結リスト	位置特定後の挿入や削除が一定時間で可能(`O(1)`) ランダムアクセスが`O(Ｎ)`となるため、カーソルを利用するなどの工夫が必要実装が簡単なため、初期のエディタ実装で採用されることが多い
Rope	挿入やランダムアクセスが `O(log N)` 二分木の構築やバランシング処理によるオーバヘッドが発生編集操作をイミュータブルにすることができる Zed Editor では Rope を基にしたデータ構造が利用されている
Piece Table	メモリ効率が良い挿入や削除は追記型となるため高速(`O(1)`) 編集によりPieceの数が増加するとパフォーマンスが劣化する VS Code では Piece Table を基にしたデータ構造が利用されている(インデックスアクセスにはRopeのように二分木を使用)

どれも一長一短があり、どんな状況においてもベストという解はありません。
私の場合は、巨大ファイルを扱いたいため、Piece Table を採用することにしました。

それぞれの利用用途に応じてデータ構造を選んでください。

データ構造だけでは語れない

データ構造が決まってテキストエディタを作り始めても、途中で迷うポイントが色々と発生します。

いくつか代表的なものに絞って以下に見てみましょう。

スクロール位置の特定

テキストエディタには、通常、縦スクロールバーと横スクロールバーが表示されます。

縦スクロールバーを表示するには、ファイル全体の行数と、現在画面に表示されている行数を特定する必要があります。

横スクロールバーを表示するには、ファイル中の最長の行と現在の画面幅を特定する必要があります。

厄介なのは横スクロールバーの制御で、最長の行は、編集操作によって最長の行ではなくなる可能性があるので、編集の都度最長の行を探し出す必要があります。

私の場合は、横スクロールバーを完全にトラックすることは諦め、現在画面に表示している行に限定して最長行を見つける実装としました。

折り返し表示

テキストエディタでは、1行をウインドウ幅で論理的に折り返して表示できるものがほとんどです。

しかし、この折り返し判定は厄介で、画面表示上のグリフに応じた文字の幅を計算する必要があります。

通常、文字の幅は文字毎に異なり、さらに面倒なのが、結合文字や合字(Ligature)という概念です。
これらは、複数の文字を繋げて一文字として表示するため、文字幅の計算が都度必要です。

厳密に対応しようとすると、全ての行に対して画面表示上の幅を計算し、適切な折り返し位置を見つける必要があり、非常に高価な処理になります。

折り返し計算は画面に表示されている部分だけ行う、という割り切りもできますが、そうすると先に述べたスクロールバーの長さと辻褄が合わなくなってしまいます。

ですので、折り返し表示は一定サイズ以下のファイルに制限したり、文字幅の計算はある程度割り切った近似値として扱うなどして、パフォーマンスとの折衷案を設けるのが現実的です。

文字シーケンスへのランダムアクセス

データ構造のまとめでは、ランダムアクセスが O(1) で効率が良いなどと書きましたが、現実的には難しい面があります。

全てASCII 文字で、1文字は1バイトという理想的な世界であれば話は簡単ですが、現実はそう上手くは出来ていません。

例えば UTF-8 は、1文字(コードポイント)で 1～4byte の可変エンコーディングとなるため、N文字目にアクセスしようとしてもインデックスアクセスはできず、1つずつバイト長を見ていく必要があります。

テキストファイルを全てメモリに読み込み、メモリ上でアクセスしたとしても、多くの言語ランタイムは、文字列を内部的に UTF-16 でエンコードされたバイト列として扱うため、結局可変エンコードを加味する必要があります。
固定長の UTF-32 としてテキストを保持すれば、ランダムアクセスは容易になりますが、メモリ使用量が増大します。

例えば、Piece Table で、UTF-8 のファイルを直接 read-only buffer として利用する場合を考えてみましょう。
画面上をクリックし、その位置が画面表示上のN文字目(Unicodeコードポイント)だった場合、言語ランタイム上の UTF-16(1〜2バイト) におけるインデックス位置に変換し、ファイル上のUTF-8(1〜4バイト)におけるインデックス位置にさらに変換し、そしてようやくファイルの当該位置にアクセスできるといった具合で、いかにも非効率になります。

先に述べたスクロールバーや折り返し表示のことも考え、行数や文字数といったメタ情報とテキストバッファとのマッピング、グリフ幅などの表示上の情報も合わせて文字シーケンスを扱わなければならず、これらをパフォーマンスとメモリ効率のバランスを取りながら実装を工夫する必要があります。

このあたりがテキストエディタ実装の奥深さになります。

ライブラリ開発にyalcを活用する

2026-03-25T00:00:00.000+00:00

はじめに

共通機能やAPIスキーマなどをライブラリ化して利用する場合、モジュール化したものを公開して各アプリケーションに組み込むと思います。
テストコードで動作確認すべきですが、実際に組み込むと軽微な修正が発生してしまうことがあります。
ファイルを相対参照させるとdist配下の構造が変わってエントリーポイントになるファイルの位置が変わってしまうなどの問題にも困っていました。
そんな悩みを解決してくれたyalcの活用方法を説明します。

yalcとは

yalcは、ローカルで開発中のnpmパッケージをローカルに公開し、GitHub Packagesなどに公開されているパッケージと同じようにアプリケーションに組み込んで開発できるようにするツールです。

同じような役割を持つ仕組みを持つ`npm link` / `npm pack` との違い

観点	yalc	npm link	npm pack
依存参照の実態	`.yalc` と `node_modules` に展開（通常の利用形態に近い）	シンボリックリンク	tarballを手動で作成/配置
変更反映のしやすさ	`yalc push`で利用先に伝搬	リンク先依存で環境差が出やすい	毎回 pack/install が必要
運用向き	複数アプリで同時検証しやすい	小規模・一時検証向き	配布物の確認向き
事故防止	`yalc check` で混入検知可能	標準で混入検知なし	手順の属人化に注意

利用手順

yalcを活用した開発の流れを説明します。

下記の構成で説明します。

ライブラリ
- ディレクトリ: packages/math-utils
- パッケージ名: @sample-yalc/math-utils
- バージョン: 1.0.0
ライブラリを利用するプロジェクト
- ディレクトリ: demo-app

よく使うコマンド一覧

コマンド	説明
`yalc publish`	パッケージをyalcストアに公開
`yalc push`	パッケージを再公開し、利用先に変更を伝搬
`yalc add <package>`	パッケージを追加
`yalc update`	追加済みパッケージを更新
`yalc remove <package>`	パッケージを削除
`yalc remove --all`	すべてのyalcパッケージを削除
`yalc installations show <package>`	パッケージの使用箇所を表示
`yalc installations clean <package>`	パッケージの使用箇所をクリーン

最短で試す（3分）

ライブラリ側で公開

cd packages/math-utils
yalc publish

利用側で追加

cd demo-app
yalc add @sample-yalc/math-utils

ライブラリ変更後に反映

cd packages/math-utils
yalc push

基本はこれだけです。
以降に図解しながら詳細な流れを説明しているので、併せてご確認ください。

事前作業

まずはyalcをインストールします。

インストール
```
npm install -g yalc
```

ライブラリのローカルへの公開から利用するまでの流れ

ローカルで開発中のライブラリをローカルに公開し、それを利用するまでの流れは以下の通りです。

パッケージをローカルに公開する（ライブラリ側）

publishすると、パッケージがローカルのyalcストアに保存されます。
- yalcストアにパッケージをコピー
- yalc.sig: パッケージの内容から算出した識別情報。ライブラリの変更有無を判定する際に使用します。
- yalcストア上のpackage.json: yalcSigの加筆
```
$ cd packages/math-utils
$ yalc publish
@sample-yalc/math-utils@1.0.0 published in store.
```
Information
yalcストア
yalcを使ってpublishしたパッケージが公開される場所のこと。
- Windows: %LOCALAPPDATA%\Yalc(e.g. C:\Users\sample-user\AppData\Local\Yalc)
- mac/Linux: ~/.yalc
dirで実際のディレクトリが確認できます。
```
$ yalc dir
C:\Users\sample-user\AppData\Local\Yalc
```
プロジェクトにパッケージを追加する（利用側）

addすると、パッケージを取り込んで、依存関係が更新されます。
- installations.json: インストール先として加筆
- package.json: 依存関係の追加/変更
```
"dependencies": {
  // パッケージの参照先が.yalc配下に変更されます
  "@sample-yalc/math-utils": "file:.yalc/@sample-yalc/math-utils"
},
```
- .yalc: yalcストアからパッケージがコピーされます
- node_modules/{パッケージスコープ/パッケージ名}: .yalcからパッケージがコピーされます
- yalc.lock: 新規作成されます
```
$ cd demo-app
$ yalc add @sample-yalc/math-utils
Package @sample-yalc/math-utils@1.0.0 added ==> C:\Users\sample-user\demo-app\node_modules\@sample-yalc\math-utils
```

ここまでで、リモートに公開されているパッケージと同じように利用できます。

ライブラリの変更を伝搬する

ライブラリの変更を、利用先に伝搬する手順は以下の通りです。

ライブラリのコードを変更する（ライブラリ側）
変更を伝搬する（ライブラリ側）

pushすると、利用先に変更内容を伝搬します。
- yalcストアにパッケージを再公開
- 更新されたパッケージの利用先に変更を反映（設定不備で失敗することがあります）
```
$ cd packages/math-utils
$ yalc push
```

ライブラリの利用を終了する

yalcパッケージとの依存を除去する手順は以下の通りです。

yalcパッケージを削除する（利用側）

removeすると、利用側にコピーされたライブラリが削除されます。
- package.json: 依存関係を削除
- .yalc: ディレクトリを削除
- node_modules/{パッケージスコープ/パッケージ名}: ディレクトリを削除
- yalc.lock: 依存関係を削除
  - ロック対象のyalcパッケージがすべてなくなったらファイルごと削除します。
- yalcストアのパッケージ: 削除されません
```
$ cd demo-app
$ yalc remove @sample-yalc/math-utils # 特定のパッケージを指定してyalcパッケージを削除する場合    
$ yalc remove --all # すべてのyalcパッケージを削除する場合
```

Appendix. 利用上の注意点など

yalc関連のファイルはgit管理から除外

あくまでも開発時に利用するツールなので、yalcを使う時は.gitignoreに該当ファイルを登録しておきます。

# yalc
.yalc/
yalc.lock

コミット前に`yalc check`で混入防止

.yalc 参照（file:.yalc/... や link:.yalc/...）がpackage.jsonに残ったままコミットすると、CIや他環境で問題になりやすいです。

# package.jsonにyalc依存が残っていないかチェック
yalc check

pre-commitで実行するようにしておくと、誤コミットを防ぎやすくなります。

パッケージが更新されない

yalcパッケージをいったん削除して、再登録してください。

# キャッシュをクリアして再追加
yalc remove @sample-yalc/math-utils
yalc add @sample-yalc/math-utils

（yalcパッケージを削除してもうまくいかない場合）node_modulesを削除して、再登録してください。

# node_modulesを削除して再インストール
rm -rf node_modules
# Remove-Item -Recurse -Force node_modules # PowerShellの場合
npm install
yalc add @sample-yalc/math-utils

（それでもうまくいかない場合）インストール先のパスが誤っている可能性があります。確認して誤っていた場合はパスを修正してください。
```
# 特定のパッケージの情報
yalc installations show @sample-yalc/math-utils
```

まとめ

ライブラリを開発しながら動作検証できるのは非常に助かります。
同じような苦労をされている方がいらっしゃれば、開発に組み込んでみてはいかがでしょうか。

AWS Session ManagerをGit Bashで利用した際の文字化け対処法

2026-03-24T00:00:00.000+00:00

はじめに

普段、業務ではどのような OSを使っているでしょうか。
筆者個人では Macを使っていますが、業務では Windowsを利用しています。

Windows環境では、軽量で扱いやすく、POSIXライクな操作ができる Git Bashを利用しています。
Windows Terminalからも使えるため、普段使い慣れたコマンドをそのまま利用でき、 AWS CLIとの相性が良い点も便利です。

https://developer.mamezou-tech.com/blogs/2023/09/08/windows-terminal-with-git-bash/

このような理由から、AWS Systems Manager Session Manager（以下、SSM）経由で EC2に接続する際にも Git Bash を利用していました。
しかし、Windows 環境の Git Bash では、lsblk や systemctl status などに含まれる一部の罫線・記号が文字化けすることがありました。

本記事では、この事象の再現内容、原因、対処方法を紹介します。

結論としては、session-manager-plugin を最新版へ更新するのが第一選択です。
更新が難しい場合は、chcp.com 65001 でコードページを UTF-8 に変更する方法が有効でした。

なお、 Macから接続した場合は同様の問題は発生しませんでした。

前提

以下の環境で検証しています。

OS: Windows: 11(Pro)
Terminal: Git Bash
AWS CLI: aws-cli/2.32.16 Python/3.13.11 Windows/11 exe/AMD64
session-manager-plugin: 1.2.707.0(検証開始時)→1.2.792.0(解決)

次のような方を対象としています。

Windows + Git Bash で AWS CLI / SSM を利用してEC2への接続している方。
lsblk や systemctl status の罫線・記号などの文字化けする方。

先に結論

対処方法は次の通りです。

優先度	対処方法	補足
1	`session-manager-plugin` を最新版（`1.2.792.0` 以降）へ更新する	根本対応。まずはこちらを推奨
2	`chcp.com 65001` を実行する	プラグインを更新できない場合の暫定対処
3	`.bashrc` に設定する	暫定対処を継続利用する場合の恒久化

推奨対処: session-manager-plugin を最新版へ更新する

検証を進める中で、最新版の session-manager-plugin に更新すると事象が解消することを確認できました。

※このバージョンは、記事の執筆・検証時点の3日前に最新版がリリースされていました。

執筆時点では、最新版の1.2.792.0 にプラグインを更新することで文字化けが再現しなくなりました。

インストール方法は、以下の AWS 公式ドキュメントを参照してください。

WindowsでのSession Managerプラグインのインストール

なぜ`1.2.792.0`で改善したのか

執筆時点での最新版である1.2.792.0 のリリースノートには、 Windows環境でのキーボード入力や文字処理に関する修正が含まれていました。

session-manager-plugin 1.2.792.0 リリースページ

1.2.792.0に関連する以下のPRを見ると、本記事の事象と近い問題が修正対象になっていることが分かります。

PR: Windowsプラットフォームにおける中国語および日本語の文字表示の不具合の修正

PRでは、Windows版のsession-manager-pluginが出力時にwindows.WriteFileAPIを使用しており、UTF-8の一部の言語の文字が正しく処理できていなかったことが説明されています。

その結果、中国語や日本語の入力・出力の一部で文字化けが発生していたと考えられます。

本記事で確認した文字化けも、この修正を含む1.2.792.0で改善した可能性が高いと考えられます。

本記事の後半は、古いバージョン (1.2.707.0) を利用していたときの再現内容と暫定対処をまとめたものです。

まずはプラグインを最新版へ更新し、改善するかを確認してください。

文字化けの事象（古いプラグインの場合）

古いバージョンのプラグイン（例：1.2.707.0）を使用している場合、以下のようなコマンドを実行した際に文字化けが発生しました。

今回は Amazon Linux 2023 と Ubuntu 24.04 の公式AMIで検証しましたが、AMIに依存せず、同様の箇所で文字化けが発生しました。

lsblk
NAME         MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
loop0          7:0    0 27.8M  1 loop /snap/amazon-ssm-agent/12322
loop1          7:1    0   74M  1 loop /snap/core22/2339
loop2          7:2    0 48.1M  1 loop /snap/snapd/25935
nvme0n1      259:0    0    8G  0 disk
笏懌楳nvme0n1p1  259:1    0    7G  0 part /
笏懌楳nvme0n1p14 259:2    0    4M  0 part
笏懌楳nvme0n1p15 259:3    0  106M  0 part /boot/efi
笏披楳nvme0n1p16 259:4    0  913M  0 part /boot

systemctl status sshd
笳・sshd.service - OpenSSH server daemon
     Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; preset: enabled)
     Active: active (running) since Sun 2026-03-20 14:18:54 UTC; 1min 12s ago
       Docs: man:sshd(8)
             man:sshd_config(5)
   Main PID: 1553 (sshd)
      Tasks: 1 (limit: 1067)
     Memory: 2.3M
        CPU: 15ms
     CGroup: /system.slice/sshd.service
             笏披楳1553 "sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups"

ご覧の通り、罫線やステータスアイコンが文字化けしています。

原因

この文字を調べてみたところ、以下の通りでした。

本来	Unicode	文字化け
`├─`	U+251C,U+2500	`笏懌楳`
`└─`	U+2514,U+2500	`笏披楳`
`●`	U+25CF	`笳`(末尾不正)

以上から、今回の文字化けは UTF-8の文字列が CP932（Shift_JIS 系）として誤って解釈されたことで発生していると考えられます。

つまり、 SSM経由で受け取った文字列と Git Bash側のコンソールのページ文字コード設定が一致しておらず、その結果として罫線や記号が正しく表示されなかった、という状況です。

Git Bash側の設定確認と暫定対処

Git Bashの現在の設定を確認する

今回の環境では、chcp.com の結果は CP932でした。

自身の Git Bashの現在の設定を確認したい場合は以下のコマンドで確認できます。

chcp.com
現在のコード ページ: 932

暫定対処: コンソールの文字コードをUTF-8に変更する

Information

まずは session-manager-plugin を最新版へ更新し、改善することを確認してください。
ここで紹介する方法は、プラグインを更新できない場合の暫定対処です。

最新版のダウンロードができない・インストールに制約がある環境の方は以下の通り、現在のページのコードをUTF-8へ変更するコマンドを試してみてください。

chcp.com 65001
Active code page: 65001

Git Bash上では単なるchcpを認識せず、期待通り動作しません。
これは Windows標準の C:\Windows\System32\chcp.comを明示的に呼び出す必要があるためです。

参考情報

結果

コンソールの文字コードを UTF-8へ変更後に再度確認したところ、文字化けが発生していた箇所が正常に出力されることを確認できました。

最新版のsession-manager-pluginに更新・利用した場合は、chcp.com 65001を実行しなくても、文字化けせずに出力されました。

lsblk
NAME         MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
loop0          7:0    0 27.8M  1 loop /snap/amazon-ssm-agent/12322
loop1          7:1    0   74M  1 loop /snap/core22/2339
loop2          7:2    0 48.1M  1 loop /snap/snapd/25935
nvme0n1      259:0    0    8G  0 disk
├─nvme0n1p1  259:1    0    7G  0 part /
├─nvme0n1p14 259:2    0    4M  0 part
├─nvme0n1p15 259:3    0  106M  0 part /boot/efi
└─nvme0n1p16 259:4    0  913M  0 part /boot

systemctl status sshd
● sshd.service - OpenSSH server daemon
     Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; preset: enabled)
     Active: active (running) since Sun 2026-03-20 15:22:04 UTC; 33s ago
       Docs: man:sshd(8)
             man:sshd_config(5)
   Main PID: 1549 (sshd)
      Tasks: 1 (limit: 1067)
     Memory: 2.3M
        CPU: 15ms
     CGroup: /system.slice/sshd.service
             └─1549 "sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups"

設定の恒久化

毎回コードページを変更するのが面倒な場合は、.bashrc に設定しておくことで Git Bash 起動時に自動で UTF-8 に切り替えられます。

echo 'chcp.com 65001 > /dev/null' >> ~/.bashrc

まとめ

今回は、Git Bash で SSM を利用した際に発生する文字化けの原因と対処方法を紹介しました。

ポイントをまとめると、次の通りです。

まずはsession-manager-pluginを最新版へ更新する
古いプラグインを使っている場合、Git Bash側のページ文字コードが原因で文字化けすることがある
更新できない環境では、chcp.com 65001によるUTF-8化が有効
継続利用する場合は .bashrcへの設定で恒久化できる

これまでは文字化けが起きても、表示が崩れた部分を手で読み替えながら対応していました。

最近は EC2 周りの作業が増え、文字化けに遭遇する頻度も高くなったため、本記事で対処方法を調べました。

解決方法にたどり着くまで時間がかかったので、本記事の内容がお役に立てば幸いです。

最後までご覧いただきありがとうございました。

食品盛り付けロボット「美膳®」開発の舞台裏――UIとコアをつなぐgRPCとリアルタイム通信の仕組み

2026-03-23T00:00:00.000+00:00

はじめに

ロボットや製造装置のソフトウェアでは、ユーザーインターフェースと装置制御ロジックの設計が重要になります。特に装置の操作パネルは、装置の状態を分かりやすく表示するとともに、安全に操作を行えるインターフェースである必要があります。

食品盛り付けロボット「美膳®」は、製造現場でのエンドユーザー利用を想定して設計されたロボットシステムです。美膳®の本体には、システムを操作するための専用の操作パネルが用意されています。

本記事では、美膳®のUI設計を例として、次の内容を紹介します。

装置UIのソフトウェアアーキテクチャ
Flutterを利用したGUI実装
gRPCによるコンポーネント間通信
双方向ストリーミングを用いたリアルタイム通信

美膳®のソフトウェアアーキテクチャ

美膳®のソフトウェアは、役割ごとに分離された複数のコンポーネントによって構成されています。それぞれのコンポーネントが明確な責務を持つことで、システム全体の保守性と拡張性を高めています。

主なコンポーネントは次の3つです。

GUIアプリケーション
ユーザー操作の入口となるアプリケーションです。装置の状態表示や操作入力を担当し、直接コアロジックにはアクセスせず、必ずAPIを経由して操作を行います。
コントローラAPI
コントローラアプリケーションの機能や状態を外部に公開するインターフェース層です。GUIなどの外部アプリケーションは、このAPIを通して装置の機能にアクセスします。
コントローラアプリケーション
美膳®の中核となるコンポーネントです。装置の状態制御、登録データ管理、画像処理などを担当します。

システム構成は次の図のようになります。

このように、GUIアプリケーションは直接コントローラアプリケーションにアクセスするのではなく、APIを介して通信する構造になっています。これにより、UIとコアロジックを独立して開発・保守することが可能になります。

コンポーネント間通信

美膳®では、GUIアプリケーションとコントローラアプリケーションの通信に gRPC を採用しています。コントローラAPIはgRPCで実装されており、コントローラアプリケーションはgRPCサーバとして動作します。GUIアプリケーションはgRPCクライアントとして接続し、各種サービスを利用します。

この構成により、UIと制御ロジックを言語や実装に依存せず接続することが可能になります。

Information

コントローラAPIはインターフェイス定義言語 ( Protocol Buffers )により公開インタフェースを定義し、サーバ側 / クライアント側それぞれのプログラミング言語用に変換して利用する。

通信の用途は主に次の3つです。

システム状態通知

GUIアプリケーションはサーバに接続している間、システムの状態更新を継続的に受信します。これは サーバストリーミングRPC によって実装されています。コントローラの状態変化に応じてGUIの表示が更新され、装置の状態とUIが常に同期されます。

サービス要求

ユーザー操作によって発生する単発の処理要求は Unary RPC によって実装されています。GUIアプリケーションから要求が送信され、サーバから処理結果が応答されます。

同期セッション

リアルタイム性が必要な操作では 双方向ストリーミングRPC を使用します。クライアントとサーバが同時にメッセージを送信できるため、リアルタイムな通信セッションを実現できます。

例えば次のような用途で利用されています。

カメラ映像を確認しながらのパラメータ調整
運転開始前の確認操作
ロボットの状態監視

通信の流れは次の図のようになります。

技術概要

Flutterについて

美膳®のGUIアプリケーションは、Googleが提供するUIフレームワーク Flutter を利用して実装されています。FlutterではDart言語を使用してアプリケーションを開発します。

Flutterはクロスプラットフォームのフレームワークであり、単一のコードベースから複数のOS向けのアプリケーションを生成できます。また、豊富なUIコンポーネントが提供されているため、操作パネルのようなGUIの開発を効率的に行うことができます。

さらに、Googleが提供する他の技術との親和性が高いことも特徴の一つです。

gRPCについて

gRPCはGoogleが開発したオープンソースのRPC（Remote Procedure Call）フレームワークです。gRPCでは Protocol Buffers（Protobuf） を利用してAPIを定義し、データのシリアライズを高速に行うことができます。

ProtobufでAPIを定義することで、複数のプログラミング言語から同一のインターフェースを利用することが可能になります。そのため、Flutter（Dart）で実装されたGUIと、C++で実装されたコントローラアプリケーションのような異なる言語のシステムを容易に接続できます。

豆蔵では過去のロボット開発プロジェクトでもgRPCを利用した実績があります。

サンプルアプリケーション

双方向ストリーミングによるリアルタイム通信

gRPCの双方向ストリーミングは、クライアントとサーバが同時にメッセージを送信できる通信方式です。この仕組みを利用することで、リアルタイム性の高いUI操作を実装できます。

ここでは、FlutterとgRPCを用いた簡単なサンプルアプリケーションを通して、双方向ストリーミングによるリアルタイム通信の仕組みを紹介します。

実際の美膳®では、Flutterで実装されたUIとC++で実装されたコアアプリケーションが通信していますが、ここでは理解を容易にするため、Dartでサーバとクライアントを実装したサンプルを作成します。

このサンプルでは、サーバが共有カウンターを管理し、複数のクライアントがカウンターの更新操作を送信できるアプリケーションを作成します。クライアントから送信された操作はサーバで処理され、その結果がすべての接続クライアントへリアルタイムに配信されます。

以降では、このサンプルアプリケーションの実装手順を紹介します。

ディレクトリ構成

今回のサンプルでは複数のプロジェクトを作業ディレクトリExamplesにまとめます。(Examplesディレクトリは任意の場所に作成してください)

これから作成するディレクトリの構成は下図のようになります。

Examples/
|
+-- counter_server/
|     サーバプログラムのプロジェクトディレクトリ
|
+-- counter_client/
|     クライアントプログラムのプロジェクトディレクトリ
|
+-- counter_api/
      gRPCで使用するAPIの定義を格納する

Information

本サンプルは、下記の環境で作成・動作の確認を行った。

OS: Ubuntu 22.04 LTS
Flutter: 3.24.2 / Dart: 3.5.2

gRPCを用いたAPIの定義

最初にProtocol Bufferで、クライアント - サーバ間で使用するAPIを定義します。

ターミナルでExamplesディレクトリに入り、下記を実行してください。

mkdir counter_api
cd counter_api
touch counter_api.proto

counter.protoをエディタで開き、gRPCのメッセージとサービスを定義して保存してください。

syntax = "proto3";

package counter_api;

/// カウンターサービス定義
service CounterService {
  /// 双方向ストリーミング
  /// クライアントは操作を送信
  /// サーバーは最新カウント値をストリームで返す
  rpc SyncCounter(stream CounterRequest) returns (stream CounterResponse);
}

/// クライアントからの操作リクエスト
message CounterRequest {
  string client_id = 1;   // クライアント識別子

  oneof action {
    Increment increment = 2;
    Decrement decrement = 3;
    Reset reset = 4;
  }
}

/// +1 操作
message Increment {
  int32 amount = 1; // 通常は1
}

/// -1 操作
message Decrement {
  int32 amount = 1; // 通常は1
}

/// リセット操作
message Reset {}

/// サーバーから配信される現在状態
message CounterResponse {
  int32 current_value = 1;   // 現在のカウント値
  string updated_by = 2;     // 更新したクライアントID
  int64 timestamp = 3;       // 更新時刻（Unix ms）
}

サーバ側のDartプロジェクトの作成

Examplesディレクトリで下記をターミナルから実行する

dart create counter_server
cd counter_server

続けて、先に定義したcounter_api.protoをコンパイルして自動生成のコードをcounter_serverのソースに加えます。

dart pub global activate protoc_plugin 21.1.2  # <-- protoc_plugin をインストール
export PATH="$PATH":"$HOME/.pub-cache/bin"  # <-- Protocol Buffers コンパイラ (protoc) のPATHを一時的に通す
mkdir -p lib/src/generated
protoc --dart_out=grpc:lib/src/generated -I../counter_api counter_api.proto # <-- counter_api.proto をコンパイルする

counter.protoのコンパイルに成功すると、下記のファイルがExamples/counter_server/lib/src/に生成されます。

Examples/counter_server/lib/src/generated
|
+-- counter_api.pb.dart
|     メッセージ型の本体定義
|
+-- counter_api.pbenum.dart
|     enum定義 (今回は使用しない)
|
+-- counter_api.pbgrpc.dart
|     gRPCサービス用のコード
|
+-- counter_api.pbjson.dart
      JSON用メタデータ (今回は使用しない)

counter_server/pubspec.yamlを編集してプロジェクトを設定します。

name: counter_server
description: "gRPC bidirectional streaming counter server"
version: 1.0.0

environment:
  sdk: ^3.5.2

dependencies:
  grpc: ^3.2.4
  protobuf: ^3.1.0
  protoc_plugin: ^21.1.2
  fixnum: ^1.1.1

dev_dependencies:
  lints: ^4.0.0
  test: ^1.24.0

counter_server/lib/counter_server.dartを編集し、サーバを実装します。

import 'dart:async';
import 'package:grpc/grpc.dart';
import 'package:fixnum/fixnum.dart';

import 'src/generated/counter_api.pb.dart';
import 'src/generated/counter_api.pbgrpc.dart';

class CounterServiceImpl extends CounterServiceBase {
  int _currentValue = 0;

  // 接続中クライアントへ配信するためのコントローラ一覧
  final List<StreamController<CounterResponse>> _clients = [];

  @override
  Stream<CounterResponse> syncCounter(
      ServiceCall call, Stream<CounterRequest> requestStream) {
    final controller = StreamController<CounterResponse>();

    _clients.add(controller);

    print("Client connected");

    // 接続直後に現在値を送信
    controller.add(_createResponse("server"));

    requestStream.listen(
      (request) {
        _handleRequest(request);
      },
      onDone: () {
        print("Client disconnected");
        _clients.remove(controller);
        controller.close();
      },
      onError: (e) {
        print("Stream error: $e");
        _clients.remove(controller);
        controller.close();
      },
    );

    return controller.stream;
  }

  void _handleRequest(CounterRequest request) {
    if (request.hasIncrement()) {
      _currentValue += request.increment.amount;
      _broadcast(request.clientId);
    } else if (request.hasDecrement()) {
      _currentValue -= request.decrement.amount;
      _broadcast(request.clientId);
    } else if (request.hasReset()) {
      _currentValue = 0;
      _broadcast(request.clientId);
    }
  }

  void _broadcast(String updatedBy) {
    final response = _createResponse(updatedBy);

    print("Broadcast: $_currentValue (by $updatedBy)");

    for (final client in _clients) {
      client.add(response);
    }
  }

  CounterResponse _createResponse(String updatedBy) {
    return CounterResponse()
      ..currentValue = _currentValue
      ..updatedBy = updatedBy
      ..timestamp = Int64(DateTime.now().millisecondsSinceEpoch);
  }
}

Future<void> main() async {
  final server = Server.create(
    services: [CounterServiceImpl()],
    interceptors: const <Interceptor>[],
  );

  await server.serve(port: 50051);
  print('Counter Server listening on port ${server.port}');
}

クライアント側のFlutterプロジェクトの作成

Examplesディレクトリで下記をターミナルから実行します。

flutter create counter_client
cd counter_client

続いてサーバのときと同じように、counter_api.protoをコンパイルして自動生成のコードをcounter_serverのソースに加えます。

dart pub global activate protoc_plugin 21.1.2  # <-- protoc_plugin をインストール
export PATH="$PATH":"$HOME/.pub-cache/bin"  # <-- Protocol Buffers コンパイラ (protoc) のPATHを一時的に通す
mkdir -p lib/src/generated
protoc --dart_out=grpc:lib/src/generated -I../counter_api counter_api.proto # <-- counter_api.proto をコンパイルする

counter_client/pubspec.yamlを編集してプロジェクトを設定します。

name: counter_client
description: "gRPC bidirectional streaming counter client"
publish_to: 'none'

version: 1.0.0+1

environment:
  sdk: ^3.5.2

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8
  grpc: ^3.2.4
  protobuf: ^3.1.0
  uuid: ^4.4.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^4.0.0

flutter:
  uses-material-design: true

counter_client/lib/main.dartを編集し、クライアントを実装します。

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:grpc/grpc.dart';
import 'package:uuid/uuid.dart';

import 'src/generated/counter_api.pb.dart';
import 'src/generated/counter_api.pbgrpc.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: CounterPage(),
    );
  }
}

class CounterPage extends StatefulWidget {
  const CounterPage({super.key});

  @override
  State<CounterPage> createState() => _CounterPageState();
}

class _CounterPageState extends State<CounterPage> {
  late ClientChannel _channel;
  late CounterServiceClient _stub;
  late StreamController<CounterRequest> _requestController;
  Stream<CounterResponse>? _responseStream;

  final String _clientId = const Uuid().v4();
  int _currentValue = 0;
  String _lastUpdatedBy = "-";

  @override
  void initState() {
    super.initState();
    _initGrpc();
  }

  void _initGrpc() {
    _channel = ClientChannel(
      'localhost', // サーバーアドレス
      port: 50051,
      options: const ChannelOptions(
        credentials: ChannelCredentials.insecure(),
      ),
    );

    _stub = CounterServiceClient(_channel);

    _requestController = StreamController<CounterRequest>();

    _responseStream = _stub.syncCounter(_requestController.stream);

    _responseStream!.listen((response) {
      setState(() {
        _currentValue = response.currentValue;
        _lastUpdatedBy = response.updatedBy;
      });
    });
  }

  void _sendIncrement() {
    final request = CounterRequest(
      clientId: _clientId,
      increment: Increment()..amount = 1,
    );
    _requestController.add(request);
  }

  void _sendDecrement() {
    final request = CounterRequest(
      clientId: _clientId,
      decrement: Decrement()..amount = 1,
    );
    _requestController.add(request);
  }

  void _sendReset() {
    final request = CounterRequest(
      clientId: _clientId,
      reset: Reset(),
    );
    _requestController.add(request);
  }

  @override
  void dispose() {
    _requestController.close();
    _channel.shutdown();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final isMe = _lastUpdatedBy == _clientId;

    return Scaffold(
      appBar: AppBar(
        title: const Text("gRPC 双方向ストリーミング カウンター"),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              '現在値',
              style: Theme.of(context).textTheme.titleLarge,
            ),
            const SizedBox(height: 16),
            Text(
              '$_currentValue',
              style: const TextStyle(
                fontSize: 60,
                fontWeight: FontWeight.bold,
              ),
            ),
            const SizedBox(height: 20),
            Text(
              '最終更新: ${isMe ? "自分" : _lastUpdatedBy}',
            ),
            const SizedBox(height: 40),
            Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                ElevatedButton(
                  onPressed: _sendIncrement,
                  child: const Text("+1"),
                ),
                const SizedBox(width: 20),
                ElevatedButton(
                  onPressed: _sendDecrement,
                  child: const Text("-1"),
                ),
                const SizedBox(width: 20),
                ElevatedButton(
                  onPressed: _sendReset,
                  child: const Text("Reset"),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

サンプルプログラムの実行

ここでは作成したサンプルプログラムを実行し、gRPCの双方向ストリーミングによるクライアント間の状態同期を確認します。

このサンプルでは、1つのサーバに対して複数のクライアントが接続し、カウンタの状態をリアルタイムに共有します。

サーバは localhost:50051 で待ち受けるように実装されています。
そのため、サーバとクライアントは同じマシン上で実行することを前提としています。

下記の順にサーバとクライアントを起動します。

1. サーバ側

ターミナルで counter_server のプロジェクトディレクトリに移動し、Dartプログラムを実行します。

cd counter_server
dart run

サーバが起動すると、次のようなログが表示されます。

Counter Server listening on port 50051

この状態で、クライアントからの接続を受け付けます。

2. クライアント側

別のターミナルを開き、counter_client のプロジェクトディレクトリでFlutterアプリケーションを起動します。

cd counter_client
flutter run

クライアントアプリケーションが起動すると、gRPCを通して自動的にサーバへ接続されます。

実行結果

クライアントの [+1] / [-1] ボタンをタップすると、操作内容が双方向ストリーミングRPCを通してサーバへ送信されます。

サーバはカウンタの状態を更新し、その結果を接続中のすべてのクライアントへストリームで配信します。
クライアントは受信した状態をもとに画面の表示を更新します。

上図はカウンタを「2」までカウントアップした状態のクライアントです（以下では「クライアントA」と呼びます）。

画面下部の [最終更新] には、最後にカウンタを更新したクライアントが表示されます。
この場合はクライアントA自身が更新しているため、「自分」と表示されています。

次に、別のターミナルを開いてもう1つクライアントを起動します。
これを「クライアントB」とします。

クライアントBもサーバから状態ストリームを購読しているため、現在のカウンタ値「2」が表示されます。
しかし [最終更新] には、更新を行ったクライアントAの識別子が表示されます。

この状態でクライアントBからカウンタを更新すると、次のような挙動になります。

クライアントBが更新操作を送信
サーバがカウンタ値を更新
サーバが全クライアントへ状態更新を配信
クライアントAとクライアントBの画面が同時に更新

この結果、

クライアントBでは [最終更新] = 自分
クライアントAでは [最終更新] = クライアントBのID

と表示が更新されます。

このように、複数のクライアントが同じ状態をリアルタイムに共有していることを確認できます。

考察

今回のサンプルでは、双方向ストリーミングRPCを利用してクライアントとサーバ間の通信を実装しました。

ただし、このカウンタの例だけを見ると、必ずしも双方向ストリーミングを使用する必要はありません。例えば次のような構成でも同様の機能を実現できます。

カウンタ更新
→ Unary RPC
状態更新通知
→ Server Streaming RPC

この方法でもクライアント間の状態同期は可能です。

しかし、実際の装置ソフトウェアでは次のような要件が発生することが多くあります。

操作入力をリアルタイムに送信する
カメラ映像などのデータを連続的に受信する
操作と状態更新を同一セッションで同期する

このようなケースでは、クライアントとサーバが同時にデータを送受信できる 双方向ストリーミングRPC が有効です。

美膳のシステムでは、この仕組みを利用して次のような操作を実装しています。

カメラ映像を確認しながらのパラメータ調整
ロボット操作の確認セッション
UIと装置状態のリアルタイム同期

双方向ストリーミングを利用することで、リアルタイム性を保ちながら複雑な操作セッションを実装することができます。

まとめ

本記事では、食品盛り付けロボット「美膳®」におけるUIアーキテクチャと、その実装技術の概要を紹介しました。

美膳®では、ユーザーインターフェースとロボット制御ロジックを明確に分離した構成を採用しています。GUIアプリケーションはFlutterによって実装され、コントローラアプリケーションとはgRPCを用いて通信します。

このような構成にすることで、UIと制御ロジックを独立して開発・保守することが可能になります。その結果、装置ソフトウェアの整備性や拡張性を高めることができます。

また、gRPCのストリーミング機能を活用することで、装置の状態通知やリアルタイムな操作セッションなど、用途に応じた通信モデルを柔軟に実装できます。

美膳®のソフトウェア設計のポイントは次の通りです。

UIと制御ロジックの分離
GUIアプリケーションとコントローラアプリケーションを独立したコンポーネントとして構成することで、責務を明確にし、開発と保守を容易にしています。
APIによるコンポーネント接続
コントローラアプリケーションの機能をAPIとして公開することで、UIからのアクセスを安全に制御し、システムの境界を明確にしています。
多言語環境を前提とした通信基盤
Flutter（Dart）とC++という異なる言語で実装されたアプリケーションを接続するために、gRPCとProtocol
Buffersを用いた通信基盤を採用しています。
ストリーミング通信によるリアルタイム同期
システム状態の配信や操作セッションなど、装置のUIに必要なリアルタイム通信を効率的に実装しています。

ロボットや装置のソフトウェアでは、UI、通信、制御ロジックなど複数の要素が密接に関係します。本記事で紹介した構成はその一例ですが、装置ソフトウェアの設計を検討する際の参考になれば幸いです。

GitHub MCP Registryに公開されているMCPサーバーをVS Codeで動かす手順

2026-03-17T00:00:00.000+00:00

はじめに

MCPサーバーは、エージェントやツールが呼び出せる実行可能な「サービス」を定義する仕組みです。
このページでは、VS CodeのMCP拡張からMCPサーバー（今回はMarkitdownを使用）を起動して、AIエージェント／MCPクライアントで呼び出す手順を紹介します。

用語補足（この記事での使い方）
- MCP（Model Context Protocol）サーバー
  エージェントに実行可能なツールを提供する仕組み。
  エージェントはMCPサーバーの「ツール」を呼び出すことで外部処理を実行できる。
- Markitdown (microsoft/markitdown)
  PDFやpptxをMarkdownに変換するMCPサーバー。
- uvx
  Markitdownのランチャー。
  今回検証に使うMCPサーバーがcommandとして期待するツール。

環境

Windows 11
VS Code
Markitdown@1.8.1: 動作確認に使用したMCPサーバー
uvx@0.10.9
Copilot: MCPサーバーの呼び出しに使用したAIエージェント
MCP Inspector@0.21.0: MCPサーバーの呼び出しに使用したMCPクライアント

手順

今回はMarkitdownを使用して、動作を確認します。

MCPサーバーをVS Codeにインストール
- GitHub MCP Registryからインストールする場合
  1. GitHub MCP Registryをブラウザで開いて、インストールしたいMCPのinstallボタンを押下。
- VS CodeのExtensionsからインストールする場合
  1. VS Code上でMCPサーバーを検索できるように設定を有効化
  Information
  ■設定を無効化したい場合
  設定を開いてチェックを外す。
  1. フィルタリング（@mcp）された状態でMCPが表示されるので、インストールしたいMCPのinstallボタンを押下。
- MCPサーバーのインストール後、.vscode/mcp.jsonにMCPサーバーの設定が追加される。
  .vscode/mcp.json
```
{
    "servers": {
        "microsoft/markitdown": { //MCPサーバー名
            "type": "stdio", //MCPサーバーの種類
            "command": "uvx", //MCPサーバーが期待するコマンド
            "args": [ //コマンドに渡す引数
                "markitdown-mcp@0.0.1a4"
            ],
            "gallery": "https://api.mcp.github.com",
            "version": "1.0.0"
        }
    },
    "inputs": []
}
```

MCPサーバーを起動
インストール後に作成された.vscode/mcp.jsonの設定を読み込んで、ローカルプロセスを起動します。

VS CodeのExtensionsから起動
.vscode/mcp.jsonから起動

起動例

2026-03-10 12:35:30.848 [info] Starting server microsoft/markitdown
2026-03-10 12:35:30.848 [info] Connection state: Starting
2026-03-10 12:35:30.849 [info] Starting server from LocalProcess extension host
2026-03-10 12:35:30.920 [info] Connection state: Starting
2026-03-10 12:35:30.920 [info] Connection state: Running
2026-03-10 12:35:35.925 [info] Waiting for server to respond to `initialize` request...
2026-03-10 12:35:40.922 [info] Waiting for server to respond to `initialize` request...
2026-03-10 12:35:45.927 [info] Waiting for server to respond to `initialize` request...
2026-03-10 12:35:50.921 [info] Waiting for server to respond to `initialize` request...
2026-03-10 12:35:55.923 [info] Waiting for server to respond to `initialize` request...
2026-03-10 12:36:00.924 [info] Waiting for server to respond to `initialize` request...
# 以下、略

Information

■uvxのインストールを促すコネクションエラー
今回、検証用に使ったMarkitdownはPythonベースでコマンドにuvxを使用します。
そのため、uvxにパスが通ってない状態だと下記のコネクションエラーが発生します。

2026-03-10 12:35:30.848 [info] Starting server microsoft/markitdown
2026-03-10 12:35:30.848 [info] Connection state: Starting
2026-03-10 12:35:30.849 [info] Starting server from LocalProcess extension host
2026-03-10 12:35:30.920 [info] Connection state: Starting
2026-03-10 12:35:30.920 [info] Connection state: Error
spawn uvx ENOENT

■uvxをインストールしてパスを通せばエラーは解消します

uvxをインストール

PS > powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

downloading uv 0.10.9 (x86_64-pc-windows-msvc)
failed to download from https://releases.astral.sh/github/uv/releases/download/0.10.9
trying alternative download URL
installing to C:\Users\xxx\.local\bin
uv.exe
uvx.exe
uvw.exe
everything's installed!

To add C:\Users\xxx\.local\bin to your PATH, either restart your shell or run:

    set Path=C:\Users\xxx\.local\bin;%Path%   (cmd)
    $env:Path = "C:\Users\xxx\.local\bin;$env:Path"   (powershell)

※spawn uvx ENOENT は「uvx コマンド自体が見つからない（PATHにない）」という意味です。インストール済みでも、VS Codeを再起動してPATHが反映されているか確認してください。

uvxへパスが通ってることを確認
uvx --versionでバージョンが表示されることを確認します。

Information

Waiting for server to respond to initialize request...
MCPサーバーの起動に時間がかかっているだけなので、辛抱強く待ちましょう。

MCPサーバーを呼び出し
- MCPサーバーをインストールすると.vscode/mcp.jsonに設定されるので、これを使用して呼び出します。
```
{
    "servers": {
        "microsoft/markitdown": { //MCPサーバー名
            "type": "stdio", //MCPサーバーの種類
            "command": "uvx", //MCPサーバーが期待するコマンド
            "args": [ //コマンドに渡す引数
                "markitdown-mcp@0.0.1a4"
            ],
            "gallery": "https://api.mcp.github.com",
            "version": "1.0.0"
        }
    },
    "inputs": []
}
```
  - AIエージェントからの呼び出し例
    - MCPサーバー名と変換対象のファイルを渡して自然言語で実行。
    Information
    実行例では変換だけを指示していますが、AIエージェントから呼び出す場合、結果をファイルとして保存させるなど、プロンプト次第でさまざまな処理が可能です。
    MCPのレスポンスを加工するなどの後続処理したい場合はAIエージェントから必要なプロンプトを定義して実行します。
    
    Information
    ■期待した結果が返ってこない
    今回使用しているMarkitdownはツールがconvert_to_markdownしかないですが、複数のツールを持つMCPサーバーを使っている場合、期待したツールを呼び出してないと想定した結果がかえされません。
    実行しているツールが想定と異なる場合は明示的に指定します。
  - MCPクライアントからの呼び出し例
    - MCP Inspectorをローカルで起動してconvert_to_markdownツールを呼び出し。
MCPサーバーを停止
確認が終わったら、以下のいずれかの方法で停止。
- TerminalでCtrl+C
- VS CodeのExtensionsから停止
- .vscode/mcp.jsonから停止

まとめ

VS CodeのMCP拡張で microsoft/markitdown を起動し、PDFをMarkdownに変換するまでを実際に確認しました。
例としてMarkitdownを使用しましたが、他のMCPサーバーでもmcp.jsonに記述されている内容に沿って準備すれば応用できます。
使用したいMCPサーバーがあれば導入して、AIエージェントに力を与えましょう。

C#×TwinCAT ADSでPLCデータを自在に操る！ハンズオンで学ぶ連携の基本

2026-03-09T00:00:00.000+00:00

本記事ではC#によるADS通信を使ってTwinCAT上にあるPLCデータと連携する方法についてご紹介します。

ロボット制御ではC#が人気？

システム開発では様々なプログラミング言語が利用されています。
Python, JavaScript(Node.js, Deno), C#, Java, C++, C 等がメジャーですね。最近だとRustやGoなども人気があるようです。

ロボット制御や工場の自動化においても同様に多くの言語が利用されています。
サービスや機器を提供するベンダーは自社製品をシステムに提供する際、APIやライブラリも同時に提供します。
そのため、利用者が多いプログラミング言語であったりオープンな規格で提供することが望まれます。
AI関連やオープンソースのものはPythonモジュールでの提供が非常に多いですがライセンスビジネスではC#でのライブラリ提供が多いと感じています。

理由は下記が挙げられるかと思います。

利用者が多い
使い方が簡単(プログラミング言語の敷居が低い)
便利なライブラリが豊富(組み合わせることで開発コスト削減)
ベンダーが提供したWindows上のGUIアプリやシミュレータ(C#で開発)との連携で相性が良い
ベンダー自体もライブラリの開発がし易い
クローズドソース(ライセンスビジネスなどを想定)
Linux(.NET Core)でも動作する

Pythonモジュールでの提供もありますが、この場合はコアとなるライブラリは(クローズドソースや高速化のため)C++などのライブラリとし、Pythonはそのライブラリを利用するためのWrapperとして提供されます。

ADS通信とは

ADS(Automation Device Specification)はBeckhoff Automation社が開発した独自の通信プロトコルです。
TCP/IPやUDP/IPの上で動作しTwinCATシステム内外のソフトウェアモジュール間でのデータ交換で利用されます。

C#(.NET)のライブラリが提供されており、TwinCATの環境が整っていればすぐに利用することができます。

TwinCATがハブとなりADSプロトコルでTwinCAT PLC変数の監視・操作などができるようになります。

TwinCATおよびADS通信に関して

連載記事「TwinCATで始めるソフトウェアPLC開発」「第1回：環境構築編」をご覧ください。

TwinCAT ADSを利用したシステム構成例

TwinCAT PLCを中心にシステムが構成されます。そのためXAR(実行環境)が必要になります。またアプリケーション1-3をADS通信で TwinCATと連携させるためXAE(開発環境)が必要となります。

連携方式
TwinCATがハブとなりデバイスやアプリケーションが産業用ネットワークやADSで接続され、TwinCATを介してデータ連携することができます。

TwinCAT PLC とアプリケーション1-3 は ADS で接続
TwinCAT PLC と Device1 は EtherCAT で接続
TwinCAT PLC と Device2 は EtherNet/IP で接続

その他のデータ連携方式

TwinCAT PLCは専用のハードウェアモジュールを追加することで温度計などで計測した温度をアナログ値として電圧値で受信することも可能です。またネットワーク通信用のソフトウェアライセンスを購入することでソケット通信でのデータ受信なども可能です。

用途
TwinCAT PLC上にグローバル変数を定義しておくと以下のような用途で利用することができます。

センサー制御
センサーデータの受信
TwinCAT PLC変数の監視・操作
デバイスやロボット等との連携
TwinCAT PLC上のプログラム(Function Block)へのRPC
TwinCAT を介したプロセス間通信

TwinCAT PLC上のグローバル変数への値の設定は TwinCAT 上のプログラムで設定します。

グローバル変数の定義・値の設定に関して

連載記事「TwinCATで始めるソフトウェアPLC開発」「第2回：ST言語でのプログラミング（1/2）」をご覧ください。

ライブラリのインストール

NuGetパッケージマネージャーで Beckhoff.TwinCAT.Ads をインストールしプロジェクトの参照に設定してください。アップデートサイクル(主にバグフィクス)が比較的早く数カ月毎にマイナーバージョンがアップしています。何度かアップデートしましたが後方互換性があるので既存のコードは問題なく動作しています。

TwinCATのデータ型とC#のデータ型の対応

TwinCATのデータ型とC#のデータ型の対応表は以下。
INTがshortに対応, REALがfloatに対応など幾つか注意が必要です。

TwinCATデータ型	ビット幅	C#データ型	説明
BOOL	8 bit	byte	真偽値/bool 1bitとの記載もあるが内部的には1byteで扱われる (要注意)
BYTE	8 bit	byte	符号なし 8bit 整数
SINT	8 bit	sbyte	符号あり 8bit 整数
USINT	8 bit	byte	符号なし 8bit 整数
INT	16 bit	short	符号あり 16bit 整数 (要注意)
UINT	16 bit	ushort	符号なし 16bit 整数
DINT	32 bit	int	符号あり 32bit 整数
UDINT	32 bit	uint	符号なし 32bit 整数
LINT	64 bit	long	符号あり 64bit 整数
ULINT	64 bit	ulong	符号なし 64bit 整数
REAL	32 bit	float	単精度浮動小数点数 (要注意)
LREAL	64 bit	double	倍精度浮動小数点数
ENUM	16 bit	short	符号あり 16bit 整数 (要注意)
STRING	1 byte/char	string	1文字1バイトのバイト列 + 終端の NULL(0)文字 (要注意)
TIME	32 bit	TimeSpan	ミリ秒単位の符号なし整数

TwinCAT側の設定

以下の条件で変数を登録します

PlcProject プロジェクト - GVLs にグローバル変数リスト名 GVL_Test を定義(名前は任意)
変数名 TestData データ型 DINT とする

TwinCAT側の設定

{attribute 'qualified_only'}
VAR_GLOBAL
    TestData : DINT;
END_VAR

それではC#からTestData変数にアクセスしてみましょう。

AdsClientによる変数アクセス

AdsClientはTwinCATとアクセスする際の窓口になります。
数値データはすべて同じ方法でRead/Writeできます。

AdsClient生成の例

using System;
using TwinCAT.Ads;

namespace AdsComponent
{
    class Program
    {
        static void Main(string[] args)
        {
            // AdsClientのインスタンス作成
            AdsClient client = new AdsClient();

            // TwinCATへの接続
            // 第1引数: AmsNetId文字列
            // 第2引数: ポート番号 (TwinCAT3 PLCの場合は851)
            client.Connect("192.168.1.101.1.1", 851);

            // TwinCATのグローバル変数を参照するためのハンドルを作成
            // TwinCAT側で定義した "グローバル変数リスト名.変数名"で指定する
            uint handle = client.CreateVariableHandle("GVL_Test.TestData");

            // 書き込み操作
            int writeValue = 123;
            client.WriteAny(handle, writeValue);

            // 読み取り操作
            int readValue = (int)client.ReadAny(handle, typeof(int));
            Console.WriteLine($"read:{readValue}");

            // ハンドルの解放
            client.DeleteVariableHandle(handle);

            // 接続を閉じて、リソース解放
            client.Close();
            client.Dispose();
        }
    }
}

読みやすさ優先のため例外処理や定数の定義等を省いています

AmsNetIdの指定

連載記事「TwinCATで始めるソフトウェアPLC開発」
「第1回：環境構築編」の「ADS通信ルート設定」で表示されているAmsNetIdを指定してください

コネクションは繋ぎっぱなしでもOKですが使い終わったら必ずリソースを解放してください

AdsClientはSystem.IDisposableインタフェースを実装しているためusingステートメントを使うことができます

データ変更コールバック通知

TwinCAT側の GVL_Test.TestData 変数が変化したかどうかを監視するにはReadAny()による定期的なポーリングは効率が悪く、スレッドも独自で管理する必要があります。これを解決するための手段として値が変化した際に、自動でクライアント側へコールバック通知を飛ばす仕組みがあります。

データ変更コールバック通知の例

private AdsClient _adsClient;  // インスタンス生成、コネクション接続済みとする
private uint _handleNotification = 0;

// データ変更通知開始
public void StartValueChangeNotification()
{
    // イベントハンドラの登録
    _adsClient.AdsNotificationEx += OnAdsNotified;

    // データ変更通知ハンドルの登録(通知開始)
    _handleNotification = _adsClient.AddDeviceNotificationEx(
            "GVL_Test.TestData",
            // 50[msec]毎に変更があったときに通知する
            // 最大遅延時間を0[msec]とする
            new NotificationSettings(AdsTransMode.OnChange, 50, 0),
            null,
            typeof(int));
}

// イベント受信
private void OnAdsNotified(object sender, AdsNotificationExEventArgs evn)
{
    if (evn.Handle != _handleNotification)
    {
        return;
    }

    var data = (int)evn.Value;
    Console.WriteLine($"notified:{data}");
}

// データ変更通知停止
public void StopValueChangeNotification()
{
    // データ変更通知ハンドルの削除(通知停止)
    _adsClient.DeleteDeviceNotification(_handleNotification);                 
    _handleNotification = 0;

    // イベントハンドラの登録解除
    _adsClient.AdsNotificationEx -= OnAdsNotified;
}

StartValueChangeNotification() を実施した後、TwinCAT側で GVL_Test.TestData の値が更新されるとC#側で OnAdsNotified() がコールバックされます。
なお、コールバック通知処理を終える場合は必ず StopValueChangeNotification() を実施しハンドルを解放してください。

`GVL_Test.TestData` の値を更新するには

グローバル変数の定義・値を手動で更新するには連載記事「TwinCATで始めるソフトウェアPLC開発」
「第2回：ST言語でのプログラミング（1/2）」の「3.3 ログインによる動作確認」よりPLCにログインして該当変数の値を直接書き換えてください

コールバック周期通知

データ変更コールバック通知のパラメータを変えることで周期的な通知も可能です。

コールバック周期通知の例

// 定期的な通知開始
public void StartCyclicNotification()
{
    // イベントハンドラの登録
    _adsClient.AdsNotificationEx += OnAdsNotified;

    // 周期通知ハンドルの登録(通知開始)
    _handleNotification = _adsClient.AddDeviceNotificationEx(
            "GVL_Test.TestData",
            // 10[msec]毎に通知する
            // 最大遅延時間を1[msec]とする
            new NotificationSettings(AdsTransMode.Cyclic, 10, 1),
            null,
            typeof(int));
}

AdsTransMode.Cyclic を指定することで周期的な通知となります。通知タイミングを10[msec]、最大遅延時間を1[msec]とした場合、1[msec]の遅延が発生する場合が稀にありますが、ほぼ正確に10[msec]毎に通知されました。
TwinCAT側はカーネルモードで動作しているため正確な周期で値の通知が可能かと思われますが、C#側は普通のWindowsアプリでWindows OSのスケジューリングの精度やネットワークドライバの受信処理などによる遅延が発生するかと思いますが不思議な現象です。いつか調査してみたいと思います。

構造体の定義

Read/Writeするデータやコールバック通知のデータ型にはプリミティブ型だけでなく構造体も使用可能です。また構造体はネストも可能です。
まずは例としてTwinCAT側で構造体 DUT_Sample を定義します。

TwinCAT側の構造体設定

// DUT_Sample構造体定義
TYPE DUT_Sample :
STRUCT
    IsValid : BOOL;      // BOOL型
    Height : DINT;       // DINT型
    CurrentMode : EMode; // ENUM型
    Status : DUT_Status; // 構造体
END_STRUCT
END_TYPE

// EMode ENUM型定義
{attribute 'strict'}
{attribute 'to_string'}
TYPE EMode :
(
    Vertical := 0,
    Horizontal := 1
);
END_TYPE

// DUT_Status構造体定義
TYPE DUT_Status :
STRUCT
    Status1 : DINT;
    Status2 : DINT;
END_STRUCT
END_TYPE

グローバル変数リスト GVL_Test に Sample を追加します。

TwinCAT側のグローバル変数設定

{attribute 'qualified_only'}
VAR_GLOBAL
    TestData : DINT;
    Sample : DUT_Sample;
END_VAR

グローバル変数 GVL_Test.Sample をC#側でも扱えるようにC#側でも同じ構造体を定義します。
ただし、アライメントの問題(メモリ上でのデータを配置する際の整列ルール)がありますので注意が必要です。
TwinCAT 3では、デフォルトで8byteのアライメントが採用されているため、これにあわせてC#側の構造体を定義する必要があります。

構造体には属性 [StructLayout(LayoutKind.Sequential, Pack = 8)] を付与する
構造体以外のデータ型は「TwinCATのデータ型とC#のデータ型の対応」に合わせる
変数の定義順序はTwinCAT側と合わせる

なお、変数や構造体の名前はTwinCAT側と合わせる必要はありませんが合わせておくと対応関係が明らかですのでお勧めします。

C#側の構造体の定義の例

// Sample構造体
[StructLayout(LayoutKind.Sequential, Pack = 8)]
public struct Sample
{
    public byte   IsValid;     // BOOL型 => byte
    public int    Height;      // DINT型 => int
    public EMode  CurrentMode; // ENUM型 => EMode
    public Status Status;      // 構造体 => Status
}

// Emode定義
public enum EMode : short     // ENUM型 => short
{
    Vertical,
    Horizontal,
}

// Status構造体
[StructLayout(LayoutKind.Sequential, Pack = 8)]
public struct Sample
{
    public int Status1; // DINT => int
    public int Status2; // DINT => int
}

int readValue = (Sample)client.ReadAny(handle, typeof(Sample)); のようにキャストや typeof() を使うことでプリミティブ型と同じAPIが使えます。

文字列(string)のRead/Write

TwinCAT 側ではSTRING型で文字列を扱うことができます。しかし、1文字1バイトのASCII文字コード(Latin-1)として扱われるためそのままでは日本語を書き込むと文字化けします。また、バイト数を指定して定義する必要があります。そのためUTF-8でエンコードするように指定して定義します。

TwinCAT側の設定

{attribute 'qualified_only'}
VAR_GLOBAL
    TestData : DINT;
    Sample : DUT_Sample;

    // UTF-8での文字列定義
    {attribute 'TcEncoding':='UTF-8'}
    Message : STRING(1024);
END_VAR

変数定義に {attribute 'TcEncoding':='UTF-8'} を付与することで文字コードをUTF-8と解釈させる
文字サイズはバイト数で指定する
文字サイズは終端のNULL(0)文字まで含めたサイズ

UTF-8の場合、1文字のバイト数は可変長(1～4バイト)となります。一般的な日本語は3バイトとなりますので余裕のあるバイトサイズを指定してください。

文字列(string)Read/Writeの例

using System.Text;

private const int STRING_SIZE = 1024;
private AdsClient _adsClient; // インスタンス生成、コネクション接続済みとする
private uint _handle; // 'GVL_Test.Message' を指しているものとする

// 文字列の書き込み
public void WriteMessage(string message)
{
    // UTF-8の文字列をバイト配列に変換
    byte[] utf8Bytes = Encoding.UTF8.GetBytes(message);

    // バイトサイズチェック
    if (utf8Bytes.Length > STRING_SIZE)
    {
         throw new Exception($"バイト数オーバー");
    }

    // バッファの初期状態はNULL(0)文字で埋められている
    byte[] targetBuffer = new byte[STRING_SIZE];
    // 変換したバイト配列を、固定長配列の先頭からコピーする
    Buffer.BlockCopy(utf8Bytes, 0, targetBuffer, 0, utf8Bytes.Length);

    _adsClient.WriteAny(_handle, targetBuffer);
}

// 文字列の読み取り
public string ReadMessage()
{
    // 固定長のバイト配列を取得する(終端のNULL文字も含む)
    var byteArray = (byte[])_adsClient.ReadAny(
            _handle, typeof(byte[]), new int[] {STRING_SIZE});

    // バイト配列の中から最初のNULL文字(0)を探す
    int nullCharIndex = Array.IndexOf(byteArray, (byte)0);

    // NULL文字が見つかった場合は、そこまでを文字列とする
    if (nullCharIndex >= 0)
    {
        // GetString(バイト配列, 開始インデックス, 長さ)
        return Encoding.UTF8.GetString(byteArray, 0, nullCharIndex);
    }

    // NULL文字が見つからない場合 (バッファが文字列で満たされている) は、
    // 配列全体を変換する
    return Encoding.UTF8.GetString(byteArray);
}

UTF-8文字列の扱いは他のデータ型に比べて少し冗長なコードになります。
文字列は定義時のバイトサイズの配列で送受信されるため、1文字だけ送りたい場合でも残りはNULL文字で埋めてバッファサイズ分データ転送されることになります。

まとめ

ADS通信で様々なデータ型の扱い方とコールバック通知の方法を理解できたかと思います。これを応用することでRPCやプロセス間通信ができます。
PC1上のプロセスA と PC2上のプロセスB とで連携するとき、データ型をJSON文字列(STRING(1024)など)で定義すれば汎用的なデータで分散処理システムを構築できます。またコールバック通知の仕組みを上手く使えばTwinCAT上の変数をTopicとみなすPublish/Subscribe型のシステムも実現できるのではないでしょうか？

BeckhoffはADSの通信プロトコル仕様をWebサイト上で公開しており、オープンソースのADS通信ライブラリもあるそうです。そのためPython, Node.js, GoなどからもADS通信ができるようです。ただし、当然これらオープンソースのライブラリはBeckhoffからのサポートが受けられない点に注意が必要です。

AWS Firewall Managerの2大セキュリティポリシー：初心者でもわかる実践＆運用ポイント

2026-03-06T00:00:00.000+00:00

0. はじめに

こんにちは。豆蔵R&Dグループの丹羽です。
今回はAWSセキュリティサービスの1つである「AWS Firewall Manager」（以下、FMS）^[1]のポリシー設定について紹介したいと思います。

最近、私が関わるプロジェクトで「AWS Shield Advanced」を導入する必要があり、Organizationsでのアカウント管理を行っている場合、任意のOUや任意のアカウントをShield Advancedの保護対象に一括で設定するためには「AWS Firewall Manager」のポリシー設定を利用する手法が推奨されています。
このポリシー設定における挙動がややわかりにくかったため、今回実際に検証してみた結果を共有したいと思います。

現在Organizationsを利用していて、「一元的なDDoS対策やWeb ACL適用をしたい」「AWS Shield Advancedの導入を考えている」「FMSポリシーについて事前に挙動を知っておきたい」など、導入検討や挙動理解をしたい方、AWSセキュリティ運用を本格的に開始しようとしているプロジェクトにとって参考になればと思います。

1. この記事で分かること

この記事では、FMSが提供する 2つの主要なセキュリティポリシー について、実際の検証結果をもとにその挙動を解説します。

FMS Shield Advancedポリシー: 組織全体にDDoS保護を一元適用するポリシー
FMS WAFポリシー: 組織全体にWeb ACL^[2]ルール^[3]を一元配布・適用するポリシー

どちらのポリシーについても「目的」「仕組み」「検証して分かったこと」の3つの観点で整理していきます。特に、自動修復機能（Auto Remediation）^[4]の挙動や、既存のWeb ACL（独自に定義したWeb ACLという意味）との共存パターンなど、公式ドキュメントだけでは掴みにくいリアルな動きを中心にお届けします。

2. 前提知識と対象読者

前提知識

本記事は「FMSポリシー設定における挙動の検証」がメインの内容になるため、FMSや検証時に登場するWAF、Shield、それらに関連するサービスについて簡単に整理しておきましょう。
その他に登場するサービスについては記事の各所で補足していきたいと思います。

AWS Firewall Manager とは

AWS Firewall Manager（FMS）は、AWS Organizations を利用して、複数の AWS アカウントにまたがる各種セキュリティルールを一元的に管理・適用するためのサービスです。FMS を使うことで、セキュリティポリシーの適用漏れを防ぎ、組織全体のセキュリティレベルを均一に保つことができます。

本記事で紹介するFMSのポリシーは先にも述べた以下の2つです。

FMS Shield Advancedポリシー: 組織全体にDDoS保護を一元適用するポリシー
FMS WAFポリシー: 組織全体にWeb ACLルールを一元配布・適用するポリシー

上記2つ以外にもポリシーは存在していますが、今回は触れないため説明は省略します。

補足: AWS Organizationsとは
複数のAWSアカウントを組織として一元管理するサービスです。OU（Organizational Unit：組織単位） という階層構造でアカウントをグループ化し、ポリシーを一括適用できます。FMSポリシーはこのOU・アカウント単位でスコープを指定して配布します。

AWS WAF とは

AWS WAF は、Webアプリケーションへの不正なリクエストをフィルタリングするためのサービスです。Web ACL（アクセスコントロールリスト）の中にルールを定義し、CloudFrontやALBなどのリソースに関連付けて使います。

たとえば「SQLインジェクション攻撃をブロックする」「特定の国からのアクセスを制限する」といった防御ルールを、リソース単位で細かく設定できるのが特徴です。

補足: 関連するAWSリソース

ALB（Application Load Balancer）: HTTPSレベルでトラフィックを振り分けるロードバランサー。WAF・Shield Advancedの主要な保護対象リソースの1つ。

CloudFront: AWSのCDN（コンテンツ配信ネットワーク）サービス。グローバルエッジでWAFルールを適用できる。

AWS Shield とは

AWS Shieldは、DDoS攻撃^[5]からAWSリソースを保護するサービスです。2つのプランがあります。

プラン	概要
Shield Standard	すべてのAWSユーザーに無料提供。L3/L4層（ネットワーク層・トランスポート層）の一般的なDDoS攻撃を自動防御
Shield Advanced	有料。より高度なDDoS保護、WAF利用料の無料化、DRT（DDoS Response Team）^[6]への相談権利、コスト保護などを提供

Shield Advancedを利用する場合、対象リソース（ALB、CloudFront、EIPなど）に「保護（Protection）」を作成して有効化する必要があります。

FMSを利用することで、新規リソース作成時に自動的にShield Advancedで保護し、設定漏れを防ぐことができ、Organizations内の全アカウントのShield Advanced保護を、FMSから集中管理することができます。

この記事の対象読者

Organizationsを利用した一元的なアカウント管理をしている方
Shield Advancedの導入を検討している方
AWSのセキュリティサービスに興味があり、組織全体での統制を考えている方
FMSを使って「全アカウントに共通のセキュリティルールを適用したい」と考えている方

3. FMS Shield Advancedポリシー

3-1. 何をするためのものか（目的）

先ほども軽く触れましたが、Shield Advancedを使うには保護したいリソース1つ1つに対して「保護」を作成する必要があります。しかし、AWS Organizationsで管理している複数のアカウントにまたがるリソースすべてに対して手作業で保護を設定するのは正直なところ現実的ではありません。

FMS Shield Advancedポリシーはこの課題を解決するためのものです。管理者アカウント（または委任管理者アカウント）^[7]から「この範囲のアカウント内に存在するALBやEIPには、全部Shield Advancedの保護をかけてね」とポリシーを定義するだけで、FMSが対象リソースを検出し、保護を一元的に適用してくれます。

3-2. 大まかな仕組み

FMS Shield Advancedポリシーの基本的な動作フローを整理すると、以下のようになります。
ここで記載されている管理者アカウントというのは、Shield Advancedをサブスクライズしたアカウントのことを指します。（基本的にはOrganizationsの管理アカウントと同一のことが多い）

flowchart TD
    A["管理者アカウント<br>or FMS委任アカウント"]
    B["AWS Firewall Manager"]
    C["メンバーアカウント"]
    D_OFF["検出・報告のみ<br>Non-Compliant として記録"]
    D_ON["Shield保護を自動作成"]
    E{"L7自動緩和<br>有効?"}
    F["ALBにWeb ACLを<br>自動作成・関連付け"]
    G["準拠（Compliant）状態"]

    A -->|"① ポリシー作成<br>対象リソース・適用スコープ・自動修復を定義"| B
    B -->|"② Config Ruleを配布<br>Shield保護の未設定リソースを監視"| C
    C -->|"③-a 自動修復 OFF"| D_OFF
    C -->|"③-b 自動修復 ON"| D_ON
    D_ON --> E
    E -->|"有効（ALBなど）"| F --> G
    E -->|"無効"| G

準拠（Compliant）というのは、FMSが対象リソースを検出し、保護を一元的に適用している状態のことを指します。自動修復をOFFにしている場合、FMSは検出のみ行い保護対象には追加しないため非準拠となります。

ここで、AWS Configサービスが関連してくるので簡単に捕捉しておきます。

AWS Configとは（FMSとの関係）

AWSリソースの設定状態を継続的に記録・評価するサービスです。AWS Config Rule（設定ルール）を定義することで、「リソースがこの基準を満たしているか？」を自動評価できます。
FMSはこの仕組みを活用し、ポリシー配布時にメンバーアカウントへConfig Ruleを自動定義。「Shield保護が未設定のリソースはないか」「FMS管理のWeb ACLが適用されているか」をConfigが継続監視し、準拠（Compliant）/非準拠（Non-Compliant）として報告します。

特に重要なのは、L7自動緩和（Automatic application layer DDoS mitigation）^[8]の設定です。この機能を有効にすると、ALBのような対象リソースに対して紐づけられているWeb ACL内に、自動緩和用のWeb ACLルール（ShieldMitigationRuleGroup... という名前のルール）がFMSによって自動で作成されます。

Information

このWeb ACLルールの自動作成は、あくまで「Shield AdvancedのL7自動緩和機能」に必要なものです。WAFポリシーで作成されるWeb ACLとは別物であり、既存のWeb ACLに影響を与えることはありません。
実際、既存のWeb ACLルール内の最後にFMSが作ったルール（ShieldMitigationRuleGroup... という名前のルール）が追加されます。最後に追加されるので、ルール評価順序としても最後になり、既存ルールでチェックしたい内容を妨げることはないです。

3-3. 実際の検証結果

検証は、メンバーアカウント上にALBとEIP（EC2にアタッチ）を用意し、管理者アカウントからFMS Shield Advancedポリシーを適用する形で行いました。

Caution

念のため断っておきますが、以下の検証はあくまで「検証」という位置づけなので、いきなり本番運用しているアカウントやOUに対して実施することはおすすめしません。もしやらざるを得ない場合でもWebACLのバックアップ（JSONによる設定定義ファイル）をダウンロードしておくなどロールバックできる準備はしておくことをお勧めします。

【検証パターンS-1: 自動修復OFF】

項目	内容
FMS設定	自動修復: 無効（Disabled）
事前状態	ALB・EIPにShield保護なし
期待値	Non-Compliant（非準拠）として検出されるが、保護は作成されない

結果: 期待通りの挙動

FMSがメンバーアカウントにAWS Configルールを自動配布し、そのルールによってALB・EIPのShield保護未設定が検出されました。FMSコンソール上では、アカウント自体のステータスが「Non-Compliant（非準拠）」、個別リソースのステータスも「Non-Compliant（非準拠）」となります。

管理アカウントのFMSコンソール

メンバーアカウントに対するステータスが非準拠
メンバーアカウント内の対象リソース（ALB, EIP）に対するステータスが非準拠の理由

メンバーアカウントのAWS Config画面

メンバーアカウントに作られるConfigルール
Configルールによる非準拠リソースの検出
例えば、対象リソースALBのConfig詳細の「リソースタイムライン」を確認すると、FMSによってConfigルールが適用されたことが確認できる

補足

Configルールによってリソースの設定情報が「どうだったか」「どうかわったのか」を確認するには、画像にある「ルールのコンプライアンス」や「設定変更」を開くことで、どのように設定が変更されて保護対象になったのか（あるいは保護対象外になったのか）、FMSルールが非準拠・準拠になったかどうかが確認できる。
（リソースの固有情報が割とバッと表示されるのでここでは開いた場合の画像は割愛します（マスクするのがめ…orz）。ご了承くださいｍｍ）

【検証パターンS-2: 自動修復ON】

項目	内容
FMS設定	自動修復: 有効（Enabled）
事前状態	ALB・EIPにShield保護なし
期待値	Shield保護が自動作成され、Compliant（準拠）に変わる

結果: 期待通りの挙動。（反映にはタイムラグがあり）

自動修復を有効にしてから数分後、EIPのステータスが先にCompliantになりました。一方、ALBのステータスがCompliantになるまでにはもう少し時間がかかり、追加で数分待つ必要がありました。

ALBについては、Shield保護の作成に加えて、L7自動緩和用のWeb ACLルール（ShieldMitigationRuleGroup...）が自動作成されていることも確認できました。これはShield Advancedの機能によるものであり、想定どおりの動作です。

管理アカウントのFMSコンソール

自動修復の有効設定

補足

画像内にある「Replace~」ですが、このチェックをONにすると、もし対象リソース（ALB、EIPなど）にWAF Classicで作られた古いWeb ACLが関連付けられていた場合に、FMSがそれをWAFv2のWeb ACLに自動的に置き換えます。

メンバーアカウントのコンソール画面

WAF&Shieldコンソール
FMSによってWeb ACLが作成されます。

FMS作成のWeb ACLはALBなどのリソースへの紐づけはされず、

代わりに既存Web ACLにルールが追加されます。
「ShieldMitigationRuleGroup_...」という名前のルールが既存Web ACLのルールの最後に追加されていることが確認できます。
これがDDoS保護のためのルールのようです。

WebACLの評価は上から順に適用されるので、最後に追加されていることで既存のWeb ACLルール評価順序に影響が出ないような仕組みになっているということですね。
Configコンソール
自動修復の有効にしたことによってリソースが保護対象となりステータスが準拠になりました。

同様にリソースタイムラインから対象リソースがShield Advancedポリシーの保護対象になったことなどが見れます。（画像は割愛します。）

ポリシー削除時の挙動

検証完了後にポリシーを削除したところ、メンバーアカウント上にFMSが作成したConfigルールやWeb ACLはきちんと削除されました。ポリシー削除直後は残っていたリソースも、しばらく待つと自動的にクリーンアップされることを確認しています。

管理アカウントのFMSコンソール

削除

メンバーアカウントのコンソール画面

WAF&Shieldコンソール
Configコンソール
ルールが削除されるので「利用不可」になる。

4. FMS WAFポリシー

4-1. 何をするためのものか（目的）

AWS WAFは非常に強力なサービスですが、組織内の全アカウントで「最低限これだけは守ってほしい」という共通ルールを徹底するのは意外と大変です。各アカウントの管理者に「この設定を入れてください」とお願いして回るのは、管理する側も管理される側も負荷が高いですよね。

FMS WAFポリシーは、管理者がWeb ACLの設定内容（適用するルールグループ、デフォルトアクションなど）をポリシーとして定義し、組織全体に一括で配布・適用するためのものです。

4-2. 大まかな仕組み

FMS WAFポリシーには、Shield Advancedポリシーよりも設定項目が多く、特に「既存のWeb ACLがある場合にどう扱うか」が重要な設計ポイントになります。

置換するor統合する

結論から言うと、FMS WAFポリシーを作成しWeb ACLを適用する際には、

管理者が定義したルールをFMSが管理するWeb ACLに置換する
メンバーアカウントの独自ルールを挟み込むような形で統合する

の2通りの設定パターンがあります。

挟みこむというのは、

flowchart TD
    subgraph ACL["FMS管理 Web ACL"]
        direction TB
        FRG["🔒 First Rule Groups（最初に評価）<br>管理者が設定 · メンバーは変更不可"]
        CUS["✏️ メンバーアカウントの独自ルール<br>各アカウントが自由に追加・編集可能"]
        LRG["🔒 Last Rule Groups（最後に評価）<br>管理者が設定 · メンバーは変更不可"]
        DEF["Default Action<br>Allow または Block"]

        FRG --> CUS --> LRG --> DEF
    end

補足

First / Last Rule Groups とは
FMS WAFポリシーで設定できるルールグループの配置枠です。

First Rule Groups: メンバーアカウントの独自ルールより先に評価される。「絶対にブロックしたい通信」を管理者が強制したい場合に使う。
Last Rule Groups: 独自ルールより後に評価される。「最後の砦」として組織共通の後処理ルールを設定する。
Default Action: どのルールにもマッチしなかったリクエストへの最終アクション（Allow または Block）。FMSポリシーで設定する。

この構造により、管理者が強制するベースラインを保ちながら、各アカウントが独自ルールを自由に追加できます。

これにより、組織全体のセキュリティベースラインを管理者が強制しつつ、各アカウントのアプリケーション固有のルールも柔軟に追加できる仕組みになっています。

Web ACL管理の4パターンを検証してみる

FMS WAFポリシーでは、リソースに対してどのようにWeb ACLを適用するか、いくつかパターンがあると思いますが、今回は以下の4パターンを試してみようと思います。

パターン	自動修復	置換オプション	Retrofit^[9]	挙動
W-1: 検出のみ	OFF	-	-	ポリシー違反を検知・報告するだけ。リソースには何も変更しない
W-2: 自動修復（置換OFF）	ON	OFF	OFF	Web ACL未設定のリソースにはFMS作成のWeb ACLを適用。既に独自のWeb ACLが設定されているリソースは変更しない
W-3: 自動修復（置換ON）	ON	ON	OFF	すべての対象リソースに対して、強制的にFMS作成のWeb ACLに置き換える
W-4: 自動修復（置換OFF）	ON	OFF	ON	すべての対象リソースに対して、FMSのルールを注入する

4-3. 実際の検証結果

検証は、メンバーアカウント上にALBと独自のWeb ACL（test-fms-waf-log）を用意し、4つのパターンに沿って設定をおこない挙動を確認しました。

【検証パターンW-1: 自動修復OFF】

項目	内容
FMS設定	自動修復: 無効
事前状態	ALBにWeb ACL関連付けなし
期待値	Non-Compliant。Web ACLは関連付けられない

結果: 想定通りの結果。FMSコンソール上でNon-Compliantとして検出され、ALBには何も変更が加えられない。

管理アカウントのコンソール画面

該当設定箇所

メンバーアカウントのコンソール画面

ポリシー設定後のWAF/Config画面
リソースに関連付けされていない独自のWeb ACLがあり（事前に作成しているもの）、

ConfigコンソールのFMSが作成したルールでのステータスは、自動修復がOFFであり、ALBにはどのACLも関連付けされていないため、FMS WAFポリシーによる評価が非準拠になる。

管理アカウントのコンソール画面

ポリシー適用後のFMSコンソール画面

【検証パターンW-2: 自動修復ON・置換OFF】

項目	内容
FMS設定	自動修復: 有効、既存Web ACLの置換: OFF
事前状態	ALBにWeb ACL関連付けなし
期待値	FMS作成のWeb ACLが自動的にALBに関連付けられ、Compliantになる

結果: 想定通りFMSが自動で作成したWeb ACLがALBに関連付けられた。ステータスもCompliant。

管理アカウントのコンソール画面

該当設定の更新

メンバーアカウントのコンソール画面

fmsが作成したWeb ACLがALBに関連付けられている
Configルールも準拠になった

管理アカウントのコンソール画面

しばらくまってから管理コンソールを確認すると

【検証パターンW-3: 置換ONの状態で独自Web ACLを割り当ててみる】

ここからが面白いところです。W-2でFMS管理のWeb ACLが適用された状態から、手動でメンバーアカウント上で独自のWeb ACL（test-fms-waf-log）に差し替えてみました。

項目	内容
FMS設定	自動修復: 有効、既存Web ACLの置換: ON
事前状態	ALBにFMS作成のWeb ACLが関連付け済み → 手動で独自Web ACLに変更
期待値	FMS管理のWeb ACLが強制的にALBに関連付けられ、Compliantになる

結果: 想定通りの結果

メンバーアカウントのコンソール画面
メンバーアカウントで独自Web ACLを割り当てた直後の画面

↓

↓

このようにfms管理のWeb ACLが外れ、独自Web ACLが設定されている状態となる。

管理アカウントのコンソール画面
次に、管理アカウントから置換ONに変更してみる。

メンバーアカウントのコンソール画面
メンバーアカウント上でのACLの状態において、fms管理のWeb ACLは以下のようになります。

そして、独自に作ったWeb ACLは以下のようになります。

このように置換設定ONで自動修復を有効にすると、手動で独自Web ACLをALBに関連付けた場合に、一度紐づけていたFMS管理のWeb ACLは自動的に外れますが、その後FMS管理のWeb ACLが強制的に再度ALBに関連付けられ、Compliantになります。

もし、運用メンバーが意図せずにFMS管理のWeb ACLをALBから外してしまった場合などに、FMS管理のWeb ACLの関連付けに強制的に戻すことができるということですね。
しかし、意図していた場合に強制的に戻されるのは困るわけです。

【検証パターンW-4: Retrofit（既存Web ACLの改修）モード】

そこで存在しているのが 「Retrofit existing web ACLs」 ^[9:1]パターンなのかなと考えています。

少しややこしくなってきたと思うので、検証内容をざっと説明しておくと、
W-3の状態（FMS管理のWeb ACLがALBに関連付けられている状態）から、一度FMS WAFポリシーの「Replace existing associated web ACLs」オプションをOFFに変更し、改めて独自のWeb ACLをALBに関連付けた状態で、自動修復有効・Retrofitモードも有効にした状態にWAFポリシーを更新します。

flowchart TD
    S["W-3の状態<br>FMS管理Web ACL → ALBに関連付け済み"]
    A["① 管理アカウントでWAFポリシーを更新<br>置換オプション（Replace）をOFF に変更"]
    B["② メンバーアカウントで手動操作<br>独自Web ACLをALBに関連付け<br>（FMS管理Web ACLは自動的に外れる）"]
    C["③ 管理アカウントでWAFポリシーを更新<br>自動修復: ON<br>Retrofit: ON"]
    D["④ FMSが独自Web ACLに対して<br>First / Last Rule Groupsを注入"]
    E["準拠（Compliant）状態<br>独自ルール + FMSルールが共存"]

    S --> A --> B --> C --> D --> E

項目	内容
FMS設定	自動修復: 有効、既存Web ACLの置換: OFF、Retrofit: ON
事前状態	ALBにFMS作成のWeb ACLが関連付け済み → 手動で独自Web ACLに変更
期待値	FMS管理のWeb ACLルールが、独自Web ACLの内容を保ちながらマージされ、Compliantになる

結果: 想定通りの結果

Retrofitモードでは、FMSは新たなWeb ACLを作成するのではなく、既存のカスタムWeb ACLの中に、FMS WAFポリシー定義時に設定したルールグループが注入されました。

具体的には、独自のWeb ACLに定義されていたルールはそのまま維持され、FMS WAFポリシーで設定したFirst Rule Groups（優先ルールグループ）とLast Rule Groups（最終ルールグループ）（今回はFirst Rule Goupsのみ）をサンドイッチする形で追加されます。

AWS Configのステータスも準拠（Compliant）となり、独自のWeb ACLの独自ルールとFMSのルールが共存している状態が確認できました。

以下検証時のコンソールの様子です。（※事前状態から始めています。）

メンバーアカウント上のコンソール

メンバーアカウント上でのWeb ACLの様子

管理アカウント上のコンソール

管理アカウントでのWAFポリシー設定を「置換OFFの状態で、RetrofitをONにする」

RetrofitがONだと、自動で置換モードが選択できなくなる（以下の補足参照）

メンバーアカウント上のコンソール
FMS管理のWeb ACLはリソースへの紐づけがありませんが、

独自に作成したWeb ACLにはFMSのルールが注入されています。

補足

置換ON設定とRetrofitモードは排他的な設定です。「置換ON設定で運用中にRetrofitに切り替える」場合は、一度置換OFFにしてからRetrofitを有効化する必要があります。

5. まとめ

今回の検証を通じて、FMSの2つのセキュリティポリシーの挙動を実際に確かめることができました。検証結果をまとめると、以下のようになります。

Shield Advancedポリシーのポイント

確認事項	結果
自動修復OFFでの検出	✅ Non-Compliantとして正しく検出される
自動修復ONでの保護作成	✅ Shield保護が自動作成される
L7自動緩和によるWeb ACL	✅ ALBにはDDoS緩和用のWeb ACLが自動作成される
ポリシー削除時のクリーンアップ	✅ FMS作成リソース（Config Rule、Web ACL）は自動削除される

WAFポリシーのポイント

確認事項	結果
自動修復OFFでの検出	✅ Non-Compliantとして正しく検出される
自動修復ON・置換OFFでのWeb ACL適用	✅ 未設定リソースにのみFMS Web ACLが適用される
置換OFF時の既存Web ACL保護	✅ 既存Web ACLは書き戻されない（安全に運用可能）
置換ON時の強制置換	✅ 既存Web ACLからFMS Web ACLに紐づけが切り替わる（カスタムWeb ACL自体は削除されない）
Retrofitモード	✅ 既存Web ACLにFMSルールを注入。独自ルールは維持される

運用する際のポイント

検証結果を踏まえ、FMSセキュリティポリシーを運用する際に意識しておくべきポイントを挙げます。

まずは自動修復OFFで始める: いきなり自動修復を有効にするのではなく、まずは「検出のみ」モードで対象を把握してから有効化するのが安全。
置換オプションは慎重に: 既にWAFを運用中のリソースがある場合、置換ONにすると既存の防御設定が外れるリスクがある。Retrofitモードの活用も検討。
反映までのタイムラグを考慮する: 地味に大事なのが、fmsポリシーの設定反映には数分〜十数分のラグがあるため、「設定したのに変わらない！」と慌てずに、しばらく待ってから確認したうえで次の設定をしたりするのがいいです。
ポリシー削除時のクリーンアップを信頼する: FMS作成のリソースはポリシー削除時にきちんと削除されます。ただし、こちらも完全削除までに若干の時間がかかります。

FMSは「設定して放っておけば組織全体を守ってくれる」便利なサービスですが、その裏側では多くのリソースが自動的に作成・管理されています。今回はFMSの2種類のポリシーに絞って紹介をしましたが、その挙動や背後で自動的に行われる設定などをざっくりとでも把握しておくことで、確証を持ったセキュリティ対策を実施できると思います。

ポリシー適用後のステップ

今回はボリューム感が大きくなってきたため扱えませんでしたが、FMSポリシーを設定したあとにさらに整備しておくと良い内容として、以下が挙げられます。

攻撃通知の整備: Shield Advancedポリシーで検知した攻撃を管理者へ通知（SNSやCloudWatchアラームの活用）
リクエストログの収集・分析: 保護対象リソースへのリクエストをS3バケットに蓄積し、Athenaなどで分析できる体制を整える

補足: 関連サービスの概要

SNS（Simple Notification Service）: AWSのメッセージ通知サービス。Shield Advancedの攻撃検知イベントと組み合わせてアラート通知に利用する。

CloudWatch: AWSのモニタリングサービス。メトリクスやアラームを設定し、DDoS攻撃検知時に自動通知・自動対応のトリガーとして使える。

S3（Simple Storage Service）: WAFログの保管先。CloudFrontやALBのアクセスログ・WAFログを集約する。

Athena: S3上のデータをSQLでクエリできる分析サービス。S3に収集したWAFログをそのままSQL分析できるため、攻撃パターンの分析に有効。

私自身も今後のプロジェクトの中でこれらは実施していく予定ですので、また皆さんに共有すべき事項が出てきた場合にはまとめてみようと思います。

紹介した検証内容がSheld AdvancedとFMSの理解、そしてセキュリティ対策の一助となれば幸いです。

注釈

AWS Firewall Manager（FMS）: AWS Organizationsと連携し、組織全体のWAF・Shield・セキュリティグループなどのセキュリティポリシーを一元管理するサービス。参考: AWS Firewall Manager Developer Guide ↩︎
Web ACL（Web Access Control List）: AWS WAFの中核リソース。リクエストの許可・拒否を判定するためのルールをまとめた「箱」。ALBやCloudFrontなどのリソースに関連付けて使用する。参考: AWS WAF Web ACLs ↩︎
ルール（Rule）: Web ACL内に定義する個々の検査条件。「IPアドレスの一致」「リクエストボディの検査」など、トラフィックを評価するための条件と、マッチした場合のアクション（Allow/Block/Count）をセットにしたもの。 ↩︎
自動修復（Auto Remediation）: FMSポリシーの機能の1つ。ポリシーに違反しているリソースを検出した際に、自動的にリソースの設定（主にWeb ACLのルールに関するもの）を修正すること。また、対象リソース（ELB、EIPなど）を自動的に保護対象に加えること。参考: FMS Policy actions ↩︎
DDoS攻撃（Distributed Denial of Service attack）: 大量のコンピューターから一斉にリクエストを送り、サービスを利用不能にする攻撃手法。 ↩︎
DRT（DDoS Response Team）: AWSのDDoS対策専門チーム。Shield Advanced契約者が利用可能で、大規模攻撃時の対応支援を受けられる。参考: DRT support ↩︎
委任管理者アカウント: AWS Organizationsの管理アカウントから、特定のサービス（FMSなど）の管理権限を委任されたメンバーアカウント。管理アカウントの権限をむやみに使わず、専用の管理アカウントに役割を分離するのがベストプラクティス。
FMSの場合、Shield Advancedをサブスクライズしたアカウントを管理アカウントとみなし、この管理アカウントから、FMSを管理するアカウント（メンバーアカウント）を権限を絞って複数追加することができる。 ↩︎
L7自動緩和（Automatic application layer DDoS mitigation）: Shield Advancedの機能の1つ。アプリケーション層（レイヤー7）のDDoS攻撃パターンを自動検知し、WAF Web ACLにルールを自動追加して緩和する。参考: Shield Advanced application layer DDoS mitigation ↩︎
Retrofit existing web ACLs: FMS WAFポリシーのWeb ACL管理モードの1つ。新しいWeb ACLを作成する代わりに、リソースに既に関連付けられている既存のWeb ACLをFMSの管理下に置き、FMSポリシーのルール（First/Last Rule Groups）を注入するアプローチ。参考: FMS WAF policy ↩︎ ↩︎

スクラムマスターのAI活用を考える - 検査・適応

2026-02-25T00:00:00.000+00:00

はじめに

アジャイルグループの石田です。

第1回：導入、第2回：透明性に続く、3部作の最後となります。

第1回の導入ではスクラムガイド拡張パックとAIによる経験的プロセス制御強化の可能性について、第2回ではJira×GAS×AIによる可視化ツールの作成を通してAIによる透明性の強化について紹介しました。
今回は、スクラムの三本柱の残り2つ、検査と適応について、スクラムマスターとしてAIをどう活用するかについてです。

現在、ミーティングの録音や文字起こし、およびそれをまとめるのにAIを使うのは一般的になりつつあります。業務で生成AIを活用するにあたって、大体の会社で真っ先に使われるところでしょう。
しかし、それを単なる「議事録」として保存するだけでは非常にもったいないです。
AIを「客観的な評価者（コーチ）」として活用し、チームのプロセス改善に切り込む事例を紹介します。

なぜAIに「レトロスペクティブの評価」を任せるのか

長い間同じチームで開発を行っていると、毎回同じような議論になってしまうマンネリ化を感じたことはないでしょうか。
毎回少しずつ改善点を見つけていく重要性は分かっていても、なんとなく良かったねという話で終わってしまい改善アクションの具体性が欠けたり、ステークホルダーに対する不満や愚痴に終始してネガティブな空気になってしまうこともありがちです。

レトロスペクティブ自体を改善するプラクティスとして「ふりかえりのふりかえり」を実施しているチームも多いかと思いますが、それもやはりマンネリ化の波にはなかなか逆らえません。

そこでAIの活用方法として、感情や人間関係に左右されない客観的な評価、すなわち検査をしてもらうという使い方が考えられます。

実践：AIによるレトロスペクティブの定量評価

実践方法は比較的シンプルです。ZoomやGoogle Meetなどで取得したレトロスペクティブの文字起こしデータを、そのまま生成AIに入力します。
その入力データをもとに、事前に定義した評価基準に従って、AIにチームの議論を採点してもらいます。

評価項目は、AIと壁打ちしながら優れたレトロスペクティブのための10項目を定め、各10点の100点満点でスコアリングします。実際に作成した評価項目の例は以下の通りです。

評価項目一覧：

話題の適切性
改善アクションの具体性
会議の進行とファシリテーションの質
活発な議論
参加度と発言分布
議論の論点の着地
議論の深さ
進化の持続性
ポジティブな視点
参加メンバー間の中立性

また、スコアだけでなく次回の改善点も具体的に3つ提案してもらいます。
そうすることで、特にスコアの低い評価項目に対して、ファシリテーター以外のメンバーの発言を促す、議論が長引かないようタイムボックスを意識する、手法を変えてみるといった、具体的なアクションを提示してくれます。

こうした評価とアクションを出力させるためのプロンプト自体も、生成AIに相談しながら構築します。AIと対話しながらプロンプトを作り上げる過程は、シンギュラリティの始まりを感じられて個人的にすごく好きです。

Geminiを使用する場合は、このプロンプトをシステムプロンプト（カスタム指示）としてGemを作成しておくと便利です。

フィードバックのループを回す

これまでにレトロスペクティブの定量評価を行う準備は整いましたが、評価して終わりでは意味がありません。この結果を次回のレトロスペクティブのアクションに繋げていきます。

具体的には、次回のレトロスペクティブの冒頭で、前回算出されたAIスコアと改善提案をチームに共有します。
これにより、前回の反省（例えば、アクションが曖昧だったなど）を意識した状態で新たなレトロスペクティブをスタートできます。

こうしたフィードバックは本来スクラムマスター自身がチームを観察したうえで行うべきものですが、生成AIというパートナーの存在により、さらに客観的で説得力のあるフィードバックが可能になります。

チームに起きた適応の実例

AIによる客観的なスコアやアクションの提示によって、実際にチームに起きた適応（変化）の実例を2つ紹介します。

1つ目のケースは、ポジティブさの欠如による低スコアの例です。AIから不満や課題の指摘に終始しており、ポジティブな視点が不足しているという指摘を受けました。その適応策としてサンクスカードを導入し、意図的に感謝や良い点を伝え合う時間を設けることで、ポジティブな発言を促すようにしました。

2つ目のケースは、アクションの曖昧さによる低スコアの例です。AIからは改善案が出ているものの具体的な実行計画に落ちていないと指摘されました。これに対する適応策として、アクション決定時に「いつ、誰が、何をするか」という5W1Hの確認を徹底するルールを設けました。

応用：デイリースクラムへの展開

今回はレトロスペクティブでの検査や適応の例を紹介しましたが、もちろん他のイベントにも応用可能です。その一例として、一番効果が出やすいのはデイリースクラムかもしれません。

デイリースクラムには15分で終わるという厳格なルールがあります。もしそれより長引くようであれば、準備の不足や議論への深入り、あるいは不要な話題を話している可能性があります。
また、デイリースクラムは単なる作業報告ではなく、スプリントゴールを達成するための検査の場であるべきです。

このような毎日のイベントだからこそ、AIによる客観的な検査と適応の繰り返しが、大きな働き方の改善に繋がる可能性は高いでしょう。

まとめ：スクラムマスターのパートナーとしてのAI

本連載では、第2回で透明性（データの可視化）を確保し、第3回で検査と適応（プロセスの評価と改善）を実践するという、スクラムの三本柱を生成AIで強化する方法について紹介しました。

スクラムマスターは、チームがスクラムを正しく実施できるようにチームを観察し、この三本柱の維持に努める必要があります。

AIは、人間が気づきにくい癖や傾向を客観的に指摘する検査が得意です。一方で、その指摘を受け止め、どうチームを導くか、どう文化を作るかといった適応の部分は、スクラムマスターとチームが考えて行う必要があります。

AIを良きパートナーとして活用することで、自分たちのスクラムをより強化していくことが、今後のアジャイル開発において重要になっていくのではないでしょうか。

Vitestと統合可能！StorybookでNext.js v16のコンポーネントテストを行う前編 - 導入・基本編 -

2026-02-18T00:00:00.000+00:00

はじめに

ビジネスソリューション事業部の塚野です。
皆さんはフロントエンド開発の際にコンポーネントのテストをどのように行っているでしょうか？
自分は最近になり、Storybook というオープンソースツールに入門しました。

https://storybook.js.org

この Storybook は UI カタログを作成するサービスです。
コンポーネントをアプリ本体から切り離して単体で描画でき、Props や状態のパターンを「ストーリー」として整理ができます。
また、見た目の確認だけではなく、クリックなどのユーザーイベントを伴うコンポーネントの「ふるまい」のテストも Storybook 上で行えます。
このふるまいのテストはテストランナーに Vitest を使うことができ、他の Vitest で作成した単体テストと一緒に一括実行が可能です。

Storybook は様々なフロントエンドフレームワークに対応しています。その中で今回は人気のあるフレームワークとして Next.js でのコンポーネントテストの導入についてご紹介します。Storybook の2026年2月18日執筆時点での最新バージョンは v10.2.7 ですが、この構成を整理した情報はまだ多くないため、コンポーネントテストの作成だけでなくセットアップ手順も含めて具体例とともにまとめます。

書いているうちに長くなってしまったため、2回に分けました。
本記事では「Vitestと統合可能！StorybookでNext.js v16のコンポーネントテストを行う」の前編として、Storybook の導入と基本的な使い方、インタラクションテストの作成と Vitest テストランナーでの実行について記述します。
後編では Next.js 特有のビルトインパッケージのモックや、App Router での設定、モジュールモックなどについてご紹介します。

Storybookの導入と基本的な使い方

まずは Storybook の導入です。以下のコマンドを実行します。

npm create storybook@latest

2026年2月18日執筆時点での Storybook の最新版は v10.2.7 です。Storybook では v10 以降から Next v16 に対応しています。（が、一部未対応の機能もあります。これについては後編で触れます。）Next の必須バージョンは v14 以上です。

上記のコマンド実行後、"New to Storybook?" と聞かれます。"Yes" を選んだ場合、簡単なチュートリアルとサンプルのストーリーファイルが作成されます。必要に応じて選択してください。

その後、"What configuration should we install?" と聞かれますがここは "Recommended" を選択し、オススメ設定で実行してもらいます。設定ファイルにアドオンの追加や Vitest の設定ファイルの作成などしてくれるのでこちらを選択しましょう。

ストーリー作成の前に設定ファイルをプロジェクトに合わせて変更します。
Storybook の設定ファイルはプロジェクトルートの .storybook 配下に作成されます。（Configure Storybook | Storybook docs）
Recommended 設定の場合 .storybook 配下は以下のようになっています。

/
└── .storybook
    ├── main.ts          #Storybookのメイン設定ファイル
    ├── preview.ts       #グローバルなスタイル等の設定ファイル
    └── vitest.setup.ts  #Storybookでのvitest設定ファイル

.storybook/main.ts を以下のように変更します。

Recommended 設定の場合自動的に入っていますが、Minimum 設定の場合 "addons" に @storybook/addon-vitest と @storybook/addon-docs が追加されていることを確認してください。

main.ts

import type { StorybookConfig } from '@storybook/nextjs-vite';

const config: StorybookConfig = {
  "stories": [
    "../components/ui/**/*.stories.@(js|jsx|mjs|ts|tsx)"  // ← プロジェクトに合わせて編集する
  ],
  "addons": [
    "@chromatic-com/storybook",
    "@storybook/addon-vitest",  // ← vitestとしての実行に必要
    "@storybook/addon-a11y",
    "@storybook/addon-docs",    // ← Document機能の利用に必要
    "@storybook/addon-onboarding"   // ← チュートリアル用のアドオン。必要ないなら削除してもOK
  ],
  "framework": "@storybook/nextjs-vite",
  "staticDirs": [
    "../public"
  ]
};
export default config;

Storybook Config オブジェクトの "stories" 要素にストーリーファイルのパスを記述します。
ストーリーファイルは Button.stories.tsx のように .stories を付けて作成します。本記事でのデモプロジェクトでは components/ui 配下にコンポーネントファイルと共に作成します。プロジェクトに合わせて記述を変更してください。

Next.js プロジェクトでは tailwind CSS を利用している場合が多いかと思います。Storybookで tailwind CSS を有効化する場合は、.storybook/preview.ts で globals.css を import します。

.storybook/preview.ts

import type { Preview } from '@storybook/nextjs-vite'
import '../app/globals.css';  // ← globals.cssをimport

const preview: Preview = {
    parameters: {
    ...
    },
    tags: ["autodocs"],  // ← Document生成をすべてのStoryで有効化する
};

export default preview;

Storybook は各コンポーネントを Canvas と呼ばれる UI 上に表示させますが、内部では "preview" と呼ばれる iframe 内で動作させています。この preview に関する設定が preview.ts であり、ストーリーの表示に関するグローバルな設定が可能です。

後述する Document という機能が大変便利なので、ここですべてのストーリーで Document を生成する設定を追加します。Preview オブジェクトの tags 要素に ["autodocs"] を指定します。Document は各ストーリーファイル内で個別に有効化もできます。

これで準備ができました。

試しに以下のようなボタンコンポーネントを components/ui 配下に作成し、そのストーリーファイルを作って Storybook を実行してみます。
Props は size と variant を受け取り、variant でプリセットとして設定した primary と outline に見た目を切り替えられます。
ここでは tailwind-variants というライブラリを使い variant と size のプリセットを variants として定義しています。
コンポーネントのコードは軽く読み飛ばしていただいて大丈夫です。

components/ui/Button.tsx

import React from "react";
import { tv, type VariantProps } from "tailwind-variants";

const buttonStyles = tv({
  base: "inline-flex items-center justify-center rounded-md font-semibold transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 disabled:opacity-60 disabled:cursor-not-allowed",
  variants: {
    size: {
      small: "px-3 py-1.5 text-sm",
      medium: "px-4 py-2 text-base",
      large: "px-5 py-3 text-lg",
    },
    variant: {
      primary:
        "bg-blue-600 text-white border border-blue-600 hover:bg-blue-700 focus-visible:outline-blue-500",
      outline:
        "bg-white text-slate-900 border border-slate-300 hover:bg-slate-50 focus-visible:outline-slate-400",
    },
  },
  defaultVariants: {
    size: "medium",
    variant: "primary",
  },
});

type ButtonVariants = VariantProps<typeof buttonStyles>;

export type ButtonProps = Omit<
  React.ButtonHTMLAttributes<HTMLButtonElement>,
  "className"
> &
  ButtonVariants;

export const Button = ({
  size,
  variant,
  type = "button",
  children,
  ...props
}: ButtonProps) => {
  return (
    <button
      type={type}
      className={buttonStyles({ size, variant })}
      {...props}
    >
      {children}
    </button>
  );
};

export default Button;

このボタンコンポーネントの Story ファイルはこのように作成しました。

Button.stories.tsx

import type { Meta, StoryObj } from "@storybook/nextjs-vite";
import { fn } from "storybook/test";

import { Button } from "./Button";

const meta = {
  title: "UI/Button",
  component: Button,
  parameters: { layout: "centered" },
  argTypes: {
    size: {
      control: { type: "inline-radio" },
      options: ["small", "medium", "large"],
      description: "ボタンのサイズ",
    },
    variant: {
      control: { type: "inline-radio" },
      options: ["primary", "outline"],
      description: "ボタンのバリアント",
    },
  },
  args: {
    children: "送信",
    size: "medium",
    variant: "primary",
    onClick: fn(),
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = {};

export const Outline: Story = {
  args: { variant: "outline", size: "large", children: "キャンセル" },
};

export const Disabled: Story = {
  args: { disabled: true, children: "無効" },
};

コンポーネントの指定やどのような種類の Props を渡せるのかといったストーリーのメタ情報を meta オブジェクトに記載し、これを default export します。
この meta オブジェクトから Story の型を生成し、Story オブジェクトを作成、export します。

Story オブジェクトがそのままストーリーとして Storybook 上で表示されます。オブジェクト名がストーリの表示名、args でそのストーリーでコンポーネントに渡す Props を定義できます。

npm run storybook で Storybook を実行してみましょう。

Button コンポーネントが Canvas 内に表示されました。下の「Controls」タブでは children や Props の操作ができ、その場でコンポーネントの見た目やふるまいの確認ができます。

Controls に表示される Props は args で渡したものになります。
今回 meta オブジェクトでも args を記述しており、これがデフォルトで渡される args になります。

Props を args で記述するほかに、argTypes で Props の詳細も記述できます。
args に記載されていない Props でも argTypes へ記載した場合、 Controls タブに表示されるようになります。

また、Controls タブでの表示方法も設定でき、例えば control: { type: "inline-radio" } と記述すればユニオン型などの場合横並びのラジオボタンで値の切り替えが可能となります。（デフォルトはセレクトボックス）

Document の自動生成を有効化した場合、"Docs" というタブがサイドバーに表示されます。
ここでは作成したストーリーのメタ情報やストーリーの一覧表示などが可能で、コンポーネントの概要が一目でわかるようになっています。

ButtonコンポーネントのStory DocsでPropsなどの情報も含めたDocumentが参照できる

Documentでは作成した全ストーリーを一覧で表示可能

この Document にはマークダウン形式で文章も記述可能です。
以下のように特定の場所に JSDoc 形式でコメントを記述した場合 Document 内に表示されます。JSDoc 内ではマークダウン記法がサポートされています。

Button.stories.tsx

...

/**
 * Button コンポーネントの Storybook ストーリー
 * 
 * | variant | スタイル |
 * |---------|----------|
 * | primary | メインアクション用の強調されたスタイル |
 * | outline | 補助的なアクション用のアウトラインスタイル |
 */
const meta = {
  title: "UI/Button",
  component: Button,
  ...
}
...

ここまでの基本的な使い方でコンポーネントの「見た目」についての確認はできました。
Storybook ではさらに、クリック時の挙動などユーザーインタラクションを含む「ふるまい」のテストが行えます。

コンポーネントテストの導入

各 Story ではふるまいに関するテスト（インタラクションテスト）を "play function" として記述ができます。（Interaction tests | Storybook docs）
先ほど作った Button コンポーネントに play function を追加して「クリックすると onClick が1度だけ呼ばれること」を確認します。

Button.stories.tsx

import type { Meta, StoryObj } from "@storybook/nextjs-vite";
import { expect, fn, userEvent, within } from "storybook/test"; // ← インタラクションテストに関するパッケージから import

import { Button } from "./Button";

const meta = {
  ... ,
  args: {
    children: "送信",
    size: "medium",
    variant: "primary",
    onClick: fn(),  // ← onClick にはスパイ関数 fn() を渡す
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

...

/** play functions の例: ボタンをクリックすると onClick が1回呼ばれることを確認 */
export const ClickTest: Story = {
  args: { children: "Click Me ！" },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement);
    await userEvent.click(canvas.getByRole("button"));
    await expect(args.onClick).toHaveBeenCalledTimes(1);
  },
};

インタラクションテスト用の Story "ClickTest" を追加しました。
インタラクションテストは Story の "play" 要素に非同期関数として記述します。

ユーザーイベントの模倣やアサーションには storybook/test パッケージのオブジェクト、関数を利用します。
play 内では順に、

Canvasを取得
Canvas内 "button" 要素を取得^[1]、クリック
args の onClick が1回呼ばれるかをアサート

をしています。userEvent と expect は必ず await の内側で呼ぶ必要があります。

args の onClick では meta オブジェクトで定義されるように fn() を渡しています。
これは Vitest のスパイ関数ですが、storyboo/test パッケージから利用可能です。実行されると Story の Actions タブにイベントが出力されます。（Via storybook/test fn spies）

それでは、ClickTest ストーリーを表示してテスト結果を確認してみましょう。
ストーリーを表示すると自動でテストが実行されます。結果は Interactions タブから確認ができます。

無事、テストを Pass していることが確認できました。
すべてのインタラクションテストは Storybook の UI 上から一括実行が可能です。
サイドバー下部の "Run tests" をクリックで一括実行が行われます。"Interaction" にチェックがついていることを確認してください。

サイドバー内 Run tests からplay functions の一括実行が可能

Storybook の起動には高速起動が人気の Vite が利用可能です^[2]。
とはいえテストのたびに起動して UI 上で結果を確認するのも手間です。また、コンポーネントのテストも CI パイプライン上で他の単体テストと一括で実行したくなります。

そこで、Storybook ではインタラクションテストを Vitest のテストとして CLI 上で実行可能とするアドオン "Vitest addon" が提供されています。（Vitest addon | Storybook docs）

このアドオンにより.storiesファイルをヘッドレスブラウザ上で実行可能なテストに変換し、既存の Vitest と一緒に vitest コマンドで実行可能とします。

Storybook セットアップ時に "Recommended" 設定を選択した場合、Vitest に関する設定ファイル（vitest.config.ts、.storybook/vitest.setup.ts）が自動的に作成されます。

vitest.config.ts

import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vitest/config';
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
import { playwright } from '@vitest/browser-playwright';

const dirname =
  typeof __dirname !== 'undefined' ? __dirname : path.dirname(fileURLToPath(import.meta.url));

export default defineConfig({
  test: {
    projects: [
      {
        extends: true,
        plugins: [
          // ↓ Storybookの設定ファイルを取得、main.tsに記載したパスの.storiesファイルをテスト実行対象とする
          storybookTest({ configDir: path.join(dirname, '.storybook') }),
        ],
        test: {
          name: 'storybook',
          browser: {
            enabled: true,
            headless: true,
            provider: playwright({}),
            instances: [{ browser: 'chromium' }],
          },
          setupFiles: ['.storybook/vitest.setup.ts'],
        },
      },
    ],
  },
});

.storybook/vitest.setup.ts

import * as a11yAddonAnnotations from "@storybook/addon-a11y/preview";
import { setProjectAnnotations } from '@storybook/nextjs-vite';
import * as projectAnnotations from './preview';

// This is an important step to apply the right configuration when testing your stories.
// More info at: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations
setProjectAnnotations([a11yAddonAnnotations, projectAnnotations]);

vitest.config.ts では .stories を対象とするテストプロジェクト「storybook」が追加されています。

.test、.spec を対象とする Vitest は別のプロジェクトとして作成します。こうすることで Storybook のテストのみを対象に Vitest を実行でき、一括実行の際にはタグを分けることで Storybook のテストと関数のテストをCLI 上で区別して表示ができます。

最後に package.json へスクリプトを追加しましょう。

package.json

{
  "scripts": {
    "test": "vitest",
    "test-storybook": "vitest --project=storybook"
  }
}

"npm run test-storybook" で Stroybook のテストのみ実行可能です。
ここは既存のテストと一括実行を考えて npm run test を実行します。

$ npm run test

> storybook-demo@0.1.0 test
> vitest


 DEV  v4.0.18 /home/tsukano/storybook-demo/

3:02:47 PM [vite] (client) Re-optimizing dependencies because lockfile has changed
 ✓  storybook (chromium)  components/ui/Button.stories.tsx (4 tests) 501ms
   ✓ Default  357ms
   ✓ Outline 57ms
   ✓ Disabled 28ms
   ✓ Click Test 58ms

 Test Files  1 passed (1)
      Tests  4 passed (4)
   Start at  15:02:46
   Duration  3.84s (transform 0ms, setup 1.14s, import 49ms, tests 501ms, environment 0ms)

無事 Vitest から .stories が呼ばれテストに Pass することが確認できました。
テストの実行には Playwright を使用しています。そのため Storybook のテストは関数の UT と比べ若干実行に時間がかかります。

実際の CI パイプラインへの統合についてはこちらの公式ドキュメントを参考にしてください。（Testing in CI | Storybook docs）

おわりに

本記事では Storybook の導入と基本的な使い方、Vitest の実行についてご紹介しました。
また、基本的にローカル実行のみについて取り上げています。デプロイについては公式ドキュメントを参照してください。（Publish Storybook | Storybook docs）

次回は Next.js 固有の設定や、ルーターオブジェクトのモック、モジュールのモックなどについてご紹介します。

ちなみに、ボタン要素の取得は getByRole() で行っています。Storybook 公式ドキュメントでは要素の取得はなるべく実際の人が目で見て行う操作に近い方法で行うべきだとしています。内部の "id" などで要素を取得するのは最終手段です。（Querying the canvas） ↩︎
Next.js の場合、main.ts の "framework" 要素で Vite と webpack で利用するビルドツールを選択できます。"@storybook/nextjs-vite" を渡した場合 Vite でビルドしますが、特段の理由がない限り Vite を選択していいと思います。また、本記事の肝である Vitest も Vite を選択した場合でしか利用できません。 ↩︎

Vitestと統合可能！StorybookでNext.js v16のコンポーネントテストを行う後編 - App Routerでの設定・モジュールモック -

2026-02-18T00:00:00.000+00:00

はじめに

ビジネスソリューション事業部の塚野です。
本記事は「Vitestと統合可能！StorybookでNext.js v16のコンポーネントテストを行う」の後編です。
前編では Storybook の導入や基本的な使い方についてご紹介しました。本記事では Next.js 固有の設定やモジュールモックなどについてまとめていきます。

Next.js でページ遷移や URL の参照・更新に関わるパッケージとして next/router 、next/navigation パッケージがあります。

next/router は主に Page Router で、next/navigation は App Router で使用されます。Storybook（@storybook/nextjs-vite）では next/router パッケージはデフォルトでスタブされ、ルーターオブジェクトはActions タブにイベントを出力するモックに置き換えられます。

next/navigation も自動的にスタブされるため、 Story 上でも usePathname、 useSearchParams、 useRouter などを呼び出せます。
ただし、App Routerを使用する場合 Storybook 側に「App Router を使う」ことを明示する必要があります。Story 単位で設定できますが、プロジェクト全体が App Router 前提であれば .storybook/preview.ts に書いて全 Story に適用するのが手軽です。

.storybook/preview.ts

import type { Preview } from '@storybook/nextjs-vite';
 
const preview: Preview = {
  ...
  parameters: {
    ...
    nextjs: {
      appDirectory: true, // ← App Router を利用する場合 true とする
    },
  },
};
 
export default preview;

ここで、next/navigation パッケージを使用したコンポーネントとその Story を作成してみます。

コンポーネントのコードは読み飛ばしてかまいません。このコンポーネントでは input に入力した値を searchParams として現在の URL を書き換えます。
コンポーネント内では next/navigation パッケージの useRouter、 useSearchParams を利用しています。

NavigationDemo.tsx

'use client';

import Link from 'next/link';
import { usePathname, useRouter, useSearchParams } from 'next/navigation';
import { useState } from 'react';

export function NavigationDemo() {
  const pathname = usePathname();
  const router = useRouter();
  const searchParams = useSearchParams();
  const [query, setQuery] = useState(searchParams.get('query') ?? '');
  const [currentQuery, setCurrentQuery] = useState(searchParams.get('query') ?? '');

  const apply = () => {
    const next = new URLSearchParams(searchParams.toString());
    query ? next.set('query', query) : next.delete('query');
    const queryString = next.toString();
    router.replace(queryString ? `?${queryString}` : '?');
    setCurrentQuery(query);
  };

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} className="p-2 border border-black" />
      <button onClick={apply} className="p-2 border border-black">Apply</button>
      <Link href={`${pathname}/link?query=${query}`} className="ml-2 underline">
        go to Link
      </Link>
      <div>current path: {pathname}</div>
      <div>current query: {currentQuery || '(empty)'}</div>
    </div>
  );
};

このコンポーネントの Story は以下のように作成しました。

NavigationDemo.stories.tsx

import type { Meta, StoryObj } from '@storybook/nextjs-vite';
import { getRouter } from '@storybook/nextjs-vite/navigation.mock';   //useRouter()のMock
import { expect, userEvent, within } from 'storybook/test';

import { NavigationDemo } from './NavigationDemo';

const meta = {
  component: NavigationDemo,
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        pathname: '/demo/navigation',   //Story上でURL Pathの初期値を設定可能
        query: { query: 'initial' },    //Story上でクエリパラメータの初期値を設定可能
      },
    },
  },
} satisfies Meta<typeof NavigationDemo>;

export default meta;
type Story = StoryObj<typeof meta>;

export const ReplaceIsCalled: Story = {
  async play({ canvasElement }) {
    const c = within(canvasElement);
    getRouter().replace.mockClear();

    await userEvent.clear(await c.findByRole('textbox'));
    await userEvent.type(await c.findByRole('textbox'), 'hello');
    await expect(c.getByRole('link', { name: 'go to Link' })).toHaveAttribute(
      'href',
      '/demo/navigation/link?query=hello',
    );
    await userEvent.click(await c.findByRole('button', { name: 'Apply' }));

    //useRouter().replace呼び出しのアサートに相当
    await expect(getRouter().replace).toHaveBeenCalledWith('?query=hello');
  },
};

ここで、Story ごとに pathname や query などを変えたい場合は、meta オブジェクトのparameters.nextjs.navigation を上書きします。これにより、URL に依存するコンポーネント（アクティブ状態、検索条件の表示など）を Story 単位で再現できます。

parameters.nextjs.navigation は初期状態の再現に便利ですが、「クリックで router.push() が呼ばれた」など、呼び出しの検証をしたいケースでは不足します。

そこで使うのが @storybook/nextjs-vite/navigation.mock です。これは next/navigation のモック実装に加えて、useRouter() 相当のルーターオブジェクトを getRouter() で取り出せるため、push、 replace、 back などの呼び出しをテストとして assert できます。

このコンポーネントの Story 上で Apply ボタンを押下すると、Actions タブに入力したクエリパラメータが出力され、ルーターオブジェクトがモックできていることが分かります。

@storybook/nextjs-vite/navigation.mock 以外のビルトインモックに関してはこちらを参照してください。（Built-in mocked modules | Storybook docs）

Information

ページ遷移に関わるパッケージとして他に next/link パッケージがあります。このパッケージに含まれる Link コンポーネントは pre-fetch 機能を備えた <a> タグを拡張したコンポーネントとしてよく使われます。この Link は内部で next/navigation、next/router のルーターオブジェクトを使用しているため、これらパッケージのモックと同時に Link コンポーネントもモックされるはずです。

しかし、Next.js（15以降〜）＋ App Router 設定の Storybook では、Link コンポーネントをクリックしたときに Storybook の iframe が存在しないページへ遷移しようとするケースが報告されています。（storybookjs/storybook | GitHub）
実際、NavigationDemo 内の「go to Link」ボタンクリックでページ遷移が発生してしまいます（Storybook v10.2.7 執筆時点）。
修正されるまで、Link コンポーネントは後述するモジュールモックを用いて Storybook 上では <a> タグにモックするなどの対策が必要でしょう。

React Server Componentの利用とServer functionsのモック

App Router では、use client ディレクティブを付与して明示的に Client Component としない限り、デフォルトとして React Server Components（RSC）としてコンポーネントは扱われます。
特に、async function としている RSC についてはそのままでは Storybook で使用できません。

Storybook v10.2.7（@storybook/nextjs-vite）現在、RSC 対応は Experimental 扱いのため、RSC を Storybook 上でレンダリングする場合は明示的に機能を有効化する設定が必要です。
具体的には .storybook/main.ts で features.experimentalRSC: true を指定します。

main.ts

import type { StorybookConfig } from '@storybook/nextjs-vite';

const config: StorybookConfig = {
  framework: '@storybook/nextjs-vite',
  features: {
    experimentalRSC: true,    //RSCを利用するにはexperimentalRSC: trueとする
  },
};

export default config;

この設定で RSC を Storybook で動作させることはできます。ただしコンポーネント内で "server actions" ディレクティブを付けた、 DB 接続やファイルアクセスなどのサーバー関数を呼び出す場合これも Storybook 上では実行ができません。

Next.js でのベストプラクティスとして、 RSC 側ではデータフェッチ関数を直接記述するのではなく、呼び出すサーバー関数を別モジュールに切り出すことが知られています。

Storybook ではコンポーネント内でimportするモジュールをモックできます（Mocking modules | Storybook docs）。そこでサーバー関数を利用する場合、Storybook ではモジュールごとモックをしてしまい UI 確認用の戻り値に差し替える、という形で運用します。

また、Storybook では、コンポーネント単体の表示確認や振る舞いの検証が目的であるため、実際のサーバー依存処理は実行しないようにモック化した方がよいです。

Storybook v10.2 では、Vite/webpack 環境での推奨手段として sb.mock() によるモジュールモックが用意されています。

モジュールモックの例として、以下のようなサーバー関数getGreeting.tsを用意しました。

actions/getGreeting.ts

"server actions"

export async function getGreeting(name: string) {
  // 実環境ではDBやAPIなどにアクセスする想定
  return `Hello, ${name}!`;
}

この関数をモックする場合、.storybook/preview.ts にモックを登録します。各 Story 内ではモックの登録はできません。
これにより、Story 実行前に対象モジュールが置き換えられ、Story 単位で戻り値だけを制御できます。

.storybook/preview.ts

import type { Preview } from '@storybook/nextjs-vite';
import { sb } from 'storybook/test';

// モック登録は preview.ts で行う
sb.mock(import('../src/server/getGreeting.ts'));

const preview: Preview = {
  parameters: {
    nextjs: { appDirectory: true },
  },
};

export default preview;

モック登録の注意点として以下があります。

Typescript を使用する場合（モックする関数が .ts の場合）、sb.mock() 内で import() を用いて記述すること
＠ のような alias の使用は不可。必ず preview.ts からの相対パスで記述すること
拡張子まで含めてパスは記述すること

この設定で getGreeting.ts は Storybook 上でモック化ができます。
ただしこの場合、Storybook 上では getGreeting.ts の機能は完全に失われます。もし、機能はそのままにスパイ関数化をしたい場合は sb.mock() の第2引数に { spy: true } を含めます。

sb.mock(import('../src/server/getGreeting.ts'), { spy: true });

それではこの関数を利用するコンポーネントと、その Story ファイルを作成し、Storybook 上でこのモック化した関数をどのように使用するのか見ていきます。

components/GreetingPanel.tsx

import { getGreeting } from '@/actions/getGreeting';

type Props = { name: string };

export async function GreetingPanel({ name }: Props) {
  const message = await getGreeting(name);

  return (
    <div>
      <h3>Greeting</h3>
      <p>{message}</p>
    </div>
  );
}

簡単な、getGreeting でメッセージを取得しそれを表示するだけのコンポーネントです。

components/GreetingPanel.stories.tsx

import type { Meta, StoryObj } from '@storybook/nextjs-vite';
import { expect, mocked } from 'storybook/test';
import { within } from 'storybook/test';

import { GreetingPanel } from './GreetingPanel';
import { getGreeting } from '../server/getGreeting';

const meta = {
  component: GreetingPanel,
  args: { name: 'Taro' },
} satisfies Meta<typeof GreetingPanel>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Basic: Story = {
  // beforeEach()でモック化した関数の戻り値などの設定を行う
  async beforeEach() {
    mocked(getGreeting).mockResolvedValue('Hello from mocked function!');
  },
  async play({ canvasElement }) {
    const canvas = within(canvasElement);
    await expect(getGreeting).toHaveBeenCalledWith('Taro');
    await expect(canvas.getByText('Hello from mocked function!')).toBeTruthy();
  },
};

GreetingPanel の Story を作成しました。
Story 内でモック化した関数を利用する場合、beforeEach() 内でモック化関数の戻り値などの設定を行います。
beforeEach() は各 Story で実行してもよいですし、meta 内 beforeEach 要素に記述することですべての Story に適用が可能です。

mocked() の引数に preview.ts で登録したモックしたい関数を渡し、その戻り値に対して、モックした関数が非同期関数である場合は mockResolvedValue() で戻り値を設定します。
モックした関数が同期関数である場合は mockReturnValue(value)、モック関数に対して任意の実装を行いたい場合は mockImplementation(fn) を利用してください。

まとめ

ここまで Vitest アドオンを利用したコンポーネントテストやモジュールモックなどを利用した Next.js コンポーネントのテストをご紹介しました。
Storybook ではさらにアドオンを使うことで Visual Regression Test（VRT）やアクセシビリティのテストなども実行可能です。

学習コストは若干感じるものの、CI パイプラインへの統合が可能なことや、デプロイすることでデザイナーとイメージアップに利用できるため、使いこなせればフロントエンド開発において欠かせないツールになると感じました。
Storybook は Next.js だけでなく Vue.js や Angular など幅広いフレームワークに対応しています。ご興味持たれた方は是非導入検討してみてはいかがでしょうか。

初心者も挑戦！3D Gaussian Splattingで作るリアル3Dモデリング入門

2026-02-13T00:00:00.000+00:00

こんな人におすすめ

3Dスキャン、特に動画像を用いた3次元物体・空間の再構成技術に興味がある
お気に入りのコレクションや景色をデジタルで保存したい
お金をかけずにリアルな3Dモデルを作成したい

はじめに

弊社はモデリング技術に力を入れている会社です。
システム設計においては主にUMLを有効活用してシステムをモデル化し、全体を客観的に俯瞰することを得意としています。ここでは、弊社でよく使われている「システム全体を俯瞰する」目的とは異なり、「実世界をデジタル空間にそっくり再現する」ことを目的としたモデル化(3次元再構成技術)について解説します。

3次元再構成はどこで使われているか

例としては以下のようなものが挙げられます。

現実世界に忠実なデジタル空間シミュレーション
- 例：自動運転
VRデバイスを用いた没入体験型コンテンツ
- 例：VRchat with MetaQuest3
建築物や遺跡などを歴史的資料として保存(デジタルアーカイブ)
- 例：首里城復元

使用するアプリケーション

動作環境・スペック

OS : Windows 11 Home 25H2
CPU : Intel Core i7-11700K
RAM : 64GB (DDR4-3200, より少ないRAMでも動作可能)
GPU : NVIDIA GeForce RTX 4060Ti（VRAM 16GB版を使用, LichtFeldStudioがVRAM 8GB以上推奨）
CUDA Toolkit : 12.1 (LichtFeldStudioが12.8以上推奨だが、このバージョンでも動作することを確認)

3D Gaussian Splatting (3DGS) とは

2023年に提案された3次元再構成技術^[1]で、大量の3次元ガウス分布で3Dモデルを構成します。
従来の3次元表現方法よりも透明物体や光沢(鏡面反射)のある物体の表現能力が高く、かつ描画が軽量です。この技術における3次元ガウス分布の概要について以下の図に示しています。一言で簡単に説明すると 「視点(どこから見るか)によって色が変わる半透明の楕円体」 です。

楕円体といえば、ラグビーボールやアーモンドチョコみたいな形を想像される方も多いでしょう。スケールの制約が特に無ければ、縦横の比率によっては針のようにも見えます。一般的には半透明であるため、靄(もや)のイメージが近いかもしれません。このように楕円体に「不透明度」を設けることで、ガラスなどの半透明物体や光の分布をリアルに再現できます。

また、視点によって色が変わることはまさに3DGSのキーとなる点で、今まで表現が難しかった光沢の再現をも可能としています。この表現技術には、球面調和関数(Spherical Harmonics, SH)という特殊関数が用いられています。

こうした性質を持った楕円体を空間に大量に配置することで、物体・空間を表現します。
どのように配置するかは、表現したい物体・空間を撮影した動画像をもとに決定されます。

ワークフロー

撮影：対象(物体・空間)の写真を撮影する
点群作成：撮影した写真から、点で表現されたおおまかな3次元形状(点群)を計算する
3DGS作成：作成した点群をもとに3DGSを計算する(点群を「骨」とすると「肉付け」のイメージ)
編集：作成した3DGSを編集して仕上げる

1. 撮影

以下のような花束を対象物とします。
撮り方のコツは対象物の全周を上下のアングルで隈なく撮影することです。
最終的な3DGSの解像度を上げたければ近距離や光学ズームで撮影した画像を含めるのもよいです。
今回の撮影枚数は全部で204枚となりました。

撮影条件は以下としました。

カメラ：iPhone16 Pro
焦点距離：24mm(固定)
解像度：24MP(2400万画素)
露出：0.0(デフォルト設定)
フラッシュ：なし(室内照明のみ)

豆知識

焦点距離や解像度が異なる画像を混ぜてもOKです。

2. 点群作成

Structure from Motion(以下 SfM)という手法を用いて、撮影した画像から元の3次元物体・空間を再構成していきます。これは各画像の特徴点を抽出し、画像間でマッチングをすることで3次元空間内のどの位置に何があるかを推定する技術です。この処理のアウトプットとして、RGB情報を持つ3次元点群が出力されます。SfMを利用できるアプリケーションは様々ありますが、今回は簡単に実行できるOSSのCOLMAPを使用します。またCOLMAPの詳細設定に詳しくは触れず、基本的にデフォルト値を用いるものとします。

COLMAPの最新版をダウンロードし、解凍(執筆時の最新版は3.13.0)
解凍したフォルダ内の"COLMAP.bat"をクリックするとCOLMAPのGUI画面が立ち上がる

左上メニューの"File" -> "New project"を選択し、プロジェクトを新規作成する
データベースファイルのパスと点群の元となる画像が格納されたディレクトリのパスを設定し、保存する(①～③の順で実施)

左上メニューの"Processing" -> "Feature extraction"から以下の項目(①,②)を実施後、"Extract"(③)で各画像の特徴点を抽出する(今回はデフォルト設定)

処理完了("Extracting..."のダイアログが出なくなる)まで待機する
左上メニューの"Processing" -> "Feature matching"から設定を実施後、"Run"(②)で画像間の特徴点マッチングを実行する(今回はデフォルト設定)

処理完了("Matching..."のダイアログが出なくなる)まで待機する
左上メニューの"Reconstruction" -> "Start reconstruction"を選択し、特徴点マッチング結果からRGB情報を持つ3次元点群を生成する

左上メニューの"Extras" -> "Undistortion"を選択し、カメラレンズによる歪みを除去した画像を生成する
- "Select folder"から出力を保存するフォルダを作成・指定しておくこと
- ここでは入力画像と同じ階層に"dense"という名前のフォルダを作成する

処理完了("Undistorting..."のダイアログが出なくなる)まで待機する
作成・指定したフォルダ内に出力画像等が生成されていれば完了

3. 3DGS作成

いよいよメイン工程です。COLMAPで作成した3次元点群や歪み補正した画像を用いて3DGSを作成していきます。本工程ではOSSのLichtFeldStudioを使用します。LichtFeldStudioについてもCOLMAPと同様、設定可能なパラメータは数多いですが、今回は詳細設定に詳しく触れず、基本的にデフォルト値を用いるものとします。

LichtFeldStudioの最新版をダウンロードし、解凍(執筆時の最新版は0.41)
解凍したフォルダ内の"bin -> LichtFeld-Studio.exe"をクリックするとGUI画面が立ち上がる
- 中央のプルダウンから言語を日本語などに変更可能

アプリケーションウィンドウ内の任意の場所をクリックすると、以下のように画面が切り替わる

COLMAPの出力(今回は"dense")をフォルダごとドラッグ&ドロップすると、以下の画面が表示されるため、Outputの場所を確認し、"Load"ボタンを押す

COLMAPで生成した3次元点群と画像の位置・向きを表現した視錐台(Frustum)が表示される

ウインドウ右の"Training"タブをクリックし設定パラメータを確認後、"Start Training"を押す
以下に主要な設定パラメータを示しています。
- Iterations：繰り返し計算の回数
- Max Gaussians：3次元ガウス分布の最大個数
- SH Degree：球面調和関数の次数(小さいほどパラメータ数が減る)
いずれも数値が大きいほど高品質のものができやすい反面計算量が多くなるため、その他の設定パラメータも含め、試行錯誤が必要な場合があります。

以下はトレーニング中の様子。
- COLMAPの点群を初期値として、点(=3次元ガウス分布の中心)の数を増やしたり、移動させたりしている(10倍速、点群表示モード)
- 各点を中心とした3次元ガウス分布を生成し、パラメータを調整している(10倍速)

"Training Complete"のダイアログが表示されるまで待機する

"File" -> "Export..."を選択し、作成した3DGSをファイルに保存できれば完了

4. 編集

作成した3DGSをキレイに仕上げていくフェーズです。
特に手を加えなくても3DGSの品質が十分と判断した場合は省略してもOKです。
ただ一般的には背景の解像度が低かったり、対象物の周囲などに意図していないモヤのようなもの(フローター)が浮かんでいることが多いため、それらを処理すると3DGSの見栄えがさらに良くなります。また、レンダリング速度の向上やファイルサイズの軽量化にもつながります。このような3DGSの編集にSuperSplatを使用します。

SuperSplatにアクセスする

SuperSplatを表示したブラウザ画面に、作成した3DGSファイルをドラッグ&ドロップしてインポートする

インポートした3DGSを編集する
- 原点位置と座標系の向きを変更する
  インポート時にはワールド座標系の原点が意図しない位置・向きになっていることが多く、編集の際に不便となることがあります。そこでまず並進移動と回転のツールを用いて対象物とワールド座標系の位置・向きを合わせます。
- 対象物の背景を領域選択して削除する
- 不要なガウス分布を個別に選択して削除する
編集した3DGSを保存する

おわりに

今回は3次元物体・空間をデジタルでリアルに再構成する技術である3DGSを、無料かつ高解像度で作成する手順に焦点を当てました。今後は技術的な深堀や3DGSの課題、最新研究を解説していきたいと思います。

おまけ

本編におけるアプリケーションは今のところすべて無料ですが、環境構築の手間とGPUが必須のため、お手軽かと言われると微妙なところなのが正直なご感想かと思います。そこで他の選択肢も用意しました。

有料でもいいからもっと簡単に作りたいなら...Postshot
スマホだけでお手軽にササッと作りたいなら...Scaniverse

	手軽さ	表現できる解像度	パラメータ自由度	GPU	備考
COLMAP+LFS	△	〇~◎	◎	必須	無料、細かなチューニングができる
Postshot	〇	〇~◎	〇	必須	有料、高品質な3DGSが簡単に作成可能
Scaniverse	◎	△~〇	△	不要	無料、スマホのみで作成可能

ただし今回ご紹介したLichtFeldStudioは、本記事を執筆した2026年1月現在開発が盛んに行われており、手軽さや機能の向上が今後見込まれます。

3D Gaussian Splatting for Real-Time Radiance Field Rendering ↩︎

DJIドローン開発Tips - カスタムウィジェットの紹介

2026-02-12T00:00:00.000+00:00

はじめに

豆蔵では太陽光発電パネルの清掃ロボットシステムの開発に取り組んでいます。

本システムは、太陽光発電パネルを清掃するロボットと、それを搬送するドローンで構成されています。本記事では、ドローン側の開発に用いる Payload SDK を使って、送信機にカスタムウィジェットを表示する方法を紹介します。

Payload SDK の概要は以下の記事でも紹介しています。あわせて参照してください。

https://developer.mamezou-tech.com/robotics/solar-panel-clean-robot/dji-drone-psdk-introduction/

カスタムウィジェットとは

ペイロードデバイスを機体に搭載して使う場合、ユーザーがペイロードに対して操作指示を出したり、状態を確認したりしたい場面は多いでしょう。

DJI のドローンシステムでは、UI として DJI 製の送信機（DJI Pilot 2 が動作）や Mobile SDK で開発したアプリケーションが使われます。

カスタムウィジェットは、これらの UI に独自のウィジェットを組み込むための仕組みです。

送信機を使う場合のシステム構成のイメージは以下のとおりです。

サードパーティ製のペイロードデバイスの SBC 内のアプリケーションが Payload SDK を介してウィジェットの定義を機体へ提供します。
送信機内で動作する DJI Pilot 2 は機体から自動でウィジェットの定義を取得し、UI へウィジェットを表示します。

本記事では、DJI のチュートリアルをベースに、カスタムウィジェットでできることを紹介していきます。

カスタムウィジェットのサンプルコードによるデモ

Payload SDK のリポジトリには、SDK の各機能ごとにサンプルコードが含まれています。

カスタムウィジェットのサンプルコードは次のパスにあります。

Payload-SDK/samples/sample_c/module_sample/widget/

以下はサンプルコードを実行したときのデモ動画です。

DJI Pilot 2 のカメラビュー左側のメインメニューに「PSDK」が追加されています。

右上の設定ボタンを押すと、右側の設定メニューにも「PSDK」が表示されます。

サンプルではウィジェット操作時のコールバックがモック実装のため、ボタン押下時の実際の動作はありませんが、UI がどのように拡張されるかはイメージしやすいと思います。

カスタムウィジェットのファイル構成

サンプルディレクトリ（Payload-SDK/samples/sample_c/module_sample/widget/）のファイル構成は以下のとおりです。

├── test_widget.c
├── test_widget.h
└── widget_file
    ├── cn_big_screen
    │   ├── icon_button1.png
    │   ├── icon_button2.png
    │   ├── icon_list_item1.png
    │   ├── icon_list_item2.png
    │   ├── icon_scale.png
    │   ├── icon_switch_select.png
    │   ├── icon_switch_unselect.png
    │   └── widget_config.json
    └── en_big_screen
        ├── icon_button1.png
        ├── icon_button2.png
        ├── icon_list_item1.png
        ├── icon_list_item2.png
        ├── icon_scale.png
        ├── icon_switch_select.png
        ├── icon_switch_unselect.png
        └── widget_config.json

widget_config.json がカスタムウィジェットの定義ファイルで、PNG ファイルがアイコンとして使われます。

UI の言語ごとにディレクトリが分かれており、中国語向けが cn_big_screen、英語向けが en_big_screen です。送信機の言語設定に応じて、参照されるディレクトリが切り替わります。

すべての言語向けに定義を作る必要はなく、デフォルトのディレクトリを指定できます。サンプルでは en_big_screen をデフォルトとしており、前述のデモでは送信機が日本語設定だったため en_big_screen が参照されていました。

test_widget.c には、SDK から呼ばれるコールバック用のハンドラが実装されています。ハンドラ内で、ボタン押下時の処理や UI に表示する値を返す処理を記述します。

カスタムウィジェットの初期化処理の流れ

サンプルアプリケーションを起動すると、各機能用のコンソールメニューが表示されます。カスタムウィジェットは、起動後に自動で機体へアップロードされ、DJI Pilot 2 に表示されます。

0.016	            core	[Info]	               dji_core.c:113  Payload SDK Version : V3.15.0-beta.0-build.2318 Dec 10 2025 17:27:05
1.075	         adapter	[Info]	     dji_access_adapter.c:351  Identify mount position type is Extension Port Type
1.075	         adapter	[Info]	     dji_access_adapter.c:371  Identify aircraft series is Matrice 4 Series
1.578	         adapter	[Info]	     dji_access_adapter.c:493  Identity uart0 baudrate is 921600 bps
1.582	            core	[Info]	    dji_identity_verify.c:627  Updating dji sdk policy file...
...(omit)
12.455	            core	[Info]	               dji_core.c:328  Start dji sdk application
12.455	            user	[Info]	          application.cpp:372  Application start.

| Available commands:                                                                              |
| [0] Fc subscribe sample - subscribe quaternion and gps data                                      |
| [1] Flight controller sample - you can control flying by PSDK                                    |
| [2] Hms info manager sample - get health manger system info by language                          |
| [a] Gimbal manager sample - you can control gimbal by PSDK                                       |
| [c] Camera stream view sample - display the camera video stream                                  |
| [d] Stereo vision view sample - display the stereo image                                         |
| [e] Run camera manager sample - you can test camera's functions interactively                    |
| [f] Start rtk positioning sample - you can receive rtk rtcm data when rtk signal is ok           |
| [g] Request Lidar data sample - Request Lidar data and store the point cloud data as pcd files   |
| [h] Request Radar data sample - Request radar data                                               |
| [l] Run widget states manager sample, control widget states on other payload                     |

以下は、SDK の初期化処理（抜粋）です。

Payload-SDK/samples/sample_c++/platform/linux/raspberry_pi/application/application.cpp

void Application::DjiUser_ApplicationStart()
{
    ...(omit)

    returnCode = DjiCore_SetAlias("PSDK_APPALIAS");  // ペイロード名（UI表示用）
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("Set alias error.");
    }

    ...(omit)

    returnCode = DjiTest_WidgetStartService();  // ウィジェットサービス開始
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        USER_LOG_ERROR("widget sample init error");
    }

DjiCore_SetAlias で指定した PSDK_APPALIAS は、ペイロードデバイス名として UI に表示されます。DjiTest_WidgetStartService は、前述の test_widget.c で定義されている関数です。

以下は DjiTest_WidgetStartService の抜粋です。widget_file のディレクトリパスを SDK に設定し、各ウィジェットの操作時コールバックと表示値を返すコールバックのハンドラを登録しています。s_widgetHandlerList のインデックス 0〜8 は、widget_config.json で定義した各ウィジェットの widget_index と対応します。

Payload-SDK/samples/sample_c/module_sample/widget/test_widget.c

static const T_DjiWidgetHandlerListItem s_widgetHandlerList[] = {
    {0, DJI_WIDGET_TYPE_BUTTON,        DjiTestWidget_SetWidgetValue, DjiTestWidget_GetWidgetValue, NULL},
    {1, DJI_WIDGET_TYPE_LIST,          DjiTestWidget_SetWidgetValue, DjiTestWidget_GetWidgetValue, NULL},
    {2, DJI_WIDGET_TYPE_SWITCH,        DjiTestWidget_SetWidgetValue, DjiTestWidget_GetWidgetValue, NULL},
    {3, DJI_WIDGET_TYPE_SCALE,         DjiTestWidget_SetWidgetValue, DjiTestWidget_GetWidgetValue, NULL},
    {4, DJI_WIDGET_TYPE_BUTTON,        DjiTestWidget_SetWidgetValue, DjiTestWidget_GetWidgetValue, NULL},
    {5, DJI_WIDGET_TYPE_SCALE,         DjiTestWidget_SetWidgetValue, DjiTestWidget_GetWidgetValue, NULL},
    {6, DJI_WIDGET_TYPE_INT_INPUT_BOX, DjiTestWidget_SetWidgetValue, DjiTestWidget_GetWidgetValue, NULL},
    {7, DJI_WIDGET_TYPE_SWITCH,        DjiTestWidget_SetWidgetValue, DjiTestWidget_GetWidgetValue, NULL},
    {8, DJI_WIDGET_TYPE_LIST,          DjiTestWidget_SetWidgetValue, DjiTestWidget_GetWidgetValue, NULL},
};

...(omit)

T_DjiReturnCode DjiTest_WidgetStartService(void)
{
    T_DjiReturnCode djiStat;
    T_DjiOsalHandler *osalHandler = DjiPlatform_GetOsalHandler();

    //Step 1 : Init DJI Widget
    djiStat = DjiWidget_Init();
    if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        USER_LOG_ERROR("Dji test widget init error, stat = 0x%08llX", djiStat);
        return djiStat;
    }

    ...(omit)

    //set default ui config path
    djiStat = DjiWidget_RegDefaultUiConfigByDirPath(tempPath);
    if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        USER_LOG_ERROR("Add default widget ui config error, stat = 0x%08llX", djiStat);
        return djiStat;
    }

    //set ui config for English language
    djiStat = DjiWidget_RegUiConfigByDirPath(DJI_MOBILE_APP_LANGUAGE_ENGLISH,
                                             DJI_MOBILE_APP_SCREEN_TYPE_BIG_SCREEN,
                                             tempPath);
    if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        USER_LOG_ERROR("Add widget ui config error, stat = 0x%08llX", djiStat);
        return djiStat;
    }

    //set ui config for Chinese language
    djiStat = DjiWidget_RegUiConfigByDirPath(DJI_MOBILE_APP_LANGUAGE_CHINESE,
                                                DJI_MOBILE_APP_SCREEN_TYPE_BIG_SCREEN,
                                                tempPath);
    if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        USER_LOG_ERROR("Add widget ui config error, stat = 0x%08llX", djiStat);
        return djiStat;
    }

    //Step 3 : Set widget handler list
    djiStat = DjiWidget_RegHandlerList(s_widgetHandlerList, s_widgetHandlerListCount);
    if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        USER_LOG_ERROR("Set widget handler list error, stat = 0x%08llX", djiStat);
        return djiStat;
    }

言語設定の識別子（DJI_MOBILE_APP_LANGUAGE_ENGLISH など）は dji_typedef.h に定義されています。

/**
 * @brief Mobile APP system language.
 */
typedef enum {
    DJI_MOBILE_APP_LANGUAGE_UNKNOWN             = 255, /*!< The system language of the mobile app is unknown */
    DJI_MOBILE_APP_LANGUAGE_ENGLISH             = 0, /*!< The system language of the mobile app is English */
    DJI_MOBILE_APP_LANGUAGE_CHINESE             = 1, /*!< The system language of the mobile app is Chinese */
    DJI_MOBILE_APP_LANGUAGE_JAPANESE            = 2, /*!< The system language of the mobile app is Japanese */
    DJI_MOBILE_APP_LANGUAGE_FRENCH              = 3, /*!< The system language of the mobile app is French */
} E_DjiMobileAppLanguage;

サンプルでは日本語（DJI_MOBILE_APP_LANGUAGE_JAPANESE）用の UI 設定を登録していません。そのため、送信機が日本語のときは DjiWidget_RegDefaultUiConfigByDirPath で登録したデフォルト（en_big_screen）が参照されます。これが前節で述べた「デフォルトのディレクトリ」の挙動です。

次に、ハンドラの実装を見てみましょう。

static T_DjiReturnCode DjiTestWidget_SetWidgetValue(E_DjiWidgetType widgetType, uint32_t index, int32_t value,
                                                    void *userData)
{
    s_widgetValueList[index] = value;
    return DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS;
}

static T_DjiReturnCode DjiTestWidget_GetWidgetValue(E_DjiWidgetType widgetType, uint32_t index, int32_t *value,
                                                    void *userData)
{
    *value = s_widgetValueList[index];
    return DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS;
}

s_widgetValueList は、ウィジェットのインデックスを添字とする配列です。UI でウィジェットを操作すると DjiTestWidget_SetWidgetValue が呼ばれ、操作に対応する値が value として渡されます。DjiTestWidget_GetWidgetValue は周期的に呼ばれ、ウィジェットの状態を value で返します。

サンプルでは SetWidgetValue で受け取った値を保持し、GetWidgetValue でそのまま返しているだけです。そのため、スイッチの ON/OFF 操作で表示が即座に切り替わります。

たとえば、スイッチの ON 操作で外部機器を制御する場合、機器の状態が変わるまでは表示を OFF にしておきたいときがあります。そのときは GetWidgetValue で実際の機器状態に応じた値を返すとよいでしょう。

DjiCore へのウィジェットファイル・ハンドラの登録、およびウィジェット操作時・状態取得（周期呼び出し）時のコールバックの流れは次のとおりです。アプリケーション側の開発対象は、エントリポイントとウィジェットハンドラです。

sequenceDiagram
  participant App as エントリポイント
  participant Core as DjiCore
  participant Handler as ウィジェットハンドラ

  Note over App,Handler: 初期化時
  App->>Core: DjiWidget_Init()
  App->>Core: DjiWidget_RegUiConfigByDirPath()<br/>（widget ファイル登録）
  App->>Core: DjiWidget_RegHandlerList()<br/>（ハンドラ登録）
  Note over Core: 登録完了

  Note over Core,Handler: 実行時（ウィジェット操作時）
  Core->>Handler: SetWidgetValue コールバック<br/>（例: DjiTestWidget_SetWidgetValue）
  Handler-->>Core: 結果

  Note over Core,Handler: 実行時（状態取得・周期的）
  Core->>Handler: GetWidgetValue コールバック<br/>（例: DjiTestWidget_GetWidgetValue）
  Handler-->>Core: 状態値（value）

widget_config.json の解説

本節では、サンプルアプリの widget_config.json を例に、定義ファイルの構成を説明します。詳細は Payload SDK チュートリアル（Custom Widget）を参照してください。

トップレベルの構成

version … 設定フォーマットのバージョン（major / minor）。
ar_config … チュートリアルおよび API 仕様に記載がないため、本記事では説明を省略する。
main_interface … メインメニューに表示するウィジェットの定義。
config_interface … 設定メニューに表示するウィジェットの定義。

main_interface

メインメニュー用の設定です。floating_window（フローティング画面の表示有無）と speaker（TTS／音声）のほか、widget_list でウィジェットを並べます。サンプルでは widget_index 0〜3 の 4 つ（Button, List, Switch, Scale）を定義しています。

メニュー上部に表示されるペイロードデバイス名は、前述の DjiCore_SetAlias で設定した文字列です。

config_interface

設定メニュー用の設定です。text_input_box（テキスト入力の有無やプレースホルダー）と widget_list でウィジェットを定義します。サンプルでは widget_index 4〜8 の 5 つ（Button／Scale／Integer Input Box／Switch／List）を定義しています。

widget_list の各要素

各ウィジェットは少なくとも次のプロパティを持ちます。

プロパティ	説明
widget_index	ウィジェットのインデックス。ハンドラ登録時の `s_widgetHandlerList` のインデックスと対応し、コールバックでどのウィジェットかを識別するために使います。
widget_type	ウィジェット種別。`button`・`list`・`switch`・`scale`・`int_input_box` の 5 種類があります。
widget_name	UI に表示する名前。

このほか、種別に応じて次のプロパティを指定できます。

ウィジェット種別	追加プロパティ	説明
button	`icon_file_set`	`icon_file_name_selected` と `icon_file_name_unselected` に PNG ファイル名を指定。GetWidgetValue が返す value が 1 のとき選択時、0 のとき非選択時のアイコンが表示される。同一ディレクトリを参照。
list	`list_item`	配列で各項目の `item_name` を指定。各項目に `icon_file_set` を指定可能。
switch	`icon_file_set`	button と同様。
scale	`icon_file_set`、`customize_rc_buttons_config`	アイコンは button と同様。`button_value_step_length` で送信機ボタン操作時のステップ幅を指定。
int_input_box	`int_input_box_hint`	単位などのヒント文字列（例: `"unit:s"`）を指定。

アイコン仕様

DJI Pilot 用のカスタムウィジェットでは、アイコンに次のデザイン仕様が推奨されています。

サイズ・フレーム

項目	推奨値
アイコン標準サイズ	96px
ボトムフレーム（サイズ）	80px
ボトムフレーム（背景色）	#000000（黒）
ボトムフレーム（不透明度）	0.6（アルファ。0＝完全透明、1＝完全不透明。約 60% の不透明度で半透明）
ボトムフレーム（ブラー）	4（枠のぼかし強さ。エッジが柔らかく表示される）
円形要素のストローク（線の太さ）	4px 程度

ボトムフレームは、仕様で示されているアイコン表示用の枠です。

表示状態と色

アイコンは表示状態に応じて次の色で表現します。icon_file_name_selected / icon_file_name_unselected および GetWidgetValue コールバックが返す value に対応します。

状態	色（HEX）	説明
Normal（非選択）	#4E4E4E	非選択時（value が 0 のとき）
Active（選択）	#1FA3F6	選択時（value が 1 のとき）
Disable	#BCBCBC	無効時

補足

上記の表は UI アイコン仕様全般の記載と考えられます。カスタムウィジェットでは widget_config.json で指定できるのは 2 種類のみです。icon_file_name_selected と icon_file_name_unselected です。Disable 用を SDK に渡す仕組みはありません。Normal と Active に従い、2 種類のアイコンを用意すれば十分です。

形式・レイアウト

アイコン形式は PNG を使用する。
表示領域サイズの例は 48×48、56×56、40×56、56×40 など。実コンテンツを中央に収め、余白を適切にすることが推奨されている。

Sketch 用テンプレート（psdk_widget.sketch）が DJI から提供されています。アイコン作成時は、これをベースにすることを推奨します。

まとめ

本記事では、送信機の UI をペイロード用に拡張するカスタムウィジェットの仕組みと、定義ファイル（widget_config.json）およびハンドラ登録による実装の流れを紹介しました。

Payload SDK を用いたカスタムペイロードの開発事例はまだ多くなく、チュートリアルだけでは情報が限られるため、「どのような UI が作れるか」が分かりにくい状況にあります。本記事が、ペイロードデバイスを開発しようとしている方の参考になれば幸いです。

無料のOSSツールSysONで始めるSysMLv2モデリング（６）〜 ActionFlowの作成

2026-02-12T00:00:00.000+00:00

前回の記事では、Action Definitionと Action Usageを作成しました。

/blogs/2026/02/05/sysmlv2-tool-syson-action/

本記事ではそれらを用いて ActionFlowを作成します。

SysMLv2には標準で Action間の接続を表示するための ActionFlowViewが用意されています。
ActionFlowを作成するにはこの ActionFlowViewを使うのが順当でしょう。
しかし、SysONのドキュメントにある Action Flow Viewのページには「開発中（under development）」とあります。
この連載で使用してきた v2025.8.0はもちろん、執筆時点の最新版である mainでも同様でした。

そこで今回は、要素の Graphical Compartmentに ActionFlowを作成します。
Graphical Compartmentは、Partや Actionの枠内にグラフィカルなビューを表示する区画のことです。

本記事では、主に作成の流れをご紹介します。
要素の追加方法といった操作方法については、本連載のこれまでの記事を参照してください。

Action Flowを作成する（その１）

"Introduction to the SysML v2 Language Textual Notation" スライド30の図を作成してみましょう。

General Viewを開き、Action Definitionを３つ作成します。
作成した Action Definitionの名前をそれぞれ、"Focus", "Shoot", "TakePicture"に変更します。

"TakePicture"に入力と出力の Itemを１つずつ追加します。
入力 Itemの名前を"scene : Scene"に、出力 Itemの名前を"picture : Picture"に変更します。

"TakePicture"のManage Visibilityコンテキストメニューを表示し、"action flow"のチェックをONにします。
これにより、"TakePicture"に Action Flow Viewを表示する Graphical Compartmentが表示されます。

"TakePicture"にある action flowの区画を右クリックし、コンテキストメニューから Action Usageを２つ作成します。
作成した Action Usageの名前をそれぞれ"focus : Focus"と"shoot : Shoot"に変更します。

Action Usageの"focus"に入力 Itemと出力 Itemを１つずつ追加します。
入力 Itemの名前を"scene"、出力 Itemの名前を"image"に変更します。

同じように、Action Usageの"shoot"に入力と出力の Itemを１つずつ追加します。
入力 Itemと出力 Itemの名前をそれぞれ"image"と"picture"に変更します。

"TakePicture"の入力 Itemである"scene"を選択します。
その外側に表示される"＞"をドラッグし"focus"の入力 Itemでドロップすると、接続の種別を選択するメニューが表示されます。
メニューで"New Binding Connector As Usage (bind)"を選択してください。

２つの Item間を結ぶ線（コネクタ）が追加されます。
また、このコネクタの近傍に"="が表示されます。
これが Binding Connectionです。

Action Usage"shoot"の出力 Itemと"TakePicture"の出力 Itemである"picture"も同様にコネクタでつなぎましょう。

"focus"の出力 Itemと"shoot"の入力 Itemをつなぎます。
この場合もドラッグ＆ドロップで接続の種別を選択するメニューを出しますが、今度はメニューから"New Flow (flow)"を選択します。

片側に矢印の付いた線が追加されます。
これが flow connectionです。

不要な要素を非表示にすれば作図終了です。

Action Flowを作成する（その２）

今回は、もう１つ作図してみます。

"Intro to the SysML v2 Language-Graphical Notation.pdf" スライド58の図です。
分岐やマージなど、いくつかの Control Nodeが使われています。

General Viewを開き、Action Usageを追加します。
追加した Action Usageの名前を"transportPassenger"に変更します。

"transportPassenger"の Manage Visibilityで"action flow"にチェックを付けます。
表示された action flowの区画に Action Usageを追加していきます。
題材にあわせて11個の Action Usageを追加し、それぞれの名前を変更します。

action flowの区画を右クリックし、表示されたコンテキストメニューの"Behavior"から必要な Control Nodeを追加します。

Decision Nodeや Marge Nodeのサイズを変更したり、Fork Nodeや Join Nodeを縦長に変更できないようです。

Control Nodeや Action Usageを選択した際、外側に表示される"＞"をドラッグ＆ドロップして、Control Nodeや Action Usageをフローで接続します。
接続する際は、コンテキストメニューから”New Transition”を選択します。

action flowの要素を配置しなおして、フローを記述するところまでは出来ました。

あとはガードを付ければ作図終了なのですが、この手順が見つかりませんでした。

テキスト記法で Action Flowを作成する

テキスト記法を用いれば、ガード条件も追加できます。

SysMLv2仕様書 p.92の表に記載されたテキスト記法を参考に以下を作成しました。
ガードはBooleanでなければならないため、attributeとして追加しました。
terminateは表示されないため、doneに変更しました。

action act {
	attribute guard1 : ScalarValues::Boolean;
	attribute guard2 : ScalarValues::Boolean;

	first start;
	then fork fork1;
		then action1;
		then action2;
	action action1;
		then join1;
	action action2;
		then join1;
	join join1;
	then decide decision1;
		if guard2 then action3;
		if guard1 then action4;
	action action3;
		then merge1;
	action action4;
		then merge1;
	merge merge1;
	then done;
}

これを SysONに読ませてオブジェクトを生成し、General Viewで表示、整形すると下図のようになります。

まとめと次回予告

SysMLv2の仕様書には他にも Action Flowの例が載っています。
また、本連載の題材にしているドキュメントにも上記の他に Action Flowが記載されています。
しかし本連載で使用した SysONでは、これらすべての Action Flowをグラフィカル記法で表現することは出来ません。
その一方、GitHubのコミットログをみると、日々 SysONの開発が進められていることがわかります。
Action Flow Viewを含め、今後のリリースに期待しましょう。

次回は、State Definitionと State Usageを作成します。
Stateもまだまだ開発中だと思いますが、どこまで出来るのか試してみましょう。

DJIドローン開発Tips - カスタムペイロードデバイスの Application Binding

2026-02-10T00:00:00.000+00:00

はじめに

豆蔵では太陽光発電パネルの清掃ロボットシステムの開発に取り組んでいます。

本システムでは太陽光発電パネルを清掃するロボットとロボットを搬送するドローンで構成されています。本記事では、ドローン側の開発技術である Payload SDK における Application Binding について紹介します。

Payload SDK については以下の記事でもご紹介していますので併せて参照して下さい。

https://developer.mamezou-tech.com/robotics/solar-panel-clean-robot/dji-drone-psdk-introduction/

Application Binding について

一部の機体ではペイロードデバイスを使用する前に Application Binding という以下の手順が必要となります。

機体とペイロードデバイスを接続し Payload SDK で開発されたアプリケーションを起動する
- Payload SDK の初期化シーケンスで機体とのバインド待ちとなる
機体とPCを接続し DJI Assistant 2 を起動する
- バインド待ちとなっているペイロードデバイスの一覧が表示される
DJI Assistant 2 で機体とペイロードデバイスをバインドする
- SDK の初期化シーケンスで機体が応答を返すようになり SDK の API を利用可能となる

バインドしたペイロードデバイスの情報は機体内に永続化され、以降は対象のペイロードデバイスを使用可能となります。

Application Binding が必要な機体

以下は、現行機体が提供している拡張ポートの一覧です。Standard Hardware Port Introduction より抜粋。

Aircraft	Port Name	Supports App Binding
FlyCart 100	E-Port Lite	–
FlyCart 30	E-Port Lite	–
Matrice 4D/4TD	E-Port, E-Port Lite	✓
Matrice 4E/4T	E-Port, E-Port Lite	✓
Matrice 3D/3TD	E-Port, E-Port Lite	–
Matrice 30/30T	E-Port	–
Mavic 3E/3T	E-Port	–
M400	E-Port V2	✓
M350 RTK	E-Port	–
M350 RTK	Gimbal Port	✓
M300 RTK	OSDK Port	–
M300 RTK	Gimbal Port	✓

Supports App Binding にチェックが入っている機体の拡張ポートに対してペイロードデバイスを接続する場合はバインドが必要です。

E-Port、E-Port V2、Gimbal Portで接続するペイロードデバイスが対象ですが、Matrice 系では
Matrice 4E/4T 以降のモデルから必要となっています。今後発売される機体では（E-Port Lite を除けば）基本的にはペイロードデバイスに対するバインドが必要になってくるものと思われます。

SDK 認証チップ

バインドするサードパーティ製のペイロードデバイスには DJI SDK 認証チップ（略称 DJI SDK CC）を取り付ける必要があります。

DJIストアから50個セットのものを購入できます。

以下の写真のパッケージングされた細長いシート状のものが購入した認証チップです。
袋の上に置いてあるのは認証チップを取り付けるためのアダプタです（後述）。

認証チップは機体とサードパーティ製ペイロードデバイス間の通信を認証・暗号化するハードウェアセキュリティモジュールです。

この認証チップにより機体側が各ペイロードデバイスを識別可能となり、バインド済のペイロードデバイスの情報（認証チップの情報）が機体内に永続化されます。

このチップはサードパーティ向けに提供されているものですが DJI製のペイロードデバイスにも同様の認証チップ或いはこれに準ずる仕組みが組み込まれているものと思います。

SDK 認証チップの接続

SDK Certified Chip Quick Start に Raspberry Pi 4B を対象とした接続例が記載されていますので、これをベースに解説致します。

SDK 認証チップのインターフェイス

認証チップは I²C インターフェースでホスト（ Raspberry Pi ）と通信します。

下図は認証チップのピン配置です。

VCC: 電源入力ピン（動作電圧範囲: 1.62 V - 5.5 V）
GND: グランドピン
NRST: 外部リセットピン
I2C_SCL: I²Cバスインターフェースピン（Serial Clock Line）
I2C_SDA: I²Cバスインターフェースピン（Serial Data Line）

チップのパッケージタイプは DFN8 2x3 です。
外径サイズが 2mm x 3mm と非常に小型であるため、これに直接配線することは困難です。
そのため、以下の写真のような DIP8 ソケットにつなげる変換アダプタを使用します。

SDK 認証チップと Raspberry Pi の接続

Raspberry Pi の 40-pin GPIO header のピンと認証チップを接続します。

認証チップと GPIO のピン対応は以下のとおりです。

認証チップ	GPIO
1pin(7816IO)	(NC)
2pin(Vcc)	1pin(3.3V power)
3pin(7816CLK)	(NC)
4pin(GND)	9pin(Ground)
5pin(I2C_SDA)	3pin(GPIO2:SDA)
6pin(NC)	(NC)
7pin(I2C_SCL)	5pin(GPIO3:SCL)
8pin(NRST)	7pin(GPIO4:GPCLK0)
9pin(GND)	9pin(Ground)

デバイスツリーで I²C を有効化した後に i2cdetect コマンドなどで I²C のアドレスが表示されればOKです。

以下の例だと認証チップに割り当たっているデバイスは /dev/i2c-1 です。

$ ls /dev/i2c-*
/dev/i2c-1  /dev/i2c-20  /dev/i2c-21

認証チップの Vcc に 3.3V が給電されただけでは反応しません。

$ sudo i2cdetect -y 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:                         -- -- -- -- -- -- -- -- 
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
70: -- -- -- -- -- -- -- --

以下のように GPIO4（認証チップの NRST と接続）を LOW にして HIGH にすると認証チップがリセットされ、I²C アドレス 0x2a が検出されます。

$ sudo gpioset gpiochip0 4=0
$ sudo i2cdetect -y 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:                         -- -- -- -- -- -- -- -- 
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
70: -- -- -- -- -- -- -- --                         

$ sudo gpioset gpiochip0 4=1
$ sudo i2cdetect -y 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:                         -- -- -- -- -- -- -- -- 
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
20: -- -- -- -- -- -- -- -- -- -- 2a -- -- -- -- -- 
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
70: -- -- -- -- -- -- -- --

DJIのデベロッパーセンターで Payload SDK アプリケーションを登録する

バインドする前に Payload SDK アプリケーションを DJIのデベロッパーセンターで登録する必要があります。

アプリケーションの情報を入力します。

アプリケーションの登録後に Send Email を押下するとアクティベーションのインビテーションメールが送信されます。

メールのリンク先を開くとアクティベーションが完了し ID や KEY が表示されます。

ページに記載されている通り、登録したアプリケーションに対してバインドできるペイロードデバイスは最大で20台までです。

Application Verification のページで会社の説明やペイロードデバイスのテストレポートなど様々な書類を用意して審査が完了すると、台数の制約が解除されます。開発初期にはこの台数の制約は問題になりませんが、ペイロードデバイスを量産するフェーズではテストレポートを用意して申請しましょう。

Payload SDK アプリケーションの設定

ここでは Payload SDK の Raspberry Pi 向けのサンプルアプリケーションを例にして SDK への設定内容を説明します。

DJIのデベロッパーセンターで登録したアプリケーション情報を以下のファイルへ設定します。

Payload-SDK/samples/sample_c++/platform/linux/raspberry_pi/application/dji_sdk_app_info.h

/* Exported constants --------------------------------------------------------*/
// ATTENTION: User must goto https://developer.dji.com/user/apps/#all to create your own dji sdk application, get dji sdk application
// information then fill in the application information here.
#define USER_APP_NAME               "your_app_name"
#define USER_APP_ID                 "your_app_id"
#define USER_APP_KEY                "your_app_key"
#define USER_APP_LICENSE            "your_app_license"
#define USER_DEVELOPER_ACCOUNT      "your_developer_account"
#define USER_BAUD_RATE              "460800"

定数名	説明	例
USER_APP_NAME	DJIのデベロッパーセンターの登録情報の `App Name` が対応します	DockingControl
USER_APP_ID	DJIのデベロッパーセンターの登録情報の `App ID` が対応します	（省略）
USER_APP_KEY	DJIのデベロッパーセンターの登録情報の `App Key` が対応します	（省略）
USER_APP_LICENSE	DJIのデベロッパーセンターの登録情報の `App Basic License` が対応します	（省略）
USER_DEVELOPER_ACCOUNT	DJIのデベロッパーセンターのアカウント名です	masayuki-kono

サンプルアプリケーションを起動して以下のログが延々と出力されれば OK です（バインド待ちの状態です）。

[Error]	dji_auth_sha256_rsa_verify.c:137  The DJI SDK CC has not binded. Please check the bind state of the DJI SDK CC and bind it.

Information

Raspberry Pi 向けのサンプルコードはメンテナンスされていないようで、そのままでは以下のようなエラーが出力されて認証チップと通信に失敗します。

Connect DJI SDK CC device failed, errno: 0x30000002

アドレス 0x2A への書き込みで ioctl(I2C_RDWR) が -1 を返し、スレーブが ACK を返していないのが原因です。
HalI2c_ResetDevice() で GPIO4 を LOW→25ms→HIGH とリセットした直後に、即座にデバイスを開いて書き込みしています。チップがリセットから復帰しきる前に初回トランザクションが走っているのが原因と考えられます。リセット解放後、チップが I²C に応答できるまでに必要な待ち時間が不足しているようなので、リセット解放後 50ms 待ってから I²C アクセスを行うように変更して改善しました。

Payload SDKをフォークしたリポジトリに修正したコードをアップしていますので参考にして下さい。デバッグログの出力も追加しているのでどのようなデータをチップと送受信しているか観測すると理解が深まると思います。

機体とペイロードデバイスを接続する

今回は Matrice 4E を使用しました。

各機器の接続イメージは以下の通りです。

Matrice 4E
- Application Binding で使用する機体
PC
- DJI Assistant 2 の動作環境
- DJI Assistant 2 は機体によってバリエーションがあり Matrice 4E の場合は Enterprise Series を使用する
- DJI Assistant 2 は DJI のクラウドサービスと通信するためインターネットに接続する必要がある
E-Port Development Kit
- 機体とペイロードデバイスを接続するためのアダプタボード
UART-USB Adapter
- 今回は FTDI のUART-USB変換アダプタを中継
- Raspberry Pi のGPIO（UART ピン）へ直接接続する場合は不要
Raspberry Pi
- Payload SDK アプリケーションの動作環境
DFN8 Breakout Adapter
- DFN8（2×3 mm）パッケージの表面実装ICを DIP8 互換ピン配置に変換するためのブレークアウトアダプタ
SDK Certified Chip

E-Port Development Kit

Development Kit の基盤上に E-Port switch というディップスイッチがあり、これを ON にして UART の出力を有効にします。

USB ID switch(Device|Host) のディップスイッチは、USB で RNDIS や Bulk 転送する場合に Host を設定する必要があります。今回は UART のみを使用するため、設定不要（どちらでも良い）です。

E-Port のコネクタはHW的にはリバーシブルですが、機体の E-Port コネクタと Development Kit を接続する際に機体側と開発キット側のコネクタの向きに指定があります。

Connect Development Board to E-Port からの抜粋です。

Note: The E-Port coaxial USB-C cable doesn't have a foolproof design, allowing A/B side to be reversibly connected.
Due to pin layout differences in the aircraft's USB-C, if the coaxial cable is reversed, the other end also needs to be flipped correspondingly.
If not flipped correspondingly, the E-Port Development Kit can not power up and communicate.

以下の写真のようにコネクタに A/B が印字されており、機体側が A なら開発キット側は B 、機体側が B なら開発キット側は A のようにフリップする必要があります。

DJI のページの記載では、どの向きが正しいのか判断できないため、結局、どちらも試して動作する向きを特定しました（写真は動作した時の組み合わせです）。

Application Binding を行う

Payload SDK アプリケーションから以下のログが延々と出力される状態（バインド待ち）にします。

[Error]	dji_auth_sha256_rsa_verify.c:137  The DJI SDK CC has not binded. Please check the bind state of the DJI SDK CC and bind it.

この状態で機体と E-Port Lite で接続した PC 上で DJI Assistant 2 を開くと Payload SDK メニューに以下が表示されます。

Bind ボタンを押下すると、バインドが完了します。

バインドが完了すると、サンプルアプリケーションの起動時のログは以下のようになります。

0.016	            core	[Info]	               dji_core.c:113  Payload SDK Version : V3.15.0-beta.0-build.2318 Dec 10 2025 17:27:05
1.075	         adapter	[Info]	     dji_access_adapter.c:351  Identify mount position type is Extension Port Type
1.075	         adapter	[Info]	     dji_access_adapter.c:371  Identify aircraft series is Matrice 4 Series
1.578	         adapter	[Info]	     dji_access_adapter.c:493  Identity uart0 baudrate is 921600 bps
1.582	            core	[Info]	    dji_identity_verify.c:627  Updating dji sdk policy file...
2.582	            core	[Info]	    dji_identity_verify.c:635  Update dji sdk policy file successfully
2.627	            core	[Info]	               dji_core.c:261  Identify AircraftType = Matrice 4E, MountPosition = Extension Port, SdkAdapterType = None
2.748	            auth	[Info]	        dji_sdk_cc_auth.c:86   Get DJI SDK CC serial num: 99PDN73EUB13J3
4.812	          linker	[Warn]	            dji_command.c:1025 <0xd5d0>Command async send retry: index = 0, retryTimes = 1, 0x0A06->0x0F01(0x002F) 0x3C13
5.945	          linker	[Warn]	            dji_command.c:910  Received invalid ack,<0xd5d0> 0x0F01(0x002F)->0x0A06(0x00CA) 0x3C13
6.322	         adapter	[Info]	    dji_identity_verify.c:257  the license level is basic
6.322	            core	[Info]	       dji_product_info.c:187  Set alias: PSDK_APPALIAS
6.942	            user	[Info]	            test_widget.c:141  widget file: /home/dev/DockingController/third_party/Payload-SDK/samples/sample_c/module_sample/widget/widget_file/en_big_screen
6.952	            user	[Info]	    test_widget_speaker.c:594  Set widget speaker volume: 60
6.952	            user	[Warn]	    test_widget_speaker.c:613  No audio device found, please add audio device and init speaker volume here!!!
12.455	            core	[Info]	               dji_core.c:328  Start dji sdk application
12.455	            user	[Info]	          application.cpp:372  Application start.

| Available commands:                                                                              |
| [0] Fc subscribe sample - subscribe quaternion and gps data                                      |
| [1] Flight controller sample - you can control flying by PSDK                                    |
| [2] Hms info manager sample - get health manger system info by language                          |
| [a] Gimbal manager sample - you can control gimbal by PSDK                                       |
| [c] Camera stream view sample - display the camera video stream                                  |
| [d] Stereo vision view sample - display the stereo image                                         |
| [e] Run camera manager sample - you can test camera's functions interactively                    |
| [f] Start rtk positioning sample - you can receive rtk rtcm data when rtk signal is ok           |
| [g] Request Lidar data sample - Request Lidar data and store the point cloud data as pcd files   |
| [h] Request Radar data sample - Request radar data                                               |
| [l] Run widget states manager sample, control widget states on other payload                     |

Information

I²C への読み書きする hal_i2c.c で通信データをログ出力すると分かりますが、SDK は初期化完了後も周期的に認証チップと通信しており、毎回異なるデータを送受信しています。

公式のプロトコル仕様は公開されていないため以下は推測ですが、チャレンジ・レスポンス型の認証として次のような流れと考えられます。

機体 → 認証チップ: チャレンジデータ送信（ランダム値やタイムスタンプを含む）
認証チップ → 機体: 署名済みレスポンス返送（認証チップ固有の秘密鍵を使用）
機体側が認証チップの公開鍵で署名を検証

これによりサードパーティが販売したペイロードデバイスを機体が正規のものとして識別でき、バインド済みのデバイスのみが Payload SDK を利用可能になっているようです。

バインド完了後に、DJIのデベロッパーセンターを開くと 1 Payloads が表示されカウントが増えていることが確認できるはずです。

まとめ

Application Binding は Matrice 4E/4T（2025年1月発売）以降で登場した比較的新しい仕様です。
そのため DJI の公式サイトを見ても全体像の把握が難しく、具体的な手順が分かりづらい状況にあります。

本記事では、Application Binding が必要な機体の一覧、SDK 認証チップの接続方法（Raspberry Pi を例に）、デベロッパーセンターでのアプリケーション登録を説明しました。
さらに、機体・ペイロード・PC を接続したうえで DJI Assistant 2 からバインドするまでの流れを一通り紹介しました。

Application Binding は今後発売される機体では標準となる可能性が高いです。
カスタムペイロードの開発に取り組まれる方は、本記事を手がかりにぜひ試してみてください。

DJIドローンの Payload SDK の紹介

2026-02-09T00:00:00.000+00:00

はじめに

豆蔵では太陽光発電パネルの清掃ロボットシステムの開発に取り組んでいます。

本システムでは太陽光発電パネルを清掃するロボットとロボットを搬送するドローンで構成されており、本記事では、ドローン側の開発技術である Payload SDK を紹介します。

プロジェクトの概要

太陽光発電パネルの発電効率を最大限に保つためには、表面に堆積する埃や汚れの定期的な除去が不可欠です。
一般家庭用の小規模なパネルであれば手作業での清掃も可能ですが、
メガソーラーなどの大規模な発電施設では、人力による清掃作業は効率面・コスト面で現実的ではありません。

当社では、このような発電施設向けの自律型清掃ロボットを開発しています。

清掃ロボットのシステム構成

発電所には連結された太陽光発電パネルがそれぞれ離れた位置に設置されています。
太陽光発電パネルは地表から2m以上の高い位置に設置されており、人手でロボットをパネル間で搬送するのは困難です。

そのため、本システムではドローンを使用してロボットを搬送する手法を採用しています。

主な構成要素は以下のとおりです。

清掃ロボット

太陽光発電パネル上をブラシで清掃しながら自律走行する自社開発の AMR です。ドローンの搬送対象（ペイロード）であり、総重量がドローンの可搬重量以内になるように設計しています。2025 国際ロボット展でも展示しました。

ドローン

DJI FlyCart 30 を使用しています。可搬重量は、デュアルバッテリーモードで 30 kg（最大飛行時間 18 分）、シングルバッテリーモードで 40 kg（最大飛行時間 9 分）です。

送信機（操作端末）は DJI RC Plus でDJI Pilot 2 というアプリケーションが動作しています。

ペイロードデバイス

FlyCart 30 に標準で付属している以下の貨物ケースは内寸 573×416×305 mm のため、ロボットを格納できません。そのため、ドローンにロボットを固定するデバイスを開発しています。

ペイロードデバイスの構成

本システムにおけるペイロードデバイスの主な役割はロボットをドローンに固定することです。

ドローンの送信機の操作でロック機構を制御し、ロボットを固定します。
ロック機構の制御や送信機へのウィジェットの提供はペイロードデバイス内のSBC（シングルボードコンピュータ）が担います。

DJIはペイロードデバイスの開発用に Payload SDK というSDKを提供しており、ペイロードデバイスではこのSDKを使用して開発したアプリケーションをSBC上で動作させます。

FlyCart 30の場合は以下のインターフェイスがペイロードデバイス向けに提供されています。

E-Port Lite
- USB Type-C のメンテナンス用ポート
- DJI Assistant 2 がインストールされた PC と USB Type-C ケーブルで直接接続し、機体のファームウェア更新やログ収集が可能
- FlyCart 30 のように E-Port を提供していない機体では、E-Port Lite と SBC を USB to TTL シリアルモジュールで接続し、拡張ポートとして使用が可能
Payload Port
- ペイロードデバイス向けの電源供給ポート
- 定格電圧は 51.2 V

本システムのロック機構は開発中のため詳細は割愛します。以下は CAN 対応のサーボを使う場合の構成イメージです。この場合、サーボへの電源供給は Payload Port から行い、SBC が E-Port Lite を介して機体と連携し、サーボを制御します。

機体が提供するさまざまな拡張ポート

前述した構成は FlyCart 30 の例です。機体によっては E-Port Lite 以外の拡張ポートを提供しているものもあります。

E-Port

多くの機体がサポートしている拡張ポートで、電源、UART、USB を提供します。E-Port Development Kit を中継してカスタムペイロードと接続し、UART や USB の通信が可能になります。

E-Port Lite ではカメラ画像の取得などに制約がありますが、E-Port では Development Kit を中継することで USB が拡張され、多くの機能を利用できます。

E-Port V2

M400（Matrice 400）で提供される拡張ポートです（M400 は 2025年6月発表であり、E-Port V2 は比較的、最近登場したポートです）。E-Port が機体あたり 1 ポートであることが多いのに対し、E-Port V2 は M400 の機体下部に 4 ポートを備え、1 ポートあたり 120 W の電源供給が可能です。電源出力は 13.6 V / 17 V / 24 V の 3 段階で調整できます。USB 3.0 をサポートしており、4K ストリームやレーダーポイントクラウドデータなどを同時に取得可能です。E-Port V2 Development Kit を中継してカスタムペイロードと接続します。

Gimbal Port

M300 RTK（2020年5月発表）と M350 RTK（2023年5月発表）のジンバル部に装備される標準インターフェースで、PSDK Port とも呼ばれます。Zenmuse シリーズに代表される DJI 製ジンバルペイロード（カメラ・センサー等）を接続するためのインターフェースです。

サードパーティ向けには Payload SDK Development Board Kit 2.0 が提供されており、これを中継すればカスタムペイロードと接続できます。

OSDK Port

現行機体ではM300 RTK のみが提供する旧来のインターフェースです。E-Port 登場以前の方式であり、Onboard SDK (OSDK) を利用しますが、OSDK の最終リリースは 2021-02-02(OSDK 4.1.0) で、新機能の追加は終了しています。

OSDK Port は OSDK Expansion Module 以外に E-Port Development Kit との接続もサポートしており、Payload SDK（PSDK）を使用できます。OSDK Version Support Information（2023年5月9日付）では、OSDK 4.x の機能はすべて PSDK V3 へ移行済みであるとされています。新規開発では PSDK V3 への移行が推奨されています。

機体別の拡張ポート

以下は、現行機体が提供している拡張ポートの一覧です。Standard Hardware Port Introduction より抜粋。

Aircraft	Port Name	Supports App Binding
FlyCart 100	E-Port Lite	–
FlyCart 30	E-Port Lite	–
Matrice 4D/4TD	E-Port, E-Port Lite	✓
Matrice 4E/4T	E-Port, E-Port Lite	✓
Matrice 3D/3TD	E-Port, E-Port Lite	–
Matrice 30/30T	E-Port	–
Mavic 3E/3T	E-Port	–
M400	E-Port V2	✓
M350 RTK	E-Port	–
M350 RTK	Gimbal Port	✓
M300 RTK	OSDK Port	–
M300 RTK	Gimbal Port	✓

Supports App Binding にチェックが入っている機体は Application Binding の手順が必要な機体です。
この手順は別の記事で紹介する予定です。

ポート種別ごとの機能対応表

下表は、Aircraft Type Function Difference の一覧から、一部の機体について、ポートごとの対応機能を抜粋したものです。

同じポート種別でも機体によって対応機能は異なるため、「E-Port ならこの機能が使える」のようにポート種別だけでは判断できません。例えば Hoisting Control は、FlyCart 100 の E-Port Lite でのみサポートされています。

Function Name	Function Level	FlyCart 30 E-Port Lite	Matrice 4E/4T E-Port	Matrice 400 E-Port V2	Matrice 350 RTK Gimbal Port
Log Management	basic	✓	✓	✓	✓
Data Subscription	basic	✓	✓	✓	✓
Basic Camera Function	basic	-	✓	✓	✓
Basic Camera Management	advanced	-	-	✓	-
Gimbal Function	basic	-	✓	✓	✓
Gimbal Management	advanced	-	-	✓	-
Power Management	basic	✓	-	✓	✓
Flight Control	advanced	✓	-	✓	✓
Custom Widget	basic	✓	✓	✓	✓
Custom HMS	basic	✓	✓	✓	✓
HMS Manager	advanced	✓	-	✓	✓
Time Synchronization	basic	-	✓	✓	✓
Low-speed Data Transmission	basic	✓	✓	✓	✓
Camera Video Stream	basic	-	✓	✓	✓
Playback Download	basic	-	-	✓	✓
X-Port Function	basic	-	-	✓	✓
Camera Stream Liveview	advanced	-	-	✓	-
Local Upgrade	basic	-	✓	-	✓
High-speed Data Transmission	basic	-	-	✓	-
Positioning	basic	-	-	✓	✓
SDK Interconnection	basic	-	-	✓	✓
Waypoint Mission	advanced	✓	-	✓	-
Speaker	basic	✓	✓	✓	✓
Hoisting Control	basic	-	-	-	-
Access Internet	advanced	-	-	✓	-
Network RTK	advanced	-	-	✓	-

シリアル通信仕様

Payload SDKはUARTやUSBのシリアル通信を使用します。

USB 通信では USB Gadget（Linux デバイスを USB 機器のデバイス側として振る舞わせる仕組み）を用い、次の 2 種類の通信方式を使い分けます。

Bulk（USB Bulk Transfer）
- デバイスとホスト間の双方向の生データ通信
RNDIS（Remote Network Driver Interface Spec）
- USB上で Ethernet をエミュレートする規格
- デバイスとホスト間のIP通信

各ポートのサポート状況は次の表のとおりです。

Port	Only UART	UART+Bulk	UART+RNDIS	Only Bulk	Only RNDIS
E-Port Lite	✓	–	–	–	–
E-Port	✓	✓	✓	–	–
E-Port V2	✓	–	–	✓	✓
Gimbal Port	✓	–	✓	–	–

方式	説明
Only UART	UART のみで機体と通信
UART+Bulk	UART と Bulk を併用して機体と通信
UART+RNDIS	UART と RNDIS を併用して機体と通信
Only Bulk	Bulk のみで機体と通信
Only RNDIS	RNDIS のみで機体と通信

Bulk のみまたは RNDIS のみで通信できるのは E-Port V2 だけで、それ以外のポートでは UART が必須です。

詳細は以下の DJI Developer Support のページ（中国語）を参照してください。いずれも閲覧には DJI Developer Center でのアカウント登録が必要です。

どのポートでも UART のみで通信できるため、開発初期は UART だけを接続し、Payload SDK で開発したアプリケーションの動作検証から始めることを推奨します。

Payload SDK の API 仕様

Payload SDK の API リファレンスには、SDKのソースコードのヘッダから自動生成されたと思われる API 仕様が掲載されています。ただし説明文はほとんどなく、関数や型の一覧が中心です。そのため、API仕様を理解するには、サンプルコードを参照しつつ実機で動作を確認する必要があります。

Payload SDK のサンプルアプリケーション

DJI の Payload-SDK リポジトリには、Payload SDK のライブラリとそれを使ったサンプルアプリケーションが公開されています。

ディレクトリ構成

リポジトリのディレクトリ構成は以下のとおりです。

├── psdk_lib
│   ├── include
│   └── lib
│       ├── aarch64-linux-gnu-gcc
│       ├── arm-linux-gnueabi-gcc
│       ├── arm-linux-gnueabihf-gcc
│       ├── armcc_cortex-m4
│       └── x86_64-linux-gnu-gcc
├── samples
│   ├── sample_c
│   │   ├── module_sample
│   │   │   ├── camera_emu
│   │   │   ├── camera_manager
│   │   │   ├── cloud_api
│   │   │   ├── data_transmission
│   │   │   ├── fc_subscription
│   │   │   ├── flight_control
│   │   │   ├── gimbal_emu
│   │   │   ├── gimbal_manager
│   │   │   ├── hms
│   │   │   ├── interest_point
│   │   │   ├── liveview
│   │   │   ├── mop_channel
│   │   │   ├── payload_collaboration
│   │   │   ├── perception
│   │   │   ├── positioning
│   │   │   ├── power_management
│   │   │   ├── tethered_battery
│   │   │   ├── time_sync
│   │   │   ├── upgrade
│   │   │   ├── utils
│   │   │   ├── waypoint_v2
│   │   │   ├── waypoint_v3
│   │   │   ├── widget
│   │   │   ├── widget_interaction_test
│   │   │   └── xport
│   │   └── platform
│   │       ├── linux
│   │       │   ├── common
│   │       │   │   ├── 3rdparty
│   │       │   │   ├── monitor
│   │       │   │   ├── osal
│   │       │   │   └── upgrade_platform_opt
│   │       │   ├── manifold2
│   │       │   │   ├── application
│   │       │   │   └── hal
│   │       │   ├── manifold3
│   │       │   │   ├── app_json
│   │       │   │   ├── application
│   │       │   │   └── hal
│   │       │   ├── nvidia_jetson
│   │       │   │   ├── application
│   │       │   │   └── hal
│   │       │   └── raspberry_pi
│   │       │       ├── application
│   │       │       └── hal
│   │       └── rtos_freertos
│   │           ├── common
│   │           │   └── osal
│   │           ├── gd32f527_development_board
│   │           │   ├── application
│   │           │   ├── bootloader
│   │           │   ├── drivers
│   │           │   ├── hal
│   │           │   ├── middlewares
│   │           │   └── project
│   │           └── stm32f4_discovery
│   │               ├── application
│   │               ├── bootloader
│   │               ├── drivers
│   │               ├── hal
│   │               ├── middlewares
│   │               └── project
│   └── sample_c++
│       ├── module_sample
│       │   ├── camera_manager
│       │   ├── flight_controller
│       │   ├── gimbal
│       │   ├── hms_manager
│       │   ├── liveview
│       │   ├── perception
│       │   ├── positioning
│       │   └── widget_manager
│       └── platform
│           └── linux
│               ├── common
│               │   ├── 3rdparty
│               │   └── osal
│               ├── manifold2
│               │   ├── application
│               │   └── hal
│               ├── manifold3
│               │   ├── application
│               │   └── hal
│               ├── nvidia_jetson
│               │   ├── application
│               │   └── hal
│               └── raspberry_pi
│                   ├── application
│                   └── hal

psdk_lib

プラットフォームごとの静的ライブラリが配置されています。各ツールチェーンについては Using third-party development platforms を参照してください。Raspberry Pi や Jetson の場合はこのディレクトリ内の aarch64-linux-gnu-gcc/libpayloadsdk.a を使用します。ここにないツールチェーンを使う場合は、SDK テクニカルサポート（dev@dji.com）に依頼すれば、そのツールチェーン用の静的ライブラリを用意してもらえるようです。PSDK platform static library link も参照してください。

samples

module_sample

SDK が提供する各機能のサンプルコードが配置されています。カメラ管理・飛行制御・ジンバル・ライブビュー・HMS・位置情報・ウィジェットなど、機能ごとにサンプルが用意されています。

platform

プラットフォーム依存のコードがまとめられています。hal/ に配置されているソースコードは、ハードウェア抽象化レイヤー（HAL）の実装（ネットワーク・UART・USB Bulk・I2C など）です。

サンプルアプリケーションのエントリポイントは application/main.cpp です。ここから application/application.cpp が呼ばれ、HAL ハンドラの登録や DjiCore_Init による SDK のセットアップが行われます。UART・Bulk・RNDIS のいずれを使うかは、登録する HAL ハンドラの組み合わせで決まります。

上記の HAL ハンドラ登録部分（CONFIG_HARDWARE_CONNECTION による分岐）の抜粋です。

Payload-SDK/samples/sample_c++/platform/linux/raspberry_pi/application/application.cpp

    returnCode = DjiPlatform_RegHalI2cHandler(&i2CHandler);
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("register hal i2c handler error");
    }

#if (CONFIG_HARDWARE_CONNECTION == DJI_USE_UART_AND_USB_BULK_DEVICE)
    returnCode = DjiPlatform_RegHalUartHandler(&uartHandler);
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("Register hal uart handler error.");
    }

    returnCode = DjiPlatform_RegHalUsbBulkHandler(&usbBulkHandler);
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("Register hal usb bulk handler error.");
    }
#elif (CONFIG_HARDWARE_CONNECTION == DJI_USE_UART_AND_NETWORK_DEVICE)
    returnCode = DjiPlatform_RegHalUartHandler(&uartHandler);
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("Register hal uart handler error.");
    }

    returnCode = DjiPlatform_RegHalNetworkHandler(&networkHandler);
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("Register hal network handler error");
    }
#elif (CONFIG_HARDWARE_CONNECTION == DJI_USE_ONLY_USB_BULK_DEVICE)
    returnCode = DjiPlatform_RegHalUsbBulkHandler(&usbBulkHandler);
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("Register hal usb bulk handler error.");
    }

#elif (CONFIG_HARDWARE_CONNECTION == DJI_USE_ONLY_NETWORK_DEVICE)
    returnCode = DjiPlatform_RegHalNetworkHandler(&networkHandler);
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("Register hal network handler error");
    }

    //Attention: if you want to use camera stream view function, please uncomment it.
    returnCode = DjiPlatform_RegSocketHandler(&socketHandler);
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("register osal socket handler error");
    }
#elif (CONFIG_HARDWARE_CONNECTION == DJI_USE_ONLY_UART)
    /*!< Attention: Only use uart hardware connection.
     */
    returnCode = DjiPlatform_RegHalUartHandler(&uartHandler);
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        throw std::runtime_error("Register hal uart handler error.");
    }
#endif

以下はアプリケーションのレイヤー構成のイメージです。

flowchart LR
  subgraph App["エントリポイント"]
    A["application.cpp<br/>HAL 登録・DjiCore_Init"]
  end
  subgraph SDK["SDK コア"]
    B["DjiCore_Init 等"]
  end
  subgraph HAL["HAL ハンドラ"]
    H["Network / UART /<br/>USB Bulk / I2C"]
  end
  A --> B --> H

実行時には、DjiCore が UART への書き込みなどを行う際に、事前に登録した HAL ハンドラがコールバックとして呼ばれます。その流れは次のとおりです。

sequenceDiagram
  participant App as application.cpp
  participant Core as DjiCore
  participant HAL as HALハンドラ

  App->>Core: HAL ハンドラを登録
  App->>Core: DjiCore_Init()
  Note over Core: 初期化完了
  Note over Core,HAL: 実行時（UART への書き込みが必要なとき）
  Core->>HAL: コールバック呼び出し<br/>（例: HalUart_WriteData）
  HAL-->>Core: 結果

図中の application.cpp と HALハンドラがサンプルコードに含まれており、DjiCore は psdk_lib の静的ライブラリとして提供されています。

初見ではサンプルコードの割にコード量が多く感じられるかもしれませんが、プラットフォーム依存のコードは基本的にそのまま利用できます。ただし、同じプラットフォームでも、最新の OS や付随するライブラリでは動作しない場合があるため、開発者側での保守が必要です。

Payload SDK の検証環境

残念ながら、Payload SDK のアプリケーションの動作を確認するには実際の機体が必要です。

DJI Assistant 2 にはフライトをシミュレートする機能がありますが、送信機とペアリングされた機体と接続した状態でしか利用できません。また、Payload SDK の通信先も実際の機体が前提となります。

本番運用で使用する機体と同じポート（E-Port Lite や E-Port）を備えた機種を調達またはレンタルする必要があります。

弊社では本番運用に FlyCart 30 を使用しますが、高価なため開発・デバッグには E-Port Lite を備えた別機種（Matrice 4E など）でアプリケーションを開発しています。

まとめ

本記事では、太陽光発電パネルの清掃ロボットをドローンで搬送するシステムのうち、ドローン側の開発に用いる Payload SDK を紹介しました。

インターネット上で検索しても Payload SDK に関する資料は DJI 提供のものに限られ、実用的な手順も DJI Developer Support の中国語ページが中心です。弊社でも、アプリケーションを動作するところまで持っていくのに手間がかかりました。同じようにカスタムペイロードの開発に取り組まれる方にとって、本記事がスタート地点の一助となれば幸いです。

飛行状態の取得やウィジェット連携、Application Binding の手順など、Payload SDK の実践的なトピックは続く記事で詳しくお届けする予定です。引き続きお付き合いいただければと存じます。

無料のOSSツールSysONで始めるSysMLv2モデリング（５）〜 Actionの作成

2026-02-05T00:00:00.000+00:00

これまでの記事では、Part Definitionと Part Usage、Packageの作成をご紹介しました。

/blogs/2026/01/29/sysmlv2-tool-syson-partusage/

本記事から振る舞いのモデリングを行います。

執筆時点における SysONの安定版は v2025.12.0が最新ですが、本記事では引き続き v2025.8.0を使用します。
ざっとドキュメントを見る限りでは、v2025.8.0と v2025.12.0の間に大きな機能追加はなさそうです。
ただし、今後を含めた最新リリースの挙動は一部異なる可能性がありますのでご了承ください。

Parameterを持つAction Definitionを作成する

"Intro to the SysML v2 Language-Graphical Notation.pdf" スライド50の図を作成してみましょう。

General Viewを開き、エディタ画面を右クリックでしてンテキストメニューから"Behavior" > "New Action Definition"を選択します。

作成した Action Definitionの名前を"ProvidePower"に変更しましょう。
変更方法は以前の記事を参照してください。

次にParameterを追加します。

"ProvidePower"を右クリックしてコンテキストメニューから"Structure" > "New Item In"を選択します。

追加された Itemを"pwrCmd : PwrCmd"に変更します。
このとき、左サイドバーのツリーに"PwrCmd"が追加されたことに着目してください。
これは、"pwrCmd"のItem Definitionです。
ツリーにある"PwrCmd"をエディタ画面にドラッグ＆ドロップしたら"pwrCmd"との間に definitionが表示されます。

再び "ProvidePower"を選択し、名前の右にマウスカーソルを移動すると表示される目のアイコンをクリックします。
表示された"Manage Visibility"のコンテキストメニューで、"parameters"のチェックをON、"pwrCmd : PwrCmd"のチェックをOFFにします。

pwrCmdのitemを（モデルではなく）図から削除します。

同様の方法で、"torque : Torque"を追加しましょう。
”pwrCmd : PwrCmd”の場合と同様、左サイドバーのツリーに"Torque"が追加されます。

Parameterのin, out, inout, noneは、右サイドバーのDetailsにある"Direction"のラジオボタンで変更できます。

題材は"torque"が配列になっています。
"torque : Torque"を"torque[*] : Torque"に変更してください。
右サイドバーのツリーの"torque"に"LiteralInfinity"の入った"MultiplicityRange"が追加されます。

題材では"torque : Torque [*]"となっていますが、v2025.8.0のSysONではこの表記だと多重度が無視されてしまいました。

Action DefinitionからAction Usageを作成する

エディタ画面を右クリックでコンテキストメニューから"Behavior" > "New Action"を選択します。
作成した Action Usageの名前を"providePower"に変更しましょう。

"providePower"を選択し、要素４辺の外側に表示された"＞"を"ProvidePower"までドラッグ＆ドロップします。
表示されたコンテキストメニューから"New Feature Typing"を選択します。

Action DefinitionにParameterを追加したのと同様にして、Action Usageである"providePower"にもItemを追加します。

"Manage Visibility"で"item1In"を非表示にし、"item1In"を"fuelCmd : FuelCmd :>> pwrCmd"に変更します。

見た目にはいくつか差異がありますが、意味的には同じものが出来ました。

Action UsageのDecomposition

"Intro to the SysML v2 Language-Graphical Notation.pdf" スライド51の図を作成してみましょう。

4つのAction Usage("generateTorque", "amplifyTorque", "distributeTorque", "transferTorque")を作成します。

Action Usageの Decompositionはエディタ画面で作図できませんでした。
（今後はできるようになるかもしれません）

左サイドバーのツリーで先程作成した4つのAction Usageを選択し、"providePower"にドラッグ＆ドロップします。
すると、ドラッグ＆ドロップした4つのAction Usageと"providePower"間にDecompositionが表示されます。

referenceにしたい場合は、対象のAction Usageを選択します。
右サイドバーで"Advance"タグを選択し、"Is Composite"のチェックをOFFにします。
対象のAction Usageのステレオタイプが"action"から"ref action"に変わり、"providePower"側の黒塗りひし形が白塗りに変わります。

Action DefinitionとAction UsageのDecompsition

SysMLv2仕様では、Action UsageをAction Definitionの部品とすることも出来ます。

先程のスライド51の図の、"providePower"をAction Definitionである"ProvidePower"に変更してみましょう。

左サイドバーのツリーにある"ProvidePower"をエディタ画面にドラッグ＆ドロップします。
次に、左サイドバーのツリーで"provodePower"内にあった４つのAction Usageを"ProvidePower"に移動します。
"Manage Visibility"でポートをダイアグラムから削除すると下図のようになります。

SysON起動時にエラーした場合の対応

これまで何度か SysONの起動と終了を繰り返してきました。
その中で、SysON起動時にエラーが発生して起動しないケースが偶に発生します。
こんな時は以下のコマンドでDockerの使われていないリソースを削除してみてください。

docker system prune

削除後に再度 Dockerで SysONを起動します。

次回予告

本記事では、Action Definitionと Action Usageを作成しました。
また、Decompositionで Actionを分割することをモデルで表現しました。

次回は、Action Usageをつなげて Action Flowを作成します。

GitHub Copilotのエージェントとインストラクションの設定方法

2026-01-30T00:00:00.000+00:00

はじめに

本記事では、GitHub Copilotのエージェント（Agents）およびインストラクション（Instructions）の設定方法について説明します。

Agents（エージェント）とは
特定のタスクや分野に特化した専門家としてCopilotをカスタマイズする機能です。
たとえば、バックエンド開発用、フロントエンド開発用など、異なる専門性を持つ複数のエージェントを定義し、状況に応じて使い分けることができます。
Issueにアサインしたり、VS Code上で選択して利用します。

Instructions（インストラクション）とは
Copilotに対する共通のルールや制約を定義する機能です。
コーディング規約、命名規則、プロジェクト固有のベストプラクティスなどを記載し、すべての開発者が一貫したコード生成の支援を受けられるようにします。
エージェントと併用され、VS CodeでのコーディングやPull Requestのレビューなど、あらゆる場面で適用されます。

適用順序

以下の順序でルールが適用されます。競合するルールがある場合、数字の小さいルールが優先されます。

選択したエージェント（例: agents/backend.agent.md）
マッチするインストラクション（例: instructions/typescript.instructions.md ← applyToパターンに一致）
全体のインストラクション（copilot-instructions.md）

ファイルの配置

GitHub Copilotが認識できるよう、下記のように配置します。

.github/
- agents/
  - xxx.agent.md: 特定の分野（ロールなど）に合わせて定義するエージェントファイル（e.g. backend, frontend, test）
- copilot-instructions.md: 全体に適用されるルールや制約を定義するファイル
- instructions/
  - xxx.instructions.md: 特定の分野（テクノロジーなど）に合わせて定義するファイル。（e.g. typescript, python, react）※サブフォルダーで分類したくなりますが、フォルダー分けすると読み込まれません。

Caution

AGENTS.mdについて

.github/AGENTS.md（ディレクトリ直下）はGitHub CLI用のファイルです。
VS Codeでは読み込まれませんので注意してください。
VS Codeではagents/ディレクトリ内の*.agent.mdファイルのみが有効です。

Information

ワークスペースでの配置

VS Codeでマルチリポジトリ（複数のリポジトリを同時に開いて作業）する場合、
設定ファイルはワークスペースのルートディレクトリの.github/に配置する必要があります。
各リポジトリに個別の設定を使いたい場合は、リポジトリごとに別のVS Codeウィンドウで開いてください。

.github/agents/sample.agent.md: ワークスペースルートに配置すると選択できます
- repo-A/.github/agents/sample.agent.md: 各リポジトリ配下のエージェントは読み込まれません
- repo-B/.github/agents/sample.agent.md

ヘッダー部の用途

定義ファイルのヘッダー部に設定できるプロパティの一部を紹介します。

エージェント

---
name: Backend Agents(TypeScript)
description: This custom agent implements backend features using TypeScript.
model: GPT-5.2
---

※エージェント選択画面（VS Code）

プロパティ	設定時	未設定時
name	エージェント名として使用	拡張子を除いたファイル名をエージェント名として使用
description	エージェントの説明として使用	空欄
model	使用するAIモデルを指定	デフォルトモデル

インストラクション

---
applyTo: "src/**/*.ts" # e.g. src配下のtsファイルを対象
---

プロパティ	設定時	未設定時
applyTo	指示を適用するファイルのパターンを指定（globパターン）	すべてのファイルに適用

Information

applyToの指定例

**/*.ts - すべてのTypeScriptファイル
src/** - srcディレクトリ配下のすべてのファイル
**/*.{js,ts} - JavaScriptとTypeScriptファイル

定義例

エージェントおよびインストラクションの定義例を以下に示します。
これらを組み合わせることで、プロジェクトやタスクに最適化されたCopilotの動作を実現できます。

エージェント：バックエンド開発者

.github/agents/backend-specialist.agent.md

---
name: Backend Developer Agent
description: NestJSを使用したバックエンド開発の専門家
---

# 役割

あなたはNestJSとTypeScriptを使用したバックエンド開発の専門家です。

# 技術スタック

- **フレームワーク**: NestJS 11.x
- **言語**: TypeScript 5.x
- **データベース**: PostgreSQL
- **ORM**: TypeORM
- **テスト**: Jest

# コーディング規約

- ヘキサゴナルアーキテクチャを遵守してください
- DTOには必ずバリデーションデコレータを付与してください
- 例外処理は適切なHTTPステータスコードを返すカスタム例外を使用してください

# テスト方針

- 単体テストはすべてのServiceクラスに対して作成してください
- テストカバレッジは80%以上を目標としてください

全体インストラクション：プロジェクト共通規約

.github/copilot-instructions.md

# コーディング規約

## 共通ルール

- **言語**: 日本語でコメントとドキュメントを記載してください
- **命名規則**: 
  - クラス名: PascalCase
  - 関数名・変数名: camelCase
  - 定数: UPPER_SNAKE_CASE
- **インデント**: スペース2文字
- **文字列**: シングルクォートを使用

## 禁止事項

- `any`型の使用は原則禁止（型定義を適切に行うこと）
- `console.log`のコミットは禁止（ロガーを使用すること）
- 機密情報のハードコードは厳禁

## セキュリティ

- 外部入力は必ずバリデーションを行うこと
- SQLインジェクション対策を実施すること
- 認証・認可が必要なエンドポイントにはガードを設定すること

分野別インストラクション：TypeScript専用ルール

.github/instructions/typescript.instructions.md

---
applyTo: "**/*.ts"
---

# TypeScript固有のルール

## 命名規則

- ファイル名: kebab-case

## 型定義

- 明示的な型注釈を優先してください
- Utility Typesを活用してください（`Partial`, `Pick`, `Omit`など）
- 複雑な型は`type`エイリアスで定義してください

```typescript
// Good
type UserProfile = {
  id: string;
  name: string;
  email: string;
};

type UserProfileUpdate = Partial<Pick<UserProfile, 'name' | 'email'>>;

// Bad
const updateUser = (data: any) => { ... };
```

## 非同期処理

- `async/await`を使用してください（Promiseチェーンは避ける）
- エラーハンドリングは`try-catch`で行ってください

## インポート順序

1. 外部ライブラリ
2. 内部モジュール（絶対パス）
3. 相対パス

```typescript
// 外部ライブラリ
import { Injectable } from '@nestjs/common';
import { Repository } from 'typeorm';

// 内部モジュール
import { UserEntity } from '@/entities/user.entity';
import { CreateUserDto } from '@/dto/create-user.dto';

// 相対パス
import { UserService } from './user.service';
```

運用上の注意事項

VS Codeでのキャッシュ管理

エージェントやインストラクションのファイルを変更した場合、初回ロードした内容がキャッシュされます。
変更を反映するには、以下のいずれかの操作が必要です。

チャットで変更したファイルを明記して再読み込みを促す（例: sample.agent.mdを変更したので再読み込みしてください）
新しいチャットを開始する
VS Codeを再起動する

GitHubでのファイルサイズ制限

エージェントファイルの文字数が30,000文字（バイト数ではなく、ヘッダー部は含まない）を超えると選択できなくなります。
適切な粒度でファイルを分割してください。

GitHub IssueでCopilotをアサイン後に表示されるダイアログ

Kiro CLIでRalphループを試してみた

2026-01-30T00:00:00.000+00:00

はじめに

AIエージェントによる自律開発は魅力的ですが、長時間の処理でコンテキストの劣化により精度が落ちる問題があります。この課題に対するアプローチとして注目されているのはRalphループ（コンテキストを都度破棄して新しいセッションで処理を継続する自律開発手法）です。本記事では、Kiro CLI^[1]（AIエージェントによる自律開発を支援するCLIツール）を使ったRalphループの検証結果と、実践で得た教訓を共有します。

背景：コンテキスト管理の課題とRalphループ

従来のAIチャットにおける課題は、長時間の会話でコンテキストが圧縮されたり劣化したりして精度が落ちることです^[2]。

Ralphループの核となる原則はコンテキスト腐敗の回避です^[3]。1つのタスクが終わるごとにコンテキストを破棄し、新しいセッションで次のタスクを開始するというループ構造を回します。一見シンプルなテクニックですが、これにより精度を安定させながら長時間のタスク実行が可能になると考えられます。

今回の検証では、定番構成のClaude Code + PRD.md（Product Requirements Document: 製品要求仕様書）ではなく、Kiro IDE^[4]（仕様作成からタスク管理まで対話的に支援するIDE）の仕様成果物3種（requirements.md、design.md、tasks.md）に置き換えました。構造化された指示により精度向上を狙っています。

検証題材：スプレッドシートアプリ

今回の検証では、Webブラウザ上で動作する軽量スプレッドシートアプリを開発しました。

アプリケーション仕様

10列×20行のグリッド、セル参照、四則演算
SUM/AVG関数、循環参照エラー検知
技術スタック：React + TypeScript + Vite + Vitest

選定のポイントは、比較的複雑度が高く、コンテキストがひっ迫して処理が迷走しそうなアプリケーションであることです。数式パーサー、依存関係グラフ、循環参照検知など、複数の概念が絡み合う題材で、Ralphループの実用性を試しました。

完成したアプリケーション

今回作成したスプレッドシートアプリを先に説明します。
初期画面では、以下のように10列×20行のグリッドと数式バーが表示されます。

セル参照、四則演算、SUM/AVG関数などが実装されており、数式による自動演算が可能です。入力例として、簡単な数値演算をSUM関数を用いて行いました。

テスト品質

自律実行により、以下のテストが自動生成・実装されました。

テストケース総数: 126テスト
ユニットテスト: 101テスト
プロパティベーステスト（ランダム入力により仕様の性質を検証するテスト手法）: 25テスト

Kiro CLIはテスト駆動開発のアプローチに従い、プロパティベーステストによるランダム入力検証を含むテストスイートを自律構築しました。人間では予測困難な入力パターンに対しても、循環参照検知や数式評価の正確性を効率的に検証するテストが生成され、品質確保に寄与しています。

実装ステップ

Ralphループの実装は、以下の2ステップで進めました。

ステップ1：Kiro IDEによる準備フェーズ

プロジェクト構成

まず、プロジェクトのディレクトリ構造を以下のように準備します。

project/
├── .kiro/specs/spreadsheet-sample/
│   ├── requirements.md      # EARS記法による要件定義
│   ├── design.md            # システム設計書
│   └── tasks.md             # 実装タスクリスト
├── progress.txt             # 実装進捗を記録（イテレーション間で引き継ぎ）
├── ralph-once.sh            # 単発実行用スクリプト
└── afk-ralph.sh             # Ralphループ制御スクリプト

1-1. 仕様成果物の作成

Kiro IDEを使ってスプレッドシートアプリの仕様を定義します。

Specモードで、.kiro/specs/spreadsheet-sample/ディレクトリに以下3つの仕様成果物を生成します。

requirements.md: EARS記法（要件定義の構文ルール）による要件定義。受入基準が明確に記述される
design.md: システム設計書。アーキテクチャやコンポーネント設計が含まれる
tasks.md: 実装タスクリスト。Kiro CLIがこれを読み取り、未完了タスクを実装する

Kiro IDEとの対話を通じて、アプリケーションの要件を伝え、これらの仕様成果物を完成させます。この段階では、まだコードは生成されません。

1-2. シェルスクリプトの作成

次に、Ralphループを制御するシェルスクリプトafk-ralph.shを作成します。シェルスクリプトの実装は、AIHero.devのガイド^[5]を参考にしました。

メインループ

afk-ralph.sh（メインループ部分）

for ((i=1; i<=${1}; i++)); do
  echo "loop iteration $i"

  # 仕様3種とprogress.txtを読み込み
  req="$(cat "${SPEC_DIR}/requirements.md")"
  des="$(cat "${SPEC_DIR}/design.md")"
  tasks="$(cat "${SPEC_DIR}/tasks.md")"
  progress="$(cat progress.txt 2>/dev/null || echo 'まだ進捗なし')"

  # プレースホルダーを実際の内容に置換
  prompt="$(build_prompt)"
  prompt="${prompt/__REQ__/$req}"
  prompt="${prompt/__DES__/$des}"
  prompt="${prompt/__TASKS__/$tasks}"
  prompt="${prompt/__PROGRESS__/$progress}"

  logfile="/tmp/kiro-iteration-${i}.log"
  kiro-cli chat --no-interactive --trust-all-tools "$prompt" 2>&1 | tee "$logfile"

  # tasks.mdの未完了タスク数とCOMPLETE出力で終了判定
  uncompleted=$(grep -cE '^\- \[ \]' "${SPEC_DIR}/tasks.md" 2>/dev/null || echo "0")
  has_promise=$(grep -q "<promise>COMPLETE</promise>" "$logfile" && echo "yes" || echo "no")

  if [ "$uncompleted" -eq 0 ] && [ "$has_promise" = "yes" ]; then
    echo "All tasks verified complete after $i iterations."
    exit 0
  fi
done

メインループでは、毎イテレーションで仕様ファイルを読み込み、プロンプトに埋め込んでKiro CLIを実行します。終了条件は、tasks.mdの未完了タスクがゼロかつAIによる<promise>COMPLETE</promise>の出力の両方を満たす場合です。

実行オプションとリスク

Kiro CLIの実行には、以下の2つの重要なオプションを指定しています。

--no-interactive: 対話モードを無効化し、ユーザー入力を待たずに自動実行する
--trust-all-tools: すべてのツール実行を自動承認し、コマンド実行の確認を求めない

これらのオプションにより完全自律実行が可能になりますが、意図しないコマンドの実行リスクがあります。そのため、devcontainerなどの隔離環境での実行が必須です。後述の「気づきと教訓」でも述べるように、環境分離なしでの実行は推奨しません。

AIエージェントへのプロンプト

afk-ralph.sh（プロンプトテンプレート部分）

build_prompt() {
  cat <<'PROMPT'
【要件】__REQ__
【設計】__DES__
【タスク一覧】__TASKS__
【進捗】__PROGRESS__

1. 要件と設計を理解する
2. タスク一覧と進捗を確認し、次の未完了タスクを見つける
3. そのタスクを実行する
4. 変更をコミットする
5. 完了後、tasks.md のチェックボックスを [ ] から [x] に更新する（必須）
6. progress.txt に完了した内容を追記する（必須）

1回の実行で1タスクのみ実装すること
npm run test は禁止。必ず npm run test:unit または npm run test -- --run を使う
常駐プロセスは禁止、必ず一回で終了するコマンドのみ実行すること
（中略）
全タスク完了時のみ <promise>COMPLETE</promise> を出力すること
tasks.mdに未完了タスク [ ] が残っている場合は絶対に <promise>COMPLETE</promise> を出力しないこと
PROMPT
}

プロンプトには、仕様3種と進捗を埋め込むプレースホルダーと、AIエージェントへの詳細な実行制約を含めています。特に、常駐プロセスの禁止と終了条件の明確化が重要でした。

ステップ2：Kiro CLIでRalphループの実行

devcontainer（VS Codeのコンテナベース開発）環境でシェルスクリプトを実行し、Ralphループを開始します。

$ ./afk-ralph.sh 10
START afk-ralph.sh
loop iteration 1
# ... kiro-cliがタスク1を実装、コミット ...
loop iteration 2
# ... kiro-cliがタスク2を実装、コミット ...
...
All tasks verified complete after 7 iterations.

引数の10は最大イテレーション数です。各イテレーションでは、新しいコンテキストでKiro CLIが起動し、タスクを実行します。

上図は、タスク2.2と2.3を完了した後、イテレーション2に移行する様子です。

各イテレーションで以下を実行します。

仕様成果物3種と進捗を読み込み
次の未完了タスクを特定
タスクを実装し、テストを実行
変更をコミット
tasks.mdのチェックボックスを更新
progress.txtに進捗を記録

気づきと教訓

環境分離は必須

自律実行は実行コマンドの全自動承認を前提とするので、何が起こるかわかりません。今回はdevcontainer環境で実行しました。進捗ファイルが複数箇所にできるなど、AIの行動を予測することの難しさを感じました。

待機モード・対話確認を消す

自律実行のためには中断を挟まないようにする必要があります。今回はプロンプトの中で対話確認や待機を伴うコマンドの実行禁止を指示しました。

トークンを大量に消費する

処理の都度、新しくセッションを立ち上げてゼロからインプットする行為を繰り返すので、消費トークンが従来よりも増えます。余裕のある環境で実行する必要があります。

まとめ

完成したアプリケーションの基本機能は問題なく動作しましたが、商用製品と比較すると機能面での差は歴然です。それでも、夜中にスクリプトを起動して朝起きたら動くアプリケーションが完成していた体験は、AIエージェントの可能性を実感させるものでした。

今回は数10回のイテレーションで完了するシンプルな題材でしたが、数100回のイテレーションを要する複雑なアプリケーション開発にも挑戦してみたいと考えています。

今回開発したリポジトリは以下で公開しています。（予告なく公開停止する場合があります）

https://github.com/hironori-maruoka/kiro-ralph

AWS. Kiro CLI の紹介. ↩︎
16x Engineer. LLM Context Management Guide: Performance degrades with more context. ↩︎
The Ralph Wiggum Loop from 1st principles (by the creator of Ralph). YouTube. ↩︎
AWS. Kiro の紹介. ↩︎
AIHero.dev. Getting Started with Ralph: Create your script. ↩︎

無料のOSSツールSysONで始めるSysMLv2モデリング（４）〜 Part Usageの作成

2026-01-29T00:00:00.000+00:00

前回の記事「無料のOSSツールSysONで始めるSysMLv2モデリング（３）〜 Part Definitionの作成」では、Part Definitionを作成しました。

/blogs/2026/01/22/sysmlv2-tool-syson-partdef/

本記事では、Part Usageを作成します。

本記事で使用する SysONは前回同様、v2025.8.0です。
SysONは現在も進化中ですので最新リリースの挙動とは異なる可能性があります。
ご了承ください。

モデリングの題材は、SysMLv2の仕様書 A Annex: Example Modelから拝借します。
"Figure 63. Variant engine4Cyl"を作成してみましょう。

新規のPart Usageを作成する

General Viewを右クリックして表示されるコンテキストメニューから "Structure" > "New Part"を選択すると、General Viewに "part1"が追加されます。

要素を追加する方法はもう１つあります。
左サイドバーのツリーでパッケージなどの要素の右にあるケバブアイコン（︙）をクリックします。
表示されたダイアログで Partを選択し、"CREATE"ボタンを押下することで指定した要素の中に新たな要素を追加できます。

追加した要素を General Viewにドラッグ＆ドロップすれば、グラフィカル記法で表示できます。

Part DefinitionとPart Usageの間にdefinitionを作成する

前回の記事の手順でPart Definitionを作成し、"Engine"に名前を変更します。
次に、Part Usageを作成し、"engine"に名前を変更します。

"engine"を選択し、４つの辺の外に表示された三角（＞）を"Engine"までドラッグ＆ドロップすると、コンテキストメニューが表示されます。
コンテキストメニューで"New Feature Typing"を選択すると、Part DefinitionとPart Usageの間にdefinitionを作成できます。

definitionは白抜き三角と２つの点が付いた線であらわします。
もう１セット、Part Definitionの"Cylinder"と Part Usageの"cylinders"も作成しましょう。

Part Usage間にcomposite-feature-membershipを作成する

"engine"と"cylinders"間にcomposite-feature-membershipを作成します。

"engine"を選択し、４つの辺の外に表示された三角（＞）を"cylinder"までドラッグ＆ドロップし、コンテキストメニューを表示します。
コンテキストメニューで"Add as nested Part"を選択すると、Part Usage間にcomposite-feature-membershipを作成できます。

"cylinders"から"engine"にドラッグ＆ドロップの操作をした場合、コンテキストメニューで"Become nested Part"を選択すると同様に作成できます。

左サイドバーのツリー上で、”cylinders”を"engine"にドラッグ＆ドロップすることによっても作成できます。

composite-feature-membershipは黒塗りひし形の付いた線であらわします。

Part Usage間にnoncomposite-feature-membershipを作成する

"engine"と"cylinders"間のrelationshipをnoncomposite-feature-membershipにします。

noncomposite-feature-membershipはusageが参照的であることをあらわします。
したがって、参照されている側のusageの設定を変更します。

参照されている"cylinders"を選択して、右サイドバーのDetailsにあるAdvancedタグを選択します。
ここにある Is Compositeのチェックを外してください。
すると Is Referenceにチェックが付き、エディタ上の"cylinders"のステレオタイプが"«ref part»"に変わります。
これと共に、"engine"と"cylinders"の間のrelationshipがnoncomposite-feature-membrship（白抜きのひし形）に変わります。

戻す場合は、Is Compositeにチェックを付けます。

UsageにMultiplicityを設定する

”cylinders”のMultiplicityを"4..8"に設定します。

"cylinders"を選択して、F2キーやEditで直接編集できるようにします。
次に、"cylinders"を"cylinders[4..8]"に変更します。
すると、左サイドバーのツリーの"cylinders"内にMultiplicityRangeが追加されます。
MultiplicityRangeの中にはLiteralIntegerが２つあり、１つのValueは”4”、もう１つは"8"が設定されます。

"cylinders"を編集した際、"cylinders[4..8] : ShapeItems::Cylinder"に変わることがあります。
このとき ShapeItems Libraryの"Cylinder"がdefinitionとして選択されている状態になっています。
この場合は以下の手順で修正できます。

右サイドバーのDetailにある Typed byで設定されている"Cylinder"を削除
左サイドバーのツリーにある"cylinders"内の"FeatureTyping"をモデルから削除
"cylinders[4..8]"と"Cylinder"の間にdefinitionを再作成

Part Usage間にsubsettingを作成する

"engine"と"engine4Cyl"の間にsubsettingを作成します。

Part Usageを作成し、名前を"engine4Cyl"に変更します。
”engine4Cyl”を選択して外側に表示された三角（＞）を"engine : Engine"までドラッグ＆ドロップします。
表示されたコンテキストメニューで”New Subsetting”を選択します。

subsettingは白抜き三角が付いた線であらわします。

Part Usage間にredefinitionを作成する

"cylinders[4]"のPart Usageを作成し、"cylinders[4..8]"との間にredefinitionを作成します。

"cylinders[4]"を選択し、外側に表示された三角（＞）を”cylinders[4..8]”までドラッグ＆ドロップします。
表示されたコンテキストメニューで"New Redifinition"を選択します。

redefinitionは白抜き三角と１本線が付いた線であらわします。

Viewを完成させる

"cylinder1[1]", "cylinder2[1]", "cylinder3[1]", "cylinder4[1]"の４つのPart Usageを作成します。
作成した４つのPart Usageと"cylinders[4]"の間にsubsettingを作成します。
また、先の４つのPart Usageに加えて、"cylinders[4]"と"engine4Cyl"の間にcomposite-feature-membershipを作成します。

"engine4Cyl"と"cylinders[4]"の間のcomposite-feature-membershipを選択します。
右クリックでコンテキストメニューを表示し、”Show/Hide” > "Hide"を選択します。

”Engine”と"Cylinder"の２つのPart Definitionを（モデルから削除ではなく）ダイアグラムから削除すると、下図のようになります。

題材と「全く同じ」とはいきませんが、等価なモデルが作成できました。

次回予告

本記事では、Part Usage要素を作成し、構造をモデル化しました。

次回は、振る舞いのモデル要素である Action Definitionと Action Usageを作成します。

LLMでロボット通信コードを書く - 安川HSES向けAgent Skillsの紹介

2026-01-28T00:00:00.000+00:00

はじめに

弊社では様々なメーカのロボットを使用してシステムを構築しています。ロボットコントローラとの通信部分は「出来て当たり前」の機能です。ここのインテグレーションコストを抑え、ビジョンやハンドといったシステム固有の機能開発にフォーカスしたいという課題がありました。

一方で、産業用ロボットコントローラのプロトコル仕様はPDFで配布されていることが多く、LLMへの入力にはマークダウン化が必要です。マークダウン化しても理解にはドメイン知識を要したり、Webに活用事例のような情報が少なくLLMの学習データが不足していたりと、別途コンテキストの入力が必要なケースも多いです。

そこで今回、コントローラ通信プロトコルとクライアントの使用方法をAgent Skillsとして整備し、LLMにコントローラ通信コードを書かせる取り組みを行いました。

今回は安川ロボットのHSES（High-Speed Ethernet Server）プロトコル向けにスキルを作成し、Rust製クライアント moto-hses と組み合わせて検証しました。

通信仕様やクライアントの使用方法をAgent Skillsの形式で提供することで、Webに活用事例がなくてもLLMが適切なコードを生成してくれます。まだまだ内容は成熟していませんが、スキルを活用・改善してゆくことでコントローラとの通信コードはLLMが自動で実装してくれつつあります。また、通信の障害が発生した際にパケットデータと通信プロトコルを照合してデバッグするといった使い方も可能であり、コード生成から保守までLLMへ任せられるようになってきました。

安川電機が提供する標準SDK

安川電機のロボットコントローラと通信する手段としてメーカからは以下の3つのSDKが提供されています。

項目	MotoCom32 / MotoComES	MotoPlus	YMConnect
概要	PCからEthernet経由でロボットコントローラへアクセスするための従来型通信SDK。外部PC上で実行。	コントローラ内部で動作するユーザアプリをC言語で開発するための組込みSDK。	MotoComの後継。クロスプラットフォーム対応の新世代通信SDK。外部PC上で実行。
対応OS	Windows（32bit/64bit）	専用RTOS（ロボットコントローラ内で動作）	Windows 10+ / Ubuntu 22.04+
対応言語	C / C++ / VB6 / .NET	C	C++17 / C# (.NET 10)
動作場所	外部PC（ホスト側）	コントローラ内（組込み側）	外部PC（ホスト側）
通信方式	Ethernet（TCP/IP）	内部API（コントローラOSと直接連携）	Ethernet（TCP/IP）
主な用途	監視・I/O制御・ジョブ起動など外部制御	高速制御・カスタム動作・外部通信タスク	監視・I/O制御・ジョブ起動など外部制御
有償 / 無償	有償（USBドングルによるHWライセンス。実行環境ごとに必要）	有償（開発ライセンスのみ。実行環境は不要）	無償（Apache License 2.0）
特徴	Windows専用、歴史が長く安定だが新機能は更新停止傾向。	最も自由度が高く、リアルタイム処理・外部通信も可能。	マルチプラットフォーム・モダンAPI設計。
配布元	Yaskawa Electric（販売契約が必要）	Yaskawa Electric（契約した開発者のみ）	GitHub

MotoPlusの場合は、コントローラ内部で動作するアプリとPC側の通信クライアントをそれぞれ自身で開発する必要があります。そのため、提供されている通信クライアントとしてはMotoComとYMConnectの2択となります。

YMConnectは比較的最近（2024年）に公開されたSDKです。C++17以降や.NET 10以降を使用可能なモダンなプロジェクトならYMConnectが良さそうですが、既存のレガシーシステムではMotoComを使用し続けているケースも多いのではないでしょうか。YMConnectの活用事例はまだほとんど見かけません。しかし、YMConnectのDiscussions を見ると少しずつ不具合報告も挙がってきているので、徐々に採用実績も増えてくるのではないかと思います。

一方で安川ロボットのコントローラは High-Speed Ethernet Server (HSES) というサーバー機能を提供しており、通信プロトコルも公開されています（FS100 HSES Manual (PDF)）。

MotoCom（恐らくYMConnectも）はHSESの通信クライアントとして安川から提供されたSDKであり、同等のクライアントは内製することができます。
今回は上位アプリケーションがRustであったこと、レガシーシステムでも使用したいこと、LLM駆動の開発に必要なモックサーバー機能が欲しかったことから、自作したRustクライアントを使用しています。

moto-hses: Rust製HSESクライアント

moto-hses は、安川ロボットコントローラのHSES (High-Speed Ethernet Server) プロトコルに対応したRust製の非同期通信クライアントライブラリです。

moto-hses自体もLLMで開発

実はこのクライアント自体もLLMで開発しました。プロトコル仕様PDFをマークダウン化したドキュメントと、リファレンスとなる別言語のクライアントコードをコンテキストとして入力しています。LLMに対するガードレールや自動フィードバックの仕組みを整備しながら開発を進めました。同様のアプローチでC#向けクライアントなども作成できそうです。この開発プロセスについては、機会があれば別の記事で紹介したいと思います。

特徴

型安全: Rustの型システムを活用した安全なAPI設計
非同期処理: Tokioランタイムを使用した非同期UDP通信
スレッドセーフ: SharedHsesClient による複数タスクからの並行アクセスに対応
テスト容易性: モックサーバー (moto-hses-mock) による統合テストが可能

モックサーバーの重要性

安川が提供するロボットシミュレータ（MotoSim EG-VRC）はHSESサーバー機能を有していません。そのため、これまでは実機のロボットコントローラを使用して通信検証する必要がありました。moto-hsesのモックサーバーを使えばローカル環境やCIで通信コードのテストが可能です。ローカルで完結して通信検証できることは、LLMへ自動でフィードバックする仕組みを構築する上でも非常に重要な要素となります。

クレート構成

クレート	説明
`moto-hses-proto`	プロトコル定義とシリアライゼーション
`moto-hses-client`	Tokioベースの非同期UDPクライアント
`moto-hses-mock`	テスト用のローカルモックHSESサーバー

対応コマンド

現在、以下のロボット制御コマンドに対応しており、逐次追加中です。

コマンドNo	コマンド名
0x70	アラームデータ読み出し
0x71	アラーム履歴読み出し
0x72	ステータス情報読み出し
0x73	実行中ジョブ情報読み出し
0x75	ロボット位置データ読み出し
0x78	I/Oデータ読み書き
0x79	レジスタデータ読み書き
0x7A〜0x7E	各種変数（B/I/D/R/S型）読み書き
0x82	アラームリセット / エラーキャンセル
0x83	ホールド / サーボON/OFF
0x84	ステップ / サイクル / 連続切替
0x86	スタートアップ（ジョブ起動）
0x87	ジョブ選択

その他、ファイル操作コマンド（削除、保存、一覧取得）や複数データの一括読み書きコマンドにも対応しています。

基本的な使い方

use moto_hses_client::HsesClient;
use moto_hses_proto::AlarmAttribute;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // クライアント作成
    let client = HsesClient::new("192.168.0.3:10040").await?;

    // アラームデータ読み出し
    let alarm = client.read_alarm_data(1, AlarmAttribute::All).await?;
    println!("Alarm Code: {}", alarm.code);
    println!("Alarm Name: {}", alarm.name);

    // アラームリセット
    client.reset_alarm().await?;
    println!("Alarm reset completed");

    Ok(())
}

Agent Skills によるLLM支援

Agent Skills は、AIコーディングエージェントに特定のドメイン知識や使用方法を教えるためのフォーマットです。スキルは、SKILL.md（エージェントへの指示）、references/（参考ドキュメント）、scripts/（自動化スクリプト）で構成されます。

今回、moto-hsesを活用するために以下の3つのスキルを作成しました。

スキル	説明
hses-protocol	HSESプロトコル仕様。メッセージ構造、コマンドフォーマット、エラーコードなど
moto-hses-usage	moto-hsesクレートの使用ガイド。クライアント操作、コマンドリファレンスなど
hses-packet-analysis	HSESパケットの解析ガイド。通信障害時のデバッグに活用

スキルのインストール

作成したスキルはGitHubリポジトリで公開しています。Vercelが提供するスキルインストーラー add-skill を使用して、プロジェクトにスキルを導入できます。

# Cursorの場合
npx add-skill masayuki-kono/agent-skills -s hses-protocol moto-hses-usage hses-packet-analysis -a cursor -y

# Claude Codeの場合
npx add-skill masayuki-kono/agent-skills -s hses-protocol moto-hses-usage hses-packet-analysis -a claude-code -y

インストールすると、プロジェクトに以下のようなディレクトリ構造でスキルが配置されます。

.agents/
└── skills
    ├── hses-packet-analysis
    │   └── SKILL.md
    ├── hses-protocol
    │   ├── references
    │   │   ├── data-types.md
    │   │   ├── error-codes.md
    │   │   ├── protocol-overview.md
    │   │   └── ...
    │   └── SKILL.md
    └── moto-hses-usage
        ├── references
        │   ├── examples
        │   │   ├── alarm_operations.rs
        │   │   ├── job_start.rs
        │   │   ├── read_status.rs
        │   │   └── ...
        │   └── protocol-commands.md
        └── SKILL.md

Cursorの場合は .cursor/skills/ 配下にシンボリックリンクが作成され、AIエージェントがスキルを参照できるようになります。add-skillの詳しい使い方については公式リポジトリを参照してください。

スキルをインストールすると、AIエージェントがHSESプロトコルを理解し、moto-hsesを使った適切なコードを生成できるようになります。

Agent Skillsを使ったコード生成デモ

スキルの効果を検証するため、Cursor Agentにコードを生成させました。生成したコードはmoto-hses-examples リポジトリで公開しています。

生成プロンプト

以下のシンプルなプロンプトを入力しました。

moto-hsesを使用したRustサンプルアプリケーションを開発してください。アプリ起動時にサーボをONにして、指定したジョブを起動してください。ロボットコントローラのIPアドレスはコマンドライン引数で指定できるようにしてください。

生成されたアプリケーション

上記プロンプトから、Cursor Agentが以下の機能を持つアプリケーションを自動生成しました。

コマンドライン引数でロボットコントローラのIPアドレスとジョブ名を指定
ロボットコントローラへ接続
サーボをONに設定
指定されたジョブを選択して起動
起動状態を確認して結果を表示

実行例

# ロボットコントローラ（192.168.0.18）に接続し、ジョブ "TEST" を起動
cargo run -- 192.168.0.18 TEST

実行すると以下のような出力が得られます。

[2026-01-26T21:50:24Z INFO  moto_hses_examples] Connecting to robot controller: 192.168.0.18:10040
[2026-01-26T21:50:24Z INFO  moto_hses_examples] ✓ Successfully connected to controller
[2026-01-26T21:50:24Z INFO  moto_hses_examples] Reading initial status...
[2026-01-26T21:50:24Z INFO  moto_hses_examples] ✓ Status read successfully
[2026-01-26T21:50:24Z INFO  moto_hses_examples]   - Running: false
[2026-01-26T21:50:24Z INFO  moto_hses_examples]   - Servo ON: true
[2026-01-26T21:50:24Z INFO  moto_hses_examples]   - Alarm: false
[2026-01-26T21:50:24Z INFO  moto_hses_examples]   - Error: false
[2026-01-26T21:50:24Z INFO  moto_hses_examples] Turning servo ON...
[2026-01-26T21:50:24Z INFO  moto_hses_examples] ✓ Servo ON command sent successfully
[2026-01-26T21:50:25Z INFO  moto_hses_examples] ✓ Servo is now ON
[2026-01-26T21:50:25Z INFO  moto_hses_examples] Selecting job 'TEST'...
[2026-01-26T21:50:25Z INFO  moto_hses_examples] ✓ Job 'TEST' selected successfully
[2026-01-26T21:50:25Z INFO  moto_hses_examples] Starting job 'TEST'...
[2026-01-26T21:50:25Z INFO  moto_hses_examples] ✓ Job start command sent successfully
[2026-01-26T21:50:25Z INFO  moto_hses_examples] ✓ Job 'TEST' started successfully

自作のクライアントライブラリであり、Web上に活用事例がほとんど存在しない状況でも、Agent Skillsによってドメイン知識を補完することで、LLMが適切なコードを生成できることが確認できました。

Agent Skillsを使ったパケット解析デモ

次に、通信障害時のデバッグにスキルを活用する例を紹介します。hses-packet-analysis スキルは、tsharkでパケットをキャプチャし、hses-protocol スキルのプロトコル仕様と照合してレポートを出力します。このようにスキル間で連携することで、複雑な解析タスクにも対応できます。

障害シナリオの作成

検証のため、Status Reading（0x72）コマンドの応答パケットをモックサーバー側で意図的に不正なデータに書き換えて返信してみます。

Status Reading の Data 1 フィールドは 4バイト（32ビット）ですが、有効なステータスビットは下位8ビットのみ使用されます。

ビット	内容
Bit 0	Step モード
Bit 1	One Cycle モード
Bit 2	Continuous モード
Bit 3	Running（動作中）
Bit 4	Speed Limited
Bit 5	Teach モード
Bit 6	Play モード
Bit 7	Remote モード
Bit 8-31	未使用（常に0であるべき）

仕様違反の内容

Data 1 の上位バイト（Bit 16-23）に値 0x01 を設定し、定義された値域を超過させます。

期待値: [0x00][0x00][0x00][0x00]  （上位3バイトは常に0）
実際:   [0x00][0x00][0x01][0x00]  （3バイト目に0x01）
         ↓    ↓    ↓    ↓
        Bit  Bit  Bit  Bit
        0-7  8-15 16-23 24-31
                   ↑
              不正な値

この状態で先ほど生成したアプリケーションを実行すると、以下のエラーログが出力されます。

[2026-01-27T21:18:54Z INFO  moto_hses_examples] Connecting to robot controller: 192.168.0.18:10040
[2026-01-27T21:18:54Z INFO  moto_hses_examples] ✓ Successfully connected to controller
[2026-01-27T21:18:54Z INFO  moto_hses_examples] Reading initial status...
[2026-01-27T21:18:54Z ERROR moto_hses_examples] ✗ Failed to read status: Protocol error: deserialization error: Invalid status word value
Error: ProtocolError(Deserialization("Invalid status word value"))

Invalid status word valueエラーが発生しました。ここで hses-packet-analysis スキルを使ってLLMにパケット解析をしてもらいましょう。

解析プロンプト

以下のプロンプトを入力しました。

cargo run -- 192.168.0.18 TEST が失敗します。パケット解析してマークダウンに結果を出力して。

解析結果

以下の解析レポートが出力されました。スキルはパケットキャプチャを実行し、プロトコル仕様と照合して問題箇所を特定しています。

レポートの構成

出力されるレポートには、プロトコル検証結果、シーケンス図、パケット詳細（バイナリ解析）、推奨対応を含みます。今回は Status Data 1 の bit 16 に不正な値がセットされているという仕様違反を原因として特定しました。

HSES Protocol Analysis Report

Generated: 2026-01-28 06:19:36
Capture File: hses_capture_20260128_061936.pcap
Export File: hses_export_20260128_061936.txt

1. Summary

Metric	Value
Total Packets	2
Requests	1
Responses	1
Errors	0 (protocol level)
Duration	0.000136 sec

Issue Detected: Application error "Invalid status word value" - the robot controller returned a status value with an unexpected bit set (bit 16) that is not defined in the protocol specification.

2. Protocol Validation

Check	Result	Details
Magic bytes	✅ Pass	Both packets start with "YERC" (0x59455243)
Header size	✅ Pass	All headers are 32 bytes (0x0020)
Reserved (byte 8)	✅ Pass	Value is 0x03
Reserved (bytes 16-23)	✅ Pass	Value is "99999999"
Division	✅ Pass	0x01 (Robot)
ACK field	✅ Pass	Request=0x00, Response=0x01
Block number	✅ Pass	Request=0, Response=0x80000000 (single)
Request/Response pairs	✅ Pass	1 request matched with 1 response
Service code match	✅ Pass	Response service (0x81) = Request service (0x01) + 0x80
Command ID	✅ Pass	0x72 (Status reading) is valid
Response status	✅ Pass	0x00 (Normal reply)
Payload validity	⚠️ Warning	Status word contains undefined bit 16

Payload Analysis Issue

The response payload contains status data with an unexpected value:

Expected: Status Data 1 should only use bits 0-7 (bits 8-15 are reserved)
Received: 0x00010000 (bit 16 is set)
Consequence: moto-hses library rejects this value as "Invalid status word value"

3. Sequence Diagram

sequenceDiagram
    participant C as Client
    participant R as Robot Controller

    C->>R: Status Reading (0x72) Instance=1
    R-->>C: Status=0x00 (OK), Data=0x00010000
    Note over C: Deserialization failed:<br/>Invalid status word value

4. Communication Sequence

#	Time (sec)	Direction	Command	Instance	Status	Description
1	0.000000	Request	Status Reading (0x72)	1	-	Read Status Data 1
2	0.000136	Response	Status Reading	-	0x00 (OK)	Returned status=0x00010000

5. Protocol Errors

No protocol-level errors detected. However, an application-level deserialization error occurred.

#	Time	Command	Issue	Meaning
2	0.000136	Status Reading	Status word bit 16 set	Robot returned status data with undefined bit, causing deserialization failure

Root Cause Analysis

The robot controller returned Status Data 1 with value 0x00010000, which has bit 16 set. According to the HSES protocol specification:

Status Data 1 (Command 0x72, Instance 1) bit definitions:

Bit	Meaning
0	Step mode
1	One-cycle mode
2	Continuous mode
3	Running
4	Speed limited
5	Teach mode
6	Play mode
7	Remote mode
8-15	Reserved

Bit 16 is not defined in the specification. The moto-hses library strictly validates status values and rejects undefined bits.

Possible causes:

Newer firmware version with extended status bits not yet documented
Controller-specific extension to the protocol
Memory/data corruption on the controller

6. Packet Details

Packet 1 - Request

Field	Value	Description
Time	0.000000	Start of capture
Type	Request	ACK=0x00
Magic	YERC	0x59455243
Header Size	32	0x0020
Payload Size	0	No payload
Division	Robot	0x01
Request ID	1	Session ID
Block Number	0	Request block
Command ID	0x0072	Status reading
Instance	1	Status Data 1
Attribute	0	Default
Service	0x01	Get_Attribute_All

Raw Hex:

59455243 2000 0000 03 01 00 01 00000000 3939393939393939 7200 0100 00 01 0000
│        │    │    │  │  │  │  │        │                │    │    │  │  │
│        │    │    │  │  │  │  │        │                │    │    │  │  └─ Padding
│        │    │    │  │  │  │  │        │                │    │    │  └─ Service (Get_Attribute_All)
│        │    │    │  │  │  │  │        │                │    │    └─ Attribute
│        │    │    │  │  │  │  │        │                │    └─ Instance (1)
│        │    │    │  │  │  │  │        │                └─ Command ID (Status reading)
│        │    │    │  │  │  │  │        └─ Reserved "99999999"
│        │    │    │  │  │  │  └─ Block Number (0)
│        │    │    │  │  │  └─ Request ID (1)
│        │    │    │  │  └─ ACK (Request)
│        │    │    │  └─ Division (Robot)
│        │    │    └─ Reserved (0x03)
│        │    └─ Payload Size (0)
│        └─ Header Size (32)
└─ Magic "YERC"

Packet 2 - Response

Field	Value	Description
Time	0.000136	136μs after request
Type	Response	ACK=0x01
Magic	YERC	0x59455243
Header Size	32	0x0020
Payload Size	8	Status data
Division	Robot	0x01
Request ID	1	Matches request
Block Number	0x80000000	Single response
Service	0x81	Get_Attribute_All + 0x80
Status	0x00	Normal reply
Added Status Size	2
Added Status	0x0000	No error

Payload Data:

00000100 00000000
│        └─ Status Data 1 part 2: 0x00000000
└─ Status Data 1 part 1: 0x00010000 (bit 16 set - UNEXPECTED)

Raw Hex:

59455243 2000 0800 03 01 01 01 00000080 3939393939393939 81 00 02 00 0000 0000 | 00000100 00000000
│        │    │    │  │  │  │  │        │                │  │  │  │  │    │      │
│        │    │    │  │  │  │  │        │                │  │  │  │  │    │      └─ Payload (8 bytes)
│        │    │    │  │  │  │  │        │                │  │  │  │  │    └─ Padding
│        │    │    │  │  │  │  │        │                │  │  │  │  └─ Added Status (0x0000)
│        │    │    │  │  │  │  │        │                │  │  │  └─ Padding
│        │    │    │  │  │  │  │        │                │  │  └─ Added Status Size (2)
│        │    │    │  │  │  │  │        │                │  └─ Status (0x00 = OK)
│        │    │    │  │  │  │  │        │                └─ Service (0x81 = 0x01 + 0x80)
│        │    │    │  │  │  │  │        └─ Reserved "99999999"
│        │    │    │  │  │  │  └─ Block Number (0x80000000 = single)
│        │    │    │  │  │  └─ Request ID (1)
│        │    │    │  │  └─ ACK (Response)
│        │    │    │  └─ Division (Robot)
│        │    │    └─ Reserved (0x03)
│        │    └─ Payload Size (8)
│        └─ Header Size (32)
└─ Magic "YERC"

7. Recommendations

Investigate controller firmware - Check if the robot controller has a newer firmware that uses extended status bits
Update moto-hses library - Consider relaxing status validation to ignore unknown bits (mask with 0x00FF for Status Data 1)
Contact Yaskawa - If the issue persists, consult Yaskawa support about the meaning of bit 16 in Status Data 1

シンプルなプロンプトから、パケットのバイナリデータをプロトコル仕様と照合し、原因を特定してくれました。このように、Agent Skillsを活用することで通信障害のデバッグ作業もLLMに任せることができます。

まとめ

本記事では、安川ロボットコントローラのHSES通信クライアント（moto-hses）とAgent Skillsを組み合わせた取り組みを紹介しました。

コード生成: moto-hses-usage スキルにより、LLMがmoto-hsesを使った適切な通信コードを自動生成
パケット解析: hses-packet-analysis スキルにより、通信障害時のデバッグをLLMに委任

産業用ロボットのプロトコル仕様はPDFとして配布されていたり、ドメイン知識が必要だったりとLLMには扱いにくい情報ですが、Agent Skillsの形式に整備すればこの課題を解決できます。コード生成から保守・デバッグまで、一貫してLLMに任せられる環境が整いつつあります。

今後の展望

各社ロボットコントローラがROS2のようなフレームワークに対応し、共通I/Fで利用できるようになる未来も想定されますが、コントローラ側の歩み寄りが必要であり現実的には難しいと考えています。また、各社ロボットには様々な独自仕様（溶接のような用途別の機能など）があり、共通I/Fでは吸収しきれない部分も存在します。

コントローラのI/Fが異なっていてもスキルが提供されれば、必要とするアプリケーションの開発をLLMが行うことは可能です。各社ロボットコントローラに対する様々なスキルを作成してゆき、ロボットシステム開発においてLLMが担える部位を増やしてゆきたいと考えています。

無料のOSSツールSysONで始めるSysMLv2モデリング（３）〜 Part Definitionの作成

2026-01-22T00:00:00.000+00:00

前回の記事では、新しいプロジェクトとPackage要素を作成しました。

/blogs/2026/01/15/sysmlv2-tool-syson-pkg/

本記事では、構造定義の要の１つである Part Definitionを作成します。

執筆時点における SysONの安定版は v2025.12.0が最新ですが、本記事では前回同様 v2025.8.0を使用します。
最新リリースの挙動は一部異なる可能性がありますのでご了承ください。

モデリングの題材は、SysMLv2の仕様書 A Annex: Example Modelから拝借します。
"Figure 59. Axle and its Subclass FrontA"を作成してみましょう。

新規のPart Definitionを作成する

前回と同じように General Viewを表示し、右クリックで表示されるコンテキストメニューから "Structure" > "New Part Definition"を選択します。

すると、General Viewに Part Definitionが表示されます。

Part Definitionの名前を変更する

作成した Part Definitionの名前を"Axle"に変更しましょう。

名前を変更する方法は２つあります。
後述しますが、この２つの方法はくわしくみると動作が異なります。

変更方法その１

１つは右サイドバーで変更する方法です。
対象の要素（PartDefinition1）を選択すると右サイドバーに Detailsが表示されます。
その Declared Nameの欄に表示されている名前を直接編集します。

変更方法その２

もう１つは要素のコンテキストメニューやファンクションキーで変更する方法です。
コンテキストメニューを表示して上部に並んでいるアイコンの中で最も左にあるペンアイコンをクリックします。

ペンアイコンをクリックすると、要素内に表示された名前を直接編集できるようになります。
コンテキストメニューで、ペンアイコンではなく "Edit" > "Edit"を選択しても同様に名前を直接編集できるようになります。

要素を選択して F2キーを押下しても同様に名前を直接編集できます。

Part DefinitionにAttributeを追加する

次は、"Axle"の attributesに"mass"を追加しましょう。

"Axle"を選択してコンテキストメニューを表示し、"Structure" > "New Attribute"を選択します。
"Axle"にattributes区画が表示され、その区画に"attribute1"が追加されます。

追加された"attribute1"を選択し、その名前を"mass :> ISQBase::mass"に変更します。

コンテキストメニューかファンクションキーを用いた方法で変更した場合、右サイドバーの Detailsに Subsetsの項目があらわれ、そこに massが表示されます。

"attribute1"の名前を左サイドバーの Detailsにある Declared Nameで変更した場合、図の見た目は同じですが Detailsに Subsetsの項目はあらわれません。

これはどういうことでしょうか。

前者（コンテキストメニューなどで変更）の場合は、subsetsの記号（:>）が解釈されて massが ISQBase::massの subsetsになります。
一方後者（Declared Nameで名前を変更）の場合は、単純に名前が"mass :> ISQBase::mass"に変更されます。

この違いは図の見た目だけではわからないため注意してください。

Part Definition間にSubclassificationを設定する

Axleと同様の手順でもう１つ Part Definitionを作成して名前を"FrontAxle"にします。

"FrontAxle"を選択した時に要素の上下左右に表示される三角（＞）の位置にマウスをあわせるとマウスのポインタが十字（＋）に変わります。
この状態で"Axle"にドラッグ＆ドロップすると、relationshipを選択するコンテキストメニューが表示されます。

ここで、"New Subclassification"を選択すると、Subclassificationをあらわす白抜き矢印の線が表示されます。
加えて、"FrontAxle"の名前が"FrontAxle :> Axle"に変更されます。

Subclassificationを設定するもう１つの方法があります。
それは、"FrontAxle"をコンテキストメニューもしくはファンクションキーで"FrontAxle :> Axle"に変更する方法です。
変更すると、"FrontAxle"の表示が変わるとともに、Axleとの間に Subclassificationをあらわす線が表示されます。

"FrontAxle"に"steering"の attributeを追加します。

SysMLv2仕様書の"Figure 59. Axle and its Subclass FrontA"と等価な図ができました。

テキスト記法を用いたPart Definitionの追加

ここまで作図でモデルを作成してきましたが、Packageと同様テキスト記述を用いたモデル作成もできます。

part def Axle {
	attribute mass:>ISQ::mass;
}
part def FrontAxle :> Axle {
	attribute steeringAngle :> ISQ::angularMeasure;
}

作成された Axleと FrontAxleを General Viewにドラッグ＆ドロップします。

attribute区画を表示するにはまず、Part Definitionの名前の右にマウスカーソルをあわせた際に表示される目のアイコンをクリックします。
表示された"Manage Visibility"コンテキストメニューの"attribute"にチェックを入れます。

次回予告

本記事では、Part Definition要素を作成し要素間に Subclassificationを設定しました。

次回は、Part Usageを作成し、Part Definitionとの関連付けを行います。

Slackアプリで始める業務日誌（その１）- 基本操作 -

2026-01-19T00:00:00.000+00:00

1. はじめに

先日、業務日誌について書いた投稿がこちらになります。

/blogs/2026/01/06/businessdiary/

ただ、

ここは技術ブログなので、記事だけだと片手落ちな気がする。
自分は技術者なんだから、せっかくだから何か作りたい。

と思いましたので、業務日誌を題材にアプリを作りました。
（あくまで学習用のサンプルアプリになりますが）

また、最近、社内研修で要件定義、設計、文章の書き方などを
学びましたので、練習を兼ねてこれらも実施しました。

そこで、本記事では、業務日誌アプリを題材に
要件定義〜設計をどのように整理したかを中心に紹介します。
私と同じようにアプリを作成するエンジニアの方向けに、設計の良し悪しではなく、作業の過程について共有できればいいなと思っています。
なお、実装したアプリそのものについては、本記事では割愛し、別記事で公開したいと思います。

2. アプリを開発する

まず、今回のゴールとしては、業務日誌を作成するアプリの必要最低限の機能のみを開発します。
前回のブログでSlackを使用して業務日誌を作成していることに触れていることも踏まえ、
今回はSlackのアプリを作成してみます（技術要素は別途、以下で整理します）。
開発は以下の手順で進めます。
1. 要件定義
2. 設計
3. 製造・テスト（ブログ上では詳細割愛）

2-1. 要件定義

本記事で中心となる内容で、少し記述量が多くなってしまいましたが、
よろしければお付き合いいただければと思います😓
要件定義では、要望→要求→要件→仕様の順に作成していきます。

2-1-1. 要望を書いてみる。

まず、要望ですが、要望とは「システム（今回はアプリ）で実現したいこと」となります。
とりあえず、業務日誌アプリでできそうなことを思いつくまま書き出してみます。

Information

業務日誌を自動で作成してほしい。
手書きは面倒なので、アプリで自動生成してほしい。
業務日誌を自動で報告してほしい。
Slackのチャネル投稿するなど、報告を自動化したい。
決められた時間に業務日誌を作成・報告してほしい。
定時前などスケジュールに基づいて業務日誌を作成・報告してほしい。
業務日誌の体裁を調整したい。
業務日誌のテンプレートを作成して、日誌の体裁を整えたい。
作業は随時登録したい。
業務日誌に記載する作業は、業務中につど登録したい。
（日誌を作成時に考えるのは、効率的ではないので、事前に登録しておきたい）
作業の状況を管理したい。
作業状況が分かるようにしたい。
登録した作業は保管しておきたい。
アプリを停止、再開した後も作業が参照できるようにしたい。
作成した業務日誌は保管しておきたい。
アプリを停止、再開した後も業務日誌が参照できるようにしたい。
業務日誌の要約したい。
作成済みの複数日の業務日誌を要約して、週報、月報、あるいは、評価面談用の資料としたい。
フィードバックがほしい。
作成した業務日誌の内容についてフィードバックがほしい。
（AIとかにレビューさせるとかできるかも）

2-1-2. 要求を書いてみる。

次に、要求ですが、要求とは「要望の内、実現するものとして採用されたもの」となります。
今回は、業務日誌アプリとして必要な最低限な要望のみを要求として選択します。
よって、要求は以下のとおりとします。

Information

作業を登録したい。
業務中に実施する作業を登録できるようにします。
登録した作業を確認したい。
登録した作業が確認できるようにしたい。
作業のステータスを設定したい。
登録済みの作業に対して、作業ステータスが設定できるようにします。
作業ステータスは、以下のとおりとします。
- 未着手
- 作業中
- 完了
業務日誌を作成したい。
登録済みの作業から業務日誌を作成します。
業務日誌には「当日実施した作業一覧」と「翌日実施する作業予定一覧」が登録されています。
登録した作業を保存しておきたい。
登録した作業が消失しないようにします。
作成した業務日誌を保存しておきたい。
作成した業務日誌が消失しないようにします。

1.-4.はいいかと思います。5.6.はちょっと違うような気もしますが、いったんよしとします。
登録と永続化って大抵はセットなので、どこかで1つにしたほうがいいとは思うのですが。

2-1-3. 要望のうち、要求に含めないもの。

要望として挙げたもののうち、要求としないものについても、一応明記するようにします。

Information

業務日誌の自動生成
業務日誌の生成はアプリの機能としますが、生成処理の起動は手動で行うこととします。
業務日誌の自動報告
報告は手動で行うこととします。
業務日誌のスケジュール生成
必須機能ではないので、対象外とします。
業務日誌のテンプレート
今回は業務日誌のテンプレートは決め打ちとします。
業務日誌の要約
必須機能ではないので、対象外とします。
業務日誌へのフィードバック
必須機能ではないので、対象外とします。

2-1-4. 要件を書いてみる。

続けて、上記の要求を基に要件を定義してみます。
要件とは「完成したシステムが実現することを定義したもの」となります。

Information

ユーザーは、アプリの画面から作業が登録できなければならない。
ユーザーは、アプリの画面上で、登録した作業の一覧を確認できなければならない。
ユーザーは、アプリの画面から、登録済みの作業に対して、定義された作業のステータスを設定できなければならない。
ユーザーは、アプリに業務日誌の作成を指示できなければならない。
アプリは、登録済みの作業を基に業務日誌を生成し、その内容をユーザーに提示しなければならない。
ユーザーがアプリを停止、再開しても、停止前に登録した作業が参照できなければならない。
ユーザーがアプリを停止、再開しても、停止前に作成した業務日誌が参照できなければならない。

2-1-5. 仕様を書いてみる。

最後に、仕様を定義してみます。
仕様とは「網羅的に記述された要件」となります。

Information

作業の登録

ユーザーは、画面から作業内容を入力する。
アプリは、ユーザーが入力した作業内容に加え、以下の内容を合わせて登録する。
- 作業ID
- 登録日
- 作業ステータス
作業IDは、作業を一意に特定できる識別子とする。
登録時点の現在日を登録日として登録する。登録日の書式はyyyy/MM/dd とする。
登録日は、ユーザーが作業登録を実行した時点の日本標準時（JST）に基づく日付とする。
また、作業のステータスを未着手として設定する。
作業内容は必須入力とし、前後の空白文字を除去した結果が空文字列となる場合は無効とする。
作業内容が未入力の場合、アプリは登録が失敗した旨のメッセージを表示して、処理を終了する。
作業内容として入力可能な文字数の上限は100文字とする。この時、全半角は考慮せず、どちらも1文字として扱うこととする。

作業の一覧確認

ユーザーはアプリへ登録済みの作業の一覧を表示するように指示する。
アプリは画面上に登録済みの作業の一覧を表示する。
一覧は登録した順序（作業ID）の昇順で表示する。
一覧には作業内容、登録日、作業ステータスを表示する。

作業ステータスの変更

ユーザーは、対象となる作業を指定し、作業ステータスを変更できる。
作業ステータスは、未着手、作業中、完了の3つとする。
ユーザーが存在しない作業（作業ID）を更新しようとした場合、アプリは設定が失敗した旨のメッセージを表示して処理を終了する。
ユーザーが規定のステータス以外に更新しようとした場合、アプリは設定が失敗した旨のメッセージを表示して処理を終了する。
アプリはユーザーが入力した作業IDと作業ステータスで指定された作業のステータスを更新する。
ステータス間の遷移に制約は設けないこととする。ユーザーが指定したステータスを必ず設定するようにする。

業務日誌の生成

ユーザーは画面上から、アプリに対して業務日誌の生成を指示する。
アプリはユーザーの指示を受け、登録済みの作業から業務日誌を作成する。
業務日誌には以下の項目で構成される。
- 生成日
- 当日実施した作業の一覧
- 翌日実施する作業予定の一覧
生成日は、業務日誌を生成時の現在日を表示する。
生成日の表示形式は yyyy年MM月dd日（WeekDay）とする
※WeekDayは曜日で、月、火、水..といった値となる。
生成日は、日誌作成時点の日本標準時（JST）に基づく日付とする。
当日実施した作業の一覧には、次の条件をすべて満たす作業を含める。
- 当日中に作業ステータスを更新している。
- 作業ステータスが作業中、あるいは、完了である。
翌日実施する作業予定の一覧には、次の条件をすべて満たす作業を含める。
- 作業ステータスが未着手、あるいは、作業中のどちらかである。

作業の保存

ユーザーが作業を登録した際に、アプリは作業を永続化する。
ユーザーが作業の一覧を確認する際に、アプリは作業の一覧を永続化された作業から生成する。
ユーザーが作業のステータスを設定した際に、アプリは永続化された作業のステータスを更新する。

業務日誌の保存

アプリは業務日誌を生成した時に、生成した業務日誌を永続化する。

2-2. 設計

2-2-1. 方式設計

アプリ全体の設計方針について記載します。
設計フェーズなので、具体的な技術要素についても記載します。

Information

アプリケーションはSlackアプリとして実装します。
- アプリにUIが必要ですが、デスクトップアプリを作るのはちょっと大げさだと感じました。
- 業務では、Slackを利用していますので、Slackで業務日誌を作成できると、
  作成→報告が一箇所でできるのでベターかと思いました
- Bolt for JavaScriptフレームワークを使用します。
データを永続化するために、DBを利用します。DBはSQLiteを採用します。
- 今回はローカルで動作するサンプルですので、
  軽量なインメモリデータベースで十分だと思います。
永続化層にO/RマッパーとしてDrizzle ORMを採用します。
- https://orm.drizzle.team/
- これは個人的な好みです。
開発言語はTypeScript（JavaScript）を使用します。
- 前述のBoltフレームワークではPython、JavaScriptが利用できますが、
  あいにく、Pythonは不得手ですので、得意なJavaScriptを使用します。
- Denoは使用しないこととします。
  Bolt for JavaScriptではDenoが利用でき、個人的にもDenoは嫌いではないのですが、
  Denoがそこまで浸透しているかが不明ですので、今回はいったん見送ります。

2-2-2. 機能設計

仕様の5と6、登録した作業、業務日誌の保存（永続化）は
それぞれ、1と４にマージします。
結果として機能が４つとなりますので、それぞれについて記載します。

Information

作業を登録する
1. 作業内容の入力
  1. 作業内容はアプリのDMにメッセージとして入力します。
2. 作業内容の検証
  1. 作業内容が未入力の場合、エラーメッセージを表示します。
    エラーメッセージはアプリからの返信として表示します。
  2. 作業内容が100文字を超過する場合、エラーメッセージを表示します。
    エラーメッセージはアプリからの返信として表示します。
3. 作業内容の登録
  1. 作業内容の登録はSlackアプリのコマンドを実行することで起動します。
  2. 作業内容をDBに保存します。
    保存する内容は、入力した作業内容、登録日、初期作業ステータス（未着手）になります。
作業を確認する
1. 作業一覧を表示する。
  1. コマンドを実行することで作業の一覧を表示するようにします。
    作業の一覧の各項目は、作業内容、ステータス、設定ボタンの4項目とします。
    ステータスは変更できるように、セレクトボックスで表示します。
    ステータスの初期値は登録済みの作業ステータスの値となります。
    作業の一覧は登録順（ID順）の昇順とします。
  2. 作業が未登録の場合は、エラーメッセージを表示します。
    エラーメッセージはアプリからの返信として表示します。
作業ステータスを設定する
1. 作業ステータスの更新
  1. 作業一覧に表示されている、設定ボタンを押下することで、
    作業ステータスの値を選択している値に設定します。
業務日誌を生成する
1. 業務日誌を生成する。
  業務日誌は、文章（テキスト）とします。
  業務日誌には、当日実施した作業の一覧、および、翌日実施した作業の一覧を含めます。
  当日実施した作業の一覧は、作業ステータスが作業中、あるいは、完了となっている作業となります。
  翌日実施した作業の一覧は、作業ステータスが未着手、あるいは、作業中となっている作業とします。
  該当する作業が存在しない場合は、作業の一覧ではなく、テキスト”作業が存在しません”を業務日誌に含めるようにします。
  コマンドを実行することで業務日誌を生成します。
  生成した業務日誌は、アプリからの返信として表示します。
2. 業務日誌の保存
  生成した業務日誌はDBへ保存します。
  登録内容は、業務日誌ID、登録日、業務日誌の3項目とします。

2-3. 図

設計の練習を兼ねて、作図も行います。

2-3-1. ユースケース図

2-3-2. ドメインモデル

2-3-4. ロバストネス図

3. 作成したアプリについて

アプリを作成したので、ここでは動作結果のみを記載します。
※アプリ自体については別の記事で言及できればと考えています。

3-1. 機能の動作確認

3-1-1. 作業を登録する

まずは、作業を登録します。
/task_add コマンドに、引数として作業内容を設定して送信。

登録に成功するとメッセージが返信されます。

3-1-2. 作業を確認する

次に、登録した作業を/task_listコマンドで表示します。
一覧表示は引数なしのコマンドとなります。

一覧が登録順に表示されます。
また、ステータスが更新できるようにステータスをセレクトボックスで表示し、更新処理を実行するためのボタンを配置しました。

なお、動作確認用に３つのタスクを登録しています。

3-1-3. 作業ステータスを設定する

さらにステータスを変更してみます。
３つの作業のうち、１つを作業中に、もう１つを完了に変更します。

アプリ上でステータスを変更して、更新ボタンをクリックすると、
ステータスが更新され、メッセージが返信されます。

3-1-4. 業務日誌を作成する

最後に業務日誌を生成してみます。
こちらは/businessDiary_createコマンドを実行します。

コマンドの受け付けに対して、応答を返した後、
生成された業務日誌が表示されます。
当日の作業一覧に作業中、あるいは、完了の作業が表示されます。
また、翌日の作業予定一覧に未着手、あるいは、作業中の作業が表示されます。

4. まとめ

本記事では、業務日誌を題材に、アプリケーションの要件定義、設計、実装を行ってみました。個人の学習の一環として取り組んだ内容の整理になりますが、
同じように設計に悩みながらアプリを作っている方の参考になれば幸いです。

実際に取り組んでみた所感としては、以下のように感じました。

業務外の作業なので、所々手抜きもあるのですが、
それを別にしても、まだまだ至らない点があるので、こういった作業を通じて、能力向上ができればなと思いました。
また、こういったサンプル程度のアプリでも、実際に要件定義・設計すると、
結構なボリュームになったなと感じています。
ただ、アプリの開発自体は（体感としては）スムーズに進んだようにも思えましたので、こういった要件定義、設計のプロセスというのは無駄ではないと思いました。
以前、ローコードツールを使用した開発を行っていましたが、ツールの「生成した成果物（コード）＝設計書」という思想の影響で、設計を行わずに実装することが多かったです。
ですが、今回のように設計 → 実装の流れで作業すると、ローコードでなくても、事前に設計を実施してから実装に着手したほうが作業が捗るように感じました。理由としては、実装中にトライ・アンド・エラーで作業するよりも、事前に設計を文書化するほうが、仕様をよりよく理解できるためだと思います。

業務日誌アプリについては、今後、技術習得も兼ねて、機能拡張していければと考えています。また、採用した技術要素についても、別途記事として公開できればと考えています。

無料のOSSツールSysONで始めるSysMLv2モデリング（２）〜 Packageの作成

2026-01-15T00:00:00.000+00:00

前回の記事「無料のOSSツールSysONで始めるSysML v2モデリング（１）〜はじめてのSysON」では、SysONをインストールして Webブラウザでホーム画面を表示しました。

/blogs/2026/01/08/sysmlv2-tool-syson-intro/

本記事では、新しいプロジェクトとパッケージを作成してみましょう。

本記事では Release 2025.8.0を使用しています。
最新版ではUIや挙動が異なる可能性がありますのでご了承ください。

ホーム画面はプロジェクトブラウザ画面とも呼びます。
プロジェクトブラウザ画面の上側にはプロジェクトを作成するアイコンが並びます。
その下側には既存のプロジェクトのリストが表示されます。

プロジェクトを作成する

新しい SysMLv2プロジェクトを作るには、"Create a new project"にある左から２番目の"SysMLv2"と記載されたアイコン（SysMLv2テンプレート）を選択します。

選択すると、プロジェクトエディタ画面が表示されます。

エディタ画面は、画面上部の「ツールバー」、左側の「左サイドバー」、右側の「右サイドバー」、左右サイドバーの間にある「エディタ」の４つから構成されます。

プロジェクト名を変更する

プロジェクト名は、ツールバーの中央にある"SysMLv2"です。

まずはプロジェクトの名前を変更しましょう。
ツールバーにあるプロジェクト名横のケバブボタン（︙）をクリックし"Rename"を選択すると、"Rename the project"のダイアログが表示されます。
今回は"SysMLv2.trial"と入力して"RENAME"ボタンを押下します。

ビューを表示する

左サイドバーのツリーで"General View"を選択すると、エディタに図を描く画面が表示されます。
グラフィカル記法でモデルを作成する場合は、ここに図を描いていきます。

ビューを追加する

新たにビューを追加したい場合は、左サイドバーのツリーにあるパッケージなどの要素に付いているケバブアイコン（︙）をクリックします。
表示されたコンテキストメニューから"New representation"を選択するとビューを追加するためのダイアログが表示されます。
このダイアログで名前を入力しビューの種類を指定して"CREATE"ボタンを押すとビューを追加できます。

プロジェクトブラウザ画面に戻る

プロジェクトブラウザ画面に戻る場合は、画面上部ツールバーの右端にあるハンバーガーボタン（≡）をクリックして"Projects"を選択します。

ツールバーの左端にある立方体のアイコンをクリックしても、プロジェクトブラウザ画面に戻ります。

新規のPackage要素を作成する

最初に Packageを作成してみます。

中央のエディタで空きスペースを右クリックすると、図に配置できる要素のカテゴリ一覧がコンテキストメニューに表示されます。

"Structure"を選択すると、コンテキストメニューの表示が図に配置できる"Structure"の要素の一覧に切り替わるので、"New Package"を選択します。

すると、エディタに Package要素が表示され、左サイドバーのツリーに Package要素が追加されます。
このとき、左サイドバーのツリーをみると、新しく追加した"Package1"は"General View"がある"Package1"の中に追加されていることがわかります。
右サイドツリーの"Details"にある"Declared Name"にも"Package1"と記載されています。

ここでもうひとつ、”Package1”を作成したのと同じ手順で"Package2"を追加します。

次は、左サイドバーのツリーにある"Package2"をツリーにある"Package1"の中にドラッグ＆ドロップで移動します。
その後、"Package1"を右クリックしてコンテキストメニューを表示します。

表示されたコンテキストメニューから "Related Elements" > "Add existing nested elements"を選択します。
すると、"Package1"の中に"Package2"が表示されます。

このとき、"Package1"の外に表示されている"Package2"に変化はありません。

SysMLv2仕様をみると、"Package1"と"Package2"の間に owned-membershipを表示するのがよさそうです。
今後のリリースで owned-membershipを表示するように変更されるかもしれません。

Packageをビューから削除する

"General View"には"Package2"が２つ表示されています。
このうち"Package1"の外にある"Package2"をビューから削除します。

"Package2"を選択した状態で右クリックしてコンテキストメニューを表示します。
コンテキストメニューの上部に並んでいるアイコンの中で左から４つ目にある四角に斜線が入ったアイコンをクリックします。

"Package2"はビューから削除されますが、左サイドバーのツリーには"Package2"が残っています。

Packageをビューに配置する

左サイドバーのツリーの"Package2"をエディタにドラッグ＆ドロップしてください。

ふたたび、ビューに"Package2"が表示されます。

PackageをImportする

左サイドバーのツリーでPackage右側のケバブアイコン（︙）をクリックします。
表示されたコンテキストメニューの"New object"を選択すると"Create a new object"のダイアログが表示されます。
ダイアログの"Object type"で"Namespace Import"を選択します。

すると、ツリーで先に選択したPackageの中に”Namespace Import”が追加されます。
追加された”Namespace Import”を選択すると右サイドバーの"Details"にその詳細が表示されます。
左サイドバーに表示される"Datails"の"Imported Namespace"でImportするPackageを選択するとImportの設定は完了です。

図のPackageを右クリックし、コンテキストメニューから "Related Elements" > "Add existing nested elements"を選択します。
Packageの中に表示された点線のPackageがImportをあらわします。

左サイドバーの"Details"にある"Visibility"でImportされたPackageの可視性を変更できます。

Packageをモデルから削除する

"Package1"をモデルから削除します。

"Package2"をビューから削除したのと同様の手順でコンテキストメニューを表示します。
表示したコンテキストメニュー上部のアイコンの中で、今度は左から２つ目にあるゴミ箱アイコンをクリックします。

すると、削除してよいかを確認するダイアログが表示されます。

”DELETE”ボタンを押下すると"Package1"の中にあった"Package2"ごと左サイドバーのツリーから削除され、"Package1"と"Package2"がビューから消えます。

テキスト記法を用いたPackageの追加

SysONは SysML v2の特徴であるテキスト記法を扱うこともできます。

左サイドバーのツリーで、"Package1"の右にあるケバブアイコン（︙）をクリックして、表示されたメニューから"New objects from text"を選択します。
すると、上部に"Enter or paste SysMLv2 text to create new objects in the model"と記載されたダイアログが表示されます。

ダイアログに以下を入力して"CREATE OBJECTS"のボタンを押下します。

package Package2 {
	package 'Package 3' {
	}
}
package 'パッケージ' {
}

左サイドバーのツリーに"Package2", "Package3", "パッケージ"の３つのパッケージが追加されます。
続けて追加しない場合は"CLOSE"ボタンでダイアログを閉じます。

テキスト記法では、パッケージ名をシングルクオート（'）で囲むと日本語や半角スペースを入れた文字列を使うことができます。

次回予告

本記事では、新しいプロジェクトを作成し、パッケージを追加しました。

次回は Part Definition要素を作成します。

スクラムマスターのAI活用を考える - 透明性

2026-01-15T00:00:00.000+00:00

はじめに

アジャイルグループの石田です。

第1回：導入の続編です。前回は、スクラムガイド拡張パックを参考に、AIがスクラムを強化する可能性の一つとして「経験的プロセス制御」の強化について触れました。

スクラムマスターとして、スクラムというプロセスにAIを活用することで、チームが実践するスクラムの三本柱「透明性・検査・適応」をより強化することができます。

透明性へのアプローチ

本記事では、三本柱の第一歩である「透明性」に着目します。ここでいう透明性とは、単に見えるようにすることではなく、チームが正しい判断（検査・適応）を行うための材料を揃えることに他なりません。

今回はAIにデータの分析そのものを依頼するのではなく、「可視化のためのツール作成（コーディング）をAIに任せる」というアプローチを紹介します。
具体的には、JiraのデータをGoogle Apps Script (GAS)で取得・加工し、可視化するプロセスをAIと共に実装した事例をご紹介します。

なぜAIに「可視化ツール」を作らせるのか

スクラムマスターがチームの状態を正しく観測するために、またチームメンバー自身が自分たちを客観視するために、定量的なデータは不可欠です。

Jiraなどのプロジェクト管理ツールには標準的なレポート機能が備わっていますが、現場では「もう少しこの切り口で見たい」「外部スプレッドシートの情報と突き合わせたい」といった、標準機能ではカバーしきれないニーズが頻繁に発生します。
Jiraには強力なAPIが用意されており、データを自由に扱うことが可能ですが、開発専任ではないスクラムマスターにとって、ゼロからツールを開発するのは学習コストや時間の面でハードルが高いのが現実です。

そこで活用したいのが、生成AIにコードを書かせ、「スクラムマスター専属のエンジニア」として振る舞わせる方法です。これにより、技術的な壁を取り払い、スクラムマスターとしての機動力を劇的に高めることができます。

実際のプロダクトコードにAI生成コードをそのまま使うことには保守性の観点から慎重な議論が必要ですが、チーム内部で使う一時的なツールやダッシュボードを作るという観点では、積極的に活用してこそ価値が発揮される領域だと考えます。

ここから先は、実際に業務で行った生成AIでのチーム可視化の実例をご紹介します。

実践例1：Four Keysによる開発スピードと安定性の可視化

Four Keysとは

まずは、今回可視化の対象とした「Four Keys」について簡単に触れておきます。
Four Keysは、GoogleのDevOps Research and Assessment（DORA）チームが提唱した、ソフトウェア開発チームのパフォーマンス（デリバリー能力）を測定するための4つの指標です。

デプロイの頻度 (Deployment Frequency): 本番環境へのリリースの頻度。
変更のリードタイム (Lead Time for Changes): コードがコミットされてから本番環境で稼働するまでの時間。
変更障害率 (Change Failure Rate): デプロイが原因で障害が発生した割合。
サービス復元時間 (Time to Restore Service): 障害発生から復旧までの時間。

これらは、開発の「スピード（1と2）」と「安定性（3と4）」を示す指標です。
これらの指標を計測することで、チームが速く、かつ安定して価値を届けられているかを客観的に把握できます。

指標の定義は明確ですが、いざ自分たちの環境で計測しようとすると、いくつかの壁にぶつかりました。

まず、変更のリードタイム（開発着手からリリースまでの時間）はJiraのステータス遷移履歴から計算可能ですが、標準のレポート機能だけで算出するのは難しく、APIによるデータ取得と計算処理が必要になります。
また変更障害率については、今回のプロジェクトでは商用障害をGoogleスプレッドシートで管理しているため、そのデータとJiraのリリース情報を突き合わせて計算する必要がありました。

このように散在するデータを集計し、Four Keysダッシュボードを構築するためにGoogle Apps Script (GAS)を採用しました。そして前述の通り、そのコード作成は生成AIに任せました。

1. Jiraから「スピード」を抽出する

まず、Jira APIを通じてチケットデータを取得するスクリプトをAIに作成させました。
プロンプトのポイントは、「ステータスの遷移履歴」に着目させたことです。

プロンプトのイメージ:
「Jiraの特定のプロジェクトから、完了したチケット情報を取得したい。各チケットが『In Progress』になった日時と、そのチケットを含むリリースが完了になった日時を抽出し、その差分をリードタイムとして計算するGASの関数を書いてください。」

これにより、チケットごとのリードタイムと、月ごとのリリース回数（デプロイ頻度）が自動集計できるようになりました。

2. スプレッドシートから「安定性」を計算する

次に、障害管理をしているスプレッドシートへのアクセスです。
こちらは、月ごとの障害発生件数をカウントし、先ほど算出したデプロイ回数と突き合わせることで「変更障害率」を算出させます。

これらを最終的に一つのスプレッドシート上のグラフとして描画することで、チームの「Four Keys」が日次で更新されるダッシュボードが完成しました。

こうして最新のFour Keysをチーム全員がいつでも見られる状態にしたことで、自分たちのリリース頻度や、それに伴う品質への影響（障害）がひと目でわかるようになり、チームの「スピード」と「安定性」が透明化されました。

実践例2：リリース必達案件における「加速」の可視化

2つ目は、少しスクラムの枠を超えた対応についてです。
プロジェクトの特性上、リリース日が固定されている「必達案件」があり、その対応に追われていました。本来のスクラムであれば、ベロシティの実績に基づいてスコープを調整すべきですが、この案件ではスコープも固定されており、従来のベロシティのままではリリースに間に合わないことが判明しました。

そこで現実的な対応として、開発者の稼働（人数や時間）を一時的に増やし、ペースアップを図るという決断をしました。

しかし、単に稼働を増やしたといっても、それによって開発スピードがどれだけ上がったのか、今のペースで本当に期日に着地できるのかは、従来のバーンダウンチャートだけでは直感的に分かりづらい状態でした。
「頑張ってはいるが、間に合うかどうかわからない」という不安な状態は、チームの士気を下げてしまいます。

そこで、ここでもAIを活用しました。
Jira APIから取得した「日々の消化ポイント数（実績）」をベースに、残作業を消化するのにあと何日かかるかを計算し、「予測完了日」の推移をプロットするスクリプトをAIに作成させました。

これにより、稼働を上げたあとにグラフの傾きが急になり（消化ペースが上がり）、予測完了日がリリース日手前まで近づいてくる様子が可視化されました（下の図はイメージです）。チームとステークホルダーに対し「現在の加速具合なら○日に終わる」という明確な見通しを提示できたことで、漠然とした不安を払拭し、開発メンバーが自信をもって仕事を進める手助けをすることができました。

AIがもたらす「スクラムマスターの機動力」

これまで「こういうデータがあったらいいな」と思っても、技術的なスキル不足や時間の制約で諦めていた可視化が、AIペアプログラミングによって数時間で実現可能になりました。

透明性は、鮮度が命です。
問題が起きそうだと感じた時、すぐにその状況を可視化するツールを自分自身の手で作れることは、チームを守るスクラムマスターにとって強力な武器になります。
「見えない不安」を即座に「見える課題」に変えられる機動力こそが、AIを活用する最大のメリットかもしれません。

まとめと次回予告

本記事では、AIを活用してGASを書くことで、Jiraやスプレッドシートに眠るデータを掘り起こし、チームに必要な透明性を素早く、低コストで実現した事例を紹介しました。
これは、スクラムガイド拡張パックで示唆されている「AIによる経験的プロセス制御の強化」を実践するための第一歩です。

しかし、透明性はゴールではありません。見えたデータを元にどう判断し、行動を変えるかが重要です。
次回の第3回「検査・適応」では、透明性とはまた違った視点、あるいは可視化された情報を元にした意思決定の場面でのAI活用についてご紹介します。

GOLDEN Kubestronaut 到達レポート

2026-01-12T00:00:00.000+00:00

昨年の 2025 年 1 月に Kubestronaut の称号を得たのに続き、同年 12 月に GOLDEN Kubestronaut の称号を得たので、その記録をまとめます。

流れは以下です。

GOLDEN Kubestronaut とは: GOLDEN Kubestronaut について簡単に記述
本記事のスコープ: 本記事で記載する範囲について記述
試験の特徴と関係性: GOLDEN Kubestronaut の取得に必要な試験の特徴と関係性について記述
学習方法: 私の学習方法について記述
終えてみて: GOLDEN Kubestronaut の取得を終えてみての所感を記述
各試験への取り組み: それぞれの試験ごとに、取り組みや所感を記述

GOLDEN Kubestronaut とは

GOLDEN Kubestronaut とは、すべての CNCF 認定資格と LFCS に合格すると得られる称号です。GOLDEN Kubestronaut の前段階に Kubestronaut があり、それはその中の 5 つに合格すると称号が得られます。

以下が、Kubestronaut の要件と、GOLDEN Kubestronaut に追加で必要なものです（私が受験した順に記載しています）。

Kubestronaut 要件
- Certified Kubernetes Application Developer (CKAD-JP)
- Certified Kubernetes Administrator (CKA-JP)
- Certified Kubernetes Security Specialist (CKS-JP)
- Kubernetes and Cloud Native Associate (KCNA-JP)
- Kubernetes and Cloud Native Security Associate (KCSA)
GOLDEN Kubestronaut 追加要件
- OpenTelemetry Certified Associate (OTCA)
- Istio Certified Associate (ICA)
- Cilium Certified Associate (CCA)
- Certified Argo Project Associate (CAPA)
- GitOps Certified Associate (CGOA)
- Prometheus Certified Associate (PCA)
- Certified Backstage Associate (CBA)
- Kyverno Certified Associate (KCA)
- Certified Cloud Native Platform Engineering Associate (CNPA)
- Linux Foundation Certified System Administrator (LFCS-JP)

この様に、Kubestronaut だけで 5 個、GOLDEN Kubestronaut には合計 15 個の認定が必要になります。Kubestronaut の称号は 5 つの認定のいずれかを失効すると消失するのですが、GOLDEN Kubestronaut の称号は生涯有効です。

なお、上記の要件は、CNCF に新たな認定試験が追加になるとアップデートされます。具体的には、2026/03/01 に GOLDEN Kubestronaut の要件に以下の試験が追加になるとアナウンスされています。ただ、一度 GOLDEN Kubestronaut に到達すれば、その後に要件が追加されたとしても、それに新たに合格する必要はありません。

Certified Cloud Native Platform Engineer (CNPE)

余談ですが、各試験の料金は、頻繁に行われるセールやクーポンを使うことで、概ね正規料金の 40%〜50%オフにできます。

本記事のスコープ

本記事では、主に、Kubestronaut から GOLDEN Kubestronaut へのステップアップに追加で必要な認定試験について取り上げます。Kubestronaut までに必要な認定試験については、すでに多くの情報が公開されているので、このレポートの中では割愛します。

試験の特徴と関係性

試験の特徴

追加要件の試験を総合的に見ると、その特徴は、以下のようであると思います。

クラウドネイティブ関連が広くカバーされている: それぞれの試験を個別に見ると、その殆どは、特定のプロダクトに関する知識やスキルが問われる（CGOA と CNPA は例外）。しかし全体をまとめてみると、セキュリティを始め、オブザーバビリティやガバナンス。また、GitOps とデリバリー、そして IDP など、クラウドネイティブに関する主要な要素が広くカバーされている。
ほとんどは選択式試験（ただし英語）: 現在のところ、ICA と LFCS、そして今後追加になる CNPE 以外は、選択式試験。そのため各試験は、英語がそれなりに読めれば、比較的容易。ただ CGOA と CNPA は、特定のプロダクトを対象としない反面、その問題文が理念や考え方を問われるややこしいものになるため、若干、英語のリーディング能力が問われる。

試験の関係性

それぞれの試験で扱うプロダクトや技術領域に類似や関連があり、ある試験で得た情報が他の試験で役立ちます。各試験が対象とする技術領域と、私が受験した順番の中で感じた各試験の関連は以下のような感じです。

ちなみに、"()"の数字が私の受けた順番で、以下のようにしました。

興味のあるものを先に受ける: オブザーバビリティには興味があったので OTCA は先に受けました。PCA も同じ領域ですが、Prometheus 固有のクエリ言語(PromQL)を覚えるのが面倒そうだったので、後に回しました。
難易度が高そうな実技試験を先に受ける: 実技試験は選択式よりも難易度が高いので、実技試験の ICA は先にしました。LFCS も実技試験ですが、ほかと趣が違うので、後にしました。
関連が強い試験は続けて受ける: 同じ技術領域である ICA と CCA、同じく GitOps を扱う CAPA と CGOA は続けて受けました。
知識や情報の少ない試験は後にする: 知識が薄かった PCA, CBA, KCA や、後で要件に加わって情報が少なかった CNPA は後回しにしました。

全体を通してみて、私が感じた中では、CKS の学習で得た知識が最も多く他の試験で役立ちました。

その一方で、CNPA は他の多くの試験で得られる知識が広く必要でした。これは裏を返すと、「CNPA を先に受験すれば、そこで得た知識は他の多くの試験で役に立つ」ということになります。CNPA を先に受けるか後にするかは人それぞれかと思いますが、CNPA は試験問題の英文が難しいので、私のように英語が苦手な人は後にしたほうが良いかもしれません。

学習方法

学習方法は、基本は Kubestronaut 要件の認定資格を受験したときと同じで、以下のパターンでした。

e-learning: KodeKloud や Udemy で提供されているそれぞれの試験対策のコースを受講。
模擬試験: KodeKloud や Udemy の試験対策コースに付帯されている模擬試験を受けるともに、Udemy で追加の模擬試験コンテンツを購入して実施。
ハンズオン: 手持ちの Linux PC で k8s 環境を作って試験カリキュラムに含まれる内容を実践。また、一部の試験については、Killercoda でハンズオン環境が提供されているので、そちらも活用。
リファレンス参照: 試験対象のプロダクトのリファレンスを参照し、試験カリキュラムに含まれる部分をチェック。

e-learning

基本的に、KodeKloud や Udemy で提供されているそれぞれの試験対策のコースを受講しました。それ以外にも、Linux Foundation や Tetrate Academy の e-learning など、試験に関係しそうな無料コンテンツがあれば見ておきました。

難点として、日本語字幕付きのものはほとんど無かったです。Kubestronaut 要件までの認定資格関連の e-learning の中には日本語字幕つきものもありましたが、今回はほぼ英語のみでした。序盤に受けた試験はある程度知っている技術領域のものだったので、受けた e-learning の内容の理解も追いつくことができました。しかし徐々に、知識の少ない領域の試験になってきて、学習効率が落ちてきました。

そこで、追加 10 個の半分の 5 つ取ったところで、動画の音声を文字起こししてまとめるという学習法をとりました。音声の文字起こしは、Vibe コーディングで作った、Whisper を使った文字起こしアプリを使いました。

文字起こしアプリを使って、まず動画の各レッスンを視聴直後にテキスト化し、その後で AI を使って、その英文を補正してから日本語に翻訳するとともに要約。それをセルフホストしている Wiki に転記してさっと読み直しました。この方法は、レッスン直後に復習できるのが効果的でした。難点は動画を視聴するのに比べて 1.5 倍くらい時間がかかることですが、それよりも理解を深める方を重要視しました。

この「動画視聴」→「文字起こし」→「自然な英語に整形」→「翻訳＆要約」→「Wiki に転記して復習」の流れができたことで、学習のパターンが固まりました。

アプリを作り始めた当初は、同時通訳して e-learning の動画と同時に見るのを理想としたのですが、以下の理由でそれは断念し、アプリの用途は文字起こしのみに限定しました。

翻訳が若干遅れる
標準英単語ではない専門用語の文字起こしに難がある
翻訳したターミナルと動画を同時に見てられない

若干面倒だったのは、起こしたテキストの整形につかった ChatGPT が、テキストが多いと雑に返すようになって使えなくなることでした。目安として、動画の長さが 15 分を超えるとそれに陥ることが多かったです。その場合は、いったん課金している Claude Code に自然な英語への整形をやらせて、その結果を小分けにして ChatGPT に翻訳させました。

模擬試験

KodeKloud や Udemy の試験対策コースにはだいたい模擬試験が含まれているので、まずそれは実施しました。その他に、Udemy に模擬試験のみのコンテンツもあるので、それもいくつか購入して受験しました。模擬試験は、基本的に、本試験よりも難易度の低いものがほとんどでしたが、心の準備にはなりました。

最近は、Golden Kubestronaut ができたことで、関連する模擬試験のコースが充実してきたように思います。しかし、学習を始めた初期は、適当な模擬試験のコンテンツが無かったり、あったはずのコンテンツが公開終了してしまったりしたものがありました。その対策用に、Vibe コーディングで、AI に試験問題を作成させるアプリを作りました。

そのアプリは受験期間の序盤こそ使っていたのですが、AI が生成する試験問題が簡単すぎるのと、次第に Udemy の模擬試験のコンテンツが充実してきたので、後半は使う必要がなくなりました。

ハンズオン

OTCA と、試験の直接的な対象となるプロダクトが存在しない CGOA と CNPA 以外は、手持ちの Linux PC で環境を作って、カリキュラムの範囲を確認しました。

Kubestronaut 要件を受験したときには、CKAD や CKA のカリキュラムにクラスタのインストールやアップデートがあったので、確認のための k8s 環境そのものを構築していて手間でした。しかし今回はその必要がなく、minikube や kind のような簡易環境を使って各試験ごとに簡単に環境を作れて楽でした。

LFCS については、クラウドネイティブ関連のプロダクトではなく、Linux 環境の操作を実践することになります。LFCS のカリキュラムに、仮想マシンを作る libvirt が含まれていたので、libvirt で仮想マシンを作って、その上で全体を実践しました。

リファレンス参照

これは、他の 3 つと比べて、かけた時間は少ないです。文字起こしを導入する以前の ICA, CCA, CAPA あたりまでは、リファレンスを参照して e-learning で捉えきれなかった内容を補完していました。

文字起こしの導入以降は e-learning で理解が十分になったので、それほど、リファレンスまで参照する必要はなくなりました。e-learning の中では説明されない設定項目や、デフォルト値などの仕様が問われることも多少あるので、タイミング的に受験まで日が空くときには、関係しそうなところをチェックしたりしました。

終えてみて

GOLDEN Kubestronaut の称号を得るには、追加要件の試験数が多く、その殆どが英語の試験ということで、到達は難しいだろうと思っていました。しかし、試験の難易度自体はそれほど高くなく、根を詰めれば、それぞれの試験を 1〜2 週間ほどでクリアできると思います。また、試験問題の英文についても、さすがに 10 個受けたら慣れました。

Kubestronaut に到達した時は、k8s のスキルはもとより、特に CKS の学習によってクラウドセキュリティの知識を得られたと感じました。そして今回、GOLDEN Kubestronaut の追加要件に関する学習を通じて、GitOps や、プログレッシブデリバリー。または、オブザーバビリティや IDP など、クラウドネイティブのプラットホームに関する知識を広げることができたと感じています。

この先、GOLDEN Kubestronaut の要件には CNPE が追加になることがすでに明らかになっています。カリキュラムを見るに、おそらく、今回の追加要件の中で学んだプロダクトに関する実技が問われるものになるのではないかと予想します。私はすでに GOLDEN Kubestronaut の称号を得たので、追加でそれに合格する必要はないのですが、是非、チャレンジしてみたいです（情報が集まるまで待って）。

各試験への取り組み

2025 年 1 月に、Kubestronaut の取得に必要な 5 つの認定資格をクリアしました。その後少しして、GOLDEN Kubestronaut のプログラムが追加になりました。そこで再び、2025 年 7 月から 12 月までかけて、GOLDEN Kubestronaut に必要な 10 個の認定資格をクリアしました。

当初は、2025 年度いっぱいかけてゆっくり取り組むつもりだったのですが、以下の理由により、後半は計画を前倒しして 2025 年の年内に終わらせました。

あまり時間をかけると逆に忘れてしまう
2026/03/01 に CNPE が要件へ加わると難易度が結構高くなりそう
年末年始をゆっくり休みたい

OpenTelemetry Certified Associate (OTCA)

受験日: 2025/07/06
学習日数: 5 日
使った教材:
- OpenTelemetry Foundations: Hands-On Guide to Observability
  - e-learning
- OpenTelemetry Certified Associate (OTCA) Practice Exams
  - 模擬試験
  - 公開終了

GOLDEN Kubestronaut を目指すかどうかは決めてはいませんでした。ただ、Kubestronaut の特典で 50%オフのクーポンがあったこともあり、試しに、追加要件の中で興味があった OpenTelemetry を受験しました。

e-learning は量も短めで、CKS の Cilium の学習の中で Hubble に触っていたので、理解は容易でした。学習内容は、メトリクスと OpenTelemetory の基礎。平日の間に e-learning と合わせて模擬試験を実施して、そのまま週末に受験して合格しました。

ざっと学習した程度で合格はできたので、難易度はあまり高くないように感じました。他の試験もこれくらいの難易度なら、すべての認定を取ることはできるだろうと思い、ここで GOLDEN Kubestronaut を目指すことにしました。

Istio Certified Associate (ICA)

受験日: 2025/08/23
学習期間: 48 日
使った教材:
- Istio Hands-On for Kubernetes
  - e-learning (日本語字幕あり)
- Learn Istio Fundamentals
  - e-learning
  - 無料
- https://killercoda.com/ica
  - ハンズオン

OTCA は試しにさらりと受けたのですが、ICA は、実技試験のため難易度が高いと予想し、時間をかけて準備しました。e-learning やハンズオンに加えて、理解の薄いところはリファレンスを翻訳して理解を深めました。

Istio は、以前に受けた CKS のカリキュラムに含まれてはいるものの、CKS ではどちらかというと Cilium の方が使われるので、Istio そのものについてはあまり学習していませんでした。とは言え、同じくサービスメシュ関連のプロダクトである Cilium の理解があったので、スムーズに学習できました。また、先に OTCA を受験していたので、Kiali や Jaeger あたりのオブザーバビリティに関連するプロダクトの理解も容易でした。

その一方で分かり難かったのは、Istio のトラフィック制御の基本である VirtualService や DestinationRule です。名前と振る舞いがうまく繋がらず、理解に苦しみました。その辺りは Istio 用語として割り切りました。

試験については、ICA には、同じ実技試験の CKA/CKAD/CKS の試験に付帯する Killer.sh のような試験ミュレータはありません。模擬試験としては、Killercoda のハンズオンが助けになりました。

いざ受験の申し込みをしようという段階で、ICA のカリキュラムが更新になるというハプニングがありました（ICA の申込ページをよく見たらそのアナウンスがされてました）。夏季休暇の直前に受験を予定していたのですが、その日がちょうどカリキュラムの切り替え期間の中に当たってしまって、受験ができなくなりました。そのため、受験を延期して夏季休暇後に受験しましたが、アップデート内容のチェックと、覚えたことを忘れないようにするのがちょっと面倒でした。

試験自体は、大筋に変更はなかったので、問題はなかったです。試験の難易度は、CKA や CKAD の同等かすこし低目と感じました。

Cilium Certified Associate (CCA)

受験日: 2025/09/23
学習期間: 31 日
使った教材:
- Introduction to Cilium (LFS146)
  - e-learning
  - 無料
- Prep Course - Cilium Certified Associate (CCA) Certification
  - e-learning

CCA は、CKS の学習のときの Cilium に触れた印象で、ややこしいイメージを持っていました。その印象の主な原因は、Cilium のリファレンスの構成の煩雑さかなと思います。

それはそれとして、e-learning での学習において、CKS と ICA で得た知識が助けになりました。CKS で、CiliumNetworkPolicy や mTLS、Hubble などについては学習済みで、さらに、Falco の学習で得た eBPF の知識が助けになりました。また、ICA については、Istio の Ambient モードの方式が Cilium の方式に近そうなので、Istio の Ambient モードを多少理解していたことが役立ちました。

なお、購入予定だった Udemy の模擬試験コンテンツが公開終了になってしまったのが CCA での誤算でした。心の準備をしたかったので、ICA の学習期間の途中の夏季休暇の間に模擬試験アプリを作っておいて、ここで活用しました。また、ICA の時のように e-learning の後にリファレンスを見て理解を深めようと思ったのですが、冒頭に書いたように、リファレンスの構成がややこしくて思うように整理できませんでした。

試験問題の中には結構細かい内容を問われるものもありましたが、そういった問題の数はそれほど多くなかったかと思います。

Certified Argo Project Associate (CAPA)

受験日: 2025/10/12
学習期間: 19 日
使った教材:
- Argo Workflows: The Complete Practical Guide : Unlock DevOps
  - e-learning
- Argo CD Essential Guide for End Users with Practice
  - e-learning
- Mastering Argo Rollouts: Progressive Delivery in Kubernetes
  - e-learning
- https://killercoda.com/argo
  - ハンズオン

CAPA は、Argo の 4 つのプロダクト(Workflows, CD, Rollouts, Events)をまとめて題材とする試験です。これについては、試験対策用の e-learning のコースは見つかりませんでした。ただ、Workflows, CD, Rollouts のプロダクトそのものを扱う e-learning が Udemy にあったので、その中の試験カリキュラムに該当するレッスンを視聴して学習しました。Events については e-learning が無かったので、試験カリキュラムの範囲をリファレンスを見て学習しました。もともと Events は全体の中での割合が低いので、問題はないと判断しました。

個人的に、4 つのプロダクトの中で馴染みがあるのは Argo CD と Argo Workflows で、その 2 つ学習は容易でした。とは言え、普段はプライベートでの表面的な利用のみなので、Argo CD の Projects や RBAC など、突っ込んだテーマをここで学びました。Rollouts は初見ですが、プログレッシブデリバリーの知見が多少はあったので、理解は難しくなかったです。ICA で学んだトラフィックシフトの知識が、Rolleouts のトラフィック制御をイメージするのに役立ちました。

CAPA の厄介っどころとしては、「覚えたことがどのプロダクトのものだったかわからなくなる。」という点でした。4 つのプロダクトを同時に学ぶので、仕様の細かい点などは、どのプロダクトのものだったのか曖昧になってしまいました。

e-learning 後、ハンズオンは Argo CD と Workflows については killercoda のコンテンツが充実しているので、まずはそれでざっと実施しました。Rollouts と Event については、手元に環境を作ってハンズオンをしました。模擬試験のコンテンツは見当たらなかったので、CAPA でも念の為、自作の模擬試験アプリで心の準備をしました。

なお Argo Workflows については、こちらの記事もご覧いただけます。

GitOps Certified Associate (CGOA)

受験日: 2025/10/19
学習期間: 7 日
使った教材:
- Prep Course - GitOps Certified Associate (CGOA)
  - e-learning
- Introduction to GitOps (LFS169)
  - e-learning
- https://www.udemy.com/course/certified-gitops-associate-cgoa/
  - 模擬試験
  - 公開終了

CGOA は、特定のプロダクトを対象とするものではなく、GitOps というテーマを題材とするものです。直前の CAPA で GitOps のプロダクトである Argo CD を学んだ時点で、GitOps に関する知識はおおよそ習得しました。そのため油断して、e-learning と模擬試験をサラリとやって、そのまま試験に望みました。

その結果、合格はしたものの、正答率は 15 個の試験の中で一番低かったです。その原因は、GitOps の理解というより、英語力だと思われます。前述した通り、特定のプロダクトを対象としない CGOA では、プロダクトの特徴や仕様を問われる様な単純な問題が無い代わりに問われる内容が比較的複雑で、問題の英文の理解が難しかったです。CGOA で、「特定のプロダクトを対象としない試験は意外と厄介」と気づきました。

Prometheus Certified Associate (PCA)

受験日: 2025/11/09
学習期間: 21 日
使った教材:
- Prep Course - Prometheus Certified Associate (PCA) Certification
  - e-learning
- Prometheus Certified Associate Practice Exams
  - 模擬試験

PCA が題材とする Prometheus は、これまで何度か、触ってみようとしたことはありました。その度に、「PromQL のややこしさ」がどうにも面倒そうで、深く追求することは避けてきました。しかし、ここに至っては避けることができないので取り組みました。

GCOA の受験で自分の英語力のなさを痛感したので、GCOA をパスしたその日に文字起こしアプリを作成して、この PCA の学習から使い始めました。その結果、e-learning での理解度がかなり向上しました。

PCA の受験では、先に受験した OTCA で得たメトリクスやエクスポーターの知識が役立ちました。Prometheus にはメトリクスの収集の他にもアラートのトリガーや通知の特徴がありますが、その辺りの仕組みは理解しやすかったです。ただ、Histgram と Summary の違い、Relabel Config の振る舞いや演算子など、細かい点がちらほらあるので、その辺はリファレンスを参照して頭に入れておきました。

そして肝心の、PCA の特徴である独自言語の PromQL については、ローカルに作った Prometheus の環境でのハンズオンを通じて理解を深めました。Prometheus の Expression Browser を使って実践し、何度もクエリの記述エラーを吐き出しながら、言語仕様を理解しました。

Certified Backstage Associate (CBA)

受験日: 2025/11/23
学習期間: 14 日
使った教材:
- Prep Course - Certified Backstage Associate (CBA) Certification
  - e-learning
- Introduction to Backstage: Developer Portals Made Easy (LFS142)
  - e-learning
  - 無料
- Certified Backstage Associate (CBA): Tests December 2025
  - 模擬試験

CBA は、Backstage という IDP( Internal Developer Portal)を構築するためのプロダクトを題材とするもので、他の試験とはちょっと趣が違っていました。CBA の学習で得た Platform as a Product の考え方は、この後の、CNPA で大きく役立ちました。

Backstage 自体は monorepo 構成の React アプリであり、デザインシステムに Material UI が使われています。そのため、CBA では、IDP の理念や Backstage での IDP 機能とともに、Material UI を使った React アプリの実装に関する知識が問われます。私は Material UI や React アプリの知見があったので、それは問題がなかったです。e-learning に中にもアプリ構築のセッションがあり、他の試験対策講座とはちょっと雰囲気が違ってました。

React アプリの Backstage はローカルでそのまま起動できるので、比較的、実践が容易でした。プラグインの実装やデザインのカスタマイズなどを試して、実装方法を理解しました。

なお Backstage については、こちらの記事もご覧いただけます。

Kyverno Certified Associate (KCA)

受験日: 2025/12/07
学習期間: 14 日
使った教材:
- Prep Course - Kyverno Certified Associate (KCA) Certification
  - e-learning
- KCA - Kyverno Certified Associate - Mock Exams
  - 模擬試験

KCA は、確か、学習を始めた当初は e-learning や模擬試験のコンテンツが無かったと記憶しています。そのため、受験の順番を後ろにしていました。その時点では、Kyverno のプロダクトサイトを見て学習するつもりでいたのですが、GOLDEN Kubestronaut ができたからかいつの間にかコンテンツができていたので、それらを利用しました。

KCA の学習では、CKS の学習で得たポリシーの知識が役に立ちました。CKS で扱われたのは OPA/Gatekeeper ですが、考え方や仕組みは類似しているので、理解の助けになりました。OPA/Gatekeeper ではポリシーの記述に Rego が使われていて理解が難しいのですが、Kyverno のポリシーの記述は基本的に yaml と json で、理解しやすかったです。e-learning の講師の口調もゆっくりで、理解しやすかったです。

試験前には手元に k8s の環境を作ってハンズオンをしました。ポリシーの仕様の確認とともに、各コントローラの振る舞いをチェックしました。バックグラウンドスキャンやレポート生成の動きが若干ややこしいので、実際に動かしてその様子を確認しました。

Certified Cloud Native Platform Engineering Associate (CNPA)

受験日: 2025/12/13
学習期間: 6 日
使った教材:
- Prep Course - Certified Cloud Native Platform Engineering Associate (CNPA)
  - e-learning
- CNPA- Cloud Native Platform Associate - Mock Exams
  - 模擬試験

CNPA は、学習を始めた時点では要件になく、後から追加になりました。KCA と同様、当初は e-learning や模擬試験のコンテンツが無く、LFCS よりも後の最後に受験する予定でした。その後、コンテンツができたので、予定を変更して、LFCS よりも先に受験しました。ここに来て、なんとか年内に終わらせたい気持ちが強まり、KCA から一週間で臨みました。

CNPA は、CGOA 同様、特定のプロダクトを対象としない試験です。対象の範囲は結構広くて、GitOps や DevSecOps のような開発・運用に関する理解や、Platform as a Product の理解など、様々な領域を知っておく必要がありました。ここまでに受けた試験の中では、CKS, CGOA, CBA で得た知識が役立ちました。

ちなみに、e-learning の講師がとても早口で理解がしにくかったです。AI を使って翻訳と要約をして、やっとその内容を理解できる感じでした。

そして、CNPA の試験受験で苦労したのは、問題数の多さと問題の英文の難しさでした。まず、「問題数の多さ」については、他の選択式の試験が 90 分で 60 問であるのに対し、CNPA は 120 分で 85 問でした。e-learning の中で「問題数は 60 問」と説明されていたので、それは表示のバグで実際には 60 問で終わるのかと思ったら、それ以降も終わることなく続いて結局 85 問フルに回答しました。その結果、集中力が乱れ、また、回答を見直す時間はあまり取れませんでした。次に、「問題の英文の難しさ」ですが、特定のプロダクトを対象としない試験であるために、その分、英文が長く難しいです。他の試験と比べて、問題と選択肢の文章の長さが 1.5〜2 倍くらいあったと思います。CNPA の難易度は、英語の得手不得手でだいぶ違うと感じました。

CNPA に至るまで半年勉強してきたので余裕だろうと思っていたのですが、e-learnig と試験の双方で、思いの外手こずりました（主に英語で）。

Linux Foundation Certified System Administrator (LFCS-JP)

受験日: 2025/12/28
学習期間: 15 日
使った教材:
- Linux Foundation Certified Systems Administrator - LFCS
  - e-learning
- https://killercoda.com/lfcs
  - ハンズオン

最後に受験したのは LFCS です。これは Linux そのものの実技を問う試験です。普段から Linux(Ubuntu)は使っていますが、個人利用の範囲ではあまり深い使い方はしないので、足りない部分を e-learning と手持ちの Linux PC でのハンズオンで学習しました。

受験時には、CKAD,CKA,CKS と同様に、killer.sh の試験シミュレータを事前に 2 回使えます。本番対策に非常に有効でした。1 回目は受験の一週間前に使いました。過去の経験で「killer.sh の試験シミュレータの難易度は本番より若干難しめ」と感じるところなので、出題範囲とともに、本番の難易度を予想しました。実際そのとおりだったかと思います。そして受験の前日に 2 回目を使って、（心の準備は）万端で試験に臨みました。

LFCS の試験の特徴としては、他の実技試験(CKAD,CKA,CKS,ICA)と違って、試験中にネット上のマニュアルを参照できません。そのため参照できるのはターミナル上の man と help です。試験対策に、man の操作に慣れておくのと、想定される問題に関する man や help へのたどり着き方を覚えておくと良いと思います。

また、問われている対象が明確に分かるなら、man と help で調べられるのですが、「あれはなんだったか」というようなおぼろげな状況では man と help にたどりつけません。そんな状況に備え、例えば以下のような方法で、対象にたどりつく術を身に着けておくと良いと思います。

Tab 補完の候補であたりをつける
- 例えば日付に関する問題なら、time や date などと打って Tab 補完すると候補が列挙されるので、そこからあたりをつける。
man の SEE ALSO であたりをつける
- とりあえず関連しそうなものの man を表示して、man の最後の"SEE ALSO"の候補であたりをつける。
etc 配下を grep で総当り検索
- etc 配下を grep の R オプションで階層的に関連しそうなキーワードでテキスト検索して、それらしいファイルを探す。

試験にはそれなりの手応えで全問回答できたので、試験終了の時点で合格を確信しました。24 時間以内にくるはずの通知がなかなか来ずに変だなと思いましたが、ちょっと遅れて合格通知が来ました。その後すぐ年内には GOLDEN Kubestronaut の通知も来て、心置きなく年越しを迎えられました。

Nuxt.js×SupabaseでAuth認証機能を実装しよう

2026-01-09T00:00:00.000+00:00

はじめに

こんにちは。
最近、個人開発でNuxt.jsを使ったWebアプリ開発をしています。サーバーサイドをどうしようかと検討したところ、Supabaseというフルスタックバックエンドサービスが話題になっていることを知りました。

公式サイト：https://supabase.com/

どうやらFirebaseの代替として注目を集めているバックエンドサービスで、モダンなアプリケーション開発に必要な機能を包括的に提供しているようです。
Nuxt.jsにSupabaseを導入して認証まで意外と簡単にできたので、自分のメモがてら紹介しようと思います。

本記事ではNuxt.jsにSupabaseを導入する方法、そしてメールアドレスによる認証機能の実装方法を紹介します。

Supabaseとは

Supabaseは、PostgreSQLをベースにしたオープンソースのBaaS（Backend as a Service）プラットフォームです。このプラットフォームはリアルタイムデータベース、認証、ストレージなど多様な機能を提供しています。
Supabaseを使えば、バックエンドを自分で開発することなく、すぐにデータベースやユーザー認証を導入でき、フロントエンドの開発だけに集中できます。

SQLが使えるのでデータ管理がしやすく、オープンソースで自由度が高いです。
何より（制限はありますが）無料プランで利用可能なところが魅力的です。

Supabaseの各機能の詳細については、公式ドキュメントや多くの解説記事がありますのでぜひ併せて参照してみてください。個人的には、これほど多機能でありながら導入が驚くほどスムーズで、開発者にとって非常に使い勝手の良いサービスだと感じました。

Supabase導入方法

それではNuxt.jsにSupabaseを導入してみましょう。まず前提として、下記は既に行っているとします。

公式サイトでユーザー登録をしていること
プロジェクトを立ち上げて使用するデータベースがSupabase内にあること

まだの方はSupabaseと調べれば色々と出てきますので試してみてください。思ったよりも簡単に登録できると思います。

supabaseを導入前の開発環境が下記になっているとします。

package.json

"dependencies": {
	"@nuxt/scripts": "0.12.1",
	"@nuxt/ui": "4.0.1",
	"@tailwindcss/vite": "^4.1.18",
	"nuxt": "^4.2.2",
	"tailwindcss": "^4.1.18",
	"vue": "^3.5.26",
	"vue-router": "^4.6.4"
},
"devDependencies": {
	"nuxt-icon": "1.0.0-beta.7",
	"typescript": "^5.9.3"
}

この状況で、下記コマンドを実行してsupabaseをインストールします。
（※パッケージ管理ツールとしてはpnpmを使用していますが、npmやyarnでも問題ありません）

pnpm install @nuxtjs/supabase @supabase/supabase-js

インストールしたら、nuxt.config.tsに@nuxtjs/supabaseを追加します。

nuxt.config.ts

import tailwindcss from "@tailwindcss/vite"

export default defineNuxtConfig({
  compatibilityDate: '2025-07-15',
  devtools: { enabled: true },
  css: ['./app/assets/css/main.css'],
  vite: {
        plugins: [tailwindcss()],
  },
  modules: [
	'@nuxtjs/supabase', // これを新しく入れる
	'@nuxt/ui',
	'nuxt-icon',
  ]
})

次に、Supabaseで作成したプロジェクトのProject URLやAPI Keyを取得します。「Project Settings > Data API」や「Project Settings > API Keys」を確認してみましょう。

Project Settings > Data API
Project Settings > API Keys

.envファイルを新規作成して、確認したProject URLやAPI KEYを追加します。

.env

SUPABASE_URL=<Project URL>
SUPABASE_KEY=<Publishable key>

Information

envで設定しているプロパティ名はデフォルトの名称を使用しています。
https://supabase.nuxtjs.org/getting-started/introduction#options
もしプロパティ名を別の名前にしたい場合は、nuxt.config.tsにて下記のようにsupabaseのオプションを設定してください。

nuxt.config.ts

export default defineNuxtConfig({
  // ...
  supabase: {
    // Options
  }
}

これでSupabaseの導入は完了です。それではNuxt.jsでログインページを作成していきましょう。

メールアドレスによる認証の実装

これから認証方法の実装に入りたいと思います。
Supabaseの認証方法はGoogleログイン認証やGitHubログイン認証など数多くありますが、今回はサクッと簡単に作りたいのでメールアドレス認証で作ろうと思います。
ページの作りとしては、こちらのソースコードが非常に参考になりましたので、こちらをベースに解説したいと思います。

Nuxt.js × Supabaseでは、（ログインしていない場合）デフォルトで/loginにリダイレクトします。そのためpagesディレクトリには下記を作成する必要があります。

vueファイル	説明
login.vue	ログインや新規登録をするページ
index.vue	ログインした後に遷移するページ

またログアウトする機能も必要ですが、そちらはcomponentsディレクトリにAppHeaderコンポーネントを用意してヘッダーにログアウト機能を追加します。

vueファイル	説明
AppHeader.vue	ヘッダーコンポーネント。ログアウト機能を追加します。

app.vue

pagesディレクトリに色々作成しないといけないので、まずapp.vueを下記のようにします。

app.vue

<template>
    <UApp>
        <NuxtLayout>
            <NuxtPage></NuxtPage>
        </NuxtLayout>
    </UApp>
</template>

layouts/default.vue

<template>
    <div>
        <AppHeader />

        <UMain>
            <slot />
        </UMain>
    </div>
</template>

Information

<UApp>や<NuxtLayout>などはNuxtUIというライブラリのUIコンポーネントです。
下記では特に断りなくNuxtUIのコンポーネント群を使用しています。

ログインページ

次にログインページを作成します。下記がlogin.vueの全体像です。

<script setup lang="ts">
    import type { AuthError } from '@supabase/supabase-js';

    /** Supabaseクライアントのインスタンス */
    const supabase = useSupabaseClient();
    /** ログインユーザー情報 */
    const user = useSupabaseUser();
    /** 通知（トースト）機能の利用 */
    const toast = useToast();
    /** 表示モードの切り替え（in: ログイン、up: 新規登録）*/
    const sign = ref<'in' | 'up'>('in');

    watchEffect(() => {
        // ユーザーが認証済み（ログイン中）の場合、トップページへリダイレクト
        if (user.value) {
            return navigateTo('/');
        }
    });

    // フォームの入力項目定義
    const fields = [
        {
            name: 'email',
            label: 'Email',
            type: 'text' as const,
            placeholder: 'メールアドレスを入力してください',
            required: true,
        },
        {
            name: 'password',
            label: 'Password',
            type: 'password' as const,
            placeholder: 'パスワードを入力してください',
        },
    ];

    /**
     * メールアドレスとパスワードによるログイン処理
     *
     * @param email メールアドレス
     * @param password パスワード
     */
    const signIn = async (email: string, password: string) => {
        const { error } = await supabase.auth.signInWithPassword({
            email,
            password,
        });
        if (error) {
            displayError(error);
        }
    };

    /**
     * 新規ユーザー登録処理
     *
     * @param email メールアドレス
     * @param password パスワード
     */
    const signUp = async (email: string, password: string) => {
        const { error } = await supabase.auth.signUp({
            email,
            password,
        });
        if (error) {
            displayError(error);
        } else {
            toast.add({
                title: 'Sign up successful',
                icon: 'i-lucide-check-circle',
                color: 'success',
            });
            await signIn(email, password);
        }
    };

    /**
     * 認証エラーをトースト通知として表示
     *
     * @param error Supabaseから返却される認証エラーオブジェクト
     */
    const displayError = (error: AuthError) => {
        toast.add({
            title: 'Error',
            description: error.message,
            icon: 'i-lucide-alert-circle',
            color: 'error',
        });
    };

    /**
     * フォーム送信時のハンドラー
     *
     * @param payload フォームから渡される入力データ（emailやpassword）
     */
    async function onSubmit(payload: any) {
        const email = payload.data.email;
        const password = payload.data.password;

        if (sign.value === 'in') {
            // ログインの場合
            await signIn(email, password);
        } else {
            // 新規登録の場合
            await signUp(email, password);
        }
    }
</script>
<template>
    <UContainer
        class="h-[calc(100vh-var(--ui-header-height))] flex items-center justify-center px-4"
    >
        <UPageCard class="max-w-sm w-full">
            <UAuthForm
                :title="sign === 'in' ? 'ログイン' : '新規登録'"
                icon="i-lucide-user"
                :fields="fields"
                @submit="onSubmit"
            >
                <template #description>
                    {{ sign === 'up' ? '既にアカウントをお持ちの方は' : '新規登録の場合は' }}
                    <UButton variant="link" class="p-0" @click="sign = sign === 'up' ? 'in' : 'up'">
                        こちら
                    </UButton>
                </template>
                <template #submit>
                    <div class="flex items-center justify-center">
                        <UButton type="submit" class="justify-center cursor-pointer w-80">
                            {{ sign === 'up' ? '新規登録' : 'ログイン' }}
                        </UButton>
                    </div>
                </template>
            </UAuthForm>
        </UPageCard>
    </UContainer>
</template>

コードを上から順を追って解説していきます。
最初にsupabaseクライアントの準備とログイン状態に応じたリダイレクト処理を行います。

    /** Supabaseクライアントのインスタンス */
    const supabase = useSupabaseClient();
    /** ログインユーザー情報 */
    const user = useSupabaseUser();
    /** 通知（トースト）機能の利用 */
    const toast = useToast();
    /** 表示モードの切り替え（in: ログイン、up: 新規登録）*/
    const sign = ref<'in' | 'up'>('in');

    watchEffect(() => {
        // ユーザーが認証済み（ログイン中）の場合、トップページへリダイレクト
        if (user.value) {
            return navigateTo('/');
        }
    });

またログインフォーム（UIコンポーネントUAuthForm）に渡すための入力項目を定義します。

    // フォームの入力項目定義
    const fields = [
        {
            name: 'email',
            label: 'Email',
            type: 'text' as const,
            placeholder: 'メールアドレスを入力してください',
            required: true,
        },
        {
            name: 'password',
            label: 'Password',
            type: 'password' as const,
            placeholder: 'パスワードを入力してください',
        },
    ];

次にSupabaseのauthライブラリを用いた認証部分の実装をします。
ログイン処理ではsignInWithPasswordメソッド、新規登録にはsignUpメソッドを使用して、引数にはemailとpasswordを指定します。

    /**
     * メールアドレスとパスワードによるログイン処理
     *
     * @param email メールアドレス
     * @param password パスワード
     */
    const signIn = async (email: string, password: string) => {
        const { error } = await supabase.auth.signInWithPassword({
            email,
            password,
        });
        if (error) {
            displayError(error);
        }
    };

    /**
     * 新規ユーザー登録処理
     *
     * @param email メールアドレス
     * @param password パスワード
     */
    const signUp = async (email: string, password: string) => {
        const { error } = await supabase.auth.signUp({
            email,
            password,
        });
        if (error) {
            displayError(error);
        } else {
            toast.add({
                title: 'Sign up successful',
                icon: 'i-lucide-check-circle',
                color: 'success',
            });
            await signIn(email, password);
        }
    };

エラー時にはトースト通知として表示するようにメソッドを作っています。

    /**
     * 認証エラーをトースト通知として表示
     *
     * @param error Supabaseから返却される認証エラーオブジェクト
     */
    const displayError = (error: AuthError) => {
        toast.add({
            title: 'Error',
            description: error.message,
            icon: 'i-lucide-alert-circle',
            color: 'error',
        });
    };

フォームの送信ボタンが呼ばれたら、表示モードの状態に合わせて上記のsignInメソッドとsignUpメソッドが呼ばれるようにします。

    /**
     * フォーム送信時のハンドラー
     *
     * @param payload フォームから渡される入力データ（emailやpassword）
     */
    async function onSubmit(payload: any) {
        const email = payload.data.email;
        const password = payload.data.password;

        if (sign.value === 'in') {
            // ログインの場合
            await signIn(email, password);
        } else {
            // 新規登録の場合
            await signUp(email, password);
        }
    }

最後にNuxtUIを利用してログイン用のテンプレートを作成します。表示モードに合わせてログインか新規登録を切り替えるようにしました。

<template>
    <UContainer
        class="h-[calc(100vh-var(--ui-header-height))] flex items-center justify-center px-4"
    >
        <UPageCard class="max-w-sm w-full">
            <UAuthForm
                :title="sign === 'in' ? 'ログイン' : '新規登録'"
                icon="i-lucide-user"
                :fields="fields"
                @submit="onSubmit"
            >
                <template #description>
                    {{ sign === 'up' ? '既にアカウントをお持ちの方は' : '新規登録の場合は' }}
                    <UButton variant="link" class="p-0" @click="sign = sign === 'up' ? 'in' : 'up'">
                        こちら
                    </UButton>
                </template>
                <template #submit>
                    <div class="flex items-center justify-center">
                        <UButton type="submit" class="justify-center cursor-pointer w-80">
                            {{ sign === 'up' ? '新規登録' : 'ログイン' }}
                        </UButton>
                    </div>
                </template>
            </UAuthForm>
        </UPageCard>
    </UContainer>
</template>

最終的に出来上がったテンプレート部分が下記になります。

メインページ

次にログイン後に遷移するメインページを作成します。今回は例としてユーザーが書いたブログ記事の一覧を表示するページを作成しています。

index.vue

<script setup lang="ts">
    import type { Database } from '#build/types/supabase-database';
    import type { TableColumn } from '@nuxt/ui';

    /** Supabaseクライアントのインスタンス */
    const client = useSupabaseClient<Database>();
    /** ログインユーザー情報 */
    const user = useSupabaseUser();

    /**
     * 記事一覧の取得
     */
    const { data: articles } = await useAsyncData(
        'articles',
        async () => {
            const { data } = await client
                .from('article')
                .select('*')
                .eq('uuid', user.value!.sub)
                .order('regist_date');
            return data ?? [];
        },
        { default: () => [] }
    );

    /**
     * テーブルのカラム定義
     */
    const columns: TableColumn<any, any>[] = [
        { accessorKey: 'id', header: 'ID' },
        { accessorKey: 'regist_date', header: '日付' },
        { accessorKey: 'title', header: 'タイトル' },
        { accessorKey: 'abstract', header: '概要' },
    ];
</script>
<template>
    <UContainer>
        <UPageSection title="記事一覧" description="最新記事を表示します" headline="ブログ">
            <div class="flex justify-center items-center">
                <div v-if="articles.length > 0">
                    <UCard variant="subtle">
                        <UTable :data="articles" :columns="columns"> </UTable>
                    </UCard>
                </div>
            </div>
        </UPageSection>
    </UContainer>
</template>

コードを上から順を追って解説していきます。
最初にログインページと同じようにsupabaseクライアントを行います。

    /** Supabaseクライアントのインスタンス */
    const client = useSupabaseClient<Database>();
    /** ログインユーザー情報 */
    const user = useSupabaseUser();

今回はSupabaseで作成したarticleテーブルのデータを表示する機能を実装します。そのため、Supabaseクライアントを生成する際に自動生成した型定義ファイルを適用して「Database型」を指定しています。こうすることでテーブル名やカラム名に入力補完が効くようになり、開発効率が格段にアップします。

Information

型定義ファイルはSupabase CLIを利用することによって生成できます。
まず下記コマンドを実行してSupabaseのログインと初期化をします。

npx supabase login
npx supabase init

その後、下記コマンドを実行すると、型定義ファイルが生成されます。

npx supabase gen types typescript --project-id "<project_id>" --schema public > .\app\types\database.types.ts

次に記事一覧を取得する機能を実装します。ログインユーザー情報userにあるuuidをuser.value!.subで取得して、下記のようにユーザーに紐づいている記事を取得するようにしました。
また記事一覧をテーブル形式で表示するために、テーブルのカラムを定義しています。accessorKeyはarticleテーブルのカラムと一致するように設定して、headerはテーブルのヘッダーに表示する名称を設定します。

    /**
     * 記事一覧の取得
     */
    const { data: articles } = await useAsyncData(
        'articles',
        async () => {
            const { data } = await client
                .from('article')
                .select('*')
                .eq('uuid', user.value!.sub)
                .order('regist_date');
            return data ?? [];
        },
        { default: () => [] }
    );

    /**
     * テーブルのカラム定義
     */
    const columns: TableColumn<any, any>[] = [
        { accessorKey: 'id', header: 'ID' },
        { accessorKey: 'regist_date', header: '日付' },
        { accessorKey: 'title', header: 'タイトル' },
        { accessorKey: 'abstract', header: '概要' },
    ];

最後にテンプレート部分を作成します。

<template>
    <UContainer>
        <UPageSection title="記事一覧" description="最新記事を表示します" headline="ブログ">
            <div class="flex justify-center items-center">
                <div v-if="articles.length > 0">
                    <UCard variant="subtle">
                        <UTable :data="articles" :columns="columns"> </UTable>
                    </UCard>
                </div>
            </div>
        </UPageSection>
    </UContainer>
</template>

ヘッダーコンポーネント

最後にログアウト機能を実装します。こちらの機能はヘッダー部分（components > AppHeader.vue）に実装しました。

AppHeader.vue

<script setup lang="ts">
    /** Supabaseクライアントのインスタンス */
    const client = useSupabaseClient();
    /** ログインユーザー情報 */
    const user = useSupabaseUser();

    /**
     * ログアウト処理
     */
    const logout = async () => {
        await client.auth.signOut();
        navigateTo('/login');
    };
</script>
<template>
    <UHeader :toggle="false">
        <template #left>
            <span class="font-bold text-lg">Demo</span>
        </template>
        <template #right>
            <UButton v-if="user" variant="link" class="cursor-pointer" @click="logout">
                ログアウト
            </UButton>
            <UButton v-if="!user" variant="link" to="/login"> ログイン </UButton>
        </template>
    </UHeader>
</template>

ログアウト処理はかなり単純で、ただsupabaseクライアントでsignOutメソッドを使って実装するだけです。あとはテンプレート部分にログアウトボタンを追加することで、ログアウトできてしまいます。
メインページと合わせて実際に出来たページがこちらになります。

以上でメールアドレスによる認証が実装できました。

メールアドレスによる認証の検証

それでは実際に画面上で新規登録してみましょう。
ログインページでメールアドレスとパスワードを入力して新規登録ボタンを押すと、認証メールが届きます。

こちらの「Confirm your mail」のリンクを押すと、ユーザー登録が完了し、アプリのメインページにリダイレクトします。
またユーザ登録が完了しているかは、Supabaseで作成したプロジェクトの「Authentication > Users」で確認できます。データが列として入っている場合は登録が完了しています。まだリンクでの認証が済んでいない場合は、Last Sign Inの列でWaiting for verificationと表示されます。

まとめ

今回はNuxt.jsとSupabaseを組み合わせたauth認証の実装を解説しました。特に意識したところもなく、簡単にサクッと実装できたのが今回の驚きでした。
バックエンドの開発工数を最小限に抑えつつ、安全な認証を簡単に実装できるのはかなり魅力的ですね。
今回はメールアドレスによる認証のみ解説しましたが、他にもGoogleやGitHubなどの認証も簡単に導入できます。
よかったらそちらも試してみてください。

補足：ログインしないで閲覧できるページがほしい場合

基本的に、紹介した方法でNuxt.jsとSupabaseを利用した認証できます。しかし、こちらの方法だとログインをしていない場合、必ずログインページにリダイレクトされてしまいます。ですが、たまにログインしないでも閲覧できるページもほしい場合があると思います。
その時の設定方法も、実は非常に簡単でnuxt.config.tsに下記を付け足せばよいです。

export default defineNuxtConfig({
  // ~~~省略~~~
  supabase: { 
	redirectOptions: {
		login: '/login',
		callback: '/confirm',
		include: [],
		exclude: ['/'], // ここの部分がログインしなくても閲覧できるページ
		cookieRedirect: false,
	},
  },
  // ~~~省略~~~
})

こちらを設定すると、excludeの部分で設定したページについてはログインする必要はありません。

ぜひお試しください！

参考文献

Supabase公式サイト
Nuxt Supabase導入公式サイト
- ログインフォームを作る際にこのサイトで紹介しているDemoのソースコードが非常に参考になりました。
- Todo list example using Supabase and Nuxt 3
Supabaseを布教したい
Supabaseとは？初心者向けに分かりやすく解説！
Supabase + Nuxt 3でチャットアプリを作ってみた
Nuxt + Supabase で Googleログイン機能を作ってみる
話題のSupabaseでサクッと認証機能をつくってみた！
- こちらはNext.jsによる実装ですが、参考になりました。

無料のOSSツールSysONで始めるSysMLv2モデリング（１）〜はじめてのSysON

2026-01-08T00:00:00.000+00:00

2025年9月、SysML Version 2.0(SysML v2)が正式リリースされました。

「SysML v2を試してみたい」と思っても対応しているツールは高価だったり、汎用の描画ツールで SysML v2のモデルを作成してみてもいまいちピンとこなかったりといった経験はないでしょうか。

本記事では「SysML v2のグラフィカル記法がどんなものか試してみたい」という時におすすめのツール SysONをご紹介します。

SysONとは

SysON（読みはシスオンまたはスィスオン）は、SysML v2の主にグラフィカル記法を作成、編集するためのツールです。
この名前は、「システムにオンする」と「システムモデリングの新しいシーズン（seasonとsysonはやや音が似ている）」というのが由来だそうです。

SysONのソースコードは GitHubで公開されています。
ライセンスは EPL-2.0です。
GitHubのリポジトリ名（eclipse-syson / syson）からわかるとおり、このツールは Eclipse財団の SysONプロジェクトで開発・保守されています。
この SysONプロジェクトはフランスの OBEO社と CEA（フランス原子力・代替エネルギー庁）が主導し、実開発は OBEO社が担っています。

ちなみに、「OSSツール、フランス、Eclipse財団」といえば、UML2モデリングツールである Papyrusを思い浮かべる方もいるかもしれません。
日本では認知度の低いツールですので知らない方も結構いらっしゃるのではないかと思います。
実はこの Papyrusの開発も SysONと同じ OBEO社が担っています。
Papyrusは SysML v1をサポートしているので、SysML v1を使いたいなら Papyrus、SysML v2を使いたいなら SysONという棲み分けになっているのかなと思います。

SysONの構成

SysONは Webアプリケーションです。
ユーザーはクライアントPCの Webブラウザで SysONサーバーにアクセスします。
ユーザーが Webブラウザで行ったモデルに対する操作は SysONサーバーで実行されます。

複数のユーザーによるモデリングが可能ですし SysML v2仕様には REST APIの要件もありますので、Webアプリケーションは妥当だと思います。
しかしその一方、ネットワーク環境によっては動作が遅くすぐに表示が更新されないといったデメリットもあるため、モデリングの操作に慣れてくるとストレスを感じることもあるかもしれません。

マニュアルに記載されているサポートする Webブラウザは Google Chromeと Firefoxの最新安定版です。
Safari、Microsoft Edge、Operaなど他のブラウザを用いる場合は使えるかどうか検証してからがよいでしょう。

英語ですが、SysONのユーザーマニュアルに該当するドキュメントもあります。

インストール

事前準備

まずはどのリリースをインストールするかを決めましょう。

リリースは Eclipse SysONの Webサイトに記載されています。
GitHubの Tagsを確認するといくつもの Tagがありますが、末尾に ".0" が付いているものが安定版の位置づけになります。

本記事では、安定版である v2025.8.0をインストールします。

インストール方法はマニュアル（v2025.8.0）に記載されています。
マニュアルにはインストール方法が４つ記載されていますが、大きく分けるとローカルテスト用と本番用の２タイプです。
セキュリティを気にしないならばローカルテスト用、セキュリティを考慮すべき環境ならば本番用の方法でインストールしましょう。

本記事は SysML v2を試しに使ってみることを想定していますので、Basic Local Test Setupのインストールを行います。

SysONのローカルテスト用インストールには Docker Engineを使用します。
Docker Desktopは有償ですが、Docker Engineは Apache License 2.0ですので無料で利用できます。
ここでは Docker Engineのインストール方法は割愛します。
筆者は Windows11とその WSL2(Debian/Linux)に Docker Engineをインストールしました。

Docker Engineのインストールが完了したら SysONのインストールを開始します。

docker-compose.ymlを取得する

Webブラウザで GitHubにある SysONの Webページにアクセスして、docker-compose.ymlをダウンロードします。

curlコマンドを用いて docker-compose.ymlをダウンロードする場合は以下の通りです。

curl -OL https://raw.githubusercontent.com/eclipse-syson/syson/refs/tags/v2025.8.0/docker-compose.yml

dockerを起動する

Docker Engineのサービスを起動するにあたって、現状の確認をしましょう。

serviceコマンドで dockerサービスの状態を確認します。

sudo service docker status

dockerサービスが起動していない場合は以下のメッセージが表示されます。

Docker is not running ... failed!

Docker Engineのサービスを起動します。

sudo service docker start

再び、サービスの状態を確認してみましょう。

Docker is running.

dockerサービスが起動しました。

先程ダウンロードした docker-compose.ymlファイルのあるフォルダで以下のコマンドを実行します。

docker compose up

SysONサーバーが bootすると、コンソールログの一部に以下のロゴが出力されます。

app-1       |     _____               ____   _   __
app-1       |    / ___/ __  __ _____ / __ \ / | / /
app-1       |    \__ \ / / / // ___// / / //  |/ /
app-1       |   ___/ // /_/ /(__  )/ /_/ // /|  /
app-1       |  /____/ \__, //____/ \____//_/ |_/
app-1       |        /____/
app-1       |
app-1       |  :: Spring Boot ::         (v3.5.0)
app-1       |

起動が正常に完了すると、以下のメッセージが表示されます。

app-1       | 2025-12-01T06:45:59.914Z  INFO 1 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 8080 (http) with context path '/'
app-1       | 2025-12-01T06:45:59.937Z  INFO 1 --- [           main] org.eclipse.syson.SysONApplication       : Started SysONApplication in 18.896 seconds (process running for 19.808)

Tomcat started on port 8080 (http) は Webサーバーである Apache Tomcatが起動したことをあらわします。

SysONサーバーが起動したら、いよいよ Webブラウザから SysONサーバーアクセスしてみましょう。

最初の画面

Webブラウザを起動し、http://localhost:8080 にアクセスします。

以下のホーム画面が表示されれば準備完了です。

ちなみにこの画面の Existing Projectsのリストにある "Batmobile"は、あのアメコミヒーローが使っている車を題材にしたサンプルです。

終了する

SysONサーバーを起動したシェルで Ctrl + Cすると SysONサーバーが終了します。

dockerサービスを停止する場合は、以下のコマンドで停止します。

sudo service docker stop

次回予告

ここまでで SysONを使ってモデリングする準備が整いました。

次回からはいよいよ、SysONを使った SysML v2のモデリング操作をみていきましょう。

業務日誌のすゝめ〜業務日誌を書く意味を考える〜

2026-01-06T00:00:00.000+00:00

1. はじめに

まず、この記事を書こうと思ったきっかけですが、次の2点になります。

最近読み始めた書籍『ソフトウェアエンジニアガイドブック』で、著者が「業務日誌をつけること」を勧めているから。
私自身も業務日誌をつけているので、改めて理由（動機）を考えてみましたが、単に習慣でつけているだけで、目的意識があって業務日誌をつけていないと考えたため。

ですので、この記事で次の2点を自分なりにまとめてみます。

業務日誌をつけることで何が嬉しいのか、また、逆に何が嬉しくないか。
業務日誌をつけるためのポイント。

エンジニアの方はプロジェクトで業務日誌をつけられている方も多くいらっしゃるかと思いますが、
そうでない方にも、この記事を通じて、業務日誌に興味を持っていただければと幸いです。

2. 業務日誌をつけることで何が嬉しいのか😄

こちらについて、書籍の内容と私自身の考えについて記載します。

1. 書籍に書かれていた業務日誌を勧める理由（要約）

まず、書籍に書かれていた内容を要約すると、以下の3つです。

作業が管理しやすくなる。
作業の一覧を作成しておくと、作業の優先順位がつけやすい。
また、作業が割り込んできた時にも、作業の調整がしやすくなる。
一日の終わりに仕事を終えることに満足感がある。
その日の作業内容を記録することで、一日の仕事を客観的に捉えることができる。
業績評価に利用できる。
自分の過去の作業を振り返ることができる（半年前の作業とかはすぐには思い出せない）。
面談などで上司に説明する際の資料となる（成果を効率的に説明できる）。

2. 上記に対する私の所感

上述のお勧めの理由に関する私の所感としては、以下のとおりです。

1.の「作業を管理しやすくなる」というのは実感があります。作業を列挙すると優先順位が決めやすくなります。
2.の「仕事を終えることに満足感がある」についても分かります。作業が数日に渡る場合でも、その日ごとの作業内容が分かるので、作業が進んでいるように感じられます。
3.の「業績評価に利用できる」については、そういった発想自体がなかったので、これは試してみたいと思います。

3. 私が業務日誌を勧める理由

次に、私自身が業務日誌を勧める理由を挙げたいと思います。

1日の作業を始めやすくなる。
事前に作業予定を立てておくと、当日、何から作業を始めればいいかがわかりやすくなると思います。
とくに、休日を挟むなどして時間が空いた場合に効果的だと思います。
成果を意識しながら、作業へ取り組むようになる。
業務日誌には、作業結果（成果）を記載することになります。
ですので、作業時に成果を出さないと、業務日誌に記載する内容が欠落することになります。
すると、作業時に成果を出すことを意識して作業に取り組むように意識づけることになると思います。
インサイト（気づき）が得られる。
毎日、作業の記録をつけていると、色々と思うところがあったりもします。
- 上述のように、作業に対して、明確な成果がないことに気づくこともあります。
- また、優先度の低い着手中の作業が、延々と残っていることに気づく場合もあります。

3. 業務日誌をつけることで何が嬉しくないか😖

ここまでは、業務日誌の良い点について記載してきました。
しかし、実際に業務日誌をつけ始めると、以下に挙げるような問題が発生することもあると思います。

1. 業務日誌をつけることが負担になる

業務が忙しいときほど、業務日誌を書く時間を確保するのが難しくなります。
つい後回しにしてしまい、気づけば数日分まとめて書く羽目になることも少なくないと思います。

私も社会人1年目の時に、OJT担当の先輩に言われて、業務日誌をつけていました。
ただ、炎上したプロジェクトの開発中、
夜23時過ぎの退社前に業務日誌を書くのは嬉しくなかったです。

2. 何を書けばいいかはっきりしない

「TODO」「優先度」「進捗」など、どこまで細かく書けばよいのか迷うことがあります。
TODOリストとの違いも曖昧^[1]で、単なる作業の羅列になってしまうことも。

上述の業務日誌（社会人1年目）は、部内限定公開のブログサービスを使用していました。
ただ、ブログ（フリーフォーマット）だったので、何をどのように書くか、よく悩んでいたように思います。

3. 何のために書いているのか分からないことも

業務の中で指示されて業務日誌をつけることもありますが、
目的や理由が明確でないと、モチベーションが続かないかもしれません。

上述の業務日誌（社会人1年目）の場合、
先輩曰く、「毎日業務日誌をつけることでインサイト（気づき）が得られるから」ということでした。
ただ、それでも上記の要因があったので、
正直、業務日誌をつけるのが苦痛に感じられることも多々ありました。

4. 業務日誌をつけるためのポイント✍️

最も重要なのは、業務日誌をつけることが負担とならないこと、に尽きると思います。
そのために、以下のようなポイントを押さえておくといいかもしれません。

1. 記載内容は事前に決めておく（テンプレ化する。）

毎日、書くことになるので、内容は事前に決めておくといいと思います。
私は、「本日の作業内容」と「明日の作業内容」を書くようにしています。

2. 書きすぎない。

多くのことを書こうとすると、負担感が出ますので、
必要最低限なことだけを書くようにしたほうがいいと思います。
私は基本的に、「本日の作業内容」と「明日の作業内容」を記載していますが、
必要がある場合のみ、次の内容を追加で記載しています。

作業の成果物（誰かと作業を共有する必要がある場合のみ）
進捗度（作業が日をまたぐ場合）
完了予定日（作業に明確な締切がある場合）

3. 誰かと共有する。

誰かに読んでもらう前提があると、付け忘れしにくくなります。
ですので、読んでもらう必要がないとしても、業務日誌を共有するようにするといいと思います。
私も業務日誌をSlackでチームリーダーにメンションしています。
（都度リアクションをくれるので、とても助かっています😊）

なお、業務日誌はテキストベースが無難かと思っています。
理由としては、その日ごとに記載内容を微妙に変えたいことがあるためです。
その辺りを踏まえると、Slackで業務日誌を作成するのは悪くないと思っています。
誰かと共有するのも簡単ですので。

5. まとめ📒

業務日誌をつけることには、いくつかの利点があるはずです。
ですので、業務日誌をつけておいて損はないはずです。
とはいえ、業務日誌をつけるのは難しい面もあると思うので、
継続するための工夫も必要かと思います。

この記事を読んでいただいて、業務日誌をつけることに興味を持たれましたら、
ぜひ試してみていただければと思います。

💭少し脱線しますが、私個人の見解としては、
TODOリストが「やるべき作業を管理するためのもの」だとすると、
業務日誌は「その作業が業務として意味を持っているかを見直すためのもの」
だと言えるかもしれません。
一口に作業と言っても、業務（仕事として）行うのであれば、
ちゃんと意味のある作業に取り組む必要があるはずです。 ↩︎

豆蔵デベロッパーサイト 2025年10-12月のサマリー

2026-01-02T00:00:00.000+00:00

あけましておめでとうございます。

2025年もご愛読いただきありがとうございました。本年も豆蔵デベロッパーサイトをよろしくお願いします。

記事数・執筆者数

この3ヶ月で49本の記事が投稿され、記事数は843になりました。新たに4名が執筆デビューし、累計75名になりました。

テーマ別の記事

ロボット

/robotics/twincat/introduction-chapter2/twincat-introduction-chapter2/

/blogs/2025/12/10/ceres-solver/

/robotics/bizen/bizen_introduction/

ローカル LLM

/blogs/2025/10/14/local_rag_on_lm_studio/

/blogs/2025/10/15/local_rag_on_lm_studio_part2/

プログラミング言語

/blogs/2025/10/16/csharp_di/

/blogs/2025/12/09/jspecify/

Q Developer

/blogs/2025/11/12/qdev_beginner_day1/

/blogs/2025/11/17/qdev_beginner_day2/

/blogs/2025/11/21/qdev_beginner_day3/

/blogs/2025/11/28/qdev-aidd-spec-kit/

/blogs/2025/12/11/amazon_q_collaborative_writing/

仕様駆動開発

/blogs/2025/12/16/github-spec-kit-iac-entry/

/blogs/2025/12/24/kiro-sphinx-sdd/

CI/CD

/blogs/2025/11/16/github-immutable-releases/

/blogs/2025/11/17/cd-pipeline-for-ubuntu-desktop/

テスト

/blogs/2025/12/17/kiro_ide_pbt/

/blogs/2025/12/19/edu-user-dept-training-1/

パブリッククラウド

/blogs/2025/12/12/google_cloud_entry/

/blogs/2025/12/22/aws-controltower-deepdive/

/blogs/2025/12/23/aws_all_certified_2025/

/in-house-project/sss/webhook-with-sqs/

モデリング

/blogs/2025/12/05/modeling-forum-2025-report/

アーキテクチャ

/blogs/2025/12/08/hexagonal_questions/

アジャイル

/blogs/2025/12/04/scrum-ai-1/

/blogs/2025/12/18/sushi/

GitHub Copilot

/blogs/2025/10/30/intro-to-github-copilot-cli/

開発環境構築

/blogs/2025/10/13/write-java-with-vscode-2025/

個人開発

/blogs/2025/10/13/python-game/

/blogs/2025/12/01/porting-an-electron-app-to-tauri2/

/blogs/2025/12/03/customize-markdown-preview-style-with-agent-skills/

書籍紹介

/blogs/2025/12/02/think-again/

ヘルスケア

/blogs/2025/12/25/Vitality/

アドベントカレンダー2025

アドベントカレンダー2025が開催され、バラエティ豊かな19記事が公開されました。公開された各記事は本記事内でも紹介しています。

/events/advent-calendar/2025/

さいごに

以上、2025年度第3四半期のサマリーでした。

ウォーキングのすすめ～普段リモートワークで運動習慣0の自分が1日1万2000歩歩いた結果～

2025-12-25T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第25日目の記事です。

※本件はテック系の記事ではありません。
食事を気にしていても週一でバーガーキングのワッパーは食べる石原です。
デベロッパーの皆さん、歩いてますかー！

本件は普段の生活の中で以下が思い当たる方を対象としています。

仕事はリモートワーク
休日は家にいる時間の方が多い
別段運動する習慣もなし
1日の平均歩数は1,000歩以下
ジャンキーで美味しいものを食べるのが大好き
「体を動かしたい」という気持ちはあるが、行動に移せずにいる

これらはすべて、数ヶ月前までの私そのものです。
そんな私が現在（2025年12月時点）では以下のような生活に変わりました。

毎日12,000歩のウォーキング、またはジムでの筋トレを継続
「歩くこと」が全く苦にならなくなった
食生活で総カロリーやPFCバランスを自然と意識するように
体重は2kg減
食欲は以前よりさらに増して健康的に

今回は、私がこのような変化に至った経緯と、「運動したいけど一歩が出ない」と同じ悩みを持つ皆さんに、ぜひ共有したいエピソードを書いていこうと思います。

きっかけはVitality

2025年9月末、総務の方から全社向けに「Vitalityプログラム」の参加者募集の案内が届きました。
どうやら健康経営の一環として外部サービスを導入し、社員の健康を促進したいという試みのようです。

元々「体を動かしたい」と思ってはいたものの、きっかけがなくて動けなかった自分。そんな私の背中を強烈に押したのは、案内の中にあったこの一言でした。

「ランキング表彰を実施し、忘年会で豪華景品を授与予定です！」

これを見た瞬間、「やるしかねぇ！」と思った自分は即日で参加を表明し、2025年10月から私のウォーキング生活が幕を開けたのです。

Vitalityとは？

住友生命が提供する健康増進プログラムで、豆蔵が導入したのは「Vitalityスマートプログラム（福利厚生タイプ）」です。

詳細については公式HPに譲りますが、簡単に言うと「歩数や心拍数をアプリで計測してポイントを貯める」仕組みです。貯まったポイントに応じて、一週間ごとに以下のような特典（リワード）がもらえます。

スターバックスの500円クーポン
各コンビニの500mlペットボトルのお茶 / ローソンの飲むヨーグルト
各種団体への寄付 など

デイリーで獲得できるポイントは（イベントを除いて）最大60pt。
取得条件は以下の通りです。（各項目のうち最も高いポイントのみが適用され、重複獲得は不可）

私の目標は至ってシンプル。
「毎日60ptを死守していれば、入賞できるはず！」
そう信じて、12月の忘年会まで「毎日60pt」を取り続ける生活が始まりました。
(結果的にはほぼ1万2000歩を歩くことで取得しました)

社内での取り組み

豆蔵社内ではVitality参加者に向けて、Slackに専用チャンネルを開設し、定期的にランキングを発表する取り組みが行われました。
ランキングの名前について、希望者についてはあだ名が設定できたので、私は「汗かいた後のビールは最高🍺」で登録しました。

用意したアイテム

「1日1,000歩」から脱却するために、私が実際に揃えた「三種の神器（＋α）」を紹介します。

1. スマートウォッチ（ウェアラブルデバイス）

スマートフォンでも歩数は測れますが、心拍数は計測できません。Vitalityのポイント効率を考えると、「歩数」を稼ぐよりも「高強度の運動（心拍数上昇）」を30分行う方が圧倒的にタイパが良いです。
(歩数だと大体30分で4000歩、1万2000歩なら1.5時間が必要)
元々「スマートウォッチはいらない派」だったのですが、いざ付けてみると自分の活動が可視化され、モチベーション維持に大きく貢献してくれました。未導入の方には強くおすすめします！

2. ランニング・ウォーキングシューズ【最重要】

ここへの投資が一番重要と言っても過言ではありません。
運動不足の人が普通のスニーカーで長時間歩くと、高い確率で足腰を痛めます（経験談）。最近のシューズはクッション性が凄まじいので、まずはここから新調しましょう。
以下は私が実際に購入した靴の紹介です。

Fresh Foam X 880v14 GORE-TEX® (New Balance)
黒スニーカーなので普段使いもOK。GORE-TEX素材なので、急な雨でも足元が快適なのが最高です。
Cloudmonster (On)
クッション性が異次元です。「雲の上を歩く」ような感覚で、長距離を歩く予定の人には全力でおすすめします。

3. YouTube プレミアム

ウォーキングの時間を「運動の時間」ではなく「娯楽の時間」に変えてくれる魔法のツールです。
オフライン再生とバックグラウンド再生ができるため、通信量を気にせず動画を「聴きながら」歩けます。

Tips： 「スマート一時保存機能」をオンにしておけば、お気に入りのチャンネルの新着動画が自動でダウンロードされるので、家を出る前の準備も不要になります。

4. その他の小物

帽子： 寝起きの爆発した髪を隠してくれる頼れる相棒。蒸れやすいので通気性重視で選びましょう。
動きやすい服装： 基本は何でもOKですが、軽いアウターがあると体温調節がしやすく、脱いでも荷物にならないので便利です。
ワイヤレスイヤホン： 動画視聴のお供に。ただし、歩道が狭い場所では安全のために「片耳視聴」や「外音取り込みモード」を活用しましょう。

毎日歩くコツ

2ヶ月間、ほぼ毎日1万歩以上を歩き続けて見えてきた、習慣化のポイントをまとめます。

1. 動画視聴の時間を歩く時間に

普段、家で1時間以上じっくり動画を見ている方に朗報です。その時間をそのまま歩く時間にしましょう。
YouTube Premiumなどの機能を使い、動画をあらかじめダウンロードして「聴きながら歩く」だけで、いつの間にかウォーキングが完了します。

最初は「画面を見ないと楽しめないのでは？」と思っていましたが、やってみると音声だけで満足できるコンテンツは意外と多いものです。
気になる動画を見つけたらその場で視聴せずに、ぜひダウンロードして歩きながら聴いてください。

2. 「シューズ」への投資を惜しまない

「歩くだけなら普段の靴でいいや」と思っていませんか？私はそれで失敗しました。
専用ではないスニーカーで歩き始めた結果、以下のような事態に。

物理的な故障： わずか2週間でスニーカー2足のアウトソールが剥離。
身体のバグ： 歩くたびにアキレス腱周辺に痛みが発生。

「歩く」というタスクを継続するための最重要ハードウェアは靴です。悪いことは言いません、快適なウォーキング・ランニングシューズを1足用意しましょう。これだけで継続率は格段に上がります。

3. 「分割」して難易度を下げる

1時間連続で歩こうとするとハードルが高いですが、「朝に30分、夜に30分」のように分割すると、精神的な負荷がグッと下がります。
特に朝のウォーキングは、体内時計をリセットし睡眠の質を向上させる効果もあるため、エンジニアの健康管理には特におすすめです（冬の朝は少し気合が必要ですが！）。

4. 色んなところを歩く

自分のお気に入りの道を毎日歩くのもおつなものですが、時には別の場所を歩くと新たな発見や気づきがあって良いものです。

遊歩道： 近くにあったらまず歩いてみたい道No.1。新たな隠れ家を見つけた子供のような嬉しさを感じます。
駅（特に普段歩いていかない所）： ちょっと離れた駅まで歩くと、知らない道に出会えます。「意外と近いぞ」という気づきが、移動の選択肢を広げてくれます。
大型商業施設： イオンやコストコ、アウトレットなど。歩きながらウィンドウショッピングも楽しめます。
公園、神社、寺など： 季節を感じられるスポットはメンタルにも良い影響があります。

5. 歩く速さを変えてみる

歩き慣れてきたら、スピードを変えてみるのも1つの楽しみです。
もちろんスピードを速めるほど身体への負荷は高くなるのですが、歩きながら自分でどうすれば速く、楽に歩けるかを考えながら色々試行錯誤するだけでマンネリ化は大分減ります。

6. 雨の日でも歩く

余程の嵐とかは別ですが、多少の雨なら撥水加工が施されたウェアを用意しておくだけで傘をささずに歩けます。(GORE-TEX素材の靴もおすすめ)
後は1日雨でも時間によって強弱は結構あるので、時々雨の様子を確認しながら歩くと意外と歩けるイメージがあります。
どうしても無理そうな時はおとなしく家で筋トレとか有酸素運動をしましょう。(私は家でエアロバイク漕いでました)

ウォーキングを始めて実感したメリット・デメリット

メリット

体力が劇的に向上した（HPの底上げ）
以前はたまに出社するだけで、午前中のうちに「残りHP 30%」という感覚でした。しかし最近では、満員電車に揺られてもそこまで疲れを感じません。
数値で見る身体の変化： 体重-2kg、VO2Max（最大酸素摂取量）が「平均以下」から「平均以上」へ向上、安静時心拍数も低下。「ただ歩くだけ」でも心肺機能は確実に鍛えられるようです。
活動量の増加： 1日1〜2時間をウォーキングに充てていますが、体力がついた分、活動できる時間も増えました。「朝に江ノ島ツーリング→帰宅後に銭湯→夜はウォーキング」といったアクティブな休日もこなせるようになり、使った時間以上のリターンを感じています。
睡眠の質が改善： 不規則だった生活リズムが整い、夜になると自然と眠りにつけるようになりました。
「近所の解像度」が上がった
これまで見落としていた近所の風景を知れるのも楽しみの一つです。実際、隣駅まで歩いている途中で偶然新しいジムのオープンを知り、それがきっかけで筋トレも始められました。

デメリット

出費の増加
シューズやウェアを揃え始めると、こだわりたいものがどんどん増えていきます。さらに活動範囲が広がると欲しいガジェットも増え、お財布への攻撃力は意外と高めです（本人は満足していますが！）。
アキレス腱の痛み
最近の悩みは、歩き始めのアキレス腱の痛みです。体が温まると和らぎますが、冷えや疲労の蓄積も影響しているようです。シューズやフォームを試行錯誤していますが、時には「適切な休養」も重要なタスクだと痛感しています。

エピローグ

毎日1万2000歩歩いた結果、忘年会では見事2位にランクイン！
いただいた豪華賞品は以下でした。

Vitalityタオル
Vitalityマルチラージバッグ
(SUMITOMOの文字が入った)ブランケット
【参加賞】豆蔵オリジナルスクイーズボトル(個人的にはこれが一番嬉しかった)

~~これってほぼ全部住友生命からもらったグッズ...~~
今回手にしたウォーキング習慣、それこそが最大の賞品だったのかもしれません。

忘年会が終わったらウォーキングも少し落ち着こうかと思っていた矢先、社内の方からお声がけをいただき、「第12回東京エクストリームウォーク100」に来年の5月出場することにしました！
小田原から東京の有明まで、100kmを制限時間26時間で歩き抜く過酷な大会なので、今以上に歩けるように準備したいと思っています。
今からならまだ間に合いますので（ちなみに私は初参加です）、ご興味ある方はぜひ一緒に挑戦しましょう！

Kiro × Sphinxで効率化するプロジェクト開発手法

2025-12-24T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第24日目の記事です。

はじめに

AWSは2025年11月18日、AIエージェント型IDEKiro(https://kiro.dev)の一般提供を発表しました。

筆者は以前プレビュー版を使ってのレビュー記事を執筆しました。
それ以来Kiroのファンとなり、現在は実業務でKiroを使用しています。

AIエージェント型IDE「Kiro」の登場により、個人開発やプロトタイピングの速度は劇的に向上しました。
しかし、開発規模が大きくなるにつれて、「AIへの指示（コンテキスト）」をどのように管理するかという新たな課題も生まれています。

筆者は、この課題を解決するためにドキュメントビルドツール「Sphinx」を導入しました。
この試みは今のところうまくいっています。今回は、その開発スタイルを紹介します。

1. 従来のKiro開発における「規模の壁」

Kiroは非常に優秀ですが、ある程度規模の大きい開発プロジェクトに適用しようとすると、以下の2点でコンテキスト管理の限界に直面します。

① requirements.md の肥大化と混乱

Kiroの基本的な使い方は、.kiro/specsディレクトリ内の requirements.md に要件を記述することです。
しかし、機能が増えるにつれてこのファイルは数百行・数千行に膨れ上がり、AIが文脈を見失ったり、人間側もメンテナンスが困難になります。

② ディレクトリ分割のジレンマ

これに対する策として、.kiro/specs ディレクトリ内に機能ごとのサブディレクトリを作り、そこに requirements.md を分散させる方法があります。
しかし、これには 「鶏と卵」の問題 があります。開発初期の要求分析段階では、どのような機能分割が最適かはまだ見えていません。
Kiroと会話しながら要件を詰めたい段階で、事前にディレクトリ構造をカチッと決めるのは不向きであり、柔軟性を損ないます。

2. 解決策：Sphinxによる構造化ドキュメント管理

そこで提案したいのが、Python製ドキュメントツールとして有名な Sphinx を、要求仕様書や設計書の管理・ビルド基盤として採用する方法です。

Sphinxは単なるマニュアル作成ツールではありません。テキストベースで構造化されたドキュメントを管理できるため、Kiroとの親和性が極めて高いのです。

3. Sphinx導入の5つのメリット

要求仕様書や設計書をSphinxプロジェクトとして管理することで、具体的に以下の効果が得られます。

人間にとっての可読性向上（HTML/PDF化）
- 複数のテキストファイルをビルドし、見やすいHTMLやPDFとして出力できる
- 開発者やステークホルダーは、コードのようなテキストファイルではなく、整理された「仕様書」としてブラウザで全体像を確認できる
文書構造によるコンテキスト整理
- Sphinxの toctree 機能を使えば、ファイルを機能やレイヤーごとに分けて管理しつつ、1つの体系的なドキュメントとして統合できる
- Kiroに指示を出す際も「今回は auth.rst（認証機能）を参照して」と明確にスコープを限定できる
テキストベースだからKiroが読める
- Sphinxのソースコードはプレーンテキストであるため、Kiroはプロジェクト内のドキュメントを直接読み込み、理解できる
- 「仕様書そのもの」がAIへのプロンプトとして機能する
図解（画像）によるコンテキスト共有
- Sphinxプロジェクト内に配置した画面モックアップ、ER図、分析モデルなどの画像をKiroは認識できる
- 「この図に従って実装して」と指示することで、テキストだけでは伝わりにくいニュアンスを共有可能となる

Caution

画像サイズが大きすぎると読み込めない場合があります。（筆者の実体験より）

概要から詳細仕様への自動生成フロー
- 人間が「システムの概要」や「業務フロー」をざっくりと書き、それをベースにKiroへ「各機能のユースケース記述を作成して」と依頼できる
- AI自身にドキュメントを書かせ、仕様を固めてから実装に移る「上流工程の自動化」が可能になる

4. 実践：Kiro × Sphinx

実際にKiroへどのように指示を出せばよいか、具体例を紹介します。

4.1. 新規にプロジェクトを作成する場合の初期プロンプト例

Specモードで下記のプロンプトを打ち込みます。

アルバムアプリを作成したい。

docs/requirements内にSphinxで要求仕様書を作成して欲しい。
HTMLのテーマはsphinx-rtd-themeを使用して。
PodmanでビルドできるようにDockerfileとHTML, PDFビルド用のバッチファイルを作成して。
Dockerfileのベースイメージはsphinxdoc/sphinx-latexpdfを使用して。

Kiroは要求仕様書を作成するためのプロジェクトを開始します。

ある程度、要求仕様書に書く内容がイメージできている場合は、文書の構成を指示しても良いでしょう。

requirements.mdと要求仕様書は日本語で書いて
ドキュメント構成は下記のようにして

index.rst      # 全体目次
├ overview/
│  └ index.rst # システム概要
├ usecase/
│  ├ index.rst         # ユースケース目次
│  ├ uc01-login        # UC01_ログインする
|  ├ uc02-browse       # UC02_アルバムを閲覧する 
|  ├ uc03-upload       # UC03_コンテンツをアップロードする
|  ├ uc04-edit         # UC04_コンテンツを編集する
|  ├ uc05-delete       # UC05_コンテンツを削除する
|  └ uc06-manage-users # UC06_ユーザーを管理する
├ screen/
│  ├ index.rst         # 画面仕様目次
│  ├ login.rst         # ログイン画面
│  ├ main.rst          # メイン画面
│  ├ edit.rst          # 編集画面
│  └ manage-users.rst  # ユーザ管理画面
└ changelog/
   └ index.rst         # 改訂履歴

Information

要求仕様書に書く内容は、プロジェクトにより変わってくると思います。
絶対この構成でなければならないというものではないので、柔軟に対応しましょう。

上記の指示で作成された仕様書が下記です。
何も要件を入力していないですが、AIが勝手に想像して仕様を書いてくれています。

バッチファイルは軽微な修正が必要でしたが、HTMLやPDFにビルドするときれいに出力されます。

PDFにはスタイルの不自然なところがありますが、Kiroと相談しながら進めれば、専門的なTexの知識がなくても修正は可能です。

4.2. 要求仕様書の修正プロンプト例

要求仕様書の修正は、手書きで修正可能なほか、
下記のようにSpecモードで要件を列挙して修正させることも可能です。

docs/requirements内のアルバムアプリの仕様ですが、下記のようにしたい

ユーザー認証はGoogleアカウントを使用すること。
管理者権限のあるユーザーのみ、ログイン可能なユーザーを追加・削除ができること。
管理者権限のあるユーザーは、バックエンドアプリケーションの設定ファイルで可能なこと。
写真だけでなく、動画もアップロード可能であること。
アップロード可能なファイルの上限は100MBであること。
アップロード可能なファイルの拡張子はJPG, PNG, HEIC, MP4, MOVであること。
ファイルのメタ情報から日付を取得し、『/data/pict/<YYYYMMDD>』というパターンのディレクトリを作成し、その中にファイルを保存すること。
ファイルのサムネイル画像を作成し、『/data/thumb/<YYYYMMDD>』というパターンのディレクトリを作成し、その中にサムネイル画像を保存すること。
写真の一覧はサムネイル画像を表示すること。
サムネイル画像のサイズは縦幅、横幅が300ピクセル以下となること。

4.3. 設計書の作成プロンプト例

要求仕様書が書けたら設計書も作成します。Specモードで下記の指示を出します。

docs/requirements内のアルバムアプリの仕様に基づいて、
docs/design内にSphinxでアーキテクチャ設計書を作成して欲しい。

フロントエンドはAngular、バックエンドはASP.NET Coreで。
実行環境と開発環境はPodmanコンテナ上で動くこと。

上記の指示で作成された設計書が下記です。

Dockerイメージにsphinxcontrib-mermaid拡張機能がインストールされていたため、ドキュメントをビルドするとKiroがMermaidで描いた図も表示されました。

4.4. 実装フェーズでのプロンプト例

実装フェーズでは、Specモードで下記のように指示を与えます。

docs\requirementsの要求仕様書と、
docs\designの設計書を参考に、
アルバムアプリのログイン機能を実装して

これだけの指示で、Kiroはログイン機能に必要な情報を探し出してrequirements.mdを作成してくれます。

これ以降は、下図のフローに従って実装まで進めていくだけです。

まとめ

Sphinxを導入することで、要求仕様書や設計書を「人間が読みやすい形式」と「AIが処理しやすい形式」の両方で管理できるようになります。

今回ご紹介した手法であれば、開発規模の大きなプロジェクトでもKiroを扱いやすくなるのではないでしょうか。

本記事を今後の開発の参考にしていただければ幸いです。

AWS認定12冠から3年後 - 更新と新認定区分について

2025-12-23T00:00:00.000+00:00

これは、豆蔵デベロッパーサイトアドベントカレンダー2025第23日目の記事です。

はじめに

2022年12月12日に「AWS認定資格を12個すべて取得したので勉強したことなどをまとめます」という記事を投稿してから3年が経ちました。
この記事では、その後の3年間でどのような変化があったか、そして新しく追加された認定区分についてまとめます。

Information

秘密保持契約（NDA）があるため、詳細な試験内容については触れることができませんので、ご了承ください。

3年間の振り返り

2022年10月にAWS認定12冠を達成してから、3年間が経過しました。この間、いくつかの認定が有効期限を迎え、更新が必要になりました。

認定の更新について

AWS認定は有効期限が3年です。2022年に取得した認定は、2025年には更新が必要になります。
今回更新対象となった資格は、5資格です。

プロフェッショナル2資格の更新

プロフェッショナル2資格（ソリューションアーキテクト、DevOpsエンジニア）は下位資格の更新も含むため、期限となる6月より余裕をもって1月に更新しました。
プロフェッショナルレベルの認定は、下位のアソシエイトレベルの認定（Solutions Architect – Associate、Developer – Associate、SysOps Administrator – Associate）も同時に更新されるため、一度の更新で複数の認定を維持できるメリットがあります。

AWS Certified Solutions Architect – Professional
- 内容は以前と変わらず、Organizationを中心としたアーキテクチャ、セキュリティ、運用など幅広い知識を問われました
- マルチアカウント戦略やガバナンス、コスト最適化、災害復旧など、エンタープライズレベルの設計に関する問題が多く出題されました
- 問題文は相変わらず長文で、要件を整理しながら読む必要がありました
AWS Certified DevOps Engineer – Professional
- こちらも以前と変わらず、ソリューションアーキテクトとセットで受験すると勉強した知識などを活かせました
- CI/CDパイプラインの設計、インフラストラクチャの自動化、モニタリングとログ管理などが主な出題範囲でした
- 廃止となるはずだったCode Commitが出てきて「今更これを問う意味はあるのか？」と疑問に思いましたが、撤回されたので意味ありました

専門知識3資格の再取得

専門知識3資格（セキュリティ、機械学習、高度なネットワーキング）は準備期間に余裕を持たせ、有効期限を気にせず失効後に順次再取得しました。
専門知識資格はプロフェッショナル資格と異なり、下位資格の更新には含まれないため、個別に更新する必要があります。
高度なネットワーキングは苦手で再受験キャンペーンにお世話になりました。

AWS Certified Security – Specialty
- 受験したタイミングではSCS-C02でしたが、以前と特に変わったと思う点はありませんでした
- IAM、セキュリティグループ、ネットワークACL、WAF、GuardDuty、Security Hubなど、セキュリティに関する幅広い知識が問われました
- マルチアカウント環境でのセキュリティガバナンスや、コンプライアンス要件を満たすための設計に関する問題も多く出題されました
- SCS-C03では生成AI関連のセキュリティも増えるようなので、カバーする範囲が増えそうです
AWS Certified Machine Learning – Specialty
- 2026年3月31日に廃止が発表されました
- 内容は以前と変わらず、機械学習が中心でした
- Amazon SageMakerを中心とした機械学習パイプラインの構築、モデルの訓練とデプロイ、モニタリングなどが主な出題範囲でした
- データの前処理、特徴量エンジニアリング、モデルの評価方法など、機械学習の基礎知識も必要でした
AWS Certified Advanced Networking – Specialty
- 今回の更新で一番内容が変わっていた気がします
- 以前はDirect ConnectやVPN接続が中心でしたが、今回はAWS Global Accelerator、CloudFront、Route 53などのグローバルネットワークサービスに関する問題が増えていました
- マルチリージョン環境でのネットワーク設計や、ハイブリッドクラウド環境での接続性に関する問題も多く出題されました
- Transit GatewayやGateway Load Balancerなど、比較的新しいサービスに関する問題も増加していました

廃止になった専門知識3資格

廃止となり、取得日から3年たった日に無効化されていきました。
これらの資格は、新しい認定区分への統合や、AWS認定プログラムの再編成により廃止されました。
有効期限が切れるまでは認定として有効でしたが、更新の機会はなく、自然に失効していきました。

AWS Certified Database – Specialty
AWS Certified Data Analytics – Specialty
AWS Certified SAP on AWS – Specialty

3年間で得た経験

2022年の記事では「実際にAWSを触ってシステムを構築したわけでもないので、今後は実際のシステム構築で使える技能を付けていきたい」と書きました。
この3年間で、実際のプロジェクトでAWSを活用する機会はありましたが、まだ簡単なアプリケーションの方式設計程度にとどまっています。

実務でのAWS活用

実際のプロジェクトでは、以下のような場面でAWS認定で学んだ知識が役立ちました：

既存システムの理解
- すでに動いているAWSシステムを理解する際に、認定で学んだ知識が大いに役立ちました
- どのAWSサービスが使われているか、サービス間がどのように連携しているかを理解する際に、認定で学んだ各サービスの特徴や使い方の知識が参考になりました
- システムの構成図やドキュメントを読む際に、AWS認定で学んだ知識があることで、理解がスムーズになりました
システムの動作確認や調査
- 既存システムの動作確認やトラブルシューティングの際に、認定で学んだ知識が役立ちました
- IAMロールやセキュリティグループの設定を確認する際にも、認定で学んだ知識が理解の助けになりました
設計レビューやドキュメント理解
- 他のメンバーが設計したAWS構成や、既存システムのドキュメントを理解する際に、認定で学んだ知識が役立ちました
- 認定で学んだベストプラクティスやセキュリティの知識があることで、設計の意図や注意点を理解しやすくなりました

認定知識と実務のギャップ

認定で学んだ知識と実務には、いくつかのギャップがあることも実感しました：

実務では複数のサービスを組み合わせる必要がある
- 認定試験では個別のサービスの知識が問われますが、実務では複数のサービスを組み合わせてシステムを構築します
- サービス間の連携や、データフローの設計など、より実践的な知識が必要だと感じています
コストとパフォーマンスのバランス
- 認定試験では「最適な解決策」を選ぶ問題が多いですが、実務ではコストとパフォーマンスのバランスを考慮する必要があります
- 実際のプロジェクトでは、予算の制約や、既存システムとの互換性など、試験では考慮されない要素も重要です
実際の構築・運用経験の不足
- 認定で学んだ知識は主に設計や概念に関するもので、実際の構築や運用の経験はまだ不足しています
- 今後は、実際にAWSを使ってシステムを構築し、運用する経験を積んでいきたいと考えています

新認定区分について

2022年以降、AWS認定には新しい区分が4つ追加されました。そのうち3つはすでに取得済みで、デベロッパーサイトの記事にもしています。

今回話題に挙げるのは、4つ目の新認定区分である生成AIデベロッパープロフェッショナルです。

AWS Certified Generative AI Developer – Professional

AWS Certified Generative AI Developer – Professionalは、Amazon BedrockなどのAWSサービスを使用した、本番環境に対応するAIソリューションの構築およびデプロイにおける高度なスキルを証明するプロフェッショナルレベルの認定です。

試験の概要

カテゴリ: Professional
ベータ試験期間: 205分
ベータ試験形式: 85問、択一選択問題および複数選択問題
ベータ試験料金: 150 USD（日本では22,000円（税込み））
ベータ対象言語: 英語および日本語

なお、再受験キャンペーンは使えませんが、通常の半額バウチャは使えます。

対象となる受験者

この認定は、2年以上のクラウド経験があり、キャリアを高めたいと考えている開発者に最適です。
対象となる受験者は、以下の要件を満たしている必要があります：

AWSで、またはオープンソーステクノロジーを使用して本番環境グレードのアプリケーションを構築した2年以上の経験
一般的なAI/MLまたはデータエンジニアリングの経験
生成AIソリューションの実装における1年の実務経験
AWSコンピューティング、ストレージ、ネットワーキングサービスの経験
AWSセキュリティのベストプラクティスとID管理についての理解
AWSのデプロイとInfrastructure as Codeツールの経験
AWSモニタリングおよびオブザーバビリティサービスについての知識
AWSコスト最適化原則の理解

ベータ試験について

ベータ試験なので機械学習エンジニア-アソシエートやAIプラクティショナーの時と同じく認定ガイドに沿って準備を進めました。

ベータ試験は通常の試験とは異なり、試験内容や形式が確定する前の段階で受験する試験です。
AWS認定では、標準バージョンの試験で問題が使われる前にベータ試験を使用して試験問題の質が検証されます。
ベータ試験の合格者は新しい認定の最初の取得者になります。

最初の5,000名の試験参加者には、合格時に特別なEarly Adopterバッジが贈られます。

そのため、認定ガイドをしっかりと確認し、出題範囲を理解した上で準備することが重要です。

準備方法

ベータ試験の準備として、以下のような方法で学習を進めました：

認定ガイドの確認
- 出題範囲と各ドメインの重み付けを確認し、重点的に学習すべき領域を把握しました
- 生成AIデベロッパープロフェッショナルの場合、Amazon Bedrock、Amazon SageMaker、AWS Lambda、Amazon API Gatewayなどが主な対象サービスでした
公式ドキュメントとハンズオン
- Amazon Bedrockの公式ドキュメントを読み込み、主要な機能や使い方を理解しました
- AWS Skill Builderの関連コースや、ハンズオンラボで実際にサービスを触ってみました
- 生成AIアプリケーションの構築パターンや、ベストプラクティスを学習しました
関連認定の知識の活用
- AI PractitionerやMachine Learning Engineer – Associateで学んだ知識を活用しました
- Solutions Architect – Professionalで学んだアーキテクチャ設計の知識も役立ちました
- セキュリティやモニタリングに関する知識も、生成AIアプリケーションの設計に必要でした
実務経験の活用
- 実際のプロジェクトでは簡単なアプリケーションの方式設計程度しかできていませんが、その経験が問題の理解に少しは役立ったと思います
- ただし、実務では限定的な経験にとどまっているため、認定ガイドでカバーされている範囲を広く学習する必要がありました

受験してみた

受験してみました。
しっかり準備したつもりでしたが、思っていた内容と異なっていました。

試験の難易度と特徴

問題数と時間
- 205分で85問という構成で、1問あたり約2.4分の時間配分が必要でした
- 問題文と選択肢が非常に長文で、文章から構成図をイメージするのに時間がかかりました
- 複数のサービスを組み合わせた複雑なシナリオが多く、全体像を把握するのに時間がかかりました
出題内容の特徴
- Amazon Bedrockを中心とした生成AIアプリケーションの構築に関する問題が多く出題されました
- 本番環境での運用を考慮した設計（スケーラビリティ、セキュリティ、コスト最適化など）が問われました
- 複数の選択肢が正解に見える問題が多く、ベストプラクティスに基づいた判断が求められました
- エラーハンドリングやモニタリング、ログ管理など、運用面での考慮事項も多く出題されました
時間配分の課題
- ギリギリまで時間がかかり、見直しの時間がほとんど取れませんでした
- 文章を読むのが遅いのを直さなければいけないと、いつも感じています
- 長文の問題を素早く理解し、要点を整理する能力が重要だと実感しました

結果と今後の対策

X（旧Twitter）などでは合格報告をよく見かけますが、残念ながら不合格でした。
正式リリースまでに、以下の点を改善して準備を進めたいと思います：

長文問題への対応
- 問題文を素早く読み、要点を整理する練習を重ねる
- 構成図やアーキテクチャ図を素早くイメージできるようにする
実践的な知識の強化
- Amazon Bedrockを使った実際のアプリケーション構築経験を積む
- 本番環境での運用を考慮した設計パターンを学習する
関連サービスの深い理解
- AWS Lambda、Amazon API Gateway、Amazon CloudFrontなど、生成AIアプリケーションでよく使われるサービスの詳細な理解を深める
- セキュリティ、モニタリング、コスト最適化などの観点から、ベストプラクティスを学習する

認定取得のモチベーション維持

3年間、認定を維持し続けるためには、継続的な学習が必要です。
以下のような方法でモチベーションを維持してきました：

継続的な学習方法

定期的なAWSサービスのキャッチアップ
- AWSの公式ブログや、re:Inventのセッション動画を定期的に視聴して、新しいサービスや機能をキャッチアップしています
- AWS Skill Builderのコースを活用して、体系的に知識を更新しています
- 特に生成AI関連のサービス（Amazon Bedrock、Amazon Qなど）は、頻繁にアップデートがあるため、継続的な学習が必要です
実務でのAWS活用
- 実際のプロジェクトでAWSを使うことで、認定で学んだ知識を実践で活用し、理解を深めています
- 実務で直面した課題を解決する過程で、新しい知識やベストプラクティスを学んでいます
- 認定で学んだ知識が実務で役立つことを実感することで、学習のモチベーションが維持されます
新しい認定区分への挑戦
- 新しい認定区分が追加されると、新しい知識を学ぶ機会として積極的に挑戦しています
- ベータ試験に参加することで、新しい認定の最初の取得者になることを目指しています
- 新しい認定区分への挑戦は、学習のモチベーションを高める良いきっかけになります

モチベーションの源泉

また、2026 Japan All AWS Certifications Engineersのクライテリアを満たすことが大きなモチベーションとなっています。
2023年、2024年、2025年と3年連続で対象となり、引き続きすべてのAWS認定資格を保持し続けることが目標です。

この目標を達成するためには、以下のような取り組みが必要です：

認定の更新計画
- 各認定の有効期限を管理し、更新が必要な認定を事前に把握しています
- プロフェッショナル資格は下位資格も更新されるため、優先的に更新するようにしています
- 専門知識資格は個別に更新する必要があるため、計画的に準備を進めています
新しい認定区分への対応
- 新しい認定区分が追加されたら、できるだけ早く取得するようにしています
- ベータ試験に参加することで、早期に取得できる可能性があります
- 新しい認定区分への対応は、すべてのAWS認定資格を保持し続けるために必要です
コミュニティとの交流
- X（旧Twitter）や技術ブログなどで、同じ目標を持つ人たちと情報交換をしています
- 認定取得の経験や、学習方法などを共有することで、モチベーションを維持しています
- コミュニティとの交流は、学習の継続を支える重要な要素です

まとめ

2022年にAWS認定12冠を達成してから3年が経過し、いくつかの認定の更新が必要になりました。
また、この間に新しい認定区分が追加され、AWS認定の選択肢が広がりました。

認定を取得することはゴールではなく、継続的な学習のきっかけとして活用していきたいと考えています。
今後も、新しい技術や認定区分にチャレンジし続けていきたいと思います。

【脱ブラックボックス】AWS Control Tower Account Factory & AFC の裏側を徹底解剖！

2025-12-22T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第22目の記事です。

こんにちは！AWSの世界を探求する皆さん。
突然ですが、AWS Control Tower 使っていますか？

今私が携わっているプロジェクトにおいてAWS Control Tower（以降Control Tower）を導入したアカウント運用の話があり、個人ではあまり使う機会が少ないサービスだと感じたので、この機会に使っていく中で判明した挙動について書き留めておこうと思います。

そもそもControl Towerってどんなサービスなの？という話を軽くしておくと、
AWS Control Towerは、AWSのベストプラクティスに基づいたマルチアカウント環境（ランディングゾーン）を自動的にセットアップし、継続的なガバナンスを提供するサービスになっています。

この記事で紹介するのは主にControl Towerの「Account Factory」と「Account Factory Customization（以降AFC）」による「アカウント作成」の挙動についてです。

プロジェクトとして、Account Factoryの処理をAWS CLIコマンドを直接たたくことで実現する必要があったため、AWSマネジメントコンソール（以降マネコン）からアカウント作成を実行した時の裏側で走る処理について、AWS CloudTrail（以降CloudTrail）のイベント履歴を追うことでAWS CLIコマンドで実現する方法を明確にしていきました。

そこで以降では「Account Factory」と「AFC」の具体的な処理フローについてまとめていきたいと思います。
また、AWS CLIコマンドではマネコン上で操作した時と同じように再現はできないことも合わせてお伝えしていきたいと思います。

前提

冒頭にて本記事での内容について述べましたが、以下については詳しくふれません。
そのため、ある程度AWSになれていて、AWS Organizations（以降Organizations）やAWS IAM Identity Center（以降Identity Center）などのアカウント・ユーザー管理系サービスの知識、用語の理解がある方向けの内容になっています。適宜注釈や参照リンク、軽い説明は混ぜていきますが、ご了承ください。

Control Towerの開始方法や操作、関連用語
Organizationsの機能やIdentity Centerの機能と操作、関連用語
AWS Service Catalogについての機能や操作、関連用語

また、検証にあたり以下については設定済み・リソースがあるという前提とOrganizationsとIdentity Centerを絡めた組織的なアカウント運用・管理を前提にした内容で記事を書いています。

AWSルートアカウントからIdentity Centerを有効化し、AWSルートアカウントにAdmin権限でアクセスできるユーザーを設定している
参照: 管理アクセスを持つユーザーを作成する
Control Towerのランディングゾーンを開始している
- AWSルートアカウントで有効化したIdentity CenterとControl Towerの間でアクセス制御統合をしていること
- AWS Service Catalog（以降Service Catalog）の製品「AWS Control Tower Account Factory」が存在していること
AFCを利用するためのブループリント^[1]ハブアカウントが存在する
参照: カスタマイズのための設定

1. Account Factoryの正体は「Service Catalog製品」

Control Towerを知っている方や使ったことがある方はご存じだと思いますが、アカウント作成を実行するにはControl Towerのコンソール画面にある「Account Factory」から操作を行います。
実はこれ、Control Tower独自の機能というよりも、Service Catalog というサービスをラッピングしたものなんです。

大まかに何をしているのか

Control Towerの管理アカウント（ランディングゾーンを開始したアカウントのこと）で Service Catalog のコンソールを開いてみてください。「製品」のリストに 「AWS Control Tower Account Factory」 という製品があるはずです。

マネコン上からControl Towerで「アカウント作成」ボタンを押すことは、裏側では 「Service Catalogの『AWS Control Tower Account Factory』という製品を起動している」 こととイコールになります。
後ほどより具体的に説明していきます。

なぜ Service Catalog なのか？

ここでなぜわざわざControl TowerからService Catalogを介してアカウントを作成するのか疑問に思った方もいると思います。普通にOrganizationsからアカウント作ればいいのでは？と思いますよね。
このようにアカウントを作成することにはメリットがあります。（でなければわざわざサービスとして提供しなくてもいいですからね。。）

権限の分離
本来、アカウント作成やIAM設定には強力な権限（AdministratorAccess相当）が必要です。しかし、経理担当者や各プロジェクトリーダーにそんな強権を渡したくないですよね？

Service Catalogを使えば、「この『Account Factory製品』を使う権限」だけをユーザーに渡せばOK です。（正確にはControl Towerを操作する権限を渡しておけばOkです。）

つまり、管理アカウントにログインするユーザーに、OrganizationsやIdentity Centerを操作する権限は付与しなくてよいということになります。

コントロールとベースラインの適用
Control Towerを経由することで、単にアカウントを作成するだけでなく、組織的な管理下に置かれた「統制の効いた」アカウントとして払い出すことができます。これは、企業が複数のアカウントを安全かつ効率的に運用するために不可欠な要素です。

具体的には、アカウント作成時に「コントロール（旧ガードレール）^[2]」や「ベースライン^[3]」と呼ばれるセキュリティ設定やログ設定が自動的に適用されます。これにより、管理者は個々のアカウント設定を確認する手間を省くことができ、常にポリシー（AWSのベストプラクティスに基づくセキュリティ基準のこと）に準拠した状態を維持できます。

2. アカウント作成時の「裏側の挙動」

では、実際にアカウント作成ボタンを押したとき、裏側でどのようなフローが走っているのか、CloudTrailのイベント履歴を元に正確なフローを見ていきましょう。

以下の処理は、主にSTS（Security Token Service）を使用して一時的かつ強力な権限にスイッチしながら行われます。
また、各リソースの作成確認（Describe、List系のコマンド）は随時並行して処理が走っています。

STEP 0: 設定と製品の確認

まず初めに、DescribeAccountFactoryConfig が実行され、現在のControl TowerにおけるAccount Factoryの設定情報が取得されます。
これに基づき、以下の手順でService Catalog製品の確認が行われます。

SearchProductsAsAdmin
所有者が「AWS Control Tower」であるService Catalog製品を検索します。
DescribeProduct
検索で見つかった製品（Account Factory）の詳細を取得します。
この時、製品の中身（AWS CloudFormationテンプレート、以降CloudFormationテンプレート）が新しいバージョンになっている場合、CreateProvisioningArtifact が実行され、製品の更新処理が走ることがあります。

STEP 1: Account Factory製品の起動 (ProvisionProduct)

Control Towerにおけるアカウント作成の実体である ProvisionProduct が実行されます。
これにより、「AWS Control Tower Account Factory」製品の起動が開始されます。

STEP 2: 管理アカウントへの登録 (CreateManagedAccount)

製品の起動の中で、作成されたアカウントをControl Towerの管理下に置くための CreateManagedAccount 処理が走ります。
これにより、単なるOrganizationsのアカウントとしてだけでなく、Control Towerによって管理・監視される「Managed Account」として登録されます。（作成時にしてたOU配下に登録されます。）

STEP 3: ユーザーとグループのセットアップ (CreateUser)

Identity Centerにおいて、新規作成されたアカウントへアクセスするためのユーザー作成、グループへの追加などの処理が行われます。

STEP 4: ベースラインとコントロールの適用

AWS CloudFormation StackSets（以降CloudFormation StackSets）が発動し、STEP 0で確認されたベースラインやコントロール（各種セキュリティ設定やログ設定など）が、アカウントに対してデプロイされます。

STEP 5: アクセス権限の割り当て (CreateAccountAssignment)

最後に、新規作成されたアカウントに対して、Identity Centerの許可セット（Permission Set）とユーザー（またはグループ）の割り当てが実施され、ユーザーがログイン可能な状態になります。

上記のようなステップを踏んで実際の「Account Factory」の処理が進みます。
あまり複雑になりすぎないよう簡潔にまとめましたが、Service Catalog製品の起動からベースラインなどの適用まで一貫して実施されていることがお分かりいただけたかと思います。

3. Account Factory Customization (AFC)

続いて、Account Factoryの拡張版ともいえるAFCについてのフローを見ていきましょう。

「Control Towerの標準設定だけじゃ足りない！アカウント利用開始時にIAMロールや必要なAWSリソース構成も最初から入れておきたい！」というような、
AWSが用意しているデフォルトのService Catalog製品で展開されるリソースに加えて独自の設定内容をアカウント作成時に適用したいという要望に応えるのが Account Factory Customization (AFC) です。

Account FacotryがAWSマネージドな処理で、AFCがカスタマーマネージドな処理というとらえ方でよいかと思います。（厳密には違いますが、イメージはそんな感じです。）

AFCの仕組み：Service Catalog on Service Catalog

AFCを使うと、Account Factory実行時に使用されるデフォルトのブループリントとは別に、「追加のカスタムブループリント」 を指定できるようになります。

※補足をしておくと、Account Factory時にはAWS内部的にデフォルトのブループリントが使用されています。それと対比して、AFC時に使うブループリントをここではカスタムブループリントと呼んでいます。
公式リファレンスにも表記がされているのですが、例のごとく「ブループリント=デフォルトのブループリント」だったり、「ブループリント=カスタムブループリント」だったり表記ゆれがあるので、明確に区別しておきます。

この「ブループリント」ですが、実態は Service Catalog製品として登録されたCloudformatinoテンプレート です。

管理アカウント、あるいは「ハブアカウント」にあるカスタムブループリントを、デフォルトのブループリントを実行した後に適用してくれます。

つまり、Control Towerがアカウント新規作成時にデフォルトで作成してくれるリソースを維持しつつ、独自に追加したいリソースも入れることができるということです。
※カスタムブループリントは公式的に「ハブアカウント」に置くことが推奨されています。

AFC実行時の裏側の挙動

さて、ここでも背後の挙動を追ってみましょう。通常のAccount Factoryとは少し異なる動きを見せます。
STEP 0（設定確認）までは通常時と同様ですが、その後の動きに特徴があります。

CreateManagedAccount（の実行）
AFCの場合、通常の ProvisionProduct は実行されずに、CreateManagedAccount が実行されます。
このリクエストパラメータには、通常のAccount Factoryの情報に加え、「blueprints」（事前にハブアカウントに作成しておいたService Catalog製品の情報、カスタムブループリントのこと）が含まれています。
IdCユーザー関連処理
通常と同様に、新規作成アカウントへアクセスするためのIdentity Centerユーザー作成処理などが走ります。
ベースラインとカスタムブループリントの適用
CloudFormation StackSetsによって、標準のコントロールやベースライン（デフォルトのブループリント）が適用されます。
これは推測になってしまいますが、 指定したカスタムブループリントはこのタイミングで適用される と考察しています。
なぜこのような考察に留まってしまったのかは以下の「ブラックボックスな部分」にまとめました。
アクセス権限の割り当て
最後にユーザーやグループへのアクセス権限割り当てが行われます。

ブラックボックスな部分
興味深い点として、カスタムブループリントの適用に関する明確なAPI呼び出し（例：ハブアカウントからの製品取得など）がCloudTrail上では確認できませんでした。

しかし、事実としてハブアカウント上のService Catalogではカスタムブループリント製品が実行された形跡が残っているため、CreateManagedAccount実行の背後で別の処理（製品の取得など）が走り、適用のタイミングとしてはデフォルトのブループリント適用の後にカスタムブループリントを適用しているのではと考察しました。

何度か試して確認ができなかったので、CloudTrailのイベント時系列から上記のような処理になるのではないかと予想しています。

4. プロジェクトでの実例と直面した壁

ここからは、実際のプロジェクトで直面した課題とその解決策についてお話しします。
今回のプロジェクトでは、Control Towerを開始した管理アカウント（アカウントA）とは別のAWSアカウント（アカウントB）から、AFC機能を使ってアカウントを作成したい という要件がありました。

試みたこと

当初は、「APIが用意されているはずだから、クロスアカウントでもSTSでスイッチロールしてコマンドを叩けば大丈夫だろう」と安直に考えていました。

しかし、現実はそう甘くありませんでした…。

AFC実行用のCLIコマンドが存在しない
まず、AFCの処理フロー等価である CreateManagedAccount というCLIコマンドが存在しません。 Control TowerのAPIリファレンスを探しても相当するコマンドは見つかりませんでした。
Service Catalogコマンドの限界
CLIでAccount Factoryを実行するために servicecatalog provision-product コマンドを利用することは可能です。
しかし、このコマンドでは product-id （製品ID）を 1つしか指定できません。
つまり、通常の「AWS Control Tower Account Factory」製品を指定すると、AFCで利用したい「カスタムブループリントの製品ID」を同時に渡すことができないのです。

そのため、「デフォルトブループリントの適用→カスタムブループリントの適用」という連動した動きが再現できなくなります。

デフォルトブループリントを適用した後にもう一度カスタムブループリントを指定してコマンドを実行すれば？と思うかもしれませんが、これだと新規作成アカウントの情報が連携できていないので、カスタムブループリントの内容がアカウントB上で実行されるだけになります。
クロスアカウントの制約
さらに、クロスアカウントで実行する場合、ハブアカウントに存在しているService Catalog製品（カスタムブループリント）の情報が取得できないという制限もありました。

ハブアカウントからカスタムブループリント製品を管理アカウント側に共有（厳密には製品を管理するポートフォリオを共有）して試してみましたが、これもうまくいかなかったです。（そもそもSearchProductsAsAdmin CLIコマンドにおいて共有した製品が管理アカウント上で認識できなかったです。。）

辿り着いた解決策

最終的に、API（CLI）ベースで要件を満たすために以下のアプローチを採用しました。

通常のAccount Factoryでアカウントを作成
まず、provision-product コマンドを使用して、標準のAccount Factory製品を起動し、Control Tower管理下のアカウントを作成します。これだけならアカウントBからでも実行可能です。
CloudFormation StackSetsでカスタマイズを適用
アカウント作成が完了した後、別途 CloudFormation StackSets を使用して、AFCで適用したかったカスタムリソース（IAMロールなど）を新アカウントに適用します。

一発でAFCを実行することはできませんでしたが、手順を分割することで「Control Tower管理下の統制の効いたアカウント」かつ「独自のカスタマイズが施されたアカウント」をAPIベースで作成することができました。

5. Control Towerのメリットと「手の届かない」部分

ここまで、Account Factoryの挙動やカスタマイズについて深掘りしてきました。
Control Towerは、セキュリティのベストプラクティスに沿った環境を簡単に構築・維持できる非常に強力なサービスです。ボタン一つ（あるいはコマンド一つ）で、ログ集約やアクセス制御が整ったアカウントが手に入るのは素晴らしいことです。

しかし、その「自動化」と「標準化」の裏返しとして、手の届かない部分 も存在します。

Control Towerの限界（変更できない設定）
Control Towerによって自動作成・管理されるリソースの中には、ユーザー側で設定変更ができない（または推奨されない）ものがあります。
全ては挙げれませんが、私が実際に設定変更をしようとしてできなかったものとして以下の2点があります。

CloudTrail用S3バケットの設定
ログアーカイブアカウントに作成されるS3バケットのライフサイクルポリシーなどを自由に変更することができません。要件に合わせてログ保存期間を変えたい場合など、柔軟な対応が難しいことがあります。
AWS Configアグリゲーター
組織全体のConfigルールを集約するアグリゲーターも自動生成されますが、この設定もユーザーが自由にカスタマイズすることは難しい部分です。
一度Control Towerによって自動で作られたアグリゲーターを削除してみましたが、ドリフト検出されて常に警告がでてやや鬱陶しかったです。。

その他にも、Control Towerによって作成・管理されているCloudformationテンプレートで展開されているリソースには手を加えない方が無難でしょう。

これらの「手の届かない部分」があることを理解した上で、Control Towerの標準機能でどこまでカバーし、どこからは独自の実装（例えば別途S3バケットを作る、独自のConfigルールを追加するなど）で補うかを判断することが、Control Towerとうまく付き合っていくコツだと感じました。

まとめ

本記事では、AWS Control TowerのAccount FactoryとAFC機能について、その裏側で実行されている処理フローを解説してきました。

Account Factoryの実体は、Service Catalog製品 として提供されており、アカウント作成のリクエストは、Service Catalogを経由して AWS Organizations や AWS CloudFormation StackSets に連携されます。
これらの一連の処理によって、アカウント作成からセキュリティ設定（コントロールとベースライン）の適用、Identity Centerへのユーザー登録までが自動化されています。

Account Factory Customization (AFC) も同様に、Service Catalog製品として登録した （カスタム）ブループリント を利用することで、標準の設定に加えて独自のリソースを自動的にデプロイする仕組みを提供しています。

Control Towerは一見ブラックボックスに見えるかもしれませんが、その裏側で動いているのは、IAM（Identity Centerを含む）、CloudFormation、Service Catalogといった基本的なAWSサービスです。
この構造を理解しておくことで、エラー発生時のトラブルシューティングや、より高度なカスタマイズが必要になった際の対応力が大きく向上するはずです。

Control Towerは頻繁にアップデートが行われており、APIによる運用の柔軟性も徐々に向上していくと予想しています。
特にAFC機能については、現状ではAPI連携において一部制約がありますが、将来的にはCLIやSDKを通じたよりシームレスな自動化が可能になることを期待したいところです。
引き続き最新の動向をウォッチし、より効率的なマルチアカウント運用を目指していきたいと思います！

注釈

ブループリント (Blueprint): AWSアカウントの構築やカスタマイズに使用される、事前に構成されたテンプレート（実態は主にCloudFormationテンプレート）。 ↩︎
コントロール (Controls): AWS環境全体（OU単位）に適用されるガバナンスルール（旧称: ガードレール）。予防的コントロール（SCP）と発見的コントロール（Config/AWS Lambda）などがあります。 ↩︎
ベースライン (Baseline): OUなどのターゲットに適用されるリソースとその設定のグループ。 ↩︎

ロボット開発にもクリーンアーキテクチャを。美膳®が実現する中食工場の自動化

2025-12-19T00:00:00.000+00:00

少し公開が遅くなってしまいましたが、これは豆蔵デベロッパーサイトアドベントカレンダー2025第15日目の記事です。

はじめに

豆蔵は長年にわたり、ロボットシステム開発の支援およびコンサルティングを行ってきました。
オリジナルロボット「BEANus」シリーズなどで培ってきた技術力は、単なるメカニクスの制御にとどまらず、高度なソフトウェア技術との融合にあります。

今回、三井化学株式会社と共同開発した中食（なかしょく）工場向け食品盛り付けロボット美膳®（びぜん）は、まさにその結晶です。
詳細なプレスリリースはこちらをご覧ください。

私は、主にソフトウェアアーキテクトとして美膳®の開発に携わりました。
今回、ロボット開発では珍しいクリーンアーキテクチャ（Clean Architecture）を採用し、ドメイン中心設計を実現しました。
本記事では、食品盛り付けロボット美膳®の紹介と、それを支えるソフトウェアアーキテクチャについて紹介します。

美膳®の紹介

美膳®は、中食業界で深刻化する労働力不足を解消するために開発された、食品盛り付けロボットシステムです。
豆蔵がシステム設計、メカ・エレキ設計、そしてAI・ビジョン・モーションを含むソフトウェア開発を担当し、三井化学が高機能樹脂素材の提供やロボットハンドの開発、製造・販売を担当するという、両社の強みを活かした共同開発によって生まれました。

美膳®が解決したい社会課題

下図に示すように、中食工場では多くの盛り付け作業が人手で行われており、労働力不足や人件費高騰が深刻な問題となっています。
このような背景から、盛り付け工程の自動化が強く求められています。

画像提供：株式会社豆蔵

美膳®で出来ること

美膳®は、弁当や惣菜の盛り付け作業を自動化します。
具体的には、以下のような高度な作業を高速かつ正確に行います。

食材の認識とピッキング: 番重（食材コンテナ）内にランダムに置かれた食材を、AIビジョンで瞬時に認識し、最適な把持位置を判断してピッキングします。
容器への追従盛り付け: ベルトコンベア上を流れる容器の位置・姿勢・速度をカメラを使ってリアルタイムに認識し、ロボットアームが追従しながら正確な位置に食材を盛り付けます。
双腕による協調動作: 左右のアームが互いの状況をリアルタイムに共有し、上流での作業漏れを下流でカバーしたり、作業負荷を分散させたりするなど、双腕ならではの柔軟な連携により生産性を最大化します。

特徴

美膳®には以下の大きな特徴があります。

1. 業界最速レベルの生産性

中食工場での人の作業スピードは1時間あたり約2,000食と言われていますが、美膳®はこの人の作業と同等の生産能力（2,000食/時）を実現しました。従来の盛り付けロボットの多くが1,200食/時程度であったのに対し、大幅な生産性向上を達成しています。

2. 迅速な段取り替え

多品種少量生産が求められる中食工場では、頻繁なライン変更が必要です。美膳®はキャスター付きで移動が容易であり、ロボットハンドも簡単に交換できる設計になっています。これにより、生産品目が変わっても短時間でラインを切り替えることができます。

3. 軽量・コンパクト

三井化学の高機能樹脂素材を採用することで、軽量化と高剛性を両立しました。また、双腕ロボットでありながら小型化を実現しており、既存の盛り付けラインの限られたスペースにも導入しやすくなっています。

4. 人との協働

非接触の外装センサーを搭載することで、人が近づくと自動で減速・停止する機能を備える予定です。これにより、安全柵なしで人とロボットが同じ空間で作業することが可能になります。

Information

※本機能は現在開発中であり、現行品には搭載されていません。

ソフトウェアアーキテクチャの紹介

私はソフトウェアアーキテクトとして、この美膳®の開発に携わりました。
よって、ここからはソフトウェアアーキテクチャの概要について説明します。

美膳®における設計思想

美膳®は単にメカが動くだけでなく、AIによる認識、複雑なモーション制御、そしてそれらを統合するシステム全体が高度に連携して動作しています。

このシステムの核となるのは、「食品を認識し、把持し、盛り付ける」という「食品盛り付け業務（ドメイン）」 です。
このドメイン知識をシステムの中心に据え、特定のハードウェアといった技術的詳細に依存しない設計を目指しました。

アーキテクチャ設計においては、以下の点を重視しました。

ドメイン中心: 「食品盛り付け」という業務ロジックを最重要視し、技術的詳細から分離すること
保守性: 長期間にわたる運用と機能追加に耐えうる構造であること
テスト容易性: ハードウェアに依存せず、ロジック単体でのテストが可能であること
独立性: フレームワークやセンサ・インジケーターなどの外部要素への依存を最小限に抑えること

特に、独立性を重視した理由は、美膳®には食品盛り付けロボットシステムのプラットフォームとしての役割も期待されており、将来的に新しいセンサ技術などが登場した際に、容易に置き換えられる柔軟性が求められたためです。

以上より、次節で説明するクリーンアーキテクチャ（Clean Architecture） の思想を取り入れた設計を採用しました。

クリーンアーキテクチャとは

クリーンアーキテクチャ（Clean Architecture）は、Robert C. Martin (Uncle Bob) 氏によって提唱されたソフトウェア設計思想です。
同心円状の図で表現されることが多く、外側から内側に向かってのみ依存関係を持つ「依存性のルール（Dependency Rule）」が最大の特徴です。

The overriding rule that makes this architecture work is The Dependency Rule. This rule says that source code dependencies can only point inwards. Nothing in an inner circle can know anything at all about something in an outer circle.

(出典: The Clean Architecture | The Clean Code Blog)

このアーキテクチャにおいて、最も内側に位置するのは「エンティティ（Entities）」や「ユースケース（Use Cases）」といったドメイン（ビジネスロジック） です。
データベースやWebフレームワーク、UI、そしてロボットにおけるデバイスといった詳細な技術要素は、すべて外側に配置されます。

つまり、「ドメインが詳細（インフラ）に依存するのではなく、詳細がドメインに依存する」 という構造を作ることが、クリーンアーキテクチャの核心です。
これにより、技術の流行り廃りやハードウェアの変更といった外的要因から、システムの核となるビジネスロジックを守ることができます。

具体的な設計の紹介

システム物理配置

システムの物理配置図を以下に示します。

ステレオタイプ<<app>>の要素がソフトウェアの実行単位となります。
よって、以下の3つが主要なソフトウェアの実行単位となります。

名前	説明
GUIApp	GUIを有するアプリケーションである。ユーザ向けのGUIを提供する。コントローラPC上で実行され、操作パネルのタッチパネル上に表示される。
ControllerApp	本システムのコアアプリケーションである。機能的にはシステムの状態制御や登録データの管理、画像処理を行う。その手段として、コントローラPCに接続されたデバイスの制御、Databaseの操作を行う。また、GUIAppから接続可能なサーバー機能を有する。また、生産運転中に限り、画像処理結果を供給するビジョンサーバー機能を有する。
MotionController	ロボットモーション制御を主に担うアプリケーションである。また、DIO接続デバイスや安全基盤との結合も担う。モーション制御に関する機能を持つサーバー機能を有し、ControllerAppがクライアントとして接続される。また、生産運転実行中はControllerAppのビジョンサーバーに接続し、画像処理結果を取得する。

Information

GUIAppとControllerAppが何故別々の実行単位なのか

非機能要件で将来的に操作パネルをタブレット端末など別デバイスに変更する可能性があるため、GUI部分を分離している。

Information

コントローラPCとロボットコントローラが分かれている理由

PoC段階でロボットコントローラとしてKEBA社のコントローラを使用していたため。

コンポーネント構成

美膳®のソフトウェアコンポーネント設計について解説します。
全体は、クリーンアーキテクチャのように同心円の表記ではありませんが、同様の思想に基づいて設計されています。
クリーンアーキテクチャの同心円にて中心方向に依存が向かうのと同様に、依存方向は下に向かっており、下層にはEntitesやInteractorなどのドメインロジックが配置されています。

コンポーネント	説明
ControllerApp	関連コンポーネントを結合し、実行可能にするアプリケーションコンポーネント。
ControllerAPI	外部（GUIAppや上位システム）との通信を担うAPI層。
Adapter	外部サービス(ビジョン・モーションなど)の実装コンポーネント。
Controllers	メインのビジネスロジックを束ねるコンポーネント。
Controller	ユースケース（Interactor）を統合・制御するコンポーネント。一般的なクリーンアーキテクチャのController（Interface Adapters）とは異なり、ここでは複数のInteractorを束ねる「アプリケーションサービス」に近い役割を担う。
StateMachine	システムの状態遷移を管理するコンポーネント。Interactorで実現される機能に対して横断的にシステム状態遷移を実現する。
Port	Adapterのインターフェース定義コンポーネント。外部サービスのインターフェースとなる。
Interactor	ユースケースに応じたビジネスロジックフロー(機能)を実現する中心的なコンポーネント。
Entities	ドメインモデルやデータ構造を定義するコンポーネント。
VisionController	画像処理関連機能を有するコンポーネント。
VisionAPI	画像処理機能を外部に提供するAPI。
MotionControllerAPI	MotionControllerの機能を外部に提供するAPI。REST APIによるMotionControllerへの指令送信や状態取得をラップする。
Common	再利用性の高い共通で使用される汎用的なコンポーネント群。ロギング、数値計算、スレッド制御などの機能を集約している。

この構成における重要なポイントは、Port (インターフェース) と Adapter (実装) の分離です。

例えば、ビジョンシステムやモーション制御といった外部要素は、Portコンポーネントで定義されたインターフェースを通じてのみアクセスされます。
実体である Adapterは、このインターフェースを実装する形で提供されます。
これにより、Interactorなどのビジネスロジックは、具体的なカメラの機種やロボットコントローラの通信プロトコルを知る必要がなくなります。

結果として、ビジネスロジックが分離され、ハードウェアの変更が容易になり、テストの効率化と保守性の向上を実現しています。

おわりに

今回は、中食工場向け盛り付けロボット美膳®の概要と、その裏側にあるソフトウェアアーキテクチャについてご紹介しました。

ロボット開発はハードウェアとソフトウェアが密接に関わるため複雑になりがちですが、適切な設計パターンを適用することで、もっと楽しく、効率的に開発できるようになります。
この記事が、日々ロボット開発に奮闘されているエンジニアの皆さんのヒントになれば嬉しいです。

豆蔵では、こうしたモダンな設計思想を取り入れたロボット開発を推進しています。
「ちょっと話を聞いてみたい」「ウチのロボットも何とかして」という方は、ぜひお気軽にご連絡ください。

ユーザー部門のあなたに送る - 「『情シスはテストしたのに…』と言わせない！クマに学ぶ“ユーザーテスト”のホントの意味」

2025-12-19T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第19日目の記事です。

こんにちは＆はじめまして、教育グループのやさぐれ豆ぱんだこと、おのでらです。

ユーザー部門（ビジネス部門）の皆様、ユーザーテスト（受け入れテスト）の依頼が来るたびに、正直、こう思ったことはありませんか？

「情シスがちゃんとテストしたはずなのに、なんで私たちが改めてテストしなければいけないの？」

忙しい業務の合間を縫ってのテスト作業。「バグがないか確認するだけなら、プロである情報システム部門（以下、情シス）だけで完結してほしい」「これって二度手間じゃないの？」
……そう感じてしまう気持ち、とてもよく分かります。

しかし、実は 「皆様がやらなければならない、代わりのきかない理由」 があるのです。

その理由を体感していただくために、少しだけ 「2つのチェック」 にお付き合いください。

チェック1：間違い探し

まず、以下の2つの画像を見比べてみてください。
「クマの設計書と完成イメージ^[1]」と、それを元に「実際に作られたクマの完成品（成果物）」です。

(↑クマの設計書)

(↑クマの完成品（成果物）)

この2つを見比べて、違う箇所を探してみてください。
「ここが違う」「あそこの色が違う」……いくつか見つかりましたか？

見つかった方は、どこが違うか心の中でメモしておいてください。

チェック2：目的の確認

では次に、全く別の視点で考えてみてください。
そもそも、この「クマ」は何のために作ったのでしょうか？

実は、以下のような要件（目的）があったとします。

【目的】
会社の受付に置き、来訪されるお客様からの「会社の好感度」や「知名度」を上げるためのマスコットを作りたい。

この目的を聞いた上で、改めて先ほどの「ブロックのクマ」を見てください。
そして、 「これを自社の受付に置くべきかどうか」 を判断してみてください。

いかがでしょうか？

「おもちゃのようなブロックを受付に置くのは、会社のイメージに合わないのでは？」
「好感度を上げるという目的には、もっと洗練されたデザインの方がいいのでは？」
「なぜクマなの？というかパンダだよね？頼んでないクリスマスツリーもついてきてるよね？」
「いやいや、ウチもうマスコットキャラクター居るし」

おそらく、多くの人が 「この目的には適していない」 と感じたのではないでしょうか。

ここで種明かし：2つのテストの違い

さて、皆様には今、2種類のチェックを行っていただきました。
実はこの2つが、そのまま「情シス」と「ユーザー部門」の役割の違いを表しています。

1つ目のチェック＝「システムテスト（情シス）」

最初に行った「間違い探し」は、 情報システム部門が実施する「システムテスト」 です。
これは「元々の設計書と見比べて、設計書通りに正しく作られているか」を確認する作業です。

情シスは、設計書通りにブロックが組まれているか（バグがないか）は完璧にチェックできます。しかし、それが「受付に置くのにふさわしいか」までは判断できません。

2つ目のチェック＝「ユーザーテスト（皆様）」

次に行った「目的の確認」こそが、 皆様、ユーザー部門の皆様が実施する「ユーザーテスト」 です。

ユーザーテストで重要なのは、設計書通りかどうかのチェックではありません。
「要件定義で挙げた課題（好感度アップ）が本当に解決するのか」「このシステムは今の業務や目的に適しているのか」 を確認することです。

ちなみに「間違い探し」の箇所は

口の色がピンクじゃなくて赤
体の色が茶色じゃなくて白黒（≒クマじゃなくてパンダ）
舌が長い
左耳が長い
設計書に無い「クリスマスツリー」が作られている（誰だ、途中で要件追加したのは!?）

まとめ：だから、皆様の「視点」が必要です

1つ目のチェックで「設計通り完璧なクマ」ができていたとしても、2つ目のチェックで「受付にはふさわしくない」と判断されれば、ビジネスとしては失敗です。

そして、「これは受付に置けないな」と判断できるのは、普段その業務を行い、顧客と接している ユーザー部門の皆様だけ なのです。

「情シスがテストしたのに……」と感じることもあるかと思いますが、これからのユーザーテストでは、ぜひ 「業務のプロとしての視点」 を大切にしてください。

「バグを探す」のではなく、 「このシステムは、私たちの仕事を本当に良くしてくれるか？」 という視点で触っていただくことが、プロジェクト成功の鍵となります。

お知らせ

今回ご紹介した「クマの事例」は、 ユーザー部門向け研修 でお伝えしている内容のほんの一部です。

この研修では、単なる「テストの手順」や「要件定義のコツ」といったテクニック論ではなく、

なぜ、ユーザー部門がプロジェクトに関わらなければならないのか
なぜ、情シス任せではプロジェクトが失敗するのか

という 「本質的な役割と責任」 について深く掘り下げて解説します。

「システム導入のたびに『やらされ感』を感じている」というユーザー部門の方はもちろん、
「ユーザー部門にもっと当事者意識を持ってほしい」と感じている情報システム部門の方 にも、ぜひご覧いただきたい内容です。

お互いの「視点」を合わせ、プロジェクトを成功に導くために。
詳細は以下のリンクからご確認ください。

▼ 研修の詳細・お申し込みはこちら

https://www.mamezou.com/services/hrd/user_department_training

※本記事の画像作成には、ヨシリツ株式会社の知育玩具「[LaQ（ラキュー）]」を使用しています。

https://www.laq.co.jp/
↩︎

よりよい方法を見つけだそうとし続けている：アジャイルに必要な知恵はすべて鮨屋のカウンターでも学んだ

2025-12-18T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第18日目の記事です。

はじめに

生成AIの進歩等により、人間にはますます知識よりも知恵が必要だと感じるビジネスソリューション事業部アジャイルグループの岸本大輔です。
アジャイル開発宣言が公開されてもうすぐ四半世紀。人によっては「まだまだこれから」「もうあたりまえ」あるいは「今となっては古い」など様々な意見があるようですが、重要なのは「よりよい方法を見つけだそうとし続けている」ことだと思います。
SAFeやLessやScrum@ScaleやDA等、アジャイルをスケールする工夫もそれぞれ進化しています。用語やこだわりポイントは多少違いますが、お互いリスペクトしながら参考にされているので少し抽象化して見ると似ている部分も多いですね。経済学や心理学等、様々な分野の知見もうまく活かしながら「よりよい方法」を見つけだそうとし続け、永遠のβ版になっている印象です。
それでも「スクラムのイベントが形骸化している」という悩みを持つチームもあります。「アジャイル」「スクラム」「リーン」などの名前ややり方だけではなく「何のために？」「どうなると幸せ？」について考えていると、ソフトウェア開発以外でも似たようなことがたくさんあり、それらを見つけて参考にするのが「気付き」や「刺激」になると思います。
ということで今回はお鮨屋さんを舞台に、アジャイルについて考えてみたいと思います。アジャイル初心者向けの知識習得には適していませんが、スクラムマスタやアジャイルコーチの考え方の引き出しを増やすための「気付きのきっかけ」になるとうれしいです。
以前、よりよい方法を見つけだそうとし続けている：自由があればよりよく進化するでも、「何でもアジャイルに見える例」をいくつかご紹介いたしましたが、今回のお話はお鮨屋さんに行くたびにアジャイルについて考えてしまう症状が出てしまう可能性がございますので、あらかじめご了承いただけますようお願いいたします。

人生に必要な知恵はすべて幼稚園の砂場で学んだ

ちょっと昔の本ですが、タイトルがキャッチ－で覚えていらっしゃる方も多いのではないでしょうか？
実際、幼稚園の砂場で多くのことを学んでいたと思います。人生（そしてアジャイル）について。
昼寝の時間までのタイムボックス。こんなこともあったのでは？
砂場で「山を作りたいな～」「おもしろそうぼくも作る～」「わたしも～」みんなでモブワーク。
「ぼくは水をかける」「じゃあわたしは山を固めるね」「ぼくはトンネル掘るね～」「じゃあわたしは反対側から掘るわ」と自己管理。
「砂の固め方が弱くてつぶれちゃったね」「水かけすぎちゃってごめんね」ってふりかえり。
「じゃあ次はもっと大きい山にしてトンネル２本掘ろうか？」「楽しみ～♪」って次に何をするかの計画を相談。
そしてミルクを飲んでみんなでお昼寝♪

アジャイルに必要な知恵はすべて鮨屋のカウンターでも学んだ

みなさんお鮨はお好きでしょうか？
お鮨屋さんではテーブル席で握りセットを頼みますか？それともやはりカウンターで一貫ずつ頼みますか？

例えば2人でテーブル席に座って、メニューで握りの「松セット」「竹セット」「梅セット」の写真と価格を見て、どれにするか選んだ場合、それぞれ一人前の個数やネタの種類や価格がはっきりしていて、全て揃ってからまとめて配膳（リリース）されます。なんだかウォーターフォールっぽいですね。
いきなりまとめて出てくるので、もし一貫食べて期待外れでもどうしようもありません。

ではカウンターに座った場合はどうでしょうか？
「飲み物は何にされますか？」みたいな感じで会話が始まり「今日は天然ひらめの縁側が入ってますよ～」ってことで「じゃあ塩炙りで」と答えつつネタケースに目を走らせる。
食べたいものから順番に食べたいタイミングで注文し、お腹がふくれて満足すればいつでもごちそうさま♪
もし期待外れなら早々に店を出ることもできます。

他のお客さんも、それぞれお気に入りのお鮨を頬張っています。
カウンターの中で握っている鮨職人さんは、周りの何人かのお客さんの注文を聞いて、基本的には注文された順番でお客さんに提供しますが、炙ったり多少時間がかかる注文は前後することもあります。
でもなぜかそれで揉めることはあまり無いんですよね～
鮨職人さんの状況がお客さんたちに全部見えている（見える化されている）のが大きいんだろうなぁと思います。
もちろん聞こえる化も有効です。他のお客さんが注文してる時に割り込んで注文したりしないですよね？（自粛的排他制御？）
他のお客さんが「このウニおいしい～」って言ってるとウニが食べたくなるし、ネタケースを見てトロサーモンが少なくなってたら次に頼もうと思っていた寒ブリやめて、先にトロサーモンを頼んでみたり...
優先順位は自然に次々変わっていきますよね～

お客さんが食べる速度と、鮨職人さんの握る速度。だいたい３～５人ぐらいのお客さんを相手に握れる感じでしょうか。
ネタ等の都合により多少前後することはあっても、注文の順番は結構重要です。
それぞれのお客さんごとにプロダクトバックログがありつつ、それらを時系列でマージして１人の鮨職人さんが握るイメージ。
赤だしやお茶やお酒類などの注文は、鮨職人さん以外の店員さんが非同期で持ってきてくれることが多いですね。

注文するお客さんはそれぞれプロダクトオーナー。握ってくれる鮨職人さんは開発者。親方（店主）はスクラムマスターという感じでしょうか？
（店を拡大したい場合、「カウンター５席＆鮨職人さん１人」の単位で増やしていけば大規模アジャイル？）

「またこの鮨屋で食べたいなぁ」と思うか思わないかは、何で変わるでしょうか？

お鮨の味はもちろん、価格や店の雰囲気や鮨職人さんの対応等、全ての顧客体験が影響しますよね？
ネタが新鮮で調理器具や食器も清潔で衛生上問題が無いというのはもちろん、頼んだお鮨の味が期待以上においしいという「体感できる価値」が品質。

鮨職人さんが特に気をつけるべきことはなんでしょうか？
食中毒等の発生防止や身だしなみ等、衛生面。
お客さんに快適に過ごしていただく言葉遣いや振る舞い等、接客面。
観光地の近くのお店であれば、英語での観光地紹介も多少はできた方がよさそうですね。
そしてもちろんカウンターに立つにふさわしい鮨職人としての調理スキルや品位。

でも、もしも「お客様と鮨職人さんの間に入ってやたら管理したがるタイプの親方がいる鮨屋」だったら？

親方が気になることはなんでしょうか？一貫の米粒の数が360～370になっていることでしょうか？
鮨職人さんが握ってお客さんの前に出したヒラメの握りを「ちょっとリリースしても問題がないか検査します」と言って横取りして米粒を数えたりしますでしょうか？
顕微鏡で一貫一貫、お客さんの目の前で確認し「菌はいません。安心して召し上がってください」と言いたいでしょうか？
それでお客さんは安心しますでしょうか？
逆に不安になるのではないでしょうか？

鮨職人さんがカウンターでお客様に鮨を握っている「今」　親方が本当にやるべきことは何でしょうか？

もちろん食品衛生法や食品表示法、水産物の規格基準や労働安全衛生関連等の遵守が必要です。そしてHACCPに沿った衛生管理も2021年6月以降義務化されています。
特にお鮨屋さんは生魚を扱うため、食中毒リスクが高く、徹底した衛生管理が必須です。
でもお客さんの体験品質も重要ですよね。

完了の定義、準備完了の定義、受入基準のように分けるとこんな感じでしょうか？

完了の定義（店全体での品質基準）
　法令・安全基準
　　食品衛生法遵守：調理場の衛生、従業員の健康管理、食材保管温度。
　　HACCP対応：工程ごとの危害要因分析と管理基準。
　　アレルゲン・原材料表示：テイクアウトや宅配時の必須情報。
　店舗体験（ユーザーエクスペリエンス）
　　清潔なカウンターと器具。
　　鮨職人の所作が美しく、雰囲気が落ち着いている。
　　提供タイミングはお客様のペースに合わせる。
準備完了の定義（握り始める前に満たす必要がある条件）
　ネタが規定温度で保管されている。
　調理器具が洗浄・消毒済み。
　鮨職人の手洗い・衛生確認完了。
　注文内容が明確で、お客様の好み（わさび有無など）確認済み。
受入基準（鮨ネタごとの品質基準）
　「ユーザーストーリーごとの受入条件」に近い考え方。
　お客さん個人ごとにネタに対する期待値は異なりますが、それに対してどの程度超えられるのかが重要。
　おいしさを数値的に表すのは難しいですね。同じ鯛でも産地や季節や個体によって異なりますし...
　鯛（白身魚）
　　鮮度：透明感と弾力あり。
　　温度：冷蔵0～5℃。
　　切り付け：筋目を活かした美しい断面。
　うなぎ
　　加熱：中心温度75℃以上で1分以上。
　　タレ：焦げすぎず均一な照り。
　　提供：温かいうちに出す。
　ウニ
　　色：鮮やかな黄色～オレンジ。
　　匂い：海の香り。異臭なし。
　　盛り付け：崩れないよう丁寧に。

店内の清掃や、シャリやネタの準備は、もちろん暖簾を上げる前に完了させますが、開店から時間がたてば、ネタの補充や鮨職人の休憩なども必要になります。
一般の飲食店でも「大きな声で店員に指示する店主がいるお店はちょっと落ち着かない」と思われる方が多いと思いますが、落ち着いた静かなお鮨屋さんならなおさらですよね。
熟練した鮨職人さんは状況さえ把握すれば何をすべきかもわかります。ですので状況に「気付いてもらう」だけで十分です。もし何をすべきかわからない時はその場は親方が対応し、閉店後に反省会。
親方は静かに目や耳で店内の状況を観察しながら、目配せや目立たない振る舞いで、阿吽の呼吸で鮨職人さんたちとコミュニケーションをとり、絶えずよりよい顧客体験になるよう配慮されています。
この心地よさはおいしい日本酒も効いてるのかなと思いつつ、そろそろ満腹です。ごちそうさま♪

おわりに

海外でも人気のお鮨。一人前の鮨職人さんになるには10年以上の修業が必要と言われていますが、最近では年齢や性別関係なく専門の学校で短期間に効率よく技術習得もできるようですね。
ここでもよりよく流れるように進化するという「コンストラクタル法則」が当てはまりそうです。
確かな技術の上で、さらにお客さんに満足いただけるように、自分たちで自由に工夫する。そのフィードバックはリアルタイムに返ってくる。
よりよい方法を見つけだそうとし続ける自由は誰も奪えない。

お鮨屋さんのカウンターで鮨職人さんが握ったお鮨を、お客さんがおいしそうに食べているのを見ていると、アジャイルについてもいろいろ考えてしまいます。
もうすぐ2026年。みなさまにとってよりよい年になりますように！

Kiro で始める Property-Based Testing：想定外を炙り出す

2025-12-17T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第17日目の記事です。

1. はじめに：なぜ今、PBTを試すのか

プロパティベーステスト（以下 PBT）は、仕様から抽出された「満たすべき性質（property）」を任意の入力・状態・操作系列に対して検証するテスト手法です。PBT は、従来の事例ベーステストと相互補完的な関係にあることが知られています^[1]。

正直、この説明だけでピンと来る人は多くないのではないでしょうか。私自身も、以前から興味はあったものの、満たすべき挙動の形式化が難しい、実装コストが高そうと感じて手を出せずにいました。

しかし、2025年11月17日に GA となった Kiro では、IDE 機能として 「プロパティベーステストによる仕様の正確性検証」 が導入されました^[2]。この新機能により、PBT 導入のハードルが下がったように見えたため、実際に手を動かして体験してみることにしました。

Kiro の PBT 機能については、公式ドキュメント「Correctness with Property-based tests」を参照してください。

2. なぜ PBT なのか：EBT との決定的な違い

書籍『実践プロパティベーステスト』^[3]では、PBT の特徴を次のように説明しています。

テストのための例をたくさん書いたり、コードに投げるためのランダムなデータを生成したりするのではなく、コードに潜む思いもよらなかった新しいバグを見つけるための手法である

具体例で考えてみましょう。従来の事例ベーステスト（EBT）では「1 と 3 を足したら 4 になる」のような特定の例を確認します。一方 PBT では「どんな数字を 2 つ足しても、順番を変えて足した結果と同一になる」という普遍的な性質を定義します。

左図は EBT、右図は PBT のイメージです。EBT はテストケースを手動で作成し検証する一方、PBT はプロパティを定義してランダムな入力で検証します。

つまり、EBT は予測可能なバグに強く、PBT は予測できなかったバグを発見できる可能性があります。この違いは、後半の UI 表示テストで実感することになります。

3. 題材に「チケット管理」を選んだ理由

Kiro + PBT の解説記事として、「部屋移動ゲーム」を題材にした Medium 記事^[4]があります。

このゲームは、以下の構造により PBT に非常に向いています。

状態 × 操作 × 不変条件（Property）

同じ構造は、 業務アプリケーションにも頻出すると考え、
今回はその一例である、「チケット管理」を題材とすることにしました。

チケット管理には以下の特徴があります。

状態遷移の制約
終端状態の不変条件
再実行・順序依存性
異常系の保証

これらは 事例ベーステストでは拾いにくいが、PBT と相性が良い性質です。
そのため、実務への応用を意識してチケット管理を題材に選びました。

4. 仕様：極めてシンプルなチケット管理

今回は、あえて仕様を極限まで単純にしました。

チケットの状態

Status = { Open, InProgress, Done }

上記の３つのみ

許可される状態遷移

Open        → InProgress
InProgress  → Done

上記以外の遷移はすべて無効
Done は終端状態であり、どの操作も受け付けない

この最小仕様を、Kiro に入力していきます。

5. Kiro による Property-Based Testing の実行

5-1. 要件文書（requirements.md）の生成

まず、Kiro IDE に以下の要件を入力します。

- GUI ベースの簡易チケット管理アプリを作成する
- 永続化は不要、検証用の最小アプリとする
- チケットは必ず3状態のいずれかを持つ
- 状態は「未対応→対応中→完了」の一方向のみ遷移可能
- 完了状態から他状態へは遷移できない
- 状態更新はボタン押下で切り替える
- 機能は作成・一覧・状態更新に限定
- 状態遷移ルールを不変条件として PBT で検証したい

以下のような要件文書が出力されました。
受入基準が EARS 記法^[5](「Easy Approach to Requirements Syntax: 要件定義の構文ルール)で明確に言語化されています。

要件文書の抜粋

### 要件3

**ユーザーストーリー:** ユーザーとして、チケットの状態を更新したい。作業の進捗を正確に反映するため。

#### 受入基準

1. WHEN ユーザーが未対応チケットの状態更新ボタンを押した時 THEN Ticket_System SHALL そのチケットを対応中状態に変更する
2. WHEN ユーザーが対応中チケットの状態更新ボタンを押した時 THEN Ticket_System SHALL そのチケットを完了状態に変更する
3. WHEN チケットが完了状態の時 THEN Ticket_System SHALL 状態更新ボタンを無効化する
4. WHEN 状態遷移が実行される時 THEN Ticket_System SHALL 未対応から対応中、対応中から完了の順序のみを許可する
5. WHEN 完了状態のチケットに対して状態変更が試行された時 THEN Ticket_System SHALL その操作を拒否し現在の状態を維持する

特に注目したのは、無効な遷移は拒否される、完了状態では操作できない、状態遷移の順序制約といった 後続の Property 定義につながる記述が明確になっていた点です。

5-2. 設計文書（design.md）と Property 定義

設計書生成時、Kiro は次のことを宣言しました。

設計文書の前半部分を作成しました。次に、受入基準の分析を行ってから正確性プロパティを定義します。

出力結果の抜粋は以下でした。
Property が設計成果物として明示的に出力されています。

設計文書の抜粋

### プロパティ1: チケット作成時の初期状態
*任意の*有効なタイトルに対して、新しいチケットを作成すると、そのチケットは常に未対応状態で作成される

### プロパティ2: チケット作成時のリスト追加
*任意の*チケットリストと有効なタイトルに対して、新しいチケットを作成すると、リストのサイズが1増加し、新しいチケットがリストに含まれる

### プロパティ3: チケット表示内容の完全性
*任意の*チケットに対して、そのチケットをレンダリングした結果には、タイトルと現在の状態情報が含まれる

### プロパティ4: 有効な状態遷移の実行
*任意の*チケットと有効な遷移（未対応→対応中、対応中→完了）に対して、状態更新操作を実行すると、チケットの状態が期待される次の状態に変更される

### プロパティ5: 無効な状態遷移の拒否
*任意の*チケットと無効な遷移に対して、状態更新操作を実行しても、チケットの状態は変更されない

### プロパティ6: 完了状態での操作無効化
*任意の*完了状態のチケットに対して、状態更新ボタンは無効化され、操作が実行できない

### プロパティ7: システム不変条件の維持
*任意の*操作（作成、状態更新）の実行後、システム内の全てのチケットは有効な状態（未対応、対応中、完了のいずれか）を持つ

結果として、状態遷移だけでなく、初期状態の不変性、表示内容の完全性、システム全体の不変条件など、人が明示的に頼んでいない Property まで含めて 7 件が定義されました。

5-3. 実装計画（tasks.md）と Property のトレーサビリティ

以下のような実装計画が出力されました。

実装計画の抜粋

- [ ] 2. ビジネスロジック層
  - [ ] 2.1 状態遷移ロジックのテスト作成
    - **プロパティ4: 有効な状態遷移の実行** (要件 3.1, 3.2, 3.4)
    - **プロパティ5: 無効な状態遷移の拒否** (要件 3.5, 4.2)
    - _要件: 3.1, 3.2, 3.4, 3.5, 4.2_
  
  - [ ] 2.2 状態遷移関数の実装
    - 有効な遷移の判定ロジック
    - 状態更新処理の実装
    - テスト実行と通過確認
    - _要件: 3.1, 3.2, 3.4, 3.5_

tasks.md では、Property、要件、テスト、実装タスクが対応付けられており、「なぜこのテストが存在するのか」 が追跡可能になっていました。

また、TDD によるテストファーストの原則を採用したため、以下の流れが自然に形成されています。

テスト作成 → 実装

TDDを用いたAI駆動開発については、以下の記事も参照してください。

https://developer.mamezou-tech.com/blogs/2025/11/28/qdev-aidd-spec-kit/

5-4. 実装と PBT の具体例

状態遷移の Property は、fast-check^[6] を用いた PBT として実装しました。

記述されたテストコードサンプルを提示します。任意のタイトル、任意の有効状態に対して、遷移の性質が必ず成立することを検証しています。

TypeScript と fast-check によるテストコード例

test('未対応から対応中への遷移が正しく実行される', () => {
  fc.assert(
    fc.property(validTitleArb, (title) => {
      const ticket: Ticket = {
        title,
        status: TicketStatus.PENDING
      };

      // 未対応から対応中への遷移は有効
      const isValid = isValidTransition(ticket.status, TicketStatus.IN_PROGRESS);
      const nextStatus = getNextStatus(ticket.status);

      expect(isValid).toBe(true);
      expect(nextStatus).toBe(TicketStatus.IN_PROGRESS);
    }),
    { numRuns: 100 }
  );
});

5-5. 動作確認

完成した画面にいくつかチケットを登録したり、エラーを発生させてみて、動作確認を行いました。

6. まとめ：Kiro で PBT を実装して分かったこと

正直に言うと、状態遷移だけでは PBT の凄さは分かりにくいと感じました。
今回の状態遷移のルールは単純なため、事例ベーステストでも十分に確認できてしまうからです。

しかし、UI 表示に関する Property で状況が一変します。

想定外だった発見

チケットタイトル表示の Property テストでは、
連続する空白が HTML によって正規化されることや、
前後の空白・空白のみのタイトルの扱いが曖昧であることなど、
仕様として意識していなかった問題が検出されました。

これらは、手動テストや事例ベーステストでは、まずテスト観点として挙がらなかったと思います。

この経験から、PBT の価値は「網羅的に試すこと」ではなく、
「人が想定していなかった入力や前提を炙り出すこと」
にあると実感しました。

7. おわりに

Kiro を使うことで、以下のことを実感しました。

PBT 導入の心理的・実装的ハードルは確実に下がった。
Property を中心に仕様・設計・テストをつなげられる。

今回は単体レベルでしたが、
結合テストやシステムテストでの活用も価値がありそうです。

今回使用したリポジトリは以下で公開しています。
（予告なく公開停止する可能性があります）

https://github.com/hironori-maruoka/kiro-pbt-sample

Takuto Wada. Property-based Testing の位置付け / Intro to Property-based Testing. Speaker Deck. ↩︎
Amazon Web Services. Kiro：生成 AI で IDE とコマンドライン機能を強化する新ツールが一般提供開始. AWS ブログ, 2025. ↩︎
Fred Hebert, Leonid Rozenberg. 実践プロパティベーステスト ― PropErとErlang/Elixirではじめよう. ラムダノート, 2023. ↩︎
Matheus Evangelista. Building Smarter with Kiro: A Hands-On Look at Property-Based Testing. Medium, 2025. ↩︎
Alistair Mavin. EARS: The Easy Approach to Requirements Syntax. ↩︎
fast-check. fast-check. ↩︎

GitHub Spec Kit (Gemini) でインフラストラクチャを作成してみる

2025-12-16T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第16日目の記事です。

1. はじめに

9月にKiroを使った仕様駆動開発の記事を執筆してから、約3か月経ちました。

その間に、生成AIを取り巻くエコシステムやツールは驚くべき速度で進化を続けています。
最近話題のGeminiも、リリース当初と比べると、業務利用を視野に入れられるレベルまで急速に成熟していると感じています。

今回はGitHub が提供する仕様駆動開発（Spec-Driven Development; SDD）のツール「Spec Kit」と、Model Context Protocol（MCP）に対応した AI クライアントである Gemini CLI を組み合わせて、インフラストラクチャを生成する開発手法を試してみます。

前回の記事では「Kiro × Claude」で SDD + Terraform を扱いました。
本記事ではこれを「Spec Kit × Gemini」に置き換えたうえで、特にビジネスの現場では重要となるコスト最適化・コスト把握を AWS Pricing MCP Server を使って行えるようにします。

これらを組み合わせることで、設計思想（Why）から具体的な実装（What）、そしてコードとアーキテクチャの品質保証までを一気通貫で行う、インフラ構築フローをSpec Kitでどこまで実現できるのかを検証していきます。

2. 記事のゴール

本記事のゴールは次の通りです。

Spec Kit を使いこなせるようになる
GitHub Spec Kit の 4 段階プロセス（Specify, Plan, Tasks, Implement）に沿って、インフラの仕様を定義し、具体的なコード（IaC）に落とし込む流れを体験します。
SDD を踏まえたインフラ構築フローを理解する
設計思想（Why）から実装（What）、そして品質保証までを一気通貫で行う、AI を活用した新しいインフラ構築のやり方を学びます。
コストを含めた品質保証を実現する方法を知る
AWS Pricing MCP Server を組み合わせ、Terraform コードから構築されるインフラのランニングコストを見積もりつつ、仕様レベルでコスト制約を織り込むアプローチを理解します。
実践的なインフラを構築できるようになる
上記フローを通じて、S3 と CloudFront を用いた静的ウェブサイトと、そのアクセス状況を可視化できる CloudWatch メトリクスを持つ、実践的なリソースを構築できる状態を目指します。

3. 事前知識 / 前提

本記事は、次のような読者を想定しています。

対象読者

インフラ構築・運用や、クラウド環境の設計に興味がある方
SDD（Spec-Driven Development）や IaC（特に Terraform）に興味がある方
生成 AI を用いた開発フローを、インフラ領域でも試してみたい方

本記事で扱わないこと

GitHub Spec Kit 自体のインストール手順や細かな設定方法
SDDにおける細かいプロンプト指示の内容
MCP Server（例: AWS Pricing MCP Server）のセットアップ方法の詳細
生成 AI（Gemini など）のアカウント作成や各種設定の手順
Terraform や AWS のコードの解説・公開

実施環境

Mac (M1) / macOS Sequoia 15.5^[1]
VSCode: 1.107.0
Gemini CLI: 0.20.2
Gemini 2.5 系列モデル（Flash / Pro など）
Spec Kit v0.0.90

これらの前提知識・環境は事前に整っているものとして、本記事では「どう組み合わせて活用するか」という観点に焦点を当てます。

4. 「Vibe-Coding」の限界と見過ごされるコスト

AIコーディングエージェントの能力は日々向上していますが、その利用方法の多くは、開発者の曖昧な指示（Vibe）に依存した「Vibe-Coding」に留まっています。

このアプローチでは、コードがコンパイルしなかったり、開発者の意図を正確に反映しなかったりといった、目先の生成エラーに注目が集まりがちです。

とりわけ深刻なのは、一見正常に動作しているコードが、Vibe-Coding によって大量に生まれてしまう点です。
これらのコードは、次のような「見過ごされがちなコスト」を内包しています。

属人化とブラックボックス化
- 生成時のプロンプトや前提条件が十分に残らないため、「なぜその設計になっているのか（Why）」がコードから読み取れません。
- 結果として、他の開発者には触りづらいブラックボックスとなり、修正・改善のたびに大きな認知コストが発生します。
アーキテクチャの一貫性低下
- その場その場の Vibe-Coding で機能追加を続けると、システム全体のアーキテクチャが当初の設計意図から徐々にずれていきます。
- IaC の場合、環境ごとに微妙に異なる定義が増え、「どれが正なのか」を後から整理・リファクタリングするコストが跳ね上がります。
レビュー・監査コストの増大
- レビュー担当者は、コードを読むたびに「そもそも何のための変更か？」を会話履歴やコミットメッセージから逆算する必要があります。
- セキュリティやコンプライアンスの観点では、どのコードがどの前提・ポリシーに基づいて生成されたかが追いきれず、チェックに時間がかかります。

このように、Vibe-Codingは目先の生産性を一時的に向上させるかもしれませんが、長期的な保守性や品質、セキュリティの観点では、むしろコストを増大させる要因になりえます。

5. 仕様駆動開発（SDD）の哲学

Vibe-Codingがもたらす長期的な課題に対し、GitHubは公式ブログでSpec Kitを発表し、新たな開発パラダイムとして「仕様駆動開発（SDD）」を提唱しました。

GitHubは、その哲学について次のように述べています。

"That’s why we’re rethinking specifications — not as static documents, but as living, executable artifacts that evolve with the project. Specs become the shared source of truth. When something doesn’t make sense, you go back to the spec; when a project grows complex, you refine it; when tasks feel too large, you break them down."

（だからこそ私たちは仕様を再考しています。それは静的なドキュメントではなく、プロジェクトと共に進化する生きた、実行可能な成果物として。仕様は共有された真実の源となります。何か理解できないことがあれば仕様に戻り、プロジェクトが複雑になればそれを洗練させ、タスクが大きすぎると感じたら分解するのです。）

この引用が示すエッセンスは、次の2つの重要な概念に集約されます。

仕様は「生きた実行可能な成果物」である
一度作られて陳腐化する静的なドキュメントではなく、プロジェクトの進化に合わせて更新され続け、ツールやAIがコードを生成・テスト・検証する際に直接利用する「実行可能」なファイルそのもの、という考え方です。
仕様は「信頼できる唯一の情報源」である
コードがどう動作すべきかを定義した「契約」として機能します。開発者は迷ったときに立ち戻る原点となり、AIエージェントにとっては振る舞いを決定する上での絶対的な拠り所となります。

このように仕様と実装の一貫性を強く保つことこそが、Vibe-Codingの混沌に秩序をもたらし、AIの力を最大限に引き出す鍵である、というのがGitHubの示す方向性です。

6. GitHub Spec Kitの役割

Spec Kit は、この SDD を AI コーディングエージェント（GitHub Copilot、Gemini CLI、Claude Code など）のワークフローに取り込むための オープンソースのツールキット です。

/speckit.specify：仕様（Spec）を作成する
/speckit.plan：技術スタックやアーキテクチャ方針を整理する
/speckit.tasks：作業単位に分解したタスクリストを作る
/speckit.implement：タスクに基づいて実装を進める

といったコマンドを通じて、「仕様 → 計画 → タスク → 実装」の流れを構造化し、AI に対しても一貫したコンテキストを与えられるようにします。

7. Spec Kitの構造化された開発ワークフロー

Spec Kit の大きなメリットは、「どの生成 AI を使うか」に依存しすぎず、共通のワークフローで開発を進められる点です。

現実には、複数の生成 AI を同時に利用することはコスト面で難しい場合も多く、組織として利用できる AI が限定されるケースもありますが、Spec Kit のワークフローはそうした制約の中でも再利用しやすい構造になっています。

Spec Kitは、AIとの協調作業を円滑にするため、次の4段階の明確なプロセスを定義しています。各フェーズは、特定のコマンドを通じて実行されます。

1. Specify（仕様作成）― WhatとWhyの定義

/speckit.specify コマンドを使用し、技術スタックではなく、ユーザーのジャーニー、期待される成果、成功基準 に焦点を当てて仕様（Spec）を定義します。
仕様は、利用者や要件が変わるたびに更新される「生きた成果物」として扱われ、インフラの構成もこの Spec を起点に設計されます。

2. Plan（計画作成）― 制約の組み込み

/speckit.plan コマンドで技術的な方向性を決定します。技術スタック、アーキテクチャ、コンプライアンス要件、性能目標 など、エンタープライズ制約を AI エージェントに提供し、
包括的な技術実装計画を plan.md として生成させます。ここで MCP Server からの制約も統合されます。

3. Tasks（タスク分解）― レビュー可能な単位へ

/speckit.tasks コマンドを使用し、Plan に基づき、独立して実装・テスト可能な小さな作業単位（レビュー可能な差分）に分解します。
依存関係や並列実行可能なタスク [P] が明示されることで、「どこから手を付けるべきか」が分かりやすくなります。

4. Implement（実装と検証）― 焦点を絞った変更

/speckit.implement コマンドで、エージェントがタスクリストに従って実装します。開発者は大規模なコードの塊ではなく、
特定の問題を解決する 焦点の絞られた変更 をレビューします。これにより、AI が生成した変更を人間が理解・検証しやすい単位に保つことができます。

7.1. Spec KitとKiroのプロセス対応

Spec Kit と AWS Kiro はどちらも SDD を支援するツールですが、フェーズ名や成果物の切り方が少し異なります。本記事では、おおよそ次の対応関係を意識して解説します。

観点	Spec Kit のフェーズ / コマンド	主な成果物（Spec Kit）	参考: Kiro のプロセス / ファイル例
要件・意図の明確化	Specify / `/speckit.specify`	プロダクトの目的・前提・スコープなどを整理した仕様ファイル（例: `spec.md`）	Requirements フェーズ / `requirements.md`
実現方式の検討	Plan / `/speckit.plan`	アーキテクチャ方針・技術選定・インフラ構成などをまとめた計画ファイル（例: `plan.md`）	Design フェーズ / `design.md`
作業単位への分解	Tasks / `/speckit.tasks`	実装・テスト可能な単位に分解されたタスクリスト（例: `tasks.md`）	Tasks / Implementation のタスク一覧
実装の実行・検証	Implement / `/speckit.implement`	タスクリストを基にしたコード・テスト・設定ファイル等の変更	Implementation フェーズ全体（フックやタスク実行）

※ Kiro は「Requirements → Design → Implementation」の 3 フェーズ構成で、Implementation の中にタスク実行やコード生成が含まれます。一方、Spec Kit は Tasks と Implement を分離することで、「タスク分解」と「実装実行」を明示的に分けている点が特徴です。

8. AWS Pricing MCP Server によるコスト制約の実現

本章では、AWS Pricing MCP Server の役割と、それを Spec Kit のワークフロー、とくに Implement フェーズのあとに統合することで、コストの観点からどのように制約をかけられるか解説します。

8.1. Model Context Protocol (MCP) の役割

MCP および MCP Registry を利用することで、Gemini CLI などの MCP 対応クライアントから AWS Pricing MCP Server といった外部サービスに接続できます。

Spec Kit の「Spec / Plan / Tasks / Implement」というワークフローの後にMCPを追加することで、外部ツールからの制約や推奨事項（本記事では主にコスト情報）を自然に統合します。

8.2. AWS Pricing MCP Serverによるコスト把握

AWS Pricing MCP Server は、AWS の料金情報にアクセスするための MCP Server です。
Gemini CLI から呼び出すことで、サービス種別・リージョン・利用想定などを入力し、概算の料金を問い合わせることができます。

Spec Kit の文脈では、Implement フェーズで生成された Terraform コードやアーキテクチャ案に対してコストを問い合わせることで、

どの構成が月額コストを抑えられそうか
トラフィック増加時にどの程度コストがスケールしそうか
どのリソースがコストのボトルネックになりそうか

といった観点を、AI エージェント経由で評価させることができます。

8.3. Implementフェーズ後のコスト評価への統合

/speckit.implement コマンドや、Implement フェーズで Terraform コードが生成・デプロイされたあとに、AWS Pricing MCP Server を呼び出し、実際のリソース構成に基づくコスト情報や制約・推奨事項を取得します。

これにより、パフォーマンスや可用性などの非機能要件に加え、想定トラフィックに対するランニングコストの見積もりを踏まえて、アーキテクチャやコードをリファインするループを回せるようになります。

Implement実行後は次のような流れで進めます。

リソース構成からコストを試算する
パフォーマンスとコストのバランスを評価する
必要に応じてPlan/Specを修正する

レイヤ構造として見ると、次のような関係になります。

flowchart LR
    subgraph Workflow["Spec Kit ワークフロー"]
        S["spec.md<br>What / Why"]
        P["plan.md<br>How + 制約反映"]
        T["tasks.md"]
        I["implement.md / 構築"]
        S --> P --> T --> I
    end
    subgraph Artifact["成果物"]
      A["Artifact（Terraform コードなど）"]
    end

    subgraph MCP["MCP サーバ群"]
        M1["AWS Pricing MCP Server"]
    end

    I -->|Apply| A
    I -->|コスト確認| M1 
    M1 -->|コスト最適化| I

9. 実践：CloudFrontとS3で構築する静的サイトとアクセス可視化

本章では、Spec Kit と Gemini CLI を用いて、S3 と CloudFront による静的ウェブサイトを構築し、そのアクセス状況が CloudWatch で可視化されるまでを追います。

まずはSDDで静的ウェブサイトを構築し、その後、CloudWatch でアクセス状況を可視化できるダッシュボードの作成という、仕様を追加します。

ここでのゴールは、単にインフラを構築するだけでなく、CloudWatch コンソールでリクエスト数のグラフが動くのを確認するところまでを実践することです。

これにより、意図（Spec）が実際の運用（Monitoring）に繋がる流れまでを意識するためです。

flowchart LR
    subgraph Client["クライアント"]
        U[ユーザー/ブラウザ]
    end

    subgraph AWS["AWS インフラ（Terraform で構築）"]
        CF[CloudFront ディストリビューション]
        S3[S3 バケット（静的サイト）]
        CW[CloudWatch メトリクス]
    end

    U -->|HTTPS リクエスト| CF
    CF -->|オリジン要求| S3
    CF -->|アクセス状況を送信| CW

9.1. Gemini.mdの設定と、specify init - プロジェクトの作成

specify init <PROJECT_NAME> でプロジェクトを作成します。
作成と同時に、次のような階層でファイルが作成されます。

原則、生成されるファイルはすべて英語となっているため、次のプロンプトと Gemini.md を設定することを推奨します。

# Gemini.md

## 使用言語
日本語を利用してください。
英語の場合は日本語に訳してください。

# プロンプト
.specify配下のtemplatesの各ファイルを、日本語に直してください。

+---.gemini
|   \---commands
|           speckit.analyze.toml
|           speckit.checklist.toml
|           speckit.clarify.toml
|           speckit.constitution.toml
|           speckit.implement.toml
|           speckit.plan.toml
|           speckit.specify.toml
|           speckit.tasks.toml
|           speckit.taskstoissues.toml
|
+---.specify
|   +---scripts
|   |   \---bash
|   |           check-prerequisites.sh
|   |           common.sh
|   |           create-new-feature.sh
|   |           setup-plan.sh
|   |           update-agent-context.sh
|   |
|   \---templates
|           agent-file-template.md
|           checklist-template.md
|           plan-template.md
|           spec-template.md
|           tasks-template.md
(その他多数)

9.2. Constitution ― 「規約」を定義

まず、/speckit.constitution を実行します。
Gemini では「憲法」と訳されますが、個人的には訳し方が好みではなかったので、「規約」とするようにこの constitution も設定しました。
簡単な指示を出すと、<workspace-name>/.specify/memory/constitution.md が作成されます。

constitution は「このプロジェクトでは何を必須（/許容）にするか」を先に固めるためのもので、後続のSpec/ Plan/Tasksの品質を安定させる土台になります。

ここでは実際に作成した constitution.md から、特に重要な原則だけ抜粋します。
（読みやすさのため一部要約）

# spec-kit-entry-s3-static-site 規約

## Core Principles
1. セキュリティ: 最小権限（開発環境はアクセスログ取得不要）
2. 状態管理: S3などのリモートバックエンド（ロックは必須としない）
3. IaCのモジュール化: 機能単位で独立モジュール
4. 命名規則: 一貫した命名規則を必須化
5. 静的解析とテスト: `tfsec` / `tflint` + MCPチェック必須
7. ドキュメントの言語: 日本語で記述
9. コード内言語: 変数の `description` 等も日本語

9.3. Specify ― 「何を」作るかを定義

まず spec.md を作成し、「セキュアで高速な静的ウェブサイト」という目的を定義します。
成功基準としては、例えば次のような条件を明記します。

CloudFront のエンドポイントにアクセスすると、静的コンテンツが HTTPS で配信されること

spec.md は（特に非機能要件まで含めると）それなりの分量になるので、
ここでは「静的サイトを S3 + CloudFront でホスティングする」例として、実際に作成した spec.md から雰囲気が伝わる箇所だけ抜粋します。
（読みやすさのため一部要約）

# 機能仕様書: S3静的サイトホスティング

## ユーザーシナリオとテスト *(必須)*

### ユーザーストーリー1 - S3バケットのプロビジョニング (優先度: P1)
- 受け入れ: 静的サイトホスティングが有効なS3バケットが作成される

### ユーザーストーリー2 - CloudFrontによるコンテンツ配信 (優先度: P2)
- 受け入れ: CloudFront URLへHTTPSアクセスすると `index.html` が表示される

## 機能要件 (以下、FR)
- FR-003: S3バケットへの直接のパブリックアクセスはブロックされる
- FR-005: CloudFrontはオリジンアクセス制御（OAC）を使用してS3にアクセスする

## 成功基準 *(必須)*
- SC-001: CloudFront URL経由で `index.html` がHTTPSで5秒以内に表示される

9.4. Plan ― 「どう」作るかを計画

/speckit.plan 実行時には、技術スタック（S3, CloudFront, OAC）やセキュリティ・運用要件など、主に非機能要件とアーキテクチャ制約を与えます。

この段階では、まだ具体的な Terraform コードが存在しないため、AWS Pricing MCP Server を直接呼び出して厳密なコスト試算は行いません。

代わりに、トラフィック量の見込みやざっくりとした予算感などを Spec / Plan に書き込み、後続の Implement フェーズで生成されるコードに対してコスト評価する前提を整えます。

これにより生成される plan.md には、例えば次のような方針が盛り込まれます。

S3 バケットはプライベートとし、直接のパブリックアクセスは許可しない
CloudFront からのみアクセスできるよう、OAC（Origin Access Control）を利用する

Plan は「どう作るか」をレビュー可能な形に落とし込むのが目的なので、チェックリストや構成の方針が（ある程度の粒度で）明文化されます。こちらも plan.md から抜粋します。
（specs/<feature>/ のようなディレクトリの配置方針もここに書かれます）。

# 実装計画書: S3静的サイトホスティング

## 規約チェック
- [x] 1. セキュリティ: 計画は最小権限の原則に準拠しているか？(S3パブリックアクセスを禁止し、OACを利用)
- [x] 2. 状態管理: 対象環境に対して、ロック付きのリモート状態管理が構成されているか？(Terraform Cloud/S3バックエンドを前提)
- [x] 3. IaCのモジュール化: 設計は再利用可能なモジュールを促進しているか？(s3, cloudfrontでモジュール分割を計画)

## プロジェクト構造
specs/001-s3-cloudfront-site/
├── plan.md
├── spec.md
└── checklists/requirements.md

IaCプロジェクトとして、以下のTerraform標準レイアウトを採用します。
構造の決定: 上記のTerraformモジュール構成を採用し、環境（`environments`）と再利用可能なコンポーネント（`modules`）を明確に分離します。これにより、憲法の「モジュール化」の原則を遵守し、将来的な環境追加（例: 本番環境）にも容易に対応できます。


```text
.
├── environments/
│   └── dev/              # 開発環境用のルートモジュール
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       └── backend.tf    # リモートバックエンド設定
│
└── modules/
    ├── s3-static-site/   # S3バケットと関連リソースを管理するモジュール
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    │
    └── cloudfront-cdn/     # CloudFrontディストリビューションを管理するモジュール
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

9.5. Tasks ― 実装タスクへ分解

Plan に基づき、Gemini が具体的なタスクリストを生成します。例としては次のようなタスクが含まれます。

S3 バケットの作成と基本ポリシーの設定
CloudFront ディストリビューションの作成（オリジンに S3 を指定）
OAI（Origin Access Identity）の作成と、S3 バケットポリシーへの組み込み

依存関係を考慮しながらタスクが並べられることで、Terraform 実装の順序も明確になります。

以下が、実際に作成された tasks.md からの抜粋です。
（フェーズ分割、依存関係、独立したテスト観点などがセットで出てくるのが特徴です。必要に応じて要約しています）

# タスク: S3静的サイトホスティング

> `[P]` が付いたタスクは、並列に実行できます。

## フェーズ1: セットアップ
- [x] T001 [P] `environments/dev` ディレクトリを作成する
- [x] T002 [P] `modules/s3-static-site` ディレクトリを作成する
- [x] T003 [P] `modules/cloudfront-cdn` ディレクトリを作成する

## フェーズ3: ユーザーストーリー1 (P1)
- [x] T010 [US1] S3バケット + Website設定 + パブリックアクセスブロックを定義する

## フェーズ4: ユーザーストーリー2 (P2)
- [x] T015 [US2] OAC と CloudFront ディストリビューションを定義する

## フェーズ5: ユーザーストーリー3 - TerraformによるIaC化 (優先度: P3)

目標: インフラ定義の品質と再現性を保証するためのプロセスを確立します。
独立したテスト: `terraform plan` が差分なく完了すること、静的解析ツールが警告を出さないことを確認できます。

9.6. Implement ― 実装と動作確認

Gemini が各タスクを Terraform コードとして実装し、デプロイを行います。
デプロイ後、CloudFront のエンドポイントに数回アクセスし、静的コンテンツが HTTPS で配信されることを確認します。

この確認作業をもって、最初の仕様で定義した成功基準が満たされたことを検証します。

さらに、生成された Terraform コードやデプロイされたリソース構成を入力として、AWS Pricing MCP Server を呼び出し、ランニングコストの概算を取得します。

これにより、

想定していた予算内に収まりそうか
ボトルネックになりそうなサービスはどこか

といった観点を踏まえて、Plan / Tasks / Implement を再度見直すフィードバックループを回すことができます。

9.7. 要件・リソースの追加

さて、前項で静的サイトの作成・公開は無事に完了しました。
ここからは、サイトのアクセス状況を CloudWatch で可視化する要件を追加してみます。

追加する仕様（成功基準の例）は、次のようになります。

アクセス後、CloudWatch の CloudFront メトリクスでリクエスト数がカウントされること

これに対応して、Plan / Tasks には例えば次のタスクを追加します。

CloudWatch で確認するためのメトリクスやログ設定の有効化

Implement フェーズでは、これらのタスクに基づいて Terraform コードを拡張し、再度デプロイを行います。
デプロイ後、CloudFront のエンドポイントにアクセスし、CloudWatch の CloudFront メトリクス画面で「Requests」グラフにデータが反映されることを確認します。
この確認作業をもって、追加した仕様が満たされたことを検証します。

10. SDD が特に有効な 3 つのシナリオ

Spec Kit の背景にある Spec-Driven Development は、特に次の 3 パターンで役立つとGitHubの公式ブログで提示しています。

Greenfield（ゼロからの新規開発）
- これから新しくシステムを作る場面では、「コードから考える」のではなく「意図と制約から考える」ことが重要です。
- 仕様（Spec）をきちんと書き、Plan / Tasks / Implement を順に進めることで、アーキテクチャの迷子になりにくくなります。
Feature work（既存システムへの機能追加）
- 既存のインフラやシステムに対して機能追加を行う場合は、影響範囲の洗い出しや既存ポリシー・命名規約との整合といった点を、Spec / Plan フェーズで明文化しておくことで、レビューやロールバックがしやすくなります。
- 仕様駆動開発が最も威力を発揮する分野だと GitHub 側が推しています。
Legacy modernization（レガシーの近代化）
- 手作業やスクリプトで運用されているレガシーシステムをモダンなアーキテクチャや IaC に移行する際、暗黙知になっている仕様や制約を Spec / Plan として言語化しながら段階的に置き換えていくのに、SDD は相性が良いとされています。

11. 利用してみた感想

実際に Spec Kit を Kiro と比較しながら使ってみて、次のような違いを感じました。

レビューの厳格さ

Spec Kit は、仕様・計画・タスク・実装の各段階でこまめに人間にレビューを求めてきます。AI がまとめた内容を読み込みながら一歩ずつ進めるスタイルのため、手戻りは少ない一方で、進行のテンポはややゆっくりになります。

Kiro の進め方

Kiro は、AI 側がある程度まとめた状態まで一気に進めてから人間にレビューを返してくる印象で、少ないやり取りでテンポよく進めたい場合に向いています。

一方で、今回の検証では次のような点も気になりました。

Constitution（規約）を完全には守らず、たまにルールから外れた提案をしてしまうことがある
Kiro と比べると、SDD の各フェーズ（Requirements / Design / Implementation）の境界が曖昧になりやすい

これらは、Spec Kit と組み合わせる AI エージェントの実装やプロンプト設計にも依存する部分が大きいと感じています。

総じて、

ゼロから新しいシステムをじっくり設計したい（Greenfield）
チームで仕様・タスクまでをきちんとレビューしながら進めたい

といったケースでは、Spec Kit の方がフィットしやすいと感じました。

一方で、

まずは SDD を軽めに体験してみたい
AWS プロダクト中心の構成で、Kiro のテンプレートやガイドに乗って進めたい

といった場合は、Kiro を選ぶ方が導入のハードルは低いと思います。

12. 実行可能な仕様の実現例

本記事で扱った S3 静的サイトの例では、次のような形で「実行可能な仕様」が実現されます。

spec.md
- ユースケース・制約・非機能要件をまとめたドキュメント
plan.md
- Spec で定義した要件や、非機能要件・アーキテクチャ制約を整理した方針
- 使用する AWS サービスや Terraform モジュール構成の決定
tasks.md
- 実装・テスト・監査タスクに分解された ToDo リスト
Terraform コード
- これらの成果物から導かれた、具体的な IaC 実装
- Implement 後に AWS Pricing MCP Server を用いてコスト評価する対象

重要なのは、

コード単体ではなく、「仕様 → 計画 → タスク → コード」の流れ全体が一貫していること

です。Spec Kit は、この流れを AI を介して半自動化しつつも、人間がレビューしやすい単位に分割してくれる点に価値があります。

13. 今後の発展と課題

最後に、今後の展望と課題を簡単に整理します。

13.1. 期待できる発展

IDE / エディタとの連携強化
- 現在はAI内でコマンドを叩くのに対し、VS Code などで /speckit.* コマンドを直接叩けるようになれば、より自然なワークフローになるはずです。
複数実装案の比較
- 同じ Spec / Plan から複数の実装パターン（例：S3 単体 / S3 + CloudFront / S3 + CloudFront + WAF）を生成し、コスト・運用性・セキュリティなどで比較する、といった使い方も考えられます。
大規模プロジェクトへの適用
- マイクロサービス群や複雑なネットワーク構成など、より大きなスコープでの Spec-Driven Development への展開も今後のテーマになりえます。

13.2. 現時点での課題・注意点

MCP エコシステムの成熟度
- MCP や各 MCP Server はまだ進化の真っ最中であり、仕様変更やバージョンアップの影響を受けやすい段階です。
セキュリティと権限管理
- MCP Server の実装やデプロイ方法によっては、資格情報の取り扱いやアクセス制御に注意が必要です。
「人間のレビュー」をどう組み込むか
- 最終的な責任は人間にあります。Spec / Plan / Tasks / コードの各段階で、どのようなレビューを行うかをチームとして設計することが重要です。

14. 最後に

本記事で扱った内容から、大事なポイントを一言で表すと、

「コードが起点」から「仕様・意図が起点」へと軸足を移す

ということだと考えています。

コードはあくまで「仕様と意図を具現化した結果」であり、AI や MCP Server はその橋渡しを支援する存在として捉えると、Spec-Driven Development のコンセプトが理解しやすくなるはずです。

また、今回 Spec Kit を利用してみて、SDD を支援するツールそのものだけでなく、組み合わせる AI や MCP Server によって得意な領域やワークフローが変わることも実感しました。今後も、インフラ構築や運用の現場での適用例を増やしながら、より良い組み合わせ方を探っていきたいと思います。

仕様駆動開発という考え方自体は、特にインフラ構築において長期的な保守性と品質を支える重要なアプローチだと感じています。

本記事が、読者の皆さまが自分たちのプロジェクトで SDD や Spec Kit、そして AI / MCP を試してみるきっかけになれば幸いです。

執筆時点では、Windows上のGitBashでGemini CLIをnpmインストールできるのですが、文字化けを起こしたり色々とトラブルがあります。
これはWindows環境では、Gemini CLIが内部的にPowerShellを利用していることに起因するためです。Windows環境ではデフォルトのターミナルをPowerShellにすることで、それらのトラブルは解消します。 ↩︎

AWSで読み替えるGoogle Cloud入門

2025-12-12T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第12日目の記事です。

Information

記事の内容に不正確な記述が含まれていたため 2025/12/15 に追記・修正を行いました

はじめに

ビジネスソリューション事業部の塚野です。現在、私がアサインされている案件ではパブリッククラウドとして Google Cloud を利用しています。
もともとは AWS を業務や個人開発で使っており、インフラ構成もサービス選定も「AWS の考え方」を土台にしてきました。しかし案件アサインに際し Google Cloud を本格的に学びはじめ、その設計思想やネットワークモデルが AWS と大きく異なることに気づきました。
キャッチアップの際には、AWS の常識をそのまま Google Cloud に当てはめて混乱した経験があり、両者を横並びで比較した体系的な資料が欲しいと強く感じました。

そこで本記事では、AWS 上に用意したシンプルなデモアプリケーションを題材にしながら、
「同じ構成を Google Cloud で実現するとどうなるのか？」
という観点で、Google Cloud のプロダクトや設計思想を AWS と比較しながら紹介していければと思います。
また、本記事では AWS ユーザーを対象とし、AWS ユーザーが Google Cloud を理解する際の指針になることを目指すため、AWS 各サービスの説明は行いません。

デモアプリの構成

本記事で考えるデモアプリは、簡単な ToDo アプリであるとします。
典型的な三層 Web アプリケーションに、非構造化データを保存するためのオブジェクトストレージを加えた構成です。

フロントエンドには Next / Nuxt の SSR（Server-Side Rendering）を採用し、
フロントエンドとバックエンド API を同一サーバー上でホストできる構成とします。

フロントエンド： Next / Nuxt などで構築された Web UI（SSR によりサーバー側でレンダリング）
バックエンド API：タスクの CRUD を提供する REST API
永続化層：RDBMS（ユーザー・タスク・プロジェクトなどのデータ）
ファイルストレージ：ユーザーがアップロードするアイコン画像や添付ファイルなどを保存

本記事では AWS と Google Cloud の比較のためごく簡単なアプリケーションを題材とします。そのため高度な機械学習（Google Cloud の強みはここもあったりしますが）、メッセージング、DNS、イベント駆動アーキテクチャなどは含めず、

ネットワーキング
コンピューティング
データベース
オブジェクトストレージ

といったクラウドの基本要素にフォーカスしています。
また、実運用で考えるべきマルチAZ（マルチゾーン）やマルチリージョンな冗長化構成についても考慮しません。

AWS における構成

まずは AWS でのデモアプリの構成です。

アプリを構築するリージョンは東京リージョン（ap-northeast-1）とします。
リージョン内にVPCを1つ作成し、VPC 内には AZ を1つ含めます。
その AZ 内にパブリックサブネットとプライベートサブネットを配置します。
さらに、Next / Nuxt の SSR やバックエンド API をホストするためのコンピューティングサービスとして EC2 をプライベートサブネット内に配置し、Auto Scaling グループを構成します。

パブリックサブネットには Application Load Balancer（ALB）を配置し、
インターネットからのトラフィックを Auto Scaling グループへルーティングします。
永続化層には、EC2 と同じプライベートサブネット内に
Amazon RDS（MySQL / PostgreSQL）を配置します。

ユーザーアップロード用のファイルは Amazon S3 バケットに保存し、
プライベートサブネット内の EC2 から S3 にアクセスします。

なお、実際には次のようなネットワーク構成が必要です

EC2 の外向き（Outbound）通信には NAT Gateway が必要
EC2 から S3 を安全に利用するには VPC エンドポイント（Gateway Endpoint for S3）が必要

ですが今回は構成をシンプルに保つため図からは省略しています。
また、NAT Gateway は個人利用ではコストがかかるため、EC2 をパブリックサブネットに置く構成も現実的です。しかし、AWS と Google Cloud の比較を明確にするため、本記事では EC2 をプライベートに置く構成としています。

Google Cloud における構成

続いて、同じデモアプリケーションを Google Cloud 上で構成した場合を見ていきます。

見た目は AWS よりもスッキリしています。
VPC やロードバランサなど、AWS でもよく見かけるリソース名が Google Cloud にも登場しますが、その配置のされ方を見ると「おや？」と感じる部分があるかもしれません。

この違いこそが、AWS と Google Cloud の思想的な差分であり、
以降の章ではこれらのリソースの役割や設計上の特徴を詳しく比較していきます。

ネットワーク編

まずはネットワークリソースから見ていきます。
ここで扱うのは以下のリソースです。

VPC
サブネットとゾーン
ロードバランサ

VPC

まず、AWS と Google Cloud で大きく異なるのが VPC のスコープです。
AWS では VPC はリージョンに紐づくリージョナルリソースです。
AZ をまたいでの構成は可能ですが、リージョンをまたいで1つの VPC の構成はできません。
一方、Google Cloud では VPC はグローバルリソースです。
そのため、1つの VPC の中に複数リージョンを含めることができ、AWS と比べてマルチリージョンなネットワークを容易に構成できます。

AWS と比較したときの Google Cloud の大きな特徴として、グローバルリソースを前提にした設計思想があります。
Google Cloud はまずグローバルな VPC を作成し、その中でリージョンやAWSのAZに当たるゾーンといったパーティションを切っていくというトップダウンの構成をとります。
一方 AWS は VPC をリージョンごとに作成し、必要があればリージョン間を接続してマルチリージョン化します。つまりリージョンを基本単位としたボトムアップ型のアプローチです。
この設計思想の違いこそが、AWS ユーザーが Google Cloud に触れたときに最初に戸惑うポイントといえます。

サブネットとゾーン

次に、サブネットとゾーンの扱いについて触れます。
Google Cloud では、作成した VPC に対してサブネットを追加しますが、AWS と異なりサブネットはリージョン単位のリソースです。
AWS のようにサブネット＝AZ 単位ではありません。
さらに、Google Cloud のサブネットにはパブリック／プライベートの区別がありません。
サブネットに割り当てるルート（デフォルトルートをインターネットゲートウェイに向けるかどうか）と、ファイアウォールルールによってパブリック／プライベートの性質が決まります。
また、「ゾーン」は、Google Cloud における AWS の AZ に相当する最小単位のデータセンター群です。
AWS 同様リージョンを分ける単位として機能しますが、サブネットがどこに紐づくかが異なります。
AWSの場合、サブネットは AZ 単位で作られますが、Google Cloudの場合、逆にサブネット内にゾーンが存在します。

以上Google Cloud の構成を整理すると、次のようになります。

サブネットはリージョン全体に広がるため、リージョン内のすべてのゾーンから利用可能
アプリケーションをデプロイするゾーンはサブネット内で選択する
パブリック／プライベートの区別はルートとファイアウォールで制御する

このため、AWS の AZ ごとにサブネットを作り冗長化するモデルに比べ、
Google Cloud はサブネット構成がシンプルで、ゾーン冗長を実現しやすいのが特徴です。

ロードバランサ

ロードバランサ（LB）の設計思想も AWS と Google Cloud で異なります。
ここではL7のLBのみ言及します。AWSにおけるL7 LB はALBですが、これはリージョンリソースで各リージョンごとにエンドポイントが異なります。
したがって、グローバルに公開したい場合は Route 53 や CloudFront を併用する必要があります。
一方、Google CloudにおけるL7 LBは 外部 HTTP(S) ロードバランサです。これにもいろいろ種類があるのですが^[1]、グローバルに公開したい場合は、グローバルリソースとして提供される LB を選択可能です。
AWS でグローバル LB を構成しようとすると複数サービスを組み合わせる必要がありますが、Google Cloud では LB 単体でグローバル公開ができる点が大きな違いです。

なお、インターネット接続の扱いも AWS と Google Cloud では少し異なります。
AWS では VPC を外部に公開するために Internet Gateway（IGW）を明示的に作成し、パブリックサブネットのルートテーブルに紐づける必要があります。一方、Google Cloud では IGW に相当するリソースをユーザーが直接意識することなく、外部 HTTP(S) ロードバランサなどの外部向けリソースを作成すると、自動的に Google のエッジネットワークがインターネットとの入口として機能します。

そのため、Google Cloud では「どこをインターネットに公開するか」を細かいネットワーク構成として指定することが少なく、AWS に比べて抽象度が高いという特徴があります。

ネットワークまとめ

ここまでを踏まえると、デモアプリのネットワーク構成は以下のようになります。

グローバルリソースとして VPC を1つ作成し、その中に東京リージョン（asia-northeast1）を含める。
東京リージョン内にリージョンサブネットを作成する。
リージョンサブネット内の特定のゾーン内（今回の場合はゾーンA）にコンピューティングやDBを配置する
L7 LBはグローバルリソースとして配置する

Google Cloudのネットワーク構成図

リソース	AWS のスコープ	Google Cloud のスコープ
VPC	リージョン単位	グローバルリソース
サブネット	AZ単位	リージョン単位
ゾーン（AZ 相当）	1つのリージョンに複数の AZ。サブネットと 1 対 1	サブネットの内部に存在。サブネットはゾーンをまたぐ
ロードバランサ（LB）	ALB/NLB はリージョン単位	外部 HTTP(S) LB はグローバルリソースとして配置可能
インターネット接続	IGW を VPC にアタッチし、ルートテーブルで制御	Google の外部エッジネットワーク（LB 経由）を入口として利用

コンピューティング編

続けて、コンピューティングサービスについて見ていきます。
アプリケーションを実際に実行するサーバーをどのように冗長化し、スケールさせるかは AWS と Google Cloud の大きな比較ポイントの一つです。

AWS では、EC2 インスタンスでフロント/バックエンドサーバーをホストし、EC2インスタンスを Auto Scaling グループに配置しています。これにより、一定条件下でインスタンス数を自動的に増減させることが可能です。

Google Cloud において EC2 にあたるコンピューティングサービスとして Google Compute Engine（GCE） があります。
GCE でも EC2 と同様に仮想マシンを利用してアプリケーションをホストしますが、スケーリングや冗長化の仕組みが少し異なります。Google Cloud では、GCE インスタンスを Managed Instance Group（MIG） にまとめることで、スケールイン/アウトや自己修復などを自動化できます。
ここで AWS と比べて特徴的なのは、Google Cloud では MIG をリージョン単位で作成できるという点です。
AWS の Auto Scaling グループが複数 AZ にまたがることで高可用性を実現するのと似ていますが、MIG は「リージョン MIG」として構成することで、リージョン内の複数ゾーンにコンピューティングリソースが自動的に分散配置されます。
これは前章で触れた「サブネットがリージョン単位」である Google Cloud のネットワーク設計にも関わっています。

AZをまたがるように配置可能なAWSのAuto Scalingグループ（左）とリージョン単位で作成可能なGoogle Cloud リージョナルMIG（右）

今回のデモアプリでは構成をシンプルに保つため、GCE インスタンスは asia-northeast1 の中の 1 つのゾーン（例：asia-northeast1-a）に配置しています。しかし実運用を想定する場合は、リージョン MIG を使って複数ゾーンにまたがって配置するのが定石です。複数ゾーンにまたがることで単一ゾーン障害に対する耐性を持たせることができます。

AWS の Auto Scaling グループと Google Cloud の MIGは、どちらもインスタンス数のスケーリングに加え、起動定義のバージョン管理、ローリングアップデートといった機能を備えています。

データベース、ストレージ編

お次はデモアプリで利用するデータベースとストレージについて見ていきます。

デモアプリでは、ユーザーやタスクを保存するための RDB と、ユーザーがアップロードする画像ファイルなどを保存するオブジェクトストレージを利用しています。
AWS では、RDB には Amazon RDS を、ストレージには Amazon S3 を利用しています。EC2 で動くアプリケーションは、プライベートサブネットの内部から RDS に接続し、ユーザーがアップロードしたファイルを S3 に保存します。

一方、Google Cloud で同じアプリケーションを構築する場合、対応するプロダクトは Cloud SQL と Cloud Storage になります。
Cloud SQL は MySQL や PostgreSQL をマネージドで提供するサービスで^[2]、Cloud Storage は S3 と同様にオブジェクトストレージとして利用できます。
ここまでは AWS とさほど大きな違いはありませんが、ネットワーク構成に踏み込むと、Google Cloud らしい特徴が見えてきます。

まずは DB サービスの比較です。
RDS が VPC 内のサブネットにインスタンスを持つのに対し、Cloud SQL のインスタンスはユーザー管理の VPC 内には存在しません。Cloud SQL のインスタンスは Google の管理ネットワーク内にある VPC に存在します。
Cloud SQL への接続は Public IP を付与しパブリックネットワーク経由でアクセスする方法と、プライベートネットワーク経由でGoogle Cloud内部から接続する方法があります。
本記事でのデモアプリでは、プライベートなVPC内に配置した GCE からアクセスする構成を想定するため、プライベートネットワークアクセスで Cloud SQL に接続する方法をとることとします。
プライベートなアクセス方法は本アプリでは Private Service Connect（PSC）という接続方法をとることとし^[3]、VPC 内の PSC エンドポイント経由で Cloud SQL インスタンスへ接続をおこないます。

Cloud SQL では RDS のように冗長化構成をとる場合でも、レプリカをどのサブネットに置くかといった細かいネットワーク設計を利用者が意識する必要はなく、リージョンの指定のみで冗長化・レプリカ配置は Google がよしなにやってくれます。
このようにCloud SQL は内部構造がユーザーに隠蔽されている点や、冗長化方式の抽象化という観点では、AWS の Amazon Aurora に近い部分もあります。ただし、個人開発や小規模な Web アプリケーションではコスト面や構成のシンプルさから RDS が選択されるケースも多く、Amazon Aurora は多機能であるため、本記事では純粋な RDB サービスの比較対象として RDS を扱っています。

Amazon RDS はサブネットに配置され（左）、Cloud SQL インスタンスの実体はユーザー管理のサブネットにはなく Google によって管理される（右）

オブジェクトストレージについても似た特徴があります。
AWS の場合、EC2 がプライベートサブネットにある場合は NAT Gateway または S3 用の VPC エンドポイント（Gateway Endpoint）を明示的に用意して、外向きトラフィックをどう流すかを設計する必要があります。
Google Cloud の Cloud Storage では、GCE などのインスタンスからアクセスする際にはサブネット単位で「限定公開の Google アクセス（Private Google Access）」を有効にすることで、外部 IP を持たないプライベートサブネットのインスタンスからでも Google Cloud の内部ネットワーク経由で Cloud Storage の API にアクセスできます。この場合、インターネットに公開されたパブリック IP を経由せずに通信が完結します。

こうした差異から見えてくるのは、AWS と Google Cloud のネットワーク設計に対する考え方の違いです。
AWS では、利用者がネットワークの経路やセキュリティを比較的細かく指定することが前提となっており、VPC・サブネット・NAT・VPC エンドポイントといった多くのリソースを組み合わせる必要があります。
対して Google Cloud は、Google 自身が世界規模で運用してきたネットワークを前提とし、ユーザーが意識しなくても安全で効率的な通信が成立するように抽象化されています。結果として、アプリケーション開発者は「どのネットワーク経路を通すか」よりも「どのサービスを使うか」に集中しやすくなります。

まとめ

今回、同じデモアプリを題材に AWS と Google Cloud のアーキテクチャを比較してみました。

Google Cloud は、VPC やロードバランサがグローバルであるように、グローバルなネットワークや抽象化を前提としたクラウドです。
Cloud SQL のように内部構造をユーザーに見せず、シンプルな設定だけで安全に利用できるサービスが多いため、構成は AWS よりもスッキリまとまります。ただし、抽象化が強いぶん「どこからどこまでが自分の設計領域か」が直感的に理解しづらい場面もあります。

一方 AWS は、VPC・サブネット・AZ といったネットワーク境界が明確で、ボトムアップで積み上げる構成を取りやすいのが特徴です。
インターネット接続やプライベートアクセスをユーザーが明示的に選択できるため、要件に応じて細かくコントロールできる点は大きな利点です。筆者としても、この「スコープが見えやすい構造」は理解しやすく、設計上の安心感があります。

どちらが優れているという話ではなく、Google Cloud はシンプルで抽象化されたモデル、AWS は構造が明確でコントロールしやすいモデルという違いがあります。
どちらのクラウドもそれぞれの強みがあり、アプリケーションの規模や要件に応じて最適解は変わります。本記事が、AWS を使っている方が Google Cloud を理解するきっかけになれば幸いです。

これがさらにグローバルかリージョナルリソースとして配置するか、パブリックインターネットからのトラフィックを負荷分散するか Google Cloud 内部のトラフィックを分散するかで種類が分かれます。L3/4 の LB についても同様に複数種類あってややこしいです。
何を言っているんだぜ？という感じですが、ロードバランサについてはこちらの記事で詳しく解説がなされています（AWS側の目線から理解する、Google Cloud ロードバランサの世界）。どうしてこうなったのか。 ↩︎
RDBMS のマネージドサービスとして他に Cloud Spanner がありますが、個人開発や小規模開発ではオーバーキル気味なので今回はCloud SQLを選択します。また、Amazon Aurora のように Google Cloud にも独自データベースである AlloyDB があります。こちらは PostgreSQL のみ互換性があります。 ↩︎
Cloud SQLへのプライベートな接続方法には、Cloud SQL インスタンスに Private IP を割り当て、VPC ピアリングで接続をおこなう Private Service Access(PSA) と、ユーザー管理の VPC 内にエンドポイントを作成し、エンドポイント経由で Cloud SQL インスタンスへ Google Cloud の内部ネットワークを通じて接続する Private Service Connect（PSC）が選択できます（ややこしい名前ですね…）。
接続方法はユースケースに合わせて PSA・PSC どちらも選択可能ですが、本記事では「VPC 内からマネージドサービスへプライベートに接続する」という構造をシンプルに示すことができる PSC によるプライベート接続を例に挙げました。 ↩︎

記事の大半をAIが書く時代：Amazon Q DeveloperとVSCodeで挑む協働執筆

2025-12-11T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第11日目の記事です！

はじめに

この記事は、Amazon Q Developerと人間の協働による実験的な取り組みです。
最初からネタばらしですが、「この記事、ほとんどAIが書いています。」
AIを“使う側”から“協働する側”へ。Amazon Q Developerで開発と執筆の常識が変わると思います。

何をするか：

VSCodeでAmazon Q Developerをセットアップ
実際のコード作成・改善を体験
AIとの対話で技術記事を共同執筆

特徴的な点：

記事の大部分をAmazon Q Developerが執筆
コードサンプルやテストもAIが生成
人間は企画・構成・画像挿入を担当

読者が得られるもの：

Amazon Q Developerの実用的な使い方
AI協働による効率的な開発手法
技術文書作成でのAI活用の可能性

それでは、Amazon Q Developerと人間の協働の旅を始めましょう。

1. 開発環境

今回の協働作業では、Amazon Q Developer を VSCode から使用します。
VSCode で Amazon Q Developer を使うには以下の環境が必要です。

VSCode 本体：v1.85.0 以上
サインイン用のアカウント
- 個人利用：AWS Builder ID（AWSアカウント不要）
- 会社利用：IAM Identity Center（AWSアカウント必要）

※ 会社のAWS環境で使うなら、権限やライセンスは管理者に確認しておくと安心です。

2. VSCode への拡張機能インストール

VSCode を起動します
左パネルの Extensions（拡張機能） を開きます
検索欄に Amazon Q と入力し、以下の拡張機能を選択してインストールします
以下のようなアイコンがVSCodeに表示されていれば、インストールは完了です
※ただし、まだ Amazon Q Developer へのログインが行われていないため、アイコンが赤くなっています

3. サインイン（認証）

VSCode 下部の Amazon Q アイコン をクリックし、「Sign in to get started」を選択します
「サインインオプション」から用途に合わせて選択します
- 個人（Personal account）の場合 → 事前に「Builder ID」を取得しておきます
- 会社（Company account）の場合 → 事前に「IAM Identity Center」で登録しておきます
  （今回は「会社の場合」で進めます）
IAM Identity Centerのアカウント情報を設定します
- StartURL：AWS access portal URLを設定します
- Region ：サービスのリージョンを設定します
続けて外部のAWSサイトに誘導されるので、ブラウザでログインします
以下の画面が表示されたら、アクセスを許可します
VSCodeに戻ります。
下の画面のように「Amazon Q」と表示されていればサインイン完了です

4. 基本的な使い方

チャットで質問

Amazon Qパネルで質問や指示を入力します。
試しに「ここで何ができますか？」と質問してみます。
Amazon Q から「できることリスト」の回答が得られました。

コード補完

ソースコードを作成していく場合、プログラムを書かずにコメントに意図を書いておくと、Amazon Qがインラインでコードを提案してくれます。

例1: 日本語コメントからクラス生成

# ユーザー情報を管理するクラスを作成
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
    
    def get_display_name(self):
        return f"{self.name} ({self.email})"

例2: 関数の処理内容をコメントで指定

# CSVファイルからユーザーデータを読み込む関数
import csv

def load_users_from_csv(filename):
    users = []
    with open(filename, 'r', encoding='utf-8') as file:
        reader = csv.DictReader(file)
        for row in reader:
            user = User(row['name'], row['email'])
            users.append(user)
    return users

使い方のコツ:

コメントは具体的に書く（「データを処理」より「CSVファイルから読み込み」）
日本語でも英語でも対応
Alt+C（Option+C）で手動補完も可能

5. コード作成・修正を試行

では実際に、Amazon Q Developerでのコード作成・修正を体験してみましょう。

サンプルファイル（example.py）について

まず、今回使用するサンプルファイル example.py について説明します。このファイルは、ユーザー情報を管理するシンプルなPythonプログラムです。

example.py の機能は以下です。

ユーザー情報（名前、メールアドレス）を管理するUserクラス
CSVファイルからユーザーデータを読み込む機能
メールアドレスでユーザーを検索する機能
ユーザーリストをJSON形式で保存する機能

ソースコードのひな型としてコメント部分だけを記述します。

# ユーザー情報を管理するクラスを作成
# CSVファイルからユーザーデータを読み込む関数
# リストの中から特定の条件に合うユーザーを検索する関数
# ユーザーリストをJSON形式で保存する関数

すると Amazon Q が以下のようなソースコードを提案してきます。

example.py のソースコード:

# ユーザー情報を管理するクラスを作成
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
    
    def get_display_name(self):
        return f"{self.name} ({self.email})"

# CSVファイルからユーザーデータを読み込む関数
import csv

def load_users_from_csv(filename):
    users = []
    with open(filename, 'r', encoding='utf-8') as file:
        reader = csv.DictReader(file)
        for row in reader:
            user = User(row['name'], row['email'])
            users.append(user)
    return users

# リストの中から特定の条件に合うユーザーを検索する関数
def find_user_by_email(users, email):
    for user in users:
        if user.email == email:
            return user
    return None

# ユーザーリストをJSON形式で保存する関数
import json

def save_users_to_json(users, filename):
    user_data = []
    for user in users:
        user_data.append({
            'name': user.name,
            'email': user.email
        })
    
    with open(filename, 'w', encoding='utf-8') as file:
        json.dump(user_data, file, ensure_ascii=False, indent=2)
        print(f"Saved {len(users)} users to {filename}")

このコードは構文的には正しく動作しますが

エラーハンドリングやテストコードがない
実際に実行するメイン処理がない

など、改善の余地があります。
これらの問題をAmazon Q Developerを使って解決していきます。

5.1 既存コードの理解

まず、example.pyファイルを開いて、Amazon Qにコードの内容を質問し、Amazon Q がコードを正しく理解しているかを確認します。

Amazon Qへ以下のように指示を出します。

@example.py このファイルは何をするコードですか？

Amazon Qが以下のような回答をしてくれます。

example.pyは、ユーザー情報を管理するためのシンプルなPythonプログラムです。

主な機能
1. Userクラス - ユーザー情報（名前とメールアドレス）を管理
- get_display_name(): 名前とメールアドレスを組み合わせた表示名を返す
2. CSVファイル読み込み - load_users_from_csv()
- CSVファイルからユーザーデータを読み込んでUserオブジェクトのリストを作成
3. ユーザー検索 - find_user_by_email()
- メールアドレスを指定して特定のユーザーを検索
4.JSON形式での保存 - save_users_to_json()
- ユーザーリストをJSON形式でファイルに保存

使用例
このプログラムは、CSVファイルからユーザーデータを読み込み、必要に応じてユーザーを検索し、最終的にJSON形式で保存するといったユーザーデータの変換・管理処理に使用できます。
ただし、現在のコードにはエラーハンドリングやメイン処理がないため、実際に動作させるには追加の実装が必要です。

5.2 コードの改善提案

既存のコードに対して改善提案を求めてみましょう。

Amazon Qへ以下のように指示を出します。

@example.py このコードを改善する方法はありますか？

Amazon Qから以下のような提案が得られます。

はい、example.pyには多くの改善点があります。以下のような改善方法をお勧めします：

1. エラーハンドリングの追加
現在の問題： ファイルが存在しない場合やCSVの形式が不正な場合にエラーで停止
改善案： try-except文でエラーを適切に処理

2. 型ヒントの追加
現在の問題： 引数や戻り値の型が不明確
改善案： from typing import List, Optional を使用して型を明示

3. docstringの追加
現在の問題： 関数の説明がコメントのみ
改善案： 各関数に適切なdocstringを追加

4. importの整理
現在の問題： import文が関数の直前に散らばっている
改善案： ファイル冒頭にまとめて配置

5. データ検証の追加
現在の問題： CSVデータの妥当性チェックなし
改善案： 必須フィールドの存在確認やメールアドレス形式の検証

6. 設定の外部化
現在の問題： エンコーディングなどがハードコード
改善案： 定数として定義

7. ログ機能の追加
現在の問題： print文のみでログ管理が不十分
改善案： loggingモジュールの使用

8. テスト可能な設計
現在の問題： メイン処理がなく、テストしにくい
改善案： if __name__ == "__main__": ブロックの追加

9. パフォーマンスの改善
現在の問題： 大量データ処理時の効率性
改善案： リスト内包表記の使用、メモリ効率の向上

これらの改善により、より堅牢で保守性の高いコードになります。特にエラーハンドリングと型ヒントの追加は優先度が高い改善点です。

5.3 実際にコードを修正

エラーハンドリングの追加

CSVファイル読み込み関数にエラーハンドリングを追加してみます。

修正前のコード（example.py の一部）は以下です。

def load_users_from_csv(filename):
    users = []
    with open(filename, 'r', encoding='utf-8') as file:
        reader = csv.DictReader(file)
        for row in reader:
            user = User(row['name'], row['email'])
            users.append(user)
    return users

Amazon Qへ以下のように指示を出します。

load_users_from_csv関数にファイルが存在しない場合のエラーハンドリングを追加してください

コードが以下のように修正されました。

def load_users_from_csv(filename):
    users = []
    try:
        with open(filename, 'r', encoding='utf-8') as file:
            reader = csv.DictReader(file)
            for row in reader:
                user = User(row['name'], row['email'])
                users.append(user)
    except FileNotFoundError:
        print(f"エラー: ファイル '{filename}' が見つかりません")
        return []
    except Exception as e:
        print(f"エラー: ファイル読み込み中に問題が発生しました: {e}")
        return []
    return users

Amazon Q が直接ソースコードを修正し、私（人間）はソースコードに一切触れていません。

新機能の追加

ユーザーの年齢情報を管理する機能を追加してみます。

Amazon Qへ以下のように指示を出します。

Userクラスに年齢（age）フィールドを追加し、年齢で検索する関数も作成してください

以下のようにコードが追加されました。

# ユーザー情報を管理するクラスを作成
class User:
    def __init__(self, name, email, age=None):
        self.name = name
        self.email = email
        self.age = age
    
    def get_display_name(self):
        age_info = f" (年齢: {self.age})" if self.age else ""
        return f"{self.name} ({self.email}){age_info}"

# 年齢範囲でユーザーを検索する関数
def find_users_by_age_range(users, min_age, max_age):
    """指定された年齢範囲のユーザーを検索する"""
    result = []
    for user in users:
        if user.age and min_age <= user.age <= max_age:
            result.append(user)
    return result

5.4 テストコードの生成

テストコードを追加してみます。

Amazon Qへ以下のように指示を出します。

@example.py の関数をテストするためのテストコードを作成してください

生成されたテストコード（test_example.py）は以下です。

import unittest
import tempfile
import os
import json
import csv
from example import User, load_users_from_csv, find_user_by_email, find_users_by_age_range, save_users_to_json

class TestUserManagement(unittest.TestCase):
    
    def test_user_creation_without_age(self):
        """年齢なしでのユーザー作成テスト"""
        user = User("田中太郎", "tanaka@example.com")
        self.assertEqual(user.name, "田中太郎")
        self.assertEqual(user.email, "tanaka@example.com")
        self.assertIsNone(user.age)
    
    def test_user_creation_with_age(self):
        """年齢ありでのユーザー作成テスト"""
        user = User("田中太郎", "tanaka@example.com", 30)
        self.assertEqual(user.name, "田中太郎")
        self.assertEqual(user.email, "tanaka@example.com")
        self.assertEqual(user.age, 30)
    
    def test_get_display_name_without_age(self):
        """年齢なしでの表示名テスト"""
        user = User("田中太郎", "tanaka@example.com")
        expected = "田中太郎 (tanaka@example.com)"
        self.assertEqual(user.get_display_name(), expected)
    
    def test_get_display_name_with_age(self):
        """年齢ありでの表示名テスト"""
        user = User("田中太郎", "tanaka@example.com", 30)
        expected = "田中太郎 (tanaka@example.com) (年齢: 30)"
        self.assertEqual(user.get_display_name(), expected)
    
    def test_find_user_by_email(self):
        """メールアドレスでのユーザー検索テスト"""
        users = [
            User("田中太郎", "tanaka@example.com"),
            User("佐藤花子", "sato@example.com")
        ]
        
        # 存在するユーザーの検索
        found = find_user_by_email(users, "tanaka@example.com")
        self.assertIsNotNone(found)
        self.assertEqual(found.name, "田中太郎")
        
        # 存在しないユーザーの検索
        not_found = find_user_by_email(users, "yamada@example.com")
        self.assertIsNone(not_found)
    
    def test_find_users_by_age_range(self):
        """年齢範囲でのユーザー検索テスト"""
        users = [
            User("田中太郎", "tanaka@example.com", 30),
            User("佐藤花子", "sato@example.com", 25),
            User("鈴木次郎", "suzuki@example.com", 35),
            User("山田三郎", "yamada@example.com")  # 年齢なし
        ]
        
        # 25-32歳の範囲で検索
        result = find_users_by_age_range(users, 25, 32)
        self.assertEqual(len(result), 2)
        self.assertEqual(result[0].name, "田中太郎")
        self.assertEqual(result[1].name, "佐藤花子")
        
        # 該当者なしの範囲で検索
        result_empty = find_users_by_age_range(users, 40, 50)
        self.assertEqual(len(result_empty), 0)
    
    def test_save_users_to_json(self):
        """JSON保存機能のテスト"""
        users = [
            User("田中太郎", "tanaka@example.com", 30),
            User("佐藤花子", "sato@example.com")  # 年齢なし
        ]
        
        # 一時ファイルを作成してテスト
        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.json') as temp_file:
            temp_filename = temp_file.name
        
        try:
            save_users_to_json(users, temp_filename)
            
            # ファイルが作成されたことを確認
            self.assertTrue(os.path.exists(temp_filename))
            
            # ファイル内容を確認
            with open(temp_filename, 'r', encoding='utf-8') as file:
                data = json.load(file)
            
            self.assertEqual(len(data), 2)
            
            # 年齢ありのユーザー
            self.assertEqual(data[0]['name'], "田中太郎")
            self.assertEqual(data[0]['email'], "tanaka@example.com")
            self.assertEqual(data[0]['age'], 30)
            
            # 年齢なしのユーザー
            self.assertEqual(data[1]['name'], "佐藤花子")
            self.assertEqual(data[1]['email'], "sato@example.com")
            self.assertNotIn('age', data[1])  # 年齢が設定されていない場合は含まれない
            
        finally:
            # 一時ファイルを削除
            if os.path.exists(temp_filename):
                os.unlink(temp_filename)
    
    def test_load_users_from_csv_file_not_found(self):
        """存在しないCSVファイルの読み込みテスト"""
        result = load_users_from_csv("nonexistent_file.csv")
        self.assertEqual(result, [])
    
    def test_load_users_from_csv_valid_file(self):
        """有効なCSVファイルの読み込みテスト"""
        # 一時CSVファイルを作成
        csv_data = [
            ['name', 'email', 'age'],
            ['田中太郎', 'tanaka@example.com', '30'],
            ['佐藤花子', 'sato@example.com', '']  # 年齢なし
        ]
        
        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.csv', encoding='utf-8', newline='') as temp_file:
            temp_filename = temp_file.name
            writer = csv.writer(temp_file)
            writer.writerows(csv_data)
        
        try:
            users = load_users_from_csv(temp_filename)
            
            self.assertEqual(len(users), 2)
            
            # 年齢ありのユーザー
            self.assertEqual(users[0].name, "田中太郎")
            self.assertEqual(users[0].email, "tanaka@example.com")
            self.assertEqual(users[0].age, 30)
            
            # 年齢なしのユーザー
            self.assertEqual(users[1].name, "佐藤花子")
            self.assertEqual(users[1].email, "sato@example.com")
            self.assertIsNone(users[1].age)
            
        finally:
            # 一時ファイルを削除
            if os.path.exists(temp_filename):
                os.unlink(temp_filename)

if __name__ == '__main__':
    unittest.main()

5.5 実行可能なメイン処理の追加

example.py にmain処理が無いので追加します。

Amazon Qへ以下のように指示を出します。

@example.py に実際に動作確認できるメイン処理を追加してください

追加されたメイン処理は以下です。

if __name__ == "__main__":
    # サンプルデータでテスト
    print("=== ユーザー管理システムのテスト ===")
    
    # ユーザー作成
    users = [
        User("田中太郎", "tanaka@example.com", 30),
        User("佐藤花子", "sato@example.com", 25),
        User("鈴木次郎", "suzuki@example.com", 35),
        User("山田三郎", "yamada@example.com")  # 年齢なし
    ]
    
    # 全ユーザー表示
    print("\n登録ユーザー:")
    for user in users:
        print(f"  {user.get_display_name()}")
    
    # メールアドレスで検索
    print("\nメール検索テスト:")
    found_user = find_user_by_email(users, "sato@example.com")
    if found_user:
        print(f"  見つかりました: {found_user.get_display_name()}")
    
    # 年齢範囲で検索
    print("\n年齢検索テスト (25-32歳):")
    age_filtered_users = find_users_by_age_range(users, 25, 32)
    for user in age_filtered_users:
        print(f"  {user.get_display_name()}")
    
    # JSON保存
    print("\nJSON保存テスト:")
    save_users_to_json(users, "sample_users.json")
    
    # 存在しないCSVファイルの読み込みテスト
    print("\nCSVファイル読み込みテスト（エラーハンドリング確認）:")
    csv_users = load_users_from_csv("nonexistent.csv")
    print(f"読み込み結果: {len(csv_users)}件のユーザー")
    
    print("\nテスト完了！")

5.6 Amazon Q Developerの活用ポイント

Amazon Q の効率的な使い方のポイントは以下です。

@ファイル名 でファイル全体を参照
具体的な指示を出す（「エラーハンドリングを追加」など）
段階的に機能を追加していく
テストコードも一緒に生成してもらう

このように、Amazon Q Developerを使うことで、既存コードの理解から改善、新機能追加、テスト作成まで効率的に行えます。

6. まとめ

Amazon Q Developer for VSCode を使うことで以下が期待できます。

作業効率向上: 定番の開発環境であるVSCodeを使うことで作業効率向上
コード理解: 既存コードの動作や構造を素早く把握
コード改善: エラーハンドリングや型ヒントなどの品質向上
機能追加: 新しい機能を段階的に実装
テスト作成: 自動的にテストコードを生成
実行確認: メイン処理を追加して動作検証

日本語での指示にも対応しているため、自然な言葉でコード作成・修正ができます。

7. この記事の舞台裏 ― Amazon Q Developerとの協働執筆

この記事は Amazon Q Developer との対話を通じて作成されました。
記事執筆の過程をご紹介します。

7.1 記事作成プロセス

人間（筆者）の役割:

記事の構成や方向性の決定
スクリーンショット画像の撮影・挿入
最終的な内容の確認・調整

Amazon Q Developerの役割:

各章の詳細な文章作成
コードサンプルの生成
テストコードの作成
技術的な説明文の執筆

以下は、VSCode上で記事とコードを同時に執筆している作業風景です。

このように記事を執筆しながら、コード作成・修正を同時に行っています。
人間が内容の確認を行い、Amazon Q とレビューを繰り返し、Amazon Q が記事・コードの修正を行ってくれます。

7.2 協働執筆の効果

今回、Amazon Q Developer を VSCode上で実行し、以下のような効果を実感できました。

効率性の向上:

定番開発環境による作業効率向上
記事の骨格作成時間を大幅短縮
技術的な詳細説明を素早く生成
コードサンプルとテストを同時作成

品質の向上:

一貫した文体と構成
実際に動作するコードサンプル
包括的なテストカバレッジ

創造性の発揮:

人間は全体設計と創造的な部分に集中
AIは詳細な実装と文章作成を担当
両者の強みを活かした分業

この記事の作成プロセス自体が、Amazon Q Developerの実用性を証明しています。

Amazon Q Developer は単なるコーディング支援ツールではなく、技術者の創造的な作業全般をサポートする強力なパートナーです。
ぜひ様々な場面で活用してみてください。

この記事は Amazon Q Developer との協働により作成されました。

最適化ライブラリCeresSolverを使って非線形最小二乗問題を解いてみよう

2025-12-10T00:00:00.000+00:00

本記事は豆蔵デベロッパーサイトアドベントカレンダー2025第10日目の記事です。

0. はじめに

ロボット制御や画像処理の分野では、最適化問題を解く必要に迫られる場面が多々あります。
最適化問題といっても、線形計画法や組合せ最適化など、その種類や解法は多岐にわたります。
その中でも、実用上特によく扱われるのが「最小二乗問題」です。
これは、下記のような目的関数 $F(\boldsymbol{x})$ を最小化するパラメータ $\boldsymbol{x}$ を求める問題です。
（なお、一般的に $\boldsymbol{x}$ はベクトルとなります。）

\min_{\boldsymbol{x}} F(\boldsymbol{x}) = \frac{1}{2} \sum_{i} \| r_i(\boldsymbol{x}) \|^2

ここで、上式の $r_i(x)$ は残差（Residual）といい、観測されたデータ（=実測値） $y_i$ と予測値（=理論値） $f_i(x)$ との差を意味します。

r_i(\boldsymbol{x}) = y_i - f_i(\boldsymbol{x})

今回は、このような非線形最小二乗問題を効率的に解くためのGoogle社製ソルバ "Ceres Solver"について紹介します。

1. 本記事の環境について

本記事ではUbnutu 24.04を対象とします。
筆者の環境ではWSL2を利用していますが、純正のUbuntuでも問題ありません。

Information

本記事ではUbuntu環境でライブラリを使用していますが、Windowsでも動作します。
詳しくは下記リンク先をご覧ください。
http://ceres-solver.org/installation.html#windows

2. 環境構築

CeresSolverを使用するための前準備です。少し長いですがお付き合いください。

必要なライブラリのインストール

まずは、Ceres Solverのビルドに必要なツールをインストールします。
下記を1行ずつ実施して、インストールしてください。

# apt update（パスワード入力を求められます）
sudo apt update && sudo apt upgrade -y
# ビルドツール
sudo apt install build-essential
# Git
sudo apt install git
# CMake
sudo apt install cmake
# google-glog + gflags
sudo apt install libgoogle-glog-dev libgflags-dev
# Use ATLAS for BLAS & LAPACK
sudo apt install libatlas-base-dev
# Eigen3
sudo apt install libeigen3-dev
# SuiteSparse (optional)
sudo apt install libsuitesparse-dev

ワークスペース作成

次に、任意の場所にワークスペースを作成しましょう。
今回はホームディレクトリにceres_solver_wsというディレクトリを作成します。

mkdir ~/ceres_solver_ws

Information

一般的なLinux環境での"~"（チルダ）は、ホームディレクトリを意味します。
ホームディレクトリの絶対パスは/home/${ユーザ名}/です。

CeresSolverライブラリのクローン

ワークスペースが作成出来たら、CeresSolverのソースをクローンしましょう。
クローンする場所は任意ですが、今回はexternalディレクトリ内にクローンしておきます。
この時、Submoduleについても再帰的に取得する必要があるため、--recursiveオプションを付与する必要がある点に注意してください。

cd ~/ceres_solver_ws
mkdir external
cd external
git clone --recursive https://github.com/ceres-solver/ceres-solver

Information

サブモジュールも再帰的に取得するコマンドとして、--recurse-submodulesオプションも存在するようです。

git clone --recurse-submodules ${repo-url}

CeresSolverライブラリのビルド&インストール

クローンが出来たら、CMakeを使用してビルドします。

# CeresSolverのソースに移動
cd ceres-solver
# ビルド用のディレクトリを作成
mkdir build
# ビルドシステムの生成（out-of-sourceビルド）
cmake -S . -B build
# ビルド実行
cmake --build build

ビルドシステム生成時にエラーが発生する場合

コマンド実施に下記のエラーが発生した場合は、build-essentialパッケージをaptでインストールしてください。

CMake Error at CMakeLists.txt:33 (project):
  No CMAKE_CXX_COMPILER could be found.

  Tell CMake where to find the compiler by setting either the environment
  variable "CXX" or the CMake cache entry CMAKE_CXX_COMPILER to the full path
  to the compiler, or to the compiler name if it is in the PATH.

-- Configuring incomplete, errors occurred!

並列ビルドによる高速化

ビルドには少し時間がかかります。下記コマンドで並列ジョブを使用して高速化可能です。
nprocコマンドは「システムが利用可能なCPUコア数を取得する」コマンドです。
この出力結果が$(nproc)と置換されます。

cmake --build build -- -j$(nproc)

下記のように達成率が100%となるようなログが出力されれば、ビルド成功です。

[ 99%] Built target robot_pose_mle
[ 99%] Building CXX object examples/sampled_function/CMakeFiles/sampled_function.dir/sampled_function.cc.o
[ 99%] Linking CXX executable ../../bin/sampled_function
[ 99%] Built target sampled_function
[ 99%] Building CXX object examples/slam/pose_graph_2d/CMakeFiles/pose_graph_2d.dir/pose_graph_2d.cc.o
[ 99%] Linking CXX executable ../../../bin/pose_graph_2d
[ 99%] Built target pose_graph_2d
[ 99%] Building CXX object examples/slam/pose_graph_3d/CMakeFiles/pose_graph_3d.dir/pose_graph_3d.cc.o
[100%] Linking CXX executable ../../../bin/pose_graph_3d
[100%] Built target pose_graph_3d

最後に、ビルドした生成物をインストールします。
インストール先のデフォルトは/usr/localです。

# ビルドした生成物をインストールする
sudo cmake --install build

インストールが完了したら、念のために下記のコマンドを実施しておきましょう。

source ~/.bashrc

3. 簡単な最適化計算を解いてみる

CMakeLists.txtとソースファイルの作成

では、CeresSolverを実際に使用して最適化問題を解いてみましょう。

まずは，ワークスペース~/ceres-solver_wsに戻り、CMakeLists.txtファイルを作成します。

cd ~/ceres_solver_ws
touch CMakeLists.txt

CMakeLists.txtには下記を記述します。
エディタは自由ですが、今回はVisual Studio Codeを使用しています。
（WSLとの相性も良いのでVSCodeはおすすめ！）

# CMakeの最低バージョン指定
cmake_minimum_required(VERSION 3.14)

# プロジェクト名定義
project(ceres-solver-sample)

# 実行ファイルをビルドディレクトリ直下に出力するように設定
# （不要な場合は削除してください）
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})

# 依存パッケージ指定
find_package(Ceres REQUIRED)

# サブディレクトリ追加
add_subdirectory(src)

次に，srcディレクトリを作成します。
srcディレクトリ内にもCMakeLists.txtを作成します。

cd ~/ceres-solver_ws
mkdir src
cd src
touch CMakeLists.txt

src/CMakeLists.txtには下記のように記述します。

# simple-ols
add_executable(simple-ols simple-ols.cpp)
target_link_libraries(simple-ols absl::log_initialize Ceres::ceres)

最後に，計算を記述するC++ファイル（simple-ols.cpp）を作成します。
先述したCMakeLists.txtに記載したファイル名と合致するようにしてください。

touch simple-ols.cpp

最終的なファイル構造は下記のようになります。

ceres_solver_ws/
├── CMakeLists.txt
└── src/
    ├── CMakeLists.txt
    └── simple-ols.cpp

最適化計算の実装

作成したsimple-ols.cppに処理を記述しましょう。

今回のお題としては，下式で定義された関数 $f(x)$ の値を最小化する $x$ を求めてみます。

f(x) = \frac{1}{2} (5 - x)^2

$x=5$ で最小値を取ることは火を見るよりも明らかですが，これをプログラムで求めてみましょう。
実装コードは下記です。

simple-ols.cpp

#include <ceres/ceres.h>
#include <glog/logging.h>

using ceres::AutoDiffCostFunction;
using ceres::CostFunction;
using ceres::Problem;
using ceres::Solver;

/// @brief 残差の構造体
/// @remark 最適化の対象を()演算子にて記述します
struct CostFunctor
{
    template <typename T>
    bool operator()(const T* const x, T* residual) const
    {
		// 今回の最適化対象式
        residual[0] = T(5.0) - x[0];
        return true;
    }
};

/// @brief メイン関数
int main(int argc, char** argv)
{
	// 初期値の定義
    double initial_x = 1.0;
    double x = initial_x;

	// コスト関数の定義
	CostFunction* cost_function = new ceres::AutoDiffCostFunction<CostFunctor, 1, 1>();

	// 最適化問題の定義
    Problem problem;
	problem.AddResidualBlock(cost_function, nullptr, &x);	// 残差ブロックを追加
	problem.SetParameterLowerBound(&x, 0, 0.0);		// 入力パラメータの下限値設定
	problem.SetParameterUpperBound(&x, 0, 10.0);	// 入力パラメータの上限値設定

    // 計算オプションの定義
    ceres::Solver::Options options;
    options.linear_solver_type = ceres::DENSE_QR;	// 密行列でのQR分解を使用する
    options.minimizer_progress_to_stdout = true;	// 進捗出力を有効化
	options.max_num_iterations = 10; // 最大反復回数
    
	// 計算結果の定義
	Solver::Summary summary;

	// 最適化計算を行う
    ceres::Solve(options, &problem, &summary);

	// 計算結果の出力
	// 計算結果は変数xに格納されます
    std::cout << summary.BriefReport() << std::endl;
    std::cout << "x: " << initial_x << " -> " << x << std::endl;

    return 0;
}

プログラムの詳細

コードの中で重要な部分について説明します。

コスト定義

/// @brief コスト構造体
/// @remark 最適化の対象を()演算子にて記述します
struct CostFunctor
{
    template <typename T>
    bool operator()(const T* const x, T* residual) const
    {
		// 今回の最適化対象式
        residual[0] = T(5.0) - x[0];
        return true;
    }
};

今回の最適化の対象となる式を記述します。

()演算子の中に計算式を記述する必要があります。
テンプレートTには、最適化計算時に使用される型が使用されます。
- 具体的には、ceres::Jet型というデータ型が使用されます。
- double型などを使用する場合は、T型でキャストする必要がある点に注意してください

コスト関数の定義

// コスト関数の定義
CostFunction* cost_function = new ceres::AutoDiffCostFunction<CostFunctor, 1, 1>();

上記にはコスト関数の定義を行っています。今回は計算で自動微分（Automatic Differentiation）を使用するように設定しています。
また、テンプレート引数のそれぞれの意味は下記の通りです。

第1引数: コスト関数の構造体型
第2引数: 誤差パラメータの次元数
第3引数: 最適化パラメータの次元数

今回のお題では、誤差パラメータの次元(= $f(x)$ の次元）はスカラーのため1、最適化パラメータ $x$ の次元は同じくスカラー量のため1となります。

最適化問題の定義

// 最適化問題の定義
Problem problem;
problem.AddResidualBlock(cost_function, nullptr, &x);	// 残差ブロックを追加
problem.SetParameterLowerBound(&x, 0, 0.0);		// 入力パラメータの下限値設定
problem.SetParameterUpperBound(&x, 0, 10.0);	// 入力パラメータの上限値設定

最適化問題を定義します。
また、入力パラメータの上限値、下限値もここで設定します。

AddResifualBlockメソッドの第2引数は損失関数（Loss Function）を定義できます。
本記事では詳細を割愛しますが、詳細は下記リンク先をご覧ください。
http://ceres-solver.org/nnls_tutorial.html#robust-curve-fitting

ビルドと実行

CMakeを使用して作成したプログラムをビルドします。

cd ~/ceres_solver_ws
cmake -S . -B bin
cmake --build bin

ビルドが成功したら、下記のコマンドで実施してみましょう。

./bin/simple-ols

これを実施すると、下記のようなログが出力されます。

iter      cost      cost_change  |gradient|   |step|    tr_ratio  tr_radius  ls_iter  iter_time  total_time
   0  8.000000e+00    0.00e+00    4.00e+00   0.00e+00   0.00e+00  1.00e+04        0    1.35e-05    4.40e-05
   1  7.998400e-08    8.00e+00    4.00e-04   0.00e+00   1.00e+00  3.00e+04        1    8.09e-05    1.88e-04
   2  8.886518e-17    8.00e-08    1.33e-08   4.00e-04   1.00e+00  9.00e+04        1    3.24e-05    2.39e-04
Ceres Solver Report: Iterations: 3, Initial cost: 8.000000e+00, Final cost: 8.886518e-17, Termination: CONVERGENCE
x: 1 -> 5

最終行のログより、最適入力値は5であると計算できました。
また、最適入力値の場合の残差コスト（Final cost）は8.886518e-17であり、ほぼ0であることも計算できました。

入力パラメータの上下限値を変えてみる

次に、入力値の範囲を1~3に変更して計算してみましょう。
下記の★印部分の値を10から3に変更します。

// 最適化問題の定義
Problem problem;
problem.AddResidualBlock(cost_function, nullptr, &x);	// 残差ブロックを追加
problem.SetParameterLowerBound(&x, 0, 0.0);	// 入力パラメータの下限値設定
problem.SetParameterUpperBound(&x, 0, 3.0);	// 入力パラメータの上限値設定（★）

これを再度ビルドして実行してみると、最適入力は $x=3$ 、残差コストは2.000000e+00となります。
指定した制約内でコストが最小となるような最適入力が求められることが確認できます。
参考のため、計算ログを下記に記します。

iter      cost      cost_change  |gradient|   |step|    tr_ratio  tr_radius  ls_iter  iter_time  total_time
   0  8.000000e+00    0.00e+00    2.00e+00   0.00e+00   0.00e+00  1.00e+04        0    1.21e-05    4.23e-05
   1  2.000000e+00    6.00e+00    0.00e+00   0.00e+00   7.50e-01  1.14e+04        1    6.80e-05    1.66e-04
Ceres Solver Report: Iterations: 2, Initial cost: 8.000000e+00, Final cost: 2.000000e+00, Termination: CONVERGENCE
x: 1 -> 3

4. 4自由度平面マニピュレータの逆運動学を数値的に解いてみる

3章では入力パラメータとコストがともにスカラー量である最適化問題を解くサンプルを紹介しました。
本章では、より難しい非線形最適化問題のお題として「4自由度平面マニピュレータの逆運動学」を解いてみましょう。

4自由度平面マニピュレータとは

下図のような4つの関節を持つ平面マニピュレータを対象に、逆運動学計算を実装してみます。
パラメータについては下記の通りとします。

各リンク長は $L_i$ とする
各関節角度の回転角度を $\theta_i$ $θ_{i}$ とする
- $i=1,2,3,4$
各関節の回転正方向は「反時計回り（ccw）」とする
ロボットの先端（点P）のX座標を $x_p$ 、Y座標を $y_p$ とする
ロボットの先端の姿勢角度（半直線CPとX軸のなす角）を $\phi$ とする

順運動学計算

対象ロボットの各軸角度 $\boldsymbol{\theta}$ と先端位置 $\boldsymbol{p}$ の関係を考えてみましょう。
ここで、それぞれのベクトルの定義は下記とします。

\boldsymbol{\theta} = \begin{bmatrix} \theta_1 \\ \theta_2 \\ \theta_3 \\ \theta_4 \end{bmatrix}

\boldsymbol{p} = \begin{bmatrix} x_p \\ y_p \\ \phi \end{bmatrix}

上図での原点Oから点Aまでのベクトル $\vec{OA}$ は下記のように記述できます。

\vec{OA} = \begin{bmatrix} l_1 \cos \theta_1 \\ l_1 \sin \theta_1 \end{bmatrix}

これと同様に、点Aから点B、点Bから点C、点Cから点Pまでのベクトルはそれぞれ下記のようになります。

\vec{AB} = \begin{bmatrix} l_2 \cos(\theta_1 + \theta_2) \\ l_2 \sin(\theta_1 + \theta_2) \end{bmatrix}

\vec{BC} = \begin{bmatrix} l_3 \cos(\theta_1 + \theta_2 + \theta_3) \\ l_3 \sin(\theta_1 + \theta_2 + \theta_3) \end{bmatrix}

\vec{CP} = \begin{bmatrix} l_4 \cos(\theta_1 + \theta_2 + \theta_3 + \theta_4) \\ l_4 \sin(\theta_1 + \theta_2 + \theta_3 + \theta_4) \end{bmatrix}

これらを合わせると、XY平面上での点Pの座標は下記のようになります。
（式が長くなるためベクトル表記のままとしています）

\begin{bmatrix} x_p \\ y_p \end{bmatrix} = \vec{OA} + \vec{AB} + \vec{BC} + \vec{CP}

また、ロボット先端の姿勢角度 $\phi$ は下記のようになります。

\boldsymbol{\phi} = \theta_1 + \theta_2 + \theta_3 + \theta_4

上式2つを合わせ、関節角度ベクトル $\boldsymbol{\theta}$ から先端位置ベクトル $\boldsymbol{p}$ への写像を $f$ と定義すると、下式のように表現できます。

\boldsymbol{p} = f(\boldsymbol{\theta})

これがロボットの順運動学計算時に使用する式となります。

逆運動学計算

一方、逆運動学（Inverse Kinematics）は文字通り順運動学の逆を意味します。
つまり、 $f$ の逆関数（=先端位置 $\boldsymbol{p}$ から関節角度 $\boldsymbol{\theta}$ への写像）を求める操作となります。

\boldsymbol{\theta} = f^{-1}(\boldsymbol{p})

一般的に順運動学よりも逆運動学計算の方が計算量が多くなります。
ロボットの機構次第では解析的に解くことも可能ですが、一般的に自由度が多くなるほど逆運動学計算の難易度は難しくなります。
今回はこの計算をCeresSolverを使って数値的に解いてみます。

コード実装

ディレクトリとCMakeLists.txtの作成

srcディレクトリ直下に本問題を解くためのファイルを格納するディレクトリを作成します。
ディレクトリ名は4dof-ikとします。

cd ~/ceres_solver_ws/src
mkdir 4dof-ik
cd 4dof-ik
touch CMakeLists.txt

作成した4dof-ikディレクトリもサブディレクトリとして登録されるように、srcディレクトリ直下のCMakeLists.txtに下記を記載します。（最終行を追加してください）

# simple-ols
add_executable(simple-ols simple-ols.cpp)
target_link_libraries(simple-ols absl::log_initialize Ceres::ceres)

# 4dof-ikディレクトリをサブディレクトリとして登録する
add_subdirectory(4dof-ik)

データ構造体の定義

まずはデータ構造をまとめるための構造体を定義します。
4dof-ikディレクトリ内に、位置と姿勢をまとめたPose構造体と、ロボットの機構パラメータをまとめたKinematicsParameters構造体を作成します。

cd ~/ceres_solver_ws/src/4dof-ik
touch Pose.hpp
touch KinematicsParameters.hpp

下記のように記述します。

Pose.hpp

/// @brief 姿勢
struct Pose
{
    /// @brief X座標
    double x; 

    /// @brief Y座標
    double y;

    /// @brief 先端角度
    double phi;

    Pose(double x_, double y_, double phi_)
        : x(x_), y(y_), phi(phi_){}
};

KinematicsParameters.hpp

/// @brief 機構パラメータ (リンク長)
struct KinematicParameters {
    /// @brief 第1リンク長
    double L1; 

	/// @brief 第2リンク長
    double L2;

	/// @brief 第3リンク長
    double L3;

	/// @brief 第4リンク長
    double L4;

    /// @brief コンストラクタ
    /// @param l1 第1リンク長
    /// @param l2 第2リンク長
    /// @param l3 第3リンク長
    /// @param l4 第4リンク長
    KinematicParameters(double l1, double l2, double l3, double l4)
        : L1(l1), L2(l2), L3(l3), L4(l4) {}
};

最適化計算の実装

次に、逆運動学計算を解くためのメインプログラムを作成します。

メインプログラム作成

touch 4dof-ik.cpp

最終的なファイル構造は下記のようになります。

ceres_solver_ws/
├── CMakeLists.txt
└── src/
    ├── CMakeLists.txt
    ├── simple-ols.cpp
    └── 4dof-ik/
        ├── CMakeLists.txt
        ├── 4dof-ik.cpp
        ├── KinematicsParameters.hpp
        └── Pose.hpp

4dof-ik.cppの実装は下記の通りです。

4dof-ik.cpp

#include <iostream>
#include <ceres/ceres.h>
#include <ceres/rotation.h>
#include <cmath>
#include "Pose.hpp"
#include "KinematicsParameters.hpp"

/// @brief 順運動学を行う
/// @tparam T データ型
/// @param[in] kp 機構パラメータ
/// @param[in] theta 関節角度ベクトル（配列）
/// @param[out] x X座標
/// @param[out] y Y座標
/// @param[out] phi 先端角度
template <typename T>
void compute_forward_kinematics(const KinematicParameters& kp, const T* const theta, T& x, T& y, T& phi)
{
    x = T(kp.L1) * cos(theta[0])
      + T(kp.L2) * cos(theta[0] + theta[1])
      + T(kp.L3) * cos(theta[0] + theta[1] + theta[2])
      + T(kp.L4) * cos(theta[0] + theta[1] + theta[2] + theta[3]);

    y = T(kp.L1) * sin(theta[0])
      + T(kp.L2) * sin(theta[0] + theta[1])
      + T(kp.L3) * sin(theta[0] + theta[1] + theta[2])
      + T(kp.L4) * sin(theta[0] + theta[1] + theta[2] + theta[3]);

    phi = theta[0] + theta[1] + theta[2] + theta[3];
}

/// @brief コスト
struct IKCostFunction
{
    Pose target_pose;
    KinematicParameters kp;

    /// @brief コンストラクタ
    /// @param pose 先端位置・姿勢
    /// @param param 機構パラメータ
    IKCostFunction(const Pose& pose, const KinematicParameters& param)
        : target_pose(pose), kp(param)
    {
    }

    template<typename T>
    bool operator()(const T* const theta, T* residuals) const
    {
		T x, y, phi;
		compute_forward_kinematics(kp, theta, x, y, phi);

        residuals[0] = T(target_pose.x) - x;	// X座標誤差
        residuals[1] = T(target_pose.y) - y;	// Y座標誤差
        residuals[2] = T(target_pose.phi) - phi;	// 姿勢角度誤差

        return true;
    };
};

/// @brief メイン関数
int main(int argc, char** argv)
{
    // 機構パラメータの定義
    double l1 = 1.5;
    double l2 = 1.5;
    double l3 = 1.0;
    double l4 = 1.0;

    // 目標位置・姿勢の定義
    double x_target = 3.2;
    double y_target = 0.8;
    double phi_target = -M_PI_4;

    // 初期値の設定
    double theta[4] = {0.0, 0.0, 0.0, 0.0};
    KinematicParameters kp(l1, l2, l3, l4);
    Pose target_pose{ x_target, y_target, phi_target };

    // 最適化問題の定義
    ceres::Problem problem;
    problem.AddResidualBlock(
		// 誤差次元数は3、最適化変数次元数は4
        new ceres::AutoDiffCostFunction<IKCostFunction, 3, 4>(
            new IKCostFunction(target_pose, kp)
        ),
        nullptr,
        theta
    );

    // 上下限値の適用（-pi ~ piとする）
    for (int i = 0; i < 4; i++)
    {
        problem.SetParameterLowerBound(theta, i, -M_PI);
        problem.SetParameterUpperBound(theta, i, M_PI);
    }

    // ソルバ設定
    ceres::Solver::Options options;
    options.linear_solver_type = ceres::DENSE_QR;
    options.minimizer_progress_to_stdout = true;
    options.max_num_iterations = 100; // 最大反復回数
    options.function_tolerance = 1e-6; // 収束判定の閾値

    // 最適化計算を解く
    ceres::Solver::Summary summary;
    ceres::Solve(options, &problem, &summary);

	// 計算結果の出力
    std::cout << summary.BriefReport() << std::endl;
    if (summary.termination_type == ceres::CONVERGENCE)
    {
        std::cout << "✅ IK Solution Found! (Final Cost: " << summary.final_cost << ")\n";
    } 
    else
    {
        std::cout << "❌ IK Failed to Converge.\n";
    }

    // 求まった関節角度の出力
    std::cout << "theta[0] = " << theta[0] << std::endl;
    std::cout << "theta[1] = " << theta[1] << std::endl;
    std::cout << "theta[2] = " << theta[2] << std::endl;
    std::cout << "theta[3] = " << theta[3] << std::endl;

	// 求めた関節角度でどの位置・姿勢になるかを確かめる
    std::cout << "Check Forward kinematics calculation:" << std::endl;
	double x_result, y_result, phi_result;
	compute_forward_kinematics(kp, theta, x_result, y_result, phi_result);
    std::cout << "x   = " << x_result << std::endl;
    std::cout << "y   = " << y_result << std::endl;
    std::cout << "phi = " << phi_result << std::endl;
    return 0;
}

CMakeLists.txtに追加する

4dof-ikディレクトリ内のCMakeLists.txtに下記を記述します。

4dof-ik/CMakeLists.txt

# 4dof-ik
add_executable(4dof-ik 4dof-ik.cpp)
target_link_libraries(4dof-ik absl::log_initialize Ceres::ceres)

ビルド・実行

ワークスペースに移動してビルドします。

cd ~/ceres_solver_ws
cmake --build bin

実行してみます。

./bin/4dof-ik

実行結果は下記のようになると思います。
（イテレーション結果は割愛します）

Ceres Solver Report: Iterations: 7, Initial cost: 2.248425e+00, Final cost: 4.808292e-20, Termination: CONVERGENCE
✅ IK Solution Found! (Final Cost: 4.80829e-20)
theta[0] = -0.414376
theta[1] = 1.25568
theta[2] = 0.609086
theta[3] = -2.23579
Check Forward kinematics calculation:
x   = 3.2
y   = 0.8
phi = -0.785398

最終コストはほぼ0のため、指定した目標位置・姿勢を満たす関節角度を見つけることが出来ました！
また、検算結果も正しそうです！

5. おわりに

本記事では、CeresSolverを使用して最適化問題を解くプログラムを紹介しました。
本記事で紹介したサンプル以外にも、公式ページでは多くのサンプルプログラムが提供されています。
興味のある方は確認してみてください。
http://ceres-solver.org/nnls_tutorial.html#non-linear-least-squares

また、今回作成したプログラムは、下記のリポジトリで公開しています。
https://github.com/hayat0-ota/CeresSolver_tutorial

Spring Boot 4で標準採用！JSpecifyによるnull安全性

2025-12-09T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025 第9日目の記事です。

先月の11月に、Spring Boot 4 と Spring Framework 7 がリリースされました。
Spring Boot 4ではnull安全性（Null-Safety）の強化が図られ、JSpecify が標準採用されました。

そこで今回は、Spring Boot 4によるJSpecifyについて記事にしたいと思います。

JSpecifyとは

JSpecifyは、Javaにおけるnull安全性を標準化するための仕様と、そのアノテーションを提供するオープンソースプロジェクトです。
Javaプログラムのnull安全性を高め、異なるツールやライブラリ間での互換性の問題を解決するための共通的なルールブックのようなものと捉えていただければよいと思います。

JSR-305の停滞やnull安全性に関したアノテーションの乱立を背景に、2021年にGoogleがJSpecifyプロジェクトを立ち上げ、JetBrainsやMeta、Sonarなどの複数の組織と協力して開発を進めてきました。

JSpecifyの1.0.0版がリリースされたのは2024年の7月です。
その後、Spring Boot 4.0.0-M2のリリースノートでは、JSpecify準拠のアノテーションをコードベースに導入することが発表されました。

Spring Boot 3系でのnull安全性

筆者の勝手な想像ですが、Spring Boot 3系でJSpecifyを利用されていた開発プロジェクトは少ないのではないでしょうか。
筆者が関わってきた開発プロジェクトで、JSpecifyを利用したことは一度もありませんでした。また、筆者のまわりでもJSpecifyを利用された話は聞いたことがありません。
そのため、このタイミングでJSpecifyがくるとは、まったく予想していなかったというのが正直なところです。

では、Spring Boot 3系でのnull安全性はどのように実装していたかと言いますと、筆者はSpring Frameworkから提供されるアノテーションを利用していました。
基本的には、Spring Frameworkの@NonNullApiと@Nullableの組み合わせで利用することがほとんどでした。

まず、package-info.javaのパッケージ宣言に@NonNullApiアノテーションを付与し、そのパッケージ配下のクラス等でnullを許容するメソッドの戻り値や引数に@Nullableアノテーションを付与していました。

package-info.java

@org.springframework.lang.NonNullApi
package com.mamezou.blog.batch.util;

// nullを空文字へ変換する。
public static String nullToEmpty(@Nullable String value) {
  return value == null ? "" : value;
}

// 空文字をnullへ変換する。
@Nullable
public static String emptyToNull(@Nullable String value) {
  return (value == null || value.isEmpty()) ? null : value;
}

この他にも@NonNullFieldsアノテーションや@NonNullアノテーションが提供されていますが、主にはこの組み合わせで利用することが多かったと記憶しています。

JSpecifyの導入

JSpecifyの利用方法を説明する前に、プロジェクトへのJSpecifyの導入について簡単に触れておきたいと思います。

Spring Boot 3系でJSpecifyを導入する際には、次のようにMavenプロジェクトのpom.xmlにJSpecifyの依存関係を追加する必要がありました。

pom.xml

<dependency>
    <groupId>org.jspecify</groupId>
    <artifactId>jspecify</artifactId>
    <version>1.0.0</version>
</dependency>

ですが、Spring Boot 4ではJSpecifyが標準採用されたため、個別にこのような依存関係を追加する必要がありません。
Spring BootのStarterライブラリが含まれていれば、JSpecifyを利用することができます。

記事の執筆に向けて作成したMavenプロジェクトの依存ライブラリを確認してみると、次のとおりとなりました。

$ mvn dependency:tree -Dincludes=org.jspecify:jspecify
[INFO] --- dependency:3.9.0:tree (default-cli) @ mamezou-blog-batch ---
[INFO] com.mamezou.blog:mamezou-blog-batch:jar:1.0.0
[INFO] \- org.springframework.boot:spring-boot-h2console:jar:4.0.0:compile
[INFO]    \- org.springframework.boot:spring-boot:jar:4.0.0:compile
[INFO]       \- org.springframework:spring-core:jar:7.0.1:compile
[INFO]          \- org.jspecify:jspecify:jar:1.0.0:compile

なお、今回はApplicationRunnerを用いたCLIベースのバッチアプリケーションとしたため、Spring MVCなどのWeb開発に関したStarterライブラリは含んでおりません。

Information

Spring Boot 4にて、Spring MVCのStarterライブラリの名称が変更されました。
Spring MVCのStarterライブラリは、Spring Boot 3系ではspring-boot-starter-webでしたが、Spring Boot 4ではspring-boot-starter-webmvcとなります。
Spring Initializrなどからプロジェクトを作成する際は特に気にすることもありませんが、直接pom.xmlやbuild.gradleを編集する際はご注意ください。

JSpecifyの利用

それでは、JSpecifyが提供するアノテーションについて説明していきたいと思います。

JSpecifyにおけるnull安全性のアノテーションは、次の4つを利用します。

No.	アノテーション	説明
1	`@Nullable`	null許容であることを示すアノテーション。
2	`@NonNull`	null非許容であることを示すアノテーション。
3	`@NullMarked`	一律でnull非許容とするためのアノテーション。
4	`@NullUnmarked`	null安全性チェックの対象外とするアノテーション。

Nullable と NonNull

メソッドの戻り値や引数にnullを許容する場合は、@Nullableアノテーションを使用します。
一方で、nullを非許容とする場合は、@NonNullアノテーションを使用します。
利用方法としては、Spring Frameworkから提供されるアノテーションと同じです。

Spring Frameworkのアノテーションと比較して大きく異なるのが、JSpecifyの@Nullableと@NonNullは、アノテーションの定義における@TargetにElementType.TYPE_USEが指定されている点です。

org.springframework.lang.Nullable

@Target({ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@CheckForNull
@Deprecated(since = "7.0")
@TypeQualifierNickname
public @interface Nullable

org.jspecify.annotations.Nullable

@Documented
@Target({ElementType.TYPE_USE})
@Retention(RetentionPolicy.RUNTIME)
public @interface Nullable

これにより、JSpecifyの@Nullableと@NonNullは、型が使用されているあらゆるところにアノテーションを付与することができます。
たとえば、次のような@Nullableの指定は、Spring Frameworkのアノテーションではビルドエラーとなりますが、JSpecifyのアノテーションではエラーになりません。

@NonNull
public List<@Nullable String> getValues {
  // ----- ＜中略＞ ----- //
}

この場合、戻り値となるListの要素にnullが含まれてもよいことを示しています。Listそのものはnull非許容となります。

NullMarked

@NullMarkedは、Spring Frameworkの@NonNullApiや@NonNullFieldsと同様となり、package-info.javaのパッケージ宣言に付与することで、パッケージ内のクラス等を一括でnull非許容として扱うことができます。
つまり、@NullMarkedを使用すれば、null非許容とする箇所に@NonNullを指定する必要がなくなりますね。

package-info.java

@org.jspecify.annotations.NullMarked
package com.mamezou.blog.batch.util;

// @NonNull ← これは不要
public static String nullToEmpty(@Nullable String value) {
  return value == null ? "" : value;
}

先述の「Spring Boot 3系でのnull安全性」のように、JSpecifyにおいても@NullMarkedと@Nullableの組み合わせでnull安全性を実現することができます。

NullUnmarked

最後に@NullUnmarkedですが、Spring Frameworkにこれ相応のアノテーションは存在せず、JSpecify特有のアノテーションとなります。
@NullUnmarkedは、null安全性チェックの対象外とするためのアノテーションです。

次のようなメソッドは本来、戻り値と引数に@Nullableを付与する必要がありますが、@NullUnmarkedをクラスに付与することでnull安全性チェックの対象外とすることができます。

@NoArgsConstructor(access = AccessLevel.PRIVATE)
@NullUnmarked
public final class StringUtils {

  public static String emptyToNull(String value) {
    return (value == null || value.isEmpty()) ? null : value;
  }

}

@NullMarkedと同様、@NullUnmarkedもpackage-info.javaのパッケージ宣言に付与することができます。
しかし、パッケージ宣言に@NullUnmarkedを指定してしまうと、null安全性チェックの対象外のスコープを広めてしまうため、パッケージ宣言は@NullMarkedを基本とし、必要に応じてクラスまたはメソッドの単位に@NullUnmarkedを指定するのがよいと筆者は考えます。

アノテーションの対応関係

null安全性に関して、Spring Frameworkのアノテーションと比較しながら、JSpecifyのアノテーションについて説明してきました。
これらのアノテーションの対応関係をまとめると、下表のとおりとなります。

No.	Spring Boot 4（JSpecify）	Spring Boot 3系（Spring Framework）
1	`org.jspecify.annotations.Nullable`	`org.springframework.lang.Nullable`
2	`org.jspecify.annotations.NonNull`	`org.springframework.lang.NonNull`
3	`org.jspecify.annotations.NullMarked`	`org.springframework.lang.NonNullApi`
4	`org.jspecify.annotations.NullMarked`	`org.springframework.lang.NonNullFields`
5	`org.jspecify.annotations.NullUnmarked`	該当なし

ここでひとつ、残念なお知らせがあります。
Spring Boot 4のリリースと併せて、Spring Frameworkから提供される@Nullable、@NonNull、@NonNullApi、および@NonNullFields は非推奨（@Deprecated）となりました。
これらのJavadocを参照すると、すべてJSpecifyのアノテーションへの移行を促しています。

つまり、Spring Frameworkのアノテーションを利用している開発プロジェクトでは、Spring Bootのバージョンアップに伴ってJSpecifyのアノテーションへの置き換えが必要となります。
すでにSpring Boot 4へのバージョンアップが計画されている開発プロジェクトや、数年先にリリースを控えている開発プロジェクトでは、少なからず影響があるのではないでしょうか。

最後に

というわけでして、簡単ですがSpring Boot 4に標準採用されました「JSpecify」について説明させていただきました。
さらに詳細な利用方法については、JSpecify公式のユーザーガイドなどを参照いただきたく存じます。

Spring FrameworkやJakartaプロジェクト、JetBrains、Lombokなど、null安全性のアノテーションが乱立する中、JSpecifyプロジェクトによる標準化に向けた動きそのものは正しい取り組みと感じています。
しかし、その一方でSpring Bootを用いたアプリケーション開発において、Spring Frameworkのアノテーションが非推奨となることは予想できなかったですし、冒頭でも述べたとおりJSpecifyが巻き返してくるとは思ってもみませんでした。

Spring Bootのアップデートに伴い、Spring Frameworkにおけるnull安全性のアノテーションが非推奨となっても、アプリケーションの動作に直接影響することはないと思います。
ですが、非推奨のまま利用し続けるのは、ちょっと！ちょっとちょっと！という想いです。
また、多くの開発プロジェクトでも、非推奨のものを利用するな！が基本原則として定められていることと推察します。
ですので、これに関してはSpring Bootをアップデートする際、Spring FrameworkのアノテーションをJSpecifyのアノテーションに置き換えるというのが正しい対応と言えるでしょう。

今回は、JSpecifyのnull安全性といった少し地味目のネタではありましたが、最後までご覧いただき本当にありがとうございました。

ヘキサゴナルアーキテクチャの“違和感“を徹底解剖！3つの疑問と本質を図解でスッキリ理解

2025-12-08T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第8日目の記事です。

ヘキサゴナルアーキテクチャ（Ports & Adapters）って、なんとなくわかった気はするけど、どこか腑に落ちないところありませんか？私の場合はだいたい次の3点でした。

「依存は外側 → 内側」と言うけれど入力ポートと実装で依存が逆向きに見えるのはなぜ？それっていいの？
入力のアダプタはポートを実装していないのに出力のアダプタはポートを実装しているのはなにか気持ち悪い
そもそも、オニオンアーキテクチャと何が違うの？

今回の記事は、これらのモヤモヤを整理したときのメモを例を交えながら説明していきたいと思います。

1. 説明の例に使うヘキサゴナル構成

最初に今回の記事は次に示す「教科書的なヘキサゴナル」なパッケージ構造をもつ Spring Boot のTODOアプリを例に行います。

com.example.todohex
├─ TodoHexApplication        … @SpringBootApplication
│
├─ domain                    … ドメインモデル（純粋Java）
│   └─ Task.java
│
├─ application
│   ├─ port
│   │   ├─ in                … 入力ポート（UseCase IF）
│   │   │   ├─ CreateTaskUseCase.java
│   │   │   └─ GetTaskUseCase.java
│   │   └─ out               … 出力ポート（Repo/Gateway IF）
│   │       ├─ SaveTaskPort.java
│   │       └─ LoadTaskPort.java
│   └─ service               … ユースケース実装
│       └─ TaskService.java
│
├─ adapter
│   ├─ in
│   │   └─ web                … RESTアダプタ（入力側）
│   │       ├─ TaskController.java
│   │       ├─ TaskRequest.java
│   │       └─ TaskResponse.java
│   └─ out
│       └─ persistence        … 永続化アダプタ（出力側）
│           ├─ TaskEntity.java
│           ├─ SpringDataTaskRepository.java
│           └─ TaskPersistenceAdapter.java
└─ ...

2. 依存が逆になところがあるけどいいの？

では早速最初のモヤモヤへ。どこが「逆向きに見える」かですが、教科書的に UseCase と Service を導出すると依存関係^[1]が逆になります。例をもとに図にすると次のように赤線の依存関係が右から左になっています。

一方でヘキサゴナルアーキテクチャに対する世の中的な解説では「モジュールの依存は外側 → 内側」といった説明がたくさん出てきます。ここで「えっ、port と service の依存関係って外側から内側の反対に向いているけどこれっていいの？」というモヤモヤが沸いてきます。

そこで、いったん原典に立ち戻りヘキサゴナルアーキテクチャの提唱者であるアリスター・コバーン自身は何といっているかを振り返ると、彼が原典といえる元記事でいっていることは大ざっぱにいうと以下のようなことです。

アプリケーションは Port を通して外部と会話する

その Port のプロトコルは「アプリケーションの API という形をとる」

ここでいう「API」は、メソッド呼び出しでもいいし, HTTP でも, メッセージングのプロトコルでもなんでも良い、というかなり抽象的なレベルの話をしていて、少なくとも原典では、

「入力ポートを インタフェースと実装クラス に分けろ」
「モジュールの依存矢印は 必ず外→内に向けろ」

といった Java 的な「お作法レベル」のことはいっていません。また、最近の彼のスライド版では型付き言語向けに

“required interface” を宣言しよう

Port の宣言用フォルダを用意しよう

くらいはいっていますが、依存の矢印ルールそのものには踏み込んでいません。

結論：依存を外側から内側へは単なる都市伝説

アリスター・コバーンは依存の方向についてはなにもいっていません。むしろ、ポートにはインタフェースを出せといっているので、ポートとその実装の依存関係が逆になるのは自然です。この話しは「依存は外側のリングから内側のリングへだけ許可すべし」と明確にいっているクリーンアーキテクチャ^[2]と同じコンテキストでヘキサゴナルアーキテクチャが語られることから生まれた都市伝説ではないかと思います。
ただ、port.in と service を 1 つの「アプリケーション・コアの塊」として見てしまえば、adapter.in → （port.in＋service） → domain という「外→内」の構図となるので、いわゆる、クリーンアーキテクチャの1種とみても問題ないとも思います

3. アダプタってポートを実装しないの？

次のモヤモヤはこれです。

in 側の adapter（Controller 等）は port.in を実装していない（赤の依存）
out 側の adapter（DB や外部API）は port.out を実装している（青の依存）

言葉だけではわかりづらいので図で表すと次のようになっています。

同じアダプタでもポートを実装したりしなかったり、そもそも左右で対称じゃなく、なんとなく気持ち悪いですよね。というか正直これってホントにあってるの？と思ったりしたのは私だけでしょうか？

疑問があったら原典ということでコバーンがなんといっているか再度みてみましょう。
彼は Hexagonal を Ports & Adapters とも呼びますが、ここでいう Port と Adapter は「役割の名前」になっています。

Port：
- 「何のための会話か」を表す論理的な接点
Adapter：
- その Port を、特定の技術（HTTP / CLI / DB / メール / ファイル…）に接続する変換器

そして彼のスライドではPort を

Driving Ports（アプリケーションを「駆動する」側）
Driven Ports（アプリケーションが「駆動される」側）

に分けて説明しています。

この観点で見ると、

Driving Port 側
- Adapter（UI / REST / Batch …）は「Port の定義に従ってコールするクライアント」
Driven Port 側
- Adapter（DB / メール / 外部API …）は「Port の定義を満たして処理するサーバ」

になるため、

in 側の adapter が port を実装していない
out adapter が port を実装している

という非対称さは実は自然なものとなります。

結論：アダプタとポートは役割名で構文パターンのことではない

Port / Adapter という名前は「入力＝implements、出力＝implements」という構文パターンのことではなく、「会話の目的を表す窓口」と「外界との変換器」という役割を指しているだけ。そう捉えると、実装有無の非対称さはそこまで気にならなくなります。

4. オニオンアーキテクチャと何が違うの？

最後のモヤモヤはこれです。

結局、ヘキサゴナルとオニオンって、何がどう違うの？

では、その違いが分かるようにそれぞれの全体構造をみてみたいと思います。

まずオニオンアーキテクチャ

オニオンアーキテクチャをラフに描くと次のような感じになります。

オニオンアーキテクチャの主眼は（今回の図からは分かりづらいですが、、）

ドメインを中心に同心円状に層を作り
依存は外側 → 内側になるようにして
ドメインを守る

といったところになります。

次にヘキサゴナルアーキテクチャの構造

対してヘキサゴナル（Ports & Adapters）は、境界（Port）にフォーカスしたアーキテクチャといえます。

こうして2つを並べてみると、ヘキサゴナルアーキテクチャは構造的にオニオンアーキテクチャの application 部分とその境界まわりを port.in / port.out と adapter.in / adapter.out に細かく分解し、入出力の境界（どこから入って、どこへ出ていくか）を強調したものと見ることができます。

つまり一言でいうと：

オニオンアーキテクチャ：層（Layer）で内側を守るアーキテクチャ
ヘキサゴナルアーキテクチャ：ポートとアダプタで境界を強調するアーキテクチャ

で、目指しているゴール自体はどちらも

ドメイン中心
外界（UI/DB/外部システム）からの独立
テスタビリティ向上

といったところでかなり近いです。

結論：ヘキサゴナルはオニオンの上級バージョン（ともいえる）

構造的な観点では「ヘキサゴナル＝オニオンの application＋境界部分を、port と adapter に分解して“入出力の境界を強調したバージョン”」といえます。
ただし、オニオンアーキテクチャは外側から内側に向かって層を成していく構造をその特徴にしているのに対して、ヘキサゴナルアーキテクチャは図の青線の関係が表すように外→内→外となる構造にすることで「どこから入って、どこへ出ていくか」を構造として強調することをその特徴としています。よって、もともとのコンセプトは異なるものとなります。

5. おわりに

ヘキサゴナルアーキテクチャにすることで確かにクリーンなアーキテクチャを実現することはできますが、それにはコストが掛かります。コバーン自身もスライドの中で次のことをいっています。

各 Port ごとにフィールドや DI 設定が増える
型付き言語では Port 用のインタフェースやフォルダ構成が必要
Configurator（構成ルート）の設計が必要

つまり、ヘキサゴナルアーキテクチャはきれいさと引き換えにクラスやインタフェースが増えます。個人的にドメインを分離したいだけならオニオンアーキテクチャでも十分なことも多いと思っています。
良いものが常に良い訳ではありません。自分たちが必要としているものはなにか？を考え、それにフィットするアーキテクチャを選択するのがアーキテクチャ設計では重要になります。

UML的に「依存関係」といった場合、2者間の一時的な関係(dependency)を指しますが、ここではUML的な意味ではなく、単なる使う使われる関係にあるものを「依存関係」という用語で表しています ↩︎
筆者はボブおじさんがいっているクリーンアーキテクチャは「クリーンなアーキテクチャはかくあるべき！」的なコンセプトをいっているだけで、クリーンアーキテクチャなんていうアーキテクチャは存在しないと思っている派です。ですので、記事の中のクリーンアーキテクチャはドメインが技術詳細から分離・隔離されている「クリーンなアーキテクチャ」の意味で使用しています ↩︎

Modeling Forum 2025参加レポート - AI エージェント時代のシン・モデリングを展望！

2025-12-05T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第5日目の記事です。

はじめに

先月26日 UMTP 主催の Modeling Forum 2025 が開催されました。

https://umtp-japan.org/event-seminar/mf2025/76554

今年は「AI時代のシン・データモデリングとは？」というテーマで多くの講演やパネルディスカッションが行われました。

筆者も当日 Zoom 参加して視聴させていただきました。この記事ではいくつかの講演の内容と感想をお伝えしたいと思います。

Information

Modeling Forum 2025の講演やパネルディスカッションの模様は UMTP の YouTube チャンネルで視聴できます。

Modeling Forum を開催する UMTP (UMLモデリング推進協議会)は、UML モデリング技能認定試験を通したモデリング技術の普及活動、分析力・発想力・想像力強化のための｢モデルベース思考法｣の普及活動を行っています。UMTP は豆蔵の羽生田が会長を務めています。

https://umtp-japan.org/greeting

豆蔵デベロッパーサイトでは UMTP 認定試験の記事も公開していますので、取得を目指す方は参考にしていただければと思います。

/blogs/2023/12/11/umtp_l3_challenge/

開催宣言

UMTP 会長の羽生田さんから「UMTPシン・モデリング宣言」が発表されました。

当日発表された UMTP シン・モデリング宣言：講演資料のスクリーンショットから

これからの時代の基本的なリテラシーは「よみ・かき・AI・モデリング」である。

と宣言し、見える化・仮説検証とアジャイル・AI との対話・モデルベース開発などでモデリングが果たす役割が謳われています。最後にリベラルアーツとしてのモデリングということで、モデリングを基本的なリテラシーとして位置付けています。

基調講演: 科学的思考におけるモデル：説明、創造、そして概念工学へ

東京大学大学院情報学環・学際情報学府の植原亮准教授が基調講演をされました。

講演の YouTube 動画と資料のリンクです。

MM2025-01 基調講演：科学的思考におけるモデル：説明、創造、そして概念工学へ
 MF2025 基調講演資料 - UMTP 特定非営利活動法人UMLモデリング推進協議会

植原先生の著書「科学的思考入門」では、「第5章科学的に説明するとはどういうことか」という章でモデルのことを扱っているそうです^[1]。

科学的思考入門 (講談社現代新書 2765) | 植原亮 |本 | 通販 | Amazon

講演では、科学者が探求する分野としての「狭い意味での科学」と「広い意味での科学(ふだん使いの科学)」を定義し、それぞれにおいて使われるモデルの特徴が解説されました。前者の例としては遺伝子の分子モデルのように、モデルがメカニズムの説明・理解に直結しているもの、後者の例としては鉄道の路線図のように実際には複雑な現実をヒトの頭で扱いやすくするものが挙げられ、いずれも抽象化(abstraction)と理想化(idealization)が二大特徴であることが説明されました。

後半には概念工学の説明がありました。概念工学は、①分析と評価 → ②改訂 →　③社会実装というプロセスで概念を扱うということで、自由意志や創造性などの概念の改訂について説明されていました。

感想：
概念工学というものは初耳学だった。ソフトウェアエンジニアリングのモデルは特定の業務の問題を解くということに特化しているけれども、分析と検証を繰り返し洗練(進化？)させていくところは似てるかも。
久々に大学の教養課程の講義を聴いているような気持ちになった(小並感)。

技術講演 AI readyデータ整備のためのデータモデリング

株式会社データアーキテクト代表取締役真野正さんの講演です。

講演の YouTube 動画は以下にあります。

MF2025-02 技術講演1：AI readyデータ整備のためのデータモデリング

「実践的データモデリング入門」の著者の方です(DB Magazine 懐かしい)。

実践的デ-タモデリング入門 (DB Magazine SELECTION) | 真野正 |本 | 通販 | Amazon

企業のデータを生成 AI に与えて活用する上でデータマネージメントが重要であることを延べ、エンタープライズ・データモデリングをどう進めるかということがテーマの講演でした。
特に企業が使用するデータが、SoR の構造化データだけでなく、非構造データも増えている点、システムをまたがって整合性のあるデータアーキテクチャを構築する必要性とその進め方が解説されていました。
今後の展望としては、AIエージェントがデータアーキテクチャの維持、品質の担保を担い、データマネージメントは AI エージェントによる自律的なプロセスによって運用されるような世界観が提示されていました。

感想：
現実の AI 導入プロジェクトでも、AI にデータを食わせれば素晴らしい結果が得られると期待する人と、その前にデータを整備しないとガベージ・イン・ガベージアウトだよねという冷静派のせめぎ合い。これは、AI じゃなく BI の時も同じことが言われており、今後も重要課題であり続けるんだろうな。そもそもデータが膨大でシステムの数も多いので、AI に整理を手伝ってもらわないと無理だよなあ。

生成AI時代のドメインモデリング ― OOPとFPを超えて

株式会社ウルフチーフ代表取締役川島義隆さんの講演です。

講演の YouTube 動画は以下にあります。

MM2025-03 技術講演2：生成AI時代のドメインモデリング ― OOPとFPを超えて

Information

川島さん Cosense を愛用されているようで、本講演で紹介された話題もまとめられています。

https://scrapbox.io/kawasima/

ドメインモデリングのレベルとして、概念・仕様・実装を区別し、仕様モデルの構成要素を以下のように定義しています。

仕様ドメインモデルは、小路の抽象レベルで記述された業務の

データ

振る舞い

で構成される

そして、Liskov の手続き抽象に基づく仕様記述の書き方が紹介されました。

入力(データ抽象)
出力(データ抽象)
requires: 入力が全域的^[2]でない場合に、その条件を書く
modifies: 書き換えられる入力を書く
effects: 使用される入力についての振る舞いを書く

https://scrapbox.io/kawasima/%E3%83%89%E3%83%A1%E3%82%A4%E3%83%B3%E8%A8%98%E8%BF%B0%E3%83%9F%E3%83%8B%E8%A8%80%E8%AA%9E

そして、仕様モデル駆動設計についてのお話。

アウトサイドイン開発:
業務コアの概念がわからないまま、画面駆動/テーブル駆動で設計・開発する → 配線プログラミングになりがち

インサイドアウト開発:

①仕様モデル書く(人が)
②仕様モデルに沿った Presentation モデル(画面)を書く(AI が)
②仕様モデルに沿った Persistence モデル(DB)を書く(AI が)

https://scrapbox.io/kawasima/%E3%82%BD%E3%83%95%E3%83%88%E3%82%A6%E3%82%A7%E3%82%A2%E3%80%81%E5%A4%96%E3%81%8B%E3%82%89%E4%BD%9C%E3%82%8B%E3%81%8B%3F%E5%86%85%E3%81%8B%E3%82%89%E4%BD%9C%E3%82%8B%E3%81%8B%3F

感想
DbC に似てる。実装言語でよい設計を頑張るのではなく、人は仕様記述に徹して、仕様を AI にレビューしてもらって、AI に実装言語でコードを書いてもらうのは筋がよさそう。実装言語を意識せず仕様を書ける人が強い世界。
仕様記述言語欲しいね。詳細設計書という名の、バグがあっても気づけないドキュメントを延々と書き続けている SIer は今だにいるので、そういうのが駆逐できたらいいなあ。
川島さんの仕様モデル駆動設計の本出たら買おう。

Excelデータ分析で学ぶディメンショナルモデリング～アジャイルデータモデリングへ向けて～

株式会社風音屋代表取締役ゆずたそ（横山翔）さんによる講演です。

講演の YouTube 動画は以下にあります。

MF2025-04 技術講演3：Excelデータ分析で学ぶディメンショナルモデリング～アジャイルデータモデリングへ向けて～

科学専門書) | ローレンス・コル, ジム・スタグニット, 打出紘基, 佐々木江亜, 土川稔生, 濱田大

ディメンショナルモデリングの話でした。ファクトとディメンションをどのように定義するか、業務内容がピボットし続ける時代だからこそ、アジャイルにデータ整備をするの大事というお話をされていました。

さらにデータサイエンティストはお高いが、データ分析は AI エージェントにかなりのアウトプットを期待できるようになっている。信頼できるデータソースを整備すれば、AI エージェントにやらせると安いし早いというお話もされてました。

感想
真野さんのエンタープライズデータモデリングの話にも似てるけど、アジャイルデータモデリングというところが特徴。
データ整備ができれば、データ分析は、AI エージェントにやってもらえばいいというのは分かる。

こんにちは！データモデリング

エークリッパー・インク代表羽生章洋さんの講演です。

講演の YouTube 動画は以下にあります。

MF2025-05 技術講演4：こんにちは！データモデリング

「楽々ERDレッスン」の羽生さんです。新しく要件定義の本を書かれたそうです。

こんにちは！要件定義①【情報活用とデータベース編】 (ビジネス×IT企画) 単行本（ソフトカバー）

AI の登場によって、これまで IT 化の対象にできなかった領域についても低コストでアプリが作れるようになった。人間が上流工程を行うフロントローディングの時代。上流工程・要件定義が一層大事になっている。

IPA のデジタルスキル標準では、データベース設計をすべてのビジネスパーソンが理解すべきリテラシーとして位置付けているそうです。

羽生さんは現在デジタル人材のリテラシー向上支援をされていて、これまで IT の仕事をしてない人が「お前デジタル詳しいだろ、DX 担当な」と任命されて悩む、そういう人が多いそうです。

感想
DX 人材って不足してるんやなあ(棒)。

要件定義の中心にモデルを置きLLMが出力した要件に責任をもつ

株式会社バリューソース代表取締役社長神崎善司さんの講演です。

講演の YouTube 動画は以下にあります。

MF2025-06 技術講演5：要件定義の中心にモデルを置きLLMが出力した要件に責任をもつ

神崎さんは元豆蔵で筆者が入社した頃の上司でした。モデルベースのビジネスとシステムの可視化手法である RDRA を提唱して実践されています。

https://www.rdra.jp/%E3%83%9B%E3%83%BC%E3%83%A0

最近のプロジェクトでは AI エージェントに要件定義は全部任せるように舵を切ったそうです。AI が出力した要件定義を可視化して人間が検証するという段階になっているそうです。

AI にどうやって適切なコンテキストを用意し、AI の出力をいかに理解し軌道修正するかということが課題になっているとのことでした。

要件の可視化ツールとして RDRA Graph を使用して説明しておられました。

RDRA - RDRAGraphツール

感想
神崎さん AI エージェント使いこなしてるなあ。
RDRA のビューアの動きが面白くて、内容が入ってこない。

さいごに

この後の講演やパネルディスカッションは離脱してしまい聴けませんでしたが^[3]、視聴したどの講演も興味深く、AI エージェント時代を迎えてモデリングの重要性はさらに高くなっていることを確信できる内容でした。個人的には川島さんの講演がヒットでした。

Vibe Coding などの AI エージェントとの協調作業においては言語運用能力の重要性は認知されていると思いますが、AI とモデルを共有することで、AI の出力の質が高くなったり、認識齟齬が減ったりするのであればモデリングに取り組む価値はあるのではないでしょうか。

仕様駆動開発という言葉は出てきてますが、モデルベース仕様駆動開発の時代が来るのかもしれません。

本書は、「ふだん使い」の科学を身につけようというコンセプトの一般向け実用書に擬態した科学哲学の入門書とのことです。 ↩︎
全域性：取りうる入力の全てに対して対応する出力が存在する(ふるまいが関数として定義できる) ↩︎
パネルディスカッションの YouTube 動画もこちらに公開されています。 ↩︎

スクラムマスターのAI活用を考える - 導入

2025-12-04T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第4日目の記事です。

はじめに

アジャイルグループの石田です。

近年、生成AIの進化は目覚ましく、私たちの働き方を大きく変えようとしています。豆蔵デベロッパーサイトでも、設計、実装、テストといったシステム開発の各工程で生成AIを活用する記事が豊富に投稿されています。（ご興味があれば #生成AI や #AIエージェントのタグもご覧ください）。

一方で、スクラムマスターとしてスクラムのプロセス自体にAIをどう活用するか、というテーマはまだ発展途上で、具体的な実践例も多くはありません。

そこで本連載では、全3回にわたり、スクラムマスターがAIとどう向き合い、チームを支援できるかのヒントを、私自身の実践を交えながら探っていきます。

連載の構成は以下の通りです。

第1回：導入（本記事）
第2回：透明性
第3回：検査・適応

第1回となる本記事では、スクラムガイド拡張パックで言及されている「人工知能」の考え方をベースに、スクラムにおけるAI活用の全体像と基本的な考え方をご紹介します。

スクラムガイド拡張パックとAI

スクラムガイド拡張パックは、2020年版スクラムガイドの包括的な副読本として作成され、2025年6月に公開された文書です。有志により日本語化もされています。

この拡張パックでは、変化し続ける市場や技術に対応するため、人工知能（AI）が「拡張パックにおけるスクラムの役割」のひとつとして定義されています。これは、AIが単なる技術トレンドではなく、スクラムの実践を強化する重要な要素として認識されていることを示しています。

AIがスクラムを強化する可能性については、下記のように紹介されています。

AIは以下を通じてスクラムを強化する可能性がある：

経験的プロセス制御：AI駆動の分析により、透明性・検査・適応が改善される。

認知的拡張：AIにより、人間のスクラムチームメンバーは戦略的・創造的・倫理的な検討に集中できる。

継続的な価値適応：AIは、リアルタイムのユーザーフィードバックとトレンドに基づき、プロダクトバックログアイテムの更新と再優先順位付けを行うことができる。

システム洞察：AIは隠れた相互依存関係を特定し、データに基づいた意思決定を改善する。

この連載では、特にスクラムマスターの役割と深く関わる一つ目の項目に焦点を当てます。

経験的プロセス制御：AI駆動の分析により、透明性・検査・適応が改善される。
（原文：Empirical Process Control: AI-driven analytics improve transparency, inspection, and adaptation.）

スクラムマスターの重要な責務は、チームがスクラムの三本柱である「透明性・検査・適応」を実践できるよう支援することです。AIは、この経験的プロセス制御を、これまでになかったレベルで強化する可能性を秘めています。

まとめと次回予告

スクラムガイド拡張パックの役割の中の「スクラムマスター」には、下記のユニークな一文が記載されています。

スクラムマスターは人間でなければならない。
(原文：The Scrum Master must be human.)

これは、チームとの協働や複雑な人間関係の調整といった、人間にしか果たせない役割の重要性を示唆しています。AIはあくまでスクラムマスターの能力を拡張する「強力なパートナー」であり、私たち人間はより本質的な課題に集中できるようになります。

スクラムガイドの精神を元にスクラムに関するアドバイスをAIスクラムマスターからもらうことはできるかもしれませんが、決してスクラムマスターの仕事を代替するものではなく、その役割を強化し、チームの能力を最大限に引き出すためのパートナーである必要があります。

本記事では、AIをスクラムに「導入」するための第一歩として、その全体像と可能性を提示しました。

次回は、スクラムの三本柱の一つである「透明性」をテーマに、AIという新たな武器をどう活用し、プロジェクトの「見える化」を行うか、具体的な実践例を交えて探ります。

【Agent Skills】「あの雰囲気」を VSCode に。Markdown プレビューを Anthropic テーマにしたいんだ！ - brand-guidelines 完全ガイド -

2025-12-03T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第 3 日目の記事です！

はじめに

Anthropicの公式ページをみたことがありますか？

https://www.anthropic.com/

配色の雰囲気が美しくて大変好きです。

さらに、最近 Claude Code とペアプログラミングをすることが多くなり、マークダウンファイルをプレビュー表示することが非常に多くなりました。要件定義やADR、技術記事の執筆などなど。

せっかく高頻度でマークダウンファイルを扱うなら、ぼくの好きなスタイルでプレビューさせたいものです。Anthropic の公式ページのような、読みやすく美しいプレビュー環境を構築できれば、執筆作業もより快適になるはず！

しかし、一から自分でスタイリングを考えるのは非常に大変。。。
カラーパレット、タイポグラフィ、コンポーネントスタイルなど、考えるべき要素が多く、時間もかかります。

そんな折、Anthropic から Agent Skills という機能がリリースされました。

Agent Skills は、Claude の機能を拡張するための仕組みで、Claude に特定の作業を行う「スキル（技能）」を与えるためのツールセットです。

さらに、Anthropic が提供している公式の skills brand-guidelines なら、Anthropic のテーマを基盤に色々なスタイリングをしてくれるとのこと。これなら、自分で一から考える必要がなく、公式の洗練されたデザインを簡単に活用できるのではないかと考えました。

この記事では、Claude の Agent Skills を活用して、Markdown Preview Enhanced 拡張機能に Anthropic のブランドガイドラインを適用する方法を解説します。

この記事のゴール

この記事を読むことで、以下のことができるようになります。

Claude の Agent Skills について理解できる
- Agent Skills とは何か、どのように有効化して使うのかがわかります
brand-guidelines スキルの使い方がわかる
- Anthropic のブランドガイドラインを基盤に、色々なスタイリングをしてくれるスキルです
Markdown Preview Enhanced との連携方法がわかる
- VSCode の拡張機能と Anthropic のブランドガイドラインを組み合わせる手順を理解できます

スタイル適用前

スタイル適用前のプレビュー表示例は以下のとおりです。

スタイル適用前のプレビュー表示例

スタイル適用後

スタイル適用後のプレビュー表示例は以下のとおりです。

スタイル適用後のプレビュー表示例

前提条件

この記事では、以下の環境を前提としています。

使用環境

OS: MacOS, Windows 11
VSCode: 最新版（執筆時点: 1.106.2 ）
Claude アカウント: claude.ai にアクセス可能

必要な基礎知識

VSCode の基本的な操作方法（ファイルの開き方、設定の変更方法など）
claude.ai の基本的な使い方（チャット機能の利用経験）
Markdown の基礎知識（見出し、リスト、コードブロックなど）

実施手順詳細

0. 実施手順で使用する主要な概念

Agent Skills とは

Agent Skills は、Claude の機能を拡張するための仕組みで、Claude に特定の作業を行う「スキル（技能）」を与えるためのツールセットです。この手順では、brand-guidelines スキルを使用するために Agent Skills を有効化する必要があります。Agent Skills は実験的な機能で、Pro プラン以上のユーザーが利用できます。

利用可能な公式スキル

Anthropic が提供している公式スキルには、以下のようなものがあります：
最新のスキル一覧は Anthropic の公式スキルリポジトリで確認できます。

✅ドキュメント系スキル

スキル名	説明
docx	Word 文書の作成・編集（変更履歴、書式設定対応）
pdf	PDF の操作（抽出、作成、結合、フォーム処理）
pptx	PowerPoint プレゼンテーションの作成（レイアウト、テンプレート、チャート対応）
xlsx	Excel スプレッドシートの作成（数式、書式設定、データ分析）

✅クリエイティブ・デザイン系スキル

スキル名	説明
brand-guidelines	Anthropic の公式ブランドカラーと Typography をアーティファクトに適用（この記事で使用）
theme-factory	10種類のプリセットテーマまたはカスタムテーマでアーティファクトをスタイリング
canvas-design	デザイン哲学を使用した .png / .pdf 形式のビジュアルアート作成
algorithmic-art	p5.js を使用したジェネラティブアート作成（シード付きランダム、フローフィールド、パーティクルシステム）
slack-gif-creator	Slack のサイズ制限に最適化されたアニメーション GIF 作成

✅開発・技術系スキル

スキル名	説明
artifacts-builder	React、Tailwind CSS、shadcn/ui を使用した複雑な HTML アーティファクト構築
mcp-builder	外部 API やサービスを統合する高品質な MCP サーバー作成ガイド
webapp-testing	Playwright を使用したローカル Web アプリケーションのテスト

✅エンタープライズ・コミュニケーション系スキル

スキル名	説明
internal-comms	ステータスレポート、ニュースレター、FAQ などの社内コミュニケーション文書作成

✅メタスキル（スキル作成用）

スキル名	説明
skill-creator	Claude の機能を拡張する効果的なスキル作成ガイド
template-skill	新しいスキル作成の出発点となる基本テンプレート

スキルの呼び出し方法

Agent Skills を呼び出すには、チャットにて自然言語でスキル名を指定して依頼します：

# 基本的な呼び出し方
brand-guidelines スキルを使って、○○を作成してください

# スキル名を明示的に指定
skill: brand-guidelines を使用して、CSS ファイルを生成してください

Claude がスキルを認識すると、必要な処理を自動的に実行してくれます。

brand-guidelines スキルとは

brand-guidelines スキルは、Anthropic の公式テーマファイルを生成するための Agent Skills です。このスキルを使用することで、Anthropic の公式 UI で使用されているカラーパレットや Typography を含む CSS ファイルを生成できます。

生成される CSS ファイルの内容

生成される CSS ファイルには、以下のような要素が含まれています：

カラーパレット: プライマリカラー、背景色、テキスト色など
Typography: フォントファミリー、サイズ、行間など
コンポーネントスタイル: ボタン、リンク、コードブロックなど
ダークモード対応: Light テーマと Dark テーマの両方に対応

Markdown Preview Enhanced とは

Markdown Preview Enhanced は、VSCode の拡張機能です。
VSCode には標準で Markdown プレビュー機能が搭載されていますが、この拡張機能を使用する理由は以下の通りです：

カスタム CSS の適用が容易: 独自の CSS ファイルを簡単に読み込めます
豊富な機能: 数式、図表、目次など、標準プレビューにない機能が多数あります
高いカスタマイズ性: 細かい設定変更が可能です

カスタムスタイル適用に関連する機能として、以下の特徴があります：

style.less の編集: 拡張機能専用のスタイルファイルを持っており、そこから外部 CSS を読み込めます
リアルタイムプレビュー: スタイルの変更が即座に反映されます
複数のプレビューモード: さまざまな形式でのエクスポートにも対応しています

この手順では、brand-guidelines スキルで生成した CSS ファイルを、Markdown Preview Enhanced の style.less ファイルから読み込むことで、Anthropic の公式テーマを適用します。

1. Agent Skills の有効化

https://support.claude.com/ja/articles/12512180-claude%E3%81%A7%E3%82%B9%E3%82%AD%E3%83%AB%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%99%E3%82%8B

claude.ai にアクセス

Claude の新規チャット画面
設定画面を開く
機能 > コード実行とファイル作成 を有効化
同画面にて、利用するスキル(brand-guidelines)を有効化
有効化の確認

claude.ai のチャット画面にて、利用可能なスキルを質問してみましょう。

2. Markdown Preview Enhanced 拡張機能のインストール

VSCode の拡張機能マーケットプレイスから、Markdown Preview Enhanced をインストールします。

https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced

3. brand-guidelines スキルによるスタイル作成

claude.ai のチャット画面にて、brand-guidelines スキルを使用して、CSS ファイルを生成するよう依頼します。

プロンプトは適当ですが、例えば以下の内容で依頼してみました。

vscodeでmarkdownファイルをプレビューした際のスタイルにanthropicの公式テーマを適用したい。
プレビューにはmarkdown preview enhanced 拡張機能を利用する想定。
カスタムcssファイルを生成してほしい。

出力結果は以下のとおりです。

4. 生成されたスタイルの確認

今回生成された CSS ファイルは以下のとおりです。

anthropic-markdown-preview.css

/*
 * Anthropic Brand Theme for Markdown Preview Enhanced
 * VS Code Extension Custom CSS
 * 
 * Installation:
 * 1. Open VS Code Settings (Cmd/Ctrl + ,)
 * 2. Search for "Markdown Preview Enhanced: Style"
 * 3. Add the path to this file, or
 * 4. Copy this content to ~/.mume/style.less (or style.css)
 */

/* ============================================
   Import Google Fonts
   ============================================ */
@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&family=Lora:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500&display=swap');

/* ============================================
   CSS Variables - Anthropic Brand Colors
   ============================================ */
:root {
  /* Main Colors */
  --anthropic-dark: #141413;
  --anthropic-light: #faf9f5;
  --anthropic-mid-gray: #b0aea5;
  --anthropic-light-gray: #e8e6dc;
  
  /* Accent Colors */
  --anthropic-orange: #d97757;
  --anthropic-blue: #6a9bcc;
  --anthropic-green: #788c5d;
  
  /* Typography */
  --font-heading: 'Poppins', Arial, sans-serif;
  --font-body: 'Lora', Georgia, serif;
  --font-code: 'JetBrains Mono', 'Fira Code', 'SF Mono', Consolas, monospace;
}

/* ============================================
   Base Styles
   ============================================ */
.markdown-preview.markdown-preview {
  font-family: var(--font-body);
  font-size: 16px;
  line-height: 1.7;
  color: var(--anthropic-dark);
  background-color: var(--anthropic-light);
  padding: 2rem 3rem;
  max-width: 900px;
  margin: 0 auto;
}

/* ============================================
   Headings - Poppins Font
   ============================================ */
.markdown-preview h1,
.markdown-preview h2,
.markdown-preview h3,
.markdown-preview h4,
.markdown-preview h5,
.markdown-preview h6 {
  font-family: var(--font-heading);
  font-weight: 600;
  color: var(--anthropic-dark);
  margin-top: 1.5em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

.markdown-preview h1 {
  font-size: 2.25rem;
  font-weight: 700;
  border-bottom: 3px solid var(--anthropic-orange);
  padding-bottom: 0.4em;
  margin-top: 0;
}

.markdown-preview h2 {
  font-size: 1.75rem;
  border-bottom: 2px solid var(--anthropic-light-gray);
  padding-bottom: 0.3em;
}

.markdown-preview h3 {
  font-size: 1.4rem;
  color: var(--anthropic-dark);
}

.markdown-preview h4 {
  font-size: 1.2rem;
  color: var(--anthropic-mid-gray);
}

.markdown-preview h5,
.markdown-preview h6 {
  font-size: 1rem;
  color: var(--anthropic-mid-gray);
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

/* ============================================
   Paragraphs and Body Text
   ============================================ */
.markdown-preview p {
  margin: 1em 0;
  text-align: justify;
  hyphens: auto;
}

/* ============================================
   Links
   ============================================ */
.markdown-preview a {
  color: var(--anthropic-orange);
  text-decoration: none;
  border-bottom: 1px solid transparent;
  transition: border-color 0.2s ease, color 0.2s ease;
}

.markdown-preview a:hover {
  color: var(--anthropic-blue);
  border-bottom-color: var(--anthropic-blue);
}

.markdown-preview a:visited {
  color: var(--anthropic-green);
}

/* ============================================
   Lists
   ============================================ */
.markdown-preview ul,
.markdown-preview ol {
  margin: 1em 0;
  padding-left: 1.5em;
}

.markdown-preview li {
  margin: 0.4em 0;
  line-height: 1.6;
}

.markdown-preview ul li::marker {
  color: var(--anthropic-orange);
}

.markdown-preview ol li::marker {
  color: var(--anthropic-blue);
  font-weight: 600;
}

/* Nested lists */
.markdown-preview ul ul,
.markdown-preview ol ol,
.markdown-preview ul ol,
.markdown-preview ol ul {
  margin: 0.3em 0;
}

/* Task lists */
.markdown-preview input[type="checkbox"] {
  accent-color: var(--anthropic-orange);
  margin-right: 0.5em;
}

/* ============================================
   Blockquotes
   ============================================ */
.markdown-preview blockquote {
  margin: 1.5em 0;
  padding: 1em 1.5em;
  border-left: 4px solid var(--anthropic-orange);
  background-color: var(--anthropic-light-gray);
  color: var(--anthropic-dark);
  font-style: italic;
  border-radius: 0 8px 8px 0;
}

.markdown-preview blockquote p {
  margin: 0.5em 0;
}

.markdown-preview blockquote p:first-child {
  margin-top: 0;
}

.markdown-preview blockquote p:last-child {
  margin-bottom: 0;
}

/* Nested blockquotes */
.markdown-preview blockquote blockquote {
  border-left-color: var(--anthropic-blue);
  margin: 1em 0;
}

/* ============================================
   Code - Inline and Blocks
   ============================================ */
.markdown-preview code {
  font-family: var(--font-code);
  font-size: 0.9em;
}

/* Inline code */
.markdown-preview :not(pre) > code {
  background-color: var(--anthropic-light-gray);
  color: var(--anthropic-dark);
  padding: 0.2em 0.4em;
  border-radius: 4px;
  border: 1px solid var(--anthropic-mid-gray);
}

/* Code blocks */
.markdown-preview pre {
  background-color: var(--anthropic-dark);
  color: var(--anthropic-light);
  padding: 1.25em 1.5em;
  border-radius: 8px;
  overflow-x: auto;
  margin: 1.5em 0;
  border: 1px solid var(--anthropic-mid-gray);
}

.markdown-preview pre code {
  background: none;
  border: none;
  padding: 0;
  color: inherit;
  font-size: 0.875em;
  line-height: 1.6;
}

/* ============================================
   Syntax Highlighting (Custom Theme)
   ============================================ */
.markdown-preview pre .hljs-keyword,
.markdown-preview pre .hljs-selector-tag,
.markdown-preview pre .hljs-built_in {
  color: var(--anthropic-orange);
}

.markdown-preview pre .hljs-string,
.markdown-preview pre .hljs-attr {
  color: var(--anthropic-green);
}

.markdown-preview pre .hljs-number,
.markdown-preview pre .hljs-literal {
  color: var(--anthropic-blue);
}

.markdown-preview pre .hljs-comment {
  color: var(--anthropic-mid-gray);
  font-style: italic;
}

.markdown-preview pre .hljs-function,
.markdown-preview pre .hljs-title {
  color: var(--anthropic-blue);
}

.markdown-preview pre .hljs-variable,
.markdown-preview pre .hljs-params {
  color: var(--anthropic-light);
}

.markdown-preview pre .hljs-type,
.markdown-preview pre .hljs-class {
  color: var(--anthropic-orange);
}

/* ============================================
   Tables
   ============================================ */
.markdown-preview table {
  width: 100%;
  border-collapse: collapse;
  margin: 1.5em 0;
  font-size: 0.95em;
}

.markdown-preview table th,
.markdown-preview table td {
  padding: 0.75em 1em;
  text-align: left;
  border: 1px solid var(--anthropic-light-gray);
}

.markdown-preview table th {
  font-family: var(--font-heading);
  font-weight: 600;
  background-color: var(--anthropic-dark);
  color: var(--anthropic-light);
  border-color: var(--anthropic-dark);
}

.markdown-preview table tr:nth-child(even) {
  background-color: var(--anthropic-light-gray);
}

.markdown-preview table tr:hover {
  background-color: rgba(217, 119, 87, 0.1);
}

/* ============================================
   Horizontal Rules
   ============================================ */
.markdown-preview hr {
  border: none;
  height: 2px;
  background: linear-gradient(
    90deg,
    var(--anthropic-orange),
    var(--anthropic-blue),
    var(--anthropic-green)
  );
  margin: 2em 0;
  border-radius: 1px;
}

/* ============================================
   Images
   ============================================ */
.markdown-preview img {
  max-width: 100%;
  height: auto;
  border-radius: 8px;
  margin: 1em 0;
  box-shadow: 0 4px 12px rgba(20, 20, 19, 0.1);
}

/* ============================================
   Footnotes
   ============================================ */
.markdown-preview .footnotes {
  margin-top: 3em;
  padding-top: 1.5em;
  border-top: 2px solid var(--anthropic-light-gray);
  font-size: 0.9em;
  color: var(--anthropic-mid-gray);
}

.markdown-preview .footnote-ref {
  color: var(--anthropic-orange);
  font-weight: 600;
}

/* ============================================
   Definition Lists
   ============================================ */
.markdown-preview dl {
  margin: 1em 0;
}

.markdown-preview dt {
  font-family: var(--font-heading);
  font-weight: 600;
  color: var(--anthropic-dark);
  margin-top: 1em;
}

.markdown-preview dd {
  margin-left: 1.5em;
  color: var(--anthropic-mid-gray);
}

/* ============================================
   Keyboard Keys
   ============================================ */
.markdown-preview kbd {
  font-family: var(--font-code);
  font-size: 0.85em;
  padding: 0.2em 0.5em;
  background-color: var(--anthropic-light-gray);
  border: 1px solid var(--anthropic-mid-gray);
  border-radius: 4px;
  box-shadow: 0 2px 0 var(--anthropic-mid-gray);
}

/* ============================================
   Mark / Highlight
   ============================================ */
.markdown-preview mark {
  background-color: rgba(217, 119, 87, 0.3);
  color: var(--anthropic-dark);
  padding: 0.1em 0.3em;
  border-radius: 2px;
}

/* ============================================
   Abbreviations
   ============================================ */
.markdown-preview abbr {
  text-decoration: underline dotted var(--anthropic-blue);
  cursor: help;
}

/* ============================================
   Selection
   ============================================ */
.markdown-preview ::selection {
  background-color: rgba(106, 155, 204, 0.3);
  color: var(--anthropic-dark);
}

/* ============================================
   Scrollbar Styling
   ============================================ */
.markdown-preview ::-webkit-scrollbar {
  width: 8px;
  height: 8px;
}

.markdown-preview ::-webkit-scrollbar-track {
  background: var(--anthropic-light-gray);
  border-radius: 4px;
}

.markdown-preview ::-webkit-scrollbar-thumb {
  background: var(--anthropic-mid-gray);
  border-radius: 4px;
}

.markdown-preview ::-webkit-scrollbar-thumb:hover {
  background: var(--anthropic-orange);
}

/* ============================================
   Print Styles
   ============================================ */
@media print {
  .markdown-preview.markdown-preview {
    background-color: white;
    color: black;
    padding: 0;
  }
  
  .markdown-preview a {
    color: var(--anthropic-dark);
    text-decoration: underline;
  }
  
  .markdown-preview pre {
    border: 1px solid var(--anthropic-mid-gray);
    background-color: var(--anthropic-light-gray);
    color: var(--anthropic-dark);
  }
}

/* ============================================
   Mermaid Diagrams
   ============================================ */
.markdown-preview .mermaid {
  background-color: var(--anthropic-light);
  padding: 1em;
  border-radius: 8px;
  text-align: center;
}

/* ============================================
   Math (KaTeX/MathJax)
   ============================================ */
.markdown-preview .katex,
.markdown-preview .MathJax {
  font-size: 1.1em;
}

.markdown-preview .katex-display,
.markdown-preview .MathJax_Display {
  margin: 1.5em 0;
  padding: 1em;
  background-color: var(--anthropic-light-gray);
  border-radius: 8px;
  overflow-x: auto;
}

/* ============================================
   Admonitions / Callouts
   ============================================ */
.markdown-preview .admonition,
.markdown-preview .callout {
  margin: 1.5em 0;
  padding: 1em 1.5em;
  border-radius: 8px;
  border-left: 4px solid;
}

.markdown-preview .admonition.note,
.markdown-preview .callout.note {
  background-color: rgba(106, 155, 204, 0.1);
  border-left-color: var(--anthropic-blue);
}

.markdown-preview .admonition.warning,
.markdown-preview .callout.warning {
  background-color: rgba(217, 119, 87, 0.1);
  border-left-color: var(--anthropic-orange);
}

.markdown-preview .admonition.tip,
.markdown-preview .callout.tip {
  background-color: rgba(120, 140, 93, 0.1);
  border-left-color: var(--anthropic-green);
}

/* ============================================
   TOC (Table of Contents)
   ============================================ */
.markdown-preview .md-toc {
  background-color: var(--anthropic-light-gray);
  padding: 1.5em;
  border-radius: 8px;
  margin: 1.5em 0;
}

.markdown-preview .md-toc-content {
  font-family: var(--font-heading);
}

.markdown-preview .md-toc a {
  color: var(--anthropic-dark);
}

.markdown-preview .md-toc a:hover {
  color: var(--anthropic-orange);
}

5. Markdown Preview Enhanced への適用

コマンドパレットにて、Markdown Preview Enhanced: Customize CSS (Global) を実行
表示された style.less ファイルに、生成された CSS ファイルの内容を追記し保存

6. 動作確認と微調整

プレビューに適用されたスタイルを確認して、気になる点があれば微調整します。
スタイルの微調整は、style.less ファイルを直接編集することで実施可能です。
あるいは、claude.ai のチャット画面にて、style.less ファイルの内容を変更するよう依頼もできます。

ぼくはフォントを少し変更しました。

Information

Markdown Preview Enhanced には、拡張機能の設定画面からプレビューテーマを指定する機能があります（Markdown Preview Enhanced: Preview Theme / Markdown-preview-enhanced: Code Block Theme 設定）。この設定と style.less の内容が競合すると、意図したスタイルが適用されない場合があります。

もしスタイルが思い通りに反映されない場合は、これらの設定を変更してみてください。

まとめ

この記事では、Claude の Agent Skills を活用して、Markdown プレビューに Anthropic のスタイルを適用する方法を解説しました。

実現できたこと

今回の設定により、以下のことが実現できました：

Agent Skills の理解: Claude の Agent Skills を有効化し、使いこなす方法を学びました
brand-guidelines スキルの活用: 公式スタイルの CSS ファイルを簡単に生成できるようになりました
統一された執筆環境: Anthropic の公式スタイルを適用したプレビュー環境を構築しました

さらなる発展：カスタムスキルの作成

この記事では公式の brand-guidelines スキルを使用しましたが、別の公式スキル skill-creator を使えば、自分だけのオリジナルスキルを作成することもできます。

例えば、以下のようなカスタムスキルを作成できます：

自社のブランドガイドラインに基づいた CSS 生成スキル
特定のフレームワーク向けのコンポーネント生成スキル
プロジェクト固有のドキュメントテンプレート生成スキル

skill-creator スキルの使い方は、claude.ai のチャットで以下のように依頼するだけです。

skill-creator スキルを使って、○○を行うカスタムスキルを作成してください

詳細は Anthropic の公式スキルリポジトリを参照してください。公式の skill-creator や template-skill を参考にすることで、効果的なスキルを作成できます。

なお、skill-creator を利用する場合は、brand-guidelines スキルを有効化したように、skill-creator スキルを有効化することをお忘れなく！

最後までお読みいただき、ありがとうございました。この記事が、あなたの執筆環境をより快適にする助けになれば幸いです。🎨✨

変化の波を乗り越えろ！予測不能な時代を生き抜く「考え直す力」とは - 書籍「Think Again」

2025-12-02T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第 2 日目の記事です！

はじめに

書籍 Think Again

僕がとても好きな書籍です。

この書籍では、考え直すことの重要性について書かれています。

本書の目次を以下に示しました。

Part1: 自分の考えを再考する方法
Part2: 相手に再考を促す方法
Part3: 学び、再考し続ける社会・組織を創造する方法
Part4: 結論

再考することの重要性を、Part1では自己に、Part2では他者に、Part3ではチーム・組織に焦点を当てて説明されています。

この記事では、Part1でとても印象的な下記内容について紹介したいです。

再考サイクルとは何か？
対比となる過信サイクルとは何か？
再考サイクルを継続するために必要なことは何か？

「化石化した知識」を後生大事にしていないか？

情報技術の進歩に伴い、人の知識もどんどん増加しています。
本書によると、

1950 年を見てみると、医療の知識は 1900 年から 50 年の歳月をかけて倍増した。
それが 1980 年までには 7 年ごとのペースで、そして 2010 年までにはその半分の歳月で倍増するようになった。

とのこと。

従って、社会の変化に伴い、私たちは今まで当たり前と思っていたことをより頻繁に再考する必要があリます。
だけどなかなかそれができない。。

牧師、検察官、政治家 - 誰もが持つ 3 つの思考モード

なぜ自分の知識や見解を再考できないのか。

それは、無意識に切り替わる以下 3 つの思考モードが原因とのこと。

牧師モード:
- 自分の信念がぐらついている時、理想を守り確固としたものにするため、他者を説教しようとする。
検察官モード:
- 他者の推論に矛盾を感じれば、相手の間違いを明らかにするため論拠を探す。
政治家モード:
- 多くの人を味方につけたい時は、支持層の是認を獲得するためにキャンペーンやロビー活動を行う

そして、これらの思考モードは互いに循環してしまいます。
具体的なシチュエーションを考えると、こんな感じでしょうか 👇

シチュエーション
SNS 経由で知り合った「投資アドバイザー」から勧められた暗号資産投資。
「いま始めれば月利 20 %、限定枠あり」と言われ、初期資金を投入した男性。

月利 20 % はヤバいですね。。相場を逸脱しています。。

牧師モード

自尊心が確信を生む

これは自分が見つけた正しい投資法だ。
自分の考えが正しいことをちゃんと説明すれば、みんなも納得するはず。

真実はすでに見つかっていると考える。
いかに正しいかを証明するために、他者を説得しようとする。

検察官モード

確信がバイアスを生む

仕組みを理解していない周りが間違っている。
現にこんなに利益が出ている。

相手の指摘を"無知"や"矛盾"として否定する。
自分の考えを肯定する情報しか見えなくなる。

政治家モード

バイアスが是認を生む

みんながやっているから、間違いない。
反対している人は、仕組みを理解していない無知な人たちだ。

同じ考えの人たちに囲まれて安心する。
反対意見は"無知な人の意見"として無視する。

本書では、この循環を過信サイクルと呼んでいます。
過信サイクルは、以下に没頭するあまり自分の見解が間違っているかもしれないと再考しなくなってしまう点で危険です。

自分の信念を貫くこと
他者の間違いを指摘すること
多くの支持を獲得すること

仮説、実験、結果、検証 - 科学者の思考モード

では、暗号資産投資で過信サイクルに陥った男性は、どのように考えれば良かったのか。

例えば、

月利 20 % の根拠は何かと考えるべきだった。
暗号資産投資に関するより多くの見解を集めるべきだった。
多額の資金を投じる前に、少額で実験してみるべきだった。

などでしょうか。

抽象化すると、科学者の思考モードが必要だったということです。
科学者の思考モードは、以下の 4 つの要素で構成されています。

仮説:
- 自分の考えを言語化する。
  例: 暗号資産投資は、月利 20 % の利益を生む。
実験:
- 自分の考えを実験する。
  例: 少額で投資してみる。
結果:
- 実験から得られた結果を観察する。
  例: 投資額と利益額を記録する。
検証:
- 結果をもとに仮説を検証する。
  例: 月利 20 % の根拠は何か？他の投資法と比較してどうか？

この 4 つの要素を繰り返すことができれば、過信サイクルから抜け出して、
自分の考えを再考できるようになるはずです。

再考プロセスの循環 - 再考サイクル

科学者の思考モードによる再考プロセスにも、過信サイクルと同じような循環があるそうです。
本書ではこの循環を再考サイクルと呼び、以下の 4 つの要素で整理しています。

謙虚さ:
- 知的に謙虚である。
- 無知を自覚する。
懐疑:
- 自分の考えに疑問を持つ。
- 「本当にこれで良いのか？」と問い直す。
好奇心:
- 自分が持たない情報を知りたいと思う。
- 見えなかった視点や情報にワクワクする。
発見:
- 疑問の先に、新しい視点や情報を手にする。
- 自分の想定より世界が広かったことを知る。

発見により「学ぶべきこと、発見すべきことはまだたくさんある」と自覚することで、
謙虚さを保つことができるようになります。

Information

人が再考しない理由

これまでのやり方と異なる
そんなのできっこない
自分の経験と異なる
複雑すぎて考えたくない

過信サイクル vs 再考サイクル

過信サイクルと再考サイクルは、以下のように対比されます。

過信サイクル
- 自尊心 → 確信 → バイアス → 是認

graph LR
    A[**自尊心**<br>自分の考えこそが<br>正しい]
    B[**確信**<br>疑う余地はないと<br>思い込む]
    C[**バイアス**<br>都合の良い情報しか<br>見えなくなる]
    D[**是認**<br>賛同してくれる人だけを<br>信じる]
    A --> B
    B --> C
    C --> D
    D --> A

    style A fill:#fdf5e6,stroke:#d2691e,stroke-width:2px
    style B fill:#f0f8ff,stroke:#4682b4,stroke-width:2px
    style C fill:#e6ffe6,stroke:#2e8b57,stroke-width:2px
    style D fill:#f5f5ff,stroke:#6a5acd,stroke-width:2px

再考サイクル
- 謙虚さ → 懐疑 → 好奇心 → 発見

graph LR
    A[**謙虚さ**<br>自分の無知を認める]
    B[**懐疑**<br>今の見解に疑問を持つ]
    C[**好奇心**<br>もっと知りたいという衝動]
    D[**発見**<br>新しい視点に気づく]
    A --> B
    B --> C
    C --> D
    D --> A

    style A fill:#fdf5e6,stroke:#d2691e,stroke-width:2px
    style B fill:#f0f8ff,stroke:#4682b4,stroke-width:2px
    style C fill:#e6ffe6,stroke:#2e8b57,stroke-width:2px
    style D fill:#f5f5ff,stroke:#6a5acd,stroke-width:2px

また、同じ状況に対しても、自分がどちらのサイクルにいるかで思考や行動が変わります。

	過信サイクル	再考サイクル
自分の考えを変える	心の弱わさの表れ	知的誠実さの表れ
他者に説得される	負けた気になる	真実に 1 歩近づいた
考えを変える根拠	他人の反応	理性や証拠

再考サイクルを継続するために必要なこと - 自信に満ちた謙虚さ

過信サイクルに陥らず、再考サイクルを継続するためにはどうすれば良いか。
本書では、バランスの取れた自信と謙虚さが重要だと述べられています。

自信
- 自己信頼度
  自分をどのくらい信頼しているか
  注意 ! 自分のやり方をどれほど確信しているかではない
謙虚さ
- しっかりした知識や能力、つまり自分の過ちや不確実さを認識する力
  注意 ! 自信を控えめに持つことではない

ここで重要なのは、自信と謙虚さは両立するということです。

自信を持つことは、謙虚さを失うこと
謙虚さを持つことは、自信を失うこと

ではありません。

将来の目標に達するのに十分な能力が備わっていると自信を持ちながら、
そのための正しい手段は何かと現在の自分に問う謙虚さを持つことは可能です。

つまり、自己の能力を信じながら、自分の解決方法が正しくない可能性、問題自体を誤解している可能性を認める。
そこから疑問が生じれば、既存の知識を再評価するようになり、ほどほどの自信があれば、新しい知識を追い求めることができるようになります。

自分の知識に対してではなく、自分の学ぶ能力を強く信じている状態

この状態が、自信に満ちた謙虚さを持った状態です。

おわりに - ソフトウェアエンジニアとしての知識と再考サイクル

ソフトウェアエンジニアは、自分の知識を武器にする職業だと思います。技術的な判断や設計の選択において、これまでに培ってきた知識や経験が意思決定の基盤となります。

Electron アプリを Tauri 2.0に移植する PoC をやってみた

2025-12-01T00:00:00.000+00:00

これは豆蔵デベロッパーサイトアドベントカレンダー2025第1日目の記事です。

はじめに

昨年9月に Tauri 2.0 の RC を触って記事を書いていました。

/blogs/2024/09/22/try-tauri-v2-rc/

当時も2年ぶりぐらいに Tauri を触ったのですが、この時からまた1年以上が経ってしまいました。月日が経つの早いですね。

Tauri 2.0 は昨年10月に正式リリースされ、現在のバージョンは 2.9.3 です。そろそろ熟成されてきた頃ではないかと考え、Electron から移植してみる PoC を思いついた次第です。

移植するアプリ

これまでは、ちょっとした SPA 的なアプリを動かす程度のことしかやってこなかったので、もう少し実用的なアプリで試そうと思いました。
例によって拙作の Electron 製の野良 Cosense(Scrapbox) アプリを題材にさせていただきます。

https://github.com/kondoumh/sbe

sbe の操作イメージのスクリーンショットです。タブ UI が特徴で、Cosense のページをタブで開いて表示・編集できるのと、独自の管理画面やプロジェクトのページ一覧などの UI も利用可能です。

移植といっても長年メンテしているアプリなので意外とコードベースも大きく機能も多いのでピンポイントでフィーチャーを実装してみて Electron との違いを噛み締めてみるという試みです。

今回の PoC での移植結果の出来上がりのスクリーンショットです。

最初のタブで開いたページの履歴とお気に入りが表示され、次のタブでページ一覧が開きます。ここでは任意の Cosense プロジェクトのページ一覧を表示可能です。履歴やお気に入りのリンクをクリックすると別ウィンドウでページを開きます。
後述しますが、タブ内での Cosense ページ表示はできなかったので PoC では妥協して別ウィンドウ表示としました。お気に入りへの追加はコンテキストメニューから可能です。

作成したコード全体をご紹介すると膨大になってしまうため、リポジトリは記事の終わりに掲載します。記事中のコードスニペットで雰囲気を掴んでいただければと思います。

使用したソフトウェアのバージョンなど

今回は、以下のような構成で PoC を行いました。

Rust 1.19.1
Tauri 2.9.3
Vite 6.0.3
Vue 3.5.13

sbe では Vuetify を使っていましたが、シンプルにするため、Vue と CSS だけで作成しました。最初に vanilla テンプレートを使ってプロジェクトを作成し、後から必要なものをインストールしました。

mkdir sbe-tauri-poc && cd sbe-tauri-poc
npm create tauri-app@latest . --template vanilla-ts

マルチビュー、タブ UI

sbe では、複数の Cosense ページや独自の画面をタブ UI で表示しています。以下のように、Electron の WebContentsView で Scrapbox のページを表示し、複数の WebContentsView を Vue(Vuetify) で実装したタブで切り替えるようにしています。

WebContentsView は BaseWindow に埋め込まれます。複数の WebContentsView を重ねて表示やタイル表示もできますし、API により Z 軸上の順序を入れ替え可能です。レンダラープロセスの Vuetiry のタブクリックイベントをメインプロセスに通知して WebContentsView の Z order を入れ替えることでタブ切り替えを実現しています。

Information

Electron の WebContentsView の簡単なサンプルを GitHub の mamezou-tech オーガニゼーションで公開しています。

https://github.com/mamezou-tech/electron-example-browserview

WebContentsView を使用するアプリの構造については以下の記事を参照してください。

/blogs/2024/08/28/electron-webcontentsview-app-structure/

実際には sbe は BaseWindow + WebContentsView ではなく、BrowserWindow + BrowserView で実装しています。BrowserView は現在 WebContentsView の SIM として提供されているため、実質 WebContentsView による実装となっています。

一方、Tauri の WebView は埋め込みをサポートしておらず、独立ウィンドウとして表示する方法しかありません。sbe のような UI を実装するには、単独の WebView 内に iframe を使ってサイトを表示する方法が考えられます。

Cosense サイトを iframe で表示しようとすると以下のようなエラーになります。

Refused to load https://scrapbox.io/ because it does not appear in the frame-ancestors directive of the Content Security Policy.

Cosense は Content Security Policy (CSP) によって iframe 内での表示を制限しているようです。
そこで、Cosense 自体のタブ内表示は諦め、ページ毎に独立したウィンドウを WebView で起動することにしました。ただし、sbe で実装している管理画面やプロジェクトのページ一覧のような UI はタブで本体の WebView で表示することとしました。

Rust 側で WebView をウィンドウ表示するコマンドを作成しました。

src-tauri/src/lib.rs(抜粋)

#[tauri::command]
async fn create_webview_window(app: tauri::AppHandle, url: String, label: String) -> Result<(), String> {
    let webview_url = WebviewUrl::External(url.parse().map_err(|e| format!("Invalid URL: {}", e))?);
    
    let window = WebviewWindowBuilder::new(&app, &label, webview_url)
        .title("Scrapbox")
        .inner_size(1200.0, 800.0)
        .min_inner_size(800.0, 600.0)
        .center()
        .resizable(true)
        .visible(false)
        .build()
        .map_err(|e| e.to_string())?;
    
    // Show window after it's fully initialized
    window.show().map_err(|e| e.to_string())?;
    
    Ok(())
}

これを Vue の UI から invoke で呼び出します。

App.vue(抜粋)

const reopenWindow = async (window: RecentWindow) => {
  try {
    const windowId = `reopen-${Date.now()}`;
    await invoke('create_webview_window', { 
      url: window.url,
      label: windowId
    });   
    errorMessage.value = "";
  } catch (error) {
    console.error('Failed to reopen window:', error);
    errorMessage.value = `ウィンドウの再起動に失敗しました: ${error}`;
  }
};

デスクトップがウィンドウだらけになってしまいますが、ひとまずマルチビューアプリの土台はできました。

WebView でのナビゲーションの検出と Rust → フロントエンド通知

sbe では閲覧した Cosense ページの履歴を記録していますが、これは Electron の webContents のイベントを捕捉して実装しています。Cosense サイト内での遷移は did-navigate-in-page イベントで捕捉できます。

Electron のコード - main.mjs(抜粋)

function handleLinkEvent(view) {
  view.webContents.on('will-navigate', (e, url) => {
    // リンクを開く処理
  });
  view.webContents.on('did-start-navigation', async (e, url, isInPlace) => {
    const currentUrl = view.webContents.getURL();
    // 遷移開始時の処理
  });
  view.webContents.on('did-navigate-in-page', async (e, url) => {
    // サイト内遷移の処理(ヒストリへの保存など)
  });
  view.webContents.on('update-target-url', (e, url) => {
    // リンクのマウスオーバー時の処理
  });
}

Tauri の Rust 用 API では on_navigation や on_page_loadというメソッドがあり、Web ページの取得開始やロード完了を捕捉できます。しかしこのハンドラーでは同一サイト内のページ遷移は検出できないようです。Cosense サイト内でのページ遷移をリアルタイムに捕捉するには、JavaScript を WebView に埋め込んでイベントをトラッキングする必要があります。そのため WebView を起動する際に initialization_script でトラッキング用のスクリプトを埋め込みます。

Tauri WebView でのスクリプト注入 - src-tauri/src/lib.rs(抜粋)

#[tauri::command]
async fn create_webview_window(app: tauri::AppHandle, url: String, label: String) -> Result<(), String> {
    let webview_url = WebviewUrl::External(url.parse().map_err(|e| format!("Invalid URL: {}", e))?);
    let window = WebviewWindowBuilder::new(&app, &label, webview_url)
        .title("Scrapbox")
        .inner_size(1200.0, 800.0)
        .min_inner_size(800.0, 600.0)
        .center()
        .resizable(true)
        .visible(false)
        .initialization_script(include_str!("../scripts/navigation-tracker.js"))
        .build()
        .map_err(|e| e.to_string())?;
    
    window.show().map_err(|e| e.to_string())?;
    Ok(())
}

短いスクリプトは initialization_script の中にインラインで書けますが、可読性や IDE での作業効率化のために別ファイルで作成しロードする方がよいでしょう。

以下のスクリプトでは、trackNavigation 関数を用意し、変更を検出したら Tauri の invoke コマンドを通じて Rust 側に送信しています。ブラウザの進む・戻るイベントをリッスンして通知。history.pushState / history.replaceState をキャプチャーして SPA のナビゲーションを通知しています。また、MutationObserver を使ってタイトル変更を検知するようにしています。これにより、Cosense のようなモダンな SPA の画面遷移をトラッキングできるようになります。

注入するスクリプト - navigation-tracker.js

let currentUrl = window.location.href;
let currentTitle = document.title || window.location.hostname || 'Untitled';

// Function to track navigation
function trackNavigation(source = 'unknown') {
    const url = window.location.href;
    const title = document.title || window.location.hostname || 'Untitled';
    
    // Skip if no change
    if (url === currentUrl && title === currentTitle) return;
    
    console.log('Navigation tracked (' + source + '):', title, '→', url);
    
    // Update state
    currentUrl = url;
    currentTitle = title;

    // invoke Tauri command
    if (window.__TAURI__ && window.__TAURI__.core) {
        window.__TAURI__.core.invoke('track_navigation', {
            windowLabel: window.navigationTrackerLabel,
            url: url,
            title: title
        }).then(result => {
            console.log('Track navigation success:', result);
        }).catch(err => {
            console.error('Failed to track navigation:', err);
        });
    } else {
        console.error('Tauri API not available');
    }
}

// Track initial page load
trackNavigation('initialization');

// Listen for forward/back event
window.addEventListener('popstate', () => trackNavigation('popstate'));
window.addEventListener('hashchange', () => trackNavigation('hashchange'));

// Handle SPA navigation
const originalPushState = history.pushState;
const originalReplaceState = history.replaceState;

history.pushState = function(...args) {
    originalPushState.apply(this, args);
    trackNavigation('pushState');
};

history.replaceState = function(...args) {
    originalReplaceState.apply(this, args);
    trackNavigation('replaceState');
};

// Monitor title changes (for dynamic title updates)
let titleObserver;
if (document.querySelector('title')) {
    titleObserver = new MutationObserver(() => trackNavigation('titleChange'));
    titleObserver.observe(document.querySelector('title'), { childList: true });
}

WebView から invoke された Rust の track_navigation では、Vue 側に add-to-recent イベントを発行します。

注入スクリプトから invoke される Tauri コマンド

#[tauri::command]
async fn track_navigation(app: tauri::AppHandle, window_label: String, url: String, title: String) -> Result<(), String> {
    println!("Navigation tracked: {} -> {} ({})", window_label, url, title);
    
    // Emit event to main window for history tracking
    app.emit("add-to-recent", NavigationEvent {
        window_label,
        url,
        title,
    }).map_err(|e| e.to_string())?;
    
    Ok(())
}

Vue 側では add-to-recent イベントを受けてリストを更新し、重複を排除するなどの処理をしてローカルストレージに書き込みます。

Vue 側の処理

  // Listen for navigation events from WebView windows
  navigationUnlisten = await listen('add-to-recent', (event: any) => {
    const { window_label, url, title } = event.payload;
    
    addToRecent({
      id: `${window_label}-${Date.now()}`,
      title: title || new URL(url).hostname,
      url,
      lastAccessed: new Date()
    });

    console.log(`Navigation tracked: ${title} (${url})`);
  });


// Recent windows functions
const addToRecent = (window: RecentWindow) => {
  recentWindows.value = recentWindows.value.filter(w => w.id !== window.id);
  recentWindows.value.unshift(window);
  saveToStorage();
};

// Data persistence
const saveToStorage = () => {
  localStorage.setItem('sbe-recent', JSON.stringify(recentWindows.value.map(w => ({
    ...w,
    lastAccessed: w.lastAccessed.toISOString()
  }))));
  localStorage.setItem('sbe-favorites', JSON.stringify(favorites.value));
};

Information

今回はフロントエンド側で LocalStorage に保存しましたが、Rust 側で JSON ファイルとしてセーブ・ロードするように実装すれば、マシンが変わっても履歴を持っていけるので便利かもしれません。

Electron がページ内遷移の細やかなイベントを提供してくれていたので、Tauri の方式はかなり面倒に感じる部分でした。Electron が Chrome を内包していることで開発者はきめ細かいイベントの捕捉を簡単にできていましたが、Tauri は OS にインストールされた WebView を使用しているのでそこまで WebView 実装に入り込んだイベントの提供はできないようです。そこで、initialization_script スクリプトを注入するという、ややハッキーなやり方が必要でした。
これは Tauri と WebView が疎結合であるためであり、このおかげで Tauri のアプリは軽量で省メモリになっているとも言えます。

Cosense ページ一覧画面のための API 呼び出しと JSON Parse

Cosense プロジェクトのページ一覧を Vue で作成しタブ内で表示します。このためには Cosense の API で該当するプロジェクトのページリストを取得する必要があります。sbe では、およそ以下のような感じでメインプロセス側で Cosense API を使用してページ一覧を取得しています。

Electron での API 呼び出し - main.mjs

async function fetchPageInfo(url) {
  const sid = await getSid();
  const res = await fetch(url, { headers: { cookie: sid } });
  const data = await res.json();
  return data;
}

async function getSid() {
  const cookies = await session.defaultSession.cookies.get({ name: 'connect.sid' });
  return cookies[0].value;
}

プライベートな Cosense プロジェクトからも取得できるよう、Cookie をセッションから取得して、リクエストヘッダーに埋め込んでいます。

Tauri でもデータのフェッチは Rust 側でやるのが推奨です。特に API キーなどはフロントエンドに晒さない方がよいでしょう。

Rust 側で API 呼び出しを実装するので、Electron のメインプロセス(の JavaScript) ではするっと実装できていたレスポンスの処理はやや面倒になります。API のレスポンスを解析して以下のように型情報を定義しました。

Rust でのレスポンス型定義

// API Response
#[derive(Serialize, Deserialize)]
struct ScrapboxPagesResponse {
    #[serde(rename = "projectName")]
    project_name: String,
    skip: i32,
    limit: i32,
    count: i32,
    pages: Vec<ScrapboxPage>,
}

// Cosense page
#[derive(Serialize, Deserialize, Clone)]
struct ScrapboxPage {
    id: String,
    title: String,
    image: Option<String>,
    descriptions: Vec<String>,
    #[serde(rename = "lastUpdateUser")]
    last_update_user: Option<ScrapboxUser>,
    // 中略
    #[serde(rename = "charsCount")]
    chars_count: Option<i32>,
    helpfeels: Option<Vec<String>>,
}

// Cosense user
#[derive(Serialize, Deserialize, Clone)]
struct ScrapboxUser {
    id: String,
}

Cosense API を呼び出す fetch_scrapbox_pages コマンドです。Cosense API のページングのためのパラメータを処理しているため少し長ったらしくなっていますが、cookies_for_url メソッドでウィンドウから Cookie を取得し、ヘッダーに埋め込むところは Electron と同様の流れです。上記で定義した ScrapboxPagesResponse に API のレスポンスを格納しています。

Rust での Cosense API 呼び出し

// Command to fetch Scrapbox pages with authentication (supports both public and private projects)
#[tauri::command]
async fn fetch_scrapbox_pages(
    app: tauri::AppHandle,
    project: String, 
    skip: Option<i32>, 
    limit: Option<i32>, 
    sort: Option<String>
) -> Result<ScrapboxPagesResponse, String> {
    let skip = skip.unwrap_or(0);
    let limit = limit.unwrap_or(20);
    let sort = sort.unwrap_or_else(|| "updated".to_string());
    
    let api_url = format!(
        "https://scrapbox.io/api/pages/{}?skip={}&limit={}&sort={}",
        project, skip, limit, sort
    );

    let scrapbox_url = Url::parse("https://scrapbox.io").map_err(|e| format!("Invalid URL: {}", e))?;

    // Try to get cookies from main window's webview
    let cookies = if let Some(main_window) = app.get_webview_window("main") {
        main_window.cookies_for_url(scrapbox_url.clone())
            .map_err(|e| format!("Failed to get cookies: {}", e))?
    };

    let client = reqwest::Client::new();
    let mut request_builder = client.get(&api_url);

    // Add cookies if available
    if !cookies.is_empty() {
        let cookie_header = build_cookie_header(cookies);
        println!("Using cookies for authentication: {} cookies", cookie_header.matches(';').count() + 1);
        request_builder = request_builder.header("Cookie", cookie_header);
    }
    
    let response = request_builder
        .send()
        .await
        .map_err(|e| format!("Failed to fetch pages: {}", e))?;
    
    if !response.status().is_success() {
        return Err(format!("API request failed with status: {} - This might be a private project requiring authentication", response.status()));
    }
    
    let pages_data: ScrapboxPagesResponse = response
        .json()
        .await
        .map_err(|e| format!("Failed to parse JSON: {}", e))?;

    Ok(pages_data)
}

Vue 側では Rust の fetch_scrapbox_pages を invoke して取得したリストを表示します。

Vue 側の処理

// Scrapbox pages functions
const fetchScrapboxPages = async () => {
  scrapboxLoading.value = true;
  scrapboxError.value = '';
  
  try {
    const result = await invoke('fetch_scrapbox_pages', {
      project: scrapboxProject.value,
      skip: scrapboxSkip.value,
      limit: scrapboxLimit.value,
      sort: scrapboxSort.value
    }) as { pages: ScrapboxPage[], count: number, skip: number };
    
    scrapboxPages.value = result.pages;
    console.log(`Fetched ${result.pages.length} pages from ${scrapboxProject.value}`);
  } catch (error) {
    console.error('Failed to fetch Scrapbox pages:', error);
    scrapboxError.value = `ページの取得に失敗しました: ${error}`;
  } finally {
    scrapboxLoading.value = false;
  }
};

Electron はメインプロセスも JavaScript で書けるので JSON の処理は楽でした。Tauri(Rust) では実行時ではなくコンパイル時のエラー検出など型安全性によるメリットもありますし、TypeScript でも同様です。大規模な開発では、この辺はコードジェネレータの仕事なんだと思います。

コンテキストメニューのハンドリング

WebView ウィンドウに表示している Cosense ページをお気に入りに追加するための実装を行います。WebView 上でコンテキストメニューを表示して追加してもらうのが自然でしょう。
以前の記事では、SPA をアプリ化していたので Tauri の JavaScript API で簡単にコンテキストメニューを実装していました。今回のように WebView に Web サイトを表示する場合、コンテキストメニューの処理はやはりスクリプトを注入する必要があります。Tauri API によるコンテキストメニューのコードを注入してもいいのですが、今回は DOM 操作でコンテキストメニューを追加しました。Tauri API で追加するコンテキストメニューは OS ネイティブなものなので、WebView で表示しているサイトのルックアンドフィールに合わせたい場合は、DOM 操作で近い雰囲気のメニューを作るのも選択肢です。

WebView に注入するコンテキストメニュー用スクリプト

function showContextMenu(x, y) {
    // Remove existing context menu if any
    const existingMenu = document.getElementById('tauri-context-menu');
    if (existingMenu) {
        existingMenu.remove();
    }
    
    // Create context menu
    const menu = document.createElement('div');
    menu.id = 'tauri-context-menu';
    menu.style.cssText = `
        position: fixed;
        left: ${x}px;
        top: ${y}px;
        box-shadow: 0 2px 8px rgba(0,0,0,0.15);
        z-index: 10000;
        min-width: 180px;
        font-size: 14px;
    `;
    
    // Add menu item
    const menuItem = document.createElement('div');
    menuItem.textContent = '⭐ お気に入りに追加';
    menuItem.style.cssText = `
        padding: 8px 16px;
        cursor: pointer;
        border-radius: 4px;
        transition: background-color 0.2s;
    `;
    
    menuItem.addEventListener('click', () => {
        addToFavorites();
        menu.remove();
    });
    
    menu.appendChild(menuItem);
    document.body.appendChild(menu);
    
    document.addEventListener('click', function removeMenu() {
        menu.remove();
        document.removeEventListener('click', removeMenu);
    });
}

このスクリプトを先ほどの、navigation-tracker.js と同様 WebView に注入します。

コンテキストメニューのクリックで addToFavorites 関数を呼び出しており、この中で、add_to_favorites_from_webview を invoke しています。Rust 側で add_to_favorites_from_webview　コマンドが実行され、Vue 側に add-to-favorites イベントが発行されます。

コンテキストメニューから呼び出される Tauri コマンド - lib.rs

// Command to add to favorites from WebView
#[tauri::command]
async fn add_to_favorites_from_webview(app: tauri::AppHandle, url: String, title: String) -> Result<(), String> {
    // Emit event to main window to add to favorites
    app.emit("add-to-favorites", FavoriteEvent {
        url,
        title,
    }).map_err(|e| e.to_string())?;
    
    Ok(())
}

Vue側では、Rust から送信されたイベントを元にお気に入り追加の処理を行います。

Vue 側の処理

const addFavoriteFromWebView = async (url: string, title: string) => {
  try {
    // Check if already exists
    const existingFavorite = favorites.value.find(f => f.url === url);
    if (existingFavorite) {
      errorMessage.value = "すでにお気に入りに登録されています";
      setTimeout(() => {
        errorMessage.value = "";
      }, 2000);
      return;
    }
    
    const favorite: Favorite = {
      id: `fav-${Date.now()}`,
      title,
      url
    };
    
    favorites.value.unshift(favorite);
    saveToStorage();
    errorMessage.value = `お気に入りに追加しました: ${title}`;
    
    setTimeout(() => {
      errorMessage.value = "";
    }, 3000);
  } catch (error) {
    console.error('Failed to add favorite from WebView:', error);
    errorMessage.value = `お気に入りの追加に失敗しました: ${error}`;
  }
};

GitHub Actions ワークフローでプラットフォーム毎のインストーラーを生成

一通り動作する Tauri 版の Cosense アプリができたので、macOS や Windows 向けのインストーラを CI で作成するようにしてみます。

Tauri は OS の WebView を使用するため、クロスコンパイルはできません。OS ごとにビルド環境を用意する必要があります。Electron でも OS 毎の Chrome を同梱させるため、OS ごとのビルド環境が必要になるのでそこは変わりません。

GitHub Actions の Strategy Matrix を使って、macOS と Windows のインストーラを作成して成果物として保存するワークフローを定義しました。

.github/workflows/build-installers.yml

name: Build Installers

on:
  workflow_dispatch:

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: macos-latest
            name: macos-installer
            path: |
              src-tauri/target/release/bundle/dmg/*.dmg
              src-tauri/target/release/bundle/macos/*.app
          - os: windows-latest
            name: windows-installer
            path: |
              src-tauri/target/release/bundle/msi/*.msi
              src-tauri/target/release/bundle/nsis/*.exe
    
    runs-on: ${{ matrix.os }}
    
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
        cache: 'npm'

    - name: Setup Rust
      uses: dtolnay/rust-toolchain@stable

    - name: Install dependencies
      run: npm install

    - name: Build Tauri app
      run: npm run tauri build

    - name: Upload artifacts
      uses: actions/upload-artifact@v4
      with:
        name: ${{ matrix.name }}
        path: ${{ matrix.path }}
        retention-days: 30

このワークフローを実行して、生成された Tauri のアプリのインストーラは 5-7MB 程度、インストールされるバイナリは 3-4MB 程度です。

sbe のインストーラは 100MB 前後、macOS のユニバーサルインストーラは200MB近くあります。

Tauri アプリのフットプリントの軽さは魅力的ですね。起動が速くてアプリのレスポンスも軽快です。

ソースコードのリポジトリ

今回の PoC の結果は以下のリポジトリに置いています。

https://github.com/kondoumh/sbe-tauri-poc

Copilot に README を書いてもらったので表現がやや大袈裟になってしまっている点はご了承ください😅。

さいごに

以上、Electron のアプリを Tauri 2.0 に移植してみる PoC のご紹介でした。今回の題材だと Electron の機能性や利便性が逆に強調される感じでしたが、軽量で高速なバイナリが生成される点や、Rust/Tauri のエコシステム、型安全性による開発体験は魅力ですね。

Information

Tauri では、.NET の Blazor もサポートされています。

https://v2.tauri.app/ja/start/create-project/#%E6%96%B0%E3%81%97%E3%81%84%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%82%92%E6%BA%96%E5%82%99%E3%81%99%E3%82%8B

Blazor については昨年のアドベントカレンダーで紹介されています。

/blogs/2024/12/20/asp-dotnet-core-blazor/

Tauri 2.0 では OS の WebView を利用していますが、Servo ベースのクロスプラットフォームな WebView を開発するプロジェクト Verso があります。

NLnet; Servo improvements for Tauri

Verso により各 OS の WebView 間の差異が吸収され、主要なデスクトップおよびモバイルプラットフォームで一貫性のある体験がもたらされます。今回面倒に感じた Navigation 用の API なども利用しやすくなるかもしれません。

将来 Tauri に Verso プロジェクトの成果が取り込まれれば WebView を腹持ちする構造になるため、バイナリサイズは大きくなるでしょう。そのため、従来の OS の WebView と切り替えるようなオプションが提供されるかもしれませんね。

コピペで始める：Amazon Q Developer × Spec Kitで始めるAI駆動開発

2025-11-28T00:00:00.000+00:00

本記事は、以下イベントで講演した内容の文字起こし版です。

超実践 AI駆動開発～生成AIを活用したシステム開発の効率化・品質向上の最前線～

Information

2025年11月17日より、Q Developer CLIは正式名称「Kiro CLI」となりました。本記事では執筆時点の名称「Q Developer CLI」で説明していますが、コマンドや機能は同じです。今後のアップデートで q コマンドが kiro コマンドに変更される可能性があります。

はじめに

対象読者

本記事は以下のような方を対象としています。

生成AIを使った開発に興味がある開発者
AIコード生成で「意図しない実装」に困った経験がある方
品質を保ちながらAIを活用したい方
Amazon Q Developer（Kiro CLI）やSpec Kitを試したい方

前提知識

以下の基礎知識があることを前提としています。

Git、GitHubの基本操作
Docker、Docker Composeの基本概念
Java/Spring Boot、React/TypeScriptの基礎（サンプルプロジェクトで使用）
AWSの基本知識（デプロイセクション）

本記事で得られること

本記事を読むことで、以下ができるようになります。

環境構築からデプロイまでの工程を理解できる
コピペで動く実践的なプロンプト例を入手できる
AI駆動開発における品質確保の方法を学べる
実際に動くサンプルプロジェクトを手に入れられる

背景知識：なぜSDD+TDDなのか

生成AI駆動開発の現状

2022年末のChatGPT登場以降、AIを活用した開発は急速に普及しました。現在、GitHub Copilot、Cursor、Claude Code、Windsurf、Amazon Q Developer^[1]、Kiroなど、多くのコーディングアシスタントが利用可能です。

AIの進化は「モデル中心（GPT時代）」から「エージェントネットワーク中心」へと移行しつつあり、単なるコーディング支援から自律実行型エージェントへと発展しています。

AIコード生成の「影」

しかし、実際の開発現場では以下のような課題に直面することがあります。

1. 過剰実装

要求していない機能を勝手に追加してしまう。

例：

ログイン機能だけ依頼したのに、パスワードリセット機能まで実装される
シンプルなCRUDを依頼したのに、検索機能や並び替えまで追加される

2. 仮定

要求仕様の曖昧な部分を勝手に補完し、意図しない設計になる。

例：

「ユーザー情報を保存」→ AIが勝手にメールアドレスを必須項目にする
「データを表示」→ AIが勝手にページングを10件単位で実装する

3. 成功宣言

ビルドやテストが失敗しているのに「完了しました」と報告する。

例：

コンパイルエラーがあるのに「実装完了」
テストが落ちているのに「全てのテストが成功」と報告

4. 保守コストの増大

最近の研究^[2]^[3]によると、AI支援ツールで開発スピードを上げても、保守やレビュー、品質管理コストは上昇する傾向にあります。また、経験豊富な開発者が本来の新規開発業務から外れ、保守業務に偏るパターンも観察されています。

SDD+TDDによる解決アプローチ

これらの課題を解決するために、以下2つの手法を組み合わせます。

SDD（Specification-Driven Development：仕様駆動開発）

コードを書く前に、期待する動作・要件・制約を明確に仕様化し、それをもとに開発を進める手法。

効果：明確な仕様があると、AIが曖昧さなく正確にコードを生成可能になる^[4]。

TDD（Test-Driven Development：テスト駆動開発）

コードを書く前にテストを定義し、失敗を起点に修正・改善を繰り返す手法。

効果：LLMによるコード生成にTDDの枠組みを導入すると生成成功率が向上^[5]。テストを「仕様・制約」として明示することで、AIの生成精度が改善^[6]。

SDDで仕様を固め、TDDで正しい振る舞いを基準化することで、AIの制御可能性を高めます。

環境構築：最小限の準備で始める

前提条件チェックリスト

以下がインストール済みであることを確認してください。

Windows + WSL2（Linuxでも可）
Git
VSCode
Docker Desktop（または Docker Engine）
AWS Builder ID または AWS IAM Identity Center アカウント（Q Developer用）

ステップ1：GitHubリポジトリのクローン

今回講演用に作成した公開サンプルリポジトリをクローンします。

# 作業ディレクトリに移動
cd ~/workspace

# リポジトリをクローン
git clone https://github.com/mamezou-tech/aidd-demo.git

# ディレクトリに移動
cd aidd-demo

https://github.com/mamezou-tech/aidd-demo

リポジトリの内容：

backend/: Spring Boot バックエンド（Java 17, Spring Boot 3.x）
frontend/: React フロントエンド（React 18, TypeScript, Vite）
specs/: 仕様書ドキュメント
.devcontainer/: DevContainer設定
.amazonq/: Amazon Q Developer設定
docker-compose.yml: 開発環境構成

ステップ2：VSCodeでDevContainerを起動

# VSCodeで開く
code .

VSCodeが起動したら、以下の手順を実行します。

左下の緑色のボタン（リモートエクスプローラー）をクリック
「Reopen in Container」を選択
初回は数十分かかります（Dockerイメージのビルド）
コンテナ内のターミナルが自動的に開く

DevContainerに含まれるもの：

Node.js、Java 17、Gradle
AWS CLI
Q Developer CLI 1.19.7
各種開発ツール

ステップ3：Q Developer CLI（Kiro CLI）のログイン

Free プランの場合（AWS Builder ID）

# ログインコマンド
q login

# ブラウザが開くので、AWS Builder IDでログイン
# ログイン完了後、ターミナルに戻る

Pro プランの場合（IAM Identity Center）^[7]

# ログインコマンド
q login

# プロンプトに従ってIAM Identity Centerの情報を入力
# Start URL: https://[your-domain].awsapps.com/start
# Region: ap-northeast-1 など

# ブラウザが開くので、認証を完了

対話モード開始：

q chat

Information

2025年11月17日以降、Q Developer CLIは正式名称「Kiro CLI」となりました。本記事では旧名称「Q Developer CLI」で説明していますが、機能は同じです。今後のアップデートで q コマンドが kiro コマンドに変更される可能性があります。

ステップ4：アプリケーションの起動と動作確認

1. データベースとバックエンドの起動

Dev Container内のターミナルで以下を実行します。

docker compose up -d

このコマンドで以下が起動します。

MySQLデータベース（ポート3306）
Spring Bootアプリケーション（ポート8080）

コンテナが起動していることを確認します。

docker compose ps

# 期待される出力：
# mysqldbとappコンテナのSTATUSがUp (healthy)

2. フロントエンドの起動

以下を実行します。

cd frontend
npm run dev

※依存パッケージはDev Container起動時に自動インストールされます。

フロントエンドは http://localhost:3000 で起動します。

動作確認：

ブラウザで以下にアクセスします。

フロントエンド: http://localhost:3000
バックエンドAPI: http://localhost:8080/api/health

トラブルシューティング（環境構築）

Q1: DevContainerが起動しない

原因: Dockerが起動していない、またはリソース不足。

解決策:

# Dockerが起動しているか確認
docker ps

# リソース設定を確認（Docker Desktopの場合、Settings > Resources）

Q2: `q` コマンドが見つからない

原因: DevContainerのビルドが不完全。

解決策:

# コンテナを再ビルド
# VSCodeで Ctrl+Shift+P → "Dev Containers: Rebuild Container"

# または、コマンドラインから
docker compose down
docker compose up -d --build

Q3: ポート3000や8080が既に使用されている

原因: 他のアプリケーションがポートを使用中。

解決策:

# 使用中のプロセスを確認
lsof -i :3000
lsof -i :8080

# プロセスを終了するか、docker-compose.ymlのポートを変更
# ports:
#   - "3001:3000"  # 3000 → 3001に変更

実践①：仕様策定 - specify → clarify の反復

Spec Kitコマンド一覧

Spec Kitは以下のコマンドを提供します。

コマンド	説明	主な用途
`@speckit.constitution`	プロジェクト原則を作成・更新	TDDルールなどの定義
`@speckit.specify`	機能の要件・ユーザーストーリーを定義	仕様書作成
`@speckit.clarify`	曖昧な仕様を明確化	仕様の精緻化
`@speckit.plan`	技術的な実装計画を作成	アーキテクチャ設計
`@speckit.analyze`	仕様・計画・タスク間の整合性分析	矛盾チェック
`@speckit.tasks`	実装タスク一覧を生成	タスク分解
`@speckit.implement`	計画とタスクに従って実装	コード生成
`@speckit.checklist`	要件チェックリスト生成	進捗管理

Caution

Q Developer CLIでは、スラッシュ（/）ではなくアットマーク（@）でプロンプトを呼び出します。引数を正しく渡すため、コマンドの先頭に引用符（'）を付けます^[8]。

対話型セッションの開始

まず、Q Developer CLIの対話型セッションを開始します。以降のコマンドはすべてこのセッション内で実行します。

q chat

セッションが開始されると、プロンプトが表示され、コマンドを入力できるようになります。

ステップ1：プロジェクト原則の確認

プロジェクトにTDDなどの原則が定義されているか確認します。
追加が必要な場合は、以下のコマンドで追加が可能です。

'@speckit.constitution <プロジェクト原則に追加したい内容>'

記載例：

# Project Constitution

## Test-First Imperative
コードの前に必ずテストを書く。
- ユニットテストを先に作成
- テストが失敗すること（Red phase）を確認してから実装
- 非交渉事項として厳格に適用

## Library-First Principle
すべての機能は独立したライブラリとして実装する。

## Simplicity Gate
過度なエンジニアリングを防ぐ。
- 初期実装は最大3プロジェクトまで

公開リポジトリのconstitution.mdには、Spec Kitで提示されている6つの原則を記述しています。

ステップ2：仕様を策定する（@speckit.specify）

初回のspecify

社員検索システムMVPの仕様を作成します。

プロンプト例：

'@speckit.specify
社員検索システム（MVP）の仕様を作成してください。

【目的】
社員情報を一元管理し、人事が「誰がどのスキルを持ち、どの組織に所属しているか」をすばやく把握できるようにすること。

【主な利用者】
- 人事：全社の社員・スキル・組織情報を俯瞰し、配置検討や採用計画のインプットに利用する。

【想定ユースケース】
- 人事が、特定スキル（例：Java、AWS）を持つ社員を検索し、部署横断で候補者リストを作成する。
- 顔写真付きの社員一覧・詳細画面で、人物を視覚的に識別できる。

【MVPで提供したい機能範囲】
- ログイン機能（シンプルな認証）
- 社員情報の登録・閲覧・検索
  - 基本属性（氏名、社員ID、所属組織、役職、雇用区分）
  - 顔写真の登録・表示
- スキル情報の閲覧
  - スキルマスタの管理
  - 社員ごとの保有スキルの紐づけ
- 組織の階層管理（親子関係のみのシンプルなツリー構造）

【MVP対象外】
- 詳細な権限管理
- 監査ログ
- 高度なスキル分析
- 組織改編の履歴管理
- 外部システム連携

【アウトプットの期待】
- ユースケース一覧と簡単なフロー
- 画面・APIの概要
- データモデルの概要
- 非機能要件（MVP に必要な最低限）
- MVP対象外機能の明示
'

ポイント：

目的を明確に記述する
利用者のペルソナを定義する
MVPの範囲を明確にする（特に「対象外」を明示）
曖昧な表現を避ける

出力例：

AIが spec.md ファイルを生成します。内容には以下のような内容が含まれます。

# 社員検索システムMVP 仕様書

## 1. 概要
...

## 2. ユースケース
### UC-001: ログイン
- アクター: 人事担当者
- 前提条件: ユーザーアカウントが登録されている
- 基本フロー:
  1. ユーザーがログイン画面でユーザー名とパスワードを入力
  2. システムが認証を実行
  3. 認証成功時、ホーム画面にリダイレクト
...

## 3. 画面設計
### 3.1 ログイン画面
- 入力項目: ユーザー名、パスワード
- ボタン: ログイン
...

## 4. データモデル
### 4.1 社員（Employee）
- employee_id (PK): 社員ID
- name: 氏名
- organization_id (FK): 所属組織
- photo_url: 顔写真URL
...

ステップ3：曖昧な点を明確化する（@speckit.clarify）

生成された仕様書には、まだ曖昧な点が残っています。clarifyコマンドで明確化します。

プロンプト例：

'@speckit.clarify
社員検索システムMVP仕様書に対して、以下の点について曖昧な点を洗い出し、質問リストを作成してください：
- ログイン／認証方式（MVPでの具体的な前提）
- スキル検索と表示方法
- 顔写真の登録方法
- 一覧画面におけるページング／ソートの扱い
'

出力例：

AIが以下のような質問リストを生成します。

# 仕様の曖昧点に関する質問

## ログイン／認証方式
Q1: パスワードの暗号化方式は何を使用しますか？（bcrypt、PBKDF2など）
Q2: セッション管理はどうしますか？（Cookie、JWT、サーバーサイドセッションなど）
Q3: ログアウト機能は必要ですか？
Q4: パスワードリセット機能はMVPに含まれますか？

## スキル検索と表示方法
Q5: スキル検索は完全一致ですか、部分一致ですか？
Q6: 複数スキルのAND検索/OR検索は必要ですか？
Q7: スキルレベル（初級/中級/上級など）の扱いはどうしますか？

## 顔写真の登録方法
Q8: 顔写真のファイルサイズ上限は？
Q9: 許可する画像形式は？（JPEG、PNG、GIFなど）
Q10: 顔写真がない場合、デフォルト画像を表示しますか？

## ページング／ソート
Q11: 一覧画面の1ページあたりの表示件数は？
Q12: ソート項目は何ですか？（氏名、社員ID、組織など）
Q13: デフォルトのソート順は？

ステップ4：質問に回答して仕様を修正（@speckit.specify）

AIからの質問に回答し、仕様を修正します。

プロンプト例：

'@speckit.specify
社員検索システムMVP仕様書を、以下の回答に基づいて更新してください。

【ログイン／認証方式】
A1: bcryptを使用
A2: JWTトークンをCookieに保存
A3: ログアウト機能は必要
A4: パスワードリセット機能はMVP対象外

【スキル検索と表示方法】
A5: 部分一致（前方一致）
A6: 複数スキルのAND検索のみ
A7: スキルレベルは3段階（初級/中級/上級）

【顔写真の登録方法】
A8: 5MB以下
A9: JPEG、PNGのみ
A10: デフォルトアバター画像を表示

【ページング／ソート】
A11: 20件/ページ
A12: 氏名、社員ID、所属組織でソート可能
A13: 氏名の昇順
'

ステップ5：反復

specify → clarify → specify のサイクルを繰り返すと、曖昧な点がかなり減少します。

反復のポイント：

仕様が曖昧だと困る点を指定すると効果的
AIに推奨案を提示してもらうことで高速化できる

高速化の例：

'@speckit.clarify
社員情報の登録と更新について、曖昧な点を洗い出し、
あなたの推奨案も合わせて提示してください。
'

成果物：spec.md

最終的に以下のような完成度の高い仕様書が得られます。

ユースケースが具体的に記述されている
画面項目・API仕様が明確
データモデルが詳細に定義されている
曖昧な点が解消されている
MVP対象外が明確

実践②：実装 - TDDサイクルの実践

ステップ1：実装計画を作成（@speckit.plan）

@speckit.plan

出力例：

# 実装計画

## 技術スタック
- Backend: Java 17, Spring Boot 3.2.0, Spring Security, Spring Data JPA
- Frontend: React 18, TypeScript, Tailwind CSS
- Database: MySQL 8.0
- Test: JUnit 5, Testcontainers, Playwright

## アーキテクチャ
### バックエンド
- レイヤードアーキテクチャ
  - Controller層: REST APIエンドポイント
  - Service層: ビジネスロジック
  - Repository層: データアクセス

### フロントエンド
- コンポーネントベースアーキテクチャ
- React Router for SPA
- Context API for 状態管理

## セキュリティ
- JWT認証
- bcryptによるパスワードハッシュ化
- CORS設定

この内容が plan.md として保存されます。

ステップ2：タスク一覧を生成（@speckit.tasks）

'@speckit.tasks
タレントマネジメントシステムMVPを、2〜3日の粒度の実装タスクに分解してください。
'

出力例：

# 実装タスク一覧

## Phase 1: 基盤構築
- Task 1.1: プロジェクト構造のセットアップ
- Task 1.2: データベーススキーマの作成

## Phase 2: 認証機能
- Task 2.1: ユーザーエンティティとRepository
  - Red: UserRepositoryTestを作成し、失敗を確認
  - Green: User.java, UserRepository.javaを実装し、テスト成功
  - Refactor: コードの整理
- Task 2.2: JWT認証の実装
  - Red: JwtUtilTestを作成し、失敗を確認
  - Green: JwtUtil.java, JwtAuthenticationFilter.javaを実装
  - Refactor: コードの整理
- Task 2.3: ログインAPIの実装
  - Red: AuthControllerTestを作成し、失敗を確認
  - Green: AuthController.java, AuthService.javaを実装
  - Refactor: コードの整理

## Phase 3: 社員管理機能
- Task 3.1: 社員エンティティとRepository
- Task 3.2: 社員登録API
- Task 3.3: 社員検索API
- Task 3.4: 社員詳細API

...

この内容が tasks.md として保存されます。

ステップ3：実装（@speckit.implement）

いよいよ実装です。Spec Kitのテストファースト原則に基づき、TDDサイクルを使って実装を進めます。

Task 2.1の実装例：ユーザーエンティティとRepository

プロンプト例：

'@speckit.implement Task 2.1'

AIの動作例：

まずテストを生成（Red phase）

UserRepositoryTest.java:

package com.example.demo.repository;

import com.example.demo.entity.User;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.testcontainers.containers.MySQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import java.util.Optional;

import static org.assertj.core.api.Assertions.assertThat;

@DataJpaTest
@Testcontainers
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class UserRepositoryTest {

    @Container
    static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
            .withDatabaseName("testdb");

    @Autowired
    private UserRepository userRepository;

    @Test
    void ユーザー名でユーザーを検索できる() {
        // Arrange
        User user = new User();
        user.setUsername("testuser");
        user.setPassword("hashedPassword");
        userRepository.save(user);

        // Act
        Optional<User> found = userRepository.findByUsername("testuser");

        // Assert
        assertThat(found).isPresent();
        assertThat(found.get().getUsername()).isEqualTo("testuser");
    }

    @Test
    void 存在しないユーザー名で検索すると空が返る() {
        // Act
        Optional<User> found = userRepository.findByUsername("nonexistent");

        // Assert
        assertThat(found).isEmpty();
    }
}

テストを実行して失敗を確認

# AIが自動的に実行
./gradlew test --tests UserRepositoryTest

# 結果：FAILED（User.javaやUserRepository.javaがまだ存在しないため）

実装を生成（Green phase）

User.java:

package com.example.demo.entity;

import jakarta.persistence.*;
import lombok.Data;

@Entity
@Table(name = "users")
@Data
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 50)
    private String username;

    @Column(nullable = false)
    private String password;

    @Column(length = 100)
    private String email;
}

UserRepository.java:

package com.example.demo.repository;

import com.example.demo.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import java.util.Optional;

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    Optional<User> findByUsername(String username);
}

テストを実行して成功を確認

./gradlew test --tests UserRepositoryTest

# 結果：PASSED

リファクタリング（Refactor phase）

テストが通った状態で、コードを改善します。AIが以下のようなリファクタリングを実行します。

変数名・メソッド名の改善
重複コードの削除
可読性の向上

テストが通り続けることを確認しながら、安全にコードを改善します。

TDDサイクルの反復ポイント

Red → Green → Refactor のサイクル：

Red（失敗するテストを書く）
- 期待する振る舞いをテストで表現
- 実装がないため、テストは失敗する
Green（テストが通る最小限の実装）
- テストを通過させるコードを書く
- この段階では「美しさ」より「動作」を優先
Refactor（リファクタリング）
- テストが通った状態で、コードを改善
- 重複を削除、可読性を向上

実践③：デプロイ - 自然言語だけでAWS構築

前提条件

AWS CLIがインストール済み（DevContainerに含まれる）
AWSプロファイル（認証情報）が設定済み
EC2を起動する権限があるIAMユーザー/ロール

今回のデプロイはテスト用途のため、以下は簡略化しています。

HTTPSではなくHTTP
単一EC2インスタンス
ロードバランサーなし
データベースはコンテナ内

ステップ1：EC2インスタンスの作成

プロンプト例：

Amazon Linux 2023、t3.smallでEC2インスタンスを作成してください。
セキュリティグループは、22番ポート（SSH）と3000番ポート（アプリ）を
自分のIPアドレスからのみ許可してください。
キーペアは "aidd-demo-key" という名前で作成してください。

AIの動作例：

AIが以下を自動実行します。

現在のIPアドレスを取得
セキュリティグループを作成（SSH: 22、App: 3000）
キーペアを作成
EC2インスタンスを起動
インスタンスIDとパブリックIPを出力

ステップ2：DockerとDocker Composeのインストール

プロンプト例：

EC2インスタンス（(パブリックIP)）にSSHで接続し、
Docker と Docker Compose をインストールしてください。
ユーザーをdockerグループに追加し、再ログインせずに使えるようにしてください。

AIの動作例：

AIが以下を自動実行します。

EC2インスタンスにSSH接続
システムパッケージを更新
Dockerをインストール・起動・自動起動設定
ユーザーをdockerグループに追加
Docker Composeをインストール
インストール完了を確認

ステップ3：アプリ一式をEC2へ転送

プロンプト例：

カレントディレクトリのdocker-compose.ymlと、
backend、frontend、dbディレクトリを、
EC2インスタンス（(パブリックIP)）の /home/ec2-user/aidd-demo へ転送してください。

AIの動作例：

AIが以下を自動実行します。

EC2インスタンス上に転送先ディレクトリを作成
docker-compose.yml、backend、frontend、dbディレクトリをSCPで転送

ステップ4：Docker Composeでアプリ起動

プロンプト例：

EC2インスタンスで、転送したディレクトリに移動し、
docker compose up -d を実行してください。
全コンテナが Up(healthy) で起動していることを確認してください。

AIの動作例：

AIが以下を自動実行します。

EC2インスタンスにSSH接続
転送したディレクトリに移動
docker compose up -d でコンテナを起動
全コンテナのステータスを確認し、Up (healthy) であることを報告

ステップ5：アプリ動作確認

ブラウザでアクセス：

http://(パブリックIP):3000

API疎通確認：

curl http://(パブリックIP):8080/api/health

# 出力例：
# {"status":"UP"}

ログイン確認：

ブラウザでログイン画面にアクセスし、以下のテストユーザー情報でログインします。

ID: test@example.com
PW: aiddTest

ログイン後TOP画面が表示され、そのリンクから社員検索システムに遷移します。

※登録データおよび顔写真はすべてAI生成によるものです。

CORS問題の修正（必要に応じて）

もしCORSエラーが発生した場合は以下を実行します。

プロンプト例：

バックエンドのCORS設定を修正してください。
フロントエンドのオリジン（http://(パブリックIP):3000）からのリクエストを許可してください。
修正後、EC2上でアプリを再起動してください。

まとめと参考資料

本記事のポイント

本記事では、Amazon Q Developer × Spec Kitを使ったAI駆動開発の全工程を解説しました。

環境構築：

GitHubリポジトリのクローンだけで開始可能
DevContainerで依存関係を自動解決

仕様策定：

specify → clarify の反復で仕様を精緻化
曖昧さを排除することがAI活用の鍵

実装：

TDDサイクル（Red → Green → Refactor）の実践
テストファーストの原則でAIの生成精度が向上

デプロイ：

自然言語でAWSリソースを構築

重要な学び

人間の役割は不可欠：上流工程と品質確保は現段階では人間が担う
仕様とテストが資産：高品質な成果物は次のAI駆動開発で再利用可能

Amazon Web Services. Amazon Q Developer. ↩︎
Xu et al. AI-assisted Programming and Maintenance Burden. arXiv, 2025. ↩︎
Amasanti & Jahić. The Impact of Generative AI-Generated Solutions on Software Maintainability. arXiv, 2025. ↩︎
GitHub. Spec-driven development with AI: Get started with a new open source toolkit. 2024. ↩︎
Mathews et al. Test-Driven Development for Code Generation. arXiv, 2024. ↩︎
Chen et al. TENET: Leveraging Tests Beyond Validation for Code Generation. arXiv, 2025. ↩︎
Classmethod. Amazon Q Developer Pro をメンバーアカウントでサブスクライブ利用してみた. 2024. ↩︎
Ahanoff. Amazon Q Developer を使用した Spec Kit：発見事項と癖. 2024. ↩︎

AIと始めるAWS開発 ― Q Developerで継続的品質保証

2025-11-21T00:00:00.000+00:00

はじめに

前回では、仕様から実装・テスト生成までの流れを体験し、AIがどのようにソフトウェア開発を支援できるかを確認しました。
今回（Day 3）は、その延長として 品質保証 に焦点を当てます。

AIによるコード生成が一般化する中で、重要なのは「どう品質を保証し続けるか」。
Q Developerのレビュー支援機能とメトリクス可視化を使いながら、AIと人間のハイブリッドによる品質保証サイクルを具体的に見ていきましょう。

1. どこを見るか ― 品質観点の棚卸し

まずは「レビューで何を見るのか」を整理します。
これはQ Developerが自動チェックする項目にも関わる部分です。

観点	チェック項目	目的
例外処理	例外の握り潰し・再スロー方針の一貫性	障害解析性を確保
命名規約	クラス名・変数名・ディレクトリ構造の整合性	読解コスト削減
依存関係	循環依存・層違反の有無	構造的健全性の担保
ログ設計	粒度・相関ID・監査性	運用時トレーサビリティの向上
テストの意図	境界条件・オラクルの有無	妥当性と網羅性の保証

2. Q Developerでレビューを回す

コードレビューをAIに依頼する場合、次のようなコマンドで開始します。
サンプルは前回作成したToDoアプリを使用します。

Q Developerを起動します。

# 対話モードを起動
q

レビュー観点をレビューのカテゴリにまとめ、カテゴリ単位でQ Developerに指示を出します。

レビュー観点	レビュー・カテゴリ	説明
例外処理	設計／可読性	例外方針の整合性・例外伝播の扱いは設計扱い
命名規約	可読性	命名揺れ・責務不一致は可読性として指摘される
依存関係	設計	層違反・循環依存などアーキテクチャ的問題
ログ設計	可読性／設計	ログ粒度・相関ID は設計・運用設計の観点
テストの意図	設計／品質（テスト品質）	AI では「テストの妥当性」＝設計・品質問題として扱われる

また、上記表のカテゴリにはありませんが、全体横断的にセキュリティは重要な観点のため、Q Developerへの指示に追加します。

起動後のプロンプトで以下のように入力します。
※ツール実行提案が出た場合、セッション中のみ許可する場合は y、以後も許可する場合は t を選択します。

main.py と test_api.py のコードをレビューしてください。
セキュリティ、可読性、設計の観点で指摘を分類し、修正提案も示してください。

応答：

🛠️  Using tool: fs_read (trusted)
 ⋮
 ● Reading file: /home/ubuntu/todo-fastapi/main.py, all lines
 ✓ Successfully read 1684 bytes from /home/ubuntu/todo-fastapi/main.py

 ⋮
 ● Completed in 0.0s

🛠️  Using tool: fs_read (trusted)
 ⋮
 ● Reading file: /home/ubuntu/todo-fastapi/test_api.py, all lines
 ✓ Successfully read 3155 bytes from /home/ubuntu/todo-fastapi/test_api.py

 ⋮
 ● Completed in 0.0s

> ## コードレビュー結果

### 🔒 セキュリティの問題

main.py:
1. 入力値制限なし
  python
   # 問題: title/descriptionの長さ制限なし
   title: str  # DoS攻撃の可能性

2. レート制限なし
  python
   # 問題: API呼び出し制限なし
   @app.post("/todos")  # 大量リクエスト可能

3. CORS設定なし
  python
   # 問題: クロスオリジン制御なし
   app = FastAPI()  # CORS未設定

test_api.py:
4. ハードコードされたURL
  python
   BASE_URL = "http://localhost:8000"  # 設定ファイル化推奨

### 📖 可読性の問題

main.py:
1. グローバル変数
  python
   # 問題: グローバル状態
   todos = []
   todo_id_counter = 1

2. マジックナンバー
  python
   # 問題: ポート番号ハードコード
   uvicorn.run(app, host="0.0.0.0", port=8000)

test_api.py:
3. 重複コード

python
   # 問題: 同じパターンの繰り返し
   print(f"Create Todo: {response.status_code}")
   print(json.dumps(response.json(), indent=2))

### 🏗️ 設計の問題

main.py:
1. 単一責任原則違反

python
   # 問題: ビジネスロジックとAPI層が混在
   def create_todo(todo: TodoCreate):
       global todo_id_counter  # データ操作がAPI層に

2. スレッドセーフティ
  python
   # 問題: 競合状態の可能性
   todo_id_counter += 1  # 非原子的操作

test_api.py:
3. テスト独立性なし
  python
   # 問題: テスト間の依存関係
   todo_id = test_create_todo()  # 前のテスト結果に依存

## 🔧 修正提案

### セキュリティ改善

🛠️  Using tool: fs_write (trusted)
 ⋮
 ● Path: /home/ubuntu/todo-fastapi/main_improved.py

+     1: from fastapi import FastAPI, HTTPException
+     2: from fastapi.middleware.cors import CORSMiddleware
+     3: from pydantic import BaseModel, Field, validator
+     4: from typing import List, Optional
+     5: from datetime import datetime, timezone

～～～（中略）～～～

+    84: @app.delete("/todos/{todo_id}", status_code=204)
+    85: def delete_todo(todo_id: int = Field(..., gt=0)):
+    86:     if not repo.delete(todo_id):
+    87:         raise HTTPException(status_code=404, detail="Todo not found")
+    88:
+    89: if __name__ == "__main__":
+    90:     import uvicorn
+    91:     uvicorn.run(app, host="127.0.0.1", port=8000)

 ⋮
 ↳ Purpose: Create improved main.py with security enhancements
Creating: /home/ubuntu/todo-fastapi/main_improved.py

 ⋮
 ● Completed in 0.1s

> ### テスト改善

🛠️  Using tool: fs_write (trusted)
 ⋮
 ● Path: /home/ubuntu/todo-fastapi/test_improved.py

+      1: import requests
+      2: import json
+      3: from datetime import datetime, timedelta
+      4: from typing import Dict, Any
+      5:

～～～（中略）～～～

+    121:         # クリーンアップ
+    122:         self.cleanup()
+    123:         self.test_get_todos()
+    124:
+    125: if __name__ == "__main__":
+    126:     tester = TodoAPITester()
+    127:     tester.run_all_tests()

 ⋮
 ↳ Purpose: Create improved test file with better structure
Creating: /home/ubuntu/todo-fastapi/test_improved.py

 ⋮
 ● Completed in 0.3s

> ## 📋 改善点まとめ

### セキュリティ改善
• **入力値制限**: Field()でmin_length/max_length設定
• **CORS設定**: 特定オリジンのみ許可
• **スレッドセーフ**: threading.Lockで排他制御
• **バインドアドレス**: 127.0.0.1に変更（外部アクセス制限）

### 可読性改善
• **責任分離**: TodoRepositoryクラスでデータ操作を分離
• **設定外部化**: 環境変数やクラス初期化で設定管理
• **重複排除**: テストクラスで共通処理をメソッド化

### 設計改善
• **依存性注入**: リポジトリパターン採用
• **テスト独立性**: クリーンアップ機能追加
• **エラーハンドリング**: 適切なHTTPステータスコード使用
• **型安全性**: Field()バリデーション強化

改善版では本格運用に近い品質になっています。

指示したように、AIレビュー結果では以下のように分類されて表示されました。

カテゴリ	例	対応方針
セキュリティ	未処理の例外、ハードコードされた認証情報	優先対応
可読性	命名のばらつき、コメント欠如	対応を検討
設計	クラス肥大化、循環依存	チーム内で合意形成が必要

このようにAIを相手にレビューを実施することが可能です。
ただし、AIの自動修正提案（ツール実行）は “提案”レベルです。
必ず人間が承認する運用にしましょう。

3. メトリクスで「見える化」する

レビューは定性的な活動ですが、Q Developerでは数値指標による定量的管理も可能です。
ここでは、なぜメトリクスが必要なのか、そしてどのように活用すべきかを、より実務的な観点で詳しく説明します。

3.1 メトリクスの役割とは？

メトリクスとは、コード品質や開発プロセスを「数値」で客観的に評価する道具です。
属人的な「なんとなく良さそう」「たぶん問題ない」を排除し、以下の3つを実現します：

現状の可視化（見える化）：改善すべき箇所を定量的に把握できる
改善効果の測定：前回との比較で良くなったかどうかがわかる
基準の共有：チーム全員が同じ尺度で議論できる

特にAIと共存する開発では、生成コードの質にばらつきがあるため、メトリクスは「品質の安定化」に欠かせません。

3.2 主要メトリクスの詳細

ここでは、コード品質を評価する際に特に重要となるメトリクスを整理します。
これらは単なる“数字”ではなく、品質改善の優先順位付けやチーム内での合意形成に欠かせない指標です。
メトリクスの目的や意味を理解しておくことで、レビュー結果をより実務的に活用できます。

指標	目的	目安	詳細説明
静的解析スコア	構文・構造の健全性	90点以上	循環依存、未使用コード、例外処理、セキュリティ問題などを総合評価。点数化することで改善の優先度を決めやすい。
テストカバレッジ	機能網羅率	80%以上	単に数値を見るのではなく、どの関数が未カバーかまで確認するのが重要。重要ロジックは100%を目指す。
コメント率	可読性・ドキュメント性	10〜20%	コメントが「多ければ良い」ではない。コードの意図や設計判断を書き残す“質”が重要。
命名一貫率	品質基準遵守度	95%以上	関数・変数の命名パターンが揃っているか。レビュー時間削減につながる。
変更影響深度	リファクタ容易性	低いほど良い	変更がどれだけ他モジュールへ影響するかを測る。深度が高い＝保守コストが高いコード。

3.3 メトリクスを実際に計測する

前回作成した todo-fastapi/ はモジュール構成が小さいため、まずはテストカバレッジを例にします。
pytestを使用したカバレッジ計測を実施します。

指示：

python main.py
pytest --cov=. --cov-report=xml

応答：

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command: python main.py &
 ⋮
 ↳ Purpose: Start FastAPI server in background

 ⋮
 ● Completed in 0.1s

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
sleep 3 && pytest --cov=. --cov-report=xml
 ⋮
 ↳ Purpose: Wait for server to start and run pytest with coverage

============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-9.0.1, pluggy-1.6.0
rootdir: /home/ubuntu/todo-fastapi
plugins: anyio-4.11.0, cov-7.0.0
collected 8 items

test_api.py ..E.....                                                     [100%]

==================================== ERRORS ====================================
______________________ ERROR at setup of test_delete_todo ______________________
file /home/ubuntu/todo-fastapi/test_api.py, line 24
  def test_delete_todo(todo_id):

～～～（中略）～～～

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
ps aux | grep "python main.py"
 ⋮
 ↳ Purpose: Check if server is running

ubuntu    222074  0.2  0.6 231596 49596 pts/7    Sl+  21:55   0:00 python main.py
ubuntu    224348  0.0  0.0   4756  3248 pts/5    S+   22:02   0:00 bash -c ps aux | grep "python main.py"
ubuntu    224350  0.0  0.0   4100  1992 pts/5    S+   22:02   0:00 grep python main.py
 ⋮
 ● Completed in 0.28s

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
curl -s http://localhost:8000/todos || echo "Server not responding"
 ⋮
 ↳ Purpose: Test server connectivity

[{"id":1,"title":"Test Todo","description":"Test description","priority":"high","due_date":"2025-11-17T21:55:47.625131","created_at":"2025-11-16T21:55:47.632922"},{"id":2,"title":"Minimal Todo","description":null,"priority":"low","due_date":null,"created_at":"2025-11-16T21:55:47.654090"},{"id":5,"title":"Test Todo","description":"Test description","priority":"high","due_date":"2025-11-17T22:02:54.546964","created_at":"2025-11-16T22:02:54.550647"},{"id":6,"title":"Minimal Todo","description":null,"priority":"low","due_date":null,"created_at":"2025-11-16T22:02:54.575022"}]
 ⋮
 ● Completed in 0.16s

> ✅ サーバーが起動し、テストが実行されました

結果:
• **サーバー**: 正常起動中（PID 222074）
• **XMLレポート**: Coverage XML written to file coverage.xml - 成功
• **テスト**: 7つ成功、1つエラー（fixture問題）
• **API**: 正常動作（Todoデータが存在）

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
pkill -f "python main.py"
 ⋮
 ↳ Purpose: Stop the server

 ⋮
 ● Completed in 0.15s

> サーバーを停止しました。XMLカバレッジレポートが正常に生成されています。

これにより coverage.xml が生成されます。

3.4 coverage.xml を Q Developer に解析させる（対話）

対話モードで、次のように依頼します：

coverage.xml を読み込み、
・関数ごとのカバレッジ
・未テスト箇所の一覧
・優先的に追加すべきテストケースの提案
・複雑度の高い関数ランキング
を出してください。

Q Developer は内部ツール（fs_read / analyze_code）を使い、以下を返します：

どの関数が未カバーか
条件分岐のテスト不足
異常系・境界テストの欠落
テスト追加の具体例（パラメータ例まで出ることが多い）

応答：

🛠️  Using tool: fs_read (trusted)
 ⋮
 ● Reading file: /home/ubuntu/todo-fastapi/coverage.xml, all lines
 ✓ Successfully read 4891 bytes from /home/ubuntu/todo-fastapi/coverage.xml
 ⋮
 ● Completed in 0.0s

～～～（中略）～～～

問題: サーバーが起動していたにも関わらず、main.pyのカバレッジが0%のままです。これは、テストがHTTPリクエストを送信しているだけで、pytestがmain.pyのコードを直接実行していないためです。TestClientを使用することで解決できます。

どうやら、カバレッジが正しく収集できないようです。
Q Developerは単に「できません」と言うだけでなく、解決案の提示もしてくれます。

Q Developerの進言に従って、TestClientを使用するように依頼します。

指示：

TestClientを使用するように変更してください

応答：

🛠️  Using tool: fs_write
 ⋮
 ● Path: test_api.py

-  0    : import requests
+      0: from fastapi.testclient import TestClient
   1,  1: import pytest
   2,  2: from datetime import datetime
+      3: from main import app
   3,  4:
-  4    : BASE_URL = "http://localhost:8000"
+      5: client = TestClient(app)
   5,  6:
   6,  7: def test_create_todo():
   7,  8:     todo_data = {
   8,  9:         "title": "Test Todo",
   9, 10:         "description": "Test description",
  10, 11:         "priority": "high",
  11, 12:         "due_date": "2025-11-17T12:00:00"
  12, 13:     }

～～～（中略）～～～

Coverage XML written to file coverage.xml
========================= 8 passed, 1 warning in 1.17s =========================
 ⋮
 ● Completed in 1.557s

> ✅ TestClientを使用したテストが成功しました！

結果:
• **httpx**: インストール完了
• **テスト**: 8つ全て成功
• **XMLレポート**: Coverage XML written to file coverage.xml - 成功
• **実行時間**: 1.17秒
• **警告**: Pydantic V1 validator使用の警告のみ

TestClientを使用することで、サーバー起動なしでAPIテストが実行でき、main.pyのコードカバレッジも測定されるようになりました

カバレッジが収集されたので、再度以下のように依頼します。

coverage.xml を読み込み、
・関数ごとのカバレッジ
・未テスト箇所の一覧
・優先的に追加すべきテストケースの提案
・複雑度の高い関数ランキング
を出してください。

応答：

🛠️  Using tool: fs_read (trusted)
 ⋮
 ● Reading file: /home/ubuntu/todo-fastapi/coverage.xml, all lines
 ✓ Successfully read 4181 bytes from /home/ubuntu/todo-fastapi/coverage.xml
 ⋮
 ● Completed in 0.0s

> ## カバレッジ分析結果

### 📊 全体カバレッジ
• **総合カバレッジ**: 97.87% (92/94行) - 大幅改善！
• **main.py**: 95.83% (46/48行)
• **test_api.py**: 100% (46/46行)

### 🔍 関数ごとのカバレッジ

#### main.py (95.83%カバレッジ)
• create_todo() (38-48行): ✅ 完全テスト済み
• get_todos() (49-51行): ✅ 完全テスト済み
• delete_todo() (57-63行): ✅ 完全テスト済み
• validate_due_date() (24-28行): ✅ 完全テスト済み

#### test_api.py (100%カバレッジ)
• 全テスト関数が実行済み

### ❌ 未テスト箇所の一覧

#### main.py (わずか2行未テスト)
1. 66行: import uvicorn
2. 67行: uvicorn.run(app, host="0.0.0.0", port=8000)

これらはif __name__ == "__main__"ブロック内のサーバー起動コードで、テスト時には実行されません。

### 🎯 優先的に追加すべきテストケース

#### 低優先度（既に高カバレッジのため）
1. エッジケースの追加
   • 空文字列タイトル
   • 極端に長いタイトル/説明
   • 境界値テスト

2. エラーハンドリングの詳細テスト
   • 不正なJSON形式
   • 型変換エラー

3. パフォーマンステスト
   • 大量データでの動作確認

### 📈 複雑度の高い関数ランキング

#### 1位: create_todo() (main.py 38-48行)
• **複雑度**: 高
• **カバレッジ**: ✅ 100%
• **理由**: グローバル変数操作、オブジェクト生成、リスト操作、カウンター管理
• **行数**: 11行

#### 2位: delete_todo() (main.py 57-63行)
• **複雑度**: 中高
• **カバレッジ**: ✅ 100%
• **理由**: ループ処理、条件分岐、例外処理、リスト操作
• **行数**: 7行

#### 3位: validate_due_date() (main.py 24-28行)
• **複雑度**: 中
• **カバレッジ**: ✅ 100%
• **理由**: 条件分岐、日時比較、例外発生
• **行数**: 5行

#### 4位: get_todos() (main.py 49-51行)
• **複雑度**: 低
• **カバレッジ**: ✅ 100%
• **理由**: 単純なリスト返却
• **行数**: 3行

### 🎉 成果

TestClient導入により劇的改善:
• **カバレッジ**: 35.96% → 97.87% (+61.91%)
• **main.py**: 0% → 95.83% (+95.83%)
• **全テスト**: 成功（8/8）
• **実行時間**: 高速化（サーバー起動不要）

### 💡 推奨アクション

1. 現状維持 - 既に優秀なカバレッジ
2. コード品質向上
   • Pydantic V2への移行（警告解消）
   • 型ヒントの追加
3. 統合テストの追加
   • 複数操作の組み合わせテスト
4. ドキュメント整備
   • API仕様書の作成

結論: TestClientの導入により、ほぼ完璧なテストカバレッジを達成しました。残りの2行は実行時コードのため、実質的に100%のカバレッジです。

無事にカバレッジを収集することができました。

3.5 メトリクスをどう改善に活かすか

メトリクスは“数値を見ること”が目的ではありません。
むしろ、メトリクスは 「どこから改善すれば最も効果が高いのか」 を示す“改善ナビゲーション”です。
数値が示す意味を正しく理解し、次のアクションへつなげることで、品質改善サイクルが加速します。

以下では、代表的なメトリクスからどのように改善につなげるかを、より具体的に説明します。

改善のために以下のように使います：

低カバレッジ関数 → 追加テストを作成
カバレッジが低いということは、挙動を保証するテストが不足している状態です。特にビジネスロジックやバリデーション処理など、バグが入りやすい部分は優先的にテストを追加します。
例：create_todo() が0% → POST /todos の正常系・異常系テストを追加
複雑度の高い関数 → まずは分割（リファクタ）
複雑度が高い関数は読みづらく、バグが入りやすい上にテストもしづらい傾向があります。
責務を分割したり、共通処理をメソッド化することで可読性が向上し、結果的にテストもしやすくなります。
例：create_todo() に状態管理・バリデーション・登録処理が混在 → 役割ごとに関数分離
命名揺れ → コード規約をAIに与えて揃える
命名規約のばらつきは理解コストを上げ、レビュー時間を増大させます。
Q Developer に命名規約（例：snake_case / camelCase、略語ルール）を伝えておけば、一貫性のない命名を自動で指摘させることも可能です。
また、プロジェクトに合わせて命名変更案をAIが自動生成してくれます。
変更影響深度が高い箇所 → 設計見直しを検討
「この関数を変えると他の10ファイルが壊れる」という状態は、保守性の低さを表します。
依存関係の整理、責務分離、アーキテクチャ層の明確化などを検討し、影響範囲を意図的に小さくしていきます。

また、メトリクスは改善結果を“数字で説明できる”ため、「なぜその改善が必要なのか？」をチームに説明しやすくなります。
定量化により、改善ポイントが明確になり、チーム内での合意形成が容易になります。

このように、どれだけのコードがカバーできているのかを「定量的」に見極めながら、品質を維持しつつ機能を拡張・検証していくことが可能になります。

4. メトリクス駆動のハイブリッドレビュー運用モデル

AI と人間、それぞれの強みを活かしつつ、定量的メトリクスを軸に品質保証サイクルを回すための運用モデルです。
従来のレビューでは人の経験や勘に依存していましたが、メトリクスを導入することで「観点の統一」「効果測定」「改善の優先順位付け」が可能になり、AI との組み合わせによって品質保証を持続的に行えるようになります。

AI レビューは網羅性と速度に優れ、一方でメトリクスは改善の指針として機能します。
最終判断は人間が行い、AI × メトリクス × 人間の判断によって再現性と持続性のある品質保証が成立します。

まとめ

今回の最大の成果は、メトリクスによって品質を“定量的に”評価できるようになったことです。
これにより、これまで感覚的・属人的だったレビュー活動が、数字を用いた客観的な改善サイクルへと進化しました。

特に以下の点が大きな前進です：

静的解析スコア、カバレッジ、複雑度、命名一貫率といった指標により、レビューの“抜け漏れ”が可視化された
数値をもとに「どこを優先して直すべきか」が判断できるようになり、改善活動の効率が向上した
AIによるレビュー提案と人間の判断を組み合わせることで、品質改善プロセスを継続的に回せる基盤ができた

これらにより、レビュー精度のばらつきが減り、品質改善のPDCAがデータに基づいて回る状態へと近づきました。

皆さまの生成AI活用の参考になれば幸いです。

AIと始めるAWS開発 ― Q Developerで体験する仕様駆動テスト

2025-11-17T00:00:00.000+00:00

はじめに

前回は、Q Developerを使って簡単なアプリケーションをインタラクティブモードで作成しました。
今回の記事では、Q Developerをさらに一歩掘り下げ、仕様 → 実装 → テスト生成 → 修正 の一連の工程を通じて、AIがどのようにソフトウェア開発を支援するのかを確認します。
とくに焦点を当てるのは、テスト可能な仕様（バリデーション） の考え方です。
AIが生成するテストがどこまで自動化できるのか、そして人間の開発者がどの段階で介入し、品質を保証すべきなのかを、実際のプロセスを通して検証していきます。

この記事を読むことで、次のような理解が得られるでしょう。

Q Developerが仕様からテストまで自動化できる範囲
AIによる自動テスト生成の利点と限界
テスト可能な仕様を設計する際の実務的なポイント
人が介在すべき判断ポイントと品質保証の勘どころ

使用するQ Developerのバージョンは「1.13.0」を想定しています。
それでは、AIが関わるテスト自動化を具体的に見ていきましょう。

1. シンプルなToDoアプリを作る

1.1 Q Developer を対話モードで起動

作業ディレクトリを作成し、qを起動します。

mkdir todo-fastapi && cd todo-fastapi
q

起動後のプロンプトに、以下のメッセージを貼り付けます。

指示：

FastAPIを使ってシンプルなToDoアプリケーション (登録・一覧・削除 API) を作成するためのPythonスクリプトを生成してください。
ファイル名は main.py と test_api.py です。
DBはメモリ、Pydanticでバリデーションを行い、
priorityは low/medium/high、
due_date は未来日チェックを含めてください。

応答：

🛠️  Using tool: fs_write
 ⋮
 ● Path: /home/ubuntu/todo-fastapi/main.py

+     1: from fastapi import FastAPI, HTTPException
+     2: from pydantic import BaseModel, validator
+     3: from typing import List, Optional
+     4: from datetime import datetime
+     5: from enum import Enum
+     6:
+     7: app = FastAPI()
+     8:
+     9: # In-memory database
+    10: todos = []

～～～（中略）～～～

+    57: @app.delete("/todos/{todo_id}")
+    58: def delete_todo(todo_id: int):
+    59:     for i, todo in enumerate(todos):
+    60:         if todo.id == todo_id:
+    61:             del todos[i]
+    62:             return {"message": "Todo deleted successfully"}
+    63:     raise HTTPException(status_code=404, detail="Todo not found")
+    64:
+    65: if __name__ == "__main__":
+    66:     import uvicorn
+    67:     uvicorn.run(app, host="0.0.0.0", port=8000)

 ⋮
 ↳ Purpose: Create FastAPI ToDo application with registration, listing, and deletion APIs

Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:

> t

Creating: /home/ubuntu/todo-fastapi/main.py

 ⋮
 ● Completed in 0.0s

🛠️  Using tool: fs_write (trusted)
 ⋮
 ● Path: /home/ubuntu/todo-fastapi/test_api.py

+     1: import requests
+     2: import json
+     3: from datetime import datetime, timedelta
+     4:
+     5: BASE_URL = "http://localhost:8000"
+     6:
+     7: def test_create_todo():
+     8:     todo_data = {
+     9:         "title": "Test Todo",
+    10:         "description": "Test description",

～～～（中略）～～～

+    50:
+    51:     # Test invalid due date
+    52:     test_invalid_due_date()
+    53:     print()
+    54:
+    55:     # Test deleting a todo
+    56:     test_delete_todo(todo_id)
+    57:     print()
+    58:
+    59:     # Verify deletion
+    60:     test_get_todos()

 ⋮
 ↳ Purpose: Create test file for the FastAPI ToDo application
Creating: /home/ubuntu/todo-fastapi/test_api.py

 ⋮
 ● Completed in 0.0s

> FastAPIを使ったシンプルなToDoアプリケーションを作成しました。

main.py の主な機能:
• POST /todos: ToDo登録 (タイトル、説明、優先度、期限日)
• GET /todos: ToDo一覧取得
• DELETE /todos/{todo_id}: ToDo削除
• Pydanticでバリデーション (優先度: low/medium/high、期限日: 未来日チェック)
• メモリ内データベース

test_api.py でAPIテストが可能です。

アプリケーションを起動するには:
bash
python main.py

テストを実行するには (別ターミナルで):
bash
python test_api.py

指示通りにPythonファイル main.py と test_api.py が作成されました。

1.2 生成コードの確認と適用

結果を確認します。
Q を起動しているフォルダ（作業ディレクトリ）上に main.py と test_api.py が保存されています。

※もし Q Developer が「ツール実行（ファイル作成）」を提案した場合は、yes で許可します。

依存ライブラリをインストールします。
これも Q Developer に実施してもらいます。

指示：

アプリケーションを動かすのに必要なPythonライブラリをインストールしてください

応答：

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command: python main.py
 ⋮
 ↳ Purpose: Start the FastAPI ToDo application

Traceback (most recent call last):
  File "/home/ubuntu/todo-fastapi/main.py", line 1, in <module>
    from fastapi import FastAPI, HTTPException
ModuleNotFoundError: No module named 'fastapi'

 ⋮
 ● Completed in 0.11s

> FastAPIがインストールされていないようです。インストールします:

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
pip install fastapi uvicorn requests
 ⋮
 ↳ Purpose: Install FastAPI and required dependencies

～～～（中略）～～～

Using cached uvicorn-0.38.0-py3-none-any.whl (68 kB)
Downloading typing_extensions-4.15.0-py3-none-any.whl (44 kB)
Downloading typing_inspection-0.4.2-py3-none-any.whl (14 kB)
Installing collected packages: uvicorn, typing-extensions, typing-inspection, pydantic-core, pydantic, fastapi
  Attempting uninstall: typing-extensions
    Found existing installation: typing_extensions 4.13.2
    Uninstalling typing_extensions-4.13.2:
      Successfully uninstalled typing_extensions-4.13.2
  Attempting uninstall: typing-inspection
    Found existing installation: typing-inspection 0.4.0
    Uninstalling typing-inspection-0.4.0:
      Successfully uninstalled typing-inspection-0.4.0
  Attempting uninstall: pydantic-core
    Found existing installation: pydantic_core 2.33.2
    Uninstalling pydantic_core-2.33.2:
      Successfully uninstalled pydantic_core-2.33.2

Successfully installed fastapi-0.121.1 pydantic-2.12.4 pydantic-core-2.41.5 typing-extensions-4.15.0 typing-inspection-0.4.2 uvicorn-0.38.0

[notice] A new release of pip is available: 25.1.1 -> 25.3
[notice] To update, run: pip install --upgrade pip

 ⋮
 ● Completed in 7.388s

> ライブラリのインストールが完了しました。アプリケーションを起動できます:

bash
python main.py

動作確認を行います。
アプリケーションを別コンソールから実行します。

python main.py

ブラウザまたは curl で次を確認します。

curl http://127.0.0.1:8000/todos

まだデータは空なので結果として「[]」（空データ）が出力されるはずです。
1章では「AIに自然言語で仕様を伝え、コードを自動生成させる」までを実施しました。
次にコードを前提に、仕様を改めて明文化し、テストで検証できるようにします。

2. バリデーション強化 ― テスト可能な仕様にする

次の2つの仕様を改めて明文化します。

due_date は「未来日」でなければならない
priority は low, medium, high のいずれかである

AIに対しては、以下のように日本語で伝えます。

指示：

Taskモデルにバリデーションを追加してください。due_dateは未来日でなければならず、priorityはlow・medium・highのいずれかのみ許可してください。

応答：

> 既存のコードにはバリデーションが実装されていますが、より明確にするために確認・改善します:

🛠️  Using tool: fs_read (trusted)
 ⋮
 ● Reading file: /home/ubuntu/todo-fastapi/main.py, from line 10 to 30
 ✓ Successfully read 469 bytes from /home/ubuntu/todo-fastapi/main.py

 ⋮
 ● Completed in 0.0s

～～～（中略）～～～

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
pkill -f "python main.py"
 ⋮
 ↳ Purpose: Stop the background FastAPI process

 ⋮
 ● Completed in 0.48s

> バリデーションは既に正しく実装されており、動作しています:

1. priority: Priority Enumにより low、medium、high のみ許可
2. due_date: 過去日を指定すると422エラーで「due_date must be in the future」メッセージが返される

テスト結果で確認できるように:
• 有効なデータ: 正常に作成 (200)
• 無効な過去日: バリデーションエラー (422)

現在のコードで要求されたバリデーションは完全に実装されています。

このように、コードを前提に、仕様を改めて明文化し、テストで検証できるようになりました。

これまで1章、2章で実施した内容をまとめると以下のようになります。

章	フェーズ	意図	役割
1章	実装生成	AIに自然言語で仕様を伝え、コードを自動生成させる	「生成の正確さ」を観察
2章	仕様検証	コードを前提に、仕様を改めて明文化・テストで検証	「仕様のテスト化」を学ぶ

3. サーバ実行とテスト

では、実際にアプリケーションを動かして、テストを実施してみましょう。
（テストの内容については、この後の章で説明します）

アプリケーションをローカルで実行します

python main.py

次にテストを実行します。

python test_api.py

実行結果は以下のようになりました。

Testing FastAPI Todo App
==============================
Create Todo: 200
{
  "id": 1,
  "title": "Test Todo",
  "description": "Test description",
  "priority": "high",
  "due_date": "2025-11-10T22:59:37.092516",
  "created_at": "2025-11-09T22:59:37.099295"
}

Get Todos: 200
[
  {
    "id": 1,
    "title": "Test Todo",
    "description": "Test description",
    "priority": "high",
    "due_date": "2025-11-10T22:59:37.092516",
    "created_at": "2025-11-09T22:59:37.099295"
  }
]

Invalid Due Date: 422
{
  "detail": [
    {
      "type": "value_error",
      "loc": [
        "body",
        "due_date"
      ],
      "msg": "Value error, due_date must be in the future",
      "input": "2025-11-08T22:59:37.104030",
      "ctx": {
        "error": {}
      }
    }
  ]
}

Delete Todo: 200
{
  "message": "Todo deleted successfully"
}

Get Todos: 200
[]

テストの戻り値「200」「422」が確認できていることがわかります。

4. AI生成テストを読み解く

AIは仕様文からテストを推論します。
今回作成されたテストケースは以下の通りです。

def test_create_todo():
    todo_data = {
        "title": "Test Todo",
        "description": "Test description",
        "priority": "high",
        "due_date": (datetime.now() + timedelta(days=1)).isoformat()
    }
    response = requests.post(f"{BASE_URL}/todos", json=todo_data)
    print(f"Create Todo: {response.status_code}")
    print(json.dumps(response.json(), indent=2))
    return response.json()["id"]

def test_get_todos():
    response = requests.get(f"{BASE_URL}/todos")
    print(f"Get Todos: {response.status_code}")
    print(json.dumps(response.json(), indent=2))

def test_delete_todo(todo_id):
    response = requests.delete(f"{BASE_URL}/todos/{todo_id}")
    print(f"Delete Todo: {response.status_code}")
    print(json.dumps(response.json(), indent=2))

def test_invalid_due_date():
    todo_data = {
        "title": "Invalid Todo",
        "priority": "low",
        "due_date": (datetime.now() - timedelta(days=1)).isoformat()
    }
    response = requests.post(f"{BASE_URL}/todos", json=todo_data)
    print(f"Invalid Due Date: {response.status_code}")
    print(json.dumps(response.json(), indent=2))

これらのテストは基本的には正しく動作しますが、AIが自動生成したものを鵜呑みにせず、人間の観点でレビューすることが極めて重要です。
AIの推論は仕様文から妥当なロジックを導き出しますが、暗黙的な前提や境界条件までは十分に理解していないことが多いためです。

以下の観点でレビューを行うと、テストの品質を一段高めることができます。

観点	チェック内容	対応方針
仕様整合性	未来日境界（今日の日付は有効か？）、入力制約は明確か？	境界テストを追加する
可読性	テスト名が仕様を説明しているか、期待結果が明示されているか	名前やprint内容を改善する
網羅性	`low`, `medium`, `high` の正常系が揃っているか、異常系が網羅されているか	不足分を追加生成させる
独立性	各テストが他テストの結果に依存していないか	前提データ作成・削除処理を分離する
再現性	実行順序や時刻依存で結果が変わらないか	固定日時やID管理の仕組みを導入

AIが生成するテストは、仕様記述をもとに 「最も一般的なケース」 を推論する傾向があります。
そのため、

境界条件（当日や閾値など）
エラー系（不正値、欠損値、異常なリクエスト）
並行動作や排他制御の確認

といった “仕様の周縁部” を十分に網羅できていないケースが多いです。

AIに「境界テストも追加して」と明示すれば生成されますが、重要なのは「何を境界とみなすか」を人が定義することです。
AIは仕様書の文章を解析してロジックを作りますが、その仕様書自体が不完全であれば、テストも不完全なままになります。

5. テスト補完（人手で対応）

AIが生成したテストコードは、いわば “骨格” です。
そこに仕様の解釈・リスクベース思考・品質観点を肉付けするのが人間の役割です。
とくに、次の3点を意識すると品質が安定します。

仕様理解の再確認：AIが実装した内容と意図した仕様が一致しているか。
異常系の強化：予期しない入力や外れ値をどう扱うかを明示する。
テスト設計の再利用性：後続の機能追加でも使える汎用構造に整理する。

FastAPIのToDoアプリが動作し、基本テストが通ったら、次は不足しているテストケース（境界・異常系） を補います。
ここでは、AIの提案に頼るのではなく、人が意図をもってテストを追加する手順を示します。

テスト対象：

due_date が「今日」→ 無効（未来日限定）
priority に不正値 → 無効（low / medium / high のみ許可）
正常系3種（low, medium, high）を網羅

def test_due_date_today_invalid():
    """今日の日付を指定した場合の検証（422想定）"""
    todo_data = {
        "title": "Today Todo",
        "priority": "low",
        "due_date": datetime.now().isoformat()
    }
    response = requests.post(f"{BASE_URL}/todos", json=todo_data)
    print(f"Due Date Today Invalid: {response.status_code}")
    try:
        print(json.dumps(response.json(), indent=2))
    except Exception:
        print(response.text)

def test_priority_invalid_value():
    """priority に不正値を指定した場合の検証（422想定）"""
    todo_data = {
        "title": "Invalid Priority Todo",
        "priority": "urgent",  # 許可値: low/medium/high のみ
        "due_date": (datetime.now() + timedelta(days=1)).isoformat()
    }
    response = requests.post(f"{BASE_URL}/todos", json=todo_data)
    print(f"Invalid Priority: {response.status_code}")
    try:
        print(json.dumps(response.json(), indent=2))
    except Exception:
        print(response.text)

6. テスト補完（AIに依頼）

5章では人手でテストケースを拡充しましたが、AIにテストケースの補完が可能かどうかを確認してみます。

指示：

テストケースが十分かどうかを確認してください

応答：

> 現在のテストケースを確認し、不足している部分を特定します:

🛠️  Using tool: fs_read (trusted)
 ⋮
 ● Reading file: /home/ubuntu/todo-fastapi/test_api.py, all lines
 ✓ Successfully read 1661 bytes from /home/ubuntu/todo-fastapi/test_api.py

 ⋮
 ● Completed in 0.0s

> 現在のテストケースは基本的な機能のみをカバーしています。不足しているテストケースを追加します:

🛠️  Using tool: fs_write (trusted)
 ⋮
 ● Path: test_api.py

  29, 29: def test_invalid_due_date():
  30, 30:     todo_data = {
  31, 31:         "title": "Invalid Todo",
  32, 32:         "priority": "low",
  33, 33:         "due_date": (datetime.now() - timedelta(days=1)).isoformat()

～～～（中略）～～～

+     107:     # Delete minimal todo if created
+     108:     if minimal_id:
+     109:         test_delete_todo(minimal_id)
+     110:         print()
+     111:
  91, 112:     # Verify deletion
  92, 113:     test_get_todos()

 ⋮
 ↳ Purpose: Update main test execution to include all test cases
Updating: test_api.py

 ⋮
 ● Completed in 0.0s

> 追加したテストケース:

バリデーションテスト:
• test_invalid_priority(): 無効な優先度 ("urgent") をテスト
• test_missing_title(): 必須フィールド (title) の欠如をテスト
• test_minimal_todo(): 最小限の必須フィールドのみでの作成をテスト

エラーハンドリングテスト:
• test_delete_nonexistent(): 存在しないToDo削除時の404エラーをテスト

テストカバレッジ:
• 正常系: 完全なToDo作成、最小限のToDo作成、一覧取得、削除
• 異常系: 過去日、無効な優先度、必須フィールド欠如、存在しないID削除

これで主要なバリデーションとエラーケースがカバーされます。

追加されたテストを実行してみましょう。

指示：

テストを実行してください

応答：

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command: python main.py &
 ⋮
 ↳ Purpose: Start FastAPI application in background

 ⋮
 ● Completed in 0.3s

～～～（中略）～～～

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
pkill -f "python main.py"
 ⋮
 ↳ Purpose: Stop the background FastAPI process

 ⋮
 ● Completed in 0.15s

> テスト結果の分析:

✅ 正常系テスト:
• 完全なToDo作成: 200 OK
• 最小限のToDo作成: 200 OK (description, due_dateはnull)
• 一覧取得: 200 OK
• ToDo削除: 200 OK

✅ バリデーションテスト:
• 過去日指定: 422エラー "due_date must be in the future"
• 無効な優先度: 422エラー "Input should be 'low', 'medium' or 'high'"
• 必須フィールド欠如: 422エラー "Field required"

✅ エラーハンドリングテスト:
• 存在しないToDo削除: 404エラー "Todo not found"

すべてのテストケースが期待通りに動作しており、バリデーションとエラーハンドリングが正しく実装されています。テストカバレッ
ジは十分です。

このようにAIと対話を進めながら、テストケースを拡充していくこともできます。
AIとペアでプログラミングできる日が来るとは、すごい時代になりました。

まとめ

AIが提案するテストはあくまで「たたき台」です。
人が仕様理解と品質観点でレビューし、採用・修正・削除の判断を行うことが重要です。

観点	採用すべき提案	却下すべき提案
仕様整合性	未来日・優先度の要件を正確に守る	曖昧な条件を含む（例：今日を許可）
可読性	テスト名・変数名が直感的	意味不明な略語や複雑なロジック
保守性	簡潔で再利用可能	重複コードや不要な依存関係を含む
実行容易性	`python test_api.py` で完結	外部サーバ起動が必要

これがQ Developerによる“品質管理の自動化”を成立させる鍵です。

皆さまの生成AI活用の参考になれば幸いです。

SSH穴あけ不要！Cloudflare Tunnel でお家 Ubuntu Desktop へのセキュアな CD パイプラインを構築したい！

2025-11-17T00:00:00.000+00:00

はじめに

最近、Ubuntu Desktop 用にノートPCを購入しました。自宅で Web アプリケーションをホストしてみたいと思ったのがきっかけです。

購入後、早速 Apache Web サーバーをインストールし、/var/www/html/index.htmlを直接編集してブラウザからアクセスしてみました。思った通りに表示されるのを見て、「これは楽しい！」と感じたのを覚えています。

しかし、このままでは問題があります。この状態で外部にページを公開すると、編集内容が即座に本番環境へ反映されてしまうということです。つまり、開発中の未完成なコードや、テスト用のデータが訪問者に見えてしまう可能性があります。

「開発環境と本番環境を分けたい...！」

そこで、Apache Web サーバーの公開ディレクトリとは別に開発用のディレクトリを作成し、そちらで開発を進めることにしました。同時に Git/GitHub を使ったバージョン管理も導入し、一般的なdevブランチからmainブランチへのプルリクエスト・マージという開発フローも採用しました。

しかし、新たな問題が発生しました。この開発フローを取り入れたことで、開発が完了するたびに開発ディレクトリから公開ディレクトリへの手動コピー&ペースト作業が必要になったのです。GitHub 上でプルリクエストをマージさせつつ、手元のローカルリポジトリのmainブランチを基準にして、開発ディレクトリから公開ディレクトリへの手動コピー&ペーストを行う必要があります。流石にこれは面倒です。

「プルリクエストをマージしたら、更新内容が自動的に Apache Web サーバーの公開ディレクトリに反映されてほしい...！」

この面倒な手作業をなんとか自動化できないかと考えた結果、GitHub Actions による CD パイプラインを構築することにしました。

本記事では、GitHub Actions を用いて自宅 LAN 内の Ubuntu Desktop に対する継続的デプロイメント（CD）パイプラインの構築経験を、具体的な設定手順も併せて解説したいと思います。

構築するパイプライン

本記事で構築する CD パイプラインは、以下のような仕組みで動作します。

実現される動作フロー

graph TD
    A[コード編集] --> B[dev ブランチにコミット]
    B --> C[GitHub で PR 作成]
    C --> D[PR を main にマージ]
    D --> E[GitHub Actions 自動起動]
    E --> F[自宅サーバーに自動デプロイ]
    F --> G[本番環境に反映完了]

    style A fill:#e1f5fe
    style D fill:#fff3e0
    style G fill:#c8e6c9

手動で行っていた「開発ディレクトリから公開ディレクトリへのコピー&ペースト」が、プルリクエストのマージをトリガーに完全自動化されます。

システム構成

graph TD
    A[GitHub Actions Runner] --> B[Cloudflare Edge]
    B --> C[Cloudflare Tunnel]
    C --> D[自宅 Ubuntu Desktop]
    D --> E[Apache Web Server]

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#fff3e0
    style D fill:#c8e6c9
    style E fill:#c8e6c9

コンポーネント	役割
GitHub Actions	マージをトリガーにデプロイワークフローを実行
Cloudflare Tunnel	自宅 IP を公開せずに安全な通信経路を提供
Cloudflare Access	Service Token による自動認証を実現
SSH + rsync	変更されたファイルのみを効率的に同期

完成後にできること

✅ プルリクエストをマージするだけで本番環境に自動反映
✅ 自宅のパブリック IP アドレスを公開せずに安全に運用
✅ デプロイ履歴が GitHub Actions のログに自動記録
✅ 手動デプロイ作業から完全に解放

この記事の前提条件

本記事は以下の知識・環境をお持ちの方を対象としています。

必要な知識

GitHub Actions の基本: workflow ファイルの書き方や基本的なアクションの使い方
Linux の基本操作: コマンドライン操作、ファイル権限、SSH 接続の概念
Apache Web サーバーの基本: DocumentRoot の概念、基本的な設定
Git の基本: ブランチ、プルリクエスト、マージの概念

必要な環境

GitHub リポジトリ: プライベート・パブリックは問いません
Ubuntu Desktop 環境: 今回は Ubuntu 24.04.3 LTS を想定
Apache Web サーバー: インストール・設定済み
Cloudflare アカウント: Cloudflare Zero Trust の利用を想定
独自ドメイン: ネームサーバーが Cloudflare に設定されているドメインであること

必要な技術概念と知識

パイプラインを構築する前に、関連する技術概念を整理します。

GitHub Actions Workflows

GitHub Actions は、GitHub リポジトリ内で CI/CD パイプラインを実行するためのプラットフォームです。

https://docs.github.com/ja/actions/get-started/understand-github-actions

重要な概念

ワークフロー: .github/workflows/ 内のYAMLファイルで定義された1つ以上のジョブを実行するプロセス
イベント: ワークフローをトリガーする、リポジトリ内の特定のアクティビティ（例えばプルリクエストのマージ）
ジョブ: 同じランナーで実行される、ワークフロー内の一連のステップ
アクション: ワークフロー内で特定のタスクを実行するコンポーネント (GitHub Actions で提供されるものや、自作のものを使用できる)
ランナー: ワークフローを実行する仮想環境。各ランナーは一度に1つのジョブを実行できる。(今回は ubuntu-latest を使用します)

SSH 接続とセキュリティ

SSH（Secure Shell）の基本

SSH は暗号化された通信路を使ってリモートサーバーに安全に接続するプロトコルです。

ホスト認証

SSH クライアント側で、接続先が本物の SSH サーバーであることを確認する。

ホスト認証の仕組み

SSH サーバーにはホスト鍵(host key)という固有の秘密鍵/公開鍵ペアが設定されている。
SSH クライアント側でこの公開鍵を保存する先が、~/.ssh/known_hostsファイル。

初回接続時に、SSH サーバーのホスト鍵 (公開鍵) を SSH クライアント側の~/.ssh/known_hostsファイルに追加する。
その後の接続時に、このファイルに登録されているホスト鍵 (公開鍵) と SSH サーバーのホスト鍵 (秘密鍵) を比較して、接続先が本物の SSH サーバーであることを確認する。

ユーザー認証

SSH サーバー側で、接続してきた SSH クライアントのユーザーが本物のユーザーであることを確認する。

ユーザー認証の仕組み

公開鍵認証方式を使用する。
ざっくりなイメージは以下のとおり。

SSH サーバーは、許可された SSH クライアントの公開鍵を~/.ssh/authorized_keysファイルに保持している。
SSH クライアントは、自身の秘密鍵を使用して署名を生成する。
SSH サーバーは、SSH クライアントの公開鍵を使用して署名を検証する。
署名が検証された場合、SSH サーバーは SSH クライアントのユーザーとして接続を許可する。

https://qiita.com/whoami_priv/items/9f165f8dfd95edb169b7

https://qiita.com/pyon_kiti_jp/items/f89b8fa9f5b7f8abac23

Information

今回の SSH 接続における役割

SSH クライアント: GitHub Actions のランナー環境 (ubuntu-latest)
SSH サーバー: 自宅の Ubuntu Desktop

なぜこの関係になるのか？

GitHub Actions のワークフローは GitHub のクラウド環境で実行されます。
したがって、クラウド環境からみて外部のサーバー(自宅の Ubuntu Desktop)にファイルをデプロイするには、GitHub Actions ランナーから自宅サーバーに向けて SSH 接続を開始する必要があります。
つまり、「クラウド → 自宅」という方向での接続となり、GitHub Actions ランナーが接続を開始する側(クライアント)、自宅 Ubuntu Desktop が接続を受ける側(サーバー)となります。

Cloudflare Tunnel

Cloudflare Tunnel とは

Cloudflare Tunnel は、パブリック IP アドレスを公開することなく、ローカルサーバーを安全にインターネットに公開できるサービスです。

https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/

https://qiita.com/keke21/items/efaa2b2c35dfb646a43e

従来の自宅サーバー公開方法との違い

従来の方法（ポートフォワーディング）：

インターネット → ルーター（ポート22開放） → 自宅 Ubuntu Desktop
                    ↑ セキュリティリスク

❌️ ルーターで SSH ポート(22番)を開放する必要
❌ パブリック IP アドレスが直接露出
❌ DDoS 攻撃やブルートフォース攻撃の標的になりやすい
❌ 自宅の IP アドレスが特定される可能性

Cloudflare Tunnel を使った方法：

GitHub Actions → Cloudflare Edge → Cloudflare Tunnel → 自宅 Ubuntu Desktop
                                       ↑
                               暗号化されたトンネル

✅️ ルーターでポートを開放する必要がない
✅️ パブリック IP アドレスを隠匿
✅️ Cloudflare のセキュリティ機能を活用
✅️ トラフィックが Cloudflare エッジを経由してフィルタリング

今回の構成での役割

graph TD
    A[GitHub Actions Runner] --> B[Cloudflare Edge]
    B --> C[Cloudflare Tunnel]
    C --> D[自宅 Ubuntu Desktop]
    
    style A fill:#e1f5fe
    style D fill:#c8e6c9
    style C fill:#fff3e0

自宅 Ubuntu Desktop 側：cloudflared デーモンが常時 Cloudflare に接続
GitHub Actions 側：cloudflared access sshコマンドでプロキシ経由接続
Cloudflare：両者の間でセキュアなトンネルを提供

セキュリティ上のメリット

IP 隠匿：自宅のパブリック IP アドレスが外部に露出しない
DDoS 保護：Cloudflare のセキュリティインフラを活用
アクセス制御：Cloudflare Access による詳細な制御

Cloudflare Access

Cloudflare Access とは

Cloudflare Access は、Zero Trust Network Access（ZTNA）を実現する Cloudflare のセキュリティサービスです。従来の VPN に代わって、アプリケーションレベルでの認証・認可を提供します。

Zero Trust Network Access（ZTNA）の概念

https://www.cloudflare.com/ja-jp/learning/access-management/what-is-ztna/

従来の境界セキュリティモデル：

外部（危険） | ファイアウォール | 内部（安全）

社内ネットワークとインターネットの間に境界を引き、ファイアウォールで外部からの脅威をブロックする
「内部ネットワークは信頼できる」という前提
一度内部に侵入されると横展開のリスク

Zero Trust アプローチ：

すべてのアクセスを検証 → 認証 → 認可 → アクセス許可

「信頼しない、常に検証する」（Never Trust, Always Verify）
ネットワークの場所に関係なく、すべての接続を認証・認可

今回の構成での Cloudflare Access の役割

sequenceDiagram
    participant GA as GitHub Actions
    participant CF as Cloudflare Access
    participant CT as Cloudflare Tunnel
    participant UD as Ubuntu Desktop

    GA->>CF: 1. SSH 接続リクエスト + 認証情報
    CF->>CF: 2. Access Policy 確認
    CF->>GA: 3. 認証成功
    GA->>CT: 4. cloudflared プロキシ経由で SSH 接続
    CT->>UD: 5. セキュアトンネル経由で SSH 接続
    UD->>GA: 6. SSH 接続確立

セキュリティ上のメリット

細かいアクセス制御：リソースごと、ユーザーごとの詳細な権限設定
監査ログ：すべてのアクセス試行が記録される
MFA 対応：多要素認証の強制が可能（人間のユーザーの場合）
リアルタイム制御：ポリシー変更が即座に反映
セッション管理：接続セッションの詳細な管理・監視

従来の VPN との違い

項目	従来の VPN	Cloudflare Access
接続範囲	ネットワーク全体	アプリケーション単位
認証	接続時のみ	アクセス毎に検証
設定複雑さ	複雑	比較的シンプル
スケーラビリティ	制限あり	高い
監査ログ	限定的	詳細

Service Token による自動認証

Service Token とは

Service Token は、自動化システムやマシン間通信のための認証メカニズムです。人間のユーザーによるインタラクティブな認証（OAuth、SAMLなど）とは異なり、完全にプログラマティックなアクセスを可能にします。

従来のユーザー認証との違い：

項目	ユーザー認証 (OAuth/SAML)	Service Token
対象	人間のユーザー	自動化システム・アプリケーション
認証フロー	ブラウザベース・インタラクティブ	API ベース・プログラマティック
認証情報	ユーザー名・パスワード・MFA	Client ID・Client Secret
有効期限	セッション単位 (数時間)	長期間

GitHub Actions での役割

1. 自動化された SSH 接続の実現

GitHub Actions のワークフローでは、人間による認証操作ができないため、Service Token が不可欠です。

GitHub Actions Runner → Service Token 認証 → Cloudflare Access → SSH 接続

2. CD パイプラインに最適な理由

無人実行: 人間の介入なしで24時間実行可能
スケーラビリティ: 複数のワークフローから同時利用可能
信頼性: セッション切れやタイムアウトの心配がない
セキュリティ: GitHub Secrets での安全な管理

3. 自動化ワークフローでのセキュリティ利点

最小権限の原則: 特定のアプリケーションのみへのアクセス
監査可能性: すべてのアクセスがログに記録
中央管理: Cloudflare ダッシュボードでの一元管理

認証フローの概念

Service Token 認証プロセス：

sequenceDiagram
    participant GA as GitHub Actions
    participant CF as Cloudflare Access
    participant App as Protected Application

    GA->>CF: 1. Service Token (Client ID + Secret)
    CF->>CF: 2. Token 有効性確認
    CF->>CF: 3. Access Policy 評価
    CF->>GA: 4. 認証成功 (Access Token)
    GA->>App: 5. アプリケーションアクセス (Access Token)
    App->>GA: 6. レスポンス

Cloudflare Access による検証プロセス：

Token 有効性確認: 提供された Client ID と Secret の検証
Policy 評価: 該当する Access Policy の条件確認
アクセス許可判定: すべての条件を満たした場合のみアクセス許可
監査ログ記録: 認証試行と結果の詳細ログ

この Service Token による認証機構により、セキュリティを損なうことなく、完全に自動化された CD パイプラインを実現できます。

完成形のパイプライン全体像

まずは最終的に完成したCDパイプラインの全体像を紹介します。

deploy.yml ファイルの全容

name: Deploy to Server

on:
  pull_request:
   types: [closed]
   branches:
     - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    if: github.event.pull_request.merged == true

    env:
      REMOTE_HOST: ssh.your-domain.com
      REMOTE_USER: deploy-user
      REMOTE_DIR: /var/www/html
      SSH_PROXY_COMMAND: /tmp/cloudflared/cloudflared access ssh --id ${{ secrets.CLOUDFLARED_SSH_ID }} --secret ${{ secrets.CLOUDFLARED_SSH_SECRET }} --hostname %h

    steps:
      - name: Install cloudflared
        run: |
          latest_version=$(curl -s $GITHUB_API_URL/repos/cloudflare/cloudflared/releases/latest | jq -r '.tag_name')
          mkdir -p /tmp/cloudflared
          curl -sL -o /tmp/cloudflared/cloudflared $GITHUB_SERVER_URL/cloudflare/cloudflared/releases/download/$latest_version/cloudflared-linux-amd64
          chmod +x /tmp/cloudflared/cloudflared
          /tmp/cloudflared/cloudflared --version

      - name: Prepare .ssh/known_hosts from secrets
        run: |
          mkdir -p $HOME/.ssh
          chmod 700 $HOME/.ssh
          echo "${{ secrets.SSH_KNOWN_HOSTS }}" > $HOME/.ssh/known_hosts
          chmod 644 $HOME/.ssh/known_hosts

      - name: Set up SSH key
        run: |
          SSH_KEY_PATH=$HOME/.ssh/id_ed25519_github_actions
          echo "${{ secrets.SSH_PRIVATE_KEY }}" > "$SSH_KEY_PATH"
          chmod 600 "$SSH_KEY_PATH"

      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Deploy application via rsync
        run: |
          SSH_KEY_PATH=$HOME/.ssh/id_ed25519_github_actions
          rsync -rvz --no-group --no-perms --omit-dir-times \
            -e "ssh -i \"$SSH_KEY_PATH\" -o StrictHostKeyChecking=yes -o ProxyCommand='$SSH_PROXY_COMMAND'" \
            --include='public/***' \
            --include='src/***' \
            --include='views/***' \
            --include='composer.json' \
            --include='composer.lock' \
            --exclude='*' \
            ./ \
            $REMOTE_USER@$REMOTE_HOST:$REMOTE_DIR/

      - name: Run composer install on remote
        run: |
          echo "Installing composer dependencies..."
          SSH_KEY_PATH=$HOME/.ssh/id_ed25519_github_actions
          ssh -i "$SSH_KEY_PATH" \
            -o StrictHostKeyChecking=yes \
            -o ProxyCommand="$SSH_PROXY_COMMAND" \
            $REMOTE_USER@$REMOTE_HOST "
              set -euo pipefail
              cd \"$REMOTE_DIR\"
              if command -v composer >/dev/null 2>&1; then
                COMPOSER_NO_INTERACTION=1 \
                composer install \
                  --no-dev \
                  --prefer-dist \
                  --no-interaction \
                  --no-progress \
                  --optimize-autoloader
                if sudo -n true 2>/dev/null; then
                  sudo chown -R www-data:www-data vendor
                  sudo chmod -R 755 vendor
                else
                  echo '⚠️ sudo権限がないため vendor の所有権/権限変更をスキップしました'
                fi
                echo '✅ Composer install completed.'
              else
                echo '❌ composer not found on remote host.'
                exit 1
              fi
            "

パイプラインの動作フロー

graph TD
    A[プルリクエストが main ブランチにマージ] --> B[GitHub Actions 起動]
    B --> C[リポジトリのコードをチェックアウト]
    C --> D[cloudflared のインストール]
    D --> E[SSH 設定とホスト鍵登録]
    E --> F[rsync によるファイル同期]
    F --> G[デプロイ完了]
    F -.-> H[Composer による依存パッケージのインストール<br/>※ PHP 環境のみ]
    H -.-> G
    
    style A fill:#e1f5fe
    style G fill:#c8e6c9
    style H fill:#fff2cc

各ステップの詳細

1. トリガー条件

on:
  pull_request:
    types: [closed]
    branches: [main]

main ブランチへのプルリクエストがクローズされた際に実行
github.event.pull_request.merged == true でマージされた場合のみ処理

2. cloudflared のインストール

latest_version=$(curl -s $GITHUB_API_URL/repos/cloudflare/cloudflared/releases/latest | jq -r '.tag_name')
mkdir -p /tmp/cloudflared
curl -sL -o /tmp/cloudflared/cloudflared $GITHUB_SERVER_URL/cloudflare/cloudflared/releases/download/$latest_version/cloudflared-linux-amd64
chmod +x /tmp/cloudflared/cloudflared
/tmp/cloudflared/cloudflared --version

GitHub APIから最新バージョンを動的に取得

3. SSH 接続におけるホスト鍵の事前登録

mkdir -p $HOME/.ssh
chmod 700 $HOME/.ssh
echo "${{ secrets.SSH_KNOWN_HOSTS }}" > $HOME/.ssh/known_hosts
chmod 644 $HOME/.ssh/known_hosts

事前に登録したホスト鍵を使用して安全な SSH 接続を確立

Caution

セキュリティを重視した設計判断

自動化システムで SSH 接続を行う際、StrictHostKeyChecking=no オプションを使用することで初回接続時のホスト確認を省略し、設定の簡素化も可能です。

# 簡単だがセキュリティリスクのあるアプローチ
ssh -o StrictHostKeyChecking=no user@hostname "command"

しかし、このアプローチは以下のセキュリティリスクを抱えています：

❌️ 中間者攻撃（MITM）の危険性: 悪意のあるサーバーが正規のサーバーになりすますことが可能
❌️ 接続先の真正性確認不可: 意図した正しいサーバーに接続しているかの保証がない
❌️ セキュリティポリシーの妥協: 自動化のために基本的なセキュリティチェックを無効化

事前ホスト鍵登録によるメリット：

# セキュアなアプローチ
echo "${{ secrets.SSH_KNOWN_HOSTS }}" > ~/.ssh/known_hosts
ssh -o StrictHostKeyChecking=yes user@hostname "command"  # デフォルト動作

✅️ 接続先の検証: 事前に登録した正規のホスト鍵との照合により接続先を確実に検証
✅️ 中間者攻撃の防止: 不正なサーバーへの接続を自動的に拒否
✅️ 自動化とセキュリティの両立: 人間の介入なしに安全な接続を実現
✅️ 監査適合性: セキュリティ基準を満たした自動化システムの構築

このパイプラインでは、自動化の利便性よりもセキュリティを優先し、事前にホスト鍵を取得・管理する手間を承知で、より安全なアプローチを採用しました。

https://io.cyberdefense.jp/entry/dangerous_ssh_sftp_usage/

4. ソースコードのチェックアウト

- name: Checkout repository
  uses: actions/checkout@v4

actions/checkout@v4: GitHub Actions の公式アクションを使用してリポジトリのソースコードを取得
デプロイ対象ファイルの準備: rsync での転送前に、最新のマージされたコードをランナー環境に配置

5. ファイル同期

SSH_KEY_PATH=$HOME/.ssh/id_ed25519_github_actions
rsync -rvz --no-group --no-perms --omit-dir-times \
  -e "ssh -i \"$SSH_KEY_PATH\" -o StrictHostKeyChecking=yes -o ProxyCommand='$SSH_PROXY_COMMAND'" \
  --include='public/***' \
  --include='src/***' \
  --include='views/***' \
  --include='composer.json' \
  --include='composer.lock' \
  --exclude='*' \
  ./ \
  $REMOTE_USER@$REMOTE_HOST:$REMOTE_DIR/

rsync コマンドの詳細解説

SSH_KEY_PATH 変数: SSH 秘密鍵のパスを変数化して可読性と保守性を向上
ed25519 鍵タイプ: RSA より高速で安全な楕円曲線暗号を使用
GitHub Actions 専用鍵: デプロイ専用の識別しやすい鍵名

rsync オプションの解説

rsync -rvz --no-group --no-perms --omit-dir-times

オプション	説明	理由
`-r`	再帰的コピー	ディレクトリ構造を保持して全ファイルを転送
`-v`	詳細出力	転送状況をログで確認可能
`-z`	圧縮転送	ネットワーク帯域を効率的に利用
`--no-group`	グループ変更スキップ	権限エラーを回避
`--no-perms`	権限変更スキップ	既存のサーバー権限を保持
`--omit-dir-times`	ディレクトリタイムスタンプスキップ	タイムスタンプ関連エラーを防止

https://log.dot-co.co.jp/rsync/

SSH 接続設定

-e "ssh -i \"$SSH_KEY_PATH\" -o StrictHostKeyChecking=yes -o ProxyCommand='$SSH_PROXY_COMMAND'"

-e フラグ: rsync が使用する SSH コマンドを明示的に指定
-i "$SSH_KEY_PATH": 指定した秘密鍵ファイルを使用してユーザー認証
StrictHostKeyChecking=yes: ホスト鍵検証を強制（セキュリティ確保）
ProxyCommand='$SSH_PROXY_COMMAND': Cloudflare Access 経由で SSH 接続を確立

SSH_PROXY_COMMAND の詳細

SSH_PROXY_COMMAND: /tmp/cloudflared/cloudflared access ssh --id ${{ secrets.CLOUDFLARED_SSH_ID }} --secret ${{ secrets.CLOUDFLARED_SSH_SECRET }} --hostname %h

パラメータ	説明	役割
`/tmp/cloudflared/cloudflared`	cloudflared バイナリパス	事前にインストールした cloudflared の実行ファイル
`access ssh`	SSH アクセスモード	Cloudflare Access 経由での SSH 接続を指定
`--id ${{ secrets.CLOUDFLARED_SSH_ID }}`	Service Token ID	Cloudflare Access での認証に使用するクライアント ID
`--secret ${{ secrets.CLOUDFLARED_SSH_SECRET }}`	Service Token Secret	Service Token のクライアントシークレット（GitHub Secrets で管理）
`--hostname %h`	動的ホスト名指定	SSH 接続時のホスト名を動的に取得（`%h` は SSH の置換変数）

なぜこのコマンドが必要なのか？

GitHub Actions ランナー(SSH クライアント)は、人間のようにブラウザでログインして ID/パスワードや MFA を入力できません。Cloudflare Access のゲートを通過するためには、プログラマティックな認証メカニズムが必要です。

このコマンドの役割:

このコマンドは、SSH 接続の前に Cloudflare Access による認証を自動的に行い、必要な認証情報を付与する ProxyCommand として機能します。具体的には、Service Token を使用して Cloudflare Access の認証を通過し、Cloudflare Tunnel 経由で自宅サーバーへの SSH 接続を確立します。

SSH プロキシコマンドの動作フロー:

sequenceDiagram
    participant SSH as SSH Client
    participant CF as cloudflared
    participant CA as Cloudflare Access
    participant CT as Cloudflare Tunnel
    participant Server as Ubuntu Server

    SSH->>CF: ProxyCommand 実行
    CF->>CA: Service Token で認証
    CA->>CF: 認証成功
    CF->>CT: Tunnel 経由接続要求
    CT->>Server: SSH 接続転送
    Server->>SSH: SSH セッション確立

このプロキシコマンドにより、GitHub Actions ランナー(SSH クライアント)は Cloudflare Access の認証とトンネルを経由して安全に自宅サーバー(SSH サーバー)に接続できます。

ファイル選択ロジック

包含パターン（Include）:

--include='public/***'      # Web 公開ファイル
--include='src/***'         # アプリケーションソースコード  
--include='views/***'       # テンプレートファイル
--include='composer.json'   # PHP 依存関係定義
--include='composer.lock'   # 依存関係ロックファイル

除外パターン（Exclude）:

--exclude='*'              # デフォルトですべて除外

選択的同期の利点:

セキュリティ: 機密ファイル（.env, .git等）の転送を防止
効率性: 不要なファイル（node_modules, vendor等）を除外して高速転送
安全性: 本番環境に影響を与える可能性のあるファイルを制御

転送元・転送先の指定

./ $REMOTE_USER@$REMOTE_HOST:$REMOTE_DIR/

./: カレントディレクトリ（チェックアウトされたリポジトリのルート）
$REMOTE_USER: リモートサーバーのユーザー名（例: deploy-user）
$REMOTE_HOST: 接続先ホスト名（例: ssh.your-domain.com）
$REMOTE_DIR: デプロイ先ディレクトリ（例: /var/www/html）

この設定により、セキュアで効率的、かつ制御されたファイル同期を実現しています。

この基本的な4ステップで、GitHub Actions から Cloudflare Access 経由で自宅サーバーへの安全なファイル同期が実現できます。

詳細な設定手順

実際に同じ環境を構築するための詳細な手順を説明します。

1. Cloudflare の設定

参考

Cloudflare login

https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/

https://zenn.dev/z4ck_key/articles/github-actions-to-cloudflare-tunnnel

https://zenn.dev/greendrop/articles/2024-04-25-aacf4debe469e8

https://dev.classmethod.jp/articles/use-service-tokens-to-authenticate-cloudflare-access-from-my-application/

https://zenn.dev/takajun/articles/fbd783e459c722

1.1 Cloudflare Tunnel の作成

Zero Trust > ネットワーク > Tunnels に移動
トンネルを作成する をクリック

Cloudflared をクリック

トンネル名を入力
トンネルを保存 をクリック

表示されたインストールコマンドをコピー

下記項目を入力し、セットアップを完了する をクリック

項目説明

サブドメイン (任意) ssh

ドメイン 取得済みの独自ドメイン

タイプ SSH

URL localhost:22

1.3 Cloudflare Access の設定

1.3.1 Service Token の作成

Zero Trust > Access > サービス認証 に移動
サービストークンを作成する をクリック

下記項目を入力し、トークンを作成する をクリック

項目説明

サービストークン名 サービストークンの名前

サービストークンの有効期間 任意の選択肢

作成されたサービストークンのクライアント IDとクライアントシークレットをコピー (追って GitHub の Secrets に設定します)
保存 をクリック

1.3.2 Policy の作成

Zero Trust > Access > ポリシー に移動
ポリシーを追加する をクリック

下記項目を入力し、保存 をクリック

項目	説明
`ポリシー名`	任意の名前
`アクション`	`Service Auth`
`セッション時間`	任意の選択肢
`セレクター`	`Service Auth`
`値`	1.3.1 Service Token の作成で作成したサービストークン

1.3.3 Application の作成

Zero Trust > Access > アプリケーション に移動
アプリケーションを追加する をクリック

セルフホスト をクリック

下記項目を入力

項目説明

アプリケーション名 任意の名前

セッション時間 任意の選択肢

サブドメイン (任意) ssh

ドメイン 取得済みの独自ドメイン

パブリックホスト名 の入力欄は パブリックホスト名を追加 をクリックすると表示されます。
既存のポリシーを選択 をクリックし、 1.3.2 Policy の作成で作成したポリシーを選択
次へ をクリック

エクスペリエンス設定 と 詳細設定 はデフォルトのまま、各自の環境に合わせて設定し、 次へ/保存 をクリック

2. Ubuntu Desktop 側の設定

2.1 SSH サーバーのインストールと設定

# OpenSSH Serverのインストール
sudo apt update
sudo apt install openssh-server

# SSH設定の編集
sudo nano /etc/ssh/sshd_config

設定項目：

# パスワード認証を無効化
PasswordAuthentication no

# 公開鍵認証を有効化
PubkeyAuthentication yes

# rootログインを無効化
PermitRootLogin no

# 空のパスワードを持つアカウントのログインを禁止
PermitEmptyPasswords no

# 最大認証試行回数
MaxAuthTries 6

# ホスト鍵の指定
HostKey /etc/ssh/ssh_host_rsa_key
HostKey /etc/ssh/ssh_host_ecdsa_key
HostKey /etc/ssh/ssh_host_ed25519_key

設定後の再起動：

sudo systemctl restart ssh.socket
sudo systemctl enable ssh.socket

2.2 ファイアウォールの設定

# ファイアウォールの有効化
sudo ufw enable
# デフォルトポリシーで受信 (Incoming) を拒否
sudo ufw default deny incoming
# デフォルトポリシーで送信 (Outgoing) を許可
sudo ufw default allow outgoing
# SSHポートの開放
sudo ufw allow ssh
# SSH ブルートフォース攻撃の防止
sudo ufw limit ssh
# ファイアウォールの状態を確認
sudo ufw status

セキュアなSSHサーバの構築と運用ガイド（Ubuntu上）

2.3 デプロイ用ユーザーの作成

# デプロイ専用ユーザーを作成
sudo adduser deploy-user

# デプロイ用ユーザー用に公開鍵を配置するディレクトリを作成する
sudo mkdir -p /home/deploy-user/.ssh
# 公開鍵ファイルを作成する (今は空ファイル)
sudo touch /home/deploy-user/.ssh/authorized_keys
# ディレクトリの権限を設定する
sudo chmod 700 /home/deploy-user/.ssh
# 公開鍵ファイルの権限を設定する
sudo chmod 600 /home/deploy-user/.ssh/authorized_keys
# ディレクトリの所有者を設定する
sudo chown -R deploy-user:deploy-user /home/deploy-user/.ssh

2.4 Apache Web サーバーの設定

# Apacheのインストール
sudo apt install apache2

# DocumentRootの権限設定
find /var/www/html -type d -exec chmod 750 {} \;
find /var/www/html -type f -exec chmod 640 {} \;
sudo chown -R www-data:www-data /var/www/html

# deploy-userがwww-dataグループで書き込み可能に
sudo usermod -aG www-data deploy-user

2.5 パッケージマネージャーのインストール

Information

この手順について

パッケージマネージャーのインストールは今回の主題（CD パイプライン構築）とは別の内容のため、詳細は省略します。

今回は PHP 環境のため Composer をインストールしますが、開発言語に応じて適切なパッケージマネージャーを選択してください。

PHP: Composer
Node.js: npm / yarn / pnpm
Python: pip / poetry / pipenv
Ruby: gem / bundler
Go: go mod
Rust: cargo
Java: Maven / Gradle

各言語の公式ドキュメントを参照してインストールを行ってください。

2.6 cloudflared のインストールと設定

#1.1 Cloudflare Tunnel の作成でコピーしたインストールコマンドを実行します。

# cloudflaredのインストール
# Add cloudflare gpg key
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-public-v2.gpg | sudo tee /usr/share/keyrings/cloudflare-public-v2.gpg >/dev/null

# Add this repo to your apt repositories
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-public-v2.gpg] https://pkg.cloudflare.com/cloudflared any main' | sudo tee /etc/apt/sources.list.d/cloudflared.list

# install cloudflared
sudo apt-get update && sudo apt-get install cloudflared

サービス化：

sudo cloudflared service install [TOKEN]
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

3. GitHub Secrets の設定

3.1 SSH鍵ペアの生成

Caution

この手順について

SSH 鍵の生成と公開鍵の配置は、2.3 デプロイ用ユーザーの作成で作成したユーザーのホームディレクトリで実施します。

# ユーザー名を確認
$ whoami
deploy-user

# カレントディレクトリを確認
$ pwd
/home/deploy-user

# GitHub Actions用のSSH鍵を生成
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_github_actions -C "GitHub Actions"

# 公開鍵をサーバーに配置
cat ~/.ssh/id_ed25519_github_actions.pub >> ~/.ssh/authorized_keys

3.2 ホスト鍵の取得

Ubuntu Desktop の SSH サーバーに接続して、ホスト鍵を取得します。
下記コマンドの出力をコピーしておきます。

ssh-keyscan localhost 2>/dev/null | sed 's/localhost/ssh.your-domain.com/'

ssh-keyscan コマンドで取得したホスト鍵に含まれる文字列 localhost を Cloudflare Tunnel のホスト名に置き換えるため、sed コマンドの your-domain.com を各自の環境に合わせて置き換えてください。

3.3 GitHub Repository Settings での設定

Settings → Secrets and variables → Actions で New repository secret をクリックし、以下を設定する。

Name	Value
`SSH_PRIVATE_KEY`	`~/.ssh/id_ed25519_github_actions` の内容
`SSH_KNOWN_HOSTS`	3.2 ホスト鍵の取得でコピーしたホスト鍵の内容
`CLOUDFLARED_SSH_ID`	1.3.1 Service Token の作成で作成したサービストークンの`クライアント ID` (ヘッダー部分を除いたものをそのまま貼り付け)
`CLOUDFLARED_SSH_SECRET`	1.3.1 Service Token の作成で作成したサービストークンの`クライアントシークレット` (ヘッダー部分を除いたものをそのまま貼り付け)

4. ワークフローファイルの配置

リポジトリに .github/workflows/deploy.yml を作成し、先ほど紹介した完成版のYAMLを配置します。

5. 動作確認

5.1 プルリクエストでのテスト

機能ブランチを作成
何らかの変更をコミット
main ブランチに対するプルリクエストを作成
プルリクエストをマージ
GitHub Actions の実行ログを確認

まとめ

本記事では、GitHub Actions を使って自宅の Ubuntu Desktop への継続的デプロイメント（CD）パイプラインを構築する方法を解説しました。

達成したこと

手動デプロイ作業の完全自動化: プルリクエストのマージをトリガーに、開発ディレクトリから公開ディレクトリへのファイル同期を自動化
セキュアな接続: Cloudflare Tunnel と Cloudflare Access を活用し、自宅のパブリック IP を公開せずに安全な SSH 接続を実現
Zero Trust アーキテクチャの実装: Service Token による認証とアクセス制御により、セキュリティを損なわない自動化を構築

重要なポイント

Cloudflare Tunnel の活用: ルーターのポート開放不要で、セキュアに自宅サーバーを外部に公開
Service Token 認証: 人間の介入なしに、GitHub Actions からの自動アクセスを安全に実現
ホスト鍵の事前登録: StrictHostKeyChecking=no の安易な使用を避け、セキュリティを優先した設計

このアプローチの利点

開発効率の向上: デプロイ作業が自動化され、開発に集中できる
セキュリティの確保: 複数のセキュリティレイヤーにより、自宅サーバーを安全に運用
スケーラビリティ: 同じ仕組みを複数のプロジェクトやサーバーに適用可能
監査可能性: すべてのデプロイが GitHub Actions と Cloudflare のログに記録

今後の発展

このパイプラインを基盤として、以下のような機能拡張も検討できます。

デプロイ前の自動テスト実行
複数環境（ステージング/本番）への対応
デプロイ失敗時の自動ロールバック
Slack/Discord への通知連携

自宅サーバーでの Web ホスティングは、学習や実験に最適な環境だなぁと感じました。大変楽しかったです☺️

GitHub の Immutable releases でリリースを変更不可にする

2025-11-16T00:00:00.000+00:00

はじめに

先月 Immutable releases が GA になりました。

https://github.blog/changelog/2025-10-28-immutable-releases-are-now-generally-available/

これによりリリースが公開後に変更されていないことを確認でき、改ざんや偶発的な変更を回避できるようになります。

変更不可リリースの特徴

ドキュメントは以下で参照できます。

https://docs.github.com/ja/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases

変更不可リリースは以下のような特徴があります。

Git タグは移動または削除できない：リリースに関連付けられている Git タグは特定のコミットにロックされ、変更または削除することはできなくなります。
リリースアセットを変更または削除することはできない:リリースにアタッチされているすべてのファイルは、変更または削除から保護されます。

リリース構成証明が自動的に生成され、リリースタグ、コミット SHA、アセットなどの検証が可能になります。

変更不可リリースが有効な場合、そのリポジトリを削除し、同じ名前の新しいリポジトリを作成した場合でも、元のリポジトリの変更不可リリースに関連付けられたタグを再利用することはできなくなります。これは強力な保護機能ですね。

使ってみる

筆者がメンテナンスしている野良 Cosense アプリ sbe のリポジトリで設定してみました。

Information

Immutable releases は、リポジトリ単位、オーガニゼーション単位で設定可能です。

一度リリースしてしまうとリポジトリのコミッタでも変更はできないため、以下のようにドラフトリリースで作業する手順が推奨されています。

ドラフトリリースを作成
全てのアセットをドラフトリリースにアタッチ
ドラフトリリースを正式リリースにする

ちょうど sbe の変更が溜まっていたので、ベストプラクティスに従ってリリースドラフトを作成します。

保存されたドラフトリリースはまだ非公開で変更可能です。

Information

このアプリのリリース用ワークフローではタグ作成を契機にリリースを作るようにしています。
softprops/action-gh-release という Action を使っています。リリース成果物のアタッチもやってくれます。prerelease を true にすることで、ドラフトリリースを作成してくれます。

    - name: Publish
      uses: softprops/action-gh-release@v2
      with:
        files: |
          dist/**/*.exe
          dist/**/*.deb
          dist/**/*.AppImage
          dist/**/*.dmg
        prerelease: true

添付ファイルや差分を指差し確認してリリースを発行します。

Immutable release を有効にしていると確認のダイアログが出ます。

発行されたリリースには Immutable マークが付きました。

アセットには、リリースの attestation (証明) の JSON ファイルも追加されています。

編集画面では、リリースの説明などは編集可能ですが、タグやアセットは編集できない旨のメッセージが表示されます。

リリースを検証する

利用者は Immutable release で作成された変更不可リリースを GitHub CLI で検証できます。

https://docs.github.com/ja/code-security/supply-chain-security/understanding-your-software-supply-chain/verifying-the-integrity-of-a-release?utm_medium=changelog&utm_campaign=universe25

リリースが存在し、かつ不変であることを検証するには、クローンしたリポジトリのディレクトリ内で release verify コマンドを実行します。

gh release verify RELEASE-TAG

sbe の v3.8.0 リリースを検証すると GitHub API を使って証明を読み取り表示してくれます。

$ gh release verify v3.8.0

Resolved tag v3.8.0 to sha1:1f3f380d33f022230046a3200a67950ea027c8a1
Loaded attestation from GitHub API
✓ Release v3.8.0 verified!

Assets
NAME                     DIGEST                                                                 
sbe-3.8.0-universal.dmg  sha256:ab1c2595601136bf82aa7594d48bc764fe6f226ed1071c52441eb531f34e0252
sbe-3.8.0.AppImage       sha256:de1797b12152531df71e78519d660e32e1a79dca203bc3201d85b2facfe4b5a9
sbe-Setup-3.8.0.exe      sha256:a4a8d6fe8ddde6e1a2005a29d7e2759511cb537427e4a0ff03440c5e9f48fb94

ローカルにある成果物がリリース成果物と完全に一致していることを検証するには release verify-asset コマンドを使用します。

gh release verify-asset RELEASE-TAG ARTIFACT-PATH

リリースのアセットから macOS 用ユニバーサルインストーラのバイナリをダウンロードして検証してみました。

$ gh release verify-asset v3.8.0 ~/Downloads/sbe-3.8.0-universal.dmg 
Calculated digest for sbe-3.8.0-universal.dmg: sha256:ab1c2595601136bf82aa7594d48bc764fe6f226ed1071c52441eb531f34e0252
Resolved tag v3.8.0 to sha1:1f3f380d33f022230046a3200a67950ea027c8a1
Loaded attestation from GitHub API

✓ Verification succeeded! sbe-3.8.0-universal.dmg is present in release v3.8.0

Information

アセットの証明には Sigstore の署名技術が利用されています。ソフトウェアの出所情報を検証可能し、ソフトウェアサプライチェーンの安全性を高めるための技術です。かなり前の記事ですが以下で紹介しています。

https://developer.mamezou-tech.com/blogs/2022/08/17/github-actions-workflows-for-software-supply-chain-security/

さいごに

以上、Immutable releases の紹介でした。一定数ユーザーがいる OSS では変更不可リリースを採用する方がいいでしょう。

GitHub Actions でもサードパーティの Action を利用する際は、不意な変更の影響を受けないためにバージョンだけでなくコミットハッシュまで指定して固定することもあります。変更不可リリースを採用してくれる Action が増えれば使う側も安心ですね。

AIと始めるAWS開発 ― Q Developer入門

2025-11-12T00:00:00.000+00:00

Q Developerとは

Q Developer は、AWSが提供する生成AIによる開発支援ツールです。
ChatGPT や Copilot のように「コードを補完するAI」ではなく、設計・実装・テスト・レビュー・ドキュメント化までを支援する開発プラットフォームとして設計されています。

特徴を一言で言うと、AWSの開発を、AIと一緒に進められる統合環境です。

主な機能と特徴

項目	概要
自然言語での開発支援	「Lambda関数を作って」「DynamoDBと連携して」と自然言語で指示できる
コード生成と補完	Python, TypeScript, Javaなど主要言語をサポート
テストコード自動生成	既存コードからテストを推論して自動生成
レビューと改善提案	コード品質・例外処理・命名規約などをAIが自動レビュー
AWS統合	Lambda / API Gateway / DynamoDB / CDK などのAWSリソースを直接扱える
VS Code統合	拡張機能からインラインでAIに指示・生成・修正が可能

CLIとVS Codeの2つの使い方

Q Developerには2つの利用スタイルがあります。

スタイル	概要	コマンド例
CLI（コマンドライン）	ターミナル上でAIに直接指示を出す	`$ q generate lambda --name hello-world`
VS Code拡張	エディタ内で自然言語プロンプトを入力し、コード生成・修正を行う	コマンドパレットで「Q Developer: Generate Code」

Pro版を利用していれば、CLIとVS Codeの両方からAWSサービスを直接操作できるようになります。

“Q”の由来と目的

「Q」は “Quality（品質）” と “Question（問い）” の両方を意味します。
このツールの思想は、「AIがコードを書く」のではなく、開発者がAIと会話しながら品質を作り込む という協働開発にあります。

したがって、Q Developerは単なる補助ツールではなく、設計レビューから実装・改善までを一貫して支援する“AI開発パートナー” です。

今回は主に Q CLI を使って簡単なアプリケーションを作っていきます。

1. Q Developer CLIの概要

CLI（コマンドラインインターフェース） では高度な操作が可能になります。
CLIでは、ターミナル上でAIと対話（インタラクティブモード）できるだけでなく、以下のようなコマンドで自動処理や統合が行えます。

機能	説明
コード生成	Lambda・API Gateway・CDK構成などをAIが生成
レビュー	既存コードの品質を分析し、改善案を提示
修正と再生成	問題箇所をAIが自動修正
テスト生成	単体テストコードを自動で生成・実行
ドキュメント化	READMEや設計書を自動出力

動作確認例

以下が表示されれば、環境は正しく構成されています。
コマンドラインですべて完結させることができますが、初回の試みということもあるので、今後はすべて対話形式のインタラクティブモードで実行します。

$ q --version
q 1.13.0

$ q help
# 利用可能なサブコマンド一覧を表示
# generate / review / test / fix / metrics / deploy など

2. Q CLIの起動とインタラクティブモード

以下のコマンド「q」を実行します。

$ q

以下のような画面が表示されます。


    ⢠⣶⣶⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀        ⢀⣤⣶⣿⣿⣿⣶⣦⡀⠀
 ⠀⠀⠀⣾⡿⢻⣿⡆⠀⠀⠀⢀⣄⡄⢀⣠⣤⣤⡀⢀⣠⣤⣤⡀⠀⠀⣠⣤⣤⣤⣄⠀⠀⢀⣤⣤⣤⣤⣤⣤⡀⠀⠀⣀⣤⣤⣤⣀⠀⠀ ⠀⢠⣤⡀⣀⣤⣤⣄⡀⠀⠀⠀⠀⠀⠀⢠⣿⣿⠋⠀⠀⠀⠙⣿⣿⡆
 ⠀⠀⣼⣿⠇⠀⣿⣿⡄⠀⠀⢸⣿⣿⠛⠉⠻⣿⣿⠛⠉⠛⣿⣿⠀⠀⠛⠉⠉⠻⣿⣧⠀⠈⠛⠛⠛⣻⣿⡿⠀⢀⣾⣿⠛⠉⠻⣿⣷⡀⠀ ⢸⣿⡟⠛⠉⢻⣿⣷⠀⠀⠀⠀⠀⣼⣿⡏⠀⠀⠀⠀⠀ ⢸⣿⣿
 ⠀⢰⣿⣿⣤⣤⣼⣿⣷⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⢀⣴⣶⣶⣶⣿⣿⠀⠀⠀⣠⣾⡿⠋⠀⠀⢸⣿⣿⠀⠀⠀ ⣿⣿⡇⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⢹⣿⣇⠀⠀⠀⠀ ⠀⢸⣿⡿
 ⢀⣿⣿⠋⠉⠉⠉⢻⣿⣇⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⣿⣿⡀⠀⣠⣿⣿⠀⢀⣴⣿⣋⣀⣀⣀⡀⠘⣿⣿⣄⣀⣠⣿⣿⠃⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⠈⢿⣿⣦⣀⣀⣀⣴⣿⡿⠃
 ⠚⠛⠋⠀⠀⠀⠀ ⠘⠛⠛⠀⠘⠛⠛⠀⠀⠀⠛⠛⠀⠀⠀⠛⠛⠀⠀⠙⠻⠿⠟⠋⠛⠛⠀⠘⠛⠛⠛⠛⠛⠛⠃⠀⠈⠛⠿⠿⠿⠛⠁⠀⠀⠘⠛⠃⠀ ⠘⠛⠛⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠿⢿⣿⣿⣋⠀⠀
 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀　　　　　⠈⠛⠿⢿⡧

╭─────────────────────────────── Did you know? ────────────────────────────────╮
│                                                                              │
│    If you want to file an issue to the Q CLI team, just tell me, or run q    │
│                                    issue                                     │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

/help all commands  •  ctrl + j new lines  •  ctrl + s fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤖 You are chatting with claude-4-sonnet

この状態が「インタラクティブモード」です。
自然言語で直接話しかけて、AIと一緒に設計・実装を進めることができます。

対話例

以下の文章を入力します。

> DynamoDB にデータを保存する Lambda 関数を作成して

応答は次のようになりました。

> DynamoDBにデータを保存するLambda関数を作成します。


🛠️  Using tool: fs_write (trusted)
 ⋮
 ● Path: /home/ubuntu/q/lambda_dynamodb_jp.py

+     1: import json
+     2: import boto3
+     3:
+     4: dynamodb = boto3.resource('dynamodb')
+     5: table = dynamodb.Table('your-table-name')
+     6:
+     7: def lambda_handler(event, context):
+     8:     try:
+     9:         # 入力データの検証
+    10:         if not event or not isinstance(event, dict):
+    11:             return {
+    12:                 'statusCode': 400,
+    13:                 'body': json.dumps('無効な入力: イベントは空でないオブジェクトである必要があります', ensure_ascii=False)
+    14:             }
+    15:
+    16:         # DynamoDBにデータを保存
+    17:         table.put_item(Item=event)
+    18:
+    19:         return {
+    20:             'statusCode': 200,
+    21:             'body': json.dumps('データが正常に保存されました', ensure_ascii=False)
+    22:         }
+    23:     except Exception as e:
+    24:         return {
+    25:             'statusCode': 500,
+    26:             'body': json.dumps(f'エラー: {str(e)}', ensure_ascii=False)
+    27:         }

 ⋮
 ↳ Purpose: DynamoDBにデータを保存するLambda関数を作成
Creating: /home/ubuntu/q/lambda_dynamodb_jp.py

 ⋮
 ● Completed in 0.1s


> Lambda関数を作成しました。主な機能：

• boto3を使用してDynamoDBと連携
• イベントデータの入力検証
• DynamoDBテーブルへのデータ保存
• 日本語でのエラーメッセージ
• 適切なHTTPステータスコードを返却

使用方法：
1. 'your-table-name'を実際のDynamoDBテーブル名に変更
2. Lambda実行ロールにdynamodb:PutItem権限を付与
3. 関数はイベントで渡されたJSONデータをDynamoDBに保存します

3. 対話で進めるプログラム開発体験

Q Developer CLI（q）を使って、AIと自然言語で会話しながら、シンプルなアプリケーション（ここでは「テトリス」ゲーム）を一緒に作り上げる流れを紹介します。

$ q
🤖 You are chatting with claude-4-sonnet

3.1 シナリオ設定

今回作成するテトリスの要件は以下のとおりです。

①：通常のテトリスが備えている操作は一通り持っている
②：単なるブロックではなく、動物のアイコン（例えば猫）を使う
③：猫アイコンの表情も一通りではなく、ブロックが積まれてくると、猫アイコンの表情を変える
④：格納場所はAWSのS3として、グローバルでアクセスできるように設定する

3.2 Q Developerとの対話開始

指示：（概要＋詳細（上記の要件の①と②））

テトリスを作ってください。
テトリスが備えているであろう普通の機能（ブロックの回転、位置決め、落下など）を備えてください。
ブロックは通常のブロックではなく、猫のアイコン画像（画像の選定は任せます）を使ってください。

応答：

> 猫のアイコンを使ったテトリスゲームを作成します：

🛠️  Using tool: fs_write (trusted)
 ⋮
 ● Path: /home/ubuntu/q/cat-tetris.html

+      1: <!DOCTYPE html>
+      2: <html>
+      3: <head>
+      4:     <meta charset="UTF-8">
+      5:     <title>猫テトリス</title>
+      6:     <style>
+      7:         body { margin: 0; padding: 20px; background: #222; color: white; font-family: Arial; text-align: center; }
+      8:         canvas { border: 2px solid #fff; background: #000; }
+      9:         .score { font-size: 20px; margin: 10px; }
+     10:         .controls { margin: 10px; font-size: 14px; }
+     11:     </style>
+     12: </head>

～～～（中略）～～～

+    239:         // Start game
+    240:         updateScore();
+    241:         requestAnimationFrame(gameLoop);
+    242:     </script>
+    243: </body>
+    244: </html>

 ⋮
 ↳ Purpose: Create cat tetris game with standard tetris features
Creating: /home/ubuntu/q/cat-tetris.html

 ⋮
 ● Completed in 0.1s

> 猫のアイコンを使ったテトリスゲームを作成しました！

主な機能:
• **ブロック回転**: ↑キーで回転
• **左右移動**: ←→キーで移動
• **高速落下**: ↓キーで高速落下
• **ハードドロップ**: スペースキーで瞬間落下
• **ライン消去**: 横一列が揃うと消去
• **スコアシステム**: ライン消去でスコア獲得
• **レベルアップ**: スコアに応じて落下速度が上がる
• **猫のアイコン**: 7種類の猫の絵文字をランダム使用

操作方法:
• ←→: 左右移動
• ↓: 高速落下
• ↑: 回転
• スペース: ハードドロップ

ファイルを開いてブラウザでプレイできます！

どうやら「/home/ubuntu/q/cat-tetris.html」が成果物のようです。
（出力を明確に指定していなかったので、Qが任意の保存場所とファイル名を用意したようです）

HTMLファイルを開いてみます。

猫テトリスが動いています。
猫アイコンもそれぞれ表情が違っていて面白いです。
しかし、最初から猫が泣いていたりして、法則性が無いように思います。
どのように猫の表情を変化させているのかを確認してみます。

指示：

> 猫アイコンはどういうロジックで変化しているのですか？

応答：

> 猫アイコンの変化ロジックは以下の通りです：

1. ピース生成時にランダム決定:
javascript
this.catType = Math.floor(Math.random() * CAT_EMOJIS.length);

新しいテトリスピースが生成される際に、7種類の猫絵文字（🐱😺😸😹😻🙀😿）からランダムに1つ選択されます。

2. ピース全体で同じ猫:
各テトリスピース（I、O、T、S、Z、J、L）は生成時に決まった1種類の猫アイコンで統一されます。

～～～（中略）～～～

4. 表示時の変換:
javascript
drawBlock(x, y, board[y][x] - 1);

描画時に-1して元の猫タイプインデックスに戻します。

つまり: 各テトリスピースごとに猫の種類がランダムに決まり、そのピース内のすべてのブロックは同じ猫アイコンになります。ピー
スが異なれば猫の種類も変わる可能性があります。

質問を投げかけると、このように応答します。
ただ、ランダムだと面白くないので、さらに制約（詳細）を追加していきます。

指示：（要件：③）

ゲームの序盤では余裕の猫で、ブロックが高く積みあがってくるにしたがって、余裕のない表情の猫にしてください。

応答：

> ゲームの状況に応じて猫の表情が変わるように修正します：

🛠️  Using tool: fs_write (trusted)
 ⋮
 ● Path: cat-tetris.html

- 29    :         // 猫の絵文字を使用
- 30    :         const CAT_EMOJIS = ['🐱', '😺', '😸', '😹', '😻', '🙀', '😿'];
+     29:         // 猫の絵文字を使用（余裕→緊張の順）
+     30:         const CAT_EMOJIS = ['😻', '😺', '😸', '🐱', '😹', '🙀', '😿'];

～～～（中略）～～～

> 修正完了しました！

新しい猫の表情システム:

• **😻 (余裕)**: ブロックが低い位置にある時
• **😺 (まだ余裕)**: 少し積み上がってきた時
• **😸 (少し心配)**: 中程度の高さ
• **🐱 (普通)**: 半分くらいの高さ
• **😹 (緊張)**: かなり高く積み上がった時
• **🙀 (焦り)**: 危険な高さ
• **😿 (絶望)**: ゲームオーバー寸前

ブロックが高く積み上がるほど、猫の表情が余裕から絶望へと変化します。ゲームの緊張感が猫の表情で表現されるようになりました！

実行して制約を確認します。
以下が実行結果です。

今度は余裕が無くなってくる（ブロックが積み上がる）と、猫アイコンの表情が（余裕→絶望）に変わっていくのがわかります。

ただ、ゲームを少しプレイしていると以下のバグが見つかりました。

横4つつながったブロックが上↑キーで回転しない。
2回目以降のゲーム再開で、最初から絶望や焦りの表情をした猫ブロックが登場する。

バグの修正を「日本語」で指示します。

指示：（バグ修正依頼）

バグがあります。修正してください。バグは以下です。
１．横4つつながったブロックが上↑キーで回転しない。
２．2回目のゲームで、最初から絶望や焦りの猫の表情のブロックが登場する。

応答：

> バグを修正します：

1. I字ピース（横4つ）の回転バグ修正：

🛠️  Using tool: fs_write (trusted)
 ⋮
 ● Path: cat-tetris.html

  39, 39:         const PIECES = [
  40, 40:             // I piece
- 41    :             [[[1,1,1,1]]],
+     41:             [[[1,1,1,1]], [[1],[1],[1],[1]]],

 ⋮
 ↳ Purpose: Fix I-piece rotation by adding vertical rotation state
Updating: cat-tetris.html

 ⋮
 ● Completed in 0.0s

> 2. ゲームリセット時のボード初期化バグ修正：

🛠️  Using tool: fs_read (trusted)
 ⋮
 ● Searching: /home/ubuntu/q/cat-tetris.html for pattern: ゲームオーバー
 ✓ Found 1 matches for pattern 'ゲームオーバー' in /home/ubuntu/q/cat-tetris.html

 ⋮
 ● Completed in 0.0s

🛠️  Using tool: fs_read (trusted)
 ⋮
 ● Reading file: /home/ubuntu/q/cat-tetris.html, from line 224 to 234
 ✓ Successfully read 464 bytes from /home/ubuntu/q/cat-tetris.html
 ⋮

～～～（中略）～～～

 ⋮
 ↳ Purpose: Fix board reset to ensure proper initialization
Updating: cat-tetris.html

 ⋮
 ● Completed in 0.0s

> 修正完了しました！

修正内容:
1. I字ピースの回転: 横4つの状態と縦4つの状態を追加し、↑キーで回転できるようになりました
2. ゲームリセット: ボードを完全に0で初期化し、新しいピースを生成するようにしたので、2回目のゲームでも正しく余裕のある猫から始まります

これでバグが解消され、正常にゲームが動作するはずです！

修正版のゲームを再度実行します。

回転できなかった横一列のブロックも回転できるようになっています。
また、ゲーム再開時の猫アイコンも正しく表示されるようになっていました。

3.3 AWS S3にアップロード

出来上がったテトリスアプリケーションはHTMLファイルが一つだけの単純なものです。
このアプリケーションをAWS S3にアップロードしてみます。
（AWS S3へのアクセス権を持っていることが条件です）

指示：（要件：④）

ゲームをAWS S3にアップロードして。
アップロード先は新しいバケットを作成して。

応答：

> 新しいバケットを作成して猫テトリスをアップロードしますね。

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
aws s3 mb s3://cat-tetris-game-$(date +%s)
 ⋮
 ↳ Purpose: 新しいS3バケットを作成

make_bucket: cat-tetris-game-<バケットID>

 ⋮
 ● Completed in 1.573s

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
aws s3 cp /home/ubuntu/cat-tetris.html s3://cat-tetris-game-<バケットID>/cat-tetris.html --content-type text/html
 ⋮
 ↳ Purpose: 猫テトリスファイルを新しいバケットにアップロード

upload: ./cat-tetris.html to s3://cat-tetris-game-<バケットID>/cat-tetris.html

 ⋮
 ● Completed in 0.655s

> 完了しました！新しいバケット cat-tetris-game-<バケットID> を作成して、猫テトリスファイルをアップロードしました。

アップロードが完了したようですが、アクセス方法がわかりません。
最終的にどのようにアクセスしたいかを伝えていませんでした。
Q Developerに＜最終成果物のイメージ＞を伝えます。

指示：

URLでアクセスしたいので、URLを教えて

応答：（バケットIDは実際に出力されたものから変更しています）

> 現在はS3バケットがプライベートなので、Webからアクセスできません。パブリックアクセスを有効にする必要があります。

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
aws s3api put-public-access-block --bucket cat-tetris-game-<バケットID> --public-access-block-configuration "BlockPublicAcls=false,IgnorePublicAcls=false,BlockPublicPolicy=false,RestrictPublicBuckets=false"
 ⋮
 ↳ Purpose: バケットのパブリックアクセスブロックを無効化

 ⋮
 ● Completed in 0.989s

🛠️  Using tool: execute_bash (trusted)
 ⋮
 ● I will run the following shell command:
aws s3api put-bucket-policy --bucket cat-tetris-game-<バケットID> --policy '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::cat-tetris-game-<バケットID>/*"
    }
  ]
}'
 ⋮
 ↳ Purpose: バケットポリシーでパブリック読み取りを許可

 ⋮
 ● Completed in 1.112s

> これで以下のURLでアクセスできます：

https://cat-tetris-game-<バケットID>.s3.amazonaws.com/cat-tetris.html

ブラウザでこのURLを開けば猫テトリスがプレイできます！

指定されたURLを開きます。
ローカルで実行したものと同じテトリスを、AWS S3上で実行することが出来ました。

4. 指示の出し方の基本パターン

AIとの対話で成果を出すには、「どのように伝えるか」 が最も重要です。
Q Developerは自然言語を理解しますが、明確で構造的な指示ほど精度の高いコードを生成します。

4.1 指示の基本構造

AIにタスクを伝えるときは、次の3段階を意識します。

段階	内容	例
① ゴール	何を達成したいか	「DynamoDBにデータを保存するAPIを作りたい」
② 制約	技術的な条件・使用技術	「Python 3.11で、Lambda関数として実装して」
③ 期待結果	出力してほしい成果物の形	「ハンドラー関数とテストコードを生成して」

この3要素を順番に伝えるだけで、出力の再現性と品質が大きく向上します。

4.2 指示の粒度を使い分ける

Q Developerへの指示は、大きく「部分指示」と「全体指示」の2種類があります。

種類	対象範囲	使い方の例
部分指示	関数・モジュールなど局所的な修正	「この関数をリファクタして、例外処理を標準化して」
全体指示	プロジェクト全体や設計方針	「全APIのレスポンス形式を統一して、共通エラーハンドラを追加して」

部分指示では即時的な改善を狙い、全体指示では設計方針の整合性を図ります。
この2つを組み合わせることで、AIに意図の上下関係を理解してもらうことができます。

4.3 フィードバックを循環させる

AIが出した結果に対して「そのまま使う」のではなく、誤解 → 修正 → 再生成 のサイクルを回すことが重要です。

例：

AI：Lambda関数を作成しました。DynamoDBに書き込みます。
↓
開発者：このコードではテーブル名が固定なので、環境変数から取得するようにして。
↓
AI：了解しました。修正したコードを以下に示します。

このように、AIとの対話を「レビューの往復」として扱うと、より高品質なコードを一緒に育てることができます。

4.4 良い指示と悪い指示の比較

指示の例	AIの反応	評価
「DynamoDB対応のLambda作って」	動くが、スキーマや例外処理が曖昧	❌ 不明確
「DynamoDBにタスクを登録するLambda関数を作成。titleとstatusを受け取り、statusの初期値はpendingにして」	適切なハンドラーとバリデーションを自動生成	✅ 明確
「関数を改善して」	どこをどう直すか分からない	❌ 抽象的
「この関数のエラーハンドリングを追加し、ログに例外内容を出力して」	コードの修正意図を正確に反映	✅ 具体的

「短い指示」よりも「明確な文脈を含む指示」が結果を良くします。

4.5 応用：AIをレビューアとして使う

AIに “設計者” や “品質管理者” の視点を持たせることも可能です。
たとえば次のような指示が有効です。

このコードの保守性とテスト容易性の観点から、改善点を3つ挙げて。

または、

このAPI設計をREST原則に照らしてレビューして。

これにより、Q Developerは単なる生成エンジンから「レビューAI」として機能し、開発者の品質意識を高めるパートナーになります。

まとめ

指示は「ゴール → 制約 → 期待結果」の順に伝える
粒度（部分／全体）を意識して構造的に指示する
フィードバックを繰り返して精度を上げる
最小構成で動かしながら、AIとの会話を通じて開発プロセスを理解する

Q Developerは「AIがコードを書くツール」ではなく、「AIと共に設計・実装・品質を磨くためのプラットフォーム」です。

皆さまの生成AI活用の参考になれば幸いです。

IaCでWebhookイベントのキューイングを構築

2025-10-31T00:00:00.000+00:00

はじめに

社内プロジェクトの営業支援システム(Sales Support System、以下、SSS)開発で導入した Webhook のイベントキューイングの Terraform での構築手順を紹介します。

背景

SSS ではワークフローを提供する SaaS と稟議の進捗イベントを Webhook 連携することでデータのステータス管理をしています。
初期の段階では優先度や工数の制約により、直接呼び出しで運用が開始されました。

しかし、以下にあげる事情により、イベントのキューイングを導入することにしました。

想定していた機能開発が完了し、先送りしていた機能改善に着手する工数ができた。
優先度や頻度の多い他のエラーが解消されて優先度が上位になった。
運用リカバリで、ただでさえ少ない工数なのに手動データパッチの手間やワークフローの再申請などの利用者の負担となることも。^[1]
運用保守向けの補足的な機能で、技術的な選択の自由度が高い。

キューイング機能に対する要件

実際に SaaS 連携イベントのキューイングを導入するに当たり、以下のような要件を満たすべく、いくつかの AWS サービスを比較検討しました。

メッセージを取りこぼさないでほしい。
順番を保証してほしい。
- 順序を保証してほしいイベントは状態が遷移しないと次のイベントが出せないので実質的な問題は発生しないが仕組みとして保証できればしたい。
受信失敗したときにメッセージが残っていてほしい。
失敗したメッセージを簡単に再送出来るとなお良し。
ECS の SSS サービスとは独立させたい。
- 独立していないとリプレースで ECS サービス停止中に同じ問題が発生してしまう。
既存の SSS サービスへの修正ができるだけ少ない方が良い。
- 追加機能だけが依存するのがベスト。
どうせならサーバレスなサービスを利用したい。

機能比較／検討

以上の要件を踏まえて機能比較表を作成して評価しました。^[2]
本当は重みがありそうですが、ポイントは単純に〇（2）、△ と？（1）、×（0）で換算しています。

案	サービス	タイプ	順序	exactly-once	サーバレス	API GW 統合^[3]	送信失敗時	振り分け	ポイント
1	SQS	標準	×	×	〇	〇	DLQ	Lambda	4
2	SQS	FIFO	〇	〇	〇	〇	DLQ	Lambda	8
3	SNS	標準	×	×	〇	×（Lambda）	？	SNS	4(3-5)
4	SNS	FIFO	〇	〇	〇	×（Lambda）	？	SNS	6(5-7)
5	Kinesis	DataStream	〇	？	〇	〇	？	Lambda	7(5-9)
6	SNS+SQS	FIFO+FIFO	〇	〇	〇	×（Lambda）	DLQ	SNS	6
7	SQS+SNS	FIFO+FIFO	〇	〇	〇	〇	DLQ	Lambda	8

なお、DLQ（Dead Letter Queue）は正常に処理できなかったメッセージを一時的に保存するための特別なメッセージキューのことです。

SNS の送信失敗

当時は見つけられなかったのか、比較表では SNS の送信失敗時は「？」となっていますが、SNS も DLQ があるようです。
Amazon SNS デッドレターキュー - Amazon Simple Notification Service
実体は SQS の DLQ に連携するらしいですが。

比較表からポイントで単純に絞り込んで案 2 か案 7 のいずれか。

1 ポイント差の案 5 も惹かれるけど「イベントストリーム」というほどデータは来ないので廃案。
案 7 は振り分けに SNS が使えないかと考えたがキュー自体を分けるか結局 Lambda を利用する必要があったので組み合わせのメリットがなくなったため廃案。
- 大したデータ量と頻度もないのに複数のキューに分けて管理とかしたくないのも理由。
- 1 つのキューにすると結局は Lambda で振り分けになる。
  - これだと SNS 意味がないのでは？
  - 案 2 に無駄に SNS が追加されただけになる。
案 2 はメッセージグループ ID で Lambda が振り分け。
- メッセージグループ ID は API Gateway との統合で設定可能（ルート（URL パス）ごとにできる）。

以上の検討の結果、以下の AWS サービス構成と呼び出しフローとすることになりました。

補足事項

SQS のイベント監視の Lambda のポーリングは実体がそうなっているだけで実装するわけではない。
- イベントソースとして SQS を指定するだけ。
直接 CloudMap を呼び出したかったが上手くいかなかった。
- サービスディスカバリで CloudMap の登録サービスの取得まではいけたが、呼び出しが戻ってこないでタイムアウトする。
- 同じ URL で踏み台サーバから curl で呼び出したら出来たのに AWS Lambda からだとうまくいかなかった。
- 設定とかいろいろやれば行けるのかもしれないが、後日の課題とした。
当たり前だが、Amazon API Gateway 経由では行けたのでこちらの方式で対応することにした。
- 結局 Amazon API Gateway のパスがさらされたままだから、SSS サービスを直接呼べるように将来はしたいところ。

構築の前提事項

外部システムから既存システムの Webhook の呼び出しの間にキューを差し込む形になるため、以下が前提となっています。

IaC で Sales Support System のインフラ構築で紹介した API Gateway 経由で ECS サービスを呼び出すシステムが既に構築されていること。
ECS サービスは Webhook 用の API が公開されていること。

この記事では 2 つ目の前提の代替として AWS Lambda の統合を利用するものとします。

次章から具体的な実装について説明していきます。

メッセージキュー

まずは以下の 2 つの AWS SQS の作成をしていきます。

Webhook 用メッセージキュー
DLQ

Webhook 用メッセージキュー

メインとなる Webhook 用のメッセージキューの作成です。
AWS SQS では 2 種類のキューがありますが、今回は FIFO キューを利用します。

fifo_queueをtrueにしていますが FIFO の場合はキュー名のサフィックスが.filoでなければなりません。
また、DLQ を利用するため、関連付け（deadLetterTargetArn）が必要となります。
他にはメッセージの重複判定をコンテンツベースにするのと可視性タイムアウト（処理中に他からメッセージが見えなくなる時間）を設定しています。

main.tf

resource "aws_sqs_queue" "webhook_queue" {
  name                        = "${local.webhook_queue_name}.fifo"
  fifo_queue                  = true
  content_based_deduplication = true
  visibility_timeout_seconds  = local.processing_timeout
  redrive_policy              = jsonencode({
    deadLetterTargetArn = aws_sqs_queue.webhook_dlq.arn
    maxReceiveCount     = var.webhook.max_receive_count
  })
}

DLQ

次に DLQ の作成になります。
メインのメッセージキューよりシンプルに定義できます。

キュー名についてはメインのメッセージキューと同様に.fifoサフィックスが必要です。
リカバリ処理で失敗したメッセージ内容の確認をするまでの時間を調整するため、保持期間（message_retention_seconds、デフォルトは 4 日間）を外部変数で指定しています。

main.tf

# DLQ
resource "aws_sqs_queue" "webhook_dlq" {
  name                      = "${local.webhook_queue_name}-dlq.fifo"
  fifo_queue                = true
  message_retention_seconds = var.webhook.dlq_retention_second
}

キューイング用 Webhook API

今回は SSS 同様に API Gateway は既存のものがある前提となるため、新たに SQS が受けるための設定を API Gateway へ追加することになります。
具体的には以下のものになります。

ルート
統合

なお、API Gateway 自体の構築についてはIaC で Sales Support System のインフラ構築の記事を参照ください。

キューイング Webhook API に対するルート

今回は JWT 認証しないため、以前のアプリケーション用のルートよりもシンプルになります。
ルートキーのパスは/sqs-hookとしています。
HTTP メソッドは SSS で利用している SaaS の指定（POST）に合わせています。

なお、API Gateway の ID については既存の参照としてデータソースを利用しています。
API Gateway 自体も新規に作成する場合は通常の AWS リソースへの参照となります。

integration.tf

resource "aws_apigatewayv2_route" "webhook_event_route" {
  api_id              = data.aws_apigatewayv2_api.this.id
  route_key = "POST /sqs-hook"
  target    = "integrations/${aws_apigatewayv2_integration.webhook_event_producer.id}"
}

SQS との統合

続いて API Gateway と SQS を関連付けるための統合を作成します。

integration_subtypeとしてSQS-SendMessageを指定しています。
これによって SQS への送信用として統合されます。

更にrequest_parametersで以下の設定をします。^[4]

キューイング Webhook API に対する URL（必須）
メッセージグループ ID
メッセージボディ（必須）

integration.tf

resource "aws_apigatewayv2_integration" "webhook_event_producer" {
  description         = "Queue of Webhook Event"
  api_id              = data.aws_apigatewayv2_api.this.id
  integration_type    = "AWS_PROXY"
  integration_subtype = "SQS-SendMessage"
  credentials_arn     = aws_iam_role.webhook_event_producer_role.arn

  request_parameters = {
    "QueueUrl"       = aws_sqs_queue.webhook_queue.url
    "MessageGroupId" = local.message_group_id
    "MessageBody"    = "$request.body"
  }
}

SQS 送信のための IAM ロール

API Gateway が SQS にメッセージ送信するための権限を付与するための IAM ロールを作成します。

API Gateway に対するロールなので信頼ポリシー（apigateway_assume_role）の principalsに API Gateway を指定します。
付与するポリシーは SQS への送信のみのためactionsとしてsqs:SendMessageのみを指定します。

これらを API Gateway 統合用の IAM ロールに関連付けます。
念の為ですが、aws_iam_role_policies_exclusiveも指定しておきます。

integration.tf

data "aws_iam_policy_document" "apigateway_assume_role" {
  statement {
    actions = ["sts:AssumeRole"]

    principals {
      type        = "Service"
      identifiers = ["apigateway.amazonaws.com"]
    }
  }
}

data "aws_iam_policy_document" "sqs_send_only_policy" {
  statement {
    actions   = ["sqs:SendMessage"]
    resources = ["${aws_sqs_queue.webhook_queue.arn}"]
  }
}

resource "aws_iam_role" "webhook_event_producer_role" {
  name               = "${local.prefix}-webhook-event-producer-role"
  assume_role_policy = data.aws_iam_policy_document.apigateway_assume_role.json
}

resource "aws_iam_role_policy" "sqs_integration_access_policy" {
  name   = "sqs-integration-access-policy"
  role   = aws_iam_role.webhook_event_producer_role.id
  policy = data.aws_iam_policy_document.sqs_send_only_policy.json
}

resource "aws_iam_role_policies_exclusive" "webhook_event_producer_role_policies" {
  role_name = aws_iam_role.webhook_event_producer_role.name
  policy_names = [
    aws_iam_role_policy.sqs_integration_access_policy.name
  ]
}

SQS Labmda トリガー

SQS の準備ができたので、SQS からメッセージを受け取ってアプリケーションの Webhook に送信するための Lambda トリガーを作成します。

SQS Lambda トリガー用 Lambda 関数

メッセージを受け取ったらアプリケーションの Webhook に送信するための AWS Lambda 関数を作成します。
SQS のトリガーとして AWS Lambda を関連付けるためにはキューの URL の環境変数とaws_lambda_event_source_mappingの定義が必要となります。

キューへの URL 指定はaws_lambda_functionの環境変数で設定し、環境変数名はQUEUE_URLになります。
archive_fileデータソースなどの他の設定は通常の AWS Lambda と同様に行います。
設定の詳細は本記事のリポジトリのコードや Terraform のドキュメントを参照してください。

続いてaws_lambda_event_source_mappingを定義します。
イベントソースは当然ながら Webhook 用メッセージキューを指定します。
Lambda 関数も今回定義したトリガ用のものを指定します。
他にバッチサイズ（SSS は 1 つずつなので1）と同時処理最大数を設定しています。

main.tf

resource "aws_lambda_function" "webhook_event_producer" {
  description      = "Webhook Event Producer"
  function_name    = local.webhook_event_producer_function_name
  handler          = "${local.webhook_event_producer_module_name}.lambda_handler"
  filename         = data.archive_file.webhook_event_producer.output_path
  source_code_hash = data.archive_file.webhook_event_producer.output_base64sha256

  role = aws_iam_role.webhook_event_producer_execution_role.arn

  runtime       = var.webhook.runtime
  architectures = ["arm64"]
  timeout       = local.processing_timeout

  environment {
    variables = {
      QUEUE_URL = aws_sqs_queue.webhook_queue.url
    }
  }

  depends_on = [
    aws_iam_role_policy_attachment.webhook_event_producer_basic_execution_role_attach,
    aws_cloudwatch_log_group.webhook_event_producer,
  ]
}

resource "aws_lambda_event_source_mapping" "webhook_event_producer_mapping" {
  event_source_arn = aws_sqs_queue.webhook_queue.arn
  function_name    = aws_lambda_function.webhook_event_producer.function_name
  batch_size       = 1 # 1つのメッセージごとに Lambda 関数を呼び出します
  scaling_config {
    maximum_concurrency = var.webhook.max_concurrency
  }
}

SQS Lambda トリガーのための IAM ロール

SQS Lambda トリガーは SQS からのメッセージを受信する権限のみを付与します。

システム構成図で SQS のイベント監視の AWS Lambda が SQS をポーリングしていましたが、ここにイベントソース処理実装の影響が出ています。
AWS Lambda のロジックには SQS のメッセージ受信処理はないのに、キューの確認やメッセージ受信、受信後のキューからのメッセージ削除などの権限が必要になっています。

main.tf

data "aws_iam_policy_document" "sqs_receive_message_policy" {
  statement {
    actions = [
      "sqs:ReceiveMessage",
      "sqs:ChangeMessageVisibility",
      "sqs:DeleteMessage",
      "sqs:GetQueueAttributes"
    ]
    resources = ["${aws_sqs_queue.webhook_queue.arn}"]
  }
}

resource "aws_iam_role" "webhook_event_producer_execution_role" {
  name               = local.webhook_event_producer_execution_role_name
  assume_role_policy = data.aws_iam_policy_document.lambda_assume_role_policy.json
}

resource "aws_iam_role_policy" "sqs_receive_message_policy" {
  name   = "sqs-receive-message-policy"
  role   = aws_iam_role.webhook_event_producer_execution_role.id
  policy = data.aws_iam_policy_document.sqs_receive_message_policy.json
}

resource "aws_iam_role_policies_exclusive" "webhook_event_producer_execution_role_policies" {
  role_name = aws_iam_role.webhook_event_producer_execution_role.name
  policy_names = [
    aws_iam_role_policy.sqs_receive_message_policy.name,
  ]
}

resource "aws_iam_role_policy_attachment" "webhook_event_producer_basic_execution_role_attach" {
  role       = aws_iam_role.webhook_event_producer_execution_role.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
}

SQS Lambda トリガー関数

Lambda 関数は Python で実装しています。
Python ファイル内には 3 つの関数が定義されています。

lambda_handler
extract_data_from_event
send_request

lambda_handler関数は AWS Lambda のエントリポイント関数で主処理になります。
まず、第 1 引数で渡されたイベントからextract_data_from_eventで宛先とメッセージを取り出します。
次に、send_requestで取得した宛先とメッセージを API Gateway のアプリケーションの Webhook API に転送します。

extract_data_from_eventはデータ構造^[5]をチェックしながら、メッセージグループ ID とメッセージ自体を取り出します。
イベントは Python ではdictとして扱うことができます。
メッセージグループ ID からアプリケーションの URL に変換して、その URL とメッセージ内容を返します。

send_requestは引数で渡された元のアプリケーションの Webhook API の URL に対してメッセージを HTTP の POST メソッドで呼び出します。
API Gateway の呼び出しは普通に HTTP 通信すれば大丈夫です。

Python の Lambda 関数の実装に際して以下の点に注意してください。

データはエンコードする必要がある。
処理に失敗した（DLQ に入れる）場合は例外にする。
- お行儀よく 4xx や 5xx のコードを返して正常終了にしていたら、DLQ にメッセージが転送されませんでした。

AWS Lambda 関数のコード詳細は本記事のリポジトリを参照ください。

データソース

API Gateway はIaC で Sales Support System のインフラ構築で構築したものを取得します。
統合の定義などに API Gateway の ID が必要ですが、aws_apigatewayv2_apiデータソースを直接使うと ID が必要になってしまうのでひと工夫しています。

data.tf

data "aws_apigatewayv2_apis" "this" {
  protocol_type = "HTTP"
  name          = var.apigw_name
}

data "aws_apigatewayv2_api" "this" {
  api_id = one(data.aws_apigatewayv2_apis.this.ids)
}

最後に

SSS では定期リリースのおりに、作業前に通知しているにもかかわらず、SaaS からのメッセージを送る操作をしてしまうユーザがいました。
しかし、これで開発者もユーザもリリースのことを気にせずに作業できるようになりました。
キューイング機能をリリースしてから、実際に何度かリリース中に操作が行われてしまうことがありました。
ですが、DLQ にメッセージが保持されていたため、リリース後に再送することで、後続業務が支障なく進められました。

SSS アプリケーションサービスとは独立したキューとして作成することで、SSS と外部の SaaS との結合度を軽減することが出来ました。
更に、既存のシステムへの改修もなかったため、短期間での導入もできました。
また、DLQ からの再送も AWS 管理コンソールや AWS CLI の機能が使えたため、保守ツールの開発コストも抑えることも出来ました。

今回紹介した内容はIaC で Webhook イベントのキューイングを構築のリポジトリからコードを入手可能です。
また、IaC で Sales Support System のインフラ構築のリポジトリコードと合わせることで、実際に動作させて確認することが出来ます。

運用工数削減に関しては他のエラー対応の改善（半自動化やチェック強化など）の一環でもあります。 ↩︎
参考として AWS のメッセージングサービスの決定木を紹介しているDecision Tree: choose the right AWS messaging service | Better Devも参照。 ↩︎
AWS API Gateway V2 を使う場合（ECS 統合で利用しているため）。利用できない場合は Lambda 経由となるため Lambda の開発が追加になる。 ↩︎
request_paramtersの項目はintegration_subtypeの値によって変わります。詳細はIntegration subtype reference - Amazon API Gatewayを参照。 ↩︎
イベントの具体的な構造はFIFO キューメッセージイベントの例を参照。 ↩︎

GitHub Copilot にも CLI がやってきた！

2025-10-30T00:00:00.000+00:00

はじめに

ちょっと時間が経ってしまいましたが、先月末 GitHub Copilot CLI がパブリックプレビューになりました。

https://github.blog/changelog/2025-09-25-github-copilot-cli-is-now-in-public-preview/

VS Code の拡張から始まった GitHub Copilot も Claude Code や Gemini と同様 CLI としても動作するようになりました。CLI として提供されることで、

IDE 縛りがなくなる
パイプを使って他の CLI ツールとの連携が可能

という強みが追加されます。ターミナルだけで作業が完結できるという点にも魅力を感じる人は多いでしょう。

さらに GitHub にログイン状態で利用するため自分が関わっているリポジトリの操作もできますし、GitHub の MCP サーバーもすぐ利用ます。

日本語のドキュメントは以下から参照できます。

GitHub Copilot CLI の使用 - GitHub Docs

Caution

従来 GitHub CLI の拡張として提供されていた gh-cpilot は Copilot CLI のパブリックプレビューに伴って非推奨となり、Copilot CLI に置き換えられます。

https://github.blog/changelog/2025-09-24-deprecate-github-copilot-extensions-github-apps/

gh-copilot については昨年2月紹介してました。

https://developer.mamezou-tech.com/blogs/2024/02/28/github-copilot-in-cli/

Information

GitHub Copilot CLI は、GitHub Copilot Pro、GitHub Copilot Pro+、GitHub Copilot Business、GitHub Copilot Enterprise プランで使用できます。

インストールと起動

ドキュメントに従ってインストールします。

https://docs.github.com/ja/copilot/how-tos/set-up/install-copilot-cli

npm でグローバルインストール可能です。

npm install -g @github/copilot

GitHub CLI を起動します。

copilot

GitHub CLI の TUI が起動し GitHub へのログイン状態、GitHub MCP サーバへの接続状況が表示されます。

作業するフォルダの信頼について聞かれています。いつも $HOME/dev で作業してるので2番の Yes, and remember this folder for future sessions を選択しました。

Information

筆者の環境では GitHub CLI (Copilot CLI じゃない GitHub 操作用 CLI) で事前に GitHub にログインしているため、その認証トークンでログイン状態になっているのだと思います。

使ってみる

使い方を理解する上では以下のページが役立ちます。

https://docs.github.com/ja/copilot/concepts/agents/about-copilot-cli

対話型モード

TUI 上でプロンプトを入力して対話的に作業を進めるモードです。

GitHub から clone した筆者が作っている Electron アプリのリポジトリ(sbe)のディレクトリに移動してから Copilot CLI を起動しました。

cd sbe
copilot

@ でファイルをメンションできます。@ に続いてパスの一部を入力すると候補が列挙されます。

ソースコードの説明をしてもらいました。

日本語で質問すると日本語で回答してくれます。

対話モードを抜けると利用実績やコードの変更行数などが表示されます。

 Total usage est:       2 Premium requests
 Total duration (API):  15.1s
 Total duration (wall): 12m 33.3s
 Total code changes:    0 lines added, 0 lines removed
 Usage by model:
     claude-sonnet-4.5    24.9k input, 414 output, 0 cache read, 0 cache write (Est. 2 Premium requests)

 Shutting down...

プログラムモード

Copilot CLI に引数やパイプでプロンプトを与えて直接実行するモードです。

copilot -p "explain src/favs.js"

TUI は起動せず直接プロンプトの結果が出力されます。

I'll read the src/favs.js file to explain it to you.

✓ Read src/favs.js (57 lines)

This is a Vue.js 3 app that manages favorites in an Electron application. It creates a UI for displaying and deleting favorite items with these key features:

**Core functionality**: Loads favorites from the Electron backend via `window.favsApi`, displays them in a list, and provides delete functionality with a confirmation dialog. It listens for window focus events to refresh the favorites list.

**Theme support**: Automatically detects and applies light/dark mode based on system preferences using Vuetify's theming system.


Total usage est:       1 Premium request
Total duration (API):  11.5s
Total duration (wall): 15.2s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
    claude-sonnet-4.5    23.6k input, 239 output, 0 cache read, 0 cache write (Est. 1 Premium request)

結果は標準出力に出力され、続いて利用実績も表示されます。

ローカルタスク

ローカルにあるコードを変更するように指示できます。

まず、1つのソースコードのファイルについてのレビューを依頼し、改善ポイントを挙げてもらいました。

Review @src/about.js

良い点として、適切なライフサイクルフックを持つクリーンなコンポーネント構造とか、IPC による関心事の適切な分離などを誉めてくれています。

いくつか問題点を挙げてくれていますが、使用している Vue の beforeUnmount でフォーカス関連のリスナーを削除してないので、メモリリークの懸念があるというのが気になりました。

そこで、この問題を修正するように依頼。

Fix No cleanup problem

beforeUnmount のフックメソッドと Listener 削除のコードが追加されました。リスナーを off で削除する API は存在しないため受け入れる変更ではありません。ですが、今は Copilot CLI の機能を試しているため、他のファイルにも同様に適用をお願いしてみました。ファイルごとに変更していいか聞かれます。

Apply this fix to other files too

全てのファイルに適用が終わりました。

Information

この例では使用しませんでしたが、ローカルタスクにおいて sed とか chmod などの外部コマンドを使用する場合は、使用許可を聞いてきます。--allow-tool で実行時に予め許可を与えることもできます。

GitHub タスク(issue 一覧取得)

GitHub の操作に関するタスクも実行できます。手始めにリポジトリの issue 一覧を表示させてみました。

list my open issues

GitHub タスク(PR 作成)

先ほど試した Electron アプリへのリスナー削除の変更が手元にあるので、そこから PR を作ってもらいます。

create a pull request from this changes

ブランチを作って push までやってくれました。これをもとに PR を作るか確認が入りました。

Yes を選択すると PR が作成されました。

PR の作者は筆者自身となっています。

GitHub タスク(Actions ワークフロー実行)

GitHub タスクでは GitHub Actions ワークフローの操作も可能です。まず、このリポジトリのワークフローを列挙させてみました。

列挙されたワークフローのうち OS Matrix は、クロスプラットフォームで Electron アプリのテストを実行するワークフローです。手動実行時に beta というパラメータを true に設定して実行すると Electron の最新ベータ版をインストールしてテストします。ワークフローファイルはこちらから参照してください。

このワークフローの実行を指示してみました。

Run OS Matrix with input value "beta" to true

(GitHub Copilot CLI ではなく) GitHub CLI を使って実行するプランを提示、実行についてのオプションを提示してきました。

1を選択すると、1回限りの実行を許可、2を選択するとこのセッションを通しての許可を与えることになります。1を選択すると無事に実行できたようです。

実際にちゃんと Electron のベータ版をインストールしてテストが実行されていました。

Web UI を使わなくても GitHUb CLI によるワークフロー実行方法を知らなくても、自然言語で指示すればいいので助かりますね。

さいごに

GitHub Copilot CLI は予想以上に強力な Copilot 協調環境を提供してくれていました。

プロンプトの複数行入力にも対応するなど、GA に向けて改善が進んでいます。

https://github.blog/changelog/2025-10-17-copilot-cli-multiline-input-new-mcp-enhancements-and-haiku-4-5/

MCP サーバーとの連携なども使いこなせれば、ターミナルだけで多くの複雑なタスクがこなせそうですね。

【C# DIコンテナ入門】Microsoft.Extensions.DependencyInjectionの基本と使い方

2025-10-16T00:00:00.000+00:00

C#から7年ほど遠ざかり、久々にデベロッパーサイト向けにC#をやり出しました。そこでふと疑問が出てきました。最近のC#ではDIコンテナはどんなのがあるんだろうと。

以前やっていたときは、Castle WindsorやUnity（ゲーム制作ツールのUnityとは別物）、Seasarなどがありました（実は.NET用のSeasarなんてものがかつては存在しました）。

Castle Windsorのページ
https://www.castleproject.org/projects/windsor/

.NET CoreになってからMicrosoft製のDIコンテナも登場しているようです。他にはAUTOFACというものやNinjectというものもあるようです。

AUTOFACのページ
https://autofac.org/

Ninjectのページ
http://www.ninject.org/

色々ありますが、Microsoft製のものが一番とっつきやすいかなと思って使ってみたところ、本当にとっつきやすかったです。

そのためこの記事ではMicrosoft製のMicrosoft.Extensions.DependencyInjectionの使い方について、サンプルコード付きで解説します。

DIコンテナとは

あらためてDIコンテナとは何かについて確認します。

DI（Dependency Injection）コンテナはオブジェクトの生成、ライフサイクルの管理、依存関係の注入を自動化するライブラリです。コードを疎結合化し、修正やテストをしやすくします。

DIコンテナを使うメリットは主に以下です。

仕様変更などが発生しても、修正の手間を減らせる。
テスト時にはテスト用のクラス（モックと呼ばれる）に差し替えることで、テストをしやすくできる。
どの部品が他のどの部品を必要としているかが分かりやすいため、システムの構造が見通しやすい。

例えば以下のサンプルコードのように、オブジェクトの生成がハードコードされているとします。

public class Sample
{
    private readonly SampleWriter _sampleWriter = new();

    protected override SampleResult ExecuteSample()
    {
        return _sampleWriter.Write($"Execute sample at: {DateTimeOffset.Now}");
    }
}

シンプルなコードなので気にならないと思いますが、SampleWriterクラスを別のクラスで置き換えることを考えてみましょう。

するとSampleWriterクラスのオブジェクトを使っている個所を見直さなければいけなくなります（見直す範囲は仕様次第ですが）。

そこで登場するのがDIコンテナです。DIコンテナは例えるなら「必要なオブジェクトをまとめて提供してくれる万能な倉庫」です。

このインターフェイスにはこのクラスを代入してくださいという設定をDIコンテナに教えます。するとDIコンテナはその設定に基づいて必要なオブジェクトを自動的に作成し、渡してくれます。

例えば先ほどのサンプルコードは次のように修正できます。

public class Sample()
{
    public Sample(ISampleWriter sampleWriter)
    {
        _sampleWriter = sampleWriter;
    }

    private readonly ISampleWriter _sampleWriter;

    protected override SampleResult ExecuteSample()
    {
        return _sampleWriter.Write($"Execute sample at: {DateTimeOffset.Now}");
    }
}

コンストラクタの引数としてDIコンテナからオブジェクトを受け取ります。そしてSampleWriteの型をインターフェイスとしています。

SampleWriterクラスを別のクラスで置き換えるにしても、インターフェイスを使ってISampleWriterとしているので、DIコンテナの設定だけ変えればよくなります。

Microsoft.Extensions.DependencyInjectionとは

Microsoft.Extensions.DependencyInjectionはMicrosoft製のDIコンテナです。NuGetからインストールするだけですぐ使えます。またMicrosoft公式の記事も充実しています。

必要十分な機能を備えており、軽量でシンプルです。そして何より実際にやってみてコーディングが簡単でした。プロジェクト作成時に自動生成されるProgram.csに少し追加するだけなのです。

Microsoft.Extensions.DependencyInjectionはC#で使うには導入のハードルが低いDIコンテナと言ってよいでしょう。

WebAppSample

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddTransient<ISampleProc, SamplePoc>();

var app = builder.Build();

主要な概念

サービス

サービスは依存関係として注入するインスタンスのことです。

例えばIsampleProcというインターフェイスにSampleProcというクラスのインスタンスを注入するよう設定した場合、SampleProcというクラスのインスタンスがサービスに該当します。

サービスには以下の3つのライフサイクルがあります。

種類	概要
Transient	一時的という意味。サービスが要求されるたびに、新しいインスタンスが生成される。一時的な操作を行うサービスや状態を持つべきでないサービスに適している。
Scoped	特定のスコープ内でインスタンスが1つだけ生成される。例えばWebアプリにおけるHTTPリクエスト(リクエストスコープ)やアプリケーション全体(アプリケーションスコープ)。
Singleton	アプリケーション全体でインスタンスが1つだけ生成される。

コンテナ

ISampleProcが要求されたらSampleProcのインスタンスを渡すというインターフェイスとオブジェクトの紐付けや、そのスコープを登録しておくものがコンテナです。

サービスプロバイダー

サービスプロバイダーはコンテナに登録された内容に基づいて依存関係の解決を行います。

あるクラスのオブジェクトが生成されるとき、そのクラスに依存関係の注入が必要なインターフェイスがあったら、オブジェクトを生成して注入します。

言葉だと抽象的なので、コードで見てみましょう。

DiSampleというクラスのオブジェクトをサービスプロバイダーが生成するケースを考えます。

このクラスにはISampleProcがあります。サービスプロバイダーがDiSampleを生成したとき、コンストラクタにISampleProcがあるのを見てSampleProcも生成してくれるのです。

DiSample

public class DiSample
{
    private ISampleProc _sampleProc;

    // コンストラクタでインジェクション
    public DiSample(ISampleProc sampleProc)
    {
        _sampleProc = sampleProc;
    }
}

さらにサービスプロバイダーは依存関係を連鎖解決してくれます。SampleProcにIDbConnectionがある場合を考えてみましょう。

DiSample

public class SampleProc
{
    private IDbConnection _dbConnection;

    // コンストラクタでインジェクション
    public SampleProc(IDbConnection dbConnection)
    {
        _dbConnection = dbConnection;
    }
}

サービスプロバイダーがDiSampleを生成すると、先ほど書いた通りISampleProcがあるのを見てSampleProcも生成が必要だと判断します。

すると次はSampleProcにIDbConnectionがあるのを見て、DbConnectionの生成が必要だと判断します。

こうしてサービスプロバイダーは連鎖解決してオブジェクトを生成してくれます。なんて便利なのでしょう。

サービスの登録方法

AddSingleton

ライフサイクルをSingletonにしてサービスを登録するには、下記のように記述します。

SingletonSample

services.AddSingleton<ISampleProc, SampleProc>();

AddScoped

ライフサイクルをScopedにしてサービスを登録するには、下記のように記述します。

ScopedSample

services.AddScoped<ISampleProc, SampleProc>();

AddTransient

ライフサイクルをTransientにしてサービスを登録するには、下記のように記述します。

TransientSample

services.AddTransient<ISampleProc, SampleProc>();

複数のオブジェクトを登録する方法

Microsoft.Extensions.DependencyInjectionは1つのインターフェイスに対して複数のオブジェクトを登録できます。その場合は後から追加した設定で上書きされ、最後に追加された設定が使われます。

ただしIEnumerable<{SERVICE}>を使って解決すれば、登録したオブジェクトすべてを生成できます。

サンプルコードを見てみましょう。まずはISampleProcに注入するオブジェクトを2つ登録します。

DiEnumerable

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddTransient<ISampleProc, SampleProc>();
builder.Services.AddTransient<ISampleProc, SampleProcess>();

var app = builder.Build();

ResolveSample

public class ResolveSample
{
    public ResolveSample(ISampleProc sampleProc)
    {
        // この場合はSampleProcessのオブジェクトが渡される
    }
}

ResolveSampleEnumerable

public class ResolveSample
{
    public ResolveSample(IEnumerable<ISampleProc> sampleProcs)
    {
        // この場合はIEnumerableにSampleProcとSampleProcessのオブジェクトが入って渡される
        // つまり値が2つあるコレクションとして渡される
    }
}

サンプルコードで実践しつつ解説

サービスとして登録するインターフェイスとクラス

まずはサービスとして登録するインターフェイスとクラスのサンプルコードを提示します。

1つのインターフェイスに対して、インジェクションするオブジェクトのクラスを変えることで、Hello WorldとMorning Worldの表示を切り替えます。またIEnumerableを使って1つのインターフェイスに複数のクラスを登録し、利用するサンプルも掲載します。

以下はHello WorldとMorning Worldを表示するためのインターフェイスとクラスのサンプルコードです。namespaceがDIConsoleAppになっていますが、プロジェクト名やディレクトリ名に合わせてください。

IMessageCreator.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace DIConsoleApp
{
    public interface IMessageCreator
    {
        string CreateMessage();
    }
}

MessageCreatorHello.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace DIConsoleApp
{
    internal class MessageCreatorHello : IMessageCreator
    {
        public string CreateMessage()
        {
            return "Hello, World!";
        }
    }
}

MessageCreatorMorning.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace DIConsoleApp
{
    internal class MessageCreatorMorning : IMessageCreator
    {
        public string CreateMessage()
        {
            return "Morning, World!";
        }
    }
}

続いてこれらのクラスをコンストラクタからインジェクションするサンプルコードを掲載します。

ISampleProc.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace DIConsoleApp
{
    internal interface ISampleProc
    {
        void DisplayMessage();
    }
}

SampleProc.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace DIConsoleApp
{
    internal class SampleProc : ISampleProc
    {
        private IMessageCreator _messageCreator;

        public SampleProc(IMessageCreator messageCreator)
        {
            _messageCreator = messageCreator;
        }

        public void DisplayMessage()
        {
            Console.WriteLine(_messageCreator.CreateMessage());
        }
    }
}

こちらは1つのインターフェイスに複数のクラスが登録されている場合に、複数のクラスのオブジェクトを取得するサンプルコードです。

SampleProcEnumerable.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace DIConsoleApp
{
    internal class SampleProcEnumerable : ISampleProc
    {
        private IMessageCreator _messageCreator;

        public SampleProcEnumerable(IEnumerable<IMessageCreator> messageCreators)
        {
            _messageCreator = messageCreators.ToArray()[0];
        }

        public void DisplayMessage()
        {
            Console.WriteLine(_messageCreator.CreateMessage());
        }
    }
}

コンソールアプリ

まずはコンソールアプリでDIを試してみましょう。理由はシンプルなものから見ていった方が理解しやすいからです。

コンソールアプリプロジェクトを作ってください。そしてインターフェイスやクラスを作成し、先ほど掲載したサンプルコードをコピペしてください。

それができたらProgram.csにDI設定を記述します。

Program.cs

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
using DIConsoleApp;

// ビルダーの作成
HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

// サービスの登録
builder.Services.AddTransient<ISampleProc, SampleProc>();
builder.Services.AddTransient<ISampleProc, SampleProcEnumerable>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorHello>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorMorning>();

// ホストの構築
IHost host = builder.Build();

// サービスの取得と使用
ISampleProc sampleProc = host.Services.GetRequiredService<ISampleProc>();
sampleProc.DisplayMessage();

サービス登録の個所を以下のように、IEnumerableを使わない方のクラスにして実行してみましょう。

Program.cs（一部抜粋）

// サービスの登録
builder.Services.AddTransient<ISampleProc, SampleProc>();
//builder.Services.AddTransient<ISampleProc, SampleProcEnumerable>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorHello>();
//builder.Services.AddTransient<IMessageCreator, MessageCreatorMorning>();

コンソールにHello Worldが表示されればOKです。

これを以下のようにMorningWorld用のクラスに変えて実行してみましょう。

Program.cs（一部抜粋）

// サービスの登録
builder.Services.AddTransient<ISampleProc, SampleProc>();
//builder.Services.AddTransient<ISampleProc, SampleProcEnumerable>();
//builder.Services.AddTransient<IMessageCreator, MessageCreatorHello>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorMorning>();

今度はMorning Worldが表示されます。

それではHello WorldのクラスもMorning Worldのクラスも両方とも登録してみましょう。

Program.cs（一部抜粋）

// サービスの登録
builder.Services.AddTransient<ISampleProc, SampleProc>();
//builder.Services.AddTransient<ISampleProc, SampleProcEnumerable>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorHello>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorMorning>();

この場合は後勝ちとなってMorning Worldが表示されます。

その次はIEnumerableを試してみましょう。コードを次のように変えて実行します。

Program.cs（一部抜粋）

// サービスの登録
//builder.Services.AddTransient<ISampleProc, SampleProc>();
builder.Services.AddTransient<ISampleProc, SampleProcEnumerable>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorHello>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorMorning>();

SampleProcEnumerableでは、以下のようにインデックスが0のオブジェクトを使うようになっています。そのため先に登録されたMessageCreatorHelloのオブジェクトがインジェクションされます。インデックスを1にすれば2番目に登録されたクラスのオブジェクトがインジェクションされます。

SampleProcEnumerable.cs（一部抜粋）

public SampleProcEnumerable(IEnumerable<IMessageCreator> messageCreators)
{
    _messageCreator = messageCreators.ToArray()[0];
}

Webアプリ

WebアプリのDI設定

今度はWebアプリで試してみましょう。やっぱり現実的にはWebアプリのプロジェクトが多いでしょうから、Webアプリでの使い方を知っておきたいところです。

この記事ではRazorページを使って解説していきます。Razorとは何かについてはこちらの記事を参照してください。

C#とRazorで始める効率的なWeb開発！サンプルコード付きで徹底解説

Razorページアプリプロジェクトを作ってください。そしてインターフェイスやクラスを作成し、先ほど掲載したサンプルコードをコピペしてください。

そしたらProgram.csを開いてみてください。次のようになっています。

Program.cs

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

なんとRazorページアプリプロジェクトのProgram.csには、最初からMicrosoft.Extensions.DependencyInjectionで使うビルダーが記述されているのです。RazorページがDI設定同様にサービスとして登録されているのです。

ここがMicrosoft.Extensions.DependencyInjectionの導入のしやすさなのでしょう。仕組みがRazorページのようなC#でよく使う技術と共通化されているわけですね。

Razorページの登録前にDI設定を記述します。サンプルコードは以下です。コメントで「サービスの登録」と記述した個所が該当します。

Program.cs

using DIConsoleApp;

var builder = WebApplication.CreateBuilder(args);

// サービスの登録
builder.Services.AddTransient<ISampleProc, SampleProc>();
builder.Services.AddTransient<ISampleProc, SampleProcEnumerable>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorHello>();
builder.Services.AddTransient<IMessageCreator, MessageCreatorMorning>();

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Webアプリの動作確認

Webアプリの場合は確認用の画面を作る必要もあります。Indexを修正し、SampleProcとSampleProcEnumerableというRazorページを作ってください。ページ遷移のイメージはこの画像のようになります。

Webアプリのサンプルのページ遷移

サンプルコードを掲載します。まずはIndex.cshtmlに以下のようにアンカータグを2ページ分追加します。

Index.cshtml

<div class="text-center">
    <h1 class="display-4">Welcome</h1>
    <p>Learn about <a href="https://learn.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.</p>
    <p><a href="/SampleProc">SampleProc</a></p>
    <p><a href="/SampleProcEnumerable">SampleProcEnumerable</a></p>
</div>

そしたらSampleProc（後勝ち用のページ）とSampleProcEnumerable（IEnumerable用のページ）を作ります。まずはSampleProcのサンプルコードを掲載します。

SampleProc.cshtml

@page
@model DIWebApp.Pages.SampleProcModel
@{
}

<h2>SampleProc</h2>
<p>@Model.DisplayMessage()</p>

SampleProc.cshtml.cs

using DIWebApp;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace DIWebApp.Pages
{
    public class SampleProcModel : PageModel
    {
        private IMessageCreator _messageCreator;

        public SampleProcModel(IMessageCreator messageCreator)
        {
            _messageCreator = messageCreator;
        }

        public string DisplayMessage()
        {
            return _messageCreator.CreateMessage();
        }

        public void OnGet()
        {
        }
    }
}

続いてSampleProcEnumerable（IEnumerableを使うページ）のサンプルコードを掲載します。

SampleProcEnumerable.cshtml

@page
@model DIWebApp.Pages.SampleProcEnumerableModel
@{
}

<h2>SampleProcEnumerable</h2>
<p>@Model.DisplayMessage()</p>

SampleProcEnumerable.cshtml.cs

using DIWebApp;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace DIWebApp.Pages
{
    public class SampleProcEnumerableModel : PageModel
    {
        private IMessageCreator _messageCreator;

        public SampleProcEnumerableModel(IEnumerable<IMessageCreator> messageCreatora)
        {
            _messageCreator = messageCreatora.ToArray()[0];
        }

        public string DisplayMessage()
        {
            return _messageCreator.CreateMessage();
        }

        public void OnGet()
        {
        }
    }
}

デバッグ起動すると最初にIndex画面が表示されます。

そしたらSampleProcとSampleProcEnumerableにアクセスして、先ほどのコンソールアプリ同様に、後勝ちであることやIEnumerableについて実行して確認してみてください。

おわりに

私はC#にはLINQやRazorなどとても便利な技術があるのに、DIコンテナはいまいちだなぁと感じていました。

しかし今回Microsoft.Extensions.DependencyInjectionを使ってみて、C#にも簡単に扱えるDIコンテナがあるんだと知りました。

かつて私がCastle Windsorを使ったときは、.NET MVCで今のProgram.csに該当するクラスにもっと複雑なコードを書いていました。そしてXMLに冗長なDI設定を書いていました。

それと比べるとMicrosoft.Extensions.DependencyInjectionは書くべき個所が明確ですし、書き方も簡単ですね。これなら導入のハードルは低いです。

もしC#で開発する際のDIコンテナに迷っているようでしたら、Microsoft.Extensions.DependencyInjectionを使ってみてはいかがでしょうか。その際にこの記事が参考になれば幸いです。

クラウドに頼らないAI体験：LM Studio＋LangChain＋StreamlitでつくるローカルRAGのマルチドキュメント・永続化対応

2025-10-15T00:00:00.000+00:00

はじめに

前回の記事では、1つのテキストファイル（桃太郎物語） を対象にした単純なRAG（検索＋生成）環境を構築しました。
今回はその拡張として、複数のドキュメントを読み込み・保持・削除できる永続化対応のローカルRAGアプリを構築します。

全体構成

ディレクトリ構造

project/
├─ app2.py              # 本体アプリケーション
├─ vectorstore/         # ベクトルストアの永続化ディレクトリ
│   ├─ faiss_index/     # FAISSのインデックスファイル
│   ├─ metadata.json    # 読み込まれたファイル一覧
│   └─ temp_docs/       # アップロードされたドキュメントの一時保存場所

新しいアプリ（app2.py）では次のような進化があります。

機能	内容
マルチドキュメント対応	PDF, Word, PowerPoint, テキストなど複数ファイルを同時に学習可能
永続化ストレージ	ベクトルDB（FAISS）をローカル保存し、再起動後も再構築不要
個別ファイル削除	特定のファイルだけを削除し、DBを再構築
UI強化	Streamlitのサイドバーでファイル一覧・削除・全削除操作が可能
精度向上	MultiQueryRetrieverで質問を多角的に変換して検索精度を改善

アプリを起動すると、vectorstore/以下に自動で必要なフォルダが作成されます。
ファイルを追加すると、ベクトルDBとメタデータがディスクに永続化されます。

必要なライブラリ

必要なライブラリを以下のコマンドでインストールします。

pip install langchain langchain-openai langchain-community langchain-huggingface sentence-transformers streamlit faiss-cpu pypdf python-docx python-pptx pydantic cryptography unstructured docx2txt

プログラム全体

本体ソースコードは以下です。
ソースコード中のコメントに処理内容を記載しています。
かなり行数が多いので、プログラムの主要な部分についてはこの後解説します。

import streamlit as st
import os
import tempfile
from pathlib import Path
import shutil
import json
import uuid 

# --- LangChain関連ライブラリのインポート ---
# LLM（大規模言語モデル）および埋め込みモデルを利用したRAG（Retrieval-Augmented Generation）構成に使用
from langchain_openai import ChatOpenAI  # OpenAI互換LLM（例：LM Studio/Ollama）との接続用
from langchain_huggingface import HuggingFaceEmbeddings  # HuggingFaceの埋め込みモデル（ベクトル化用）
from langchain.text_splitter import RecursiveCharacterTextSplitter  # 文書をチャンク単位に分割
from langchain_community.vectorstores import FAISS  # 高速ベクトル検索エンジン（ローカル永続化対応）
from langchain.chains import RetrievalQA  # 検索と回答生成を結合したRAGチェーン
from langchain_community.document_loaders import (
    PyPDFLoader, Docx2txtLoader, TextLoader, UnstructuredPowerPointLoader
)  # 各種ファイル形式のローダー
from langchain.prompts import PromptTemplate  # LLMへのプロンプトテンプレート
from langchain.retrievers.multi_query import MultiQueryRetriever  # 複数クエリ拡張による検索精度向上

# ============================================================
# 永続化関連のパス設定
# ============================================================
DB_DIR = "vectorstore"  # ベクトルストア保存ディレクトリ
DB_FAISS_PATH = Path(DB_DIR) / "faiss_index"  # FAISSベクトルインデックスファイル
DB_METADATA_PATH = Path(DB_DIR) / "metadata.json"  # メタデータ保存ファイル
TEMP_DOCS_DIR = Path(DB_DIR) / "temp_docs"  # 一時的なアップロードファイルの保存先

# ============================================================
# file_uploader のキーを初期化
# ============================================================
# file_uploaderを再初期化するためのユニークキーを設定
if 'file_uploader_key' not in st.session_state:
    st.session_state['file_uploader_key'] = str(uuid.uuid4())

# ============================================================
# ファイル読み込み関数
# ============================================================
def load_document(file_path):
    """拡張子に応じて適切なLangChainローダーで文書を読み込む"""
    ext = os.path.splitext(file_path)[1].lower()
    if ext == ".pdf":
        loader = PyPDFLoader(str(file_path))
    elif ext == ".docx":
        loader = Docx2txtLoader(str(file_path))
    elif ext == ".pptx":
        loader = UnstructuredPowerPointLoader(str(file_path))
    else:
        loader = TextLoader(str(file_path), encoding="utf-8")
    return loader.load()  # LangChain Document形式で返却

# ============================================================
# 埋め込みモデル初期化（キャッシュ利用）
# ============================================================
# 埋め込みモデルをキャッシュして再利用する関数
@st.cache_resource(show_spinner=False)
def get_embeddings():
    """HuggingFaceのSentence-BERTモデルを一度だけロードしキャッシュ"""
    return HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")

# ============================================================
# ベクトルDB構築関数
# ============================================================
# ベクトルDBを構築し、ファイルリストと共にディスクに保存する関数
@st.cache_resource(show_spinner=False)
def build_and_save_db(documents, file_metadata_list):
    """文書群からFAISSベクトルDBを構築し、メタデータと共に保存"""
    if not documents:
        # 文書が空の場合は既存DBを削除
        if Path(DB_DIR).is_dir():
            shutil.rmtree(DB_DIR)
        return None
    
    # 文書を小さなチャンクに分割（500文字単位で100文字重複）
    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=500, 
        chunk_overlap=100, 
        length_function=len
    )
    docs = text_splitter.split_documents(documents) # 分割実行
    # 埋め込みモデルの初期化 (Sentence-BERTベースのモデルを使用)
    embeddings = get_embeddings()  # 埋め込みモデルの取得

    # FAISSベクトルストアの新規構築
    db = FAISS.from_documents(docs, embeddings)
    
    # 永続化ディレクトリ作成と保存
    Path(DB_FAISS_PATH).parent.mkdir(parents=True, exist_ok=True)
    db.save_local(str(DB_FAISS_PATH))

    # メタデータをJSONとして保存
    with open(DB_METADATA_PATH, "w", encoding="utf-8") as f:
        json.dump(file_metadata_list, f, ensure_ascii=False, indent=4)

    return db

# ============================================================
# RAGチェーン構築関数
# ============================================================
# 保存されたDBをロードし、RAGチェーンを作成する関数
def create_rag_chain_from_db(db):
    """既存DBからRAGチェーン（Retrieval＋LLM）を構築"""
    llm = ChatOpenAI(
        model_name="local-model",                       # LM Stduioに読み込まれているモデルを指定（モデル名は特定していない）
        openai_api_base="http://localhost:1234/v1",     # LM StduioサーバのURL
        openai_api_key="not-needed",                    # API-keyは無し
        temperature=0.1,                                # 高い確率の単語を優先的に選ぶ
        max_tokens=512                                  # 最大512トークンに制限
    )

    # 検索精度向上のため、質問を複数クエリに拡張するRetriever
    # MultiQueryRetrieverを設定: 質問をLLMに渡し、複数の質問に言い換えて検索精度を向上させる
    # search_kwargs={"k": 2} で取得する文書チャンク数を2つに制限し、応答速度を改善    
    retriever = MultiQueryRetriever.from_llm(
        retriever=db.as_retriever(search_kwargs={"k": 2}),
        llm=llm
    )

    # RAGプロンプト定義（回答方針）
    prompt_template = """
        以下の参考文章を元に、質問に日本語で回答してください。
        参考文章に答えが見つからない場合は、「分かりません」と回答してください。
        参考文章: {context}
        質問: {question}
    """
    PROMPT = PromptTemplate(
        template=prompt_template, 
        input_variables=["context", "question"]
        )

    # RetrievalQAチェーンを生成（検索→回答生成の一連の流れ）
    qa_chain = RetrievalQA.from_chain_type(
        llm=llm,
        chain_type="stuff",  # 検索結果を全てプロンプトに詰め込む方式
        retriever=retriever,
        return_source_documents=True, # 回答の根拠となった文書（ソース）を返す設定
        chain_type_kwargs={"prompt": PROMPT} # カスタムプロンプトを適用
        )
    return qa_chain

# ============================================================
# 個別ファイル削除とDB再構築
# ============================================================
# 個別ファイル削除とDB再構築のロジック
def delete_single_file(file_id_to_delete):
    """指定されたファイルIDを削除し、残りの文書でDBを再構築"""
    if not DB_METADATA_PATH.exists():
        st.error("メタデータが見つかりません。全体削除を推奨します。")
        return

    with open(DB_METADATA_PATH, "r", encoding="utf-8") as f:
        current_metadata = json.load(f)
    
    # 削除対象を特定
    file_to_remove = next((item for item in current_metadata if item["id"] == file_id_to_delete), None)
    if not file_to_remove:
        st.error("削除対象のファイルIDが見つかりませんでした。")
        return

    # 一時ファイルを削除
    temp_path = Path(file_to_remove["temp_path"])
    if temp_path.exists():
        os.remove(temp_path)

    # 残りのファイルでDBを再構築
    new_metadata = [item for item in current_metadata if item["id"] != file_id_to_delete]
    all_documents = []

    with st.spinner(f"ファイルを削除し、残りのデータでAIを再構築中..."):
        # 残ったすべてのファイルを再ロード
        for item in new_metadata:
            doc_path = Path(item["temp_path"])
            if doc_path.exists():
                documents = load_document(doc_path)
                all_documents.extend(documents)
        
        # 既存キャッシュをクリアしてDB再構築
        if "rag_chain" in st.session_state:
            del st.session_state["rag_chain"]
        build_and_save_db.clear()

        # 残りの文書でDBを再構築し、保存
        db = build_and_save_db(all_documents, new_metadata)

        # 再構築後の状態更新
        if db:
            st.session_state.rag_chain = create_rag_chain_from_db(db)
            st.session_state.current_files = new_metadata
            st.toast(f"✅ ファイル '{file_to_remove['name']}' を削除し、DBを更新しました。", icon="🗑️")
        else:
            # 全削除された場合の後処理
            keys_to_delete = ["rag_chain", "messages", "current_files", "file_identifiers"]
            for key in keys_to_delete:
                if key in st.session_state:
                    del st.session_state[key]
            st.toast("✅ 全てのファイルを削除しました。", icon="🗑️")
            st.session_state['file_uploader_key'] = str(uuid.uuid4())

    st.rerun()  # Streamlit再実行でUI更新

# ============================================================
# 全体削除処理
# ============================================================
def delete_all_data():
    """DBディレクトリとセッション変数を全削除"""
    if Path(DB_DIR).is_dir():
        try:
            shutil.rmtree(DB_DIR)
            st.toast("✅ 全ての読み込みデータを削除しました。", icon="🗑️")
        except OSError as e:
            st.error(f"データの削除中にエラーが発生しました: {e}")
            return

    # セッション変数をクリア
    keys_to_delete = ["rag_chain", "messages", "current_files", "file_identifiers"]
    for key in keys_to_delete:
        if key in st.session_state:
            del st.session_state[key]
    # file_uploader のキーをリセット
    st.session_state['file_uploader_key'] = str(uuid.uuid4())
    st.rerun()

# ============================================================
# Streamlit UI 構築
# ============================================================
st.title("📄 ドキュメント Chatbot")
st.write("複数のPDF, DOCX, PPTX, テキストファイルをアップロードして、内容について質問してください。")

# --- サイドバー: ファイルアップロード ---
uploaded_files = st.sidebar.file_uploader(
    "ファイルをアップロード（既存DBに追加・上書き）",
    type=["pdf", "docx", "pptx", "txt", "md"],
    accept_multiple_files=True,
    key=st.session_state['file_uploader_key']
)

# --- DB存在チェック ---
db_exists = DB_FAISS_PATH.exists()
metadata_exists = DB_METADATA_PATH.exists()
current_file_identifiers = [(f.name, f.size) for f in uploaded_files]

# ----------------------------------------------------------------------
# 初期化ロジック (既存データと新規データの結合処理)
# ----------------------------------------------------------------------

# 1. 新しいファイルがアップロードされた場合 (追加/新規構築＆保存)
if uploaded_files:
    
    # 既存のメタデータ（ファイルリスト）をロード
    existing_metadata = []
    if metadata_exists:
        with open(DB_METADATA_PATH, "r", encoding="utf-8") as f:
            existing_metadata = json.load(f)
    
    # 既存のファイル名（name）のセットを作成（重複チェック用）
    existing_names = {meta['name'] for meta in existing_metadata}

    # ----------------------------------------------------
    # 新規アップロードファイルの処理
    # ----------------------------------------------------
    newly_uploaded_files = []
    
    # アップロードされたファイルの中から、既存ファイル名と重複しないものだけを選択
    for uploaded_file in uploaded_files:
        if uploaded_file.name not in existing_names:
            newly_uploaded_files.append(uploaded_file)
        else:
             # 既存ファイルと同じ名前の場合はスキップ（上書きは行わない）
             pass 
    
    if newly_uploaded_files:
        
        all_documents = []
        new_metadata_list = []
        
        TEMP_DOCS_DIR.mkdir(parents=True, exist_ok=True)
        
        with st.spinner("新しいファイルを読み込んでいます..."):
            for uploaded_file in newly_uploaded_files:
                unique_id = str(uuid.uuid4())
                
                # 新しい一時ファイルとして保存
                temp_path = TEMP_DOCS_DIR / f"{unique_id}_{uploaded_file.name}"
                temp_path.write_bytes(uploaded_file.getvalue())
                
                # 新しいファイルのメタデータを生成
                new_metadata_list.append({
                    "id": unique_id, # 一意なID
                    "name": uploaded_file.name,
                    "temp_path": str(temp_path)
                })

                documents = load_document(temp_path)
                all_documents.extend(documents) # ドキュメントリストに追加
        
        # ----------------------------------------------------
        # 既存データと新規データの結合
        # ----------------------------------------------------
        
        # 既存のファイルを再度ロードし、全ドキュメントリストに結合
        for meta in existing_metadata:
             doc_path = Path(meta["temp_path"])
             if doc_path.exists():
                 documents = load_document(doc_path)
                 all_documents.extend(documents)
             
        # メタデータリストを結合
        combined_metadata = existing_metadata + new_metadata_list

        with st.spinner("AIのデータ統合と再構築をしています..."):
            
            # 古いキャッシュをクリア
            if "rag_chain" in st.session_state:
                del st.session_state["rag_chain"]
            build_and_save_db.clear()

            # 全文書と全メタデータでDBを再構築し、保存
            db = build_and_save_db(all_documents, combined_metadata)
            st.session_state.rag_chain = create_rag_chain_from_db(db)
            st.session_state.current_files = combined_metadata # セッションに新しいファイルリストを保存
        
        st.session_state.messages = []
        st.info("新しいデータが既存のデータに追加され、AIの準備が完了しました。")

        # DB構築成功後、アップローダーのリスト（赤枠部分）をクリアするためにリセット
        st.session_state['file_uploader_key'] = str(uuid.uuid4())
        st.rerun() 

    else:
        # アップロードはされたが、すべて既存ファイル名と同じだった場合
        st.info("アップロードされたファイルはすべて既に読み込まれているファイル名と同じだったため、処理をスキップしました。")
        # スキップされた場合も、手動での削除を防ぐためにアップローダーをリセット
        st.session_state['file_uploader_key'] = str(uuid.uuid4())
        st.rerun() 

# 2. アップロードがなく、既存DBファイルが存在する場合 (高速ロード)
elif not uploaded_files and db_exists and "rag_chain" not in st.session_state:
    with st.spinner("既存のAIデータ（DB）を読み込んでいます..."):
        # 埋め込みモデルをロード
        embeddings = get_embeddings()
        # 既存のFAISS DBをディスクからロード
        db = FAISS.load_local(str(DB_FAISS_PATH), embeddings, allow_dangerous_deserialization=True)
        st.session_state.rag_chain = create_rag_chain_from_db(db)
        
        # 既存のメタデータ（ファイルリスト）をロード
        if metadata_exists:
            with open(DB_METADATA_PATH, "r", encoding="utf-8") as f:
                loaded_metadata = json.load(f)
            st.session_state.current_files = loaded_metadata
            st.success("既存のドキュメントでチャット可能です。")
        else:
            st.session_state.current_files = []
            st.warning("既存のドキュメントでチャット可能ですが、元のファイル名リストが見つかりませんでした。")
        
        st.session_state.messages = []


# 3. 初期メッセージの表示
if "rag_chain" not in st.session_state and not db_exists:
    st.info("ファイルをアップロードするか、過去に保存したデータが存在すれば自動的にロードされます。")

# ----------------------------------------------------------------------
# 表示ロジック: 現在読み込まれているファイル名の表示と削除ボタン 
# ----------------------------------------------------------------------
if "current_files" in st.session_state:
    st.sidebar.markdown("---")
    st.sidebar.subheader("現在読み込まれているファイル")
    
    if st.session_state.current_files:
        for file_meta in st.session_state.current_files:
            col1, col2 = st.sidebar.columns([0.8, 0.2])
            
            # ファイル名を表示
            col1.markdown(f"- **{file_meta['name']}**")
            
            # 個別削除ボタンのUI (ポップオーバーで確認)
            with col2.popover("🗑️", help="このファイルを削除します"):
                st.write(f"ファイル **{file_meta['name']}** を削除し、DBを再構築しますか？")
                if st.button("削除を確定", key=f"delete_{file_meta['id']}", type="secondary"):
                    delete_single_file(file_meta['id'])
    else:
        st.sidebar.markdown("- ファイルがありません。")

    st.sidebar.markdown("---")
    if Path(DB_DIR).is_dir():
        # 全体削除ボタン
        if st.sidebar.button("🗑️ 全ての読み込みデータを削除", type="secondary"):
            delete_all_data()

# ============================================================
# チャット処理
# ============================================================
if "rag_chain" in st.session_state:
    # 履歴表示
    if "messages" in st.session_state:
        for message in st.session_state.messages:
            with st.chat_message(message["role"]):
                st.markdown(message["content"])

    # ユーザー入力受付
    if prompt := st.chat_input("ドキュメントについて質問をどうぞ"):
        with st.chat_message("user"):
            st.markdown(prompt)
        st.session_state.messages.append({"role": "user", "content": prompt})

        rag_chain = st.session_state.rag_chain
        with st.spinner("考え中..."):
            # RAG実行（検索＋回答生成）
            response = rag_chain.invoke({"query": prompt})
            answer = response["result"]

        # 回答表示と参照ソース展開
        with st.chat_message("assistant"):
            st.markdown(answer)
            with st.expander("参考にした文章"):
                for doc in response["source_documents"]:
                    st.markdown(f"--- \n {doc.page_content}")

        st.session_state.messages.append({"role": "assistant", "content": answer})

コード全体の構造

app2.pyの構成を俯瞰すると以下のようになります。

1.  ドキュメントローダー関数群
2.  ベクトルDB構築・保存・ロード関数
3.  RAGチェーン生成関数（MultiQueryRetrieverによる検索精度向上）
4.  ファイル削除ロジック
5.  Streamlit UI構成
    - サイドバー: アップロード・削除・一覧表示
    - メイン画面: チャットUI

この分離構造により、RAG処理とUIが明確に分かれ、拡張性が高い設計になっています。

主要コンポーネントの説明

この章では、app2.py の内部構造をさらに掘り下げ、各関数やモジュールがどのように連携して RAG (Retrieval-Augmented Generation) 環境を構築しているのかを詳しく解説します。

1. ドキュメントローダー（Document Loader）

この部分はシステムの「入力ゲート」として機能します。アップロードされたファイルを受け取り、LangChain が扱える Document オブジェクトに変換します。これにより、後続のベクトル化処理や検索が統一的に実施できます。
内部では拡張子を基に適切なローダークラスを選択し、PDF・Word・PowerPoint・テキストの各形式に対応しています。
ローダーは単にテキストを抽出するだけでなく、ページ情報などのメタデータも付与します。

load_document()関数で、PDF・DOCX・PPTX・TXTなどのファイル形式を自動判別して読み込みます。
LangChainの各種ローダーを活用しています。

from langchain_community.document_loaders import (
    PyPDFLoader, Docx2txtLoader, TextLoader, UnstructuredPowerPointLoader
)

2. ベクトルDB（FAISS）永続化

RAG の根幹を担うのがこの部分です。分割・埋め込み・保存の3工程で構成され、アップロードした複数の文書を検索可能な形に変換します。

分割：RecursiveCharacterTextSplitter により、文脈の自然な区切りを保ったままテキストをチャンク化。
埋め込み：HuggingFaceEmbeddings によるSentence-BERTモデル（all-MiniLM-L6-v2）を使用し、文意を数値ベクトルに変換。
保存：FAISSによってベクトル空間を構築し、インデックスファイルとしてローカル保存。

これらを組み合わせることで、アプリを再起動しても同一の知識ベースを即座に再利用できる「永続化RAG」が実現しています。

分割したドキュメントチャンクを埋め込み（ベクトル化）し、FAISSで保存します。
保存先はvectorstore/faiss_index/です。
また、読み込んだファイル情報（UUID、ファイル名、保存パス）はmetadata.jsonに保持します。

これにより、アプリを再起動しても同じ知識ベースを即座に再利用できます。

また、アプリの中で特に処理時間が長くなりやすいのが、埋め込みモデルのロードやFAISSベクトルDBの構築です。
これらを毎回ゼロから実行すると、ユーザー体験が大きく損なわれます。

そこで Streamlit の @st.cache_resource デコレータを利用しています。
これは、関数の戻り値（モデルやデータベースなどの「リソース」）をキャッシュし、再利用可能にする仕組みです。
以前の @st.cache の後継であり、リソース指向のキャッシュをより安全かつ効率的に扱うことができます。

3. MultiQueryRetrieverによる検索精度向上

標準的なRAGでは、ユーザーの質問を1つのクエリに変換して検索しますが、このプログラムでは LangChain の MultiQueryRetriever を採用し、LLMが質問を複数の言い換えに自動変換します。

たとえば「品質管理とは何か？」という質問に対して、LLMは内部で以下のような複数クエリを生成します：

品質管理の定義とは？
ソフトウェア品質保証との違いは？
品質を維持・改善する方法とは？

これにより、文書中の言い換え表現や別の文脈にもマッチしやすくなり、検索精度が大幅に向上します。

単一の質問に対し、LLMが複数の検索クエリを自動生成し、類似文書を多角的に探索します。
これにより、言い換えや表現の揺れに強いRAGが実現できます。

from langchain.retrievers.multi_query import MultiQueryRetriever

retriever = MultiQueryRetriever.from_llm(
    retriever=db.as_retriever(search_kwargs={"k": 2}),
    llm=llm
)

search_kwargs={"k": 2} の 「k」 は、Retriever が検索時に取得する類似文書チャンクの件数（トップK件） を表します。
つまり、「最も関連度の高い文書を上位2件だけ取得する」という設定です。

LangChain の Retriever は、ユーザーの質問と文書をベクトル空間上で比較し、コサイン類似度が高い順に K 件の文書チャンクを返します。

パラメータ	意味
`k`	類似度上位 K 件の文書を取得する
`search_kwargs`	検索時の動作パラメータをまとめた辞書
`db.as_retriever()`	ベクトルDB（FAISSなど）を検索エンジンとして利用する設定

なぜ「2」を選んでいるのかは、検索精度・処理速度・トークン消費のバランスを最適化するためです。

観点	kが大きい場合	kが小さい場合（例：2）
検索精度	多くの文書を参照できるが、関係ない文も混ざりやすい	関連度の高い文脈に限定できる
処理速度	応答が遅くなる（特にローカル実行時）	高速で軽量に動作する
トークン消費	多文書入力により増加	少なく済むため効率的
適用場面	大規模RAGや多分野文書	小規模・単一テーマのRAG（本アプリに最適）

本アプリでは「ローカル実行」「FAISS永続化」「中〜小規模ドキュメント」を前提としているため、過剰な文脈を含めずに回答の精度と速度を両立させることが重要です。

LLM（LM Studio / Ollamaなど）のコンテキスト長に収まるよう調整
StreamlitのUI上で応答をスムーズに返すため、処理時間を短縮
ノイズ文書を除去して、より一貫性のある回答を生成

チューニングの目安は以下です。

k値	特徴	想定用途
1	最速・最小トークン。文脈が単純な場合に最適。	短文中心・単一テーマ
2〜3	精度と速度のバランスが良い。	通常のRAG（本アプリ推奨）
5以上	網羅的だが遅い。長文・百科事典的な用途に適する。	多分野・長文RAG

このように、k=2 は「精度・速度・軽量性の最適点」 を狙った実装上の設計判断です。

4. ファイル削除操作

永続化されたデータを扱う場合、部分的な削除や再構築の制御が不可欠です。
このアプリでは2段階の削除ロジックを実装しています：

個別削除：特定のファイルIDを基に、そのファイルに対応する一時保存データとメタ情報を削除し、残りのデータからDBを再構築します。
全削除：vectorstore/ディレクトリ全体を削除し、完全な初期化を行います。

削除処理はすべてStreamlitのセッション状態と連動しており、削除後にst.rerun()でアプリを再描画することで、UIが即時更新されます。

アプリは、ファイルアップロード時に自動でベクトルDBを再構築します。
また、以下の2種類の削除機能を備えています。

操作	動作
個別削除	特定ファイルを削除し、残りのデータでDBを再構築
全削除	`vectorstore/`ディレクトリ全体を削除して完全初期化

削除後は自動でUIがリフレッシュされ、状態が更新されます。

5. Streamlit UI の特徴

アプリケーションの操作性を担うフロントエンド部分です。Streamlitのコンポーネントを駆使し、シンプルながら実用的なチャットUIを構築しています。特筆すべき点は次の通りです。

サイドバー：ファイル管理・削除・リスト表示の制御を集中化。
チャットエリア：st.chat_message を使い、ユーザーとAIの会話履歴を対話形式で可視化。
再現性：Streamlitのsession_stateを活用することで、状態保持と再初期化を両立しています。

さらに、チャットの背後ではRAGチェーン（RetrievalQA）が動作しており、質問ごとに検索→生成の2段階推論を行います。

サイドバー

ファイルアップロード（複数対応）
現在読み込まれているファイル一覧
各ファイルの削除ボタン
「全削除」ボタン

メイン画面

チャット履歴の表示
「ドキュメントについて質問をどうぞ」入力欄
AI回答と「参考にした文章」の展開パネル

実行方法

LM Studioで http://localhost:1234 サーバを起動（事前にLLMをロードしておく）
ターミナルで以下を実行：

streamlit run app2.py

ブラウザ（通常は http://localhost:8501）でアプリが開きます。

初回起動時は「ファイルをアップロードしてください」というメッセージが表示されます。
PDFやテキストをアップロードすると、自動的に学習・永続化が行われます。

例：複数ドキュメントを活用したRAG

前回の「桃太郎」のほかに「かぐや姫」の物語をRAGに読み込ませます。
かぐや姫の物語は以下のようにしました。

むかしむかし、竹を取って暮らす翁（おきな）と、その妻が住んでいました。
ある日、翁が山で光る竹を見つけ、その竹を割ると中から小さな女の子が出てきました。
翁はその子を家に連れ帰り、妻とともに「かぐや姫」と名付けて大切に育てました。
かぐや姫は美しく成長し、そのうつくしさは都にまで広まりました。
多くの貴族が求婚しましたが、かぐや姫は誰の申し出も受けず、難しい宝を求めて試しました。
誰一人として成功する者はいませんでした。
やがて帝もかぐや姫を愛しましたが、彼女の心は月の国にありました。
十五夜の夜、月の使者が迎えに来て、かぐや姫は涙を流しながら月へ帰っていきました。
翁と妻は深く悲しみ、いつまでも夜空を見上げてかぐや姫を思いました。

「桃太郎」と「かぐや姫」の2つのテキストをアップロードした場合、両者の内容を組み合わせた質問にも正確に回答できます。

それぞれを読み込ませます。

質問例：「桃太郎とかぐや姫にはどんな共通点がありますか？」

RAGはそれぞれの物語から類似する文脈を抽出し、両者を比較した回答を生成します。

回答として以下のような文章が出力されました。

回答の中の「どちらも最終的に元の場所へ帰っていくという結末」は、双方が元居た場所に戻るというところを関連付けているのが面白いです。
（桃太郎はおじいさん、おばあさんの元へ。かぐや姫は月へ）

まとめ

今回の拡張版では、ローカルRAG環境をより実践的な形に進化させました。

改善点	効果
FAISS永続化	再起動後もDB再構築不要で高速起動
MultiQueryRetriever	検索精度の向上
ファイル管理UI	アップロード・削除を視覚的に操作可能
複数ファイル形式対応	PDF/DOCX/PPTX/TXTを混在学習可能

ローカル環境で完結しながらも、実用的な知識アシスタントを実現できるようになりました。
次回は、文書の要約・分類機能の追加や、OpenAI互換API以外のモデル（例：Ollama, Llama.cpp）対応にも拡張していく予定です。

クラウドに頼らないAI体験：LM Studio＋LangChain＋StreamlitでつくるローカルRAG環境

2025-10-14T00:00:00.000+00:00

はじめに

前回は、LM Studio＋Gemmaでクラウドに頼らないAI環境を構築しました。

本記事では、LM Studio を使ってローカルでLLM（例：Gemma 3 4B）を動かし、さらに LangChain と Streamlit を組み合わせて、クラウドに頼らずに動作する RAG（Retrieval-Augmented Generation） 環境を構築します。

題材として、誰もが知っている「桃太郎」の物語を使い、自分で用意した知識ベースを読み込む ローカルAIチャットボット を作っていきます。

今回のゴールは以下です。

LM StudioでローカルLLMをAPIサーバーとして動かす
LangChainでRAG（検索＋生成）パイプラインを構築する
StreamlitでチャットUIを作成する

すべて自分のPC上で完結し、インターネット接続がなくても動作します。
まさに「自分だけのAI」を作る第一歩です。

LangChainとは

LangChain は、大規模言語モデル（LLM）を外部データと統合して活用するためのフレームワーク です。
特に、RAG（Retrieval-Augmented Generation） の構築を容易にする仕組みを提供します。

今回作成するRAG環境では次の4つの処理を組み合わせて、より正確で文脈に基づいた回答を生成します。

ステップ	処理内容	LangChainの機能
① テキスト分割	ドキュメントを小さなチャンクに分割	`TextSplitter`
② 埋め込み生成	テキストをベクトル化	`Embeddings`
③ 検索	質問と類似したチャンクを検索	`VectorStore`（FAISS, Chromaなど）
④ 回答生成	検索結果＋質問をLLMに入力	`RetrievalQA` や `Chain`

Streamlitとは

Streamlit（ストリームリット） は、Pythonコードだけで簡単にWebアプリを作成できるフレームワーク です。
データ分析・機械学習・LLMアプリ（例：RAGチャットボット）などのUI構築に広く利用されています。

特徴	説明
簡単な構文	HTMLやJavaScriptを使わず、PythonのみでUIが書ける
即時実行型	コードを保存すると自動でWeb画面が更新される
データ可視化に強い	`matplotlib`、`plotly`、`pandas`などと連携可能
インタラクティブUI	テキスト入力・スライダー・ボタン・チャットUIなどを簡単に実装できる
ローカル or クラウド両対応	`streamlit run app.py` でローカル実行、または共有用にクラウド公開可能

LM Studio サーバの起動

最初のステップとして、モデルを動かすための「APIサーバー」をLM Studioで起動します。
これによって、PythonプログラムがLLMと会話できるようになります。

手順は以下です。

LM Studioを開きます。
左側のメニューから、「開発者」タブを選びます。
画面の上部にあるドロップダウンメニューで、gemma-3 4B モデルを選択し、読み込みます。
（モデルは前回も使用したものです）
「Start Server」ボタンをクリックします。
サーバーが起動します。
ログに以下のようなメッセージが出力されます。
サーバが「http://localhost:1234」で動作していることがわかります。
以下のAPIが確認できます。
（OpenAI互換APIです）

RAGパイプラインの構築

次は、RAG（Retrieval-Augmented Generation） という仕組みを作ります。
これは、LLMが外部の知識（今回はテキストファイル）を参照しながら回答を生成するための技術です。
身近な例で言うと、「教科書を見ながらテスト問題を解く」に似ています。

教科書＝事前に用意するデータ（今回はテキストファイルを用います）
テスト問題＝ユーザーからの質問
問題を解く人＝ LLM

この仕組みを作るために、まずはPythonの環境を整える必要があります。
いくつか専門のライブラリ（便利な道具セットのようなもの）をインストールします。
ターミナル（WindowsならコマンドプロンプトやPowerShell）を開いて、以下のコマンドを実行します。

pip install langchain langchain-community langchain-openai langchain-huggingface streamlit faiss-cpu

RAGの教科書

まず、LLMが読み込む「教科書」（知識ベース）を作成します。（単純なテキストファイルとします）
Python スクリプトを作成する予定のフォルダーと同じフォルダーに、knowledge.txtという名前の新しいテキストファイルを作成します。
教科書データとして、桃太郎に関する次の短編小説をコピーしてテキストファイルに貼り付け、保存します。
このファイルが ローカルナレッジベース になります。

むかしむかし、あるところにおじいさんとおばあさんが住んでいました。
おじいさんは山へ芝刈りに、おばあさんは川へ洗濯に行きました。
おばあさんが川で洗濯をしていると、大きな桃がどんぶらこ、どんぶらこと流れてきました。
おばあさんはその桃を拾い上げて、家に持ち帰りました。
家に帰って桃を割ってみると、中から元気な男の子の赤ちゃんが出てきました。
桃から生まれたので、その子を「桃太郎」と名付けました。
桃太郎はすくすくと育ち、やがて鬼ヶ島へ鬼退治に行くと言い出しました。
おばあさんからきびだんごをもらい、桃太郎は旅に出ます。
旅の途中で、犬、猿、雉を家来にしました。
そして、みんなで力を合わせて鬼を退治し、宝物を持って家に帰りました。

Streamlitアプリを作成する

本体のプログラムを作成します。
先ほど作った knowledge.txt と同じフォルダに、app.py という名前で新しいファイルを作成します。
そして、以下のコードをすべてコピーして、app.py ファイルに貼り付けます。

import streamlit as st
from langchain_openai import ChatOpenAI
from langchain.text_splitter import CharacterTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_community.vectorstores import FAISS
from langchain.chains import RetrievalQA

# =============================
# --- LLMとRAGのセットアップ ---
# =============================

# ドキュメントを読み込んでRAGパイプラインを作成する関数
def create_rag_chain(document_path):
    # ドキュメントを読み込む
    with open(document_path, 'r', encoding='utf-8') as f:
        document_text = f.read()

    # 1. ドキュメントを小さな「チャンク」に分割する
    # これにより、モデルが関連情報を見つけやすくなります。
    text_splitter = CharacterTextSplitter(
        separator="\n",
        chunk_size=200,      # 各チャンクのサイズ（文字数）
        chunk_overlap=50,    # チャンク同士の重なり
        length_function=len
    )
    docs = text_splitter.split_text(document_text)

    # 2. 各チャンクの「埋め込みベクトル」を作成する
    # 埋め込み（Embeddings）は、テキストをコンピュータが意味を理解できる数値のベクトルに変換する技術です。
    # all-MiniLM-L6-v2は、文章をコンピュータが理解できる数値（ベクトル）に変換することに特化した、小型で高速なモデルです。
    embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")

    # 3. ベクトルストア（FAISS）を作成し、埋め込みを保存・検索できるようにする
    # これは、私たちの「教科書」に検索可能な索引を作るようなものです。
    db = FAISS.from_texts(docs, embeddings)

    # 4. ローカルLLMサーバー（LM Studio）への接続を設定する
    llm = ChatOpenAI(
       # ↓↓↓ LM Studioの「API Identifier」をここに貼り付けてください ↓↓↓
        model_name="local-model",            # ローカルモデルを使用するように指定
        base_url="http://localhost:1234/v1", # LM Studioサーバーのアドレス
        api_key="not-needed",                # ローカルサーバーなのでAPIキーは不要
        temperature=0.1                      # temperatureを低く設定して、「参考文章から外れず、最も確実な回答をしなさい」とAIに指示している
    )

    # 5. RetrievalQAチェーンを作成する
    # このチェーンは、検索役（FAISSの索引）とLLMを組み合わせます。
    # 質問をすると、まず最も関連性の高いテキストチャンクを見つけ出し、
    # それを質問と一緒にLLMに渡して、回答を生成させます。
    retriever = db.as_retriever()
    qa_chain = RetrievalQA.from_chain_type(
        llm=llm,
        chain_type="stuff", # "stuff"は、関連するチャンクをすべてプロンプトに「詰め込む」方式
        retriever=retriever,
        return_source_documents=True
    )
    return qa_chain

# knowledge.txtを使ってRAGチェーンを作成
rag_chain = create_rag_chain("knowledge.txt")

# =============================
# --- Streamlit UI ---
# =============================

st.title("🍑 桃太郎チャットボット")
st.write("桃太郎の物語について、質問してください！")

# チャット履歴を初期化する
if "messages" not in st.session_state:
    st.session_state.messages = []

# 履歴にあるメッセージを再表示する
for message in st.session_state.messages:
    with st.chat_message(message["role"]):
        st.markdown(message["content"])

# ユーザーの入力に反応する
if prompt := st.chat_input("質問をどうぞ"):
    # ユーザーのメッセージを表示
    with st.chat_message("user"):
        st.markdown(prompt)
    # ユーザーのメッセージを履歴に追加
    st.session_state.messages.append({"role": "user", "content": prompt})

    # LLMの応答を取得
    response = rag_chain.invoke({"query": prompt})
    answer = response["result"]

    # アシスタントの応答を表示
    with st.chat_message("assistant"):
        st.markdown(answer)
    # アシスタントの応答を履歴に追加
    st.session_state.messages.append({"role": "assistant", "content": answer})

ソースコード中のコメントでプログラムの解説をしていますが、概略を以下にまとめます。

前半：頭脳の準備パート (`create_rag_chain` 関数)

ここは、LLMが 「賢い司書」 になるための準備をする部分です。

本を読む: まず、教科書ファイル「桃太郎の物語」 (knowledge.txt) の内容をすべて読み込みます。
付箋を貼る: 物語を短い文章（チャンク）に区切って、内容ごとにたくさんの付箋を貼っていくようなイメージです。(CharacterTextSplitter)
索引を作る: コンピュータが「どの付箋にどんな内容が書いてあるか」をすぐに見つけられるように、特殊な索引（ベクトルストア）を作ります。(Embeddings, FAISS)
LLMと連携: 最後に、「質問が来たら、まず索引を使って関連する付箋を探し、その内容を参考にして答える」というルール（RetrievalQA）を決め、LM StudioのLLMと連携させます。

この準備によって、LLMはただの物知りではなく、資料（教科書データ）に基づいて回答できる専門家になります。

Information

all-MiniLM-L6-v2はどこから来るのか？
上記のモデルは、初めてプログラムを実行したときに、インターネット上にある 「Hugging Face Hub」 という巨大なAIモデルの保管庫から、自動的にダウンロードされます。
一度ダウンロードされると、PC内の特別なフォルダ（キャッシュと呼ばれます）に保存されます。
2回目以降にプログラムを実行するときは、もう一度ダウンロードするのではなく、PCに保存されたそのファイルから直接読み込まれます。

後半：アプリ画面パート (Streamlit UI)

ここは、ユーザーが実際に触るチャット画面を作る部分です。

画面の表示: 「🍑 桃太郎チャットボット」というタイトルを表示します。
入力欄の用意: ユーザーが質問を入力するためのチャットボックスを用意します。
応答の処理:
- ユーザーが質問を入力すると、その質問を 前半で作った「賢い司書」 に渡します。
- 司書（RAG）が資料を調べて作った回答を受け取ります。
- その回答をチャット画面に表示します。

ざっくり言うと、「前半で資料を読み込んで賢くなったAIを用意し、後半でそのAIと会話するためのチャット画面を作る」 という2段構成になっています。

アプリケーションを実行

アプリケーション（チャットボット）を起動します。

LM Studioのサーバーが起動していることを確認します。
app.py と knowledge.txt を保存したフォルダを、ターミナル（コマンドプロンプト）で開きます。
ターミナルで、以下のコマンドを入力して実行します。

streamlit run app.py

上記コマンドを実行すると、自動的にWebブラウザで新しいタブが開きます。
（デフォルトでは「 http://localhost:8501/ 」でアプリケーションが起動しています）

ブラウザの右上にRAGを用意していることを示す進捗が数秒間表示されます。

少しの時間の後「🍑 桃太郎チャットボット」の画面が表示されるはずです。

質問をする

チャットボットに質問をしてみます。
質問は以下です。

「桃太郎とは何者ですか？」
「桃太郎は何をしましたか？」

教科書データに載っている内容を回答していることがわかります。

教科書データの内容を一部変えてみる

教科書データの内容を一部変えてみます。

以下の

旅の途中で、犬、猿、雉を家来にしました。

の部分を

旅の途中で、猫、亀、鶴を家来にしました。

に変えて実行してみましょう。
結果は以下のようになりました。

正しく家来が入れ替わって解釈されていることがわかります。

教科書データに無いことを聞いてみる

教科書データに無いことを聞いてみます。
AIが勝手に物語を拡張していないことを確認します。

用意した教科書データ以外の内容については答えられないことがわかります。

参考にした元の文章の表示

回答と一緒に「参考にした元の文章」も表示するように機能を追加します。

ソースコードの以下の部分

    with st.chat_message("assistant"):
        st.markdown(answer)

に機能を追加します。
変更後のソースコードは以下です。

   with st.chat_message("assistant"):
        st.markdown(answer)
        
        # --- ここから追加 ---
        with st.expander("参考にした文章"):
            for doc in response["source_documents"]:
                st.markdown(f"--- \n {doc.page_content}")
        # --- ここまで追加 ---

アプリケーションを実行すると、以下のように参考にした文章も一緒に表示されるようになりました。

まとめ

今回紹介した手順では、LM Studio × LangChain × Streamlit を組み合わせることで、クラウドに依存しないローカルRAG環境を構築しました。

ポイントを振り返ると次の通りです。

LM Studio でローカルLLMをOpenAI互換APIとして動作
LangChain で文書を分割・ベクトル化・検索・回答生成を自動化
Streamlit で対話的なUIを構築し、ブラウザから手軽に利用可能
教科書データを変更すると、AIの回答内容も動的に変化

この仕組みにより、「自分の持つ知識ファイル」をAIが読み込み、AIが “自分専用の知識アシスタント” のように振る舞います。
より複雑なナレッジや複数ファイル対応、さらには検索精度向上やUI改善などに発展させることもできます。

自分のデータを自分の環境で活かす、新しいAI活用の形を試すことができました。

項目	説明
`サブドメイン`	(任意) `ssh`
`ドメイン`	取得済みの独自ドメイン
`タイプ`	`SSH`
`URL`	`localhost:22`

項目	説明
`サービストークン名`	サービストークンの名前
`サービストークンの有効期間`	任意の選択肢

項目	説明
`アプリケーション名`	任意の名前
`セッション時間`	任意の選択肢
`サブドメイン`	(任意) `ssh`
`ドメイン`	取得済みの独自ドメイン

豆蔵デベロッパーサイト

親心VSこども Wi-Fi大作戦！Raspberry Pi＆Pi-holeで徹底ペアレンタルコントロールしてみた

はじめに

我が家のネットワーク事情と事の発端

イタチごっこの始まり

今回行った根本的な対策（ガチ構成）

今後の展望と親の葛藤

おわりに

豆蔵デベロッパーサイト 2026年1-3月のサマリー

記事数・執筆者数

連載

SysML モデリング連載

スクラムマスターのAI活用

テーマ別の記事

フロントエンド

ロボット

AI エージェント

認定資格

AWS

個人開発

さいごに

要件定義入門①：要件定義とはなにか ～現場での役割と全体像～

要件定義入門①：要件定義とは何か ～現場での役割と全体像～

1. はじめに

2. 要件定義とは何か

なぜ要件定義が必要なのか

要件定義でやっていること

3. 設計とはどう違うのか

具体例

4. 基本的な流れ

5. 具体例

■ 要望（やりたいこと）

■ 要求（具体化されたニーズ）

■ 整理・検討（要求の整理・実現可能性の確認）

■ 提案（実現案の提示）

■ 検討（顧客側確認）

■ 合意（要件確定）

6. まとめ

最先端ロボ×AIで遊ぼう！LeRobotとSO-101でマルチモーダルAIを体験＆環境構築ガイド

こんなひとにおすすめ

はじめに

用語の説明

マルチモーダルAI とは

LeRobot とは

SO-101 とは

動作環境

環境構築方法

LeRobot の環境構築方法

0. 【任意】conda 系のパッケージがインストールされていない場合

1. 仮想環境構築

2. LeRobot をインストールする

SO-101 の環境構築

1. SO-101 の印刷（もしくは購入）

2. SO-101 のセットアップ

2.1. モーターの仕分け

2.2. MotorBus（モーターバス）のセットアップ

2.3. モーターとモーターバスを連動させる

2.4. ロボットアームの組み立て

3. 動作確認

最後に

AWS QuickSightのCI/CD環境構築：第1章 ダッシュボードの自動バックアップ（Git管理）

はじめに

第1章：自動アップロード環境の構築

1. 全体の流れ

2. 実装手順

Step 1: GitHub認証情報のAWS Secrets Managerへの登録

Step 2: 実行スクリプトの配置

Step 3: IAMロールとCodeBuildプロジェクトの作成

Step 4: EventBridgeルールの設定

3. Tips: 構築時におけるQuickSight APIの技術的制約と解決策

事象: APIにおけるローカルファイルデータセットの非互換性

第2章・第3章に向けて

参考資料

🤖ABBロボットコントローラにPC-SDKで連携するときの落とし穴10選🕳️

PC-SDKとは

落とし穴 ティア表

🕳️1. Web上の情報が少ない B

🕳️2. AIが頻繁にハルシネーションを起こす B

🕳️3. ロボットコントローラが見つからないことがある A

🕳️4. 制御権の獲得し忘れ C

要件定義入門①：要件定義とはなにか　～現場での役割と全体像～

要件定義入門①：要件定義とは何か　～現場での役割と全体像～

AWS QuickSightのCI/CD環境構築：第1章ダッシュボードの自動バックアップ（Git管理）

落とし穴ティア表

同じような役割を持つ仕組みを持つ`npm link` / `npm pack` との違い

コミット前に`yalc check`で混入防止

なぜ`1.2.792.0`で改善したのか