なぜ Cloudflare Pages か​

これまで S3 + CloudFront + Route53 という AWS 標準の構成で運用してきたが、以下の理由から Cloudflare Pages への移行を決めた。

1. 管理コストの低さ: SSL 証明書の自動更新、グローバルエッジへのデプロイが標準で組み込まれている。
2. 無料枠の広さ: 個人ブログ程度のトラフィックであれば、ほとんどの機能を無料枠で利用できる。
3. デプロイの柔軟性: GitHub 連携だけでなく、GitHub Actions からの Direct Upload にも対応しており、複雑なビルドフローも維持できる。

移行の手順​

1. GitHub Actions のワークフロー作成​

既存の S3 デプロイ用のワークフローを Cloudflare Pages 用に書き換えた。今回は cloudflare/pages-action を使用している。

2. Cloudflare Pages プロジェクトの作成​

Cloudflare のダッシュボード、または CLI (Wrangler) からプロジェクトを作成する。今回は確実にブランチを指定して作成するため、Wrangler を使用した。

3. DNS の切り替え​

S3 を向いていた www.hikari-dev.com の DNS レコードを Cloudflare Pages のエンドポイント（xxx.pages.dev）に向けるよう更新した。

Cloudflare Pages 側でカスタムドメインを追加すると、自動的に検証が走り、SSL 証明書が発行される。この際、古いレコードが残っていると検証に失敗することがあるため、一度ドメイン設定を削除して再登録することでスムーズに反映された。

移行後の所感​

移行自体は非常にスムーズで、デプロイ速度も S3 へのアップロードと遜色ない。何より、AWS 側で管理していた複数のリソース（S3 バケット、CloudFront ディストリビューション、ACM 証明書）を Cloudflare Pages という一つのプロジェクトに集約できたのが大きなメリットだと感じている。

今後は Cloudflare Workers などを活用した動的な機能追加も検討していきたい。

単位: USD / 1M トークン (MTok)。2026 年 4 月時点の情報。

料金比較​

GPT-4o mini が入力・出力ともに最安だが、ナレッジカットオフが 2023 年 10 月と古いため最新知識が必要なタスクには不向きである。GPT-5.4 nano は入力コストで GPT-4o mini とほぼ同等ながら、GPT-5.4 ファミリーの品質と 2025 年 8 月までの最新知識を持つ。GPT-5.4 (フラグシップ) は入力コストが GPT-4o と同額だが、出力コストが $15.00 / MTok と高く、最高品質の推論が必要な場面向けである。

リージョナル処理エンドポイントを使用する場合は、GPT-5.4 シリーズに対して 10% の割増料金 が発生する。

スペック比較​

GPT-5.4 シリーズはコンテキスト ウィンドウが 400K トークン と大幅に拡張され、最大出力も 128K トークンまで対応する。GPT-4o / GPT-4o mini は 128K / 16K に留まる。

性能・精度比較​

GPT-5.4​

GPT-5.4 ファミリーのフラグシップ モデル。OpenAI が提供する現世代最高の知能を持ち、複雑な推論・長文生成・高度なコーディングにおいて GPT-5.4 mini を大きく上回る。コンピュータ使用・MCP・Web 検索などすべてのネイティブ ツールに対応し、マルチモーダル入出力も完全サポートする。出力コストが $15.00 / MTok と高いため、高品質な出力が必要な場面に絞って使用するのが効果的である。

GPT-5.4 mini​

GPT-5.4 ファミリーの中間モデルで、コーディング、コンピュータ使用、サブエージェントに最適化されている。GPT-5 mini より一貫して高い性能を示し、フラグシップの GPT-5.4 に近いパス レートを、より高速な処理で実現する。GPT-5 mini 比で 2 倍以上の速度向上が確認されており、コーディング ワークフローにおいて最高クラスのパフォーマンス / レイテンシー トレードオフを提供する。

GPT-5.4 nano​

GPT-5.4 ファミリーの最小・最安モデル。分類、データ抽出、ランキング、コーディングのサブエージェントなど、大量処理で速度とコストが最優先のユース ケース向けに最適化されている。深い推論が必要な複雑なタスクには向かない。

GPT-4o​

汎用フラグシップ モデルとして登場し、テキスト・画像の両方に対応する高い知能を持つ。現在は GPT-5.4 系に後継されたレガシー モデルの位置付けで、ChatGPT からは 2026 年 2 月に退役したが API アクセスは継続している。

GPT-4o mini​

「ファインチューニングに最適な小型モデル」として設計された。大規模モデル (GPT-4o) の出力を蒸留することで同等の結果を低コスト・低遅延で実現する。MMLU スコアは 82.0%。シンプルなタスクへの投入コストを抑えたい場合に適している。

どのモデルを選ぶか​

• 大量処理・コスト最優先: GPT-5.4 nano か GPT-4o mini。最新知識が必要なら GPT-5.4 nano、ファインチューニングが必要なら GPT-4o mini。
• コーディング・エージェント: GPT-5.4 mini。速度・精度のバランスが最良。
• 複雑な推論・高品質出力: GPT-5.4。入力 $2.50、出力 $15.00 / MTok と高コストだが、現世代最高品質の出力が得られる。
• レガシー システムとの互換性: GPT-4o。API は継続提供されているため既存の統合を維持できる。

コスパ良く選ぶなら...​

コスパの観点で特に注目すべきは GPT-5.4 nano と GPT-5.4 mini の 2 モデルである。

GPT-5.4 nano は GPT-4o mini とほぼ同じ入力コスト ($0.20 vs $0.15) ながら、400K のコンテキスト、2025 年 8 月までのナレッジ、Web 検索・ファイル検索・MCP などのネイティブ ツールをすべて利用できる。ナレッジカットオフを除いて GPT-4o mini に優る点がほとんどであるため、ファインチューニングが不要であれば GPT-5.4 nano への移行が合理的である。

GPT-5.4 mini は GPT-4o ($2.50 / MTok) より安い入力コスト ($0.75) で、コーディングや エージェント ワークフローにおいては GPT-4o を超える性能を発揮する。GPT-4o を日常的に使っているなら、GPT-5.4 mini への切り替えでコスト削減と性能向上を同時に実現できる可能性が高い。

一方、GPT-4o は現時点では割高感がある。入力コストが GPT-5.4 と同額 ($2.50) でありながら、コンテキスト・知識・ツール対応のいずれでも GPT-5.4 系に劣る。ファインチューニングや既存システムとの互換性が必要な場合を除き、積極的に選ぶ理由は薄い。

参考​

• OpenAI API 料金
• GPT-5.4 mini モデル詳細
• GPT-5.4 nano モデル詳細
• GPT-5.4 mini と nano の紹介 – OpenAI
• GPT-5.4 モデル詳細
• GPT-4o mini モデル詳細

多くの画面密度への対応​

現代のディスプレイは 1x・1.5x・2x・3x・4x などの pixel ratio を持っている。

8 は多くの倍率で整数に割り切れるため、サブピクセルレンダリングによるぼやけが起きにくい。5 px のような値を使うと、1.5x 環境で 7.5 px という端数が生じ、レンダリングが不正確になる。

タイポグラフィとの相性​

ブラウザのデフォルトフォントサイズは 16 px (= 8 × 2)。行間も通常 1.5 倍 = 24 px (= 8 × 3) である。

8 の倍数で余白を設定すると、テキストのリズムと視覚的に揃いやすくなる。見出しや本文の高さが余白のグリッドと一致するため、整然とした垂直リズムが生まれる。

デザイントークンの作りやすさ​

--space-1: 8px;
--space-2: 16px;
--space-3: 24px;
--space-4: 32px;

スケールが単純で、デザイナーとエンジニアが共通言語として使いやすい。Material Design や Tailwind CSS もこの考え方を採用している。

デザイナーが「ここは space-3」と指定するだけで、エンジニアは迷わず 24px を当てられる。命名規則が整うことで、コードレビュー時のコミュニケーションコストも下がる。

4 px ベースという選択肢​

より細かい調整が必要な UI では 4 px ベース (4, 8, 12, 16...) も一般的である。Tailwind CSS はデフォルトで 4 px ベース (p-1 = 4px) を採用している。

4 px ベースは 8 px ベースの部分集合でもあるため、両者は矛盾しない。コンポーネント内部など細かな余白には 4 px 単位を使い、セクション間など大きな余白には 8 px 単位を使うといった使い分けも有効である。

まとめ​

8 px の倍数が余白の基準として使われる理由は 3 点に集約される。

1. 画面密度への対応: 多くの pixel ratio で整数に割り切れ、サブピクセルのぼやけを防ぐ
2. タイポグラフィとの整合: デフォルトフォントサイズ (16 px) や行間 (24 px) と揃い、垂直リズムが生まれる
3. スケールの一貫性: シンプルなトークン体系がデザイナーとエンジニアの共通言語になる

S3 Files とは​

S3 Files は Amazon EFS をベースに構築された共有ファイルシステムで、S3 バケットのデータにファイルシステムとしてアクセスできる。

主な特徴は以下の通りである。

動作の仕組み​

S3 Files はアクセスされたデータを高性能ストレージに自動ロードし、低レイテンシで提供する。

• 小さいファイル (デフォルト 128 KB 未満): 高性能ストレージから直接読み取り
• 大きいファイル (1 MB 以上): S3 から直接ストリーミング
• 書き込み: 高性能ストレージに書き込み後、S3 に自動同期

高性能ストレージ上のデータは、一定期間 (デフォルト 30 日、1 - 365 日で設定可能) アクセスがないと自動削除される。

前提条件​

• AWS アカウント
• EC2 インスタンス (Linux)
• S3 バケット (EC2 と同じリージョン)
• IAM ロール 2 つ
  • ファイルシステム作成用: S3 バケットの読み書き権限
  • EC2 インスタンス用: AmazonS3FilesClientFullAccess マネージドポリシーをアタッチ
• セキュリティグループ: NFS ポート 2049 の通信を許可

IAM ロールの作成​

S3 Files には 2 つの IAM ロールが必要である。

1. ファイルシステム作成用ロール​

マネジメントコンソールを使用した場合は自動的に作成されるため不要

S3 Files がバケットにアクセスするためのロールである。

# ロールの作成
aws iam create-role \
  --role-name S3Files-FileSystem-Role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": { "Service": "s3files.amazonaws.com" },
        "Action": "sts:AssumeRole"
      }
    ]
  }'

# S3 Files クライアントポリシーをアタッチ
aws iam attach-role-policy \
  --role-name S3Files-FileSystem-Role \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3FilesClientFullAccess

ファイルシステム作成時に --role-arn で指定する。

2. EC2 インスタンス用ロール​

IAM ロールのアタッチがないとマウントに失敗する

以下のロールを CloudShell で作成する。

# ロールの作成
aws iam create-role \
  --role-name EC2-S3Files-Role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": { "Service": "ec2.amazonaws.com" },
        "Action": "sts:AssumeRole"
      }
    ]
  }'

# S3 Files クライアントポリシーをアタッチ
aws iam attach-role-policy \
  --role-name EC2-S3Files-Role \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3FilesClientFullAccess

# インスタンスプロファイルの作成とアタッチ
aws iam create-instance-profile \
  --instance-profile-name EC2-S3Files-Profile

aws iam add-role-to-instance-profile \
  --instance-profile-name EC2-S3Files-Profile \
  --role-name EC2-S3Files-Role

このロールをインスタンスにアタッチする。

セットアップ手順​

1. S3 バケットの準備​

S3 コンソールで汎用バケットを作成する。既存のバケットでも構わない。

ただし、バケットのバージョニング設定が必要

2. ファイルシステムの作成​

コンソールから作成する場合​

1. S3 コンソールでバケットを選択
2. 「ファイルシステム」タブ → 「ファイルシステムを作成」 をクリック

コンソールから作成すると、全 AZ にマウントターゲットとアクセスポイントが自動作成される。

3. プレフィックスと VPC を指定して、「ファイルシステムを作成」をクリックする。

出力されるファイルシステム ID (例: fs-0123456789abcdef0) を記録しておく。

3. インスタンスにマウント​

ターミナルで、以下を実行する。

# マウントポイントの作成
sudo mkdir /mnt/s3files

# マウント
sudo mount -t s3files fs-0123456789abcdef0:/ /mnt/s3files

sudo dnf install -y amazon-efs-utils # Amazon Linux, RHEL
# sudo apt install -y amazon-efs-utils (Ubuntu, Debian)

マウントの確認:

df -h /mnt/s3files

以下のような出力が表示される。

Filesystem      Size  Used Avail Use% Mounted on
<s3files-dns>   8.0E  129M  8.0E   1% /mnt/s3files

4. 動作確認​

cd /mnt/s3files

# ファイルの作成
sudo sh -c 'echo "Hello, s3 Files!" > test.txt'

# ファイルの読み取り
cat test.txt

# ディレクトリの作成
sudo mkdir test-directory

ls -la

# ファイルのコピー
sudo cp test.txt test-directory/

cd test-directory/

# ファイル一覧の確認
ls -la

書き込んだファイルは約 1 分で S3 バケットに同期される。S3 コンソールでオブジェクトが作成されていることを確認できる。

aws s3 ls s3://<bucket-name>/

自動マウントの設定​

再起動後もマウントを維持するには /etc/fstab に追加する。

# /etc/fstab に追加
fs-0123456789abcdef0:/ /mnt/s3files s3files _netdev,nofail 0 0

_netdev はネットワーク接続後にマウントするためのオプションで、必須である。nofail を付けることで、マウント失敗時にインスタンスが起動不能になることを防げる。

料金​

S3 Files の料金は以下で構成される。

• 高性能ストレージ使用量: ファイルシステム上のデータのストレージ料金
• ファイルシステムアクセス料金: 高性能ストレージへの読み書き操作
• S3 リクエスト料金: 1 MB 以上のファイルを S3 から直接読み取る場合は S3 GET 料金のみ

プロビジョニング不要の従量課金制で、AWS によると従来の S3 とファイルシステム間のデータコピーと比較して最大 90% のコスト削減が可能とされている。

まとめ​

• S3 Files を使うと S3 バケットを NFS ファイルシステムとして EC2 にマウントできる
• データは S3 に保持されたまま、ls、cat、cp などの通常のファイル操作が使える
• 高性能ストレージによるキャッシュで低レイテンシを実現し、アクセスのないデータは自動で退避される
• /etc/fstab で自動マウントを設定すれば、再起動後も維持される

参考​

• Amazon S3 Files - Amazon Web Services
• S3 Files ユーザーガイド - AWS Documentation
• Tutorial: Getting started with S3 Files - AWS Documentation

仕組み​

多くの AI コーディングツールは Node.js 製のアプリであり、HTTPS で外部 API と通信している。mitmproxy を中間プロキシとして挟み、Node.js に mitmproxy の CA 証明書を信頼させることで、暗号化された通信を復号してリアルタイムで確認できる。

インストール​

mitmproxy は uv でインストールするのが手軽である。

uv tool install mitmproxy

プロキシの設定​

ツールを起動する前に、以下の環境変数を設定する。

$env:HTTPS_PROXY = "http://127.0.0.1:8080"
$env:HTTP_PROXY  = "http://127.0.0.1:8080"
$env:NODE_EXTRA_CA_CERTS = "$env:USERPROFILE\.mitmproxy\mitmproxy-ca-cert.pem"

NODE_EXTRA_CA_CERTS について​

HTTPS_PROXY と HTTP_PROXY だけでは Node.js の TLS 検証が失敗し、通信できない。mitmproxy は HTTPS を中継するときに自己署名証明書を使うため、Node.js がその証明書を拒否してしまう。

NODE_EXTRA_CA_CERTS に mitmproxy の CA 証明書のパスを指定することで、Node.js がその証明書を信頼するようになり、通信が成立する。

CA 証明書の生成​

mitmproxy は初回起動時に自動的に CA 証明書を生成し、~\.mitmproxy\ に保存する。まだ生成していない場合は一度起動すれば生成される。

mitmweb

ブラウザが自動的に開き、http://127.0.0.1:8081 にプロキシの管理画面が表示される。

ツールの起動​

別のターミナルで環境変数を設定した状態でツールを起動する。

ツールを操作し始めると、mitmweb の画面にリクエストが流れてくる。

キャプチャした通信の中身​

エンドポイント​

ツールは以下のエンドポイントにリクエストを送信する。

POST https://api.example.com/v1/messages

リクエストヘッダー​

x-service-version: ...
content-type: application/json
x-api-key: sk-...

リクエストボディ​

{
  "model": "model-name",
  "max_tokens": 16000,
  "stream": true,
  "system": [
    {
      "type": "text",
      "text": "..."
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "..."
    }
  ],
  "tools": [
    {
      "name": "Read",
      "description": "...",
      "input_schema": {}
    }
  ]
}

stream: true で Server-Sent Events (SSE) 形式のストリーミングレスポンスを受け取る。

レスポンス​

data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
...
data: {"type":"message_stop"}

わかること​

システムプロンプトの中には AI コーディングツールの動作原則、利用可能なツールの説明、注意事項などが含まれている。

まとめ​

• NODE_EXTRA_CA_CERTS で mitmproxy の CA 証明書を Node.js に信頼させることがポイント
• API 通信は SSE ストリーミング形式で行われる
• ツール定義やシステムプロンプトなど、AI コーディングツールの内部構造を把握できる

前提条件：パスキーに必要な Cognito の設定​

Cognito でパスキーを使うには、以下がすべて揃っている必要がある。

Cognito のパスキーは Managed Login v2 UI から登録・使用する形になる。LITE tier (無料) では WebAuthn は使えないため、ESSENTIALS tier が必要である。

認証フロー​

パスキー登録フロー​

初回はパスワードでログインし、アカウント設定からパスキーを登録する。

パスキーログインフロー​

登録後は「パスキーでサインイン」ボタンから直接認証できる。

設定内容​

パスキー追加のために template.yaml (SAM テンプレート) に加えた変更はわずか 6 行である。

変更前​

UserPool:
  Type: AWS::Cognito::UserPool
  Properties:
    # ...
    Policies:
      PasswordPolicy:
        MinimumLength: 8
        # ...
    MfaConfiguration: "OFF"

変更後​

UserPool:
  Type: AWS::Cognito::UserPool
  Properties:
    # ...
    Policies:
      PasswordPolicy:
        MinimumLength: 8
        # ...
      SignInPolicy:
        AllowedFirstAuthFactors:
          - PASSWORD
          - WEB_AUTHN       # ← パスキーを追加
    MfaConfiguration: "OFF"
    WebAuthnRelyingPartyID: login.example.com   # ← RP ID を指定
    WebAuthnUserVerification: required              # ← 生体認証等を必須に

各パラメータの意味​

SignInPolicy.AllowedFirstAuthFactors​

最初の認証ステップで使える認証方式のリストである。PASSWORD だけだとパスワードのみ、WEB_AUTHN を追加するとパスキーも選べるようになる。

WebAuthnRelyingPartyID​

WebAuthn の Relying Party ID (RP ID) である。パスキーはこのドメインに紐付いて生成・保存されるため、実際にログインページを配信しているドメインと一致させる必要がある。

今回はカスタムドメイン login.example.com をそのまま指定している。Cognito デフォルトドメイン (xxx.auth.ap-northeast-1.amazoncognito.com) を使っている場合はそちらを指定する。

WebAuthnUserVerification​

パスキー使用時のユーザー確認レベルである。

セキュリティ強化のため required を選択した。

Managed Login の UI​

Managed Login v2 の画面では、パスキー設定後にログイン画面へ「パスキーでサインイン」ボタンが自動で追加される。初回登録時はパスワードでログインした後、アカウント設定からパスキーを追加できる。

デプロイ​

sam build
sam deploy --no-confirm-changeset

samconfig.toml にスタック名・リージョン・パラメータを定義済みなので、毎回オプション指定は不要である。

まとめ​

Cognito でパスキーを有効にするポイントをまとめると:

1. ESSENTIALS tier に設定する (LITE では WebAuthn 非対応)
2. Managed Login v2 を使う
3. カスタムドメイン (または Cognito デフォルトドメイン) を RP ID として指定する
4. SignInPolicy.AllowedFirstAuthFactors に WEB_AUTHN を追加する
5. WebAuthnUserVerification: required で生体認証を必須にする

たった 6 行の変更でパスキーログインが使えるようになった。パスワードは残しつつ段階的にパスキーへ移行できるのが Cognito の便利なところである。

認証方法​

gcloud auth（推奨）​

API キー不要。既存の Google Cloud 認証情報をそのまま利用できる。

$accessToken = (gcloud auth print-access-token)

API キー​

$apiKey = $env:VERTEX_API_KEY

エンドポイント​

OpenAI 互換エンドポイント（gcloud auth 認証）​

https://{region}-aiplatform.googleapis.com/v1beta1/projects/{projectId}/locations/{region}/endpoints/openapi/chat/completions

リクエスト・レスポンス形式が OpenAI API と同じ。モデル名に google/ プレフィックスが必要（例: google/gemini-2.5-flash-lite）。

ネイティブ Gemini エンドポイント（API キー認証）​

https://{region}-aiplatform.googleapis.com/v1/projects/{projectId}/locations/{region}/publishers/google/models/{model}:generateContent

ストリーミングが必要な場合は :streamGenerateContent を使用する。

基本的な呼び出し​

OpenAI 互換（gcloud auth）​

$projectId   = "your-project-id"
$region      = "us-central1"
$model       = "google/gemini-2.5-flash-lite"
$accessToken = (gcloud auth print-access-token)

$body = @{
    model    = $model
    messages = @(
        @{
            role    = "user"
            content = "東京の人口は?"
        }
    )
} | ConvertTo-Json -Depth 10

$uri = "https://$region-aiplatform.googleapis.com/v1beta1/projects/$projectId/locations/$region/endpoints/openapi/chat/completions"

$response = Invoke-RestMethod `
    -Uri         $uri `
    -Method      Post `
    -ContentType "application/json" `
    -Headers     @{ Authorization = "Bearer $accessToken" } `
    -Body        $body

$response.choices[0].message.content

ネイティブ Gemini（API キー）​

$projectId = "your-project-id"
$region    = "us-central1"
$model     = "gemini-2.5-flash-lite"
$apiKey    = $env:VERTEX_API_KEY

$body = @{
    contents = @(
        @{
            role  = "user"
            parts = @(
                @{ text = "東京の人口は?" }
            )
        }
    )
} | ConvertTo-Json -Depth 10

$uri = "https://$region-aiplatform.googleapis.com/v1/projects/$projectId/locations/$region/publishers/google/models/${model}:generateContent?key=$apiKey"

$response = Invoke-RestMethod `
    -Uri         $uri `
    -Method      Post `
    -ContentType "application/json" `
    -Body        $body

$response.candidates[0].content.parts[0].text

レスポンス構造​

OpenAI 互換​

$response.choices[0].message.content  # 生成テキスト
$response.usage.total_tokens           # 合計トークン数
$response.model                        # 使用モデル

ネイティブ Gemini​

$response.candidates[0].content.parts[0].text  # 生成テキスト
$response.usageMetadata.totalTokenCount         # 合計トークン数
$response.modelVersion                          # 使用モデルバージョン

ストリーミング（streamGenerateContent）の場合は複数チャンクの配列が返るため、テキストを結合して取り出す。

$fullText = ($response | ForEach-Object {
    $_.candidates[0].content.parts[0].text
}) -join ""

システムプロンプトを追加する​

OpenAI 互換​

$body = @{
    model    = $model
    messages = @(
        @{
            role    = "system"
            content = "日本語で回答する AI アシスタントです。簡潔に答えてください。"
        }
        @{
            role    = "user"
            content = "What is the speed of light?"
        }
    )
} | ConvertTo-Json -Depth 10

ネイティブ Gemini​

$body = @{
    system_instruction = @{
        parts = @(
            @{ text = "日本語で回答する AI アシスタントです。簡潔に答えてください。" }
        )
    }
    contents = @(
        @{
            role  = "user"
            parts = @(@{ text = "What is the speed of light?" })
        }
    )
} | ConvertTo-Json -Depth 10

マルチターン会話​

これまでの会話履歴を配列に並べることでマルチターン会話が実現できる。

OpenAI 互換​

$body = @{
    model    = $model
    messages = @(
        @{ role = "user";      content = "猫と犬、どちらが好きですか?" }
        @{ role = "assistant"; content = "私は猫が好きです。" }
        @{ role = "user";      content = "その理由は?" }
    )
} | ConvertTo-Json -Depth 10

ネイティブ Gemini​

アシスタントのロールは "model" を指定する。

$body = @{
    contents = @(
        @{
            role  = "user"
            parts = @(@{ text = "猫と犬、どちらが好きですか?" })
        }
        @{
            role  = "model"
            parts = @(@{ text = "私は猫が好きです。" })
        }
        @{
            role  = "user"
            parts = @(@{ text = "その理由は?" })
        }
    )
} | ConvertTo-Json -Depth 10

利用可能なモデル​

方式の選択基準​

注意事項​

• API キーはスクリプトにハードコードせず、環境変数 ($env:VERTEX_API_KEY) から読み込むこと。
• gcloud auth の場合、トークンの有効期限は約 1 時間。長時間スクリプトでは都度再取得が必要。
• レート制限やクォータはプロジェクトごとに設定されている。大量リクエストを送る場合は事前に確認すること。

CORS が必要になった背景: 同一オリジンポリシー​

1990 年代初頭、JavaScript がブラウザーに搭載されたとき、Web セキュリティの概念はほぼ存在しなかった。当時、悪意のある Web サイトが他のサイトのデータに自由にアクセスできたため、セッション乗っ取りやデータ窃盗が容易だった。

この問題を解決するため、同一オリジンポリシー (Same-Origin Policy) という制限が導入された。これは「Web ページから読み込んだ JavaScript は、そのページと異なるオリジンのデータにアクセスできない」というシンプルかつ強力なルールである。

例えば、https://www.example.com のページから読み込んだ JavaScript は、https://www.bank.com のデータにアクセスできない。これにより、ユーザーが銀行サイトにログイン中に悪意のあるサイトにアクセスしても、銀行の情報が盗まれることはなくなった。

同一オリジンとは​

オリジン (Origin) とは、以下の 3 つで決まる。

• プロトコル: http:// か https:// か
• ホスト (ドメイン): example.com か api.example.com か
• ポート: 80 か 8080 か

例えば、

これらは異なるホストなので、異なるオリジン と見なされる。

同一オリジンポリシーが防ぐもの​

JavaScript からの XHR (XMLHttpRequest) や Fetch API で、異なるオリジンへのリクエストが制限される。

例: evil.com にある悪意のあるスクリプト

fetch('https://bank.example.com/api/transfer', {
  method: 'POST',
  body: JSON.stringify({ amount: 1000000 })
});

同一オリジンポリシーがなければ、悪意あるサイト (evil.com) の JavaScript から、ユーザーが銀行サイトにログインしている状態で送金リクエストを送られてしまう。これを防ぐのが同一オリジンポリシーの目的である。

なぜ CORS が必要か​

しかし現代の Web では、複数のオリジンが協力する設計が一般的。

• フロントエンド: https://www.example.com
• API サーバー: https://api.example.com
• CDN / 静的ファイル: https://cdn.example.com

これらは同じ企業が運営しており、正当な通信である。しかし同一オリジンポリシーで制限されては、アプリが動かない。

そこで CORS (Cross-Origin Resource Sharing) が登場した。

CORS とは：明示的にアクセスを許可する​

CORS は、サーバー側が「このオリジンからのリクエストは許可する」と明示的に宣言する仕組みである。

サーバーが以下のレスポンス ヘッダーを返すだけで、ブラウザーが制限を緩和する。

Access-Control-Allow-Origin: https://www.example.com
Access-Control-Allow-Methods: GET, POST, PUT
Access-Control-Allow-Headers: Content-Type, Authorization

サーバーが「許可」と言わない限り、ブラウザーはリクエストの結果を JavaScript に渡さない。これで安全性を保ちながら、クロスオリジンアクセスを実現する。

CORS のセキュリティリスク：よくある設定ミス​

便利な CORS だが、設定を間違えるとセキュリティホールになる。

NG: すべてのオリジンを許可する​

Access-Control-Allow-Origin: *

これは「世界中誰からでも、このサーバーにアクセス OK」という意味。

// https://evil.com の JavaScript から
fetch('https://api.example.com/user/profile')
  .then(r => r.json())
  .then(data => {
    // ユーザーのプロフィール情報を盗む処理
    console.log(data);
  });

認証情報 (Cookie) を含むリクエストでは特に危険であり、ユーザーが api.example.com にログイン状態で evil.com にアクセスすると、個人情報が盗まれる。

半分だけ危険：Cookie を含む場合は * 禁止​

fetch('https://api.example.com/user/profile', {
  credentials: 'include'  // Cookie を含める
})

認証情報を含む場合、Access-Control-Allow-Origin: * は使用できない。必ず具体的なオリジンを指定する必要がある。

Access-Control-Allow-Origin: https://www.example.com
Access-Control-Allow-Credentials: true

NG: ユーザーが指定した URL をそのまま許可する​

// 危険な実装例 (サーバー側)
const origin = request.headers.get('Origin');
response.headers.set('Access-Control-Allow-Origin', origin);  // そのまま返す!

こうすると、https://evil.com からのリクエストでも、レスポンスに Access-Control-Allow-Origin: https://evil.com が付いて、悪用される。

ホワイトリストを用意して、そこにあるものだけ許可するのが正解である。

const allowedOrigins = [
  'https://www.example.com',
  'https://admin.example.com'
];

if (allowedOrigins.includes(origin)) {
  response.headers.set('Access-Control-Allow-Origin', origin);
}

NG: すべてのヘッダーを許可する​

Access-Control-Allow-Headers: *

これは「どんなヘッダーでも受け付ける」という意味であり、カスタム ヘッダーで不正なデータを注入する攻撃が可能となる。

必要なヘッダーだけリストアップする。

Access-Control-Allow-Headers: Content-Type, Authorization

CORS プリフライト リクエスト：ブラウザーの事前確認​

単純なリクエスト (GET、HEAD、POST) 以外は、ブラウザーが事前に OPTIONS メソッド で「これで大丈夫？」と確認する。これをプリフライト リクエストという。

1. JavaScript が PUT リクエストを送ろうとする

2. ブラウザーが OPTIONS プリフライト リクエストを自動送信
    OPTIONS /api/resource HTTP/1.1
    Origin: https://www.example.com
    Access-Control-Request-Method: PUT
    Access-Control-Request-Headers: Content-Type

3. サーバーが「OK」と応答
    HTTP 200 OK
    Access-Control-Allow-Origin: https://www.example.com
    Access-Control-Allow-Methods: PUT
    Access-Control-Allow-Headers: Content-Type

4. ブラウザーが実際の PUT リクエストを送信

サーバー側で OPTIONS メソッドに対応していないと、プリフライトで失敗して、実際のリクエストが送信されない。

ポイント:

• ホワイトリストで許可するオリジンを明示的に指定
• credentials: true で Cookie 認証を含むリクエストに対応
• 必要なメソッドとヘッダーのみ許可
• OPTIONS プリフライト リクエスト

よくある疑問​

Q. CORS エラーが出た。すべてのオリジンを許可して解決できるか?​

A: NG。一時的には動くかもしれないが、本番環境で * 許可するのはセキュリティリスクである。サーバー側設定を見直すか、API の設計を変更する必要がある。

Q. ローカル開発中、異なるポートのオリジンにアクセスしたいのか?​

A: ローカル開発環境だけ CORS を無効化するのは問題ない。

Q. モバイルアプリから API を呼ぶ場合、CORS は関係あるか?​

A: CORS はブラウザーのセキュリティ機能なので、モバイルアプリには関係ない。代わりに、API キーや OAuth で認証・認可を実装する必要がある。

まとめ​

CORS は単なる「エラーの原因」ではなく、Web セキュリティの重要な仕組みである。 設定を間違えると、セキュリティ事故につながるため、慎重に取り扱う必要がある。

参考​

• MDN Web Docs - CORS (Cross-Origin Resource Sharing)
• Same-origin policy - MDN Web Docs

translate-mcp とは​

translate-mcp は、OpenAI API を使った翻訳専用ツール である。Python で実装されており、次の 2 つの利用方法がある。

1. CLI モード: コマンドラインから直接ファイルを翻訳
2. MCP サーバーモード: Model Context Protocol (MCP) サーバーとして動作し、AI ツールに統合

特徴​

• 複数言語対応: 多言語に対応している
• シンプルな使い方: API キー 1 つで始められる
• 2 つの利用方法: CLI スクリプトとしても、MCP サーバーとしても動作する
• 軽量: 外部ライブラリに依存せず、OpenAI API に依存するのみ
• エラー ハンドリング: CLI モードは stderr、MCP モードは JSON 形式で返却する

セットアップ​

前提条件​

• Python がインストール済み
• OpenAI API キーを取得済み

uv のインストール​

translate-mcp は uv で管理されているため、まず uv をインストールする必要がある。

uv のインストール方法は Installation | uv を参照すること。

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

translate-mcp のインストール​

uv を使う場合は以下のコマンドでインストールできる。

uv tool install git+https://github.com/Himeyama/translate-mcp

uvx を使えばインストール不要で直接実行も可能である。

uvx git+https://github.com/Himeyama/translate-mcp --help

使用方法​

CLI モード​

ファイルを翻訳する場合は以下のように実行する。

translate --input blog/2026-04-02-example.md --from Japanese --to English

結果は標準出力に出力される。リダイレクトでファイルに保存できる。

translate \
  --input blog/2026-04-02-example.md \
  --from Japanese \
  --to English \
  --output i18n/en/blog/2026-04-02-example.md

パラメータ​

• --mcp: MCP モード
• --input: 翻訳するファイルのパス
• --from: 元の言語（例: Japanese、English）
• --to: 翻訳先の言語（例: English、Taiwanese）
• --output (オプション): 翻訳済みテキストの保存先
• --model (オプション): OpenAI モデル（例: gpt-5-mini）
• --debug (オプション): デバッグモード

エラー時​

エラーが発生した場合は stderr に出力される。

MCP サーバーモード​

MCP サーバーとして起動し、Claude Code や他の AI ツールから利用できる。

translate --mcp

実践例​

ブログ記事を日本語から英語と繁体字中国語（台湾）に翻訳する場合について説明する。

日本語版（元記事）​

# blog/2026-04-02-example.md に日本語の記事がある状態

英語版を生成​

translate \
  --input blog/2026-04-02-example.md \
  --from Japanese \
  --to English > i18n/en/docusaurus-plugin-content-blog/2026-04-02-example.md

台湾版（繁体字中国語）を生成​

translate \
  --input blog/2026-04-02-example.md \
  --from Japanese \
  --to Taiwanese > i18n/zh-TW/docusaurus-plugin-content-blog/2026-04-02-example.md

メリット・デメリット​

メリット​

• 精度が高い: OpenAI の高品質モデル（GPT-4 など）を使用する
• スキル対応: ChatGPT や Claude の様々なツールに統合可能である
• シンプル: セットアップと使い方が非常に簡単である
• カスタマイズ可能: ソースコードが公開されているため、カスタマイズも可能である

デメリット​

• API 費用がかかる: 翻訳量に応じて OpenAI API の費用が発生する
• インターネット接続が必須: API 呼び出しが必要なため、オフライン利用は不可である
• レート制限: OpenAI API のレート制限の影響を受ける

まとめ​

translate-mcp は、OpenAI API を活用した シンプルで高品質な翻訳ツール である。ブログ記事の多言語対応、ドキュメント翻訳、AI ツールへの統合など、様々なシーンで活躍する。

特に Docusaurus などの静的サイト ジェネレーターで複数言語をサポートしたい場合、自動化スクリプトとしての利用が効果的である。

参考​

• GitHub - Himeyama/translate-mcp
• OpenAI API Documentation

単位: USD / 1M トークン (MTok) 。2026 年 3 月時点の情報。

基本料金 (オンデマンド)​

基本料金はどの経路でも同額。

ただし Vertex AI ではグローバルエンドポイントではなくリージョナルエンドポイントを指定した場合、標準価格に 10% 上乗せ される。Bedrock には Long Context バリアント (別 SKU) が存在するが同価格。Anthropic API では Long Context は通常モデルに統合済み。

キャッシュ料金​

プロンプトキャッシュ (Prompt Caching) の料金もどの経路でも同額。

キャッシュライトは TTL に応じて 5 分 (短期) と 1 時間 (長期) の 2 段階がある。長期キャッシュほど書き込みコストが高いが、繰り返し参照するシステムプロンプトが長い場合はリード料金の節約で十分ペイする。

バッチ処理料金​

Bedrock・Vertex AI・Anthropic API いずれも非同期バッチ API がオンデマンド料金の 50% OFF で利用できる。Azure は現時点では非明示。

大量データの一括処理 (ログ解析、埋め込み生成など) でバッチを多用するなら、いずれの経路でもコストを半減できる。

エコシステム比較​

新機能 (Extended Thinking など) は Anthropic API に最初に展開され、Vertex AI・Bedrock・Azure への展開は数週間遅れることがある。

どれを選ぶか​

• シンプルな利用・プロトタイプ: Anthropic API が API キー 1 本で始められ、新機能も最速で使える。
• AWS に統合済み: IAM・CloudWatch・VPC が必要なら Bedrock 一択。東京リージョン対応。
• Google Cloud に統合済み: Vertex AI が自然な選択。リージョナルエンドポイントは 10% 割高になる点に注意。
• Azure に統合済み: Azure AI Foundry 経由で利用可能。Azure の課金・管理に統合できる。
• バッチ多用でコスト削減: Bedrock・Vertex AI・Anthropic API いずれも 50% OFF のバッチ API が使える。

参考​

• Anthropic API 料金 – Claude API Docs
• AWS Bedrock 料金 – Amazon Web Services
• Vertex AI 料金 – Google Cloud
• Claude in Microsoft Azure AI Foundry – Claude API Docs

可読性の維持​

明朝体を単純に太くすると、セリフ（ウロコ）と主ストロークの対比が大きくなりすぎ、文字の内側にあるカウンター（空白部分）が失われやすくなる。特に Web やモニタでの小サイズ表示では顕著で、文字が潰れて判読しにくくなる。

ゴシック体はもともとセリフがないため、ウェイトを上げてもカウンターが保たれ、読みやすさが低下しない。

強調意図の明確性​

フォントファミリー自体を変えることで、「ここは強調されている」という意図が視覚的に即座に伝わる。明朝体を単に濃くした場合と比べ、ゴシック体への切り替えは人間の視覚系に対してより明確な「異なる情報」として処理される。

歴史的・文化的背景​

日本の活字印刷の時代から、強調には別書体を使うという慣習があった。明朝体を太くすると活字の鋳造上の問題が生じるため、ゴシック体という全く異なる書体を使って強調を表現していた。その慣習がデジタル組版、そして Web にそのまま引き継がれている。

CSS での実装​

Web で明朝体をベース書体に使う場合、以下のようなスタイルで太字をゴシック体に切り替える。

body {
  font-family: "Noto Serif JP", serif;
}

strong, b, h1, h2, h3, h4, h5, h6 {
  font-family: "Noto Sans JP", sans-serif;
  font-weight: 700;
}

このアプローチには実装上の利点もある。明朝体の複数ウェイトをすべて読み込む必要がなく、本文の Regular とゴシックの Bold だけを配信すれば済むため、ページの読み込みコストを抑えられる。

まとめ​

日本語の太字がゴシック体になる理由は 3 点に集約される。

1. 可読性: ゴシック体はウェイトを上げてもカウンターが保たれ、読みやすさを維持できる
2. 視認性: フォントファミリーの変更は、単なる太字よりも強調を明確に伝える
3. 慣習: 活字印刷時代からの「強調には別書体」という慣習がそのまま引き継がれている

Web でも同様の理由からこの組み合わせが使われており、デザイン上も実装上も合理的な選択である。

改善前の課題​

素の Docusaurus ブログで PageSpeed Insights を実行すると、いくつかの問題が見つかった。

• SEO: meta description なし、OGP/Twitter Cards なし、構造化データなし、サイトマップの priority 未設定
• パフォーマンス: Google Tag Manager (GTM) の同期読み込みによる未使用 JS の肥大化、外部 CDN からのアバター取得がボトルネック
• アクセシビリティ: プライマリカラーのコントラスト比が WCAG AA 基準を未達

SEO の改善​

meta description・OGP・Twitter Cards の追加​

docusaurus.config.ts の themeConfig.metadata にサイト共通のメタデータを追加した。

themeConfig: {
  metadata: [
    { name: 'description', content: "ひかりの技術メモ..." },
    { property: 'og:locale', content: 'ja_JP' },
    { name: 'twitter:card', content: 'summary_large_image' },
    { name: 'twitter:site', content: '@ptrqr' },
  ],
}

また、src/theme/Layout/index.tsx を Swizzle して、独自の description を持たないページ（ブログ一覧、タグページなど）にロケール別のフォールバック description を設定している。

robots.txt の追加​

static/robots.txt を追加し、クローラーにサイトマップの場所を明示した。

BlogPosting JSON-LD（構造化データ）​

src/theme/BlogPostItem/index.tsx を Swizzle して、記事ページに headline・datePublished・dateModified・author を含む BlogPosting JSON-LD を出力していた。

しかし、Docusaurus 組み込みの BlogPostPage/StructuredData が同等のデータを出力していることが判明。カスタム JSON-LD を削除し、代わりに組み込みコンポーネントに keywords のフォールバック（frontMatter.keywords → tags）を追加した。構造化データの重複は SEO に悪影響を与えるため、この整理は重要であった。

WebSite JSON-LD​

docusaurus.config.ts の headTags に WebSite タイプの JSON-LD を追加し、Google がサイト名を正しく認識できるようにした。

headTags: [
  {
    tagName: 'script',
    attributes: { type: 'application/ld+json' },
    innerHTML: JSON.stringify({
      '@context': 'https://schema.org',
      '@type': 'WebSite',
      name: 'ひかりの備忘録',
      url: 'https://www.hikari-dev.com/',
    }),
  },
],

全記事への OGP 画像自動生成​

scripts/generate-ogp.js を作成し、タグに応じたグラデーション背景の OGP 画像を自動生成するようにした。これにより、SNS でシェアされた際にすべての記事が目を引く画像付きで表示される。全記事のフロントマターに image: フィールドを設定し、記事固有の画像がある場合はそちらを優先する。

サイトマップの改善​

createSitemapItems コールバックを使って、トップページの priority を 1.0、ブログ記事を 0.8 に設定した。また、URL に含まれる日付から lastmod を自動抽出している。

hreflang x-default​

src/theme/Root.tsx で、すべてのページに hreflang="x-default" の <link> タグを注入し、英語ページ（/en/...）をデフォルト（日本語）の URL にマッピングしている。これにより、検索エンジンが言語バリアントを正しく識別できる。

const defaultPath = pathname.replace(/^\/en(?=\/|$)/, '') || '/';
const xDefaultUrl = `${siteConfig.url}${defaultPath}`;

<Head>
  <link rel="alternate" hreflang="x-default" href={xDefaultUrl} />
</Head>

パフォーマンスの改善​

GTM の遅延読み込み​

@docusaurus/plugin-google-gtag を廃止し、src/clientModules/gtag.js で window.load イベント後に GTM スクリプトを動的注入するようにした。これにより、初期レンダリングをブロックする未使用 JS を大幅に削減できた。

function loadGtag() {
  const script = document.createElement('script');
  script.async = true;
  script.src = `https://www.googletagmanager.com/gtag/js?id=${GA_ID}`;
  document.head.appendChild(script);
}

window.addEventListener('load', loadGtag, { once: true });

SPA のページ遷移では Docusaurus の onRouteDidUpdate フックを使い、手動で window.gtag を呼び出している。さらに requestIdleCallback を利用してアイドル時に読み込むよう改善した。

アバターのセルフホスト化と WebP 変換​

アバター画像を GitHub CDN（avatars.githubusercontent.com）からセルフホストに移行した。GitHub CDN はキャッシュ TTL が 5 分と短く、PageSpeed Insights で毎回外部リクエストとして指摘されていた。

アバターを WebP 形式に変換し、ファイルサイズを 34 KB（PNG）から 3.5 KB へ、約 90% 削減した。

画像サイズの最適化と CLS の修正​

• GitHub アバター URL に ?size=64 を追加し、460 px → 64 px に縮小（33 KB 削減）
• ナビバーのロゴに width/height 属性を追加して CLS（Cumulative Layout Shift）を修正
• <img> タグに loading="lazy" を追加

rspack / SWC の導入​

@docusaurus/faster を導入し、webpack を rspack + SWC + lightningCSS に置き換えた。

future: {
  v4: true,
  experimental_faster: true,
},

ビルド速度とバンドルサイズの両方が改善された。

未使用プラグインの無効化​

使用していない docs プラグインを無効化し、不要な JS がクライアントに配信されないようにした。

モバイル限定の Google Fonts 読み込み​

Google Fonts（Noto Sans JP）はモバイルでのみ必要であった。matchMedia を使い、モバイル端末でのみフォントのスタイルシートを動的注入するようにしたことで、デスクトップで約 130 KB の未使用 CSS を削減した。

アクセシビリティの改善​

コントラスト比の修正​

プライマリカラーを #F15EB4 から #C82273 に変更し、白背景に対してコントラスト比 5.3:1 を達成した（WCAG AA 準拠）。ダークモードでは #F36AB2（暗背景に対して 7.0:1）を使用している。

記事の日付テキストの色は CSS 変数 --post-date-color で管理し、ライトモードは #595959（7.0:1）、ダークモードは #9e9e9e とした。

フォントの統一​

見出しと <strong> のフォントを Noto Serif JP から Noto Sans JP に変更し、本文との統一感を持たせた。

結果​

モバイルでほぼ満点を達成した。

まとめ​

最もインパクトが大きかった変更は以下の 3 つである。

1. GTM の遅延読み込み: 未使用 JS を大幅に削減し、パフォーマンススコアが大きく向上した
2. OGP・構造化データの整備: SEO 100 を達成し、SNS シェア時の見栄えも改善された
3. コントラスト比の修正: WCAG AA 準拠によりアクセシビリティが 100 になった

Docusaurus はデフォルトでも高品質なサイトを生成するが、PageSpeed Insights でほぼ満点を目指すには GTM の読み込み戦略、メタデータ、アクセシビリティの細部を調整する必要がある。同じような改善に取り組む方の参考になれば幸いである。

pLaTeX とは​

pLaTeX は日本語組版に対応した LaTeX の実装である。platex コマンドで .tex ファイルをコンパイルし、dvipdfmx で PDF に変換する。

TeX Live に含まれているため、インストール済みであればすぐに使える。TeX Live のインストール手順は「Linux に TeX Live 2026 をインストールする」を参照。

文書クラスの選び方​

日本語文書では以下のクラスを使う。

ひな型（jarticle）​

jarticle を使った基本的なサンプルは以下のとおり。

% pLaTeX サンプル文書 — 主要機能を網羅
\documentclass[a4paper,12pt]{jarticle}

%% ========== パッケージ ==========
\usepackage{amsmath, amssymb}      % 数式強化
\usepackage{graphicx}              % 図の取り込み
\usepackage{color}                 % 色指定
\usepackage{fancyhdr}              % ヘッダ・フッタ
\usepackage{geometry}              % ページレイアウト
\usepackage{enumerate}             % 列挙カスタマイズ
\usepackage{url}                   % URL 表示
\usepackage{multicol}              % 段組み
\usepackage{booktabs}              % 高品質な表罫線
\usepackage{array}                 % 表列書式拡張
\usepackage{verbatim}              % verbatim 環境
\usepackage{ascmac}                % 囲み環境（screen, itembox など）
\usepackage{okumacro}              % ルビ・圏点など（pLaTeX 定番）
\usepackage{setspace}              % 行間調整
\usepackage{listings}              % ソースコードリスト
\usepackage{xcolor}                % 色（listings 用）
\usepackage{caption}               % キャプション書式

%% ========== ページレイアウト ==========
\geometry{top=25mm, bottom=25mm, left=25mm, right=25mm}
\setlength{\headheight}{17pt}
\addtolength{\topmargin}{-5pt}

%% ========== ヘッダ・フッタ ==========
\pagestyle{fancy}
\fancyhf{}
\lhead{pLaTeX サンプル文書}
\rhead{\today}
\cfoot{\thepage}
\renewcommand{\headrulewidth}{0.4pt}

%% ========== listings 設定 ==========
\lstset{
  basicstyle=\ttfamily\small,
  keywordstyle=\color{blue}\bfseries,
  commentstyle=\color{green!50!black},
  stringstyle=\color{red!70!black},
  numbers=left,
  numberstyle=\tiny\color{gray},
  frame=single,
  breaklines=true,
  tabsize=4,
}

%% ========== タイトル情報 ==========
\title{\textbf{pLaTeX 主要機能サンプル}\\[5pt]
       \large --- 日本語 \LaTeX の典型的な使い方 ---}
\author{サンプル太郎\thanks{サンプル大学 情報工学部}
        \and サンプル花子}
\date{\today}

%% ================================================================
\begin{document}
%% ================================================================

\maketitle
\thispagestyle{fancy}

\begin{abstract}
本文書は pLaTeX の主要機能を一通り示すサンプルである。
文書クラス・パッケージの読み込み、日本語組版特有の機能、
数式、表、図、相互参照、脚注、ルビ、圏点、
ソースコードリスト、段組み、カスタムコマンドなど
を順を追って解説する。
\end{abstract}

\tableofcontents
\newpage

%% ================================================================
\section{日本語組版の基本}
%% ================================================================

\subsection{和文・欧文の混在}

pLaTeX は日本語と欧文を自然に混在させることができる。
たとえば「Hello, World!」や \texttt{LaTeX2e} のような
ASCII 文字は自動的に適切なスペースが挿入される。

全角文字と半角文字の間隔調整は pLaTeX が自動で行う：
日本語English日本語、数字123日本語、記号\%日本語。

\subsection{ルビ（振り仮名）}

\texttt{okumacro} パッケージの \verb|\ruby| コマンドでルビを振れる。

\begin{center}
  \ruby{漢字}{かんじ}、\ruby{情報処理}{じょうほうしょり}、
  \ruby{自然言語}{しぜんげんご}\ruby{処理}{しょり}
\end{center}

\subsection{圏点}

\texttt{okumacro} の \verb|\kenten| で圏点（傍点）を付ける。

\begin{center}
  \kenten{重要な箇所}には圏点を打つことができる。
\end{center}

\subsection{文字サイズ}

{\tiny 極小} {\scriptsize 脚注} {\footnotesize 小} {\small やや小}
{\normalsize 標準} {\large やや大} {\Large 大} {\LARGE 特大}
{\huge 超大} {\Huge 最大}

\subsection{文字装飾}

\begin{itemize}
  \item \textbf{ボールド（太字）}
  \item \textit{イタリック（欧文）}
  \item \textsl{スラント}
  \item \textsc{Small Caps}
  \item \texttt{タイプライタ体（等幅）}
  \item \underline{下線付きテキスト}
  \item \textcolor{red}{赤色テキスト}
  \item \textcolor{blue!70!black}{青色テキスト}
  \item \colorbox{yellow}{ハイライト背景}
\end{itemize}

%% ================================================================
\section{文書構造}
%% ================================================================

\subsection{見出し階層}

pLaTeX（\texttt{jarticle}）では以下の見出し階層が使える：
\verb|\section|、\verb|\subsection|、\verb|\subsubsection|、
\verb|\paragraph|、\verb|\subparagraph|。

\subsubsection{サブサブセクション例}
これはサブサブセクションである。

\paragraph{パラグラフ見出し}
これはパラグラフ見出しの例。インデントなしで本文が続く。

\subsection{脚注}

本文中に脚注\footnote{これが脚注のテキストである。ページ下部に自動配置される。}
を付けることができる。複数の脚注\footnote{2つ目の脚注。番号は自動採番される。}
も使える。

\subsection{相互参照}

\verb|\label| を付けると、
\verb|\ref| や \verb|\pageref| で参照できる。
例：次節は第~\ref{sec:math}~節（\pageref{sec:math}~ページ）。

%% ================================================================
\section{数式環境}
\label{sec:math}
%% ================================================================

\subsection{インライン数式とディスプレイ数式}

インライン数式：$E = mc^2$、$\alpha + \beta = \gamma$、
$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$。

ディスプレイ数式：
\[
  \int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
\]

\subsection{equation・align 環境}

番号付き数式（\texttt{equation}）：
\begin{equation}
  \label{eq:euler}
  e^{i\pi} + 1 = 0
\end{equation}
式~\eqref{eq:euler} はオイラーの等式である。

複数行の整列（\texttt{align}）：
\begin{align}
  (a+b)^2 &= a^2 + 2ab + b^2 \\
  (a-b)^2 &= a^2 - 2ab + b^2 \\
  (a+b)(a-b) &= a^2 - b^2
\end{align}

\subsection{行列・ベクトル}

\begin{equation}
  A = \begin{pmatrix} a_{11} & a_{12} \\ a_{21} & a_{22} \end{pmatrix},\quad
  \det(A) = a_{11}a_{22} - a_{12}a_{21}
\end{equation}

\subsection{場合分け・分数・極限}

\begin{equation}
  f(x) = \begin{cases}
    x^2       & (x \geq 0) \\
    -x^2      & (x < 0)
  \end{cases}, \qquad
  \lim_{n\to\infty} \left(1 + \frac{1}{n}\right)^n = e
\end{equation}

%% ================================================================
\section{表（tabular 環境）}
%% ================================================================

\subsection{基本的な表}

\begin{table}[h]
  \centering
  \caption{都市別気温データ（仮）}
  \label{tab:temp}
  \begin{tabular}{lrrr}
    \toprule
    都市   & 最高気温 (°C) & 最低気温 (°C) & 平均気温 (°C) \\
    \midrule
    東京   & 35.2 & 25.1 & 29.8 \\
    大阪   & 36.4 & 26.3 & 31.0 \\
    札幌   & 28.7 & 19.5 & 23.9 \\
    那覇   & 32.1 & 27.4 & 29.8 \\
    \bottomrule
  \end{tabular}
\end{table}

\subsection{複雑な表（\texttt{array} 拡張・セル結合）}

\begin{table}[h]
  \centering
  \caption{プログラミング言語比較}
  \label{tab:lang}
  \begin{tabular}{|l|c|c|c|}
    \hline
    言語       & 型付け   & パラダイム       & 主な用途 \\
    \hline\hline
    Python     & 動的     & マルチ           & AI/データ分析 \\
    Rust       & 静的     & システム         & システム開発 \\
    Haskell    & 静的     & 関数型           & 研究・金融 \\
    JavaScript & 動的     & マルチ           & Web フロント \\
    \hline
  \end{tabular}
\end{table}

表~\ref{tab:temp} と表~\ref{tab:lang} のように \verb|\label/\ref| で参照できる。

%% ================================================================
\section{リスト環境}
%% ================================================================

\subsection{箇条書き（itemize）}

\begin{itemize}
  \item 第一の項目
  \item 第二の項目
    \begin{itemize}
      \item 入れ子の項目 A
      \item 入れ子の項目 B
    \end{itemize}
  \item 第三の項目
\end{itemize}

\subsection{番号付きリスト（enumerate）}

\begin{enumerate}[(1)]   % enumerate パッケージで書式指定
  \item 最初のステップ
  \item 次のステップ
  \item 最後のステップ
\end{enumerate}

\subsection{説明リスト（description）}

\begin{description}
  \item[pLaTeX] 日本語対応の \LaTeX 処理系
  \item[upLaTeX] Unicode 対応の pLaTeX 後継版
  \item[LuaLaTeX] Lua スクリプトが使える \LaTeX 処理系
\end{description}

%% ================================================================
\section{verbatim・ソースコード}
%% ================================================================

\subsection{verbatim 環境}

\begin{verbatim}
#include <stdio.h>
int main(void) {
    printf("Hello, pLaTeX!\n");
    return 0;
}
\end{verbatim}

\subsection{listings によるシンタックスハイライト}

\begin{lstlisting}[language=Python, caption={フィボナッチ数列（Python）}]
def fibonacci(n: int) -> int:
    """再帰でフィボナッチ数を計算する"""
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

# 最初の 10 項を出力
for i in range(10):
    print(f"F({i}) = {fibonacci(i)}")
\end{lstlisting}

%% ================================================================
\section{囲み・強調ボックス}
%% ================================================================

\texttt{ascmac} パッケージの \texttt{itembox}、\texttt{screen} 等を活用できる。

\begin{itembox}[l]{重要なポイント}
  \begin{itemize}
    \item pLaTeX は \texttt{jarticle} / \texttt{jbook} 文書クラスを使う
    \item \texttt{okumacro} でルビ・圏点が使える
    \item \texttt{platex + dvipdfmx} で PDF を生成する
  \end{itemize}
\end{itembox}

\vspace{5pt}

\begin{screen}
\texttt{screen} 環境：端末表示風の囲み枠。ソース例や出力例の表示に使う。
\end{screen}

%% ================================================================
\section{段組み}
%% ================================================================

\texttt{multicol} パッケージで途中から 2 段組みに切り替えられる。

\begin{multicols}{2}
  \noindent
  これは 2 段組みの左カラムである。
  日本語の段組みも pLaTeX は自然に処理する。
  長い文章でも自動的に均等に振り分けられるため、
  新聞・雑誌スタイルの組版に適している。

  \columnbreak

  \noindent
  こちらが右カラムである。
  \verb|\columnbreak| で強制的に段を切り替えることもできる。
  数式 $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$
  もインラインで使える。
\end{multicols}

%% ================================================================
\section{行間・スペーシング調整}
%% ================================================================

\subsection{水平スペース}

単語間の空白：a\,b（\verb|\,| 細空白）、
a\enspace b（\verb|\enspace|）、
a\quad b（\verb|\quad|）、
a\qquad b（\verb|\qquad|）。

\subsection{垂直スペース}

\verb|\vspace| で垂直スペースを追加できる。

\vspace{5mm}
上から 5mm の垂直スペースを挿入した後のテキスト。
\vspace{5mm}

\subsection{行間}

{\setstretch{1.8}
この段落は \texttt{setspace} パッケージの
\texttt{setstretch} で行間を 1.8 倍に広げている。
日本語文書では 1.5〜2.0 程度の行間が読みやすいとされる。
}

%% ================================================================
\section{カスタムコマンドと環境}
%% ================================================================

\subsection{カスタムコマンド定義}

\newcommand{\R}{\mathbb{R}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\highlight}[1]{\colorbox{yellow!60}{#1}}
\newcommand{\term}[1]{\textbf{\textit{#1}}}  % 用語強調

定義した例：$\R$（実数体）、$\N$（自然数）。
\highlight{ハイライトされたテキスト}。
\term{機械学習}（Machine Learning）は人工知能の一分野である。

\subsection{カスタム環境定義}

\newenvironment{mybox}[1]{%
  \begin{center}\begin{tabular}{|p{0.85\linewidth}|}
  \hline\vspace{1pt}
  \textbf{#1}\\[2pt]
}{%
  \\\hline\end{tabular}\end{center}
}

\begin{mybox}{自作の囲み枠}
  \verb|\newenvironment| を使って独自の環境を定義できる。
  引数も受け取れるので柔軟な再利用が可能。
\end{mybox}

%% ================================================================
\section{参考文献}
%% ================================================================

文献引用は \verb|\cite| コマンドで行う~\cite{knuth1984,lamport1994,okumura2020}。
文末に参考文献リストが出力される。

%% ================================================================
%% 参考文献リスト（thebibliography 環境）
%% ================================================================
\begin{thebibliography}{99}

\bibitem{knuth1984}
  D.~E. Knuth,
  \textit{The \TeX book},
  Addison-Wesley, 1984.

\bibitem{lamport1994}
  L.~Lamport,
  \textit{\LaTeX: A Document Preparation System}, 2nd ed.,
  Addison-Wesley, 1994.

\bibitem{okumura2020}
  奥村晴彦・黒木裕介,
  『\LaTeXe 美文書作成入門』第 8 版,
  技術評論社, 2020.

\end{thebibliography}

\end{document}