怠惰ローカルブログ

WaylandでモニターがマイクとスピーカーとしてOSに認識される問題をWirePlumberで無効化する

Sat, 11 Apr 2026 00:00:00 +0900

問題

ふとDesktopの画面を見るとモニターがマイクとスピーカーとしてOSに認識されていた。誤って爆音で音が再生されるリスクが気になったため無効化することにした。ついでにマイクも有効にする意味がない環境だったので止めた。

純粋な開発PCで動画とかも見ないそこそこ特殊？な環境なので最悪読み込まないなら何でもいい状態。

環境

OS: ArchLinux
サウンドサーバー: PipeWire + WirePlumber 0.5.14
GPU: AMD Ryzen（APU）
問題のデバイス: AMD/ATI Raven/Raven2/Fenghuang HDMI/DP Audio Controller

原因

HDMI/DisplayPortには映像だけでなく音声も伝送できる仕様（Audio over HDMI）がある。 LinuxはこれをALSAレベルで別サウンドカードとして認識するため、 PipeWireがそのまま拾ってオーディオデバイスとして公開してしまう。

調査

認識されているカードを確認

pactl list cards short

49      alsa_card.pci-0000_04_00.1      alsa
50      alsa_card.pci-0000_04_00.6      alsa

2枚のサウンドカードが認識されている。詳細を確認する。

pactl list cards | grep -A 30 "alsa_card.pci-0000_04_00"

結果を整理すると：

PCI アドレス	ベンダー	説明	用途
`0000:04:00.1`	AMD/ATI	Raven HDMI/DP Audio Controller	モニター側（不要）
`0000:04:00.6`	AMD + Realtek ALC269VB	Ryzen HD Audio Controller	本物のオンボードサウンド

0000:04:00.1 の alsa_mixer_name が ATI R6xx HDMI であることからも、これがHDMI経由のオーディオデバイスだと確定できる。

AdGuard HomeをProxmox LXCに立ててTailscale経由でDNSブロックする

Mon, 06 Apr 2026 07:00:00 +0900

概要

はてな匿名ダイアリーとウーバーイーツをインフラレベルで封鎖したかった。 AdGuard HomeをProxmox LXCに立てて、Tailscale経由でDNSブロックする構成を作った。

環境

Proxmox VE
Tailscale導入済み
AdGuard Home v0.108.0

手順

1. AdGuard Home LXCをスクリプト一発で作成

Proxmoxのノードシェルで以下を実行する。

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/adguard.sh)"

community-scripts/ProxmoxVEが提供するスクリプト。 LXCのコンテナ作成からAdGuard Homeのインストールまで全自動でやってくれる。

デフォルト構成はDebian 13、CPU 1コア、RAM 512MB、HDD 2GB。DNS用途なら十分。

2. LXCにTUNデバイスを追加する

TailscaleはWireGuardベースのVPNで、動作に/dev/net/tunが必要。

/dev/net/tunはLinuxの仮想ネットワークデバイス（TUNデバイス）。通常のネットワークデバイス（eth0等）は物理NICに紐づいているが、TUNはソフトウェアで作った仮想NIC。

Tailscaleは以下の流れで通信を処理する。

通信をTailscaleプロセスが横取り
WireGuardで暗号化
暗号化したパケットを相手に送る

この「横取り」の実装に/dev/net/tunを使う。TUNデバイスを通してカーネルのネットワークスタックとTailscaleプロセスがやり取りする仕組みになっている。

unprivileged LXCはセキュリティ上の理由でホストのデバイスに触れないようになっているため、明示的に/dev/net/tunをコンテナに見せてあげる必要がある。

Proxmoxのノードシェルで以下を実行してTUNを有効化する。

pct stop 106
echo "lxc.cgroup2.devices.allow: c 10:200 rwm" >> /etc/pve/lxc/106.conf
echo "lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file" >> /etc/pve/lxc/106.conf
pct start 106

106の部分は自分のLXCのIDに置き換える。IDはpct listで確認できる。

3. LXCにTailscaleを入れる

LXCのシェルに入って以下を実行する。

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up

認証URLが表示されるのでブラウザで開いてログインする。認証後、TailscaleのMachines画面からAdGuard HomeのTailscale IPを確認しておく。

ArchLinuxのThunarでWalkmanのFSを開く

Sat, 04 Apr 2026 17:00:00 +0900

背景

手持ちのWalkmanをLinux（Arch Linux）環境で活用したいと考えた。単に音楽を聴くだけでなく、PCのファイルを転送したり、時にはPCの音を高音質で鳴らすオーディオインターフェースとして使いこなすのが目的だ。

ドキュメントを読む限り、最近のデバイスはMTP（Media Transfer Protocol）に対応しており、Linuxでも標準的なツールで扱えるはずだ。

環境

OS: Arch Linux
File Manager: Thunar
Device: Walkman (MTP/USB DAC対応モデル)
Tools: usbutils, gvfs-mtp, libmtp, jmtpfs

ThunarでWalkmanのFSが見えない

WalkmanをUSBケーブルでPCに接続し、Thunarを開いたがサイドバーには何も表示されない。

まず物理的な接続を確認しようと lsusb を叩いたところ、コマンド自体が入っていなかった。

sudo pacman -S usbutils

改めて確認する。

$ lsusb
Bus 001 Device 008: ID 054c:0c2f Sony Corp. Walkman

デバイス自体はUSBレベルでは認識されている。fdisk -l にブロックデバイスとして出てこないのはMTPなので当然だ。

原因：MTP用ライブラリが未インストール

gvfs-mtp と libmtp が入っていないのが原因だった。

sudo pacman -S gvfs-mtp libmtp

# Thunarを再起動して反映
thunar -q

これでThunarのサイドバーにWalkmanが表示され、GUIでファイルをコピーできるようになった。

補足：USB DACモードとは

調査中に「DACモードでなければ動かないのか？」と気になって調べたのでここにまとめておく。

USB DACモードとは、デバイスを「ストレージ」としてではなく、**「USBオーディオデバイス」**としてPCに認識させるモードだ。ファイル転送には使えない。

モード	PCからの見え方	用途
MTP / MSC	ストレージ	ファイル転送
USB DAC	オーディオデバイス	PC音声出力

Walkman側の設定でどちらのモードになっているかは確認しておく必要がある。

Canvas 2D API でピクセルアートタイルを「手書き」する実装テクニック

Tue, 31 Mar 2026 09:00:00 +0900

Canvas 2D API でピクセルアートタイルを「手書き」する実装テクニック

1. 概要

Web ゲーム開発、特にローグライクやタクティカル RPG を開発する際、避けて通れないのが「マップの描画」だ。通常、これらは「タイルセット」と呼ばれる画像ファイルを読み込んで描画するが、開発の初期段階や、あえて外部アセットに頼りたくない場合、Canvas 2D API を使ってプログラムで直接タイルを描画する「手書き（プログラマティック描画）」の手法が非常に強力な武器になる。

本記事では、HTML5 Canvas の fillRect や beginPath などの基本命令のみを使い、擬似的なピクセルアート風のタイルを描画するテクニックを解説する。画像を用意する手間を省きつつ、動的に色や形状を変更できる柔軟な描画システムを構築しよう。

2. タイル描画の基本構造

まずは、どのようなタイルでも共通して利用できる描画の入り口を作る。ピクセル座標ではなく、タイル座標（x, y）とタイルサイズ（tileSize）を受け取る設計にすることで、グリッドベースのシステムと統合しやすくなる。

/**
 * タイルを描画するメイン関数
 * @param {CanvasRenderingContext2D} ctx - Canvasコンテキスト
 * @param {string} tileType - タイルの種類 ('wall', 'floor', 'grass', etc.)
 * @param {number} x - タイルのX座標（グリッド単位）
 * @param {number} y - タイルのY座標（グリッド単位）
 * @param {number} tileSize - 1タイルのピクセルサイズ
 * @param {string} fieldType - フィールドの種類 ('meadow', 'forest', 'mountain')
 */
function drawTile(ctx, tileType, x, y, tileSize, fieldType = 'meadow') {
    const px = x * tileSize;
    const py = y * tileSize;

    ctx.save();
    ctx.translate(px, py);

    switch (tileType) {
        case 'floor':
            drawFloor(ctx, tileSize, fieldType);
            break;
        case 'wall':
            drawWall(ctx, tileSize, fieldType);
            break;
        case 'object_grass':
            drawFloor(ctx, tileSize, fieldType);
            drawGrass(ctx, tileSize);
            break;
        case 'object_tree':
            drawFloor(ctx, tileSize, fieldType);
            drawTree(ctx, tileSize);
            break;
        case 'stairs_down':
            drawFloor(ctx, tileSize, fieldType);
            drawStairs(ctx, tileSize, false);
            break;
        default:
            ctx.fillStyle = '#333';
            ctx.fillRect(0, 0, tileSize, tileSize);
    }

    ctx.restore();
}

この設計のポイントは、ctx.translate を使ってタイルの左上を原点 (0, 0) に固定することだ。これにより、各タイルの描画ロジック内で座標計算を簡略化できる。

TypeScript Union 型でスキルのレンジ種別とダメージ計算を型安全に実装する

Sat, 28 Mar 2026 17:00:00 +0900

TypeScript Union 型でスキルのレンジ種別とダメージ計算を型安全に実装する

ゲーム開発、特に RPG やタクティカルゲームにおいて、スキルの「射程（レンジ）」や「効果範囲（AOE: Area of Effect）」の実装は非常に複雑になりがちです。単体攻撃、直線、周囲、円形、さらには自分自身を対象とするものまで、そのバリエーションは多岐にわたります。

これらを string 型の ID や、大量の if 文、あるいは複雑なクラス継承で管理しようとすると、いつか必ず「新しいレンジを追加したのに、判定処理を書き忘れた」あるいは「このスキルタイプには不要なはずのパラメータが混入している」といったバグに直面します。

TypeScript の Union 型（特に Discriminated Union / 判別可能な共用体） を活用すれば、こうしたロジックをコンパイルレベルで安全に保護し、設計意図をコードに焼き付けることができます。本記事では、架空のゲームを題材に、any や as を一切使わずに、メンテナンス性の高いスキルシステムを構築する手法を徹底解説します。

1. Union 型でスキル種別を表現する

まず、スキルの「レンジ（範囲）」を型として定義します。ここでのポイントは、単に名前を列挙するのではなく、「そのレンジを計算するために最低限必要なデータ」をセットにすることです。

なぜこの設計にするのか（データ構造の純粋性）

オブジェクト指向的な発想では、BaseRange クラスを継承して AreaRange クラスを作る、といった方法が取られがちです。しかし、ゲームデータ（特に JSON などでシリアライズされるデータ）を扱う場合、純粋なオブジェクト（POJO）として扱える方がシリアリアライズの相性が良く、ロジックを分離（疎結合）しやすくなります。

// 1. 各レンジの個別定義
type MeleeRange = { 
  type: 'melee' 
}; // 隣接マス（1マス）

type RangedRange = { 
  type: 'ranged'; 
  distance: number 
}; // 遠距離（単体指定）。最大射程が必要。

type LineRange = { 
  type: 'line'; 
  length: number;
  width?: number; // オプションで太さを持たせることも可能
}; // 直線。貫通距離が必要。

type AreaRange = { 
  type: 'area'; 
  radius: number; 
  excludeCenter?: boolean 
}; // 円形または四角形範囲。半径が必要。

type SurroundRange = { 
  type: 'surround' 
}; // 自分の周囲8マス。パラメータ不要。

type SelfRange = { 
  type: 'self' 
}; // 自分自身。パラメータ不要。

// 2. これらを統合した Union 型（Discriminated Union）
export type SkillRange =
  | MeleeRange
  | RangedRange
  | LineRange
  | AreaRange
  | SurroundRange
  | SelfRange;

// 3. スキルの全体定義
export interface Skill {
  id: string;
  name: string;
  description: string;
  range: SkillRange; // 型安全なレンジ定義
  baseDamage: number;
  scalingStat: 'STR' | 'INT' | 'DEX'; // どのステータスに依存するか
  manaCost: number;
}

このように type という「タグ（判別子）」を持たせることで、TypeScript は「type が 'area' なら radius プロパティが確実に存在する」と認識します。逆に、'melee' の時には radius にアクセスしようとするとコンパイルエラーになります。これにより、不必要なデータへの依存を完全に排除できます。

ターン制戦闘をフィールドに統合する vs 専用画面に分ける：設計比較と判断基準

Sat, 28 Mar 2026 16:00:00 +0900

ターン制戦闘をフィールドに統合する vs 専用画面に分ける：設計比較と判断基準

ターン制RPGを開発する際、エンジニアが最初に直面する大きな設計判断の一つが「戦闘をどこで行うか」です。具体的には、不思議のダンジョンのように**フィールド上でそのまま戦う（フィールド統合型）のか、ドラゴンクエストのように専用の戦闘画面に遷移する（専用画面型）**のか、という選択です。

この選択は単なるビジュアルの違いに留まらず、状態管理（State Management）、当たり判定、AIの実装、そしてスケーラビリティに決定的な影響を与えます。本稿では、TypeScriptを用いた架空のゲームの実装例を交えながら、両アプローチの設計思想と判断基準を深く掘り下げます。

1. 2つのアプローチの比較

まずは、それぞれの特性をトレードオフの観点から整理します。

項目	フィールド統合型 (Seamless)	専用画面型 (Isolated)
UXの印象	テンポが良い、空間の繋がりを感じる	演出が豪華、戦略に集中できる
状態管理	非常に複雑（フィールド＋戦闘の混合）	比較的単純（画面ごとにStateを全入れ替え）
位置情報の意味	極めて重要（射程、視線、逃走経路）	抽象的（前衛・後衛、ターゲット選択）
AIの実装コスト	高い（地形考慮、パス検索が必要）	低い（コマンド選択アルゴリズムに集中）
拡張性	難しい（新しいギミックが戦闘に影響する）	容易（戦闘専用の特殊ルールを作りやすい）

2. フィールド統合型の実装：空間と時間の同期

フィールド統合型（ローグライク方式）では、「移動」と「攻撃」が同じタイムライン上で扱われます。

なぜその設計にするか

プレイヤーが「一歩動く」ことと「剣を振る」ことが同等のコスト（1ターン）を持つため、戦略が空間的になります。壁を背にする、通路に誘い込むといった地形利用が自然にゲームプレイに組み込まれるのが最大のメリットです。

アクション設計の例

TypeScriptでのアクション定義は以下のようになります。

type FieldAction =
  | { type: 'FIELD_PLAYER_MOVE'; direction: Vector2 }
  | { type: 'FIELD_PLAYER_ATTACK'; targetId: string }
  | { type: 'FIELD_MONSTER_TURN_START' }
  | { type: 'FIELD_DAMAGE_ENTITY'; entityId: string; amount: number }
  | { type: 'FIELD_KILL_MONSTER'; monsterId: string };

interface FieldState {
  player: Player;
  monsters: Record<string, Monster>;
  tiles: TileMap;
  turnOwner: 'PLAYER' | 'MONSTER';
  animations: AnimationQueue;
}

実装のポイント

この形式では、Reducer が非常に巨大になりがちです。なぜなら、「移動した結果、トラップを踏み、そのダメージでHPが0になり、死亡処理が走る」という一連の連鎖（Side Effects）を、同一のグリッド座標系で計算しなければならないからです。

const fieldReducer = (state: FieldState, action: FieldAction): FieldState => {
  switch (action.type) {
    case 'FIELD_PLAYER_ATTACK':
      const monster = state.monsters[action.targetId];
      if (!monster) return state;

      // 距離計算が必須
      const dist = calculateDistance(state.player.pos, monster.pos);
      if (dist > state.player.range) return state;

      return {
        ...state,
        // 戦闘結果を直接フィールドの状態に反映
        monsters: {
          ...state.monsters,
          [action.targetId]: { ...monster, hp: monster.hp - state.player.atk }
        },
        animations: [...state.animations, { type: 'SLASH', pos: monster.pos }]
      };
    // ...
  }
};

3. 専用画面型の実装：コンテキストの分離

専用画面型（エンカウント方式）では、戦闘が開始された瞬間にフィールドのコンテキストがシリアライズされ、独立した「戦闘エンジン」に制御が移ります。

React で作る堅牢なゲームセーブシステム：localStorage と Reducer を疎結合に保つ設計

Sat, 28 Mar 2026 15:00:00 +0900

React で作る堅牢なゲームセーブシステム：localStorage と Reducer を疎結合に保つ設計

ゲーム開発において、プレイヤーの進行状況を保存する「セーブ / ロード」は最も重要な機能の一つです。Web ブラウザで動作する React アプリケーションの場合、最も手軽な保存先は localStorage です。

しかし、単純に localStorage.setItem をコードのあちこちに散りばめてしまうと、テスタビリティが低下し、データ構造の変更（スキーマ変更）に弱いシステムになってしまいます。

本記事では、架空の RPG 『React Odyssey』を例に、SavePort インターフェースと Reducer の初期化関数を組み合わせた、クリーンで堅牢なセーブ / ロードの実装方法を解説します。

1. 概要：なぜ「直接 localStorage」を避けるのか

React の useReducer を使ったゲーム開発では、ゲームの状態（State）は一つの大きなオブジェクトとして管理されます。これを JSON.stringify して localStorage に保存するのは簡単です。

しかし、以下の理由から、ロジックの中に直接 localStorage を書くべきではありません。

副作用の分離: Reducer は純粋関数であるべきです。セーブ処理（副作用）を Reducer の中に入れることはできません。
環境非依存: 将来的に保存先を IndexedDB やクラウド（Firebase 等）に変更したくなったとき、コードを大幅に書き換える必要が出てきます。
テストのしやすさ: localStorage が存在しない Node.js 環境（Vitest 等）でロジックのテストを行う際、モック化が容易である必要があります。

これらを解決するために、Dependency Inversion Principle（依存性逆転の原則） に基づいた設計を採用します。

2. SavePort 設計：抽象化の定義

まずは、ゲームエンジン側が必要とする「セーブ機能」のインターフェースを定義します。これを SavePort と呼びます。

// domain/save/save-port.ts

/** 
 * 保存されるデータの構造（スキーマ）
 * ゲームの現在の状態に加え、メタ情報を付与する
 */
export interface SaveData {
  version: number;        // セーブデータのバージョン
  timestamp: string;      // 保存日時
  state: GameState;       // 実際のゲーム状態
}

/**
 * セーブ/ロードに関する抽象インターフェース
 */
export interface SavePort {
  /** データを保存する */
  save(data: SaveData): Promise<void>;

  /** データを読み込む。存在しない場合は null を返す */
  load(): Promise<SaveData | null>;

  /** セーブデータが存在するか確認する */
  exists(): Promise<boolean>;

  /** セーブデータを削除する */
  clear(): Promise<void>;
}

なぜインターフェースにするのか？ ゲームのメインロジック（UseCase）は、この SavePort を通じて読み書きを行います。この時点では「どうやって保存するか」は知らなくてよく、「保存できる」という事実だけに依存させます。

Reducer パターンだけでゲーム状態を管理する：副作用ゼロのアーキテクチャ

Sat, 28 Mar 2026 14:00:00 +0900

Reducer パターンだけでゲーム状態を管理する：副作用ゼロのアーキテクチャ

概要

現代のフロントエンド開発において、Redux や React の useReducer を通じて「Reducer パターン」は広く浸透しました。しかし、このパターンを本格的なゲーム開発、特に複雑なロジックが絡み合う RPG やシミュレーションゲームに適用しようとすると、多くの開発者が「副作用」の壁にぶつかります。

「ダメージ計算に乱数を使いたい」「ゲーム内の経過時間を管理したい」「マスターデータを参照したい」……。

これらの要素を素直に実装すると、Reducer の外側にある状態や関数に依存してしまい、純粋関数としての美しさとテストのしやすさが失われてしまいます。

本記事では、すべての副作用を引数として注入し、gameReducer(state, action, masters, random) という純粋関数のみでゲームの全ロジックを完結させる「副作用ゼロ」のアーキテクチャについて解説します。

課題：なぜゲーム開発で Reducer は敬遠されるのか

一般的な Web アプリケーションの Reducer は単純です。「ボタンを押したらフラグを反転させる」「入力された文字列を状態に保存する」といった操作がメインだからです。

しかし、ゲームでは以下のような「非決定的な要素」や「巨大な静的データ」が頻繁に登場します。

1. 乱数 (Randomness) の扱い

クリティカルヒットの判定、モンスターのドロップアイテム、マップの自動生成など、ゲームは乱数の塊です。Reducer の中で Math.random() を呼んだ瞬間、その関数は「同じ入力に対して同じ出力を返す」という純粋性を失います。

2. 静的データ (Master Data) の参照

モンスターのステータス表、アイテムの定義、スキル効果など、ゲームには膨大な「変わらないデータ」があります。これを Reducer の外にあるグローバル変数から参照すると、テスト時にそのグローバル変数の状態も気にしなければならなくなります。

3. 時刻 (Time) と経過の管理

「3時間経過したらスタミナが回復する」「夜になるとモンスターが強くなる」といった時間依存の処理です。new Date() を Reducer で使うのは、乱数と同様に純粋性を破壊します。

4. 非同期処理 (Async/Fetch)

サーバーから最新のイベント情報を取得したり、セーブデータをロードしたりする処理です。Reducer は同期的に実行される必要があるため、非同期処理をそのまま中に書くことはできません。

OOP（オブジェクト指向）との比較

クラスベースの OOP では、player.attack(monster) のようにメソッドを呼び出します。これは直感的ですが、内部で this.hp -= damage のように状態を直接書き換えます（ミュータブル）。小規模なら良いですが、プロジェクトが大きくなり「攻撃時にスキルが発動し、その効果で回復し、さらにログに記録し……」と連鎖が始まると、どこで何が起きたかを追跡するのが不可能になります。

設計：副作用を「引数」に封じ込める

副作用を排除するための解決策はシンプルです。「必要なものはすべて外から渡す」、つまり依存性の注入 (DI) です。

React + Canvas 2D API で作るターン制ローグライク：論理と描画を切り離す設計

Sat, 28 Mar 2026 13:00:00 +0900

React + Canvas 2D API で作るターン制ローグライク：論理と描画を切り離す設計

React でゲームを作る際、多くの開発者が最初に直面するのが「DOM で描画するか、Canvas で描画するか」という選択です。特に数千枚のタイルや多数のユニットが登場するローグライクゲームでは、DOM 要素の管理はすぐにパフォーマンスの限界に達します。

本稿では、React の強力な状態管理（useReducer）と、Canvas 2D API の命令的な描画を組み合わせ、滑らかなアニメーションを実現しつつ堅牢なゲームロジックを維持する設計手法について解説します。

1. 概要：なぜ React と Canvas を組み合わせるのか

React は「宣言的」な UI 構築に長けていますが、毎秒 60 回の頻度で数千の DOM 要素を更新するような動的な描画には向いていません。一方で、Canvas は「命令的」であり、ピクセル単位での高速な描画が可能ですが、状態と描画の同期を自分で行う必要があります。

この二つの「いいとこ取り」をするのが、「ロジックは React（useReducer）で、描画は Canvas で」 という役割分担です。

本記事で構築するアーキテクチャ

Core Logic (useReducer): ゲームの「真実の状態（State of Truth）」を管理。ターン単位で離散的に変化する座標などを扱う。
Render Loop (requestAnimationFrame): Canvas 上で毎フレーム実行される描画処理。
Interpolation (補完): 離散的な論理座標を、滑らかな描画座標へと変換するローカル状態管理。

2. 設計判断：論理座標と描画座標の分離

ローグライクゲームは基本的に「ターン制」です。プレイヤーが右に移動したとき、内部データ（Core State）では x: 10 から x: 11 へと一瞬で書き換わります。しかし、これをそのまま描画すると、キャラクターがワープしたように見えてしまいます。

滑らかな移動（アニメーション）を実現するためには、以下の二種類の状態を明確に分ける必要があります。

なぜ分離が必要か

種類	管理場所	特徴	役割
論理座標 (Logical Position)	`useReducer` (Global)	整数（タイル単位）。	当たり判定、AI、クエスト進行など。
描画座標 (Visual Position)	Canvas 内の Actor クラス (Local)	小数点を含むピクセル単位。	滑らかな移動、揺れ、エフェクト。

判断理由： Core State にアニメーションの「途中経過（x: 10.2 など）」を持たせてしまうと、ゲームロジックが描画の都合に汚染されます。例えば、「まだ移動アニメーション中だから攻撃はできない」といった判定をロジック層で書く必要が出てき、コードが複雑化します。ロジック層は常に「今は（論理的に）どこにいるか」だけを知っていれば良いのです。

乱数を interface で抽象化してゲームロジックをテスタブルにする

Sat, 28 Mar 2026 12:00:00 +0900

乱数を interface で抽象化してゲームロジックをテスタブルにする

概要

ゲーム開発において、「運」の要素は面白さを生む不可欠なスパイスです。クリティカルヒット、レアアイテムのドロップ、ダンジョンの自動生成など、多くの場面で乱数が使われます。

しかし、プログラミングの文脈において、乱数は「不確実性」そのものであり、ユニットテストの天敵です。本記事では、TypeScript を用いて乱数をインターフェースで抽象化し、テスト時に決定論的な（結果が予測可能な）挙動をさせる設計パターンについて解説します。

課題：`Math.random()` がもたらす「テスト不能」という病

もっとも素浦に実装すると、ゲームロジックの中で直接 Math.random() を呼び出すことになります。

// 直接 Math.random() を使う例
export class CombatService {
  calculateDamage(baseDamage: number, critRate: number): number {
    // 運が悪ければテストが落ちる
    if (Math.random() < critRate) {
      return baseDamage * 2;
    }
    return baseDamage;
  }
}

このコードをテストしようとすると、以下の問題に直面します。

非決定的 (Non-deterministic) なテスト: 同じ入力に対して、実行するたびに結果が変わる可能性があります。
境界値のテストが困難: 「クリティカル率 5% のとき、0.049 を引いたらクリティカル、0.051 を引いたら通常攻撃」という境界値の検証が運任せになります。
モックの乱立: vi.spyOn(Math, 'random') などでグローバルなオブジェクトを書き換える手法もありますが、並列テストで干渉したり、クリーンアップを忘れると他のテストに影響を与えたりと、脆いテストになりがちです。

設計：Port / Adapter パターンによる抽象化

この問題を解決するために、Dependency Inversion Principle (依存性逆転の原則) を適用します。

ロジックが「具体的な乱数生成器」に依存するのではなく、抽象的な「乱数提供インターフェース」に依存するように設計を変更します。

1. Port (Interface) の定義

ロジックが必要とする「乱数を得るための窓口」を定義します。

2. Adapter (Implementation) の実装

Production Adapter: 本番環境では Math.random() を使う。
Test Adapter: テスト環境では、事前に定義した値を返したり、シード値に基づいた再現性のある乱数を返す。

この設計にすることで、ロジック側は「誰がどうやって乱数を作っているか」を気にせず、「乱数がもらえること」だけを約束された状態になります。

TypeScript npm workspaces でゲームロジックを UI から完全分離する

Sat, 28 Mar 2026 11:00:00 +0900

TypeScript npm workspaces でゲームロジックを UI から完全分離する

概要

モダンなフロントエンド開発、特にゲーム開発において、「ロジック」と「表示（UI）」の分離は永遠の課題です。React や Vue などのフレームワークにロジックが密結合してしまうと、テストが困難になり、将来的に別のプラットフォーム（例えば Web から React Native や CLI ツールへ）に展開する際の大きな障害となります。

本記事では、TypeScript npm workspaces を活用して、ゲームロジックを独立したパッケージ (packages/core) として切り出し、React UI (apps/client) から完全に分離する設計手法を解説します。また、外部 I/O や非決定的な処理（乱数など）を抽象化する Port / Adapter パターンについても触れます。

課題：なぜロジックが UI に染み出すのか？

多くのプロジェクトでは、気づかないうちにロジックが React コンポーネントや Hooks の中に漏れ出していきます。

// 密結合な例
const PlayerStats = () => {
  const [hp, setHp] = useState(100);

  const handleAttack = () => {
    // UI の中で計算ロジックが動いている
    const damage = Math.floor(Math.random() * 10) + 5;
    setHp(prev => Math.max(0, prev - damage));
  };

  return <button onClick={handleAttack}>攻撃を受ける</button>;
};

このような設計には以下の課題があります：

テストの困難さ: Math.random() が直接使われているため、結果が不安定でユニットテストが書きにくい。
再利用性の欠如: この「ダメージ計算ロジック」を、サーバーサイドや別の UI フレームワークで使い回すことができない。
依存の混入: ロジックを動かすために React の実行環境（レンダリングサイクル）が必要になる。

設計：npm workspaces による物理的隔離

ロジックを「物理的に」隔離するために、以下の monorepo 構成を採用します。

AI コーディングエージェントを飼い慣らす：最強の「AGENTS.md」の書き方

Sat, 28 Mar 2026 10:00:00 +0900

AI コーディングエージェントを飼い慣らす：最強の「AGENTS.md」の書き方

近年、Gemini、Claude、Aider といった「自律型 AI コーディングエージェント」が開発現場に浸透しつつあります。彼らは指示一つでファイル構成を理解し、コードを書き、テストを実行して修正まで行います。

しかし、エージェントを使い始めた多くのエンジニアが直面するのが、**「AI エージェントの暴走」**です。

型定義を面倒くさがって any を連発する
プロジェクト独自のディレクトリ構造を無視して勝手に utils/ を作る
vitest --watch などの終了しないコマンドを叩いてフリーズする
指示していないリファクタリングを始めて関係ないファイルを壊す

これらの問題を防ぎ、エージェントを「熟練のペアプロ相手」に変える魔法のファイル、それが AGENTS.md です。本記事では、AI エージェントに守らせるべきルールを定義する AGENTS.md の書き方と、その設計思想を徹底解説します。

なぜ `AGENTS.md` が必要なのか

AI エージェントは、人間が数年かけて培った「プロジェクトの阿吽の呼吸」を知りません。エージェントに与えられるコンテキスト（ファイル内容や履歴）は有限であり、その中で彼らは「最も確率的に正しそうな推論」を行います。その結果、彼らはしばしば**「最も楽な道（＝技術的負債を生む道）」**を選んでしまいます。

AGENTS.md をプロジェクトのルートに配置する理由は、**「エージェントの推論空間に強制的な制約（ガードレール）を設けるため」**です。

なぜその設計にしたか：外部メモリとしての役割

エージェントは毎回ゼロベースで思考するわけではありませんが、多くのファイルを見すぎることで逆に重要なルールを見失う（ロスト・イン・ザ・ミドル現象）ことがあります。AGENTS.md という明確なルールブックを定義し、エージェントの起動時やタスク開始時に必ず読み込ませることで、思考のブレを最小限に抑えることができます。

`AGENTS.md` に書くべき内容の 4 つの分類

効果的な AGENTS.md は、以下の 4 つのセクションで構成するのがベストプラティスです。

禁止事項 (Prohibitions): 致命的なエラーや環境のハングを防ぐ
命名規則・コーディング基準 (Standards): コードの品質を一定に保つ
アーキテクチャ原則 (Architecture): システムの整合性を維持する
テスト・検証方針 (Testing): 修正の正しさを担保する

それぞれのセクションについて、具体的な記述例を見ていきましょう。

1. 禁止事項 (Prohibitions)

エージェントが最もやりがちな「環境破壊」を防ぐための最重要セクションです。

ルール	理由（なぜその設計にするか）
インタラクティブコマンドの禁止	`npm init` や `git commit` (メッセージ入力待ち) など、ユーザー入力を待つコマンドは CLI エージェントをフリーズさせます。
Watch Mode の禁止	`vitest --watch` 等はプロセスが終了しないため、エージェントが「完了」を検知できなくなります。
`any` 型の原則禁止	AI は型の整合性を取るのが面倒になると `any` で逃げようとします。これは長期的な保守性を著しく低下させます。
勝手な依存関係の追加禁止	`package.json` を書き換えて新しいライブラリを入れる行為は、セキュリティやビルドサイズに影響するため、人間の許可を必須にします。

実例コード

## 禁止事項
- **コマンド実行**:
  - `vi`, `nano`, `top` などのインタラクティブなコマンドは実行しない。
  - `npm start`, `vitest --watch` などの終了しないプロセスは背景実行 (`&`) するか、単発実行モードを使用すること。
- **TypeScript**:
  - `any` 型の使用は厳禁。どうしても必要な場合はコメントで理由を明記すること。
- **Git**:
  - ユーザーの明示的な指示なしに `git commit` や `git push` を行わない。

2. 命名規則・コーディング基準 (Standards)

プロジェクトの「見た目」と「一貫性」を守るためのルールです。ここを疎かにすると、エージェントは自分の得意なスタイル（多くの場合、学習データで最も多いスタイル）で書き始めてしまいます。

EmacsでGoのLsp補完が死んだときの調査記録

Sun, 22 Mar 2026 00:00:00 +0900

症状

Emacsで .go ファイルを開くと以下のログが無限ループする。

[eglot] Asking EGLOT (mydns/(go-ts-mode go-mod-ts-mode)) politely to terminate
[jsonrpc] Server exited with status 2
[eglot] Reconnected!
[eglot] Connected! Server 'gopls' now managing '(go-ts-mode go-mod-ts-mode)' buffers in project 'mydns'.
[jsonrpc] (warning) Sentinel for EGLOT (...) still hasn't run, deleting it!
[jsonrpc] Server exited with status 9
[eglot] Reconnected! [2 times]
Error running timer: (error "Selecting deleted buffer")

status 9 は SIGKILL。gopls が起動→即死→reconnect を繰り返し、補完が一切効かない状態。

fmt. と打っても候補が出ない、もしくは関係のないゴミ候補が出る。手動で M-x completion-at-point を叩いても No match。

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその6

Thu, 05 Mar 2026 23:00:00 +0900

はじめに

Part5でUIまで実装が終わった。機能として動くものはできた。テストも15件、全パス。

ここで一度立ち止まって、なぜこの設計になったのかを振り返る。

正直に言う。最初の要件はこうだった。

「クリーンアーキテクチャっぽく、テスタブルにしたい」

それだけだった。クリーンアーキテクチャを理解して設計したわけじゃない。 結果的にクリーンアーキテクチャを遂行したのは生成AIだ。

そしてPart3以降、自分はほとんど手を動かさなくなった。設計ドキュメントをAIに渡したら、実装サイクルがほぼ自動で回るようになったからだ。

途中でこう思った。

「俺いる必要なくね？」

この記事はその問いに向き合いながら、設計を改めて言語化したものだ。

このシリーズ自体がTDDだった

書き終えてから気づいたことがある。

このシリーズのサイクルはこうだった。

AIに実装させる
  ↓
動かす・読む・会話する（認識のズレを検出）
  ↓
ズレを言語化してAIにフィードバック
  ↓
納得したら記事にする

ソフトウェアのTDDは「Red → Green → Refactor」だけど、自分がやっていたのはこれだ。

Red → 認識がズレていると感じる
Green → 会話して納得する
Refactor → 記事として言語化する

人間がテストケースになっていた。

TDDが「仕様をテストで表現する」なら、自分がやっていたのは「理解をフィードバックループで検証する」だ。構造は同じだと思う。

誤っていた認識たち

振り返ると、理解がズレていた箇所がいくつかあった。

「PolicyはVOと1-1になる」と思っていた

最初、ReadingStatusPolicyがReadingStatusに対応しているのを見て、PolicyはVOと対になるものだと思っていた。

違う。今回たまたま1-1になっているだけだ。

Policyの本質は複数のEntityやVOをまたいだ条件判定だ。たとえば「同じ本に同じユーザーが2回レビューできない」というルールは、Book・User・Review[]をまたぐ。これをPolicyに出す。

VOに閉じるルールならVOに書けばいい。Entityをまたぐ判定が必要になったときにPolicyの出番だ。

「Domainは外部を知らない」という捉え方が逆だった

「DomainはDBを知らない」という言い方をよくするが、正確には逆だ。

外部がDomainを知っている。

向きの問題だ。Domainが何かを避けているのではなく、依存の矢印がすべてDomainに向かって刺さっている。

Route Handler
  ↓
Service
  ↓
Repository interface
  ↓
Domain（Entity / ValueObject / Policy）

この向きがわかって初めて、Serviceの役割も見えた。

Serviceが何をするのかわかっていなかった

依存の向きが腑に落ちるまで、Serviceが何者なのかずっと曖昧だった。

答えはシンプルだった。フローだけ持つ接着剤。

async startReading(id: string): Promise<Book> {
  const book = await this.repo.findById(id);   // 取得
  if (!book) throw new NotFoundError(...);
  book.changeStatus(ReadingStatus.Reading);     // Entityのルールに従う
  await this.repo.save(book);                  // 保存
  return book;
}

ServiceはDomainのルールを自分で判定しない。 canTransitionを自分で呼ばない。book.changeStatus()に委ねるだけだ。判定はEntity・VO・Policyが持っている。Serviceはその結果を使ってフローを組む。

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその5

Thu, 05 Mar 2026 01:30:00 +0900

はじめに

Part4 でカスタム例外クラスと残りのエンドポイントを実装し、APIが完成した。

Part5では src/app/page.tsx に簡易UIを実装する。バックエンドのロジックやテストには一切触れない。フロントエンドからAPIを叩いて動くものを作るだけだ。

実装方針

page.tsx をClient Componentにする。

Server Componentでfetchする方法もあるが、ボタン操作のたびにstateを更新して再描画する必要がある。今回のUIは「ボタンを押す → APIを叩く → 一覧を再取得して画面を更新する」という流れが中心なので、 useState + useEffect で管理するClient Componentのほうがシンプルだ。

"use client";

ファイル先頭にこの1行を追加する。

実装するUI

本の追加フォーム（id / title / isbn）
本棚（Unread / Reading / Completed のグループ表示）
各本へのアクションボタン
- Unread → 「読み始める」ボタン
- Reading → 評価入力（1〜5）＋「読了にする」ボタン
- 全ステータス → 削除ボタン

型定義

APIレスポンスの型を定義する。

type BookStatus = "Unread" | "Reading" | "Completed";

type Book = {
  id: string;
  title: string;
  isbn: string;
  status: BookStatus;
  rating: number | null;
};

バックエンドの ReadingStatus は as const で定義した文字列リテラルなので、そのまま使える。

データ取得

async function fetchBooks() {
  try {
    const res = await fetch("/api/books");
    if (!res.ok) throw new Error("取得失敗");
    const data: Book[] = await res.json();
    setBooks(data);
  } catch (e) {
    setError(e instanceof Error ? e.message : "不明なエラー");
  } finally {
    setLoading(false);
  }
}

useEffect(() => {
  fetchBooks();
}, []);

fetchBooks は追加・ステータス変更・削除の後にも呼ぶ。サーバーの状態を正として再取得するシンプルな方針だ。楽観的更新（Optimistic Update）は今回やらない。

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその4

Thu, 05 Mar 2026 00:50:00 +0900

はじめに

Part1 でValueObject・Policy・Entityを作り、Part2 でServiceをDI＋Mockテストで固めた。 Part3 でPrismaを繋ぎ、GET /api/books と POST /api/books を動かした。

Part4では残りのエンドポイントを実装する。やることは3つ。

カスタム例外クラスの導入
PATCH /api/books/:id/start と PATCH /api/books/:id/complete の実装
DELETE /api/books/:id の実装

そして「エラー種別ごとにHTTPステータスを整理する」という設計判断を掘り下げる。

また、Part3でPrisma v7特有のセットアップをしたが、v6以前と何が変わったのかをここで整理しておく。

0. Prisma v7で何が変わったか

Part3でPrismaをセットアップしたとき、v6以前と比べていくつか「見慣れない書き方」が必要だった。 v7は破壊的変更が多く、ネット上のv6時代の記事を参考にすると詰まる箇所がある。ここで整理しておく。

参考: Upgrade to Prisma ORM 7 | Prisma Documentation

generator の変更

// ❌ v6以前
generator client {
  provider = "prisma-client-js"
}

// ✅ v7
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

v7では prisma-client-js が廃止され prisma-client に変わった。 Rustベースのエンジンを廃止しTypeScriptネイティブになったことに伴う変更だ。また output が必須になり、node_modules への自動生成はなくなった。

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその3

Wed, 04 Mar 2026 17:50:00 +0900

はじめに

Part1 でValueObject・Policy・Entityを作り、Part2 でServiceをDI＋Mockテストで固めた。累計13テスト、全パスの状態だ。

Part3ではいよいよDBを繋ぐ。やることは3つ。

Prismaセットアップ＋スキーマ定義
PrismaBookRepository 実装（ドメインオブジェクトへの変換）
Route HandlerでDIを組み立てる

そして最後に「テストを書かない層を意図的に決める」という話をする。

1. Prismaセットアップ

npm install prisma @prisma/client
npx prisma init --datasource-provider sqlite

prisma/schema.prisma に Bookモデルを定義する。

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

model Book {
  id     String  @id
  title  String
  isbn   String
  status String
  rating Int?
}

User と Review はまだDBに持たない。Book の CRUD が動けば Part3 のゴール。

なぜ `status` を String で持つのか

Prismaは SQLiteで enum をネイティブサポートしていない。そのため status String で持ち、取り出し時に as ReadingStatus でキャストする。

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその2

Wed, 04 Mar 2026 02:00:00 +0900

前回のおさらい

その1では ValueObject・Policy・Entity を作った。ポイントは「フレームワークを一切使わないので、テストがただの関数呼び出しになる」という体験だった。

今回はいよいよ Service 層に入る。ここが設計の核心だ。 複数のクラスをまたぐフローを、DI（依存性の注入）を使って DB から切り離す。

今回追加したもの

src/
  domain/
    entity/
      User.ts              # 追加
      Review.ts            # 追加
    valueobject/
      UserName.ts          # 追加
      ReviewComment.ts     # 追加
  repository/
    BookRepository.ts      # 追加（Interface）
  service/
    BookShelfService.ts    # 追加

User と Review を追加する

まず Entity の準備。今回は単純なので ValueObject から作る。

UserName

export class UserName {
  constructor(public readonly value: string) {
    if (!value || value.trim().length === 0) {
      throw new Error("UserNameは空にできない");
    }
    if (value.length > 50) {
      throw new Error("UserNameは50文字以内");
    }
  }
}

trim() してから空チェックしているのがポイント。スペースだけのユーザー名を弾く。

ReviewComment

export class ReviewComment {
  constructor(public readonly value: string) {
    if (!value || value.trim().length === 0) {
      throw new Error("ReviewCommentは空にできない");
    }
    if (value.length > 1000) {
      throw new Error("ReviewCommentは1000文字以内");
    }
  }
}

User Entity

import { UserName } from "../valueobject/UserName";

export class User {
  constructor(
    public readonly id: string,
    public readonly name: UserName,
  ) {}
}

User 自体はシンプルだ。ロジックがない。ビジネスルールが増えれば changeXxx() メソッドが生える設計だが、今は id と name を持つだけでいい。

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその1

Wed, 04 Mar 2026 01:00:00 +0900

なぜこの記事を書いたか

動くものをまず作って、そこにテストを後付けしようとした。しかし、できなかった。

具体的にはこういう壁にぶつかった。

ModelなどのDB接続の切り替えがうまくいかない
Controllerをテストしようにもいろいろおかしくなる

悩んだ結果、気づいたことがある。そもそもそんなものは単体テストじゃない。 ロジックをControllerやModelに全部書いていたのが悪かった。

「じゃあ最初からそう書けばいいじゃないか」という話だが、それが難しい。雑魚プログラマにいきなりクリーンな設計はできない。

なので発想を逆にした。テスト前提でコードを書く。 テストが書けない場所にはロジックを書かない。それを体で覚えるために、今回のハンズオンを始めた。

方針

生成AIに実装ヒントと次のステップを教えてもらいながら、コードは自分で書く。

正直、コード自体はAIに書かせてもいいと思っている。ただ、設計の考え方は頭に入れる必要があるので、写経しながら理解を深めている。

テストする場所の原則はシンプルだ。

フレームワークで用意された便利クラスはテストしない
DBやAPIなど外界と接する場所はテストしない
自分で書いた純粋なTS部分だけをテストする

作るもの

読書レビューサイト。Todoアプリはビジネスロジックがほぼ存在しないのでテストの練習に向いていない。読書レビューサイトなら本の状態遷移（積読→読中→読了）などのルールが自然に生まれるので、テストの旨味がある。

技術スタック

Next.js
SQLite + Prisma
vitest

ディレクトリ構成

src/
  domain/
    entity/
    valueobject/
    policy/
  service/
  repository/

この構成の考え方は以下の通り。

層	役割
entity	概念そのもの（Book, User）
valueobject	値の制約を持つクラス（ISBN, Rating）
policy	ビジネスルールを切り出したクラス
service	複数クラスをまたぐフロー
repository	DBとのアダプタ（副作用をここに閉じ込める）

repositoryはCI4でいうModelに近い立ち位置だ。 ただし決定的な違いがある。CI4のModelはActiveRecordパターンでクラス自身がDBを知っているため切り離せないが、repositoryはInterfaceと実装を分けることで差し替え可能にする。これがDI（依存性の注入）の肝で、テスト時にMockに差し替えられる。

vitestのセットアップ

npm install -D vitest @vitejs/plugin-react vite-tsconfig-paths
npm install -D @testing-library/react @testing-library/jest-dom

vitest.config.ts

import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
    plugins: [react(), tsconfigPaths()],
    test: {
        environment: 'jsdom',
        globals: true,
        setupFiles: ['./src/test/setup.ts'],
    },
})

package.jsonのscriptsに追加。

AVL木と赤黒木をPythonで実装して比較する

Sun, 01 Mar 2026 00:00:00 +0900

AVL木と赤黒木をPythonで実装し、回転・バランス戦略の違いをベンチマークで比較する

LinuxのCFSとEEVDFを整理する - スケジューラはなぜ赤黒木を使うのか

Sun, 01 Mar 2026 00:00:00 +0900

CFSのvruntime・赤黒木・タイムスライスの仕組みと、Linux 6.6で導入されたEEVDFへの変遷をSRE視点で整理する

Linuxの起動フローを整理する - UEFI/BIOSからinitまで

Sat, 28 Feb 2026 00:00:00 +0900

UEFI/BIOSからブートローダー、カーネル、initまでのLinux起動フローをSRE視点で整理する

歴史地図アプリを雑にk3sへデプロイした

Wed, 25 Feb 2026 22:00:00 +0900

React+Vite+MapLibreで作った歴史地図アプリをk3sにデプロイした話。hostPathマウント、Viteの罠、ngrokとTailscaleを駆使したファイル転送など泥臭い記録。

WSL2でExpo + E2Eテスト（MaestroとDetox）を試みて完全に詰んだ話

Mon, 23 Feb 2026 21:30:00 +0900

TL;DR

WSL2環境でExpo（React Native）のE2EテストをMaestroとDetoxで試みたが、どちらもWSL2とWindowsエミュレータの構造的な問題で動かなかった。

かなり過言ではあるが、あえて感情的になるならば、Mobile開発においてMac以外は人権がない。というかあまりにもMac環境以外がだるすぎる。

環境

OS: Windows + WSL2（Ubuntu）
Expo SDK 54 / React Native 0.81.5
New Architecture有効
Androidエミュレータ: Windows側で動作（Medium Phone API 36）
ADB: Windows側のものをWSL2から参照

Maestroを試みる

インストール

curl -Ls "https://get.maestro.mobile.dev" | bash
export PATH="$HOME/.maestro/bin:$PATH"

ここで最初の罠。maestro --helpを叩くとAI系の全く別のCLIツールが応答した。同名の別アプリが先にPATHに入っていたため。$HOME/.maestro/binをPATHの先頭に置くことで解決。

フローの準備

# .maestro/add_and_complete_task.yml
appId: com.example.myapp
---
- launchApp
- tapOn:
    text: "追加"
- inputText: "テストタスク"
- tapOn:
    text: "追加する"
- assertVisible:
    text: "NOW"

実行して即死

You have 0 devices connected, which is not enough to run 1 shards.

エミュレータはWindows側で動いており、adb devicesにはemulator-5554が見えている。しかしMaestroはWSL2側でデバイスを探すため認識できない。

--udid=emulator-5554を指定しても：

Device emulator-5554 was requested, but it is not connected.

maestro start-device --platform=androidを試みると：

react-native-pdf 6.7.7のiOS表示問題をpatch-packageで解決する

Tue, 17 Feb 2026 14:30:00 +0900

はじめに

業務でreact-native-pdfを使用した際、AndroidではPDFが正常に表示されるのにiOSでは表示されないという問題に遭遇しました。

この記事では、GitHubのissueで共有された解決策であるpatch-packageを使ったパッチ適用方法について解説します。

問題の概要

環境

{
  "react-native-pdf": "^6.7.7",
  "react-native": "0.80.1",
  "react-native-blob-util": "^0.22.2"
}

症状

Android: PDF表示が正常に動作
iOS: PDFが表示されない

この問題は、React Native 0.80以降でreact-native-pdfを使用した際に発生することが確認されています。

参考: pdf is not displayed，Android is working fine, but there are problems with iOS #966

解決策: patch-packageを使う

GitHubのissueで@anhnguyen123さんが共有してくれたパッチファイルを適用することで、この問題を解決できます。

1. patch-packageのインストール

まず、patch-packageとpostinstall-postinstallをdevDependenciesとしてインストールします。

# npmの場合
npm install --save-dev patch-package

# yarnの場合
yarn add --dev patch-package postinstall-postinstall

参考: patch-package - npm

2. package.jsonにpostinstallスクリプトを追加

package.jsonのscriptsセクションに、postinstallスクリプトを追加します。

{
  "scripts": {
    "postinstall": "patch-package"
  }
}

このスクリプトにより、npm installまたはyarn installを実行するたびに、自動的にパッチが適用されます。

3. パッチファイルの配置

GitHubのissueからパッチファイルreact-native-pdf+6.7.7.patchをダウンロードし、プロジェクトルートにpatchesディレクトリを作成してそこに配置します。

歴史地図アプリに日本語検索を実装: GeoJSONデータの効率的な翻訳手法

Sun, 15 Feb 2026 19:00:00 +0900

はじめに

歴史的国境を可視化する地図アプリを作っていたら、「日本語で国名検索ができない」という問題に直面した。外部のGeoJSONデータは英語のみで、日本語プロパティがない。

そこで、Gemini APIを使って効率的にデータを翻訳し、日本語検索を実装した手法を紹介する。

問題: 外部GeoJSONデータには日本語がない

使用したデータソース:

現代国境: Natural Earth (約200カ国)
歴史的国境: aourednik/historical-basemaps (18ファイル、紀元前2000年〜1920年)

{
  "type": "Feature",
  "properties": {
    "NAME": "France",
    "NAME_JA": null  // ← 日本語プロパティがない!
  },
  "geometry": { ... }
}

このままでは「フランス」で検索できない。

解決策: 翻訳キャッシュを使った効率的なデータ拡張

アプローチ1: 愚直な方法 (非効率)

各ファイルごとに全データをLLMに投げる:

// ❌ 非効率: 同じ国名を何度も翻訳
for (const file of geoJsonFiles) {
  const data = await fetch(file);
  const translated = await translateAll(data); // Franceを18回翻訳...
  await save(translated);
}

問題点:

同じ国名が複数ファイルに登場 → 重複翻訳
トークン消費が膨大
処理時間が長い

アプローチ2: 翻訳キャッシュ方式 (効率的) ✅

全ファイル共通の翻訳キャッシュを使い回す:

// ✅ 効率的: 一度翻訳した国名は二度と翻訳しない
const translationCache = {}; // { "France": "フランス", ... }

for (const file of geoJsonFiles) {
  const data = await fetch(file);
  
  // 未翻訳の国名のみ抽出
  const newNames = extractUntranslatedNames(data, translationCache);
  
  // 新規の国名だけ翻訳
  if (newNames.length > 0) {
    const translations = await translate(newNames);
    Object.assign(translationCache, translations);
  }
  
  // キャッシュを使って適用
  applyTranslations(data, translationCache);
  await save(data);
}

実装: Node.jsスクリプト

完全なコード

この手法をNode.jsスクリプトとして実装した。Gemini 2.5 Flash Liteを使用している。この程度の翻訳ならこれで十分。

PostgreSQLのCTEが現場で少ない理由を実務経験から考える

Thu, 12 Feb 2026 10:50:00 +0900

バッチ処理でCTEを使った実務経験から、CTEの強み・弱み、PostgreSQL 12での最適化の進化、サブクエリ・一時テーブルとの使い分けを解説

AsyncStorageって裏側何やってんの？ - 2.0と3.0の実装の違いを調べてみた

Sun, 08 Feb 2026 17:50:00 +0900

私は普段React NativeでExpo触ってるので、AsyncStorageはよく使うんだけど、「そういえばAsyncStorageって裏側何やってんだろう？」って疑問が湧いてきたので調べてみることにした。

AsyncStorageの裏側

AsyncStorageのバージョンによって実装が少し違う。

AsyncStorage 2.0の実装

iOS/Androidのみ調査。

公式ドキュメント: Where your data is stored - Async Storage

iOS (2.0)

manifest.jsonファイルに保存される
JSONファイル形式
パス: Documents/RCTAsyncLocalStorage_V1/manifest.json
詳細: 1024文字以下のデータはmanifest.jsonに、それより大きいデータは個別ファイル(MD5ハッシュ名)に保存される

Android (2.0)

SQLiteデータベースに保存される
データベース名: RKStorage
パス: /data/data/{package_name}/databases/RKStorage

AsyncStorage 3.0 (next)の実装

公式ドキュメント: https://react-native-async-storage.github.io/3.0-next/

対応プラットフォーム

Android (SQLite)
iOS (SQLite) ✨
macOS (SQLite)
visionOS (legacy fallback, single database only)
Web (IndexedDB backend)
Windows (legacy fallback, single database only)

iOS (3.0)

SQLiteデータベースに変更された
Androidと同じ実装に統一
パフォーマンスと安定性が向上

Android (3.0)

引き続きSQLite
より洗練された実装

3.0からはiOSもAndroidも両方SQLiteになって、実装が統一されるそうだ。

互換性

React Native 0.76以降が必要(iOS/Android)
Kotlin 2.1.0
iOS minimum target: 13
Android minimum SDK: 24

なぜiOSでmanifest.jsonからSQLiteに変更したのか

あくまでも推測ではあるがやってみた。

React NativeのTodoアプリで実装する相対時間ベースのプリセット機能

Sun, 08 Feb 2026 10:50:00 +0900

絶対時間ではなく相対時間（dueHoursOffset）で期限を管理することで、繰り返しタスクを効率化するプリセット機能の実装方法を解説

Emacsのdotfilesをモジュール化してメンテナンス性を向上させた話

Fri, 06 Feb 2026 23:30:00 +0900

900行の肥大化したEmacs設定をファイル分割し、requireとloadの違いを理解して安定した環境を構築

三竦（さんすくみ）要件定義書

Fri, 06 Feb 2026 07:30:00 +0900

犬猿雉の三すくみを使った追跡型対戦ゲームの要件定義。リアルタイムアクション + 戦略性を両立したシンプルなモバイルゲーム

GEMINI.mdでAIに開発履歴を管理させる方法

Sat, 31 Jan 2026 19:30:00 +0900

GEMINI.mdファイルを使ってAI（Gemini）にコーディングルールと開発履歴を管理させる手法を紹介します。AIが自分で学習・改善していくドキュメント駆動開発の実践例。

Gemini CLIでExpo Todoアプリを爆速開発した話

Sat, 31 Jan 2026 19:00:00 +0900

Gemini CLI を使って Expo の Todo アプリを開発した体験記。GEMINI.md でルールを管理し、段階的に機能を追加していく方法を紹介します。

React NativeでTextInputの日本語入力が壊れる問題と解決方法

Sat, 31 Jan 2026 18:30:00 +0900

React NativeのTextInputで日本語入力時に変換候補が消える問題の原因と、autoComplete/autoCorrectによる解決方法を解説します。

Proxmox LXCコンテナでJupyterLab環境構築 - 試行錯誤とトラブルシューティング

Mon, 26 Jan 2026 18:30:00 +0900

はじめに

Proxmox上にJupyterLabのLXC環境を構築しました。当初はGeminiに任せて試行錯誤しましたが、最終的にベストプラクティスに辿り着いたので、その過程と解決策をまとめます。

構築の基本方針

当初は「Root + グローバル環境」で構築しようとしましたが、最終的に**「専用ユーザー + 仮想環境（venv）」**による安全でクリーンな構成に落ち着きました。

最終構成

OS: Ubuntu 24.04 LTS (LXC Container)
ユーザー: jupyter (非Root運用)
Jupyter: JupyterLab (v4.x)
環境: /opt/jupyter/venv (OSと分離した仮想環境)

環境構築手順

1. OSの準備

Ubuntu 24.04の最小構成に必要なパッケージをインストールします。

apt update && apt upgrade -y
apt install -y python3-full build-essential

python3-fullが重要です。これがないと後述するPEP 668の問題に直面します。

2. 専用ユーザーとディレクトリの作成

# 専用ユーザー作成
useradd -m -s /bin/bash jupyter

# Jupyter本体用のディレクトリ準備
mkdir -p /opt/jupyter
chown jupyter:jupyter /opt/jupyter

3. 仮想環境の構築

jupyterユーザーとして、OSの制限を受けない独立した環境を作ります。

su - jupyter
python3 -m venv /opt/jupyter/venv
source /opt/jupyter/venv/bin/activate

# JupyterLabとカーネルのインストール
pip install jupyterlab ipykernel pandas

4. systemdによるデーモン化

/etc/systemd/system/jupyter.serviceを作成します。

PythonとWorld Bankデータで世界の産業構造を可視化する方法

Mon, 26 Jan 2026 09:30:00 +0900

World BankのオープンデータとPythonを使って、世界各国の産業構造（第一次・第二次・第三次産業）の変化を可視化してみました。初心者でもわかる経済データ分析の入門記事です。

ラズパイ6台で作る、絶対に止まらない最強の自宅ネットワーク冗長化計画

Sat, 24 Jan 2026 19:00:00 +0900

はじめに

「自宅サーバーを構築したが、1台落ちただけで家族全員のネットが止まった」そんな苦い経験（特にDNS/DHCP周りでの同期失敗）を経て、今回はRaspberry Pi 6台（＋α）を駆使した「高可用性（HA）」に特化した自宅ネットワークを再設計します。

今回のコンセプトは「速度よりも、止まらないこと」。北欧神話の神々の名を冠した6台のラズパイによる、3層の冗長化レイヤーを構築します。

1. ネットワーク全体像

上位ルーターとはWi-Fiで接続し、内部ネットワークは有線L2スイッチを中心に構成します。物理的に役割を分離することで、障害時の原因切り分けを容易にしています。

階層化の設計案

Edge層 (L1): インターネットへの門番。KeepalivedでゲートウェイIPを共有。
Core層 (L2): DHCPやDNS、認証など、NWの頭脳となる機能を同期。
Service層 (L3): ファイルサーバーなどの実データをレプリケーションして保持。

2. サーバー構成表：北欧神話の神々

物理筐体	ホスト名	役割	冗長化の仕組み
Pi 3 (A)	Odin	主系Gateway / VPN	Keepalived (VIP: 192.168.1.1)
Pi 3 (B)	Frigg	副系Gateway / VPN	Odinと仮想IPを共有
Pi 3 (C)	Huginn	DNS / DHCP Primary	ISC-DHCP Failover / Gravity Sync
Pi 3 (D)	Muninn	DNS / DHCP Secondary	Huginnとリアルタイム同期
Pi 3 (E)	Mjolnir	ストレージ (NAS)	GlusterFS + Keepalived (VIP: .200)
Pi 3 (F)	Gungnir	ストレージ (NAS)	Mjolnirとデータレプリケーション

3. 過去の失敗を防ぐ「守り」の技術選定

① DNS/DHCP：仮想IPに頼らない

過去、DNSやDHCPを仮想IP（Keepalived）で制御しようとして失敗した経験から、今回はプロトコル標準の冗長化を採用します。

データが暴く物価高騰の真実 - エネルギー価格と為替の相関分析で見えた意外な結論

Fri, 23 Jan 2026 08:30:00 +0900

「円安が物価高の原因」は本当か？消費者物価指数と為替レートの詳細分析から見えた、統計が示す意外な真実。相関係数0.100が語る、エネルギー価格変動の本当のドライバーとは。

K3s実験環境構築マニュアル：安全に実験→破壊→復元のサイクルを回す

Mon, 19 Jan 2026 10:30:00 +0900

Proxmox上のK3s環境で安全に実験・破壊・復元サイクルを回すための完全ガイド

LeetCode 735: Asteroid Collision - スタックで衝突判定を美しく解く

Tue, 13 Jan 2026 19:30:00 +0900

問題概要

整数で表される小惑星の配列 asteroids が与えられる。各小惑星について：

絶対値：大きさ
符号：方向（正=右、負=左）
全て同じ速度で移動

衝突ルール：

小さい方が爆発
同じ大きさなら両方爆発
同じ方向に移動する小惑星は衝突しない

全ての衝突後の状態を返せ。

失敗した実装

from collections import deque

class Solution:
    def asteroidCollision(self, asteroids: List[int]) -> List[int]:
        stack = []
        for aster in asteroids:
            if len(stack) <= 0 or (aster <= 0) == (stack[-1] <= 0):
                stack.append(aster)
            else:
                while len(stack) > 0 and (aster <= 0) != (stack[-1] <= 0) and abs(aster) > abs(stack[-1]):
                    stack.pop()
                if len(stack) <= 0 or (stack[-1] <= 0) == (aster <= 0):
                    stack.append(aster)
                elif abs(aster) == abs(stack[-1]):
                    stack.pop()
        return stack

問題点

同じ条件判定 if len(stack) <= 0 or (stack[-1] <= 0) == (aster <= 0) が2箇所に重複
制御フローが複雑で読みにくい
(aster <= 0) != (stack[-1] <= 0) は「符号が異なる」を検出するが、衝突しないケースも含む

最適解

class Solution:
    def asteroidCollision(self, asteroids: List[int]) -> List[int]:
        stack = []
        
        for asteroid in asteroids:
            while stack and asteroid < 0 < stack[-1]:
                # 右向き vs 左向きの衝突が発生
                if abs(stack[-1]) < abs(asteroid):
                    # 右向きが小さい → 爆発して次の右向きとも衝突判定
                    stack.pop()
                    continue
                elif abs(stack[-1]) == abs(asteroid):
                    # 同じ大きさ → 両方爆発
                    stack.pop()
                break
            else:
                # 衝突しなかった or 左向きが勝った
                stack.append(asteroid)
        
        return stack

わかったこと

1. ループ条件の本質

asteroid < 0 < stack[-1]

これは (asteroid < 0) and (0 < stack[-1]) と同じ。つまり：

Go言語でネットワークプログラミングを学ぶ - 第3章

Sun, 11 Jan 2026 20:19:00 +0900

スイッチとMACアドレスを実装し、複数ノードからなるローカルネットワークを構築する

Go言語でネットワークプログラミングを学ぶ - 第2章

Sun, 11 Jan 2026 10:00:00 +0900

時間の概念とスループット制御をネットワークシミュレーションに導入する

Go言語でネットワークプログラミングを学ぶ - 第1章

Sat, 10 Jan 2026 18:00:00 +0900

ネットワークの基本要素であるNode、Link、Packetを Go言語で実装する

Go言語でネットワークプログラミングを学ぶ - 第0章

Sat, 10 Jan 2026 17:50:00 +0900

Go言語を使ってネットワークプログラミングを体系的に学ぶためのカリキュラム第0章

本が読めなかったから、仕事をやめました - 読書メモ

Fri, 09 Jan 2026 19:30:00 +0900

本の情報

タイトル: 本が読めなかったから、仕事をやめました
著者: [著者名不明]
読書期間: 2025年1月9日
読了状況: 大正時代まで（未完）

まえがき - 衝撃の一文

本が読めなかったから、仕事をやめました★

ロックすぎる。

著者の状況

読書好き、本を買うために働く
週5勤務、21時まで残業
気づいたら1年間、本を読んでいない
時間があってもスマホを見てしまう
本を開いても目が閉じる、YouTubeに逃げる
3年半後、退職
退職後、ゆっくり読書できるようになった

著者の問題提起

会社で働きながら本を読むことは難しい
本を読む余裕のない社会はおかしい

→ SNSで多くの同意が集まる
→ 趣味全般を続けづらい社会への問い
→ 「あなたの文化は労働に搾取されている」

所感: 共感と違和感

共感ポイント

仕事のために生きている人が多数派でビビる
仕事は微妙、人間関係は辛い
これ、私のことだ
読書好きでもこうなるのか…（本当なら）
余裕がない社会
働きながらX（Twitter）をやるのはマジで辛い

違和感

突然「搾取」という言葉が出てきて怖い
自称漫画家、バンドマンのようなゴミは働きながら続けるべき
- 辛いからこそ、続けるってことは熱量があるってこと

第1章: 労働と文化的生活の両立

著者の姿勢

文句だけ言っても仕方ない
歴史から学ぶアプローチ
なぜ今、両立しなくなったのか
どうしたら両立できるのか

『花束みたいな恋をした』分析

登場人物:

麦: 地方の花火職人 → 会社員
絹: 金持ち、大企業

展開:

就職後、麦は忙しくなる
漫画が続かない、頭に入らない
パズドラしかやる気しない
絹からの本も無視
心が離れていく

テーマ: 長時間労働と文化的生活は両立しないという前提の作品

速読・自己啓発ブームの意味

Amazonで速読、情報処理スキル、読書術が人気
趣味ではなく、自己啓発メイン
効率優先
→ 労働と読書の両立をみんななんとかしようとした結果
ファスト教養も同じ構造

第2章: 格差と読書

階級格差が読書意欲に影響

麦（労働者）vs 絹（富裕層）の対比
働けど働けど暮らしは楽にならず
本を読む余裕さえなくなる
暮らしの格差が余暇の時間も奪う

『独学大全』の指摘

格差は動機づけの段階から現れる
学ぶ動機づけがない者 → 学問は役に立たない、僻む
意欲から格差が生まれる

第3章: 明治時代 - 長時間労働と読書の始まり

労働環境

この頃から長時間労働
工場労働者: 農民時代より断然長時間
平均残業時間: 2時間 …あれ？
化学工場: 12時間労働 …は？
労働組合はゴミ、割増料金が魅力的
→ 今もだいたい同じ

明治時代の感覚

「最近はみんな忙しそうにしてる」
余裕がなくなった感じ、せっかち
近代化 = せっかち

読書革命

句読点と黙読の発明:

DFS/BFSの本質：深さと幅を支配するデータ構造の選択

Fri, 09 Jan 2026 06:30:00 +0900

DFS, BFSがわかりづらかったので、いくつかの記事を見て個人的に感じた疑問や「こういうコード例が欲しい」という要望を踏まえて生成AIに生成してもらった。

生成された内容を検証し、コードを実際に動かして確認したところ、自分の理解が深まる良い記事になったので、このまま公開することにした。

はじめに

LeetCodeでMedium問題を解いていると、必ず遭遇するのがDFS（深さ優先探索）とBFS（幅優先探索）だ。

「Dは深さ、Bは幅」というのは知っている。でも、なぜスタックとキューを使い分けるのか？その本質を理解している人は意外と少ない。

今回は、入れ子リストの例を使って、DFS/BFSの動作原理とデータ構造の関係を視覚的に解説する。

問題設定：入れ子リストをフラット化する

以下のような入れ子構造のリストがあるとする。

data = [1, [4, 5, [6, 7, 8], 2], 3]

これをフラットな配列にしたい。このとき、「どの順番で要素を取り出すか」がDFS/BFSの違いだ。

ツリー構造として可視化する

入れ子リストは、実はツリー構造として表現できる。

この木をどう巡回するかで、DFSとBFSが決まる。

DFS（深さ優先探索）：とにかく深く潜る

動作イメージ

「見つけた枝があれば、まずそこを最後まで探索する」

訪問順序：

1 → [中に入る] → 4 → 5 → [さらに中] → 6 → 7 → 8 
→ [戻る] → 2 → [戻る] → 3

結果：[1, 4, 5, 6, 7, 8, 2, 3]

Audibleで学ぶヨーロッパ中世史：雑談メモ

Sat, 03 Jan 2026 22:00:00 +0900

Audibleでヨーロッパ史を聞きながら取ったメモと雑談。ビザンツ帝国、カロリング朝、そして歴史上の人物への率直な感想。

k3s + Drone CI/CD構築体験記② 手動ビルドでなんとか動いた

Thu, 01 Jan 2026 18:00:00 +0900

前回のハマり話の続編。

今回は実際にCI/CDパイプラインを動かすところまで進めた。結論から言うと、自動化は99%完成したが、最後の1%（Webhook）で詰んだ。

目標設定

理想は当然これ：

GitHub push → Drone検知 → Hugo自動ビルド → Dockerイメージ作成 → k3sデプロイ更新

ただし、私の環境には致命的な制約がある。

制約：外部IP持ってない

自宅サーバーはTailscaleでVPN経由でのみアクセス可能。つまりGitHubからのWebhookが届かない。まあ、DuckDNSでドメインは取ってるけど、それでもTailscale依存の構成。

それでも「やれるとこまでやってみよう」精神で進めた。

.drone.yml 設定

最終的にはこんな感じになった：

kind: pipeline
type: kubernetes
name: hugo-pipeline

steps:
- name: build-hugo
  image: klakegg/hugo:latest
  commands:
  - cd posts
  - hugo --minify
  - ls -la public/

- name: create-docker-context
  image: alpine:latest
  commands:
  - cp -r posts/public ./public
  - ls -la public/

- name: docker-build
  image: plugins/docker
  settings:
    registry: ghcr.io
    repo: ghcr.io/wasuken/tech_blog
    username:
      from_secret: github_username
    password:
      from_secret: github_token
    tags:
    - latest
    - "${DRONE_COMMIT_SHA:0:8}"

- name: deploy-to-k3s
  image: bitnami/kubectl
  environment:
    KUBECONFIG:
      from_secret: kubeconfig
  commands:
    - kubectl set image deployment/hugo-site hugo=ghcr.io/wasuken/tech_blog:latest
    - kubectl rollout status deployment/hugo-site

- name: deploy-complete
  image: alpine:latest
  commands:
  - echo "Hugo build complete!"
  - echo "Image pushed successfully"

ポイントは、HugoビルドからDockerイメージ作成、GHCR（GitHub Container Registry）へのプッシュ、最終的なk3sデプロイまで全部自動化したこと。

ローカル環境を汚さない静的サイト構築 - Hugo Docker Compose環境構築記録

Sun, 21 Dec 2025 23:00:00 +0900

背景

日課でできる範囲の活動として、軽い記事から、疑問を生成AIに出してもらって、それに答えてもらって、深堀や補足、添削をしてもらった内容までを記事にするという習慣を続けていたが、公開するのはどうなのかなと思った。

しかし、後ほど止めるのはもったいないということで妥協案として、ローカルで動くブログには投稿することにした。

なので、ローカルブログを立ち上げることにした。

最初はGitHub Pagesでよく使われているJekyllを試した。しかし、ローカル環境とDocker環境でRubyのバージョン不一致が発生し、プロジェクト初期化の段階で躓いた。

ローカルのRuby 3.4に対してDockerの最新イメージがRuby 3.1で、この差分が原因でSCSS変換周りでエラーが頻発。Jekyllはプロジェクト作成をローカルで行う必要があるため、「Docker使えば環境差を吸収できる」という謳い文句が実質的に機能しなかった。

もっとうまくやればよかっただろうが、そのときは血が登っていて、Hugoにしてしまった。

要件整理

改めて自分の要件を整理した：

Markdownファイルのマウントだけで完結
ローカル環境に一切依存しない
プロジェクト初期化もDocker内で実行可能
検索機能とファイル一覧が欲しい

これを満たすツールを探した結果、Hugoに行き着いた。

なぜHugoなのか

Hugoを選んだ理由は明確：

1. バイナリ単体で動作

Go言語で書かれたHugoは単一バイナリで動作する。RubyやNode.js、Pythonのようなランタイム環境が不要。これにより依存関係地獄から解放される。

2. プロジェクト初期化もDocker内で完結

当初は生成AIの言うとおりに以下のコマンドでプロジェクトを作成した。

docker run --rm -v $(pwd)/posts:/src klakegg/hugo:alpine new site .

この1コマンドでプロジェクト作成が完了する。ローカルに何もインストールする必要がない。

のだが、後ほどこれがトラブルを産んだ。

3. 高速なビルド

Goの並列処理能力により、数千ページ規模のサイトでも秒単位でビルドが完了する。開発時のホットリロードも快適。

構築手順

1. docker-compose.yml作成

services:
  hugo:
    image: hugomods/hugo:base
    container_name: hugo-blog
    ports:
      - "7000:7000"
    volumes:
      - ./posts:/src
    command: server --bind 0.0.0.0 --port 7000 --buildDrafts --buildFuture
    restart: unless-stopped

ポイント：

hugomods/hugo:base を使用
ポートは7000にマッピング（後述のブラウザ制限回避）
--buildDrafts --buildFuture で下書きと未来日付の記事も表示

2. プロジェクト初期化

docker run --rm -v $(pwd)/posts:/src klakegg/hugo:alpine new site .

これで posts/ ディレクトリに必要なファイル群が生成される。

PostgreSQLのpg_trgmで中間一致検索を高速化する仕組みを学ぶ

Sun, 21 Dec 2025 12:00:00 +0900

参考

この記事は、以下の記事を読んで疑問に思ったことを調べた学習記録である。

Zennの検索スピードを5倍に高速化した話

記事では、Zennのサイト内検索をpg_trgm拡張を使って平均6倍、95パーセンタイルで4.25倍高速化した事例が紹介されている。

なぜ中間一致検索は遅いのか

通常、PostgreSQLでLIKE '%keyword%'のような中間一致検索を実行すると、BTreeインデックスが使えずフルスキャンが発生する。BTreeインデックスは文字列の前方一致には有効だが、中間一致では活用できない構造になっているためである。

データ量が増えると、このフルスキャンが深刻なパフォーマンスボトルネックになる。参考記事では、検索に1秒〜数秒かかる状態だったとのことだ。

n-gramインデックスの仕組み

n-gramインデックスは、文字列をn文字ずつに分割してインデックス化することで、中間一致検索でもインデックスを効かせる仕組みである。

3-gramの例

「PostgreSQL」という文字列を3-gram（トライグラム）で分割すると以下のようになる。

__P, _Po, Pos, ost, stg, tgr, gre, reS, eSQL, QL_, L__

先頭と末尾にはパディング文字（_）が付与される。

検索時の動作

「stgre」というキーワードで検索する場合：

検索キーワードを3-gramで分割: stg, tgr, gre
インデックスからこれらすべてのトライグラムを含む文書を抽出
抽出された候補に対してRecheck処理を実行

重要なのは「いずれか」ではなく「すべて」のトライグラムが存在する文書が候補になる点である。もし「いずれか」だと、無関係な文書が大量に候補に含まれてしまう。

Recheck処理が必要な理由

n-gramインデックスでは、インデックスレベルでの検索後に必ずRecheck処理が必要になる。

具体例

以下のような状況を考える。

本文: 「小学校校長」
クエリ: 「小学校長」

3-gramで分割すると：

「小学校校長」→ 小学校, 学校校, 校校長
「小学校長」→ 小学校, 学校長

「小学校」が共通しているため、n-gramレベルでは「小学校校長」が候補として抽出される。しかし実際には「小学校長」という文字列は含まれていない。

このようなfalse positive（誤検出）を除外するため、インデックスで絞り込んだ候補に対して、実際に検索キーワードが含まれているかを厳密にチェックする必要がある。これがRecheck処理である。

pg_trgmとpg_bigmの選択

PostgreSQLには2つの主要なn-gram拡張がある。

pg_trgm: 3-gram方式、PostgreSQL本体にcontribとして付属
pg_bigm: 2-gram方式、サードパーティ製（NECが開発）

比較表

機能	pg_trgm	pg_bigm
エコシステム	PostgreSQLコミュニティ	サードパーティ
ILIKE対応	○	×
2文字以下の検索	×	○
Recheck無効化	×	○
インデックスサイズ	小	大（約2倍）

なぜpg_trgmが選ばれたか

参考記事では、以下の理由でpg_trgmのみを採用している。

怠惰ローカルブログ

WaylandでモニターがマイクとスピーカーとしてOSに認識される問題をWirePlumberで無効化する

問題

環境

原因

調査

認識されているカードを確認

AdGuard HomeをProxmox LXCに立ててTailscale経由でDNSブロックする

概要

環境

手順

1. AdGuard Home LXCをスクリプト一発で作成

2. LXCにTUNデバイスを追加する

3. LXCにTailscaleを入れる

ArchLinuxのThunarでWalkmanのFSを開く

背景

環境

ThunarでWalkmanのFSが見えない

原因：MTP用ライブラリが未インストール

補足：USB DACモードとは

Canvas 2D API でピクセルアートタイルを「手書き」する実装テクニック

Canvas 2D API でピクセルアートタイルを「手書き」する実装テクニック

1. 概要

2. タイル描画の基本構造

TypeScript Union 型でスキルのレンジ種別とダメージ計算を型安全に実装する

TypeScript Union 型でスキルのレンジ種別とダメージ計算を型安全に実装する

1. Union 型でスキル種別を表現する

なぜこの設計にするのか（データ構造の純粋性）

ターン制戦闘をフィールドに統合する vs 専用画面に分ける：設計比較と判断基準

ターン制戦闘をフィールドに統合する vs 専用画面に分ける：設計比較と判断基準

1. 2つのアプローチの比較

2. フィールド統合型の実装：空間と時間の同期

なぜその設計にするか

アクション設計の例

実装のポイント

3. 専用画面型の実装：コンテキストの分離

React で作る堅牢なゲームセーブシステム：localStorage と Reducer を疎結合に保つ設計

React で作る堅牢なゲームセーブシステム：localStorage と Reducer を疎結合に保つ設計

1. 概要：なぜ「直接 localStorage」を避けるのか

2. SavePort 設計：抽象化の定義

Reducer パターンだけでゲーム状態を管理する：副作用ゼロのアーキテクチャ

Reducer パターンだけでゲーム状態を管理する：副作用ゼロのアーキテクチャ

概要

課題：なぜゲーム開発で Reducer は敬遠されるのか

1. 乱数 (Randomness) の扱い

2. 静的データ (Master Data) の参照

3. 時刻 (Time) と経過の管理

4. 非同期処理 (Async/Fetch)

OOP（オブジェクト指向）との比較

設計：副作用を「引数」に封じ込める

React + Canvas 2D API で作るターン制ローグライク：論理と描画を切り離す設計

React + Canvas 2D API で作るターン制ローグライク：論理と描画を切り離す設計

1. 概要：なぜ React と Canvas を組み合わせるのか

本記事で構築するアーキテクチャ

2. 設計判断：論理座標と描画座標の分離

なぜ分離が必要か

乱数を interface で抽象化してゲームロジックをテスタブルにする

乱数を interface で抽象化してゲームロジックをテスタブルにする

概要

課題：Math.random() がもたらす「テスト不能」という病

設計：Port / Adapter パターンによる抽象化

1. Port (Interface) の定義

2. Adapter (Implementation) の実装

TypeScript npm workspaces でゲームロジックを UI から完全分離する

TypeScript npm workspaces でゲームロジックを UI から完全分離する

概要

課題：なぜロジックが UI に染み出すのか？

設計：npm workspaces による物理的隔離

AI コーディングエージェントを飼い慣らす：最強の「AGENTS.md」の書き方

AI コーディングエージェントを飼い慣らす：最強の「AGENTS.md」の書き方

なぜ AGENTS.md が必要なのか

なぜその設計にしたか：外部メモリとしての役割

AGENTS.md に書くべき内容の 4 つの分類

1. 禁止事項 (Prohibitions)

実例コード

2. 命名規則・コーディング基準 (Standards)

EmacsでGoのLsp補完が死んだときの調査記録

症状

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリ その6

はじめに

課題：`Math.random()` がもたらす「テスト不能」という病

なぜ `AGENTS.md` が必要なのか

`AGENTS.md` に書くべき内容の 4 つの分類

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその6

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその5

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその4

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその3

なぜ `status` を String で持つのか

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその2

テスト前提で設計したWebアプリのハンズオン - 読書管理アプリその1