Seu Dev Notes

f-string の書式指定まとめ（桁揃え・ゼロ埋め・日付）

Mon, 03 Aug 2026 00:00:00 GMT

f-string で値を埋め込むだけなら f"{name}" で済みます。困るのは : から先です。桁を揃えたい、ゼロ埋めしたい、カンマを入れたい。そのたびにドキュメントを開き直している気がしたので、実際に使う 5 パターンに絞って手元にまとめました。

: の後ろは書式指定ミニ言語と呼ばれる独自の文法で、並びはこうなっています。

{値:[fill][align][sign][#][0][width][,][.precision][type]}

全部覚える必要はありません。実際に手が動くのは以下の 5 つです。

1. 桁揃え

< が左寄せ、> が右寄せ、^ が中央寄せ。数字は幅です。

print(f"|{'Leão':<10}|")
print(f"|{'Leão':>10}|")
print(f"|{'Leão':^10}|")

|Leão      |
|      Leão|
|   Leão   |

寄せ方を省略したときの既定は型によって違い、文字列は左寄せ、数値は右寄せです。

print(f"|{'Leão':10}|")
print(f"|{9:10}|")

|Leão      |
|         9|

寄せ方の前に文字を 1 つ置くと、空白の代わりにその文字で埋めます。

print(f"{'Leão':.<10}")
print(f"{42:*^9}")

Leão......
***42****

この埋め文字は寄せ方とセットでしか書けません。f"{42:*9}" のように寄せ方を省くと、* が埋め文字だと解釈されず ValueError: Invalid format specifier になります。.< や *^ のように必ず 2 文字で書いてください。

2. ゼロ埋め

幅の前に 0 を置くとゼロ埋めになります。

print(f"{7:03d}")
print(f"{-42:05d}")
print(f"{3.5:06.2f}")

007
-0042
003.50

-42 が -0042 になっているとおり、この 0 は符号を残したまま桁だけ埋めます。前章の埋め文字は符号より外側に入る（f"{-42:.>5}" は ..-42）ので、数値として桁を揃えたいときはこちらを使います。

3. カンマ区切り

, を入れると 3 桁区切り、_ ならアンダースコア区切りになります。

print(f"{1234567:,}")
print(f"{1234567:_}")

1,234,567
1_234_567

幅・区切り・精度は同時に指定できます。並び順は幅 → 区切り → 精度です。

print(f"{1234567.891:>14,.2f}")

  1,234,567.89

4. 小数の桁数

.2f で小数第 2 位まで。% を使うと 100 倍して % を付けてくれるので、率の表示で便利です。

print(f"{2/3:.2f}")
print(f"{0.4567:.1%}")
print(f"{123456:.3g}")

0.67
45.7%
1.23e+05

g は有効数字での指定で、大きすぎる/小さすぎる値は指数表記に切り替わります。

:::caution .2f は四捨五入とは別の規則で丸めます。しかも直感から外れる理由が 2 つあります。

print(f"{0.125:.2f}")
print(f"{2.675:.2f}")

0.12
2.67

0.125 は 1/8 なので 2 進数で正確に表せます。これはちょうど半分の値なので、偶数側に寄せる規則（偶数丸め）が働いて 0.12 になります。

一方 2.675 は 2 進数で正確に表せず、内部では 2.674999... を持っています。半分に届いていないので単に切り捨てられただけで、偶数丸めは関係ありません。「半分の値は偶数側」という規則だけを覚えていると、2.68 を期待して外します。

金額を扱ったことはまだないので受け売りです。丸め方を厳密に決めたい場面では、表示側で調整せず decimal.Decimal で丸めてから渡すのが一般的なやり方とされています。 :::

5. 日付

datetime を渡したときの : 以降は、ここまでの書式ミニ言語ではなく strftime の書式がそのまま使えます。

from datetime import datetime

d = datetime(2026, 8, 3, 21, 5)
print(f"{d:%Y-%m-%d}")
print(f"{d:%Y/%m/%d %H:%M}")
print(f"{d:%m/%d(%a)}")

2026-08-03
2026/08/03 21:05
08/03(Mon)

d.strftime("%Y-%m-%d") と結果は同じですが、f-string の中に直接書けるぶん読みやすくなります。オブジェクトごとに : 以降の解釈を変えられる仕組みなので、自作クラスでも __format__ を定義すれば同じことができます。

組み合わせると表になる

5 つを覚えると、ログや確認用の出力を整形するのが一気に楽になります。

rows = [("Rafael Leão", 9, 1.234), ("Christian Pulisic", 8, 0.87), ("Adrien Rabiot", 6, 12.5)]
for name, goals, xg in rows:
    print(f"{name:<20}{goals:>3}{xg:>8.2f}")

Rafael Leão           9    1.23
Christian Pulisic     8    0.87
Adrien Rabiot         6   12.50

:::caution この方法は日本語を混ぜると崩れます。

print(f"{'レオン':<10}|")
print(f"{'Leão':<10}|")

レオン       |
Leão      |

幅指定が数えているのは文字数であって表示幅ではないためです。レオン は 3 文字なので、残り 7 個ぶんの空白が入ります。ただし全角は 1 文字で 2 列ぶんの見た目を取るため、等幅フォントで並べたときに端が揃いません。

自力で揃えるなら unicodedata.east_asian_width で 1 文字ずつ列数を数えてパディングします。表の整形が目的なら tabulate のようなライブラリに任せるほうが早いです。 :::

幅を変数で渡したいときは、幅の部分をさらに {} で囲めます。

w = 8
print(f"{3.14159:>{w}.3f}")

   3.142

おまけ: デバッグ用の `=`

Python 3.8 以降では、式の後ろに = を置くと式そのものと値を一緒に出してくれます。書式指定と併用もできます。

xg = 1.2345
print(f"{xg=}")
print(f"{xg = :.2f}")

xg=1.2345
xg = 1.23

print("xg =", xg) と書く手間がなくなるので、値を覗きたいだけの場面はこれで足ります。

まとめ

覚えるのは並び順だけです。埋め文字 → 寄せ → 幅 → 区切り → 精度 → 型。{:>10,.2f} を「右寄せ・幅 10・カンマ区切り・小数 2 桁・浮動小数点」、{:*^9} を「* で埋めて・中央寄せ・幅 9」と読み下せるようになれば、あとは必要な部分を足し引きするだけで済みます。

Pandas で and が使えず & が要る理由

Sun, 02 Aug 2026 00:00:00 GMT

Understat から取ってきたセリエAの選手データで「ミランの選手」かつ「5 得点以上」を絞り込もうとして、素直にこう書きました。

df[df["team_title"] == "AC Milan" and df["goals"] >= 5]

ValueError: The truth value of a Series is ambiguous.
Use a.empty, a.bool(), a.item(), a.any() or a.all().

and は「全体で 1 つ」を求める

Python の and は、左右のオブジェクトを真偽値 1 つに変換してから判定します。ところが df["team_title"] == "AC Milan" が返すのは 行数と同じ長さの bool の Series で、真偽値 1 つではありません。

print(df["team_title"] == "AC Milan")

0      False
1      False
2      False
       ...
585    False
Name: team_title, Length: 586, dtype: bool

586 行ぶんの True/False が並んだこれを、and は「Yes か No のどちらか 1 つ」に決めようとします。1 つでも True があれば True なのか、全部 True でなければ False なのか。決めようがないので Pandas は判断を拒否し、ambiguous（あいまい）だと言ってきます。エラーメッセージが a.any() や a.all() を勧めてくるのは、「全体で 1 つにまとめるならどちらの意味か明示しろ」ということです。

& は「行ごとに 1 つ」

一方、こちらが本当にやりたいのは 1 行ずつ「両方の条件を満たすか」を判定する ことで、全体を 1 つにまとめることではありません。それをやるのが & です。

df[(df["team_title"] == "AC Milan") & (df["goals"] >= 5)]

       player_name team_title position  goals
       Rafael Leão   AC Milan      F S      9
 Christian Pulisic   AC Milan      F S      8
Christopher Nkunku   AC Milan      F S      7
     Adrien Rabiot   AC Milan      M S      6
Strahinja Pavlovic   AC Milan      D S      5

& は 2 つの bool Series を要素ごとに比較し、結果もまた bool の Series で返します。df[...] はそれを行の選択に使います。or に対応するのが |、not に対応するのが ~ で、対応関係は同じです。

なお各条件を丸カッコで囲んでいるのは飾りではありません。& は == や >= より結合が強いため、囲まないと意図と違う順序で評価されます。

まとめ

& は and とはそもそも別の演算で、代替品ではありません。and が「まとめて 1 つの答え」を出すのに対し、& は「行ごとに答え」を出します。Pandas の絞り込みで欲しいのは常に後者です。

データの取得元については Pythonでサッカー分析を学ぼうとしたら、無料のxGが消えていたに書きました。

Pythonでサッカー分析を学ぼうとしたら、無料のxGが消えていた

Sat, 01 Aug 2026 00:00:00 GMT

Python の学習として、好きなサッカークラブの試合データを触るところから始めようと思いました。
日本語・英語を問わず入門記事はたくさんあります。ところが、そのほとんどが前提にしているデータソースが、いま動きません。

FBref の高度スタッツが 2026年1月に丸ごと消えたためです。xG（Expected Goals）をはじめとする、いわゆる「サッカー分析らしい指標」がまとめて無くなりました。半年後に学習を始めて入り口で足止めを食らった側から、いま何が使えるのかを実際に取得して確かめた記録です。

:::tip 記事中のコードをまとめて実行できる ノートブックを用意しました。Google Colabで動くため、追加インストールなしで上から流すだけで動きます。

Google Colab で開く（ソース: c12o-dev/notebooks）

リンクを開いてそのまま実行できます。所要 1〜2 分ほどです。 :::

2026年1月20日に何が起きたか

一次ソースは Sports Reference の公式ブログ FBref & Stathead Data Update（2026年1月20日）です。要点はこの一文に尽きます。

last week the provider of our advanced soccer data sent us a letter terminating our access to their data feeds and requiring the deletion of their data from the site immediately.

データ提供元から契約終了とデータ削除を通告され、従うほかなかった、という説明です。注意したいのは、この公式ブログ記事が提供元を名指ししていない ことです。コミュニティでは Opta（Stats Perform）だと受け止められていますが、公式声明にその名前は出てきません。

確かなのは次の事実です。その 8 日前の 2026年1月12日に、Stats Perform が FIFA の公式ベッティングデータ・ストリーミング配信権の独占ディストリビューターに決まったと発表されています。因果関係が公表されているわけではないので、並んだ事実として置いておきます。

半年後の今も戻っていない

この記事のメインはここです。1月時点の記事は「消えた」までしか書いていません。2026年8月の今はどうなのかを確かめます。

FBref は現在ボット対策が入っていて、curl や自動取得ツールからは 403 が返ります。そこで Internet Archive に残っている 2026年7月31日のスナップショットで、欧州5大リーグのシュート系スタッツ一覧のテーブル列を確認しました。

import re
import requests

URL = ("https://web.archive.org/web/20260731082148/"
       "https://fbref.com/en/comps/Big5/shooting/players/Big-5-European-Leagues-Stats")
html = requests.get(URL, timeout=60).text
print(sorted(set(re.findall(r'data-stat="([a-z_0-9]+)"', html))))

返ってきた列は goals / shots / shots_on_target / shots_on_target_pct / goals_per_shot / pens_made といった基礎スタッツだけでした。xg、npxg に相当する列は 1 つも残っていません。半年経っても、シュート数は取れるが xG は取れない状態が続いているということです。

どこまで消えたかは PK 関連を見るとはっきりします。PK の試投数・成功数（pens_att / pens_made）は残っている一方で、PK を除いた期待得点である npxg は消えています。試合で数えられる事実は残り、モデルで推定した値だけが抜けたという消え方です。

公式ブログも、将来の高度データについてこう書いています。

if we present advanced data in the future it will certainly have a dramatically smaller scale.

戻るとしても以前の規模ではない、という前提で組んだほうがよさそうです。

:::note FBref そのものが使えなくなったわけではありません。100 以上の大会にわたる試合結果・出場時間・得点といった基礎データは今も健在で、歴史データの参照先としては引き続き有力です。消えたのは xG などの高度スタッツだけです。 :::

代替を実際に叩いて確かめた

「代替はこれ」と列挙している記事は増えましたが、リンクを並べただけのものも多いので、学習で使う前提の 3 つを実際に取得しました。以下はすべて 2026年8月上旬時点で動作を確認したものです。

Understat —— xG が要るならまずここ

Understat は欧州5大リーグの xG を独自モデルで公開しているサイトで、選手単位の xG / npxG / xA / xGChain / xGBuildup が取れます。FBref で取れなくなった指標を補う第一候補です。

ただし、注意点があります。日本語の入門記事の多くが書いている「HTML に埋め込まれた var playersData = JSON.parse('...') を正規表現で抜く」方法は、もう通りません。 現在の Understat はページ読み込み後に XHR でデータを取りに行く作りに変わっていて、HTML 側には該当の変数が存在しないためです。

代わりに、ページ自身が叩いているエンドポイントを使います。

import pandas as pd
import requests

LEAGUE, SEASON = "Serie_A", "2025"
res = requests.get(
    f"https://understat.com/getLeagueData/{LEAGUE}/{SEASON}",
    headers={
        "User-Agent": "Mozilla/5.0",
        "X-Requested-With": "XMLHttpRequest",
        "Referer": f"https://understat.com/league/{LEAGUE}/{SEASON}",
    },
    timeout=30,
)
df = pd.DataFrame(res.json()["players"])
print(df.columns.tolist())

['id', 'player_name', 'games', 'time', 'goals', 'xG', 'assists', 'xA',
 'shots', 'key_passes', 'yellow_cards', 'red_cards', 'position',
 'team_title', 'npg', 'npxG', 'xGChain', 'xGBuildup']

列は揃っていますが、このエンドポイントは数値もすべて文字列で返します。 goals が "17"、xG が "17.13883000984788" という具合です。気づかずに df["goals"].sum() とすると足し算ではなく文字列連結になるので、pd.to_numeric() を通してから使ってください。

セリエA 2025/26 で 586 行。ミランの xG 上位はこうなりました。

       player_name games time goals    xG assists    xA
Christopher Nkunku    32 1343     7  9.94       3  1.61
       Rafael Leão    29 1874     9  9.60       3  4.98
 Christian Pulisic    30 1612     8  9.54       4  5.04
   Youssouf Fofana    33 2231     2  4.59       3  3.64
     Adrien Rabiot    29 2546     6  4.36       4  3.94

:::caution このエンドポイントは公式に文書化されていないので、いつ変わってもおかしくありません。実際、HTML 埋め込み方式が消えたのが良い例です。学習用途でも取得間隔は空けて、一度取ったものはローカルに保存して使い回してください。

なお Understat の robots.txt は User-agent: * / Disallow: / で、自動アクセスを許可していません。ライブラリ経由でも同じことなので、負荷をかけない範囲での利用にとどめてください。 :::

自分でリクエストを組みたくない場合は、soccerdata が Understat を含む複数サイトのスクレイパーをまとめてくれています。キャッシュも面倒を見てくれるので、学習目的ならこちらのほうが安全です。

StatsBomb Open Data —— イベント単位で学ぶなら

StatsBomb Open Data は、パス・シュート・タックルといったイベント 1 件ずつが JSON で公開されている無料データセットです。GitHub の raw ファイルなので、ボット対策も認証もありません。

BASE = "https://raw.githubusercontent.com/statsbomb/open-data/master/data"

events = requests.get(f"{BASE}/events/3773386.json", timeout=60).json()
shots = [e for e in events if e["type"]["name"] == "Shot"]
print(len(events), len(shots), shots[0]["shot"]["statsbomb_xg"])  # 3891 29 0.201

1 試合が 3,891 イベント、うちシュート 29 本。各シュートに statsbomb_xg が入っており、シュート時点の全選手位置（freeze_frame）まで付いてきます。収録は 80 コンペティション。ただし最新シーズンを網羅的に追う用途には向きません。ワールドカップやメッシのキャリア全試合など、公開範囲が限定されているためです。

利用条件も明快で、README は「分析や考察を公開するときは出典を StatsBomb と明示すること」だけを求めています。

football-data.co.uk —— xG はないが手軽

football-data.co.uk はリーグ・シーズンごとの CSV を直接置いてくれています。pandas の 1 行で読めるのが強みです。

df = pd.read_csv("https://www.football-data.co.uk/mmz4281/2526/I1.csv")
print(df.shape)                                        # (380, 131)
print([c for c in df.columns if "xg" in c.lower()])    # []

380 試合 × 131 列。ただし中身は結果・シュート数・カード数と、大量のブックメーカーオッズです。xG は入っていません。 前処理や結合の練習台としては手軽ですが、xG を扱いたいなら別のソースが要ります。

学習目的ならどう組むか

3 つ触ったうえでの結論です。

公開・再配布まで考えるなら StatsBomb Open Data と football-data.co.uk。 この 2 つは利用条件がはっきりしています（StatsBomb は出典明示を求めるのみ、football-data.co.uk は robots.txt で自動アクセスを許可）。分析結果を記事や成果物として出す前提なら、こちらを使うのが安全です。

xG を使いたいなら Understat を主軸にする。 シーズン単位・選手単位で xG が揃う無料ソースとして、現状これが最も実用的です。ただし上のとおり自動アクセスは許可されていないので、手元の学習にとどめ、エンドポイントの変更に備えて取得と分析のコードは分けておきます。

取得したデータは必ずローカルに保存する。 毎回リクエストを投げる書き方は、相手への負荷も自分の試行錯誤の速度も悪くします。一度 CSV か Parquet に落として、以降はそれを読みます。

イベントデータの練習は StatsBomb Open Data で。 「シュート 1 本ごとの位置と xG」を扱う経験は、集計済みのテーブルからは得られません。対象大会は限られますが、学ぶだけなら十分です。

入門記事は 2026年1月より前かどうかを最初に見る。 それ以前の記事は FBref に高度スタッツがある前提で書かれています。手順が動かないのは自分のせいではないので、データソースの節だけ読み替えて進めます。

まとめ

「FBref を叩けば全部ある」時代は終わりました。無料で xG が手に入る時代が終わったわけではありません。手順どおりにやって動かないときは、コードではなくデータソースのほうを確認してください。

次は、ここで取ってきた Understat のデータを実際に pandas で触っていきます。手始めに、絞り込みで最初につまずく Pandas で and が使えず & が要る理由を書きました。

指でなぞると凍る画像モザイク——端末内完結のプライバシー PWA を作った

Wed, 17 Jun 2026 00:00:00 GMT

SNS や記事に写真・スクリーンショットを載せるとき、顔や住所、名前や番号など「ここだけは隠したい」部分が出てきます。選択肢は、手元の標準機能で黒塗りするか、Web の目隠しツールに画像をアップロードするかです。ただし後者は、隠したい画像をわざわざ外部サーバーに送ることになります。

それが気持ち悪かったので、全処理が端末内で完結する画像モザイク PWA「Frost（frost-mosaic）」 を作って公開しました。指でなぞった場所が氷霜に覆われて見えなくなる、という小さなツールです。

ライブ: frost.c12o.net
すぐ試す: frost.c12o.net/app?sample=1（同梱のサンプル画像で挙動を確認できます）

::github{repo="c12o-dev/frost-mosaic"}

:::photosm{title="なぞった場所から氷霜が広がる（架空のサンプル画像）"} :::

なぜ作ったか

出発点は、個人的な不満と「作ってみたい」が半分ずつでした。

既存の Web ツールのセキュリティが気になった: 隠したい情報を含む画像を、見ず知らずの Web サービスにアップロードするのが不安だった。
アプリを入れるのも手間: そのためだけにネイティブアプリをインストールするのは面倒で、ブラウザだけで終わらせたい。
すりガラスの質感を使ってみたかった: 確実に塗りつぶすだけでなく、すりガラス（フロストガラス）のような半透明の質感で隠す表現を一度作ってみたかった。

事前に調べた範囲では、ブラウザ完結の画像 redaction（目隠し）ツールは矩形や楕円で領域を選ぶものが主流で、指でなぞるブラシ式は見当たりませんでした。だったら作ろう、というのがきっかけです。

何ができるのか

やることは単純で、画像を読み込み、隠したい場所を指でなぞるだけです。なぞった軌跡に沿って、その下の画像が加工面に置き換わります。

加工の見せ方が「氷霜ガラス」です。なぞった所から霜が結晶化して広がり、対象を覆う見せ方です。黒塗りやモザイクのような無機質な遮蔽ではなく、冬の窓に降りる霜のような質感で隠します。隠蔽の実体はモザイクとぼかしが担い、氷霜はその上に乗るレイヤーなので、「凍らせる＝隠す」という比喩と機能の向きは一致しています。見た目の演出が目的を曖昧にしないよう、比喩と機能の向きを揃えました。

実際に、架空のサンプル会員証で氏名・住所・電話番号を隠すとこうなります。

:::photo{title="加工前：架空のサンプル会員証"} :::

:::photo{title="加工後：氏名・住所・電話番号を氷霜で覆った状態"} :::

端末の外に画像を出さない

このツールの核は「画像が端末の外に出ない」ことです。主張だけでなく、実装の構造でそうなるようにしています。

送らない: 読み込みは FileReader で行い、加工は Canvas 2D 上で完結します。画像をサーバーへ送信する処理を持たない作りです。
EXIF / GPS が落ちる: 保存は canvas.toBlob('image/png') で再エンコードします。そのため元画像に含まれていた撮影日時や位置情報などのメタデータは出力に残りません。
キャッシュしない: オフライン動作のために Service Worker でアプリ本体（HTML・JS・CSS など）はキャッシュします。ただし ユーザーが読み込んだ画像はキャッシュ対象に含めていません。

「ローカルで処理します」と書くだけなら簡単です。送らない・キャッシュしない・再エンコードで EXIF を落とす、という動作を実装に織り込んで主張を裏打ちしています。この設計の詳細は別記事で掘り下げる予定です。

使い方は「読み込んで、なぞって、保存」

操作の流れはこれだけです。

画像を読み込む（ファイル選択、または空状態の枠をタップ）
隠したい場所を指でなぞる
必要ならスライダーで調整する
保存する

調整できるのは 4 つのスライダーです。

スライダー	範囲	役割
粗さ	6–48px	モザイクのブロックの大きさ
ぼかし	0–14px	加工面のぼかし量
氷霜	0–100%	霜レイヤーの濃さ
ブラシ	10–90px	なぞる円の太さ

直近のストロークの取消と全消去もできます。長い縦長スクショなどは、2 本指でズーム・パンして拡大すれば細部も塗れます（1 本指は描画、2 本指がズーム・パンです）。

保存すると <元画像名>_<モード>.png（例: IMG_1234_frost.png）という名前の PNG が得られます。iOS では共有シート経由、Android やデスクトップでは直接ダウンロードと、環境に合わせて保存方法を出し分けています。

モザイクと氷霜ガラスの 2 モード

隠し方は 2 モードあります。

モザイク: 縮小→拡大によるブロック化。昔ながらの素直なモザイクです。
氷霜ガラス: モザイクを下地に、ぼかしとガラス質感、霜レイヤーを重ねたモード。

同じ会員証を、それぞれのモードで隠すと印象が変わります。

::::photorow :::photosm{title="モザイクモード：ブロック状に粗くする"} :::

:::photosm{title="氷霜ガラスモード：霜の質感で覆う"} ::: ::::

氷霜スライダーを 0 にすると霜レイヤーは消え、モザイク＋ぼかしだけが残ります。きっちり隠したい場面と、雰囲気を保ったまま隠したい場面で使い分けられます。

インストール不要、オフラインでも動く

Frost は PWA（プログレッシブ Web アプリ）です。ブラウザで開けばそのまま使えますし、ホーム画面に追加すればアプリのように起動し、2 回目以降はオフラインでも動きます。アプリ本体はランタイム依存ライブラリゼロの素の TypeScript で書いていて、ツール本体のバンドルは gzip で約 5KB と軽量です。

まずサンプルで試す

自分の画像を選ばなくても、frost.c12o.net/app?sample=1 を開くと同梱のサンプル画像が端末内で読み込まれ、なぞる・調整する・保存するの一連をそのまま試せます。

ソースは MIT ライセンスで公開しています。実装の詳しい話はそれぞれ別記事にまとめていきます。Canvas を 4 枚合成してマスク描画する仕組み、保存の方法を iOS と Android / デスクトップで出し分けた話、ズーム時に座標がずれない工夫などです。

Go の RE2 でストリーミングフィルタを安全に書く

Tue, 21 Apr 2026 00:00:00 GMT

はじめに

Go 標準の regexp パッケージは RE2 実装をベースにしており、正規表現の実行時間が入力長に対して線形 であることを保証しています。PCRE 系の実装で起きる ReDoS（Regular expression Denial of Service）の心配がありません。ユーザー入力や外部ログを正規表現で処理する CLI ツールに向いています。

材料は先日公開した mask-pipe の実装です。Go でストリーミングフィルタを書くときに押さえておきたい点を、そこから拾い出します。

RE2 が線形時間である理由

PCRE 系のバックトラッキング実装は (a+)+$ のようなネスト量化子で指数的に遅くなります。RE2 は NFA/DFA ベースの実装で、バックトラックを原理的に行わないため入力長 N に対して O(N) で済みます。

代償としてバックリファレンス（\1、\2）やルックアラウンド（(?=...)、(?!...)）は使えません。Go の regexp も同じ制約です。現場で書く「ユーザー入力をサニタイズしたい」「ログからパターンを抜きたい」用途はほぼすべてこの範囲で収まります。

import "regexp"

var awsKey = regexp.MustCompile(`AKIA[0-9A-Z]{16}`)

func main() {
    fmt.Println(awsKey.MatchString("AKIAIOSFODNN7EXAMPLE")) // true
}

MustCompile はコンパイル失敗時に panic する初期化用関数です。グローバル変数に代入して使い回すのが一般的な使い方で、init() で一度コンパイルすればホットループでの再コンパイルを避けられます。

FindAllStringSubmatchIndex を使うパターン

マスクや置換を行う場合、単に「マッチするか」だけでは足りず、マッチ位置のインデックス が必要です。FindAllStringSubmatchIndex は各マッチの開始・終了位置を []int で返します。

pattern := regexp.MustCompile(`sk_(live|test)_[A-Za-z0-9]{24}`)
line := "key=sk_live_abcdef0123456789abcdef01"

matches := pattern.FindAllStringSubmatchIndex(line, -1)
for _, m := range matches {
    start, end := m[0], m[1]
    fmt.Printf("match at [%d:%d] = %q\n", start, end, line[start:end])
}

返り値は [全体開始, 全体終了, グループ1開始, グループ1終了, ...] の繰り返しです。位置が取れれば、前後の文字列を残したまま任意のマスク文字列に置き換えられます。

func mask(line string, re *regexp.Regexp) string {
    var b strings.Builder
    last := 0
    for _, m := range re.FindAllStringSubmatchIndex(line, -1) {
        b.WriteString(line[last:m[0]])
        b.WriteString("[REDACTED]")
        last = m[1]
    }
    b.WriteString(line[last:])
    return b.String()
}

strings.Builder を使うと中間文字列のアロケーションが抑えられ、1 秒に数千行流れるログでも十分な速度が出ます。

bufio.Scanner で行単位に流す

ストリーミングフィルタの基本形は bufio.Scanner です。標準入力を 1 行ずつ読み、フィルタをかけて標準出力に書き戻します。

func main() {
    scanner := bufio.NewScanner(os.Stdin)
    writer := bufio.NewWriter(os.Stdout)
    defer writer.Flush()

    for scanner.Scan() {
        masked := mask(scanner.Text(), awsKey)
        fmt.Fprintln(writer, masked)
    }
    if err := scanner.Err(); err != nil {
        fmt.Fprintln(os.Stderr, "scan error:", err)
        os.Exit(1)
    }
}

bufio.Scanner はデフォルトで最大トークンサイズ（bufio.MaxScanTokenSize = 64 KB）までしか読めず、それを超える長い行があると bufio.ErrTooLong で停止します。初期バッファは小さく、長い行を読むたびにこの上限まで自動的に伸びる仕組みです。ログが長い場合は scanner.Buffer で上限を引き上げます。

scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)

初期容量と最大容量を個別に指定できます。必要以上に大きくするとメモリ使用量が跳ねるので、ワークロードに合わせて決めます。

複数パターンをまとめて適用する

mask-pipe では AWS / GitHub / Stripe など複数の既定パターンを同時に適用します。素朴には各パターンで FindAllStringSubmatchIndex を呼ぶのが正しく、パイプ | で連結した巨大な正規表現を作らない のが安全策です。

:::caution[巨大な OR 結合は避ける] パターンを (?:pat1|pat2|pat3|...) で結合すると、グループ番号の管理が複雑になり、パターン追加時の影響範囲も広がります。RE2 上でも DFA の状態数が膨れてコンパイル時間が伸びます。各パターンを独立に扱い、マッチ区間のマージだけ後処理する方が保守しやすい構成です。 :::

マッチ区間は互いに重なりうるので、全パターンのマッチ位置を集めてから左から右にマージします。

type span struct{ start, end int }

func merge(spans []span) []span {
    sort.Slice(spans, func(i, j int) bool { return spans[i].start < spans[j].start })
    out := spans[:0]
    for _, s := range spans {
        if len(out) == 0 || s.start > out[len(out)-1].end {
            out = append(out, s)
        } else if s.end > out[len(out)-1].end {
            out[len(out)-1].end = s.end
        }
    }
    return out
}

これで重複しない区間リストが得られ、置換が予測可能になります。

マルチライン対応のバッファリング

PEM 秘密鍵のように複数行にまたがるブロックは行単位のフィルタでは検出できません。行単位を基本にしつつ、特定のマーカーで始まったら終端マーカーが来るまでバッファリングする方式が現実的です。

var inBlock bool
var buf []string

for scanner.Scan() {
    line := scanner.Text()
    switch {
    case strings.Contains(line, "-----BEGIN"):
        inBlock = true
        buf = append(buf, line)
    case inBlock:
        buf = append(buf, line)
        if strings.Contains(line, "-----END") {
            fmt.Fprintln(writer, "[REDACTED PRIVATE KEY]")
            buf = nil
            inBlock = false
        }
    default:
        fmt.Fprintln(writer, mask(line, awsKey))
    }
}

運用上のセーフティネットとして「バッファが一定サイズを超えたら fail-open でそのまま流す」動作にしておくと、異常な入力でフリーズしません。mask-pipe では 100 行または 64 KB を上限にしています。

ベンチマークで線形性を確認する

Go の testing パッケージで計算量を手触りレベルで検証できます。

func BenchmarkMask_1KB(b *testing.B)  { benchMask(b, 1024) }
func BenchmarkMask_10KB(b *testing.B) { benchMask(b, 10*1024) }
func BenchmarkMask_100KB(b *testing.B){ benchMask(b, 100*1024) }

func benchMask(b *testing.B, n int) {
    input := strings.Repeat("a AKIAIOSFODNN7EXAMPLE ", n/23)
    b.SetBytes(int64(len(input)))
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        _ = mask(input, awsKey)
    }
}

go test -bench=. -benchmem で実行すると、入力サイズに比例してナノ秒が増えることを確認できます。指数的に伸びないのが RE2 の健全性の証拠です。

まとめ

Go の regexp は RE2 ベースで ReDoS の心配がなく、CLI のストリーミングフィルタに適している
FindAllStringSubmatchIndex でマッチ位置を取り、strings.Builder で置換を組み立てる
複数パターンは OR 結合せず、独立に評価して区間マージする
マルチライン検出は行バッファ + 上限付き fail-open で安全に実装する

実装例は mask-pipe のコードが参考になります。ストリーミング前提で RE2 を使う場合、パターン設計と区間マージを分離しておくと後からパターンを足すのが楽になります。

Cloudflare Workers とは何か：エッジ実行環境の基礎

Mon, 20 Apr 2026 00:00:00 GMT

はじめに

Cloudflare Workers は Cloudflare のエッジネットワーク上でコードを実行できるサーバーレス環境です。世界 300 以上の都市に配置されたデータセンターで、ユーザーに最も近い拠点から関数が応答します。

「AWS Lambda のエッジ版」と紹介されることが多いですが、ランタイムモデルと起動オーバーヘッドが根本的に異なります。

Pages との使い分けを先に知りたい方は Cloudflare Pages と Workers の違いと使い分けを参照してください。Pages 単体の入門は Cloudflare Pages とは何かにあります。

V8 Isolate モデル

Workers は Chrome と同じ V8 JavaScript エンジンの Isolate という単位で動き、Node.js でも Deno でもありません。Isolate は V8 が提供する軽量なサンドボックスで、1 つのプロセス内に数千個を同居させられます。

AWS Lambda が「リクエストごとに専用のコンテナを起動する」のに対し、Workers は「1 つのプロセスの中で Isolate を切り替える」方式です。結果として以下の特性が生まれます。

項目	Lambda	Workers
起動単位	コンテナ（MB〜GB）	Isolate（数 MB）
コールドスタート	数百 ms〜数秒	0〜5 ms
実行時間制限	最大 15 分（wall-clock）	CPU 時間既定 30 秒／最大 5 分（Paid）
メモリ	〜10 GB	128 MB

Lambda の「15 分」は wall-clock（実時間）の上限です。Workers の「30 秒 / 5 分」は CPU を実際に使った時間 の上限です。HTTP リクエストの wall-clock 自体はクライアント接続中は制限なく、fetch のネットワーク待ちはカウントされません。軸が違う点に注意してください。

Isolate の起動が数ミリ秒で済むため、Workers には実質的なコールドスタートが存在しません。常に「新しい Isolate を立ち上げる」コストで済み、事前ウォームアップが不要です。

リクエストライフサイクル

Workers のコードは fetch ハンドラを export するのが基本形です。

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);
    return new Response(`Hello from ${url.pathname}`);
  },
};

引数は 3 つです。

request: 標準の Request オブジェクト
env: バインド（後述）経由で注入される外部リソース
ctx: waitUntil で非同期処理をレスポンス後に継続させるためのコンテキスト

Node.js の http モジュールや Express のような独自 API はありません。すべて Web 標準の Fetch API です。フロントエンドで fetch() を使っている感覚のまま、サーバー側も書けます。

waitUntil で非同期処理を後回しに

ログ送信やキャッシュ更新など、レスポンスを待たせたくない処理は ctx.waitUntil で実行します。

ctx.waitUntil(sendAnalytics(request));
return new Response("ok");

レスポンスは即座に返りつつ、分析イベントの送信は Worker の実行時間内で継続します。

Bindings で外部リソースを注入する

Workers から他の Cloudflare リソースを使うには バインド を設定します。環境変数のリソース版だと捉えてください。

wrangler.toml（または wrangler.jsonc）で宣言します。

name = "my-worker"
main = "src/index.ts"

[[kv_namespaces]]
binding = "CACHE"
id = "xxxxxxxxxxxx"

[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "yyyyyyyyyyyy"

コード側は env.CACHE や env.DB として型付きで参照できます。

export default {
  async fetch(request, env) {
    const cached = await env.CACHE.get("key");
    if (cached) return new Response(cached);
    const { results } = await env.DB.prepare("SELECT name FROM users").all();
    await env.CACHE.put("key", JSON.stringify(results), { expirationTtl: 60 });
    return Response.json(results);
  },
};

主要なバインド先は以下の通りです。

バインド	用途
KV	グローバル分散の Key-Value ストア。読み込み頻度が高く、書き込みがまれな設定値向け
R2	S3 互換のオブジェクトストレージ。帯域無料
D1	エッジで動く SQLite。小〜中規模のリレーショナルデータに
Queues	メッセージキュー。バッチ処理やリトライ付きジョブに
Durable Objects	キー単位で状態を持てる強整合オブジェクト。WebSocket セッションやカウンタに
Service Bindings	別の Worker を関数のように呼び出す

実行時間とリソース制限

Workers の無料枠では CPU 時間が 1 リクエストあたり 10 ms までです。Paid プラン（$5/月〜）では既定で 30 秒、wrangler.toml の [limits] cpu_ms を設定すれば最大 5 分（300,000 ms）まで引き上げられます。ここで言う CPU 時間は「実際に CPU を使った時間」で、fetch の待ち時間（ネットワーク I/O）は含まれません。

[limits]
cpu_ms = 60000  # 60 秒まで許可

メモリは 128 MB 固定です。重い画像処理や機械学習モデルのロードには向かず、そうした処理は R2 や Workers AI に委ねる構成が推奨されます。

:::tip[Cron Triggers と Scheduled Workers] scheduled ハンドラを export すると、cron 式で定期実行される Worker が作れます。Pages Functions では使えない機能で、バッチ処理や外部 API のポーリングは Workers 単体で組む必要があります。 :::

デプロイ

デプロイは Wrangler CLI で行います。

$ pnpm create cloudflare@latest my-worker
$ cd my-worker
$ pnpm run deploy

wrangler deploy は TypeScript のコンパイル、バンドル、Cloudflare への配信までを一気に行います。デプロイから世界中のエッジに反映されるまで数秒です。

開発中は wrangler dev でローカル実行できます。V8 Isolate を Miniflare で模倣しており、バインドされた KV や D1 もローカルのエミュレータで動きます。

Node.js と何が違うか

Workers は Web 標準 API が中心で、Node.js 固有 API（fs、net など）は使えません。代わりに以下の対応があります。

ファイル I/O: R2 や KV に置き換える
TCP / UDP: connect() API（TCP のみ、制限あり）
Crypto: Web Crypto API 標準
環境変数: env 経由

Node.js 互換性が必要なら nodejs_compat フラグを有効にすると、主要な Node.js API のポリフィルが使えます。ただし express のような「プロセス前提」のフレームワークは動かず、全 API が揃っているわけではありません。Hono のように Web 標準だけで書かれたフレームワークを選ぶのが安全です。

まとめ

Workers は V8 Isolate で動くエッジ実行環境で、コールドスタートがほぼゼロ
fetch ハンドラを export するだけで始められ、API は Web 標準の Fetch API
バインド経由で KV / R2 / D1 / Queues などを型安全に扱える
Node.js 互換 API は限定的。Hono などの Web 標準ベースのフレームワークと相性が良い

次は具体的なユースケースとして API Proxy の構築例を書きます。静的サイトとの組み合わせは Pages と Workers の使い分けを、無料枠の全体像は Cloudflare 無料枠運用ガイドを参照してください。

Cloudflare Pages とは何か：静的サイトホスティングの実力

Sun, 19 Apr 2026 00:00:00 GMT

はじめに

Cloudflare Pages は Cloudflare が提供する静的サイトホスティングサービスです。GitHub や GitLab のリポジトリと連携し、push するだけで自動ビルド・デプロイが実行されます。

Vercel や Netlify と同じカテゴリのサービスです。差別化ポイントは、Cloudflare のエッジネットワーク（世界 300 都市以上）上に直接配信される点と、無料枠の太さです。

基本的な仕組み

Cloudflare Pages のデプロイフローは以下の通りです。

flowchart LR
    A["git push"] --> B["Cloudflare Build"]
    B --> C["静的アセット"]
    C --> D["エッジ配信<br/>300+ 都市"]

GitHub / GitLab のリポジトリに push する
Cloudflare のビルド環境でフレームワークのビルドコマンド（npm run build など）を実行
出力された静的ファイル（HTML, CSS, JS, 画像）をエッジネットワークに配信

開発者がやることは「push する」だけです。CI/CD の設定、CDN の構築、SSL 証明書の管理はすべて Cloudflare が担います。

プロジェクトの作成

Cloudflare ダッシュボードから作成する方法と、CLI（wrangler）から作成する方法があります。

ダッシュボードから

Cloudflare ダッシュボード → Workers & Pages → Create
Pages タブを選択
GitHub アカウントを接続し、リポジトリを選択
ビルド設定（フレームワーク、ビルドコマンド、出力ディレクトリ）を指定
Deploy

主要なフレームワーク（Astro, Next.js, Nuxt, SvelteKit, Hugo, Gatsby など）にはプリセットが用意されています。リポジトリを選択すると、ビルドコマンドと出力ディレクトリが自動的に設定されます。

CLI から

$ pnpm add -g wrangler
$ wrangler pages project create my-site
$ wrangler pages deploy dist

wrangler pages deploy は指定したディレクトリの中身をそのままアップロードします。Git 連携なしで使えるため、GitHub Actions など外部の CI からデプロイしたい場合に便利です。

ブランチプレビュー

Cloudflare Pages の最も便利な機能の 1 つがブランチプレビューです。

main 以外のブランチに push すると、そのブランチ専用のプレビュー URL が自動的に発行されます。

本番:              my-site.pages.dev
プレビュー（ハッシュ）: abc123.my-site.pages.dev
プレビュー（ブランチ）: fix-api.my-site.pages.dev

プレビュー URL はコミットごとに変わるハッシュ形式と、ブランチ名を使った固定エイリアス形式の両方が同時に発行されます。ハッシュ形式は「このコミット時点」の URL としてリグレッション確認に、ブランチ形式は PR のレビュー URL として共有するのに向きます。

PR ごとにプレビュー環境が立ち上がるため、レビュアーがローカルでビルドしなくても変更内容を確認できます。GitHub にはコメントでプレビュー URL が自動投稿されます。

プレビューデプロイは本番と同じエッジネットワーク上で配信されるため、パフォーマンス面でもほぼ本番と同じ条件でテストできます。

カスタムドメイン

my-site.pages.dev のデフォルトドメインに加えて、独自ドメインを設定できます。

ダッシュボード → Pages プロジェクト → Custom domains
ドメインを入力
DNS レコードの追加を承認

Cloudflare の DNS を使っている場合は自動的に CNAME レコードが追加されます。SSL 証明書も自動で発行・更新されるため、手動での管理は不要です。

外部の DNS を使っている場合は、表示される CNAME レコードを手動で追加します。

ビルド設定のカスタマイズ

環境変数

ダッシュボードの Settings → Environment variables からビルド時の環境変数を設定できます。Production と Preview で異なる値を設定することも可能です。

Production:  API_URL = https://api.example.com
Preview:     API_URL = https://staging-api.example.com

ビルドキャッシュ

Cloudflare Pages はビルド間で node_modules をキャッシュします。2 回目以降のビルドは依存のインストールがスキップされるため、その分ビルドが速くなります。

キャッシュが原因でビルドが失敗する場合は、ダッシュボードからキャッシュを手動でクリアできます。

Pages Functions

functions/ ディレクトリにファイルを配置すると、サーバーサイドの処理を追加できます。ランタイムは Cloudflare Workers と同じ V8 Isolate 環境です。

// functions/api/time.ts
export const onRequestGet: PagesFunction = async () => {
  return Response.json({ now: new Date().toISOString() });
};

ファイルパスがそのままルーティングになります。上の例では /api/time に GET リクエストを送ると JSON が返ります。

Pages Functions は静的サイトに動的機能を追加するオプションであり、複雑なバックエンドが必要なら Workers を別途使う方が適切です。

他サービスとの比較

	Cloudflare Pages	Vercel	Netlify
無料枠のビルド数	500 回/月	6,000 分/月	300 分/月
帯域	無制限	100 GB/月	100 GB/月
エッジロケーション	300+	グローバル CDN	グローバル CDN
サーバーサイド	Pages Functions	Serverless Functions	Netlify Functions
プレビューデプロイ	全ブランチ自動	全ブランチ自動	全ブランチ自動

Cloudflare Pages の突出したメリットは 帯域無制限 です。Vercel や Netlify では無料枠の帯域を超えると課金が始まります。Cloudflare Pages にはこの制限がありません。画像が多いサイトやアクセスが読めないサイトでは大きな差になります。なお、各サービスの料金体系は頻繁に変更されるため、最新の上限値は公式サイトで確認してください。

まとめ

Cloudflare Pages は Git 連携の自動ビルド・デプロイ、ブランチプレビュー、SSL 自動管理が揃った静的サイトホスティング
帯域無制限・月 500 ビルドの無料枠は個人開発には十分すぎる水準
Pages Functions で軽量なサーバーサイド処理も追加可能
より詳しい Workers との使い分けはこちらの記事を、無料枠の全体像はこちらの記事を参照

静的サイトのホスティング先を探しているなら、まずは Cloudflare Pages を試してみるのがおすすめです。GitHub リポジトリを接続して push するだけで動きます。

uv で Python 環境構築を爆速にする

Sat, 18 Apr 2026 00:00:00 GMT

はじめに

Python の環境構築は長年の課題です。pip でパッケージを入れ、venv で仮想環境を作り、requirements.txt でバージョンを固定し、場合によっては pyenv で Python 自体のバージョンも管理する。ツールが多すぎて、環境構築だけで疲弊することが珍しくありません。

uv は Astral 社（Ruff の開発元）が提供する Rust 製の Python パッケージマネージャーです。pip の 10〜100 倍速いインストール速度と、Python バージョン管理・仮想環境・パッケージ管理の一元化が特徴です。

インストール

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Windows なら PowerShell で以下を実行します。

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

インストール後、uv コマンドが使えることを確認します。

$ uv --version
uv x.y.z

Python 自体のインストール

uv は Python のバージョン管理も担います。pyenv が不要になります。

$ uv python install 3.12
$ uv python list

uv python install はビルド済みバイナリをダウンロードするため、pyenv のようなソースからのコンパイルが不要です。数秒で終わります。

プロジェクトの初期化

$ uv init my-project
$ cd my-project

uv init は以下のファイルを生成します。

my-project/
├── .git/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

uv init は内部で git init も実行するため、.git/ と .gitignore も同時に生成されます。

pyproject.toml がプロジェクトの中心です。依存パッケージ、Python バージョン制約、プロジェクトメタデータをすべてここに書きます。

パッケージのインストール

$ uv add requests
$ uv add ruff --dev

uv add はパッケージを pyproject.toml に追加し、uv.lock にバージョンをロックし、仮想環境にインストールするところまでを 1 コマンドで行います。仮想環境が存在しなければ自動的に作成されます。

速度の違いは体感で明らかです。pip で 30 秒かかるインストールが、uv では 1〜2 秒で終わることも珍しくありません。Rust 製の依存解決エンジンと、パッケージのグローバルキャッシュが速さの理由です。

pip からの移行

既存の requirements.txt からの移行も簡単です。

$ uv add -r requirements.txt

これだけで requirements.txt に書かれた全パッケージが pyproject.toml に移行され、uv.lock が生成されます。

スクリプトの実行

$ uv run python main.py
$ uv run ruff check .

uv run は仮想環境をアクティベートせずにコマンドを実行します。source .venv/bin/activate を忘れて「パッケージが見つからない」と悩む問題がなくなります。

インラインスクリプト

ファイル先頭にメタデータを書くことで、依存パッケージ付きのスクリプトを単体実行できます。

# /// script
# requires-python = ">=3.12"
# dependencies = ["requests", "rich"]
# ///

import requests
from rich import print

resp = requests.get("https://httpbin.org/get")
print(resp.json())

$ uv run fetch.py

uv run がメタデータを読み取り、依存パッケージを自動でインストールしてから実行します。使い捨てスクリプトの共有に便利です。

ツールの実行

グローバルにインストールせずに CLI ツールを実行する uvx コマンドもあります。npx の Python 版です。

$ uvx ruff check .
$ uvx black --check .
$ uvx mypy src/

ツールは一時的な隔離環境にインストールされ、プロジェクトの依存を汚しません。

pip / poetry との比較

操作	pip + venv	poetry	uv
仮想環境の作成	`python -m venv .venv`	自動	自動
パッケージ追加	`pip install` → 手動で requirements.txt 更新	`poetry add`	`uv add`
ロックファイル	なし（pip-tools で別途生成）	`poetry.lock`	`uv.lock`
Python バージョン管理	pyenv 等が別途必要	pyenv 等が別途必要	`uv python install`
インストール速度	遅い	遅い	10〜100 倍速い
ツール実行（隔離環境）	`pipx`（別途インストール）	`pipx`（別途インストール）	`uvx`

uv の最大の強みは これまで 3〜4 個のツールで賄っていた機能が 1 つに統合されている 点です。pyenv + venv + pip + pip-tools の組み合わせを uv 単体で置き換えられます。

まとめ

uv は Python のバージョン管理・仮想環境・パッケージ管理を 1 コマンドに統合する
Rust 製の依存解決エンジンにより、pip の 10〜100 倍速いインストールを実現
uv run で仮想環境のアクティベートが不要、uvx でグローバルインストールなしのツール実行が可能
既存の requirements.txt からの移行は uv add -r requirements.txt だけ

新規プロジェクトなら最初から uv を使うのがおすすめです。既存プロジェクトは、uv add -r requirements.txt で移行するところから始められます。速度の違いだけでも導入する価値があります。

Cloudflare を無料枠だけで運用する実践ガイド

Fri, 17 Apr 2026 00:00:00 GMT

はじめに

Cloudflare は無料枠が異常に太いことで知られています。
Pages、Workers、R2、D1、KV など個人開発で使うサービスのほとんどが Free プランで提供されており驚きを隠せません。

ただし「無料で使える」と「無料枠で収まる設計にする」は別の話です。上限を知らずに設計すると、思わぬところで課金が発生します。

各サービスの Free プラン上限と、個人開発で無料枠に収まる構成パターンは次のとおりです。

:::tip[この記事で登場する Cloudflare 用語]

R2: 画像・動画・PDF などを置く S3 互換オブジェクトストレージ。egress（下り転送量）が無料で CDN 的な配信にも向く
D1: SQLite ベースのリレーショナル DB。JOIN やトランザクションが必要なアプリで、従来の RDB と同じ感覚で使える
KV: キーに対して値を返す超軽量な Key-Value ストア。設定値やキャッシュなど「読み取りが多く書き込みは少ない」データ向け :::

無料枠の上限一覧

2026 年 4 月時点の主要サービスの Free プラン上限です。最新情報は公式の Plans ページで確認してください。

サービス	主な上限	超過時の挙動
Pages	無制限のサイト、500 回/月ビルド	ビルド失敗
Workers	10 万リクエスト/日、10ms CPU 時間/リクエスト	リクエスト拒否
KV	10 万読み取り/日、1,000 書き込み/日	リクエスト拒否
R2	10 GB ストレージ、100 万 Class A/月、1,000 万 Class B/月	課金開始
D1	5 GB ストレージ、500 万行読み取り/日、10 万行書き込み/日	リクエスト拒否
Queues	100 万オペレーション/月	課金開始

Pages のホスティング自体は事実上無制限です。制限があるのはビルド回数（月 500 回）ですが、個人ブログで月 500 回デプロイすることはまずありません。

構成パターン

パターン 1: 静的サイト（このブログの構成）

Pages（Astro SSG）→ 静的 HTML/CSS/JS を配信

最もシンプルな構成で、Workers も KV も使いません。ビルド回数以外に上限を気にする要素がなく、無料枠を超える心配は事実上ゼロです。

ブログ、ポートフォリオ、ドキュメントサイトはこの構成で十分です。

パターン 2: 静的サイト + 簡易 API

Pages（フロント）+ Pages Functions（API）+ KV（データ）

お問い合わせフォームやアクセスカウンターなど、軽量な動的機能を追加するパターンです。Pages Functions は Workers と同じリクエスト上限（10 万/日）を共有します。

KV の書き込み上限は 1,000 回/日とやや厳しいため、書き込み頻度が高い機能には不向きです。閲覧カウンターのように読み取りが中心のユースケースに適しています。

パターン 3: アプリ + DB + ストレージ

Pages（フロント）+ Workers（API）+ D1（DB）+ R2（ファイル）

フルスタックの個人開発アプリ向けです。D1 の読み取り上限は 500 万行/日と余裕がありますが、書き込みは 10 万行/日です。

R2 はストレージが 10 GB まで無料で、egress（下り転送量）は無制限です。画像や PDF のホスティングに向いています。S3 互換 API なので、既存の S3 クライアントがそのまま使えるのも利点です。

無料枠に収めるための設計のコツ

Workers のリクエスト数を減らす

10 万リクエスト/日は多いように見えますが、SPA のバックエンド API として使うと意外に消費します。以下の工夫で節約できます。

静的化できるレスポンスは Pages で配信する。Workers を経由させない
Cache API を使う。Workers 内で caches.default にレスポンスをキャッシュすれば、同じリクエストに対する Workers の実行回数を減らせる
バッチ API を設計する。フロントエンドから 10 回 fetch する代わりに、1 回のリクエストでまとめて取得できる API を作る

KV の書き込み上限に注意する

KV の読み取りは 10 万回/日ですが、書き込みは 1,000 回/日です。2 桁違います。

セッション管理のように頻繁に書き込むユースケースには向きません。設定値やキャッシュのように「書き込みは稀、読み取りは頻繁」なデータに使います。頻繁な書き込みが必要なら D1 を検討してください。

D1 は行数ベースで考える

D1 の制限は「行数」ベースで、「リクエスト数」ではありません。SELECT * FROM users が 100 行返せば、100 行分の読み取りとしてカウントされます。

-- 悪い例: 全件取得して JS で絞り込む
SELECT * FROM logs

-- 良い例: WHERE で絞ってから取得する
SELECT * FROM logs WHERE created_at > date('now', '-7 days') LIMIT 100

不要な行を読まない設計が、そのまま無料枠の節約になります。

R2 の Class A / B を理解する

R2 の操作は Class A（変更系 + LIST: PUT, POST, DELETE, LIST）と Class B（読み取り系: GET, HEAD）に分類されます。

Class	無料上限	主な操作
A	100 万回/月	PUT, POST, DELETE, LIST
B	1,000 万回/月	GET, HEAD

画像を CDN 的に配信する場合、読み取り（Class B）は 1,000 万回/月あるので十分です。一方で LIST 操作（ファイル一覧の取得）は Class A にカウントされます。管理画面でファイル一覧を頻繁にリロードすると、Class A の消費が早まります。

モニタリング

無料枠の消費状況は Cloudflare ダッシュボードの Analytics セクションで確認できます。Workers の場合は Workers & Pages → 該当 Worker → Metrics から日次のリクエスト数を見られます。

上限に近づいたときにアラートを受け取りたい場合は、ダッシュボードの Notifications から設定できます。無料枠でも通知設定は利用可能です。

まとめ

Cloudflare の無料枠は個人開発には十分すぎる水準だが、サービスごとの上限は把握しておく必要がある
静的サイトなら Pages のみで事実上無制限。動的機能を追加する場合は Workers のリクエスト数と KV の書き込み上限がボトルネックになりやすい
D1 は行数ベース、R2 は操作クラスベースの課金体系。不要なデータを読まない設計がそのまま節約になる
Pages と Workers の使い分けについては前回の記事を、Pages そのものの詳細は Cloudflare Pages 入門を参照

ターミナル出力のシークレットをパイプで隠す CLI「mask-pipe」を作った

Fri, 17 Apr 2026 00:00:00 GMT

画面共有で `env` を叩いてヒヤッとしたことがある

ペアプロ中に環境変数を確認しようと env を叩くと、相手の画面に AWS のアクセスキーがそのまま流れます。docker logs に平文のトークンが出力される、CI のジョブログに DB 接続 URL が出る、という形でも同じ漏れ方をします。

この「ターミナル出力経由でシークレットが漏れる瞬間」を塞ぐために、mask-pipe という Go 製の CLI を作りました。TruffleHog がリポジトリを守り、secretlint がコミットを守るのに対して、mask-pipe は ターミナル画面 を守る役割を担います。v0.1.1 をリリースしたので、設計と使い方をまとめておきます。

デモ

使い方はシンプルで、隠したい出力の先にパイプで繋ぐだけです。

:::photo{title="env | mask-pipe の実行デモ"} :::

$ env | mask-pipe
AWS_ACCESS_KEY_ID=AKIA************MPLE
AWS_SECRET_ACCESS_KEY=wJal********************************EKEY
DATABASE_URL=postgres://admin:****@db.example.com:5432/mydb
GITHUB_TOKEN=ghp_********************************ef01
STRIPE_SK=sk_live_********************************p7dc

Docker や Kubernetes のログもそのまま流せます。

$ docker logs -f my-app 2>&1 | mask-pipe
$ kubectl logs pod-name | mask-pipe --show-tail 0

本番運用のコマンドに噛ませる前に、何が置換されるかを確認したいときは --dry-run を使います。元の出力はそのまま流れ、マスク対象があった行だけが報告されます。

$ terraform plan | mask-pipe --dry-run

インストール

静的ビルドのシングルバイナリとして配布しています。Homebrew・go install・バイナリ直ダウンロードのいずれでも入ります。

$ brew install c12o-dev/tap/mask-pipe
$ go install github.com/c12o-dev/mask-pipe/cmd/mask-pipe@latest

macOS（Intel / Apple Silicon）、Linux（amd64 / arm64）、Windows（amd64）を公式ビルド対象にしています。依存ライブラリは一切なく、ランタイムも不要です。

組み込みパターンは 8 つだけ

v1 の時点では以下の 8 パターンだけを既定で有効にしています。

ID	検出対象	マスク例
`aws_access_key`	`AKIA` + 16 文字の AWS アクセスキー ID	`AKIA************MPLE`
`aws_secret_key`	`aws_secret_access_key=...` の値部分	`wJal****EKEY`
`github_token`	`ghp_` / `gho_` / `ghu_` / `ghs_` / `ghr_` で始まるトークン	`ghp_****1234`
`github_pat`	`github_pat_` で始まる fine-grained PAT	`gith****BBcc`
`stripe_key`	`sk_live_` / `sk_test_` / `pk_live_` / `pk_test_`	`sk_l****p7dc`
`jwt`	ドット区切り 3 セグメントの base64url	`eyJh****sR8U`
`db_url_password`	`scheme://user:pass@host` のパスワード部分	`://user:****@host`
`pem_private_key`	`-----BEGIN ... PRIVATE KEY-----` ブロック	`[REDACTED PRIVATE KEY]`

全パターンの仕様は docs/specs/002-pattern-library.md に書きました。

設計上のいちばん大事なポリシーは 「再現率より精度を優先する」 ことです。通常の出力を壊す誤検知 1 件は、見逃し 10 件よりユーザーの信頼を損ないます。TruffleHog の 800 以上あるパターンをそのまま持ち込まなかったのは、誤検知率をコントロールしきれないと判断したためです。自分たちで精度 99% を保証できる 8 パターンから始めて、少しずつ足していく方針にしています。

細かい話だと、Stripe キーの正規表現に \b アンカーを付けるかで悩みました。アンカーがないと disk_test_xxx のようなカラム名を誤検出することを、パターンレビュー用のエージェントが見つけました。そこで全パターンに単語境界を入れてあります。PEM 秘密鍵は単一行では一致できません。そのため ADR 0004 に書いた BEGIN/END マーカー方式のマルチラインバッファリング で実装しています。バッファ上限の 100 行または 64KB を超えたら、fail-open でそのまま流します。

設定でカスタマイズ

~/.mask-pipe.toml を置くだけでパターンの切り替え、カスタムパターンの追加、allowlist、表示スタイルの調整ができます。

[builtin]
jwt = false   # JWT 検出をオフに

[[custom]]
name    = "internal-api-key"
pattern = 'mycompany-key-[a-zA-Z0-9]{32}'

[[allowlist]]
name    = "aws-doc-example"
pattern = 'AKIAIOSFODNN7EXAMPLE'

[display]
mask_char = "*"
show_tail = 4

allowlist は「公式ドキュメントのサンプルキー」など、既知の安全な値をマスクしないためのエスケープハッチです。--mask-char '#' や --show-tail 0 のような CLI フラグでも同じ調整ができます。

設定の検証には mask-pipe doctor、有効パターンの確認には mask-pipe list-patterns を用意しました。トラブル時はまずこの 2 つを叩いてもらう想定です。

設計で悩んだところ

なぜ「パイプ専用」にしたのか

最初は 1Password の op run のように、シェルに仕込んでおけば全ての子プロセスの stdout を透過的にマスクするモードも検討しました。ただ、op run には TTY が潰れて TUI アプリが正しく表示されなくなるという有名な問題があります。同じ問題を避けるため、mask-pipe は 明示的にパイプで繋いだときだけ動く 設計にしました（ADR 0002）。色付き出力も対話プロンプトもそのまま動きます。PTY プロキシ方式の mask-pipe shell は v2 で再検討する予定です。

なぜ Go なのか

単一バイナリ配布が絶対条件で、OpenSSL の動的リンクで起きるトラブルを避けたかったので Go を選びました（ADR 0001）。標準の regexp パッケージは RE2 を採用しており、計算量が入力長に対して線形 であることが保証されます。ストリーミングで遅延を予測できるのは、リアルタイムに流れるログをフィルタする CLI にとってかなり重要でした。goreleaser で Homebrew・Scoop・APT を一気に配布できるのも楽です。

TruffleHog と競合にしない

比較表は README に詳しく書きましたが、要点だけ書くとこうなります。

	mask-pipe	TruffleHog	secretlint	GitHub `add-mask`
守る対象	ターミナル出力	Git リポジトリ	コミット前のファイル	CI ログ
実行タイミング	リアルタイム（pipe）	事後スキャン	pre-commit	CI 実行時
ローカルで動く	○	○	○	×（CI 専用）

いずれも 補完関係 にあり、全部組み合わせるのが現実的な防御ラインだと考えています。

既知の限界

TUI アプリはラップできません。 これはパイプで動かすことを選んだ時点での意図的な制約です。vim や docker run -it を巻き込んだ瞬間に操作不能になります。
エントロピーベースの検出は v1 では採用していません。 Gitleaks 系の誤検知が許容しきれない領域だったので、パターンマッチ一本で割り切りました。
PTY プロキシ（mask-pipe shell）は v2 で検討中です。 「いちいち | mask-pipe と書くのが面倒」という声への答えですが、TTY 問題を再発させずに実装する道筋が見えてから着手します。

おわりに

公開場所は github.com/c12o-dev/mask-pipe です。brew install c12o-dev/tap/mask-pipe 一発で入ります。想定している使い手は、画面共有で一度でもヒヤッとしたことがある人です。フィードバックは GitHub Discussions で歓迎します。Star も貰えたら嬉しいです。

SQLite WASM + OPFS でブラウザにリレーショナル DB を持ち込む

Thu, 16 Apr 2026 00:00:00 GMT

はじめに

前回の記事では Dexie.js で IndexedDB を実用レベルに引き上げる方法を紹介しました。IndexedDB は手軽ですが、キーバリュー型のストレージであり、複雑なクエリや JOIN は苦手です。

ブラウザの中でも SQL を書きたいという要望に応えるのが SQLite WASM です。
SQLite の C ソースコードを WebAssembly にコンパイルし、ブラウザ上でフル機能のリレーショナル DB を動かします。
永続化には Origin Private File System（OPFS）を組み合わせることで、IndexedDB を超えるパフォーマンスが得られます。

IndexedDB との比較

	IndexedDB	SQLite WASM + OPFS
データモデル	キーバリュー（オブジェクトストア）	リレーショナル（テーブル + SQL）
クエリ言語	JavaScript API（カーソル、インデックス）	SQL
JOIN	不可（アプリ層で結合）	可能
トランザクション	暗黙コミット（リクエスト完了時）	明示的（BEGIN / COMMIT）
書き込み性能	中程度	OPFS 経由で高速
ブラウザ対応	全モダンブラウザ	Chrome 102+, Firefox 111+, Safari 17.4+

単一テーブルの CRUD であれば IndexedDB（+ Dexie.js）で十分です。複数テーブルの結合や集計が頻繁に発生するなら、SQLite の方が自然に書けます。

セットアップ

公式の SQLite WASM ビルドを使う方法と、コミュニティのラッパーライブラリを使う方法があります。ここでは npm パッケージとして使いやすい @sqlite.org/sqlite-wasm を紹介します。

$ pnpm add @sqlite.org/sqlite-wasm

SQLite WASM は Web Worker 内で動かすのが推奨です。OPFS の同期アクセス API（createSyncAccessHandle）は Worker 専用のため、メインスレッドからは使えません。

// sqlite-worker.ts
import sqlite3InitModule from "@sqlite.org/sqlite-wasm";

const sqlite3 = await sqlite3InitModule();
const db = new sqlite3.oo1.OpfsDb("/app.sqlite3");

db.exec(`
  CREATE TABLE IF NOT EXISTS tasks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    done INTEGER DEFAULT 0,
    created_at TEXT DEFAULT (datetime('now'))
  )
`);

OpfsDb を使うことで、データは OPFS 上のファイルとして永続化されます。ブラウザを閉じてもデータは残り、次回アクセス時にそのまま読み込まれます。

CRUD 操作

SQL をそのまま書けるのが最大の利点です。

// 作成
db.exec({
  sql: "INSERT INTO tasks (title) VALUES (?)",
  bind: ["記事を書く"],
});

// 読み取り
const rows = db.exec({
  sql: "SELECT * FROM tasks WHERE done = 0 ORDER BY created_at DESC",
  returnValue: "resultRows",
  rowMode: "object",
});

// 更新
db.exec({
  sql: "UPDATE tasks SET done = 1 WHERE id = ?",
  bind: [1],
});

// 削除
db.exec({
  sql: "DELETE FROM tasks WHERE id = ?",
  bind: [1],
});

IndexedDB ではアプリ層で実装する必要があった集計やサブクエリも、SQL の表現力でそのまま書けます。

const stats = db.exec({
  sql: `
    SELECT
      done,
      COUNT(*) as count,
      MIN(created_at) as oldest
    FROM tasks
    GROUP BY done
  `,
  returnValue: "resultRows",
  rowMode: "object",
});

OPFS とは何か

Origin Private File System は Web 標準のファイルシステム API です。通常のファイルシステムとは異なり、オリジン（ドメイン）ごとに隔離されたプライベートな領域を提供します。

SQLite WASM にとって OPFS が重要な理由は 同期的なファイル I/O が可能な点です。IndexedDB 経由の永続化は非同期です。SQLite は同期的なファイルアクセスを前提に設計されているため相性が悪く、パフォーマンスが劣化します。OPFS の createSyncAccessHandle はバイト単位の同期読み書きを提供するため、SQLite のネイティブに近い I/O パターンを再現できます。使える場所は Worker 内だけです。

メインスレッドとの通信

DB 操作は Worker 内で行うため、メインスレッドからは postMessage で通信します。

// main.ts
const worker = new Worker(
  new URL("./sqlite-worker.ts", import.meta.url),
  { type: "module" },
);

function query(sql: string, bind?: unknown[]): Promise<unknown[]> {
  return new Promise((resolve) => {
    const id = crypto.randomUUID();
    worker.addEventListener(
      "message",
      (e) => {
        if (e.data.id === id) resolve(e.data.rows);
      },
      { once: true },
    );
    worker.postMessage({ id, sql, bind });
  });
}

const tasks = await query("SELECT * FROM tasks WHERE done = 0");

実際のアプリケーションでは、この通信層を薄いラッパーとして整備し、コンポーネント側からは通常の非同期関数として呼び出せるようにしておくのがおすすめです。

制約と注意点

Worker 必須
OPFS の同期アクセスは Worker 内でしか使えません。メインスレッドで使う場合は IndexedDB バックエンドにフォールバックしますが、パフォーマンスは OPFS より落ちます。
同時アクセス
同一オリジンの複数タブから同じ DB ファイルを開くと、ロック競合が発生します。SharedWorker で DB アクセスを一元化するか、Web Locks API で排他制御を設計します。
WASM のサイズ
SQLite WASM のバイナリは gzip 圧縮後で約 400 KB です。初回ロードのコストとして許容できるかはアプリの性質次第です。
デバッグ
OPFS のファイルは DevTools から直接参照しにくいのが現状です。Chrome の navigator.storage.getDirectory() で探索するか、アプリ側にエクスポート機能を用意しておくと開発が楽になります。

まとめ

SQLite WASM はブラウザ上でフル機能の SQL を実行でき、OPFS と組み合わせると高速な永続化が可能
IndexedDB が苦手な JOIN や集計を SQL の表現力でカバーできる
Worker 内での実行が前提。メインスレッドとは postMessage で通信する設計が必要
複数タブの同時アクセスや WASM サイズなど、導入前に検討すべき制約がある

単純な CRUD なら Dexie.js + IndexedDB、複雑なクエリが必要なら SQLite WASM + OPFS、というのが現時点での使い分けの目安です。

Cloudflare Pages と Workers の違いと使い分け

Wed, 15 Apr 2026 00:00:00 GMT

はじめに

Cloudflare でウェブアプリをデプロイしようとすると、最初に迷うのが「Pages と Workers、どっちを使えばいいのか」です。

どちらもエッジで動き、どちらも無料枠があり、Pages には Functions という Workers 互換の機能も用意されている。公式ドキュメントを読んでも境界が曖昧に感じられます。

境界は両者の設計思想の違いで決まり、それがプロジェクトの特性に応じた選定指針になります。

設計思想の違い

根本的な違いは「何を起点に設計されているか」です。

	Pages	Workers
起点	静的アセットの配信	リクエストの処理
デプロイ単位	Git リポジトリ（ビルド → 配信）	スクリプト（wrangler deploy）
ルーティング	ファイルシステムベース	`fetch` イベントハンドラ
プレビュー	ブランチごとに自動生成	自動ブランチプレビューなし

Pages は「HTML/CSS/JS をビルドしてエッジに配る」のが主務で、動的処理は後から追加するオプションです。Workers は「リクエストを受けてレスポンスを返す」関数が出発点で、静的アセットの配信は後から追加する機能です。

Pages Functions の位置付け

Pages には Functions という機能があります。functions/ ディレクトリにファイルを置くと、Workers と同じランタイム（V8 Isolate）で動的処理を追加できます。

// functions/api/hello.ts
export const onRequestGet: PagesFunction = async (context) => {
  return new Response(JSON.stringify({ message: "Hello" }), {
    headers: { "Content-Type": "application/json" },
  });
};

これが混乱のもとです。「Pages でも API が書けるなら Workers はいらないのでは？」と思えてきます。

:::tip[この記事で登場する Cloudflare 用語]

Durable Objects: キー単位で状態を持てる耐久オブジェクト。強整合な少量データの保持や WebSocket セッションの管理に使う
Static Assets: Workers に静的ファイル配信を任せる機能。Workers 単体で SPA + API の構成が組める
バインド: 別リソース（KV、D1、他の Workers など）への参照を環境に紐付ける仕組み。環境変数のリソース版
Wrangler: Workers/Pages 用の公式 CLI。wrangler deploy などでデプロイを実行する
V8 Isolate: Chrome の JS エンジン V8 が提供する軽量なサンドボックス。Workers のランタイム基盤 :::

しかし Pages Functions にはいくつかの制約があります。

Cron Triggers が使えない。定期実行が必要なら Workers が必須
Durable Objects を直接ホストできない。クラスの定義は Workers でしかできない（Pages Functions から別 Workers の Durable Objects へバインドは可能）
デプロイがビルドと結合している。静的アセットと Functions は常に同時にデプロイされるため、API だけの更新でもビルドが実行される
ルーティングがファイルシステム固定。_middleware.ts による前処理や _routes.json での制御はできるが、Workers の fetch ハンドラのように URL パターンをコードで自由に振り分けたい構成には向かない

逆に言えば、これらに該当しなければ Pages Functions で十分です。

選定のフローチャート

flowchart TD
    A["プロジェクトの種類は？"] --> B{"静的サイト / SSG が主体？"}
    B -- Yes --> C{"API やサーバー処理は？"}
    C -- 不要 --> D["Pages のみ"]
    C -- 簡単な API --> E["Pages + Functions"]
    C -- Cron / Durable Objects --> F["Pages + 別 Workers"]
    B -- No --> G{"静的アセットは？"}
    G -- なし --> H["Workers のみ"]
    G -- あり --> I["Workers + Static Assets"]

実際の判断基準をもう少し具体的に書くと、こうなります。

ブログ、ドキュメントサイト、LP: Pages のみ。ビルド → 配信のパイプラインがそのまま使えるので、これ以上シンプルな選択肢はない
SSG + お問い合わせフォーム / 簡易 API: Pages + Functions。API のために別サービスを立てる必要がない
SPA + バックエンド API: Workers（Static Assets 機能で SPA を配信しつつ、同じプロジェクトで API も処理）
定期バッチ、Webhook 受信、WebSocket: Workers 単体。Cron Triggers や Durable Objects は Workers でしか使えない
SSG + 重めのバックエンド: Pages（フロント）+ Workers（API）の分離構成

統合の方向性

Cloudflare は 2024 年以降、Pages と Workers の統合を段階的に進めています。Workers に Static Assets 機能が追加され、Workers 単体で静的ファイルの配信が可能になりました。

長期的には Workers が統一プラットフォームになり、Pages は Workers の「静的サイト向けプリセット」という位置付けになっていく方向です。実際、公式の移行ガイドも Pages から Workers への移行手順を案内しています。ただし現時点では Pages のブランチプレビューや Git 連携ビルドは Workers にはなく、静的サイトなら Pages を選ぶ理由は十分にあります。

新規プロジェクトでの判断としては、以下の方針がおすすめです。

静的サイトが主体: Pages を選ぶ。Git 連携ビルドとブランチプレビューの価値が高い
動的処理が主体: Workers を選ぶ。制約が少なく、将来の拡張にも対応しやすい
迷ったら: Pages から始める。Pages Functions で足りなくなった時点で、その機能だけ Workers に切り出す

まとめ

Pages は「静的アセットの配信」が起点、Workers は「リクエストの処理」が起点。設計思想が根本的に違う
Pages Functions は Workers 互換のランタイムだが、Cron Triggers や Durable Objects は使えない
静的サイト + 簡易 API なら Pages + Functions、動的処理が主体なら Workers を選ぶ
長期的には統合が進むが、現時点では Pages のブランチプレビューと Git 連携が差別化ポイント

このブログ自体は Astro の SSG を Pages でホスティングしており、動的処理は一切使っていません。Pages のみで完結する最もシンプルな構成です。

Pages そのものの仕組みや機能を詳しく知りたい方は、Cloudflare Pages とは何か：静的サイトホスティングの実力も参考にしてください。

Dexie.js で IndexedDB をまともに使う

Tue, 14 Apr 2026 00:00:00 GMT

はじめに

ブラウザには、構造化データを大量に保存できる IndexedDB が組み込まれています。
リレーショナルではありませんが、PWA やローカルファーストなアプリでは避けて通れないストレージです。
生の API はコールバックベースで冗長で、トランザクション管理が煩雑、型の恩恵もありません。

Dexie.js は IndexedDB の上に Promise ベースの薄いラッパーを提供するライブラリです。
TypeScript との相性がよく、スキーマのバージョン管理も宣言的に書けます。
Dexie.js v4 を対象に、導入、日常的な CRUD、スキーマ移行の順に進めます。

生の IndexedDB がつらい理由

IndexedDB の API をそのまま使うと、データベースのオープンだけでこれだけのコードが必要です。

const request = indexedDB.open("mydb", 1);
request.onupgradeneeded = (event) => {
  const db = (event.target as IDBOpenDBRequest).result;
  if (!db.objectStoreNames.contains("tasks")) {
    db.createObjectStore("tasks", { keyPath: "id", autoIncrement: true });
  }
};
request.onsuccess = (event) => {
  const db = (event.target as IDBOpenDBRequest).result;
  // ここからトランザクションを開いて操作...
};
request.onerror = (event) => {
  console.error("DB open failed", event);
};

イベントハンドラがネストし、型がなく、エラーハンドリングが散在します。
localStorage の手軽さと比べると、導入コストが高すぎます。

Dexie.js のセットアップ

$ pnpm add dexie

データベースの定義は class ベースで書きます。

// db.ts
import Dexie, { type EntityTable } from "dexie";

interface Task {
  id: number;
  title: string;
  done: boolean;
  createdAt: Date;
}

const db = new Dexie("taskdb") as Dexie & {
  tasks: EntityTable<Task, "id">;
};

db.version(1).stores({
  tasks: "++id, done, createdAt",
});

export { db };
export type { Task };

"++id, done, createdAt" はインデックスの定義です。
++ は自動採番の主キー、カンマ区切りでセカンダリインデックスを追加します。
ここに書かなかったプロパティもデータとしては保存されますが、インデックスで検索できないだけです。

CRUD 操作

Dexie の API は直感的です。Promise を返すので async/await でそのまま書けます。

作成

await db.tasks.add({
  title: "記事を書く",
  done: false,
  createdAt: new Date(),
});

読み取り

// 全件取得
const allTasks = await db.tasks.toArray();

// 条件付き取得
const pending = await db.tasks.where("done").equals(false).toArray();

// 主キーで取得
const task = await db.tasks.get(1);

更新

await db.tasks.update(1, { done: true });

削除

await db.tasks.delete(1);

生の IndexedDB ではトランザクションのオープン、オブジェクトストアの取得、リクエストの発行、イベントハンドラの登録…
と 4 ステップ必要だった操作が、1 行で完結します。

スキーマのバージョン管理

アプリの進化に伴い、テーブル構造を変更したくなるのは必然です。
Dexie はバージョンを積み上げる宣言的な移行をサポートしています。

db.version(1).stores({
  tasks: "++id, done, createdAt",
});

db.version(2).stores({
  tasks: "++id, done, createdAt, priority",
});

db.version(3)
  .stores({
    tasks: "++id, done, createdAt, priority",
    tags: "++id, name",
  })
  .upgrade((tx) => {
    return tx
      .table("tasks")
      .toCollection()
      .modify((task) => {
        task.priority = task.priority ?? "medium";
      });
  });

バージョン 2 で priority インデックスを追加し、バージョン 3 で tags テーブルを追加しつつ既存データにデフォルト値を埋めています。
upgrade コールバックには、データマイグレーションも書けます。

過去のバージョン定義は消さずに残す必要があります。
ユーザーがバージョン 1 のまま久しぶりにアクセスした場合、Dexie は 1 → 2 → 3 と順番にマイグレーションを実行してくれます。

実践的なパターン

複合クエリ

const recentPending = await db.tasks
  .where("done")
  .equals(false)
  .and((task) => task.createdAt > oneWeekAgo)
  .sortBy("createdAt");

where でインデックスを使った高速フィルタリングを行い、and で追加条件を適用するパターンです。
and の条件は where の結果に対する JS フィルタになるため、先に where で対象を減らしておきます。

一括操作

await db.tasks.bulkAdd([
  { title: "タスク A", done: false, createdAt: new Date() },
  { title: "タスク B", done: false, createdAt: new Date() },
  { title: "タスク C", done: false, createdAt: new Date() },
]);

await db.tasks.where("done").equals(true).delete();

bulkAdd は個別の add を繰り返すより高速です。
内部的に 1 つのトランザクションでまとめて書き込みます。

注意点

容量制限はブラウザ依存
Chrome はオリジンごとにディスク空き容量の一定割合（目安で数百 MB〜数 GB）まで。
Safari 17 以降も同様にディスクベースの上限が適用されます。
ただし、ユーザーがストレージをクリアすればデータは消えるため、永続化が必須ならサーバーとの同期を別途設計しておきます。
Web Worker からもアクセス可能
IndexedDB はメインスレッドと Web Worker の両方から使えます。
重い集計処理は Worker で実行すると UI がブロックされません。
DevTools で中身を確認できる
Chrome DevTools の Application タブ → IndexedDB からテーブルの中身をリアルタイムで確認できます。
デバッグ時に重宝します。

まとめ

IndexedDB はブラウザ内蔵の強力なストレージだが、生の API は実用にはつらすぎる
Dexie.js を入れれば Promise ベースの直感的な API で CRUD が 1 行で書ける
スキーマのバージョン管理が宣言的に書けるため、アプリの進化に追従しやすい
ローカルファーストなアプリや PWA のデータ層として、導入コストに対するリターンが大きい

次の記事では、IndexedDB とは異なるアプローチでブラウザ内にリレーショナル DB を持ち込む SQLite WASM + OPFS を紹介します。

Claude Code を導入してターミナル中心の開発フローを作る

Mon, 13 Apr 2026 00:00:00 GMT

はじめに

AI コーディング支援といえば VS Code の拡張が主流です。ターミナルで完結する開発フローを好むエンジニアには、IDE 前提のツールは使いにくいことがあります。
Claude Code は Anthropic が提供する CLI ベースの AI エージェントで、ターミナルから直接コードの読み書き・実行・Git 操作までを対話的に行えます。

Claude Code を導入し、日常の開発フローに組み込むまでの流れは次のとおりです。

インストールと初期設定

Claude Code の利用には Anthropic の Pro・Max・Team・Enterprise、または API（Console）アカウントが必要です。
無料プランでは利用できません。

インストール方法は 2 通りあります。

Node.js 不要のネイティブインストーラー

$ curl -fsSL https://claude.ai/install.sh | bash
$ claude

npm でグローバルインストール

$ npm install -g @anthropic-ai/claude-code
$ claude

初回起動時に Anthropic アカウントとの認証が始まります。
ブラウザが開くので、ログインして承認すれば完了です。

認証後、プロジェクトのルートディレクトリで claude を実行するだけで対話が始まります。
Claude Code は起動時にディレクトリ構造やファイルの内容を読み取り、プロジェクトの文脈を自動的に把握します。

基本の使い方

Claude Code の操作はシンプルです。ターミナルに自然言語でやりたいことを伝えるだけで動きます。

$ claude
> このプロジェクトの構成を教えて
> src/utils/auth.ts のバリデーションにメールアドレス形式のチェックを追加して
> 直近の変更をコミットして

ファイルの読み取り・編集・作成、シェルコマンドの実行、Git 操作など、開発に必要な操作は一通りカバーされています。
破壊的な操作（ファイル削除や git push など）の前には確認プロンプトが出るため、意図しない変更が実行される心配はありません。

ワンショット実行

対話モードに入らず、結果を標準出力に返す -p（--print）オプションも便利です。

$ claude -p "package.json の依存パッケージで非推奨になっているものを教えて"
$ claude -p "src/components/Header.tsx を TypeScript の strict モードに対応させて" --allowedTools Edit,Write

CI やスクリプトに組み込む場合はこちらを使います。

permission の設定

Claude Code を快適に使ううえで重要なのが .claude/settings.json による permission 設定です。
デフォルトでは Bash コマンドの実行ごとに承認が必要ですが、安全なコマンドは事前に許可しておけます。

{
  "permissions": {
    "allow": [
      "Bash(pnpm lint)",
      "Bash(pnpm check)",
      "Bash(pnpm build)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)"
    ],
    "deny": [
      "Bash(git push --force*)"
    ]
  }
}

リント・ビルド・Git の読み取り系は allow に入れ、git push --force のような破壊的コマンドは deny で明示的にブロックします。
これがないと、エージェントが毎回承認を求めてきて作業のテンポが崩れます。

CLAUDE.md でプロジェクト文脈を渡す

プロジェクトのルートに CLAUDE.md を置くと、毎セッション自動的に読み込まれます。
ここにスタック情報・コーディング規約・よく使うコマンドを書いておくと「この repo は何？」から始まる説明コストがゼロになります。

## Stack
- Astro 5 + Svelte 5 + Tailwind 3
- Package manager: pnpm
- Formatter: Biome (tabs, double quotes)

## Commands
| Purpose | Command |
|---|---|
| Dev server | `pnpm dev` |
| Build | `pnpm build` |
| Lint | `pnpm lint` |

CLAUDE.mdは短く保つのが推奨されています。
プロジェクトが大きくなって情報量が増えたら、slash command やサブエージェントに切り出す方法を検討してください。

日常ワークフローの例

実際にこのブログの運用で使っている典型的なフローを紹介します。

バグ修正

> ビルドで Warning が出ている。原因を調べて修正して

Claude Code がビルドを実行し、Warning のスタックトレースを読み取り、該当ファイルを特定して修正案を提示します。
修正内容の diff が表示されるので、承認すればそのまま適用されます。

リファクタリング

> src/utils/ にある日付関連のヘルパーが 3 ファイルに散らばっている。1 つに統合して

影響範囲の調査（import の追跡）から、ファイルの統合、既存の参照箇所の書き換えまでを一気に行います。
途中で判断に迷う箇所があれば質問が返ってくるので、対話しながら進められます。

コードレビュー

> git diff main...HEAD の変更をレビューして。セキュリティとパフォーマンスの観点で

ブランチの差分を読んで、問題点を指摘してくれます。
PR を出す前のセルフレビューとして使うと、人間のレビュアーの負荷を減らせます。

まとめ

Claude Code はターミナルから AI エージェントとペアプログラミングできる CLI ツール
.claude/settings.json の permission 設定で安全なコマンドを事前許可し、作業テンポを確保する
CLAUDE.md にプロジェクト文脈を書いておけば、毎セッションの説明コストがなくなる
バグ修正・リファクタリング・コードレビューなど、日常の開発タスクにそのまま組み込める

まずは npm install -g @anthropic-ai/claude-code でインストールし、
既存プロジェクトのディレクトリで claude を起動してみるところから始めるのがおすすめです。

Astro の OGP 画像生成で日本語の改行を自然にする

Sun, 12 Apr 2026 00:00:00 GMT

はじめに

ブログ記事を SNS でシェアしたとき、OGP 画像の有無でクリック率は大きく変わります。
Astro なら satori を使ってビルド時に自動生成する方法がよく使われますが、
Cloudflare Pages にデプロイする日本語ブログではいくつかの罠があります。

このブログで実際に踏んだ問題は次の 2 つです。

sharp が Cloudflare のランタイムで動かない
日本語タイトルが文字単位で折返され、文節の途中で改行される

構成の全体像

最終的に採用したパイプラインは以下の通りです。

flowchart LR
    A["getStaticPaths()"] --> B["satori<br/>HTML → SVG"]
    B --> C["resvg<br/>SVG → PNG"]
    C --> D["dist/og/slug.png"]

ポイントは export const prerender = true を宣言し、
ビルド時に全投稿分の OGP を静的ファイルとして出力する点です。ランタイムでは一切画像生成をしません。

// src/pages/og/[slug].png.ts
export const prerender = true;

export async function getStaticPaths() {
  const posts = await getCollection("posts");
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

記事ページ側では、<meta property="og:image"> に /og/${slug}.png を指定しておけば、
ビルドで生成された静的ファイルがそのまま配信されます。

なぜ sharp ではダメだったのか

Astro の OGP 画像生成で検索すると、多くの記事が satori + sharp の組み合わせを紹介しています。
僕も最初はこの構成でした。

ところが Cloudflare Pages では sharp がランタイムで動きません。
sharp は C++ の native binding に依存しており、Cloudflare の V8 Isolate 環境では実行できないからです。

prerender: true を付ければビルド時（= Node.js 環境）で実行されるため sharp でも動きますが、
この宣言を忘れると Astro は SSR ルート扱いにします。
結果として本番デプロイ後に OGP エンドポイントが 5xx を返し、SNS のクローラーが画像を取得できなくなります。

解決策は sharp を @resvg/resvg-js に置き換えることです。

import { Resvg } from "@resvg/resvg-js";

// satori が返した SVG 文字列を PNG に変換
const resvg = new Resvg(svg, {
  fitTo: { mode: "width", value: 1200 },
});
const png = resvg.render().asPng();

@resvg/resvg-js も native Node binding ですが、
prerender: true と組み合わせることでビルド時にしか実行されないため、ランタイム非対応の問題を回避できます。

なお、native binding を含むパッケージは Astro の server bundle に含まれるとビルドが失敗します。
astro.config.mjs で明示的に除外します。

// astro.config.mjs
vite: {
  ssr: {
    external: ["@resvg/resvg-js", "satori", "satori-html"],
  },
},

日本語タイトルの改行問題

ここまでで OGP 画像は生成できるようになりましたが、日本語ブログ特有の問題が残ります。

satori のテキストレイアウトエンジンは 文字単位 で折返しを判定します。
英語なら単語境界（スペース）で自然に切れますが、日本語にはスペースによる単語区切りがないため、
「渡す」が「渡」と「す」に分断されるような不自然な改行が発生しました。

ZWSP は使えない

最初に試したのは zero-width space（U+200B）を文節境界に挿入して word-break: keep-all と組み合わせる方法でした。
CSS の仕様上これが正攻法ですが、
satori は ZWSP をグリフとして描画してしまい、□（tofu）が表示されるという問題がありました。

budoux で解決

最終的に採用したのは、Google 製の日本語改行ライブラリ budoux です。
budoux は学習済みモデルで日本語の文節境界を推定し、自然な位置で分割してくれます。

アプローチは以下の通りです。

budoux でタイトルを文節に分割する
フォントサイズとコンテナ幅から 1 行あたりの最大文字幅を計算する
文節を貪欲法で行に詰め、上限を超えたら次の行へ送る
各行を個別の <div> として satori に渡す

import { loadDefaultJapaneseParser } from "budoux";

const jpParser = loadDefaultJapaneseParser();

function estimateWidth(text: string): number {
  let w = 0;
  for (const ch of text) {
    w += ch.charCodeAt(0) > 0x7f ? 1 : 0.55;
  }
  return w;
}

function splitTitleIntoLines(title: string, fontSize: number): string[] {
  const maxUnits = (CONTENT_WIDTH / fontSize) * 0.95;
  const phrases = jpParser.parse(title);
  const lines: string[] = [];
  let current = "";

  for (const phrase of phrases) {
    const next = current + phrase;
    if (estimateWidth(next) > maxUnits && current.length > 0) {
      lines.push(current);
      current = phrase;
    } else {
      current = next;
    }
  }
  if (current) lines.push(current);

  return lines;
}

estimateWidth では CJK 文字を幅 1.0、ASCII 文字を 0.55 として近似しています。
行折返しの判定にはこの近似で実用上十分な精度が出るため、正確なグリフ幅測定はしていません。

Before / After

記事タイトル	Before	After
Claude Code にプロジェクト文脈を渡す 4 層構造	`...文脈を渡` / `す 4 層構造`	`...プロジェクト文脈を` / `渡す 4 層構造`
SubCutter - ブラウザ完結の固定費管理PWAを作った	`...完結の固定費` / `管理PWAを作った`	`...ブラウザ完結の` / `固定費管理PWAを作った`

はまりポイントまとめ

prerender: true を忘れると本番で動かない
Cloudflare Pages + Astro の組み合わせでは、native binding を使うエンドポイントには必ず prerender: true を付ける。付け忘れると開発環境では動くのに本番で 5xx になる。
satori は全要素に display: flex が必要
satori のレイアウトエンジンは Yoga ベースで、すべての要素が Flexbox として評価される。display: flex を省略すると予期しないレイアウト崩れが起きる。
satori-html の tagged template は値を HTML エスケープする
html`...${dynamicHtml}...` と書くと dynamicHtml 内の <div> がエスケープされてしまう。動的に生成した HTML を挿入するには、raw 文字列として渡すヘルパーが必要。

まとめ

Astro + Cloudflare Pages で OGP 画像を自動生成するなら、prerender: true + satori + @resvg/resvg-js がビルド時完結で安定する
日本語ブログでは budoux を入れるだけで改行品質が劇的に改善 される。約 30 KB の依存を追加するだけで、全記事の OGP 画像が自然な文節区切りになる
satori 特有の制約（display: flex 必須、ZWSP の tofu 化、satori-html のエスケープ）は事前に知っておくとデバッグ時間を節約できる

まずは自分のブログの OGP エンドポイントに export const prerender = true が付いているか確認するところから始めるのがおすすめです。

Claude Code にプロジェクト文脈を渡す 4 層構造

Sat, 11 Apr 2026 00:00:00 GMT

はじめに

Claude Code を個人プロジェクトで本格的に使い始めると、最初にぶつかるのが「毎回同じ文脈を口頭で説明するのがつらい」という問題です。
リポジトリ直下に CLAUDE.md を置く解決策は既に広く使われていますが、プロジェクトが大きくなるとこの 1 ファイルだけでは足りなくなります。

Claude Code が提供する CLAUDE.md / slash command / subagent / skill の 4 つのレイヤーに役割を分け、
プロジェクト文脈をエージェントへ渡します。例は実際にこのブログで組んだ構成です。

なぜ CLAUDE.md だけでは足りないのか

CLAUDE.md は Claude Code が毎セッションの先頭で必ず読み込む Markdown ファイルです。
プロジェクトのスタック・規約・よく使うコマンドをここに書いておくと、
毎回「この repo は Astro で、pnpm を使って、Biome で整形していて…」と説明しなくて済みます。
常時メモリとして非常に強力です。

しかし単体では 3 つの限界があります。

全セッションの先頭で読まれる
必ず読まれるため、大きくなるほど毎回のトークンを圧迫します。
Claude Code のベストプラクティスでは 200 行以下が目安とされており、これを超えると「読まれているけれど守られない」状態になりがちです。
手続き的なワークフローを書くには冗長
「新規記事を作るときは、まずスラッグを決めて、次に雛形を生成して、フロントマターを書き換えて…」
のような順序依存の作業は、自然言語で羅列しても実行順序を保証できません。
専門的な知識は読み捨てになる危険性
たとえば SEO レビューのような重いチェックリストを CLAUDE.md に書くと、
SEO レビューをしない他のセッションでもトークンを消費してしまいます。

この 3 つを解決するために、残り 3 つのレイヤーを追加します。

4 層の役割分担

層	置き場所	何を書くか	起動契機
CLAUDE.md	リポジトリルート	不変の規約（スタック、ディレクトリ構成、コマンド、コミットスタイル）	毎セッション自動
slash command	`.claude/commands/*.md`	手続き的ワークフロー（雛形生成、特定タスクの手順）	ユーザーが `/command-name` と入力
subagent	`.claude/agents/*.md`	独立した context で動く専門家。長い指示や大量の参照ファイルを抱える	ユーザー指定、または description による自動判断
skill	`.claude/skills/<name>/SKILL.md`	スコープの狭い検証・変換ロジック。progressive disclosure で必要時のみ読まれる	エージェントが必要と判断した時

ポイントは コンテキストの寿命と読まれる頻度 です。
CLAUDE.md は毎回全員が読む共有知識、skill は必要なときだけ特定のエージェントが読むニッチ知識、という使い分けを意識します。

実例: 個人ブログで組んだ構成

今回実装した構成は次の通りです。

blog/
├── CLAUDE.md                          # 113 行。スタック・記事規約・コマンド
└── .claude/
    ├── settings.json                  # permission allowlist
    ├── commands/
    │   └── new-post.md                # /new-post <slug> で記事雛形を生成
    ├── agents/
    │   ├── post-planner.md            # 記事企画とアウトライン生成
    │   └── seo-reviewer.md            # 公開前の SEO レビュー
    └── skills/
        └── frontmatter-check/
            └── SKILL.md               # frontmatter の schema 検証

それぞれが「どの問いに答えるか」を 1 行で言えるように設計してあります。

CLAUDE.md: このブログはどんな規約で書かれているか？
/new-post: 新しい記事を始めるとき、どういう手順を踏むか？
post-planner: このアイデアは記事として成立するか？ outline はどうなるか？
seo-reviewer: この記事は公開に耐えるか？
frontmatter-check: この YAML はスキーマに合っているか？

この 5 つを CLAUDE.md に詰め込もうとすると、確実に 500 行を超えます。
分割したことで CLAUDE.md は 110 行前後で安定し、各エージェントとスキルも 50〜60 行の手ごろなサイズに収まりました。

アイデアを「エージェントが読める形」で保つ

もう 1 つ重要な気付きがあります。
計画や企画書もコードと同じくプロジェクト文脈に含まれる ということです。

このブログでは記事アイデアを docs/blog-post-plan/ 配下で以下のようなファネルで管理しています。

flowchart LR
      A["Inbox<br/>inbox.md"] -->
  B["Backlog<br/>spinoff-candidates.md"]
      B --> C["Active<br/>NN-*.md"]
      C --> D["Posts<br/>src/content/posts/"]

重要なのは、post-planner エージェントの定義ファイルに
「新規企画を受けたら、outline を書く前に必ず inbox.md と spinoff-candidates.md を grep して重複を確認せよ」
という義務を明記している点です。

## Inputs you should always gather

2. **Duplicate check (mandatory)**. Before producing any outline, grep
   both of these for overlapping keywords from the pitch:
   - docs/blog-post-plan/inbox.md
   - docs/blog-post-plan/spinoff-candidates.md
   If you find an overlapping entry, stop and report it before writing
   a new plan.

結果として、企画メモ自体が「エージェントが読みに行く構造化ドキュメント」になり、僕がアイデアの重複を手動でチェックする必要がなくなりました。
アイデア管理が 検索可能なコンテキスト になった感覚です。

運用の勘所

以下は実際に運用して役立ったポイントです。

CLAUDE.md は 200 行を厳守する
200 行を超えた時点で、役割の切り分けに失敗している兆候です。
特定ドメインに深入りした記述や「特定のケースでだけ役立つ手順」が増え始めたら、迷わずサブエージェントかスキルに切り出します。
コマンドとエージェントを混同しない
「手順が決まっている」 → コマンド、「判断が必要」 → エージェント、と分けます。
/new-post は決まったステップの実行なのでコマンドです。SEO レビューは記事ごとの文脈判断が必要なのでエージェント（seo-reviewer）にしています。
この区別を間違えると、エージェントがただの手順書になったり、コマンドが曖昧な判断を抱え込んだりします。
permission の allowlist を先に整える
.claude/settings.json に pnpm lint、pnpm check、git status 等のコマンドを事前承認しておくと、エージェントが毎回承認を求めてきません。
一方で git push --force のような破壊的コマンドは明示的に deny に入れておきます。
これがないと、便利なエージェントほど承認プロンプトで作業が止まります。
Skill は呼ばれないと読まれない
Claude Code の skill は description フィールドで自動判定されるか、
エージェントが明示的に呼んだときに初めて SKILL.md の本文が読み込まれます。
常に読んで欲しい知識は CLAUDE.md に、必要な時だけで十分な知識は skill に
という分離の鉄則を守ると、全体のトークン効率が目に見えて良くなります。

まとめ

CLAUDE.md は「常時読まれる共有規約」、それ以外（commands / agents / skills）は「必要時だけ読まれる専門知識」という区別が設計で一番大事な点
企画書やアイデア帳のような人間向けドキュメントも、エージェントが grep できる構造にすると自動化の対象にできる
個人ブログ規模でもこの 4 層を分けるだけで、毎回のセッションで「最近何書いたっけ」を説明する必要がなくなる
この仕組みは OGP 画像の自動生成のような別の自動化とも相性が良く、エージェントが規約を理解した上で実装を進められる

Claude Code のベストプラクティスは進化が速い領域なので、一度組んだ構成も定期的に見直す前提で運用するのがおすすめです。
まずは CLAUDE.md を 200 行以下に保ちつつ、/new-post のような .claude/commands/ を 1 つ作ってみるところから始めるのが最短です。
その 1 つが動くと、このレイヤリング設計の意味が実感できます。

Dockerコンテナ起動時に「address already in use」エラーが出た話

Mon, 15 Dec 2025 00:00:00 GMT

Dockerコンテナ起動時に以下のエラーが発生した際のメモ。

failed to bind host port for 0.0.0.0:8080:... address already in use

環境

Windows上のWSL2（Ubuntu）

試したこと

まずポートが競合していないか、以下のコマンドで調べた。

WSLで lsof -i:8080 → 何も表示されず
Windows（PowerShell）で netstat -anp | grep 8080 → 何も表示されず
docker ps -a で不要なコンテナがないことを確認

いずれも競合しているプロセスは見当たらなかった。

次にDockerやWSL自体の再起動を試みた。

WSL2の再起動（wsl --shutdown）
Dockerサービスの再起動 (sudo service docker restart)
Dockerネットワークのリセット(docker network prune)

しかしいずれも効果なし。

最終的な対応

PC再起動 でコンテナ起動に成功した。

WindowsのFast Startupなどが影響していたのか、あるいはゾンビプロセスのようなものが残っていたのか、原因は特定できなかった。困ったときは再起動に限る。

SEO と AEO の違い

Sat, 13 Dec 2025 00:00:00 GMT

はじめに

ブログを運営する上で、SEOについて調べていたらAEOという言葉を見かけることが増えてきました。
軽く調べた内容をもとに、SEOとAEOの違いなどをまとめてみます。

SEOとは何か

Search Engine Optimization（検索エンジン最適化）
Google のクローラーが読みやすい構造、検索順位を上げるための取り組み
主な要素
- キーワード最適化
- 内部施策（構造化、内部リンク、サイト速度、UX）
- 外部施策（被リンク、ブランド評価）
- コンテンツ品質（E-E-A-T: Experience, Expertise, Authoritativeness, Trustworthiness）

AEOとは何か

Answer Engine Optimization（回答エンジン最適化）
AIから見つけられるか、AIに選ばれるかを最適化する取り組み
対象の例: ChatGPT、Google Gemini、Perplexity、音声検索（Siri / Alexa / Google Assistant）など
特徴: 検索ではなく回答がゴールになる点が大きな違い

SEOとAEOの違い

項目	SEO	AEO
ゴール	SERP の順位を上げる	AI / 音声アシスタントに`最適な回答`として選ばれる
主体	検索エンジン	回答エンジン（AI、LLM）
最適化対象	検索クエリ・ページ	質問・回答ペア、構造化情報、コンパクトなナレッジ
重要視される点	E-E-A-T、被リンク、テキスト量や網羅性	正確性、簡潔性、文脈理解、構造化（FAQ など）

AEOが注目される理由

AI 検索の普及によりユーザーの流入が変化している
検索エンジンがページ単位で評価するのではなく、情報単位（ナレッジ）で回答を抽出する傾向が強まっている
そのため、自社や自サイトの情報が AI に選ばれる必要が高まっている

AEO対策として効果的な施策

以下は実務で取り入れやすく、効果が期待できる施策です。

ユーザーの質問にシンプルで正確に答えるセクションを設ける

:::note[FAQセクションの例]

### Q. AEO とは何ですか？

AEO（Answer Engine Optimization）とは、AI や音声アシスタントが
ユーザーの質問に答える際に、信頼できる情報源として引用されることを
目的とした最適化手法です。

:::

1 テーマ 1 記事のように、扱うトピックを明確にする
自分の業界を明確に記載する
箇条書き・短文で引用しやすい文章を心がける
- AI が切り出しやすいように、要点は箇条書きや見出しで整理する
出典・根拠を明示して正確性を担保する
- 著者情報や参照リンクを明記し、信頼性を示す

実装上の注意

構造化データは設定を間違えると検索結果の表示が変わってしまうため、Google Rich Results Test 等で検証する
生成 AI での回答が誤情報（hallucination）を起こすことがあるため、必ず人力で検証・注釈を付与する

まとめ

何を目的とした最適化か
- SEO = 検索結果に表示されること
- AEO = AI が直接返す答えの材料として使われること
良質なコンテンツは SEO にも AEO にも有効
今後は検索クエリに最適化するだけでなく質問に最適化する戦略が必要

Astro をローカルで起動するまでの手順まとめ

Fri, 12 Dec 2025 00:00:00 GMT

はじめに

公式ドキュメントをもとに、
Astro の公式ブログテンプレートを使ってローカル環境で起動するまでの手順をまとめています。

前提条件

Node.js: v18.17.1 または v20.3.0 以上（v19 はサポート対象外）
テキストエディタ: VS Code、Astro 公式拡張機能
ターミナル: CLI を利用

node/npm のバージョン確認例

$ node -v
v22.16.0

$ npm -v
10.9.2

プロジェクト作成（手順）

プロジェクト作成コマンドを実行

npm create astro@latest

新規プロジェクトをどこに作成するか
何も入力せず Enter を押すとカレントディレクトリに fast-field という名前で作成される

dir   Where should we create your new project?
      ./fast-field

テンプレートの選択で「Use blog template」を選択（矢印キーで選択）

tmpl   How would you like to start your new project?
      ○ A basic, helpful starter project (recommended)
      ● Use blog template
      ○ Use docs (Starlight) template
      ○ Use minimal (empty) template

依存関係のインストールで「Yes」を選択

deps   Install dependencies? (recommended)
      ● Yes  ○ No

Git 初期化は「No」を選択

git   Initialize a new git repository? (optional)
      ○ Yes  ● No

初期化完了後、プロジェクトディレクトリに移動して開発サーバーを起動する

cd ./fast-field
npm run dev

参考画像：

ローカルサーバー起動の確認

起動ログの例:

> fast-field@0.0.1 dev
> astro dev

astro  v5.16.5 ready in 640 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

watching for file changes...

ブラウザで http://localhost:4321/ を開くと、Astro のブログテンプレートが表示されます。

テーマや追加リソース

公式テーマ以外にも、Astro のテーママーケットプレイスから様々なテーマを探せます。
無料テーマを探す場合の参考リンク：Themes | Astro

まとめ

npm create astro@latest でテンプレートからプロジェクト作成
プロジェクト名・テンプレート・依存インストール・git 初期化をプロンプトで選択
プロジェクトのディレクトリに移動して npm run dev でローカルサーバーを起動し、http://localhost:4321/ を確認

REST Clientの使い方 - VSCodeで簡単にAPIリクエスト

Sun, 07 Dec 2025 00:00:00 GMT

概要

REST Client は Visual Studio Code 上で HTTP リクエストを送信し、レスポンスを直接確認できる拡張機能です。
API 開発や検証を VSCode 内で完結できます。

導入

VSCode の拡張機能一覧から REST Client をインストール
拡張子 .http または .rest のファイルを作成

基本的な使用方法

GET リクエスト

作成したファイルに以下のように記述し、Send Request リンクをクリックしてリクエストを送信します。

GET https://jsonplaceholder.typicode.com/posts/1

POST リクエスト

POST リクエストも同様に記述できます。
データは JSON 形式で送信できます。

POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{
  "title": "foo",
  "body": "bar",
  "userId": 1
}

複数リクエスト

### で区切ると、1 つのファイルに複数のリクエストを定義できます。

### GET
GET https://jsonplaceholder.typicode.com/posts/1

### POST
POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{
  "title": "bar",
  "body": "baz",
  "userId": 2
}

複数リクエストがある場合、Send Request リンクがそれぞれのリクエストごとに表示されます。

:::caution ### を使わずにリクエストを連続して書いた場合、 Send Request リンクが1つしか表示されません

GET https://jsonplaceholder.typicode.com/posts/1

POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{
  "title": "bar",
  "body": "baz",
  "userId": 2
}

:::

変数の利用

環境ごとに異なる URL やトークンを変数として定義し、使い回すことができます。

定義

@baseUrl = https://jsonplaceholder.typicode.com
@userId = 1

利用

GET {{baseUrl}}/posts/{{userId}}

@baseUrl = https://jsonplaceholder.typicode.com
@userId = 1

### GET
GET {{baseUrl}}/posts/{{userId}}

### POST
POST {{baseUrl}}/posts
Content-Type: application/json

{
  "title": "bar",
  "body": "baz",
  "userId": 2
}

認証付きリクエスト

認証が必要な API も簡単にリクエストを送信できます。

Bearer Token

@token = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

GET https://api.example.com/users/me
Authorization: Bearer {{token}}

利用シーン

API 開発中の動作確認
外部 API の動作検証
ドキュメントに記載された API の動作確認

補足

サンプルには JSONPlaceholder を利用しています。
JSONPlaceholder はモック API サービスで、GET/POST/PUT/DELETE などの HTTP リクエストを試すことができます。

Seu Dev Notes

f-string の書式指定まとめ（桁揃え・ゼロ埋め・日付）

1. 桁揃え

2. ゼロ埋め

3. カンマ区切り

4. 小数の桁数

5. 日付

組み合わせると表になる

おまけ: デバッグ用の =

まとめ

Pandas で and が使えず & が要る理由

and は「全体で 1 つ」を求める

& は「行ごとに 1 つ」

まとめ

Pythonでサッカー分析を学ぼうとしたら、無料のxGが消えていた

2026年1月20日に何が起きたか

半年後の今も戻っていない

代替を実際に叩いて確かめた

Understat —— xG が要るならまずここ

StatsBomb Open Data —— イベント単位で学ぶなら

football-data.co.uk —— xG はないが手軽

学習目的ならどう組むか

まとめ

指でなぞると凍る画像モザイク——端末内完結のプライバシー PWA を作った

なぜ作ったか

何ができるのか

端末の外に画像を出さない

使い方は「読み込んで、なぞって、保存」

モザイクと氷霜ガラスの 2 モード

インストール不要、オフラインでも動く

まずサンプルで試す

Go の RE2 でストリーミングフィルタを安全に書く

はじめに

RE2 が線形時間である理由

FindAllStringSubmatchIndex を使うパターン

bufio.Scanner で行単位に流す

複数パターンをまとめて適用する

マルチライン対応のバッファリング

ベンチマークで線形性を確認する

まとめ

Cloudflare Workers とは何か：エッジ実行環境の基礎

はじめに

V8 Isolate モデル

リクエストライフサイクル

waitUntil で非同期処理を後回しに

Bindings で外部リソースを注入する

実行時間とリソース制限

デプロイ

Node.js と何が違うか

まとめ

Cloudflare Pages とは何か：静的サイトホスティングの実力

はじめに

基本的な仕組み

プロジェクトの作成

ダッシュボードから

CLI から

ブランチプレビュー

カスタムドメイン

ビルド設定のカスタマイズ

環境変数

ビルドキャッシュ

Pages Functions

他サービスとの比較

まとめ

uv で Python 環境構築を爆速にする

はじめに

インストール

Python 自体のインストール

プロジェクトの初期化

パッケージのインストール

pip からの移行

スクリプトの実行

インラインスクリプト

ツールの実行

pip / poetry との比較

まとめ

Cloudflare を無料枠だけで運用する実践ガイド

はじめに

無料枠の上限一覧

構成パターン

おまけ: デバッグ用の `=`

画面共有で `env` を叩いてヒヤッとしたことがある