実験用フロントエンド完結アプリの配置とビルド方針
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 などサーバレス併用: 「バックエンド料金ゼロ」の原則と、実験場としての軽さを損なう。却下。
```markdown---date: 2026-09-25title: ツール系アプリの技術スタックdescription: プロンプト管理・メモ・ADRビューア等のツール系アプリを構築する際の技術スタックを Shoelace + Alpine.js + Pico.css + Dexie + File System Access API に固定する。LLM生成の安定性と分割容易性を優先する。type: decisiontags: [architecture, apps, frontend, tools]status: decidedrelated: - 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 併用が実用的。却下。---date: 2026-09-25title: ゲーム系アプリの技術スタックと分類基準description: ゲーム系アプリを DOM完結型・Canvas 2D型・PixiJS型の3タイプに分類し、それぞれのスタックを固定する。第一号ゲームはツール系スタックを流用可能な DOM完結型から着手する。type: decisiontags: [architecture, apps, frontend, games]status: decidedrelated: - 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枚に集約する方が資産価値が高い。却下。