Knowledge Bundle
Bundle OKF 0.1 · 6 conceitos · hanamizuno/spider
Open source Repository Open in the app JSON README (API)
About
# Knowledge Bundle
このディレクトリは [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) に準拠した知識バンドルです。AI エージェントと人間の双方が、プレーンな Markdown として読み書きできる共有メモリとして運用します。
このテンプレートでは **スケルトンのみ** を同梱します。ディレクトリ構成と予約ファイル (`index.md` / `log.md`)、そして「サブディレクトリごとに 1 つだけ」の見本ドキュメントを置いてあります。プロジェクトが育つにつれて、サンプルは実コンテンツで上書きしてください。プレースホルダを溜め込まないようにしましょう。
ユーザー向けのドキュメント (`README.md`) や AI エージェント向けのガイドライン (`AGENTS.md`) とは異なり、このバンドルは **コードや git 履歴からは読み取りにくい意思決定・背景・運用知見** を蓄積するための場所です。コードベースや `git log` から復元できる情報は書かないでください。
## レイアウト
* [architecture/](architecture/) — システム構造・データフロー・段階的なビルド計画
* [adr/](adr/) — Architecture Decision Records (決定とその理由)
* [conventions/](conventions/) — テスト・エラーハンドリング等のリポジトリ横断の取り決め
* [runbooks/](runbooks/) — 障害対応や定型運用の手順
* [research/](research/) — 調査・比較検討のスナップショット
* [log.md](log.md) — バンドル全体の更新ログ
## OKF 運用ルール
* `index.md` と `log.md` は予約ファイル名です。概念ドキュメントとして使ってはいけません。
* バンドルルートの `index.md` のみ `okf_version` フロントマターを持てます。
* それ以外の `.md` フ
Details
- Kind
- OKF bundles
- Topic
- Version control
- Publisher
- hanamizuno
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Open pull requests
- 3
- Last push
- 2026-09-01T15:22:41Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-09-09 12:02:17
- Updated
- 2026-09-09 12:02:17
- Origin id
hanamizuno/spider:docs/knowledge/index.md
README
# ブラウザゲームテンプレート AI エージェントを活用した開発を前提とする、ブラウザゲーム開発用テンプレートです。 canvas ベースのゲームと HTML 要素（フォーム等）中心のゲームの両方を想定しています。 ## 機能一覧 ### ゲーム開発 - Vite + React + TanStack Router + Panda CSS + Ark UI のクライアント基盤（サンプルゲーム 2 種同梱: canvas のボール避け / フォームの計算クイズ） - 自作の薄いゲームループ（固定タイムステップ・pause/step/timeScale・シード付き乱数 — `src/game/`、ライブラリ非依存） - Hono API サーバー同梱（開発時は Vite が `/api` を proxy、本番は SPA 配信 + API の単一プロセス） - デバッグパネル（開発時のみ）: ゲームパラメーターと Panda CSS デザイントークンをランタイム調整 → 調整値をエクスポートしてエージェントがコードへ反映 - フィードバックユーティリティ: プレイ中の気づきを `feedback/*.md` に保存し、AI エージェントへの申し送りに - GitHub Issue 発行ユーティリティ: ゲーム状態スナップショット付きで Issue 作成画面を開く - AI テストプレイの窓口 `window.__GAME_DEBUG__`: シード固定・入力注入・フレーム送りで決定論的にテストプレイ（手順: [docs/knowledge/runbooks/agent-playtest.md](docs/knowledge/runbooks/agent-playtest.md)） ### 開発基盤 - TypeScript による型安全な開発環境 - Biome による高速なフォーマット・リント - テスト・ベンチマーク・カバレッジ計測（vitest projects — node / happy-dom, しきい値 80%） - pre-commit hooks による品質保証（biome / typecheck / secretlint） - GitHub Actions による CI（Node 24/25 マトリクス、Actions は commit SHA・Dev Container Features と Docker ベースイメージは sha256 digest で固定、依存自動更新） - PR 自動ラベリング（actions/labeler — ハーネス変更 PR に `meta` ラベル）とラベル定義の同期（`.github/labels.yml`） - セキュリティスキャン（secretlint / pnpm audit / Trivy — CRITICAL/HIGH 検出で CI を fail） - SBOM 生成（CycloneDX、cdxgen） - Dockerfile / GitHub Actions 自体のリント（hadolint / actionlint / zizmor） - VS Code Dev Containers: AI エージェントツールチェーン（Claude Code CLI、Codex CLI、GitHub CLI、共通ユーティリティ）を [Dev Container Features](https://containers.dev/implementors/features/) と post-create セットアップで重ねて注入 - Chrome DevTools MCP + headless Chromium: エージェントがコンテナ内で画面の見た目をデバッグ（スクリーンショット・コンソール・ネットワーク確認） ## このテンプレートの導入手順 テンプレートからリポジトリを作成したら: 1. `package.json` の `name` をプロジェクト名に変更する（必要なら `description` 等のメタデータも追加）。 2. `LICENSE` のプレースホルダ（`[yyyy]`、`[name of copyright owner]`）を記入する — もしくはライセンスごと差し替える。 3. `.github/CODEOWNERS` の `@REPLACE-ME` を実在の GitHub ユーザー / チームに置き換える。 4. `docs/knowledge/` のサンプルドキュメントを実プロジェクトの知識で差し替える（運用ルールは `docs/knowledge/index.md` を参照）。 5. Issue 発行ユーティリティを使う場合は `.env.example` を `.env` にコピーして `VITE_REPO_URL` を設定する。 6. `corepack enable && pnpm install && pnpm release-check` を実行し、セットアップ後のプロジェクトが健全なことを確認する。 ## セットアップ ```bash corepack enable pnpm install ``` `pnpm` は `package.json` の `packageManager` フィールド経由で corepack が自動的に正しいバージョンを使用します。 ### pre-commit hooks（任意） [prek](https://github.com/j178/prek) を[インストール](https://github.com/j178/prek?tab=readme-ov-file#installation)した後： ```bash prek install ``` ## 主なコマンド ```bash pnpm dev # Vite (:5173) + Hono API (:3000) を並行起動 pnpm test # テスト（panda codegen を内包） pnpm test:cov # カバレッジ計測 pnpm bench # ベンチマーク pnpm fmt # フォーマット適用 pnpm lint # リント pnpm check # biome check + typecheck pnpm release-check # CI 相当の一括チェック（biome ci + typecheck + test） pnpm scan:secrets # シークレット検出 pnpm build # panda codegen → vite build → tsc（dist/client + dist/server） pnpm start # 本番モードで起動（:3000、SPA 配信 + API） ``` 開発サーバー起動後、`http://localhost:5173` でサンプルゲームを遊べます。 画面右下の🐞ボタン（または `Ctrl+Shift+D`）でデバッグパネルが開きます。 詳細は [AGENTS.md](AGENTS.md) を参照。 ## プロジェクト構造 ディレクトリ構成・設定ファイルの詳細は [AGENTS.md](AGENTS.md) を参照してください。 ## AI Agent Dev Container VS Code Dev Container を AI コーディングエージェント（Claude Code / Codex 等）の実行環境としても利用できます。同梱ツール・認証手順・ホスト設定の継承・サンドボックスのモード・PAT 運用などの詳細は [.devcontainer/README.md](.devcontainer/README.md) を参照してください。 ## リリースチェックリスト 1. `pnpm release-check` を実行してすべてのチェックが通ることを確認 2. `CHANGELOG.md` を更新 3. バージョンタグを作成 ## ライセンス [MIT](LICENSE)。`LICENSE` 内の `[yyyy] [name of copyright owner]` は派生先で年と著作権者名に置換してください。