Webアプリ開発テンプレート webapp-blueprint の紹介

webapp-blueprintは、Webアプリの実装、開発環境、設計原則、品質検査、Coding Agent向けの手順をまとめたプロジェクトテンプレートです。

特定の技術スタックを完成品として配るboilerplateではありません。 作るものを確認してから技術上の未決事項を選び、決めた規約を機械的に検査できる状態で開発を始めるためのrepoです。

入っているもの

monorepoにはReactのフロントエンド、API、BDD形式のE2E、Terraformの土台があります。 開発基盤はpnpm workspace、Turborepo、mise、Vitest、Playwright、oxlint、oxfmtが中心です。

依存方向、feature境界、依存versionの固定、秘密の実値混入、GitHub Actionsの構文なども検査します。 ローカルとCIは同じmise run checkを入口にします。

clean cloneでは、依存を入れてから検査します。

mise install
mise run install
mise run check

フロントエンドとAPIには小さな縦切りも入っています。 検査対象が空のまま全部greenになるのを避け、architecture ruleやテストが実コードへ噛んでいることを確認するためです。

clone後のbootstrap

最初にCoding Agentへ次のように依頼します。

bootstrap-template skillでこのprojectを初期化して

bootstrap-templateはproject briefを作り、一次資料を調べ、技術上の未決事項を順番に聞きます。 回答が揃ってから、選んだstackだけをrepoへ反映します。

たとえばclone直後の契約層は空です。 protobufとConnectRPCを使うrecipe、TypeSpecからOpenAPIを生成するrecipeはありますが、どちらを採用するかは決めていません。 契約生成物のdrift検査も、bootstrapで契約層を選び、生成経路を接続した後に有効になります。

bootstrapが終わると、READMEの案内はproject固有のsetup-project skillへ置き換わります。 以後は新しいcheckoutやworktreeで、そのprojectに必要なsetupを実行できます。

三つの寿命に分けたドキュメント

このrepoでは、ドキュメントを三つに分けています。

場所	内容
docs/principles/	ツール名に依存しない要件
docs/recipes/	現在のツールで要件を満たす方法
repo直下の設定とscript	実際に動く検査と処理

たとえば「秘密は参照だけを置く」が原則です。 現在は1Password CLIを使い、.env.exampleには実値ではなくop://参照だけを置きます。

ドキュメントはmise run docs:devで検索できます。 docs MCPも登録しているため、Coding Agentもrepo内の判断を検索できます。

RamuneとAgent向けの設定

.claude/と.agents/には、ADR作成、ドキュメント整理、commit、PR作成などのskillを同梱しています。 ClaudeとCodexによるPRレビューworkflowもありますが、bootstrapでproviderを選ぶまではdisabledです。

tools/ramune/には、複数のCoding Agentをタスクグラフで動かす仕組みも入っています。 Ramuneは別の記事で紹介します。

使いどころ

新しいWebアプリを立ち上げ、初期の技術判断から継続的な品質検査までを同じrepoで管理したい場合に向いています。

一方、小さなデモを数時間で作る用途には重いと思います。 ファイル数を減らすより、プロジェクトが続いたときに規約と実装がずれにくいことを優先しているためです。

公開repoはgithub.com/NiraiHayakawa/webapp-blueprintです。