QUARTETCOM TECH BLOG

JavaScript の Temporal 入門 | QUARTETCOM TECH BLOG

Mon, 03 Aug 2026 00:00:00 +0900

JavaScript の新しい日付時刻 API の Temporal を知っていますか？

記事執筆時点（2026/08）でのステータスは、プロポーザルが「Stage4」、Baseline が「Limited availability」となっています。MDN でも実験的な機能と紹介されており実用段階ではありませんが Google Chrome v144 や Node.js v26 で標準搭載されるなどランタイム環境のサポートは広がりつつあります。Safari で実装されればこの勢いはさらに加速するかもしれません。

とはいえ Temporal のインターフェイスはシンプルで直感的とは思えず、お試しコードを書くところからつまづいてしまいました。リファレンスを見ながら考え込んでしまった自分に「最初はこういうコードから試してみるといいよ！」と説明するつもりで入門記事を書いてみます。

1章）概要を知る

Temporal 名前空間

Temporal 名前空間にはいくつかのクラスがあります。
これらは、日付、時刻、日付時刻など用途に応じて呼び分けます。

クラス	用途	値の例
`Temporal.PlainDate`	日付	`2026-08-01`
`Temporal.PlainTime`	時刻	`10:00:00`
`Temporal.PlainDateTime`	日付時刻	`2026-08-01T09:00:00`
`Temporal.PlainMonthDay`	月日	`08-01`
`Temporal.ZonedDateTime`	日付時刻（タイムゾーン付き）	`2026-08-01T09:00:00[Asia/Tokyo]`
`Temporal.Instant`	日付時刻（ナノ秒精度）	`1785542400000000000n`
`Temporal.Duration`	日付時刻（差分）	`P3D`

はじめに PlainDateTime ZonedDateTime を使ったコードを見てみましょう。どちらも日付時刻を扱うクラスで、タイムゾーンありなしの違いがあります。

文字列またはオブジェクトを渡し、インスタンスを生成します。

const t1 = Temporal.PlainDateTime.from('2026-08-01T09:00:00');
const t2 = Temporal.ZonedDateTime.from('2026-08-01T09:00:00[Asia/Tokyo]');

const t1 = Temporal.PlainDateTime.from({
  year: 2026, month: 8, day: 1, hour: 9, minute: 0, second: 0,
});

const t2 = Temporal.ZonedDateTime.from({
  timeZone: 'Asia/Tokyo',
  year: 2026, month: 8, day: 1, hour: 9, minute: 0, second: 0,
});

文字列またはプロパティで値を取り出します。

t1.toString(); // 2026-08-01T09:00:00
t2.toString(); // 2026-08-01T09:00:00+09:00[Asia/Tokyo]

t1.year; // 2026
t1.month; // 8
t1.day; // 1
t1.hour; // 9
t1.minute; // 0
t1.second; // 0

t2.timeZoneId; // Asia/Tokyo
t2.year; // 2026
t2.month; // 8
t2.day; // 1
t2.hour; // 9
t2.minute; // 0
t2.second; // 0

Temporal の文字列表現

Temporal の入出力は RFC 3339 をベースとした文字列を扱います。

08-01
2026-08-01
2026-08-01T09:00:00+09:00

タイムゾーンを持つ場合、その情報が追加されます。

2026-08-01T09:00:00+09:00[Asia/Tokyo]

暦を指定した場合、カレンダー注釈が追加されます。

2026-08-01T09:00:00+09:00[Asia/Tokyo][u-ca=japanese]

from() は文字列表現を入力で受け取ります。

const t1 = Temporal.PlainDateTime.from('2026-08-01T09:00:00');
const t2 = Temporal.ZonedDateTime.from('2026-08-01T09:00:00+09:00[Asia/Tokyo]');
const t3 = Temporal.ZonedDateTime.from('2026-08-01T09:00:00+09:00[Asia/Tokyo][u-ca=japanese]');

toString() は文字列表現を出力します。

t1.toString(); // 2026-08-01T09:00:00
t2.toString(); // 2026-08-01T09:00:00+09:00[Asia/Tokyo]
t3.toString(); // 2026-08-01T09:00:00+09:00[Asia/Tokyo][u-ca=japanese]

ECMAScript 拡張の ISO-8601 と RFC 3339
https://tc39.es/proposal-temporal/docs/ja/iso-string-ext.html

暦

Temporal では ISO8601 以外の暦も扱うことができます。
いろいろに変化させられるのがおもしろいですね。

const t = Temporal.ZonedDateTime.from('2026-08-01T09:00:00[Asia/Tokyo]');

t.withCalendar('iso8601');
// 西暦 2026年8月1日
// {
//   era: undefined, eraYear: undefined,
//   year: 2026, month: 8, day: 1,
// }

t.withCalendar('japanese');
// 日本の暦 令和8年8月
// {
//   era: 'reiwa', eraYear: 8,
//   year: 2026, month: 8, day: 1,
// }

t.withCalendar('hebrew');
// ヘブライ歴 5786年11月
// {
//   era: undefined, eraYear: undefined,
//   year: 5786, month: 11, day: 18,
// }

現在時刻

Temporal.Now を使って現在時刻を取り出します。
Now は Temporal 名前空間のクラスではなくユーティリティオブジェクトです。

このオブジェクトは他のクラスへの変換メソッドを持っています。

const t1 = Temporal.Now.plainDateTimeISO(); // to PlainDateTime
const t2 = Temporal.Now.zonedDateTimeISO(); // to ZonedDateTime

ISO というサフィックスの通り、デフォルトで ISO8601 の暦が適用されます。

t1.calendarId; // iso8601
t2.calendarId; // iso8601

クラスに変換した後は文字列またはプロパティで値を取り出せます。

t1.toString();

t1.timeZoneId;
t1.year;
t1.month;
t1.day;
t1.hour;
t1.minute;
t1.second;

日付時刻の構成要素を表すクラス

カレンダーや時計の「2026年8月1日」「9時0分」は、見ている人それぞれのエリアでの時間を表すものです。Temporal のドキュメントでは壁時計時間（wall-clock time）と説明されています。新しい年が始まる「1月1日0時0分」のラベリングは世界共通ですが祝うタイミングは違いますよね。このように、タイミングよりも年月日が意味を持つケースがあります。

Temporal には「年月日時分秒」といった日付時刻の構成要素を扱う専用クラスが存在します。これらはタイムゾーンを持たない素の値として Plain プレフィクスが付いています。

クラス	表す値	例
`Temporal.PlainDate`	年月日	`2026-08-01`
`Temporal.PlainTime`	時分秒	`10:00:00`
`Temporal.PlainDateTime`	年月日時分秒	`2026-08-01T09:00:00`
`Temporal.PlainMonthDay`	月日	`08-01`

Plain プレフィクスのクラスは目的に沿った値だけを扱います。

const t = Temporal.PlainDate.from('2026-08-01');

t.toString(); // '2026-08-01'
t.year; // 2026
t.month; // 8
t.day; // 1

const t = Temporal.PlainTime.from('09:01:02');

t.toString(); // '09:01:02'
t.hour; // 9
t.minute; // 1
t.second; // 2

const t = Temporal.PlainDateTime.from('2026-08-01T09:01:02');

t.toString(); // '2026-08-01T09:01:02'
t.year; // 2026
t.month; // 8
t.day; // 1
t.hour; // 9
t.minute; // 1
t.second; // 2

const t = Temporal.PlainMonthDay.from('08-01');

t.toString(); // '08-01'
t.month; // 8
t.day; // 1

Plain プレフィクスのクラスにタイムゾーンを与えると ZonedDateTime に変換できます。

// TZ=Africa/Abidjan として Node.js を実行
const t = Temporal.PlainDate.from('2026-08-01');

// 2026-08-01T00:00:00+00:00[Africa/Abidjan]
t.toZonedDateTime(Temporal.Now.timeZoneId()).toString();

// 日本のタイムゾーンに変換（UTC との時差 9 時間）
// 2026-08-01T00:00:00+09:00[Asia/Tokyo]
t.toZonedDateTime('Asia/Tokyo').toString(); 

// イギリスのタイムゾーンに変換（8 月はサマータイムで UTC との時差 1 時間）
// 2026-08-01T00:00:00+01:00[Europe/London]
t.toZonedDateTime('Europe/London').toString();

特定の瞬間を表すクラス

人類がはじめて月面に降り立ったのは 1969年7月21日2時56分15秒（UTC）です。その様子は世界中でリアルタイム中継され人類史上の価値ある瞬間となりました。このような場合は時分秒よりも、時間軸上のプロットである世界共通の「瞬間」に価値が置かれます。Temporal のドキュメントではカレンダーや場所によらない特定の時点での時刻（exact time）と説明されています。

Temporal には瞬間を表現するクラスが存在します。

クラス	表す値	例
`Temporal.ZonedDateTime`	瞬間タイムゾーンによる解釈	`2026-08-01T09:00:00+0900[Asia/Tokyo]`
`Temporal.Instant`	瞬間ナノ秒精度	`1785542400000000000n`

// 月面に降り立った瞬間
const t = Temporal.ZonedDateTime.from('1969-07-21T02:56:15Z[UTC]');

// コートジボワールの都市アビジャン: 深夜 2 時
// 1969-07-21T02:56:15+00:00[Africa/Abidjan]
t.withTimeZone('Africa/Abidjan').toString();

// アームストロング船長の故郷オハイオ州: 夜 10 時
// 1969-07-20T22:56:15-04:00[America/New_York]
t.withTimeZone('America/New_York').toString();

// 東京: 昼 11 時
// 1969-07-21T11:56:15+09:00[Asia/Tokyo]
t.withTimeZone('Asia/Tokyo').toString();

瞬間を表現する ZonedDateTime Now は Instant を取り出すメソッドを持っています。Instant は時間軸上のゼロ地点（エポックタイム）からの相対位置を示すプロパティを提供します。

const t1 = Temporal.Now.instant();
t1.epochMilliseconds; // ミリ秒: 1785542400000
t1.epochNanoseconds; // ナノ秒: 1785542400000000000n

const t2 = Temporal.ZonedDateTime.from(...).toInstant();
t2.epochMilliseconds;
t2.epochNanoseconds;

const t3 = Temporal.PlainDateTime.from(...).toInstant();
// ERROR: PlainDateTime は瞬間を表現しないため Instant に変換できない

📖 目次に戻る

2章） Temporal の日付時刻演算を知る

比較

equals() で日付時刻が等しいかどうか判定できます。

const t1 = Temporal.PlainDateTime.from('2026-05-01T09:00:00');
const t2 = Temporal.PlainDateTime.from('2026-05-01T09:00:00');
t1.equals(t2); // true

const t1 = Temporal.ZonedDateTime.from('2026-05-01T00:00:00[Africa/Abidjan]');
const t2 = Temporal.ZonedDateTime.from('2026-05-01T09:00:00[Asia/Tokyo]');
t1.equals(t2); // true

compare() で大小の関係を数値化できます。

// Temporal.<クラス名>.compare(t1, t2);
// [-1] t2 が大きい
// [0] t1 と t2 が等しい
// [1] t1 が大きい

クラス名は比較対象のスコープを限定するため、日付のみ比較、日付時刻で比較、といった呼び分けができます。

const t1 = Temporal.PlainDateTime.from('2026-08-01T09:01:01');
const t2 = Temporal.PlainDateTime.from('2026-08-01T10:02:02');

// PlainDate: 日付で比較すると t1,t2 は等しい
Temporal.PlainDate.compare(t1, t2); // 0

// PlainDateTime: 日付時刻で比較すると t2 が大きい
Temporal.PlainDateTime.compare(t1, t2); // -1

compare を応用すると日付時刻のソートができます。

const dates = [
  Temporal.PlainDateTime.from('2026-08-01T13:15:00'),
  Temporal.PlainDateTime.from('1995-08-01T23:00:00'),
  Temporal.PlainDateTime.from('2026-08-01T09:30:00'),
].sort(Temporal.PlainDateTime.compare);

dates.map(d => d.toString());
// [
//   '1995-08-01T23:00:00',
//   '2026-08-01T09:30:00',
//   '2026-08-01T13:15:00'
// ]

差分

日付時刻の差分は専用クラスの Duration が担います。

クラス	表す値	値の例
`Temporal.Duration`	日付時刻（差分）	`P3D`

Duration は since() until() の結果として得られます。
文字列またはプロパティで値を取り出します。

const past = Temporal.PlainDateTime.from('2026-08-01T00:00:00');
const future = Temporal.PlainDateTime.from('2026-08-02T10:45:00');

// since: 過去にさかのぼった差分
const d1 = future.since(past);

d1.toString(); // P1DT10H45M
d1.days; // 1
d1.hours; // 10
d1.minutes; // 45
d1.seconds; // 0

// until: 未来に到達するまでの差分
const d2 = past.until(future);

d2.toString(); // P1DT10H45M
d2.days; // 1
d2.hours; // 10
d2.minutes; // 45
d2.seconds; // 0

加算

N 日後、N 時間後、といった加算には add() を使用します。

const t = Temporal.PlainDateTime.from('2026-08-01T09:00:00');

// 1 ヶ月後 / 2026-09-01T09:00:00
t.add({ months: 1 }).toString();

// 30 日後 / 2026-08-31T09:00:00
t.add({ days: 30 }).toString();

// 5 時間後 / 2026-08-01T14:00:00
t.add({ hours: 5 }).toString();

減算

N 日前、N 時間前、といった減算には subtract() を使用します。

const t = Temporal.PlainDateTime.from('2026-08-01T09:00:00');

// 1 ヶ月前 / 2026-07-01T09:00:00
t.subtract({ months: 1 }).toString();

// 30 日前 / 2026-07-02T09:00:00
t.subtract({ days: 30 }).toString();

// 5 時間前 / 2026-08-01T04:00:00
t.subtract({ hours: 5 }).toString();

更新

年月日時分秒の置き換えには with() を使用します。

const t = Temporal.PlainDateTime.from('2026-08-01T00:00:00');

// 日付を更新 / 2026-09-02T00:00:00
t.with({ year: 2026, month: 9, day: 2 }).toString();

// 時刻を更新 / 2026-08-01T12:13:14
t.with({ hour: 12, minute: 13, second: 14 }).toString();

時間の丸め

round() を使うと時間の丸め処理ができます。ビルトインでできる計算の幅が広がりましたね。

const t = Temporal.PlainTime.from('18:42:15');

// trunc（0 方向に切り捨て） / 18:30:00
t.round({
  smallestUnit: 'minutes',
  roundingMode: 'trunc',
  roundingIncrement: 30,
}).toString();

// expand（0 から外側に切り上げ） / 19:00:00
t.round({
  smallestUnit: 'minutes',
  roundingMode: 'expand',
  roundingIncrement: 30,
}).toString();

// halfCeil（四捨五入） / 18:30:00
t.round({
  smallestUnit: 'minutes',
  roundingMode: 'halfCeil',
  roundingIncrement: 30,
}).toString();

オプションの説明 - duration.round
https://tc39.es/proposal-temporal/docs/ja/duration.html#round

Temporal お試し環境

この記事で紹介したコードは Node.js v26 で実行可能です。
暦指定など一部でエラーが出た場合は https://github.com/tc39/proposal-temporal の @js-temporal/polyfill をお試しください。

すでに実装が始まっている Google Chrome でも、デベロッパーツールで Temporal とタイピングすればいろいろ遊んでみることができます。

📖 目次に戻る

所感〜関心の分離のトレードオフ〜

Temporal では既存の Date オブジェクトの課題解決にあたり、日付時刻の扱いについて根本から見直しが入りました。

名前空間には 7 つのクラスが並び、それぞれが概念を取り扱う専用道具として機能します。その道具のひとつを取り出せば、適度に抽象化され理路整然と並んだメソッドで日付時刻の演算ができます。このようなインターフェイスに、私たちが日常的に心がけている「関心の分離」を思い起こしました。

現実世界にあてはめてみると、包丁棚に出刃包丁、菜切り包丁、中華包丁、柳刃包丁…とズラリと並んだような状態でしょうか。玄人向けの調理器具ですね。リアルな体験としてじゃがいもを調理しようと思った時、菜切り包丁では芽がくりぬけず、出刃包丁では皮がむけず、なんか違うと思いながら刺身用のめちゃ長い柳刃包丁を使ったことがあります。結局のところ欲しかったのはプロ並の切れ味はなくとも使いやすい万能包丁でした。

包丁と Temporal はまったく違うものですが利用者としての体験は似ています。たくさんの専用道具を提示されると、どれを使えば良いのか分からず、最初に手にしたものが正解なのか分からず、迷いながら使いつづけます。日付時刻を扱うシーンは往々にして、関数の中だけの狭いスコープの演算と、フロントエンド外のレイヤーとのやり取りでタイムゾーンの解釈に気を配るくらいです。選択の余地がない Date オブジェクトのほうが手に取りやすい万能包丁に似ています。

Temporal は関心や責務という意味において「シンプル」です。しかしながら身近でなじみがある「イージー」ではありません。値をナノ秒単位で扱うことができ、世界各国のタイムゾーンや暦に変換できる機能性の高さを実現しながら（おそらく世界中のフロントエンドエンジニア待望の）柔軟な文字列フォーマッターが提供されなかったことも、イージーを感じさせない要因です。

Simple Made Easy | Rich Hickey
シンプルさとは使いやすいことだと思っているのならそれは間違っています。
これらは全くもって違うものです。Easy と Simple は違います。

私たちの開発体験でもシンプルを重要視する場面は数多くあります。ポリモーフィズムを適用したクラスの分離や、レイヤードアーキテクチャによる構造の分離、マイクロサービス化など、さまざまな粒度でシンプルを追求します。シンプルは保守の観点で大きなメリットをもたらしつつも、利用者の前に専用道具をずらりと並べて理解を強制します。手作業の更新を補助する開発者用コマンド、ファサードクラスの導入など、イージーの提供がないと後のメンテナーには辛いものになるかもしれません。

Temporal も然り、どうにかイージーに寄せる方法としてラッパーなど作ると思考実験としておもしろそうですね。設計やコードリーディングの学びの機会にもなりそうです。

/**
 * こういうインターフェイスはどうだろう
 * TemporalHarness() - now
 * TemporalHarness(new Date()) - legacy date
 * TemporalHarness('2026-08-01T00:00:00[Asia/Tokyo]') - RFC 9559
 * TemporalHarness('2026年08月01日', 'yyyy年MM月dd日') - string parser
 */
const th = new TemporalHarness('2026-08-01')
  .withTimeZone('Asia/Tokyo')
  .withTime('09:00:00')
  .addDays(3)
;

th.format('MM/dd hh:mm'); // 08/04 09:00
th.month; // 8
th.milliSeconds; // 123456789...
th.toLegacyDate(); // Date {}
th.toDuration(new TemporalHarness()); // { days:-11,minutes:-12,seconds:-13... }

読者のみなさんは Temporal をどのように受け止めましたか？

この記事が Temporal にこれから入門するどなたかの参考になれば幸いです。

ベストプラクティスは誰のためのものか - AWS Copilot CLIからAWS CDKに移行を終えて | QUARTETCOM TECH BLOG

Fri, 19 Jun 2026 00:00:00 +0900

はじめに

AWS Copilot CLIは、インフラ構成について深く考えずに済む、非常に強力なツールでした。

先日公開された社内ブログ記事（宣言的記述とメンタルモデル ─ AWS Copilot CLI のサポート終了に寄せて）でも触れられていましたが、Copilotの最大の価値は「何がベストプラクティスかという判断を肩代わりしてくれる」ことにありました。社内で広く使われていたのもこの明確な恩恵があったからです。

今回のAWS CDKへの移行の直接のきっかけは、全社的に利用していたこのCopilotがサポート終了を迎えることになったためです。

ただ、運用する中ですでにツールとのミスマッチを感じ始めていました。Copilotの想定から外れた要件が出るたびに追加のCloudFormation（Addon）で対応する必要があり、かえって構成が複雑化する場面が出てきていたのです。

CDKへの移行は、サポート終了という避けられないイベントを機に、「今の自分たちの要件に合わせて、インフラ設計の主導権を握ろう」と前向きに舵を切った結果です。

本記事では、Copilotの「判断の肩代わり」がもたらした具体的な運用課題と、CDKへの移行によって私たちのインフラ管理がどう変わったのかを振り返ります。

1. 「判断の肩代わり」がもたらした運用上の課題

Copilotのmanifestでは、例えば type: Load Balanced Web Service のような特定の型を指定するだけで、VPC・ALB・ECS・Auto Scalingなどをまとめて定義できました。人間のメンタルモデルに近い抽象度で簡潔に記述できることこそ、Copilot最大の強みでした。

ただ、この「まとめて定義できる」ことの裏を返せば、「細かい部分はすべてCopilotが決定している」ということです。実際に私たちが運用していく中で、壁となったのは以下のような点でした。

1.1. 構成の制約と、記述パラダイムの断片化

Copilotの用意する「型」は強力ですが、そこから一歩踏み込んで独自の最適化を行おうとした途端に、記述が複雑化するもどかしさがありました。

manifestの標準機能では表現しきれないセキュリティグループの詳細設定やRoute53のドメイン設定などを「Addon（CloudFormation）」として別途記述して組み合わせる必要がありました。

このmanifestとCloudFormationという2つの異なる記述パラダイムを行き来するスイッチングコストやコードの断片化は、運用規模が広がるにつれて小さくないストレスになっていきました。

1.2. 抽象化の裏にある挙動の把握

Copilotの高い抽象度は、manifestの設定変更が裏側でどのAWSリソースにどう影響するかをドキュメントから事前に読み取りにくくするという側面を持っています。「この一行を変えたら何が変わるのか」をCopilotのドキュメントから把握しようとしても、manifest設定とCloudFormation出力の対応は網羅的に説明されていません。結局はGitHub Issueを調べたり、実際にデプロイしてコンソールで確認する、というトライ＆エラーのサイクルに頼るしかありませんでした。

最終的にCloudFormationのdiffで変更内容を確認するのが正しいアプローチでその点ではCDKも同じです。ただ、CDKはドキュメントが充実しており、設定の意味や出力を事前に把握できる場面がほとんどです。特にL1コンストラクトはTypeScriptとCloudFormationリソースの対応が直接的なため、デプロイ前から変更結果を予測しやすく、トライ＆エラーのサイクルが大きく減りました。

1.3. アプリとインフラの密結合（インフラリポジトリの独立）

現在の関わっているシステムでは、バックエンドはECSで、フロントエンドはS3+CloudFrontで独立してデプロイする構成を採用しています。これはAWSが公式のPrescriptive Guidanceでも推奨しているSPAのデプロイパターンです。フロントエンドとバックエンドをデプロイ単位として分離することで、それぞれのリリースサイクルを独立させ、互いの変更に影響されずにデプロイできます。

このアーキテクチャでは、インフラの管理対象がバックエンド（ECS）とフロントエンド（S3+CloudFront）の両方にまたがります。そのため、アプリのコードとは完全に切り離されたインフラ専用リポジトリで一元管理したいという要件が自然に生まれました。

AWS Copilotは、copilot/ ディレクトリをアプリケーションリポジトリ内に配置し、アプリと同居させて管理することが基本の設計思想です。 copilot/ をどのリポジトリに置くかはチームが選択できますが、どこに置いたとしても「インフラ定義がいずれかのアプリリポジトリ内に存在する」という状態は避けられません。私たちが目指していた「すべてのアプリリポジトリから独立したインフラ専用リポジトリ」という構成は、Copilotの設計思想の外にありました。

2. AWS CDKに移行して変わったこと

CDKへの移行によって、記述のパラダイムが統一され、インフラ管理の見通しが大きく改善されました。具体的には、以下の4つの変化が挙げられます。

自由な構成への再設計 — CDKには「L1〜L3コンストラクト」という抽象度の異なる概念があり、これらを単一のコード内で自由に組み合わせられます。特に効いたのが、L3コンストラクトである QueueProcessingFargateService の導入です。SQSのメッセージ量に応じたオートスケーリングを含むワーカーの構成全体を、数行のコードで表現できるようになりました。
プログラミング言語を活かしたインフラ記述 — CDKはTypeScriptをはじめ複数の言語をサポートしています。私たちはTypeScriptを選択しましたが、ifやループといった制御構文が使えることに加え、AWSリソースの生成ロジックそのものをTypeScriptの型システムで保護できることが大きな利点です。IDEの補完はCloudFormationのスキーマ定義でも一定程度得られますが、CDK+TypeScriptではリソースを生成するコードそのものが型安全になるため、複雑な構成も見通しよく管理できるようになりました。
コードでの完全な完結 — Copilotでmanifestの表現力を超えるような設定が必要になると、CloudFormation（Addon）という別のパラダイムへの切り替えが発生し、その学習や記述のコストがかかっていました。CDKではL1コンストラクトを使えばCloudFormationと同等の表現力をCDKのコードのまま扱えるため、パラダイムを切り替えることなく、ほぼあらゆる設定を同じコードベース内で完結できます。
インフラリポジトリの独立 — マルチリポジトリの運用に合わせて、インフラを専用の独立したリポジトリへ完全に分離し、一元管理できるようになりました。これにより、アプリケーションコードに一切ノイズを混ぜることなく、アプリとインフラのライフサイクルをきれいに分離できました。

4つの変化に共通するのは、インフラの設計判断を「Copilotが想定する正解」ではなく「自分たちの要件」を起点に考えられるようになったことです。制約に沿った設計から、意図を直接コードに落とす設計へ——この転換が、日々の運用感覚を大きく変えました。

3. ベストプラクティスは誰のためのものか

冒頭で紹介した社内記事にもあるように、Copilotの高い抽象度は「AWSを深く知らなくてもベストプラクティスな構成で動かせる」という素晴らしい価値を生み出していました。

しかしこの移行を通じて改めて感じたのは、「AWSとしてのベストプラクティス（＝Copilotのデフォルト）」が、必ずしも「私たちにとってのベストプラクティス」とは限らないということです。

私たちには私たちの要件があり、コスト感があり、技術スタックがあります。今回の移行でも、「どのリソースをどの粒度で管理するか」「ワーカーをどうスケールさせるか」といった問いをチームで議論し、Copilotのデフォルトとは異なる選択をした箇所が複数ありました。インフラをアプリと完全に分離したリポジトリで管理したいという方針も、バックエンドとフロントエンドを独立したデプロイ単位として扱いたいという設計も、Copilotが想定する標準的な「正解」の外側にあったのです。

「判断の肩代わり」は、「自分たちの要件に合わせた判断をする余地が狭まる」ということでもあります。AWSの知識を設計にしっかり活かしながら、インフラを自分たちでコントロールしていきたいチームには、間違いなくCDKがフィットするはずです。

4. おわりに

Copilotのサポート終了は、単なるツールの移行作業ではなく、「何をツールに任せ、何を自分たちで判断するか」を根本から問い直す貴重なきっかけになりました。

Copilotが肩代わりしてくれていたインフラ設計の判断を、改めて自分たちで一つひとつ引き受けてみると、そこには、これまで諦めていた設計の選択肢が普通に取れる余地が広がっていました。

万人に共通する「完璧なベストプラクティス」はありません。プロダクトの成長やチームの状況によって、正解は変わり続けます。その時々の要件ときちんと向き合って、自分たちに合った選択をしていく——そういう姿勢が、長い目で見たシステムの健全性につながるのではないかと考えています。

今回のCDK移行を通して得た最大の収穫は、新しいインフラ構成そのもの以上に、「自分たちのベストプラクティスは自分たちで選べる」という確かな感覚です。

ツールやフレームワークの選択においても、同じことが言えるはずです。もし今、「世間的なベストプラクティス」と「自分たちの要件」の間に窮屈さを感じているなら、一度立ち止まって「これは誰のためのベストプラクティスなのか」を問い直してみてはいかがでしょうか。

サーバーサイド計測が必要になった背景 | QUARTETCOM TECH BLOG

Mon, 08 Jun 2026 00:00:00 +0900

はじめに

計測プラットフォーマーはユーザー計測をサーバーサイドに移行する動きを進めています。
計測ツール提供側（計測プラットフォーマー） / 利用側ともに負担の大きいサーバーサイド計測が求められている背景を整理します。

1. クライアントサイド主体の計測

ユーザー計測ではブラウザに Cookie を保存してユーザーを識別します。Cookie は仕様で別ドメインに自動送信されません。
そのため、従来のユーザー計測では、Cookie に保存したユーザー識別子を計測サーバーへ送る手段としておもに 2 つの方法が使われています。

`<img>` ピクセルによる送信

1 × 1 px の透明画像タグをページに埋め込みブラウザが計測サーバーに画像をリクエストします。計測サーバーはレスポンスの Set-Cookie で Cookie を発行します。代表的な計測サーバーに Google 広告のコンバージョン計測やインプレッション計測する doubleclick.net があります。

具体的なコードは以下のようになります（正確性より分かりやすさを優先したサンプルです）。

<img src="https://ad.doubleclick.net/activity;src=XXXX;type=YYYY" width="1" height="1">

JavaScript による送信

JavaScript が Cookie の値を読み取り、クエリパラメーターに付与して計測サーバーに送信します。代表的な計測サーバーに GA4 （ google-analytics.com ）があります。

擬似的なコードは以下のようになります（正確性より分かりやすさを優先したサンプルです）。

// クライアントで発行した Cookie を document.cookie で取得
const cid = document.cookie['_ga'];

// 取得した Cookie をクエリパラメーターに付与して計測サーバーに送信
send(`https://www.google-analytics.com/g/collect?cid=${cid}&...`);

2. ブラウザのプライバシー制限

Safari は ITP（ Intelligent Tracking Prevention ）を導入し機械学習でクロスサイトトラッキング能力があると判定したドメイン（ classified domain¹ ）のサードパーティ Cookie を段階的に制限しました。

当初 google-analytics.com / doubleclick.net / facebook.com 等が classified domain の対象となりました。その後、分類の有無に関わらず全サードパーティ Cookie をデフォルトでブロックしました。

Firefox も ETP（Enhanced Tracking Protection）で同様にサードパーティ Cookie を全面的にブロックしています。

これにより <img> ピクセルが依存するサードパーティ Cookie の発行・送信は Safari / Firefox で機能しなくなりました。

一方、Chrome の対応は異なります。2020 年（ Chrome 80 ）に SameSite 属性が設定されていない Cookie のデフォルトを Lax に変更しました。これはサードパーティ Cookie の禁止ではなく、明示的な指定がなければ送信しないという変更です。SameSite=None; Secure を指定すれば <img> ピクセルのレスポンスで発行されたサードパーティ Cookie が今も送受信されています（ google-analytics.com や doubleclick.net はこれを行っています）²。

ITP は JavaScript（ document.cookie ）で発行した Cookie の有効期限を最大 7 日に制限しました。前述した GA4 の _ga Cookie はこの制限を受けるため、7 日を超えると再訪ユーザーが新規ユーザーとして誤認されて計測の精度が低下します。

サーバー発行 Cookie は当初この制限を受けませんでしたが、自社サブドメインの DNS レコードで計測サーバーの IP アドレスを隠蔽する CNAME クローキング / IP アドレスクローキングという迂回策も ITP に検知され、サーバー発行 Cookie も 7 日制限の対象となりました。名前だけを自社ドメインに見せかける回避策も ITP に制限されるようになりました。

3. サーバーサイド計測の必要性＆具体例

上述したとおりクライアントサイド主体の計測は段階的に制限されてきました。これらの制限を根本的に回避するには実際に自社ドメインのサーバーがリクエストを受けて Cookie を発行・管理する必要があります。通常自社サブドメイン（例: analytics.example.com）は classified domain に分類されないため ITP の有効期限制限を受けません。

例 Google server-side Tag Manager （ SGTM ）

自社ドメインのサーバーに GTM のタグサーバーを設置しブラウザからのリクエストをいったん自社サーバーが受けてから Google の計測サーバーへ転送する構成です。自社サーバーが Set-Cookie で Cookie を発行するため ITP の有効期限制限を回避できます³。名前だけを自社ドメインにするのではなく実際に自社サーバーでリクエストを処理する点が ITP 対策として機能する核心です。

まとめ

ブラウザのプライバシー強化はクライアントサイド主体の計測（ <img> ピクセルと JavaScript による送信）を段階的に制限してきました。またその迂回策も都度制限されてきました。

Google server-side Tag Manager へのシフトはこの流れへのソリューションといえます。本記事がその背景理解の一助になれば幸いです。

ITP の文脈での classified Domain とは、Safari が機械学習を用いてユーザーを追跡（トラッキング）していると判断したドメインのことです。 ↩
プライバシー重視の流れにある現在においては、サードパーティ Cookie はすべてのブラウザで制限されると考えがちです。実際は Safari / Firefox と異なり Chrome はオプトインを条件に今もサードパーティ Cookie を許容しています。 ↩
サーバーサイドタグ設定の概要 ↩

reCAPTCHA v3の導入効果とスコアのしきい値の設定方法 | QUARTETCOM TECH BLOG

Mon, 01 Jun 2026 00:00:00 +0900

はじめに

弊社の一部SaaSプロダクトではユーザー登録におけるスパム登録数が徐々に増加し、reCAPTCHA v3導入前の3ヶ月間ではユーザー登録の約89%がスパム登録という状況になっていました。
これによりデータを使った分析の精度低下やDBの圧迫などの問題が発生していました。

そのため、対策としてまずは導入コストが低いハニーポットフィールド(ボット検知用のダミー入力欄)の設置を試してみましたが、効果が得られなかったためreCAPTCHA v3の導入に至りました。
これにより劇的な改善が見られたため導入前後での成果をこの記事にまとめます。

本記事ではreCAPTCHA v3の実装方法ではなく、導入前後でのスパム登録数の変化やスコアのしきい値をどのように設定したかといった、効果測定・運用面での学びを共有します。
実装方法については公式ドキュメントをご参照ください。

導入前後の新規ユーザー登録におけるスパム登録率の変化

reCAPTCHA v3の導入前後でスパム登録率がどのように変化したかを登録者数は伏せ、割合(%)で見ていきます。

月別スパム登録率の推移

導入前後3ヶ月のスパム登録率の変化を以下のグラフにしました。
横軸は導入月の何ヶ月前後かを表していて、縦軸はスパム登録率を表しています。

導入前の3ヶ月では、 85.1%, 90.5%, 90.1% と高止まりしておりスパム登録がユーザー登録の約89%という状況でしたが、導入後はスパム登録率は 0% となりその後もスパム登録は確認されていません。
導入後の副次的な効果として、スパム登録を試みるリクエスト数そのものが減少していました。そちらの推移もグラフで見ていきます。

スパム登録リクエスト数の推移

導入前の3ヶ月のスパム登録リクエスト数の平均を100%として各月のスパム登録リクエスト数を相対値でグラフに表しています。

導入前後3ヶ月の合計でスパム登録リクエスト数を相対的に比較すると、導入後は約90%の削減ができました。

スコアのしきい値の設定方法

reCAPTCHA v3では、ユーザーの行動を分析して人間らしさを数値化したスコアと、基準値となるしきい値をもとにスパム登録をブロックするかどうかを判断します。

スコア：0.0~1.0で表し、より人間らしい行動ほどスコアが高くなります。
しきい値：どのスコアまでを受け入れるかの基準になる数値です。

このしきい値をいくつに設定するかによって、 スパム登録をブロックできるか 、正規登録ユーザーを誤ってブロックしてしまうか が変わってくるため以下の順で段階的に設定しました。

1. 公式ドキュメントを参考に初期値を設定

まず公式ドキュメントのスコアしきい値ガイドを参考に初期のしきい値を0.5に設定しました。

設定したしきい値を下回るスコアのリクエストでも、この段階ではブロックせずにSlack通知のみを行いました。

2. Slack通知で初期しきい値を検証

初期値として高いしきい値を設定すると正規ユーザーを誤ってブロックするリスクがあったため、最初の1ヶ月間は通知ベースで以下を確認しました。

Slack通知される(しきい値を下回る)ユーザー登録が実際にスパム登録かどうか
DB内に登録されたユーザーにSlack通知されていないスパム登録があるかどうか

3. しきい値の設定

観測データをもとに以下の2点を確認し、しきい値を設定しました。

スパムと確認されたリクエストが全てしきい値を下回っているか
正規ユーザー登録のスコアがしきい値を上回っているか

両方を満たすしきい値を設定しました。
その結果、正規ユーザーのブロックやスパムユーザーの登録はない状態で現在も維持できています。

まとめ

reCAPTCHA v3の導入によって、約89%だったスパム登録率を0%にまで抑えることができました。
さらに、スパム登録リクエスト数そのものも導入前と比較すると約90%削減という副次的な効果もありました。

今回のreCAPTCHA v3導入で効果測定としきい値の設定の観点で以下が重要だと感じました。

効果測定の観点

リクエスト数の抑止効果の測定もできるように、スパム登録だけでなくリクエスト数も測定する。
ボットの手法の変化に対応するために、導入後も継続的にモニタリングする。

しきい値の設定の観点

安全にしきい値の設定をするために、最初はスパム登録をブロックせずに通知のみで検証をする。
正規ユーザーのブロックやスパムユーザーの登録防止のために、しきい値は公式ドキュメントと検証したスコアを参考に設定する。

スパム登録にお悩みの方々の参考になれば幸いです。

互換性のないオブジェクトを低コストにコンバートする | QUARTETCOM TECH BLOG

Thu, 07 May 2026 00:00:00 +0900

はじめに

弊社では多様な広告媒体を扱います。
その中で 「Aという媒体のオブジェクトを、Bの媒体へ移動したい」ようなケース があります。

素直に考えると、「AオブジェクトをBオブジェクトへ変換する Mapper」を実装すればよさそうです。
しかし、この方法は媒体が増えるほど大きな負債になります。

問題点: 対応する媒体が増えた時にコードが膨れ上がる

対応する媒体が A と B だけであれば、必要な Mapper は以下の2つです。

A → B へコンバートする Mapper
B → A へコンバートする Mapper

現状の実装であれば Mapper は2つで済みます。
しかし、新たに C、D に対応する必要が出てきた場合、状況が変わります。

この場合だと、以下のMapperを実装することになります。

A → B へコンバートする Mapper
A → C へコンバートする Mapper
A → D へコンバートする Mapper
B → A へコンバートする Mapper
B → C へコンバートする Mapper
B → D へコンバートする Mapper
C → A へコンバートする Mapper
C → B へコンバートする Mapper
C → D へコンバートする Mapper
D → A へコンバートする Mapper
D → B へコンバートする Mapper
D → C へコンバートする Mapper

Mapper 数が膨れ上がっていることがわかります。

さらに、「Aオブジェクト」の仕様変更が入った場合も影響範囲も広いです。

まとめると、以下の点で負債になります。

Mapper の数が増え続ける
媒体ごとの差を補完する処理が各 Mapper に散らばる
媒体都合の仕様変更時の影響範囲が広くなる

素直に実装するとコードが膨れ上がりそうです。

解決策: Mapper を抽象オブジェクトに依存させ、汎用的に扱えるようにする

現状の問題は、媒体同士が直接依存しているため、変更の影響が広がる構造になっています。

これを解決するために、独自に定義した抽象オブジェクトを実装します。

抽象オブジェクト本体
Aを抽象へコンバートするMapper
Bを抽象へコンバートするMapper
Cを抽象へコンバートするMapper
Dを抽象へコンバートするMapper
抽象をAへコンバートするMapper
抽象をBへコンバートするMapper
抽象をCへコンバートするMapper
抽象をDへコンバートするMapper

特徴は「全媒体に共通の中間表現(抽象)を持つ」、「具象同士を直接依存させず、抽象を経由してコンバートする」ことです。

図にすると以下です。

数値で比較した場合

以下は具体的な数値に落とし込んだ表です。

ビフォー

媒体数	必要なMapper数	仕様変更時に影響するMapper数
2	2	2
3	6	4
4	12	6
5	20	8

アフター

媒体数	抽象でコンバートした際のMapper数	仕様変更時に影響するMapper数
2	4	2
3	6	2
4	8	2
5	10	2

この設計のメリット & デメリット

メリット

媒体が 3 つを超えるあたりから Mapper 数の優位が逆転し、媒体が増えるほど差が広がる
媒体の仕様変更時の影響を受ける数が少ない
抽象オブジェクトの仕様を読めば、コンバートできるプロパティを把握できる
特定の媒体オブジェクトを抽象オブジェクトに変換さえすれば、他の媒体へコンバートしやすい

デメリット

媒体数が少ない場合「2〜3」の場合は過剰な設計になりやすい
抽象オブジェクトを管理するコストが掛かる
変換先媒体に存在しない項目は扱わない仕様にする必要がある
抽象モデルの設計を誤ると、逆に複雑性が中央に集中する
抽象モデルに存在しない情報は失われる（情報ロスが発生する）

実装例

以下はコンバート例です。ニュアンスが伝わるように最小限の構成にしています。

<?php

declare(strict_types=1);

/**
 * 共通フォーマット
 */
class AbstractAd
{
    public function __construct(
        public readonly string $title,
    ) {
    }
}

/**
 * A 媒体
 */
class AVendorAd
{
    public function __construct(
        public readonly string $headline,
    ) {
    }
}

/**
 * B 媒体
 */
class BVendorAd
{
    public function __construct(
        public readonly string $adTitle,
    ) {
    }
}

/**
 * A → 抽象 Mapper
 */
function aVendorAdToAbstractAd(AVendorAd $ad): AbstractAd
{
    return new AbstractAd(
        title: $ad->headline,
    );
}

/**
 * 抽象 → B Mapper
 */
function abstractAdToBVendorAd(AbstractAd $ad): BVendorAd
{
    return new BVendorAd(
        adTitle: $ad->title,
    );
}

/**
 * A → B へコンバートする例
 */
$aVendorAd = new AVendorAd(
    headline: '春のセール開催中',
); // コンバート対象の A のオブジェクト

$abstractAd = aVendorAdToAbstractAd($aVendorAd); // 一度抽象化する
$bVendorAd = abstractAdToBVendorAd($abstractAd); // 抽象 -> B へ

// 拡張例：抽象化してしまえば、今後増える媒体へコンバートが容易になる
$cVendorAd = abstractAdToCVendorAd($abstractAd); // 抽象 -> C へ
$dVendorAd = abstractAdToDVendorAd($abstractAd); // 抽象 -> D へ

まとめ

「A→B」「B→C」みたいに直接変換するのをやめて、
一度「共通フォーマット」に変換してから別の媒体に変換しよう、という設計でした。

これにより、媒体同士が直接依存しなくなり、変更が他の媒体に波及しにくくなります。

記事を書きながら知りましたが、
この設計は「Canonical Data Model パターン」と言うようです。

正規化したモデルを使ってやりとりしようというデザインパターンのようで、今回の記事とやっていることは大体同じようです。

感想

実際に担当しているプロダクトに、このデザインパターンを導入しました。

導入当初は、「YAGNI ではないか？」と思うこともありました。
しかし、媒体追加や仕様変更が発生した際に、既存コードへの影響を最小限に抑えられる構造を事前に用意しておくことは、長期的に見ると重要だと感じています。

特に、媒体数が増え続けるようなシステムでは、
「今の実装コスト」よりも「将来の変更コスト」を下げる価値の方が大きくなると、数年間、リスティング広告というドメインに触れていると思うことが多いです。

それに、極端な話ですが、広告媒体のモデルとは全く関係なくても、
抽象モデル(正規化したモデル)に変換さえすれば、他媒体のオブジェクトへコンバートできます。

生成 AI との相性が良さそうだと思いませんか？

宣言的記述とメンタルモデル ── AWS Copilot CLI のサポート終了に寄せて | QUARTETCOM TECH BLOG

Fri, 01 May 2026 00:00:00 +0900

きっかけ

2026年3月、AWS は Copilot CLI のサポート終了を発表しました。2026年6月12日をもって、新機能の追加もセキュリティアップデートも止まります。

Announcing the end-of-support for the AWS Copilot CLI | Containers

私が Copilot に見出していた価値は、単純に「便利なツール」ということではありませんでした。それが終わるという知らせを受けて、改めてその価値の正体を言語化してみたくなりました。

宣言的記述と手続き的記述

まず前提となる概念を整理しておきます。

プログラムの記述スタイルは大きく二つに分類できます。宣言的（Declarative）と手続き的（Procedural）です。

同じ「偶数だけ取り出して2倍にする」処理を TypeScript で書き比べてみます。

手続き的

const result = [];
for (let i = 0; i < numbers.length; i++) {
  if (numbers[i] % 2 === 0) {
    result.push(numbers[i] * 2);
  }
}

宣言的

const result = numbers
  .filter(n => n % 2 === 0)
  .map(n => n * 2);

手続き的な記述は「インデックスを進めて、条件を確認して、配列に追加して」という手順を書きます。宣言的な記述は「偶数を選んで、2倍にする」という意図を書きます。

ただし、これは二値ではなくグラデーションだという点に注意が必要です。filter().map() にも順序はあります。「完全に宣言的」というのはほぼ理想概念であり、現実のコードはどこかにグラデーションとして位置しています。本質的な違いは「順序があるかどうか」ではなく、「制御フローを自分で記述しているかどうか」にあると考えています。

また、宣言的記述は関数型言語の専売特許ではありません。SQL は宣言的の典型例ですが、関数型言語ではありません。TypeScript でも Python でも、書き手の選択次第で宣言的にも手続き的にも記述することができます。

CloudFormation・Copilot・CDK を並べてみる

この宣言的／手続き的という軸と、もう一つの軸である抽象度を組み合わせると、AWS の IaC ツール群の立ち位置が見えてきます。

ツール	記述スタイル	抽象度	メンタルモデルとの距離	ベストプラクティスの規定
AWS CloudFormation	宣言的	低	遠い（AWSリソース視点）	なし（自分で判断）
AWS Copilot CLI	宣言的	高	近い（サービス視点）	強い（AWS が規定）
AWS CDK	宣言的〜手続き的	自由	設計次第	弱い（開発者の規律次第）

AWS CloudFormation

CloudFormation は宣言的です。「あるべき状態」を YAML または JSON で記述し、AWS がその状態に収束させます。冪等性があり、差分管理もできます。

一方で抽象度は低いです。「ロードバランサー付きの Web サービスを動かしたい」という意図を表現するのに、VPC・サブネット・セキュリティグループ・ECS クラスター・タスク定義・ALB・ターゲットグループ・AutoScaling……と、数百行の記述が必要になります。

つまり CloudFormation では、「自分が何をしたいか」を記述するのではなく「AWS が何を必要とするか」を記述しているのです。宣言的ではありますが、人間のメンタルモデルからは遠いと言えます。

AWS Copilot CLI

Copilot のマニフェストはこうです。

name: my-web-service
type: Load Balanced Web Service

image:
  build: Dockerfile
  port: 80

cpu: 256
memory: 512
count: 1

type: Load Balanced Web Service の一行が、VPC・ALB・ECS クラスター・Fargate・AutoScaling をまとめて意味します。これは人間が「ロードバランサー付きの Web サービス」と考えるときのメンタルモデルそのものです。

最終的には CloudFormation に変換されて実行されます。しかしその変換を意識させません。「変換される先が何か」よりも、「書いている人間が何を考えながら書けるか」の方が重要だと考えています。

AWS CDK

CDK は抽象度の自由度が高いです。L3 Constructs を使えば Copilot に近い高抽象度の記述も可能です。最大の利点は、インフラをプログラムとして扱うことで、複雑な要件を論理的に整理し、再利用可能なコンポーネントとして管理できる点にあります。

一方で、プログラミング言語の性質上、リソース間の「依存関係」を明示的に記述するスタイルが基本となります。「VPC を定義し、それを Cluster に参照させ、Service を紐付ける」といった、リソース同士の配線を人間がコントロールする必要があります。これは「記述の簡潔さ」よりも、「システム全体の構造を詳細に把握・制御すること」に重きを置いた設計思想と言えます。

そして CDK もまた最終的には CloudFormation に変換されます。

三者に共通する事実と、それでも違うこと

CloudFormation・Copilot・CDK、いずれも最終的には CloudFormation のテンプレートとして実行されます。その意味では「同じものを作っている」とも言えます。

しかし、書いている人間が何を考えながら書くかはまったく異なります。

CloudFormation: AWS の「リソースの定義」そのものを記述する（確実な基盤）
AWS CDK: インフラの「構造と関係性」をプログラマブルに構築する（柔軟な設計）
AWS Copilot: 特定のパターンに基づき「サービスの意図」を表明する（高速なデリバリー）

変換される先が同じでも、書き手の思考コストは同じではありません。

Copilot が肩代わりしていたもの

ここが核心だと考えています。

Copilot が「考えなくて済む」ようにしてくれていたのは、記述量や抽象度の話だけではありませんでした。「何がベストプラクティスか」という判断そのものを肩代わりしてくれていたのです。

type: Load Balanced Web Service と書いた瞬間に、VPC の構成・セキュリティグループの切り方・ヘルスチェックの設定・AutoScaling の組み方という AWS の知見が暗黙的に注入されていました。ドキュメントを読んで自分で判断する必要がなかったのです。

CDK に移ると、この「判断の肩代わり」が消えます。L3 Constructs はある程度それを引き継ごうとしていますが、Copilot ほど強い意見は持っていません。そして強い意見を持たないということは、悪いプラクティスを選ぶ自由も同時に与えられるということです。

宣言的記述の本質的な価値は、単に「コードを短くすること」ではない。本来はプラットフォームが担うべき「最適解への到達手順」をツールに委ねることで、人間が「構成の細部」ではなく「本来の目的」に集中できる環境を作ることにある。

Copilot はまさにその判断を AWS 側に留保することで、開発者を本来集中すべき問題に向かわせようとしていました。

この性質は、職能別チームからプロダクトチームへと移行した私たちの組織にとって、親和性の高いものでした。各メンバーがより幅広いスキルセットを求められる体制において、AWS に精通していないメンバーであっても Copilot が実装指針をベストプラクティスとともに示してくれる点は、実際の運用上の助けになっていたと認識しています。

ただし、この高い抽象度には「表現力の制約」という側面もありました。Copilot がカバーしていないリソースが必要になった際、結局は CloudFormation での直接記述が求められるなど、利便性と柔軟性の境界線が課題となる場面もありました。

おわりに

Copilot のサポート終了を受けて、後継として ECS Express Mode や CDK L3 Constructs への移行が案内されています。

移行にあたって整理しておきたいのは、Copilot が担っていた「ベストプラクティスの規定者」としての役割のうち、何が引き継がれていて、何は私たち自身の解像度を上げて対応しなければならないのか、という点です。

その視点を持ちながら、これからのインフラ記述のあり方を考えていきたいと思います。

Symfonyの.envファイルをうっかり git プッシュから守る方法 | QUARTETCOM TECH BLOG

Mon, 16 Mar 2026 00:00:00 +0900

Symfony でアプリ開発をしていると .env.local にクレデンシャルをハードコードすることがありますが、センシティブな情報をプレーンテキストで扱うことに若干の怖さを感じています。かんたんにリネームもファイルコピーもできますし GitHub リポジトリに間違えてプッシュしちゃったら怖いですよね。

そんなうっかり操作のヒヤリハットを何らかの仕組みで防止できないか調べてみました。

はじめに

この記事の「クレデンシャル」とは Symfony アプリ内でクローズドに利用する接続情報やトークンのことを示しています。パラメータを経由してサービスクラスに注入しサードパーティベンダーの認証などに使用するイメージです。

# .env.local
APY_KEY=1234abcd
SLACK_TOKEN=xoxb-000000000000-EXAMPLE-TOKEN

# config/services.yaml
parameters:
    apiKey: '%env(APY_KEY)%'
    slackToken: '%env(SLACK_TOKEN)%'

App\Command\SomeService:
    arguments:
        $apiKey: '%apiKey%'
        $slackToken: '%slackToken%'

クレデンシャルは API キー / OAuth 認証トークン / デベロッパートークンなどさまざまな種類があり、ハードコード先も .env.* だけでなく .key .yaml などバリエーションがあります。広範囲に散らばっているクレデンシャルを守るには、いくつかの方法を組み合わせて多層防御するのがベターと言えそうです。

.env.local を git で追跡しない：.gitignore

gitignore は基本的でシンプルな方法です。.gitignore に書いたパターンにマッチすると git で追跡されず、ステージもコミットもされません。Symfony CLI でプロジェクトを作成するとプロジェクトに最適な .gitignore が作成されます。

# .gitignore

###> symfony/framework-bundle ###
/.env.local
/.env.local.php
/.env.*.local
...

けれどもプロジェクトは常に Symfony CLI で構築されるとは限りません。別プロジェクトからソースコードを流用したり、ゼロベースからディレクトリを構成することもあるでしょう。

https://github.com/github/gitignore のようなテンプレートを使って .gitignore を作成した場合 .env.* はその対象に含まれていないかもしれません。記事執筆時点の Symfony 最新バージョンは v8.0.6 ですがテンプレートは v4 以降のリリースに追随していないように見えます。

gitignore /Symfony.gitignore

グローバル設定の ~/.config/git/ignore に .env.* と書いてあるから安全！という思い込みもうっかりミスを誘発します。新しいデバイスをセットアップした時、このディレクトリの同期作業をうっかり忘れてしまうかもしれないからです。

.gitignore による追跡防止は 開発の基本であって過信しないこと というのが私の考えです。

.env.local をコミットしない：1Password Local .env files

1Password は有償のパスワードマネージャーです。
2025/10 に「Local .env files」というベータ版機能がリリースされました。この機能は .env ファイルを安全な場所に退避し、プロセスからの読み取りに開発者の許可を必要とします。

Introducing new .env file support in 1Password environments | 1Password

1Password アプリで「環境」を追加しプロジェクトを判別する任意の名前を付与します。

追加した環境に .env.local をインポートします。

プロジェクトの既存の .env.local を削除し、替わりに 1Password のファイルを保存（マウント）します。

マウントした .env.local はファイルの実体ではなく UNIX の名前付きパイプです。その内容は 1Password によって保護されているため、プロセスが読み取ろうとすると認証ダイアログが表示されます。許可すると 1Password アプリのロックがかかるまでアクセスが可能になります。

この仕組みは「うっかりプッシュ」の観点で良い副作用をもたらします。ファイルの実体ではないため git でコミットできない のです。.gitignore にうっかり書き忘れても、.env.locall とファイル名をタイポしても、コミット時点でブロックされます。

git add .env.local
> error: .env.local: can only add regular files, symbolic links or git-directories
> fatal: updating files failed

そして .env.local を一元管理できるメリットもあります。自宅とオフィスで PC を使い分けているような場合、どのデバイスでも 1Password からマウントしておけば「自宅の PC で変更した内容をオフィスの PC に反映し忘れた」なんてことがなくなります。

ただし落とし穴もあります。一時的なバックアップのために cp .env.local .env.local.bak を実行すると .env.local.bak はファイルの実体として作成され、うっかりコミットが可能になります。

.env.local を作らない：Symfony’s secrets management system

そもそもクレデンシャルを .env.local にハードコードしない手段についても検討の余地があります。Symfony 公式で紹介されている「Symfony’s secrets management system」はそのひとつです。

How to Keep Sensitive Information Secret | Symfony docs

この方法は PHP 7.2+ でバンドルされているモジュール sodium を使ってクレデンシャルを暗号化し config/secrets/* に格納します。

# モジュールが含まれているか調べる
php -m | grep sodium
> sodium

クレデンシャルの登録や削除はコマンドで行います。

# 暗号化・復号化のためのキーペアを作成（初回のみ）
php bin/console secrets:generate-keys

# クレデンシャルを登録
php bin/console secrets:set API_KEY

プロダクション環境用にはプレフィクス APP_RUNTIME_ENV=prod を付与してコマンドを実行します。

# 暗号化・復号化のためのキーペアを作成（初回のみ）
APP_RUNTIME_ENV=prod php bin/console secrets:generate-keys

# クレデンシャルを登録
APP_RUNTIME_ENV=prod php bin/console secrets:set API_KEY

一部のクレデンシャルをローカル開発用にカスタマイズする時は --local オプションを使用します。

bin/console secrets:set API_KEY --local

dev prod local それぞれの環境用に生成されたファイル群は以下のように格納されます。

config/secrets
├── dev
│   ├── dev.API_KEY.b58958.php # 個別のクレデンシャル
│   ├── dev.decrypt.private.php # 復号化の秘密鍵
│   ├── dev.encrypt.public.php # 暗号化の公開鍵
│   ├── dev.list.php # クレデンシャルのリスト
└── prod
    ├── prod.API_KEY.b58958.php # 個別のクレデンシャル
    ├── prod.decrypt.private.php # 復号化の秘密鍵
    ├── prod.encrypt.public.php # 暗号化の公開鍵
    └── prod.list.php # クレデンシャルのリスト

.env.dev.local # ローカル開発用にカスタマイズした値

これらのファイルのうち、プロダクション環境の秘密鍵 prod.decrypt.private.php だけはコミットしてはいけません。秘密鍵を直接サーバーに置くか、サーバーの環境変数 SYMFONY_DECRYPTION_SECRET に登録します。

# (A) サーバーに直接配置
config/secrets/prod/prod.decrypt.private.php

# (B) 環境変数に登録
export SYMFONY_DECRYPTION_SECRET={Base64 エンコードした鍵}

登録したクレデンシャルはコマンドでリストアップできます。

# --reveal オプションで値の表示ができる
php bin/console secrets:list --reveal

> ------------ ---------- ------------- 
>  Secret       Value      Local Value  
> ------------ ---------- ------------- 
>  API_KEY      "123abc"   "111aaa"    
>  DB_PASSWORD  "123def"   "222bbb"
> ------------ ---------- ------------- 

この仕組みは .env.* を使用せず 「うっかりプッシュ」対象を「プッシュしても良い情報」 に置き換えます。ただしローカル開発用にカスタマイズした .env.dev.local は依然としてうっかりコミットの可能性が残ります。

プッシュをブロック：GitHub Push protection

クレデンシャルの格納先は .env.* とは限りません。.key .yaml にハードコードした内容を無害なファイルパスとして .env.local に渡すことがあります。GitHub の Push protection はそのようなケースで有効です。

ユーザーのプッシュ保護 | GitHub ドキュメント

Organization に属さない個人アカウント配下でパブリックなリポジトリを作成したところ、デフォルトで Push protection が有効になっていました。

試しに AWS アカウントなどダミーのクレデンシャルを書いたファイルをプッシュすると Push protection によってデータ転送がブロックされました。

# config/keys/sample.key

DUMMY_GITHUB_TOKEN=ghp_dummy12341234nopqrstuvwxyz....
DUMMY_AWS_KEY=AKIAQA2IFJE3MPUDUMMY
DUMMY_AWS_SECRET=gsDummyyGtzLXigRMVcDHeuS7Neg6vd....

# 主要な部分のみ抜粋
git push origin main

Enumerating objects: 8, done.
Counting objects: 100% (8/8), done.
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote: error: GH013: Repository rule violations found for refs/heads/main.
remote: 
remote: - GITHUB PUSH PROTECTION
remote:   —————————————————————————————————————————
remote:     Resolve the following violations before pushing again
remote:     - Push cannot contain secrets
remote:     
remote:       —— Amazon AWS Access Key ID ——————————————————————————
remote:        locations:
remote:          - commit: 0a000111222...
remote:            path: config/keys/sample.key:4
remote:     
remote:       —— Amazon AWS Secret Access Key ——————————————————————
remote:        locations:
remote:          - commit: 0a000111222...
remote:            path: config/keys/sample.key:5
remote: 
 ! [remote rejected] main -> main (push declined due to repository rule violations)

# ブロックしてくれた ☺️

ダミーの RSA 秘密鍵も試したところ、こちらは Push protection が反応せずプッシュが完了しました。

# config/keys/sample.key（実在しないクレデンシャル）

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEArandomrandomrandomrandomrandomrandomrandomrandom
....
-----END RSA PRIVATE KEY-----

git push origin main
> Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
> + 1234c7c...4567ccc main -> main

# プッシュ完了...🙄

GitHub ドキュメントの Supported secrets を読むと Push protection は単純なパターンマッチングのようなチェックではないことが分かります。

トークン提供元のプロバイダ（AWS / Google など）によるチェックと、非プロバイダ（Generic）に分かれる
プロバイダにクレデンシャルを送信してトークンの有効性をチェックすることがある
トークンやプロバイダによってチェック内容の網羅度合いが異なる
個人アカウントのパブリックリポジトリに適用されるチェックと GitHub Team / Enterprise の GitHub Secret Protection で適用されるチェックに違いがある

偽物のクレデンシャルとほんの数回のプッシュ確認では、ブロック可能なパターンを帰納的に洗い出すことはできませんでした。

しかしながら、あらゆるクレデンシャルを対象に GitHub がスキャンしてくれる機能はとても強力です。ブロックが成功した AWS アクセスキーについてはファイルから削除するだけではダメで、コミットログも完全に消し去らないとプッシュができませんでした。

GitHub Push protection は .env.local の 外に漏れ出てしまった情報の監視役 として有効に機能してくれそうです。

まとめ

Symfony や GitHub など、それぞれがうっかりプッシュの防止策を提供してくれています。どれもすべてのクレデンシャルやユースケースを網羅できる仕組みではありませんが、組み合わせれば高い効果が期待できそうです。

これさえやっておけば大丈夫！と慢心せず、ローカルでもクラウドでも電子的に保存したデータは常に漏洩リスクを孕んでいることを念頭に開発していきたいと思っています。

Claude Code 入門: 導入から基本操作・コスト管理まで | QUARTETCOM TECH BLOG

Tue, 24 Feb 2026 00:00:00 +0900

開発部では最近、開発効率を向上させる施策の一環として、Anthropic 社の CLI 型 AI エージェント「Claude Code」を導入しました。

本記事は、これから Claude Code を触ってみたいエンジニアや、AI ツールによる開発効率化に関心のある方に向けた実践ガイドです。

今回は、「基本概念」から、コストを抑える運用まで共有します。

1. まず押さえたい基本概念: 「セッション」と「コンテキスト」

Claude Code を使いこなす上で、以下の 2 つの概念を理解しておくとスムーズです。

セッション（作業のまとまり）

Claude Code は、起動してから終了するまでの一連のやり取りを「セッション」として管理します。

最も重要な仕様は、セッションは「起動ディレクトリ（フォルダ）」に紐付いて管理されるという点です。

[プロジェクトAのディレクトリ] ⇔ [セッションA（Aの記憶）]
        ｜
    (ディレクトリ移動)
        ↓
[プロジェクトBのディレクトリ] ⇔ [セッションB（Bの記憶）]

つまり、ディレクトリを移動して新しく claude を起動すれば、別のセッションとして扱われます（前のディレクトリのコンテキストを引きずりません）。

履歴は保存されているため、完全に消失するわけではありません。

後述の /resume コマンドを使えば、過去のセッション一覧から再開したい作業を選んで元の状態を復元できます。

コンテキスト（AI の短期記憶）

AI が一度に覚えられる情報量のことです。会話が長くなると、この「コンテキスト」が溜まっていきます。

コンテキストが溜まると、AI が処理すべき情報量が増えるため、結果として利用料（コスト）も上がってしまいます。

2. 初期設定: `/init` と `CLAUDE.md`

プロジェクトの「記憶」を作る `/init`

初めて Claude Code を使うディレクトリでは、最初に以下のコマンドを実行します。

> /init

これを実行すると CLAUDE.md というファイルが生成されます。ここにはビルドコマンドやコーディング規約などを記述します。 Claude Code は起動時にこのファイルを読み込み、プロジェクトのルールを理解します。

チーム開発での運用ルール

共有設定（Git 管理する）: プロジェクトルートの CLAUDE.md はGit にコミットします。これにより、チーム全員が同じルール（ビルド手順や規約）を共有でき、通常は他のメンバーが /init を実行する必要がなくなります（既に設定ファイルが存在するため）。

要件定義ファイルなどの扱い

CLAUDE.md はあくまで「ルールブック」です。機能ごとの仕様書などは docs/spec.md などのファイルに分け、指示出しの際に @docs/spec.md のように参照させます。

3. うまく伝わらない時は？コンテキスト管理のコツ

使っていると、「最近、指示の意図を汲んでくれなくなったな……」と感じることがあります。これはコンテキストが溜まりすぎて、AI が混乱しているサインかもしれません。

基本は `/clear` でリセット

タスクの区切りや、話が噛み合わなくなったら、以下のコマンドを打ちます。

> /clear

これにより、これまでのコンテキストが消去され、まっさらな状態で再スタートできます。 CLAUDE.md の内容は保持されます。

コンテキストを残したいなら `/compact`

「今の文脈は維持したいけど、少し記憶を整理したい」という場合は /compact が有効です。

これは会話の要約のみを残し、個別のやり取りの詳細な履歴を削除することで、コンテキストを圧縮します。

4. 利用状況の確認とモデルの使い分け

Claude Code の利用状況や制限は、以下のコマンドで確認できます。契約形態（サブスクリプションまたは API 課金）によって使い分けます。

利用状況の確認

サブスクリプションプランの場合: /usage コマンド
- Claude Pro などのサブスクリプションプランで利用している場合、ここからレートリミット（残り使用回数）やプランの使用状況を確認できます。
API キーを利用（従量課金）の場合: /cost コマンド
- 組織で API キーを利用（従量課金）している場合、現在のセッション費用を確認できます。

モデルの使い分け

Sonnet 系モデル: 日常的なコーディングや修正。速度とコストのバランス型です。
Opus 系モデル: 複雑な設計や難解なバグ調査。高精度で、深い推論を必要とする作業向けです。

※モデル性能はアップデートにより変更される場合があります。

5. 急な割り込み対応（セッション管理）

開発中に緊急対応が入った場合も、セッション機能を使えば安全に中断・再開できます。

中断: 作業中のセッションに /rename [タスク名] で名前を付けて保存します。
再開: /resume で過去のセッションを選択し、元の状態（コンテキスト含む）から再開できます。
並行作業: Claude Code のセッションはディレクトリに紐付いています。そのため、git worktree でディレクトリを分け、セッションを分離して並行作業できます。片方で「バグ調査」をさせつつ、もう片方で「新機能実装」を進めるなど、互いのコンテキストを混ぜずに並行作業が行えます。

まとめ

基本: セッションはディレクトリに紐付くため、場所を変えて起動すれば記憶も変わる。
設定: チームルールはルートの CLAUDE.md（Git 管理）
維持: 話が噛み合わなくなったら /clear。コスト節約にもなる。
運用: モデルの使い分けと /resume で柔軟に対応。

ぜひ、皆さんの開発フローにも取り入れてみてください。

GitHubのマージ（Merge Commit/Squash Merging/Rebase Merging）の違い | QUARTETCOM TECH BLOG

Fri, 05 Dec 2025 00:00:00 +0900

GitHub でプルリクエストをマージする時、マージボタンのプルダウンに「Squash and merge」「Rebase and merge」ってありますよね。これらの違いをよく知らなかったので手元で試してみました。

プルリクエストのマージについて | GitHub ドキュメント

動作確認用に使ったプルリクエストはタイトルを PR-A に、コミットメッセージを A1 {コミット時刻} と統一しています。

1) Create a merge commit

プルダウンを展開せずにマージボタンを押したデフォルトの動作です。

同じブランチから切った複数ブランチをマージすると、時系列でコミットが積み上がります。

メインブランチに見立てた merge にブランチ merge-A merge-B をマージすると次の図のようになります。

git log merge-A
> 44b8478 A2 21:25
> fba0ad2 A1 21:23

git log merge-B
> 6bfb8c4 B2 21:26
> 74b8961 B1 21:24

git log merge
> 881e805 Merge pull request #18 from ringtail003/merge-B
> d2bef64 Merge pull request #17 from ringtail003/merge-A
> 6bfb8c4 B2 21:26 <== プルリクエスト(2)のコミット
> 44b8478 A2 21:25 <== プルリクエスト(1)のコミット
> 74b8961 B1 21:24 <== プルリクエスト(2)のコミット
> fba0ad2 A1 21:23 <== プルリクエスト(1)のコミット

GitHub でサンプルを見る

2) Squash and merge

Squash はプルリクエストのコミット群をひとつにまとめた新しいコミットを作成します。マージ先のブランチでは、プルリクエストとコミットが 1 対 1 になります。

メインブランチに見立てた squash にブランチ squash-A squash-B をマージすると次の図のようになります。

git log squash-A
> 36001a5 A2 21:33 <== マージ元のコミット(2個目)
> 709eb44 A1 21:30 <== マージ元のコミット(1個目)

git log squash-B
> 2d087cb B2 21:34
> aea1a38 B1 21:32

git log squash
> 7d65cc7 PR-B (#20)
> 6d63afc PR-A (#19) <== マージ先のコミット（1個にまとまる）

GitHub でサンプルを見る

Squash and merge の Author

いくつかプルリクエストを作って試したところ、プルリクエストに一番最初にコミットした人がマージコミットの Author として採用されるようです。

プルリクエストに 2 番目以降にコミットした人は「共作者」という扱いになります。

git log --pretty=full

> commit 1234abc
> Author: user1 <user1@example.com>
> Commit: GitHub <noreply@github.com>
>  PR-A (#100)
> 
>  * A1
>  * A2
>  ---------
>  Co-authored-by: user2 <user2@example.com> <== 共作者

複数の作者を持つコミットを作成する | GitHub ドキュメント

3) Rebase and merge

Rebase はプルリクエストをマージ先ブランチでリベースしてからコミットを積みます。そのためコミットにそれぞれ新しいハッシュが付与されます。

メインブランチに見立てた rebase にブランチ rebase-A rebase-B をマージすると次の図のようになります。

git log rebase-A
> 7258210 A2 21:39
> 7fcedd0 A1 21:37 <== マージ元のコミット

git log rebase-B
> 6ecf78f B2 21:40
> 5bd574d B1 21:38

git log rebase
> 3acd2d8 B2 21:40
> f4e83f7 B1 21:38
> e733a59 A2 21:39
> def1981 A1 21:37 <== マージ先のコミット(ハッシュが変わる)

GitHub でサンプルを見る

マージメッセージ

マージコミットのメッセージは Settings ページで変更できます。

選択肢がたくさんあるので表にまとめました。動作確認用に使ったプルリクエストはタイトルを PR-A {メッセージの種類} と統一しています。

マージの動作	メッセージの種類	Commits ページの表示
Merge	`Default message`
Merge	`Pull request title`
Merge	`Pull request title and description`
Squash	`Default message`
Squash	`Pull request title`
Squash	`Pull request title and commit details`
Squash	`Pull request title and description`

GitHub でサンプルを見る | Merge
GitHub でサンプルを見る | Squash

一見すると同じに見えるマージメッセージですが、マージコミットのボディ部分が異なります。

Default message

Pull request title

Pull request title and commit details

Pull request title and description

考察

マージについて調べようと思ったきっかけは、どのプルリクエストをどの順番でマージしたのかサマリを見たいと思ったことでした。

この用途だと、プルリクエストごとにマージコミットが作成される「Squash and merge」が良さそうだということになります。ですが 1 コミットに集約されることで、本来のコミットごとの作業履歴が見られなくなる、単一のコミットでリバートできなくなる、などデメリットもあるようです。たとえば release ブランチにマージする時だけ「Squash and merge」を適用できたら嬉しいのですが記事執筆時点（2025/12）ではブランチごとのコントロールはできないようでした。

せっせとキャプチャをとってまとめましたが結論はデフォルトのまま現状維持、いずれまた検討する時がきたらこのブログを見に来ます。

暗黙知が支える技術の本質 | QUARTETCOM TECH BLOG

Fri, 10 Oct 2025 00:00:00 +0900

ソフトウェア開発の現場では、属人化を避けるために「なんでもドキュメント化しよう」という文化がよく見られます。
ナレッジを共有し、誰がいなくなっても困らないチームを作るという考え方自体は、合理的で正しいものだと思います。

しかし、「なんでもドキュメント化しよう」という文化は、捉え方次第では技術の習得という観点で思わぬ弊害を生むことがあります。

属人化とドキュメントのジレンマ

例えば、あるプロジェクトの環境構築の手順をまとめたドキュメントがあるとします。
そのドキュメントの内容は、何のために、どこまで詳細に書くべきでしょうか。
その線引きは、チームの方針やメンバーに求めるスキルレベルなどによって大きく異なります。

手順を細かく書けば、誰でも手順通りに作業でき、効率的に環境構築を進められます。
もし途中で問題が発生したとしても、そういったケースのトラブルシューティングの手順も記載しておけば問題ないでしょう。

しかし、そのようなドキュメントに完全に頼って環境構築を終えたメンバーは、「自走して環境構築ができた」と言えるでしょうか。
多くの場合、それは「再現できた」にすぎず、「理解して環境構築できた」とは異なります。

ドキュメントが過度に充実してマニュアルのようになると、「なぜそうするのか」を考える機会が失われます。
チーム全体がそれを当然のように良しとし、盲目的にドキュメント化を推進していると、将来的にメンバーの技術習得が課題になったり、評価と自己認識のズレや、学習意欲の低下といった問題が生じるかもしれません。

技術の習得には、思考の身体化が必要

ドキュメントは形式知を伝えるための手段としてとても有効ですが、それだけでは技術を習得することはできません。

技術を習得するということは、単に知識を得ることではありません。
知識や経験をうまく繋げ、状況に応じて適切に判断するための思考を身体化することが必要です。

開発者としてある程度経験を積むと、「この実装はなぜ気持ち悪いのか」「なぜ今はこの構成のほうが良いのか」といった、言語化しづらい感覚的な知識（暗黙知）を得て、それに基づいた判断ができるようになります。

この暗黙知は、どれだけ充実したドキュメントを読んでも得ることはできません。
仮に「なぜそうするのか」まで書かれていても、それを形式的に知るだけでは、思考の再現には至りません。

暗黙知についての有名な例えである「自転車の乗り方」（自転車の乗り方は実際に自転車に乗ることでしか知ることができず、どのように操作すれば良いかを言語化して説明することが難しい）と同じように、技術もまた、手と頭を動かし、試行錯誤するプロセスを通じてしか身につきません。
うまくいったり、うまくいかない経験のなかで生まれる感覚が、技術者としての「地力」となっていきます。

暗黙知は、文化として残す

「属人化を避けよう」というスローガンの背景には、「個人への依存を減らそう」という意図があると思います。
しかし、開発をうまく進めるための本質的な知識の多くは、個人の経験からでしか獲得できない暗黙知にあります。

本当に強いチームとは、単に手順が共有されているチームではなく、暗黙知を文化として共有できるチームです。
ドキュメントは形式知を必要な分だけ残すことに留め、設計思想、デバッグの勘所、コードの美学といった暗黙知は、ペアプロ・コードレビュー・日常的な対話などを通して受け継いでいくことが大切です。

一緒に手を動かし、考え方や価値観を自然に共有できる時間を増やすことが、結果的にチームを強くします。

終わりに

「できる」や「できるようになった」という感覚や手応えがあると、プロセスを楽しめたり、より創造的になれたりします。

今回の記事では、ドキュメント化の具体的な方法までは踏み込めませんでしたが、今後は「強いチームをつくるためのドキュメントとは何か」を意識して考えていきたいと思います！

独自のドメインモデルを捨てて、外部のドメインモデルに従う提案 | QUARTETCOM TECH BLOG

Wed, 01 Oct 2025 00:00:00 +0900

はじめに

担当しているプロダクトには 「広告を入稿する」機能 があり、これは社内のユーザ部門の業務効率化が主な目的です。

今までのフローとして、お客様に「広告設定確認書」という書類を提出して、
その「広告設定確認書内の広告設定」を元に「当該の広告媒体へ入稿を行う」業務フローがありました。

このフローをシステム化することで、業務効率を上げていました。システムの内部の処理は、「独自ドメインモデル(広告設定確認書内の広告設定)」を定義し、それを「外部ドメインモデル（媒体API・SDK）」に変換して入稿 API を叩く、という二段構えのフローを採用していました。

このプロダクトを運用していくうちに、運用においても開発においても課題が見えてきました。

プロダクトの課題

「独自ドメインモデル(広告設定確認書内の広告設定)」 を 「外部ドメインモデル (媒体API・SDK)」 に変換する際に、スキーマの不一致によってデータの互換性が取れず、API エラーが起きやすい
「独自ドメインモデル」、「外部ドメインモデル」と理解するモデルが2つあり、認知負荷が高い
データ互換性維持のための差分対応が属人化し、特定の人しか直しづらい状態になっている

まとめると「認知負荷が高い」と「データ互換性維持が困難」、「独自ドメインモデルに属人性がある」という課題 がありました。
また、広告媒体 API はアップデートされる機会が多く、このような問題に陥るケースが多くありました。

そのことから、現状の設計を根本から見直して、課題を解決する方法を考えました。

実装した設計

コンセプト

「外部ドメインモデル駆動」 とする設計です。
外部ドメインモデルの変化をシステムがしっかりと影響を受けて、システムが変化する ことを狙っています。

つまり外部のドメインモデルに主体性があります。

API 更新頻度が高いため、ACL 層を維持して独自ドメインモデルを管理するよりも、外部ドメインモデルに直接追従する方が、全体のコストを下げて安定運用できると判断して、 ACL 層を外す判断をしました。

これは一般的な設計の方針から外れる大胆な判断ですが、「API に追従することが最優先の領域」 では合理的だと考えました。

その他のコンセプトを箇条書きすると以下となります。

特定のオブジェクトのスキーマ(今回で言うと入稿 API を実行する際に必要なオブジェクト)を外部ドメインモデルに寄せている
SDK のスキーマをミラー(写像)した Interface を定義している
- その Interface を持つオブジェクトを各層に実装する
  - Infrastructure 層
    - API や SDK とやり取りする層
  - Presentation 層
    - フロントエンドの関心を持つ層
      - バリデーションの定義を持つ
      - API スキーマとして表に出す層
  - Entity 層
    - DB に保存する関心を持つ層
- いずれの層は同じインターフェース(スキーマ)が実装されているので「オブジェクト to オブジェクト」のような変換が容易。
  - フロントエンドで来たものを Entity 層に変換したり、Infrastructure 層に変換して API の実行ができたりと、レイヤーの意味を考えながら実装ができる
本来あるはずの Anti-Corruption Layer (ACL) 層を外して、外部ドメインモデルのスキーマを自システムに影響を反映させる

また「SDK のスキーマをミラー(写像)した Interface」は以下のように「getter」を定義して、スキーマの互換性を表現しています。

interface CampaignInterface {
    public function getName(): ?string;
    // SDK スキーマと同じフィールド
}

気をつけていること

SDK のオブジェクトを「我々のコード」に注入せず、SDK のスキーマをミラー(写像)した Interface に依存している
- SDK のオブジェクトは基本的に使いづらかったり、実装が汚れがちであるため、Infrastructure 層だけ SDK のオブジェクトを扱うようにして、実装の汚れを閉じ込めている
- いわば「依存関係逆転の原則(DIP)」を取り入れて、「SDK -> Interface -> Domain」の関係性を作っています。

この設計を取り入れるメリット

API 更新への追従が容易になる
- API の更新内容を見て、変更があれば「我々のシステムの外部ドメインモデルを変更する」、という一対一の関係ができる
属人化を排除できる
- モデルの説明を媒体ドキュメントに委譲できる。
データの互換性の維持が容易になる
- 抽象層(独自ドメインモデル)を介さず、媒体スキーマに準拠しているため、適合性が高くできる

この設計を取り入れるデメリット

「外部ドメインモデル（媒体API・SDK）」の理解が必要
- ただし、これは広告運用プロダクトを扱う以上、避けられない前提知識でもある
「外部ドメインモデル（媒体API・SDK）」が廃止した時、プロダクトの改修範囲が大きくなる
外部ドメインモデルをそのままコピーするのでファイル数が膨大になる
SDK 側の仕様変更に強く依存するため「ドメイン固有の最適化」がやりにくい
- 例：「API のマイクロバジェット値(マイクロ単位の通貨値)」をシステムでは「円」として保存しておきたいなど
元々存在した「独自ドメインモデル(広告設定確認書内の広告設定)」を使わなくなったため、ユーザ部門のコントロール性が下がった。（ただし、今回の設計変更は、ユーザ部門の負うこととなるこの「デメリット」を許容してもらうことをまず合意したうえでとりかかった）
- ユビキタス言語もロストしているため、業務の影響は多少なりとも出ている
- 正規化したと考えても良いが、業務をシステム都合で変えてしまっているのは変わりがない

まとめ

抽象化は一見便利ですが、常に媒体 API に追従しなければならないシステムにおいては、むしろ負債 になりがちです。

一方で、抽象化することで 1 つのモデルで他媒体の関心を共通化できるメリットもあるので、
どの選択をしてもリスクとリターンがあると、総括して感じました。

今回の設計は独自のドメインモデルを捨てて外部ドメインモデルに従う、いわば「逆DDD」ですが、
認知負荷の低減・属人化の排除・最新 API への追従を考えると、やはりメリットが多いと感じます。

そのことから「むしろ API にしっかりと追従する必要があるシステムには逆DDD が良い」という提案をしました。

実際に、この設計を今のプロダクトに適応している最中ですが、 API の追従がしやすかったり、スキーマに互換性があるため、API を叩きやすかったりと効果的だと感じています。

とはいえ、知れ渡っている理論を逆行する設計なので、心理的にも思い切りが必要です。
そのため 「逆DDD」を採用する時は、しっかりと「そのシステムで何をしたいのか？」を明確化して判断する のをオススメします。

所感

自分でモデリングする機会が減りました。
面白いところだと思いますが、少し残念です。

ひたすら外部ドメインモデルのリファレンスを読んで、
インターフェースやクラスを書いているので、作業感がとてもあります。
(かなり膨大なので疲れます)

それでもシステムは安定してきているので、作っているシステムにとって良い設計だろうと判断しています。

Symfonyのretry_failed optionsを使って、APIリクエスト失敗時に再試行するようにする | QUARTETCOM TECH BLOG

Thu, 25 Sep 2025 00:00:00 +0900

Symfonyのretry_failed optionsを活用すると、APIリクエストが失敗した際に指数バックオフアルゴリズムによる再試行が簡単に実装できます。

本記事では、その設定方法と検証結果を紹介します :saluting_face:

指数バックオフアルゴリズム (Exponential Backoff Algorithm)とは

ネットワークやAPIリトライなどで使われる「待ち時間を指数的に増やして再試行する仕組み」です。

例えば初回 1秒 → 2秒 → 4秒 → 8秒 … のように、待機時間を指数関数的に増加させてリトライ処理をします。

過去記事「リトライ処理時の指数バックオフアルゴリズムを AWS Step Functions で実装」も参考になるので読んでみてください。
https://tech.quartetcom.co.jp/2024/10/29/exponential-backoff-step-functions/

Symfonyのretry_failed optionsの設定方法

config/packages/framework.yamlを以下のように設定します。
※Symfony 5.2以降で利用可能です。

//  config/packages/framework.yaml

framework:
    http_client:
        default_options:
            retry_failed:
                enabled: true
                max_retries: 5 # 最大リトライ回数
                delay: 1000    # 初期遅延 (ミリ秒) → 1s
                multiplier: 2  # 指数の倍率（2 なら 1s,2s,4s,8s...）
                max_delay: 64000 # 最大待機（ミリ秒）→ Memorystoreの推奨に合わせ64s上限など
                jitter: 0.1    # ジッター（0.0〜1.0、ここでは10%の揺らし）。同じタイミングで大量のリトライが発生しないようにランダムなばらつきをもたせる
                http_codes: [ 423, 425, 429, 500, 502, 503, 504, 507, 510 ] # リトライ対象のHTTPコード

特定API使用時のみリトライする場合は、scoped_clientsを使います。

framework:
    http_client:
-        default_options:
+        scoped_clients:
+            api_time.client:
+               base_uri: 'https://127.0.0.1:8000/api/time'
                    retry_failed:
                        enabled: true
                        max_retries: 5
                        ...

//src/Controller/RequestController.php

...
use Symfony\Contracts\HttpClient\HttpClientInterface:

final class RequestController extends AbstractController
{
    #[Route('/request', name: 'app_request')]
    public function index(
        #[Autowire(service: 'api_time.client')]
        HttpClientInterface $httpClient
    ): Response
    {
        //APIにアクセスする
        $response = $httpClient->request('GET', 'https://127.0.0.1:8000/api/time');
        if ($response->getStatusCode() !== 200) {
            return $this->render('request/error.html.twig', [
                'message' => 'API request failed with status code: ' . $response->getStatusCode(),
            ]);
        }

        $content = $response->toArray();
        return $this->render('request/index.html.twig', [
            'time' => $content['time'],
        ]);
    }
}

参考: https://symfony.com/doc/current/reference/configuration/framework.html#http-client

本当に指数関数的にリトライしているか検証

以下の手順で検証を行いました。

HTTP 429エラー(2リクエスト/10秒)を意図的に発生させるAPIを作成
1で作成したAPIにリクエストをするクライアントにSymfonyのretry_failedオプションを設定
リトライ処理が実際に行われているか確認

1. HTTP 429エラー(2リクエスト/10秒)を意図的に発生させるAPIを作成

composer create-project symfony/skeleton:"7.3.x" rate-limitter-example
cd rate-limitter-example/
composer require webapp
composer require symfony/rate-limiter
bin/console make:controlle ApiTimeController

// src/Controller/ShowTimeController.php

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;
use Symfony\Component\Routing\Attribute\Route;

final class ApiTimeController extends AbstractController
{
    #[Route('/api/time', name: 'app_api_time')]
    public function index(Request $request, RateLimiterFactoryInterface $apiTimeLimiter): Response
    {
        $limiter = $apiTimeLimiter->create($request->getClientIp());

        // consume(1)の1は消費するトークン数
        if (false === $limiter->consume(1)->isAccepted()) {
            throw new TooManyRequestsHttpException(null, 'Too Many Requests');
        }

        return $this->json([
            'time' => (new \DateTime())->format('Y-m-d H:i:s'),
        ]);
    }
}    

// config/packages/rate_limiter.yaml

framework:
    rate_limiter:
        api_time:
            # use 'sliding_window' if you prefer that policy
            policy: 'fixed_window'
            limit: 2
            interval: '10 second'

2. 1で作成したAPIを使用するクライアントにSymfonyのretry_failedオプションを設定

composer create-project symfony/skeleton:"7.3.x" clear-late-limiter
cd clear-late-limiter/
composer require webapp
bin/console make:controlle RequestController

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Contracts\HttpClient\HttpClientInterface;

final class RequestController extends AbstractController
{
    #[Route('/request', name: 'app_request')]
    public function index(
        HttpClientInterface $httpClient
    ): Response
    {
        //APIにアクセスする
        $response = $httpClient->request('GET', 'https://127.0.0.1:8000/api/time');
        if ($response->getStatusCode() !== 200) {
            return $this->render('request/error.html.twig', [
                'message' => 'API request failed with status code: ' . $response->getStatusCode(),
            ]);
        }

        $content = $response->toArray();
        return $this->render('request/index.html.twig', [
            'time' => $content['time'],
        ]);
    }
}

//  config/packages/framework.yaml

framework:
    http_client:
        default_options:
            retry_failed:
                enabled: true
                max_retries: 5 # 最大リトライ回数
                delay: 1000    # 初期遅延 (ミリ秒) → 1s
                multiplier: 2  # 指数の倍率（2 なら 1s,2s,4s,8s...）
                max_delay: 64000 # 最大待機（ミリ秒）→ Memorystoreの推奨に合わせ64s上限など
                jitter: 0.0    # ジッター（0.0〜1.0、ここでは10%の揺らし）。同じタイミングで大量のリトライが発生しないようにランダムなばらつきをもたせる
                http_codes: [ 423, 425, 429, 500, 502, 503, 504, 507, 510 ] # リトライ対象のHTTPコード

上記の設定で指数関数的にリトライするように設定します。今回は検証結果がわかりやすいように、jitter: 0.0とします。

3. リトライ処理が実際に行われているか確認

symfony server:startで各サーバを立てます。以下

https://127.0.0.1:8000 API側
https://127.0.0.1:8001 クライアント側

とします。

https://127.0.0.1:8001/request に短時間に連続してアクセスしてみます。

その後、クライアント側のProfiler > HTTP Client > Responseを確認すると以下のことがわかります。

"retry_count" => 4より、4回リトライし、5回目で成功している
"retries"より、各リトライが1秒後 → 2秒後 → 4秒後 → 8秒後と指数関数的に試行されている

[▼
  [▼
  "info" => [▼
    ...
    "debug" => """
      ...
      * Request completely sent off
      < HTTP/2 200 
      < cache-control: no-cache, private
      < content-type: application/json
      < date: Mon, 22 Sep 2025 01:37:56 GMT
      ...
  ]
  "retry_count" => 4
  "response_headers" => [▶]
  "response_json" => [▶]
  "retries" => [▼
    [▼
      ...
      "debug" => """
        ...
        * Request completely sent off
        < HTTP/2 429 
        < cache-control: no-cache, private
        < content-type: text/html; charset=UTF-8
        < date: Mon, 22 Sep 2025 01:37:41 GMT
        ...
    ]
    [▼
      ...
      "debug" => """
        ...
        * Request completely sent off
        < HTTP/2 429 
        < cache-control: no-cache, private
        < content-type: text/html; charset=UTF-8
        < date: Mon, 22 Sep 2025 01:37:42 GMT
        ...
    ]
    [▼
      ...
      "debug" => """
        ...        
        * Request completely sent off
        < HTTP/2 429 
        < cache-control: no-cache, private
        < content-type: text/html; charset=UTF-8
        < date: Mon, 22 Sep 2025 01:37:44 GMT
        ...
    ]
    [▼
      ...
      "debug" => """
        ...
        * Request completely sent off
        < HTTP/2 429 
        < cache-control: no-cache, private
        < content-type: text/html; charset=UTF-8
        < date: Mon, 22 Sep 2025 01:37:48 GMT
        ...
    ]
  ]
]

まとめ

今回の検証では、2リクエスト/10秒という制限のあるAPIに対して、delay: 1000(=1秒)・multiplier: 2に設定したところ、リトライが頻繁に発生し、設定した最大リトライ回数（max_retries）に達してしまうケースがありました。

このため、API側のレート制限に合わせて、delayやmultiplier、max_retriesなどのパラメータを適切に調整することが重要です :warning:

Symfonyのretry_failed optionsを活用すれば、指数バックオフアルゴリズムによるリトライ機能を簡単に設定できます！ぜひ皆さんのプロジェクトでも取り入れてみてください :heart_hands:

PHPでGraphQLサーバー構築入門：Symfony＋API Platformを活用した実践 | QUARTETCOM TECH BLOG

Fri, 15 Aug 2025 00:00:00 +0900

近年のWebアプリケーションでは、画面構成やUXの多様化にともない「より柔軟で効率的なデータ取得」の重要性が高まっています。

特にフロントエンドでは、不要なデータ取得や複数回のAPIリクエストが開発体験やパフォーマンスに影響を与えるケースも増えてきました。

よく使われているREST APIでは、エンドポイントごとに決まったレスポンスが返ってくるため、フロント側の要件に合わせて「不要なデータを受け取る」や「複数のエンドポイントを呼び分ける」 といった非効率が発生しがちです。

これらの課題を解決する手段として注目されているのがGraphQLです。

GraphQLを使えば、クライアントが必要なデータだけを明確に指定して取得できるため、通信の無駄が減り開発効率やパフォーマンスの向上につながります。

本記事では、Symfony と API Platformを使って、GraphQL APIを簡単に作成する方法を紹介します。

✅️ 今回作成するもの

今回は「書籍（Book）」と「レビュー（Review）」のデータを扱うGraphQL APIを作成します。

書籍一覧の取得
各書籍に紐づくレビューの平均スコアの取得
React + Apollo Clientを使ったフロントエンドでのデータ取得

フロント以外のコードはGitHubに公開していますので、ぜひ参考にしてください。

🔗GitHub：symfony-api-platform-graphql

📝 目次

1. Symfonyプロジェクトのセットアップ
2. API Platformの導入
3. データベース接続（PostgreSQL）
4. Book / Reviewエンティティの作成とマイグレーション
5. データ登録 (REST API)
6. GraphQLの有効化
7. GraphQLで書籍一覧を取得
8. カスタムフィールド（レビューの平均スコア）を追加
9. フロント側からデータを取得する
10. まとめ

1. Symfonyプロジェクトのセットアップ

使用バージョン：

PHP:v8.2.28
Symfony:v7.3.1

まずは新規プロジェクトを作成します。

$ symfony new symfony-api-platform-graphql

2. API Platformの導入

API Platformは、PHP製のWeb APIフレームワークです。導入するだけで自動的にRESTとGraphQLのAPIエンドポイントが作成されます。

$ composer require api

これだけで/apiにアクセスすると、Swagger UIでREST APIのドキュメントが確認できます。

💡 API Platform では、REST API と GraphQL API の両方を併用できます。エンティティを定義するだけで、自動的に REST のエンドポイントが生成され、Swagger UI から確認や操作も可能です。本記事では GraphQL をメインに扱いますが、動作確認も兼ねてデータ登録には REST API を使って進めていきます。

3. データベース接続（PostgreSQL）

.envファイルを編集し、PostgreSQLに接続できるように設定します。

- DATABASE_URL="postgresql://app:!ChangeMe!@127.0.0.1:5432/app?serverVersion=16&charset=utf8"
+ DATABASE_URL="postgresql://app:!@127.0.0.1:5432/symfony-api-platform-graphql?serverVersion=16&charset=utf8"

ユーザー名やパスワードは自分の環境に合わせて変更してください。
事前にPostgreSQLをインストールしておく必要があります。
PostgreSQL の代わりに SQLite や MySQL を使っても大丈夫です。

その後、以下のコマンドでデータベースを作成します。

$ php bin/console doctrine:database:create

4. Book / Reviewエンティティの作成とマイグレーション

まずは開発用にMakerBundleを追加します。

$ composer require symfony/maker-bundle --dev

次に、書籍（Book）とレビュー（Review）のエンティティを作成し、マイグレーションを実行します。

$ php bin/console make:entity
$ php bin/console make:migration 
$ php bin/console doctrine:migrations:migrate

👇️️ エンティティ定義のコード

反映後、/apiにアクセスすると、BookとReviewのエンドポイントが自動生成されていることが確認できます。

次に、実際にBookとReviewのデータをAPI経由で登録してみます。

5. データ登録 (REST API)

生成された/apiエンドポイントに対して、Postmanなどを使ってデータを登録します。

Bookデータを登録するために、以下のように/api/booksにPOSTリクエストを送信します。

{
    "isbn": "978-4-7741-8411-1",
    "title": "ドメイン駆動設計入門",
    "description": "DDDの基礎を学べる書籍です。",
    "author": "山田太郎",
    "publicationDate": "2024-05-01T00:00:00+09:00"
}

Reviewデータの登録も同様に/api/reviewsにPOSTリクエストを行います。

{
    "rating": 5,
    "body": "とても分かりやすい内容でDDDが理解できました！",
    "author": "読者A",
    "publicationDate": "2024-05-10T00:00:00+09:00",
    "book": "/api/books/1"
}

データベースにデータが入っていることが確認できます。

サンプルデータとしてBookとReviewデータをいくつか登録しておきます。

サンプルデータはREADME.mdに記載しておきます。

REST APIが問題なく動作することを確認できたので、ここからは本題であるGraphQLの利用方法を見ていきます。

6. GraphQLの有効化

GraphQLを有効化します。

$ composer require api-platform/graphql

これで/graphqlにアクセスすれば、GraphiQL（GraphQL IDE）が利用可能になります。

7. GraphQLで書籍一覧を取得

API Platformでは、GraphQLエンドポイント（/graphql）が自動で用意されており、ブラウザからGraphiQLを使ってクエリを試すことができます。

まずは、シンプルに書籍の一覧を取得してみます。

query {
  books {
    edges {
      node {
        id
        title
        author
        isbn
        description
        publicationDate
      }
    }
  }
}

このように、GraphQLでは必要なフィールドだけを指定して取得できるのが大きなメリットです。

edges > nodeという構造は、Relay仕様に沿ったページネーション形式です。

👇️️ 結果画面はこんな感じ

8. カスタムフィールド（レビューの平均スコア）を追加

クライアントでレビューを集計するのは手間なので、バックエンドで平均スコアを計算して返すようにします。

📌 Bookエンティティに集計ロジックを追加

#[Groups(['book:read'])]
public function getAverageRating(): ?float
{
    if (!is_iterable($this->reviews) || count($this->reviews) === 0) {
        return null;
    }

    $sum = 0;
    $count = 0;
    foreach ($this->reviews as $review) {
        $sum += $review->rating;
        $count++;
    }

    return $count > 0 ? round($sum / $count, 2) : null;
}

レビューが存在する場合だけ平均を計算し、小数第2位で丸めて返すというシンプルな実装です。

📌 GraphQLでフィールドを有効化する

このaverageRatingをGraphQLのレスポンスに含めるためには、ApiResourceにグループ指定を追加します。

#[ApiResource(normalizationContext: ['groups' => ['book:read']])]

これでGraphQL側でも以下のようなクエリで取得可能になります！

query {
  books {
    edges {
      node {
        title
        averageRating
      }
    }
  }
}

👇️️ 結果画面はこんな感じ

バックエンドで集計処理を済ませておけば、フロント側はaverageRatingをクエリに追加するだけで、すぐに表示できます。

REST APIでも集約済みのデータを1リクエストで取得することは可能ですが、事前に専用のエンドポイントを用意する必要があり画面ごとのデータ要件に応じて設計が増えていきがちです。

その点GraphQLでは、クライアントが欲しい形で柔軟にクエリを定義できるため、バックエンド側は汎用的なスキーマを用意するだけで済みます。

その結果、クライアントは欲しいデータを、欲しい形で取得できるようになり、バックエンド側も汎用的なスキーマ設計だけで済むため、API設計の手間を大きく減らすことができます。

GraphQL のこうした柔軟さは、複雑な画面構成や多様なデータ要件を持つアプリ開発において、特に効果を発揮します。

9. フロント側からデータを取得する

GraphQLの大きな利点のひとつが、「フロントエンドから必要なデータだけを効率的に取得できる」点です。

ここではReact + Apollo Clientを使って、書籍のタイトルと平均スコアを表示するシンプルなUIを作ってみます。

GraphQLクエリの定義

const GET_BOOKS = gql`
  query {
    books {
      edges {
        node {
          id
          title
          averageRating
        }
      }
    }
  }
`;

コンポーネント側の実装

import { gql, useQuery } from '@apollo/client';

const BookList = () => {
  const { loading, error, data } = useQuery(GET_BOOKS);

  if (loading) return <p>読み込み中...</p>;
  if (error) return <p>エラー: {error.message}</p>;

  return (
    <ul>
      {data.books.edges.map(({ node }: any) => (
        <li key={node.id}>
          {node.title} - 平均スコア: {node.averageRating ?? '評価なし'}
        </li>
      ))}
    </ul>
  );
};

export default BookList;

このように、GraphQLクエリを使ってフロント側で必要なフィールドだけを柔軟に取得できます。

バックエンド側でGroups属性によってフィールド公開範囲を調整できるのも、API Platform の便利な点です。

10. まとめ

今回の構成（Symfony + API Platform + GraphQL）を振り返ってみると、こんな強みがありました。

✅ 自動生成：エンティティ定義だけでREST/GraphQL APIを即構築可能
✅ 柔軟性：Groups属性で公開フィールドを制御したり、フロントエンドから必要なデータを自由に取得できる
✅ 効率性：GraphQL により、必要な情報だけを最小限で取得できるため、通信や処理の無駄がない

GraphQLが初めての方でも、API Platformを使えば簡単に構築できます。

特に、データの粒度を調整したい場面や複雑な画面構成を持つSPA開発においては、GraphQLのメリットを最大限に活かせます。

今回は実装中心の紹介でしたが、GraphQLはUIの多様化に柔軟に対応できる強力な選択肢です。

ぜひ一度、試してみてください！

📚️ 参考リンク

Angularリアクティブフォームの型安全な使い方 ─ 罠を避ける実践ポイント | QUARTETCOM TECH BLOG

Fri, 01 Aug 2025 00:00:00 +0900

はじめに

今年に入りチーム編成が変わり、バックエンドエンジニアからフロントエンドやインフラも触ることになりました。詳しくはこちらをご覧ください。

その中でAngular v18環境でのフォーム実装に関わる機会があり、特にリアクティブフォームの「型の付け方」や「構成パターン」で混乱があったので、本記事ではTyped Forms(型付きフォーム)におけるフォームオブジェクトの生成、型推論、および nonNullable の扱いなどを体系的に整理し、より型が安全なフォーム実装に必要な観点をまとめます。

Angularのフォーム構成の方法

Angularにはフォームを作成するための2つの主要な構成方法があります。

公式ドキュメントを見ていただければわかりますがデータフローや入力フィールド数の規模感の違いなどがあり、フォームの構造やロジックの定義箇所、型推論の取り扱いが選定時に特に重要になると感じました。

リアクティブフォーム：フォーム構造・ロジックをTypeScript側で定義する。
テンプレート駆動フォーム：フォーム構造・ロジックをHTMLテンプレート側に記述する。

本記事では、Typed Forms(型付きフォーム)を活かせるリアクティブフォームに焦点を当てて解説します。

リアクティブフォームの構成要素

フォームの実装をする上で良いとされる構成パターンはよく見かけますがなぜいいのかがわからない状態だったので、以下の3つの観点に分けて順に理解していくとわかりやすいと感じたので構成方法や型指定方法の違いによって起きうる危険性も含めて解説していきます。

フォームオブジェクトの作成方法
フォームの型の指定方法
オプション設定

フォームオブジェクトの生成方法

オブジェクトの作成には、主に以下の方法があります。

フォームの基盤となるクラスをnew(インスタンス化)して作成する方法(以下、「ローレベルAPI」)
Angularが提供するユーティリティサービスのFormBuilderを使用して作成する方法

以下にそれぞれのサンプルコードを示し違いを説明します。

他にも深いところで違いがあるんだとは思いますが、個人的にはDIでのテストのしやすさや可読性の点からFormBuilderの方が好みでした。

ローレベルAPIのサンプルコード

フォームの基盤クラスであるFormGroupやFormControlを明示的にインスタンス化してフォームを作成します。

export class UserFormComponent {
    userForm = new FormGroup({
        name: new FormControl(''),
    });
    ...
}

FormBuilderのサンプルコード

FormBuilderを使用してフォームを作成します。

export class UserFormComponent {
    constructor(private fb: FormBuilder) {}
    userForm = this.fb.group({
        name: this.fb.control(''),
    });
    ...
}

フォームの型指定方法

上記で作成したフォームに型を指定する方法として、v14以降に導入されたTyped Forms(型付きフォーム)を使用することでより型安全なフォームの実装が可能になります。

Typed Forms(型付きフォーム)を使っていて最も混乱したのが、開発者が指定した型と型推論の違いでした。型パラメータやNonNullableFormBuilderを使うことでより開発者が明示的に扱う型を宣言することができ、より型安全なフォームの実装が可能になります。ですが、フォームのFormControlがnullを許容するかどうかによって意図しない型推論が行われることがあるので注意が必要です。

以下に分けて解説します。

nullを許容しない場合
nullを意図して許容する場合
nullを意図せず許容してしまっている場合

nullを許容しない場合

nullを許容しない場合は、NonNullableFormBuilderと型パラメータ<T>使うことでシンプルにより型安全なフォームを作成できます。

userForm = this.fb.group({
    name: this.fb.control<string>(""),
});

constructor(private fb: NonNullableFormBuilder) {}

FormGroup<{   
    name: FormControl<string>
}>

明示した通り<string>の型パラメータを指定することで、nullを許容しない型(FormControl<string>)として推論されます。

nullを許容する場合

nullを許容する場合は、以下のようにFormBuilderと型パラメータ<T>を使ってフォームを作成できます。

userForm: FormGroup<{
    name: FormControl<string | null>;
}> = this.fb.group({
    name: this.fb.control<string | null>(""),
});

constructor(private fb: FormBuilder) {}

FormGroup<{
    name: FormControl<string | null>
}>

これは記述通りの型推論になっており、FormControl<string | null>のようにnullを許容する型として推論されます。

nullを意図せず許容してしまっている場合

nullを意図せず許容してしまっている場合は、以下のようにFormBuilderで明示的に<string>の型パラメータを与えているように見えて、内部的なFormControlの仕様によってnullが許容されてしまいます。

userForm: FormGroup<{
    name: FormControl<string>;
}> = this.fb.group({
    name: this.fb.control<string>(""),
});

constructor(private fb: FormBuilder) {}

FormGroup<{
    name: FormControl<string | null>
}>

fb.control<string>で型パラメータを<string>で与えているのでnullは許容されていないように見えますが、AngulerのFormControlの仕様によって、nullが許容されてしまいます。

以下はFormControlの該当するソースコードです。

control<T>(
    formState: T | FormControlState<T>,
    validatorOrOpts?: ValidatorFn | ValidatorFn[] | FormControlOptions | null,
    asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null
): FormControl<T | null>;

control<T>で<T>を型パラメータとして与えても返り値は<T | null>になっていることがわかります。上記のように型パラメータだけではnullが許容されている状態となりコンパイルエラーやバグの原因になります。

これを回避するためにオプション設定を理解しておくことが重要です。

オプション設定

FormControl() や fb.control() では、第2引数として構成オプションを渡すことができます。 nullを許容しないようにするためには、nonNullable: trueオプションを指定します。

nullを意図せず許容してしまっている場合にオプションを追記すると以下のようになります。

userForm = this.fb.group<{
    name: FormControl<string>;
}>({
    name: this.fb.control<string>("", { nonNullable: true }),
});

constructor(private fb: FormBuilder) {
    this.userForm = this.fb.group({
        name: this.fb.control<string>("", { nonNullable: true }),
    });
}

FormGroup<{   
    name: FormControl<string> 
}>

nonNullable: trueを指定することで、返り値のFormControl<T|null>の型がFormControl<T>に変わり、nullを許容しないことで型安全性を高めることができます。

以下はnunNullable: trueを設定した場合のソースコードです。先ほどのnonNullableのオプション設定のないソースコードと比べると、返り値がFormControl<T|null>ではなくFormControl<T>になっていることがわかります。

control<T>(
    formState: T | FormControlState<T>,
    opts: FormControlOptions & {
        nonNullable: true;
    }
): FormControl<T>;

オプションを使うことでnullを許容しないようにすることはできますが、より型安全なフォームを実装したい場合はnullを許容しない場合でフォーム作成をすることで型安全性を高めることができます。

まとめ

リアクティブフォームは柔軟性が高いため設計を曖昧にしたまま進めると、型の不一致や型推論のnullによるバグが発生しやすくなる印象を受けました。そのため最初にフォームオブジェクト+型パラメータ+オプション設定を実装の意図に合わせて組むことが、型安全性とテスト容易性を高めるために重要だと感じました。

本記事では触れませんでしたが、interface で値の型を明示したり、FormBuilder.nonNullable.group() を使ったりすることでも型の安全性を担保できます。またリアクティブフォームに触れる中で、RxJSによる非同期処理やストリームの考え方(Observableのpipe()を使ったオペレーター連結など)も非常に新鮮に感じたのでまた紹介できればと思います。

おまけ

v13以前での型の戻り値

ブログを書く中でわかったことですがv13以前ではFormGroupやFormControlに対して型パラメータ<T>を与えることができず、戻り値はFormGroup<any>と返ってきていたようで完全に型安全にしたい場合は、ngx-typed-formsなどのライブラリを使う必要があったようです。この問題はv14でTypedFormsが公式に導入されたことで解消され、今はFormGroup<T>やFormControl<T>による型安全なフォームが標準機能として扱えるようになっています。詳しくはこちらを参照してください。

プロダクトチーム制への移行とユーザー部門との連携強化に取り組みました！ | QUARTETCOM TECH BLOG

Fri, 27 Jun 2025 00:00:00 +0900

今回は、システム開発部が現在取り組んだ「チーム体制の見直し」と「他部署との連携強化」についてご紹介します。

前提

私たちは大きさの異なるプロダクトや担当業務を合計で約20ほどを開発・運用しています。そのほとんどがいわゆる Web+RDBMS で構成されるアプリケーションですが一部は Node.JS on AWS Lambda だったり Google Apps Script だったりします。

旧体制における課題：職能別チームの状況

これまでのシステム開発部は、PHP、UI、インフラといった職能別の専門チームで構成されていました。各チームは、それぞれの専門分野を担当する数名のメンバーで構成されていました。この体制には、いくつかの課題がありました。

課題例1: チーム間での業務量のばらつき

チームによって担当するタスクの質と量にばらつきが見られました。これにより、メンバー個々の価値提供の機会に偏りが生じ、必ずしも健全とは言えない状況でした。

課題例2: プロダクトオーナーシップの不明確さ

特定のプロダクトに対し、複数の職能チームのメンバーがその都度対応する形となっていました。そのため、各プロダクトを主体的に担当するメンバーやチームが明確ではなく、結果として責任の所在が曖昧になる傾向が見られました。

新体制：プロダクトチーム制への移行

これらの課題に対応するため、私たちは組織体制を「プロダクトチーム制」へと変更しました。

プロダクトチームにはリーダーが置かれ、会社の役職上のマネージャがその職責を担います。（ちなみに各チーム名はシステム開発部の業務で欠かせない Linux のイメージキャラクタであるペンギンの種別から着想を得たものです）
各プロダクトチームには、担当するプロダクトや業務範囲が設定されています。
さらに、各プロダクトや業務範囲に対し、一人の PdM（プロダクトマネージャ）と一人以上のメンバーを明確に割り当てます。

新体制への移行により、各メンバーの権限と責任がより明確になりました。これにより、各プロダクトにおけるメンバーのオーナーシップ意識の醸成にも寄与すると考えています。一方で、従来の職能チーム体制では求められなかった、より幅広いスキルセットが各メンバーに求められるようになっています。これは、メンバー一人ひとりが専門分野を超えて成長していくことを前提としており、個人のスキル向上とキャリア形成の一助となると考えています。

新体制への過程：部門内での検討

今回のプロダクトチーム制への移行は、慎重かつ綿密な検討を重ねて行われました。私たちは、どのようなチーム構成が適切か、また各プロダクトをどのチームが担当すべきかについて、適宜さまざまな座組で複数回にわたり検討を行いました。
最終段階ではメンバー全員による複数回の協議を実施し、結論を出すための最終協議はリモートワークメンバーも含め、全員が出社して対面で意見を交換しました。忌憚のない、お互いを尊重するコミュニケーションを通じて、結論を導き出しました。検討過程でのコミュニケーションは、「変更されたチーム体制」という成果物以上に、メンバーの相互理解を深め、関係を醸成するという価値を提供してくれるものでした。この変革は、部長である私から部のメンバーに提起したものですが、各メンバーの建設的で主体的な姿勢があったことで実現できたものと認識しています。大変感謝しています！

ユーザー部門との連携強化：システム開発における共創

私たちが開発するプロダクトやタスクの大部分は、他部署の業務効率化やサポートを目的としています。そこで、ユーザー部門の従業員にもより明確なオーナーシップを持ってもらえるよう、新たな連携の枠組みを構築し始めています。
その端緒として、私からシステム開発におけるユーザー部門の従業員の関与の重要性を共有し、各プロダクトに一人の PO（プロダクトオーナー）の設定を依頼しました。
システム開発部の PdM とユーザー部門の PO が一般的に呼称される役割に限定せず、それぞれの役割を適切に協議し設定することで、プロダクトがユーザーの課題を的確に解決し、さらに効果的に利用されることを目指します。

今後の展望

プロダクトチーム制への移行とユーザー部門との連携強化は、システム開発部がより柔軟で、かつ責任を持った組織へと発展するための重要な一歩となります。この変革を通じて、私たちは今後も事業が高品質なサービスを提供するためのシステムを支えていきます！

QUARTETCOM TECH BLOG

JavaScript の Temporal 入門 | QUARTETCOM TECH BLOG

目次

ざっくり読みたい方向け（所要時間 5 分）

じっくり読みたい方向け（所要時間 15 分）

1章） 概要を知る

Temporal 名前空間

Temporal の文字列表現

暦

現在時刻

日付時刻の構成要素を表すクラス

特定の瞬間を表すクラス

2章） Temporal の日付時刻演算を知る

比較

差分

加算

減算

更新

時間の丸め

Temporal お試し環境

所感 〜関心の分離のトレードオフ〜

ベストプラクティスは誰のためのものか - AWS Copilot CLIからAWS CDKに移行を終えて | QUARTETCOM TECH BLOG

はじめに

📝 目次

1. 「判断の肩代わり」がもたらした運用上の課題

1.1. 構成の制約と、記述パラダイムの断片化

1.2. 抽象化の裏にある挙動の把握

1.3. アプリとインフラの密結合（インフラリポジトリの独立）

2. AWS CDKに移行して変わったこと

3. ベストプラクティスは誰のためのものか

4. おわりに

サーバーサイド計測が必要になった背景 | QUARTETCOM TECH BLOG

はじめに

1. クライアントサイド主体の計測

<img> ピクセルによる送信

JavaScript による送信

2. ブラウザのプライバシー制限

2.1 サードパーティ Cookie のブロック

2.2 JavaScript 発行 Cookie の有効期限制限

3. サーバーサイド計測の必要性＆具体例

例 Google server-side Tag Manager （ SGTM ）

まとめ

reCAPTCHA v3の導入効果とスコアのしきい値の設定方法 | QUARTETCOM TECH BLOG

はじめに

導入前後の新規ユーザー登録におけるスパム登録率の変化

月別スパム登録率の推移

スパム登録リクエスト数の推移

スコアのしきい値の設定方法

1. 公式ドキュメントを参考に初期値を設定

2. Slack通知で初期しきい値を検証

3. しきい値の設定

まとめ

効果測定の観点

しきい値の設定の観点

互換性のないオブジェクトを低コストにコンバートする | QUARTETCOM TECH BLOG

はじめに

問題点: 対応する媒体が増えた時にコードが膨れ上がる

解決策: Mapper を抽象オブジェクトに依存させ、汎用的に扱えるようにする

数値で比較した場合

ビフォー

アフター

この設計のメリット & デメリット

メリット

デメリット

実装例

まとめ

感想

宣言的記述とメンタルモデル ── AWS Copilot CLI のサポート終了に寄せて | QUARTETCOM TECH BLOG

きっかけ

宣言的記述と手続き的記述

CloudFormation・Copilot・CDK を並べてみる

AWS CloudFormation

AWS Copilot CLI

AWS CDK

三者に共通する事実と、それでも違うこと

Copilot が肩代わりしていたもの

おわりに

Symfonyの.envファイルをうっかり git プッシュから守る方法 | QUARTETCOM TECH BLOG

はじめに

.env.local を git で追跡しない：.gitignore

1章）概要を知る

所感〜関心の分離のトレードオフ〜

`<img>` ピクセルによる送信

2. 初期設定: `/init` と `CLAUDE.md`

プロジェクトの「記憶」を作る `/init`

3. うまく伝わらない時は？コンテキスト管理のコツ

基本は `/clear` でリセット

コンテキストを残したいなら `/compact`