decisiondecided

実験用フロントエンド完結アプリの配置とビルド方針

Astroブログの public/apps/ 配下に、ビルドなしCDN読み込みの単一HTMLアプリを配置する方針を採用する。天井の低いチャットセッションで完結できる実験場を確保する。

文脈

Astro で構築済みのブログリポジトリを、実験用フロントエンド完結アプリの配置場所としても活用したい。以下の制約がある。

  • チャットセッションの上限は1メッセージ約10,000文字、8セッションで生成完了しないとトークン切れ
  • 公開前提(他人がURLで到達できる)
  • フロントエンド完結(バックエンド料金ゼロ)
  • 枯れた技術・コード量最少を優先
  • ハルシネーションを避けるため、シェル(配置・ビルド・依存)を先に固定したい

真面目な単独プロダクトなら独立リポジトリを立てるべきだが、本件はあくまで実験場であり、失敗容認・使い捨て可能な軽さを優先する。

決定

Astro ブログの既存リポジトリ内 public/apps/<name>/ 配下に、ビルドなしの単一HTMLアプリを配置する。

  • 配置パス: public/apps/<name>/index.html
  • URL: /{blog-origin}/apps/<name>/
  • 依存はすべて CDN 読み込み、npm install 不要
  • Astro のビルドプロセスに一切干渉しない(public/ は素通し)
  • 各アプリは独立し、共通レイアウトやテーマは共有しない
  • アプリ間のデータ共有は行わない(各アプリは自己完結)

技術スタックの詳細は用途別に別ADRで定める。

  • ツール系: 2026-09-25-tool-apps-tech-stack
  • ゲーム系: 2026-09-25-game-apps-tech-stack

影響

良い影響:

  • 既存ブログのビルド・デプロイ・URL構造に影響しない
  • アプリ追加・削除がファイル単位で完結、Git履歴も単純
  • ホスティングコストが増えない(静的ファイル配信のみ)
  • 実験失敗時は該当ディレクトリを消すだけ
  • 「単一HTMLに CDN 読み込み」は最も枯れた構成でLLMが安定して生成できる

悪い影響・トレードオフ:

  • アプリ数が増えると public/apps/ が肥大化する
  • 共通部品を作りたくなった時に再利用機構がない
  • 将来 SSR やビルド前提のフレームワーク(Svelte等)を導入したくなった場合、この方針から外れる必要がある
  • 本格プロダクト化する場合は独立リポジトリへの切り出しが必要

将来の見直しトリガー:

  • アプリ数が10を超えた場合、ディレクトリ構造や共通化を再検討
  • 特定アプリが本格運用に耐えるレベルに育った場合、独立リポジトリへ移管
  • ブログ本体のビルド時間に影響が出始めた場合(public/ 巨大化)

検討した代替案

  • 独立リポジトリを新設: 真面目にやるなら妥当だが、実験場としては重い。壁打ちのハードルを上げてしまう。却下。
  • Astro ページとして src/pages/apps/ に配置: Astro のビルド対象になり、コンポーネント再利用や型の恩恵は受けられる。しかし LLM に渡す前提知識が増え(Astro構文、frontmatter、レイアウト継承)、10,000文字制約下では不利。却下。
  • GitHub Pages の別リポジトリ: ドメインが分散する。ブログとの導線が弱い。却下。
  • Netlify Functions などサーバレス併用: 「バックエンド料金ゼロ」の原則と、実験場としての軽さを損なう。却下。
src/content/ja/decision/2026-09-25-tool-apps-tech-stack.md
```markdown
---
date: 2026-09-25
title: ツール系アプリの技術スタック
description: プロンプト管理・メモ・ADRビューア等のツール系アプリを構築する際の技術スタックを Shoelace + Alpine.js + Pico.css + Dexie + File System Access API に固定する。LLM生成の安定性と分割容易性を優先する。
type: decision
tags: [architecture, apps, frontend, tools]
status: decided
related:
- 2026-09-25-experimental-apps-placement
- 2026-09-25-game-apps-tech-stack
---
## 文脈
[[2026-09-25-experimental-apps-placement]] で決定した実験場に配置する、ツール系アプリ(プロンプト管理、メモ、家計簿、ADRビューア等)のための技術スタックを固定する必要がある。
制約と要件:
- 1メッセージ10,000文字、8セッション以内で完成させたい
- LLMが安定して生成できる枯れた技術のみ
- UIを一から作らず「これ使え」で済むシェルが欲しい
- 状態管理・スタイル・データ永続化までカバー
- ユーザー資産(プロンプト本体等)はアプリに閉じ込めず、ローカルファイルとして残せると理想的
第一号アプリは**プロンプト管理**を想定。
## 決定
以下のスタックを固定する。すべてCDN読み込み、ビルド不要。
**UIコンポーネント**: Shoelace (Web Components, v2系固定)
- `<sl-button>` `<sl-dialog>` `<sl-tree>` 等をタグとして直接使用
- フレームワーク非依存で長寿命が期待できる
**状態管理・宣言的UI**: Alpine.js (v3系固定)
- `x-data` `x-show` `x-for` で React の1/10のコード量
- 小規模ツールに最適
**スタイル**: Pico.css (classless)
- HTMLタグ書くだけで整う。追加CSSは最小限
- Shoelace のテーマと衝突しない範囲で併用
**データベース**: Dexie.js (IndexedDB ラッパー, v4系固定)
- プロンプト本体・検索インデックス等の構造化データ
- 生 IndexedDB API の冗長さを回避
**ファイルシステム連携**: File System Access API (ブラウザネイティブ)
- `showDirectoryPicker()` でユーザー指定ディレクトリを保持
- ディレクトリハンドルは IndexedDB に永続化し、再訪時も同じディレクトリを覚える
- Chrome/Edge 限定機能。Firefox/Safari では機能縮退(IndexedDBのみで動作)
**UI設定の永続化**: localStorage
- テーマ、最後に開いたタブ、トグル状態等の軽量データ
**分割方針**: ES Modules
- `index.html` は薄く保つ(`<body>` 直下は最小限 + `<script type="module" src="./main.js">`)
- JSは責務ごとに分割: `main.js` / `state.js` / `db.js` / `fs.js` / `ui-<name>.js` / `utils.js`
- 依存方向は `main → ui → state → db` の一方向、循環参照禁止
- 1ファイル10,000文字以内厳守
## 影響
**良い影響**:
- 1ファイル = 1責務 = 1メッセージで生成可能、8セッション制約に収まる
- Web Components と ES Modules は2017年以降の枯れた標準
- LLM に渡す前提知識が「このスタック使え」の1行で済む
- ユーザー資産を File System Access API でローカルファイルとして残せる(Git 管理可能)
- IndexedDB により大量データ・検索・インデックスに耐える
**悪い影響・トレードオフ**:
- File System Access API は Chrome/Edge 限定。Firefox/Safari ユーザーは機能縮退する
- Shoelace の Web Components はカスタマイズが CSS 変数経由で、深いカスタマイズには不向き
- Alpine.js は大規模化すると保守性が落ちる(本件は実験場なので許容)
- Pico.css と Shoelace のスタイル境界に注意が必要
**将来の見直しトリガー**:
- Shoelace v3 のメジャー変更が入った場合、v2 固定継続か移行かを判断
- File System Access API が Firefox/Safari で実装された場合、フォールバック実装を削減
- 1アプリが 10ファイル・10万文字を超え始めた場合、Astro/Svelte 移行を検討
## 検討した代替案
- **React + Vite**: エコシステム最大だがビルド前提、コード量が多い、LLM が古いバージョンの書き方を混ぜがち。実験場に過剰。却下。
- **Svelte + SvelteKit**: 構文が最小で魅力的だが、ビルド前提でありシェルが Astro と競合する。却下。
- **素の HTML + 生 IndexedDB API**: 最も枯れているが、IndexedDB の生 API が冗長すぎて LLM 生成が不安定。却下。
- **Tailwind CSS**: 表現力は高いが class 羅列で1行が長大化、10,000文字制約に不利。却下。
- **daisyUI**: Tailwind 前提。上記理由により却下。
- **ストレージを IndexedDB 単一化**: シンプルだが、UI設定まで IndexedDB を使うのは過剰。localStorage 併用が実用的。却下。
src/content/ja/decision/2026-09-25-game-apps-tech-stack.md
---
date: 2026-09-25
title: ゲーム系アプリの技術スタックと分類基準
description: ゲーム系アプリを DOM完結型・Canvas 2D型・PixiJS型の3タイプに分類し、それぞれのスタックを固定する。第一号ゲームはツール系スタックを流用可能な DOM完結型から着手する。
type: decision
tags: [architecture, apps, frontend, games]
status: decided
related:
- 2026-09-25-experimental-apps-placement
- 2026-09-25-tool-apps-tech-stack
---
## 文脈
[[2026-09-25-experimental-apps-placement]] で決定した実験場に配置する、ゲーム系アプリのための技術スタックを定める必要がある。ツール系と異なり、ゲームは**要件によって最適スタックが分岐する**(描画方式、リアルタイム性、スプライト数)。
制約:
- 1メッセージ10,000文字、8セッション以内で完成
- LLMが安定して生成できる枯れた技術
- ゲームロジックに集中し、UI・入力機は既製のものを使う
個別ゲームごとに ADR を書くのではなく、**分類基準とタイプ別スタック**を1枚にまとめる。
## 決定
ゲームを3タイプに分類し、各タイプのスタックを固定する。個別ゲームは本 ADR に従うことを明記すればよい。
### タイプA: DOM完結ゲーム(第一選択)
**適用**: 数独、マインスイーパ、2048、ワードル、テトリス、ソリティア、ライフゲーム等
- 描画: DOM + CSS Grid / Flexbox
- アニメ: CSS transition / animation
- 状態管理: Alpine.js
- UI: Shoelace(メニュー・設定ダイアログ)
- スタイル: Pico.css
- セーブデータ: localStorage
- 入力: 標準キーボード / pointer イベント
ツール系スタック([[2026-09-25-tool-apps-tech-stack]])をほぼ流用可能。**ゲーム第一号はここから着手する**。
### タイプB: Canvas 2D ゲーム
**適用**: シューティング、ブロック崩し、簡易アクション、簡易パズル等
- 描画: Canvas 2D API(生、ライブラリ不要)
- ゲームループ: `requestAnimationFrame`
- 入力: Keyboard / Pointer / Gamepad API(ブラウザ標準)
- UI(メニュー・スコア表示等): Shoelace(Canvas 外に DOM で配置)
- セーブデータ: localStorage(設定・ハイスコア)/ IndexedDB(リプレイ等大容量)
Canvas 2D は2011年以降の枯れた標準。LLM 生成が安定する。
### タイプC: PixiJS ゲーム
**適用**: スプライト100個以上、パーティクル、複雑なアニメーション
- 描画: PixiJS **v7 系固定**(バージョン明示必須、LLM が古い書き方を混ぜないため)
- それ以外はタイプBと同じ
- CDN 読み込み
### 共通分割方針
タイプ B/C は責務ごとに JS 分割:
- `main.js` エントリポイント
- `game.js` ゲーム状態・ロジック
- `input.js` 入力処理
- `render.js` 描画
- `state.js` セーブ・ロード
- `ui-*.js` DOM 側 UI(メニュー等)
タイプA はツール系分割方針をそのまま流用。
## 影響
**良い影響**:
- ゲーム着手時に「どのタイプか」を1問答えるだけでスタックが確定
- タイプA は既存ツール系スタックの検証も兼ねる
- タイプB は外部ライブラリゼロで LLM 生成が最も安定
- タイプC も PixiJS v7 固定により生成安定性を確保
- タイプ分類により、個別ゲームで ADR を量産する必要がない
**悪い影響・トレードオフ**:
- タイプ判定を誤ると後から書き直しになる(例: 当初 DOM で始めたが実は Canvas が必要だった)
- PixiJS v7 固定は将来のメジャーバージョン移行コストを先送りしている
- 3Dゲーム・ネットワーク対戦等はこの分類でカバーしない
**将来の見直しトリガー**:
- PixiJS v8 以降で LLM 生成が安定した場合、バージョン固定を見直し
- 3D や WebGL 直叩きが必要なゲームに着手する場合、タイプDを追加
- タイプA/B/C のいずれかで慢性的に破綻が出た場合、該当タイプのスタック再選定
## 検討した代替案
- **Phaser を採用**: 高機能ゲームフレームワークだが API が広大で LLM が古い書き方を混ぜがち、ハルシネーション多発。実験場には過剰。却下。
- **Three.js を採用**: 3D は実験場の目的(軽量・枯れた・コード最少)と合わない。却下。
- **Unity WebGL**: ビルド前提でシェルが完全に別物。却下。
- **タイプ分類せず単一スタックに統一**: ゲームの多様性を吸収できず、DOM で足りるものに Canvas を使う過剰実装や、Canvas が必要なものを DOM で無理する事態を招く。却下。
- **ゲーム個別に ADR を書く**: ADR が量産され、意思決定の重複が発生する。分類基準1枚に集約する方が資産価値が高い。却下。