アプリハブ
— Cowork でつくり、ポータルから配る仕組み

1この文書の位置づけ — 4 つ目の方式全員

同じフォルダに、社内サービスを非エンジニアに作らせるための資料が 3 本ある。この文書は 4 つ目の方式の設計書であり、既存 3 方式を置き換えるものではない。

2何を解くのか — プラン B の残課題用意する人

プラン B（claude-code-internal-app-workflow-planb）は動く設計だが、実装を進める中で 4 つの摩擦が残った。アプリハブはこの 4 つを潰すためだけに存在する。

プラン B から引き継いで変えないもの：ベースは cf-internal-app-starter（Workers + D1 + R2 + KV + Access）／ Cloudflare の鍵は GitHub Actions にしか置かない ／ 本番は必ず人が承認する ／ ブランチは試用と本番を分ける。

33 分でわかる全体像全員

工程は 8 つ。このうちつくる人がやるのは 3 つ（②③④）だけである。

4設計の 3 原則用意する人

実装で迷ったときは、この 3 つに戻って決める。

原則 1 — 正本は GitHub にしかない

つくる人の手元のフォルダも、アップロードされた zip も、すべて写しである。消えても失われるものは無い。

• ポータルは zip を受け取ったら、必ず GitHub にコミットしてから「受け付けました」と言う。R2 に置いた zip は 90 日で消える調査用の控えであって、正本ではない
• したがって「Cowork のプロジェクトを消してしまった」は事故ではない。ポータルから落とし直せばよい

原則 2 — 危ないものはつくる人に渡さない

渡さないもの: Cloudflare の API トークン、Access の設定、wrangler.jsonc、.github/workflows/、本番の DB、他人のアプリ。

• これらは 保護パスとして、zip に入っていてもサーバ側で無視し、テンプレートの正本で上書きする（→ 16 章）
• つくる人が触れる設定は app.config.json ただ 1 つ。書けることは allowlist で限定する（→ 17 章）

原則 3 — 確かめる場所は試用環境（staging）

手元でビルドできない代わりに、アプリごとに試用環境を常設する。本番と同じ構成・同じ認証・別の DB。

• つくる人は <slug>-stg.apps.synon.co.jp を開いて確かめる。同僚に見てもらうときも同じ URL
• 試用環境の DB には本番のデータを入れない。入れると「試しに全部消す」が事故になる

5登場人物と権限全員

役割は 4 つ。ポータルの中の役割であって、Cloudflare Access のグループとは別物である点に注意（Access は「この URL を開いてよいか」だけを見る）。

役割はポータルの D1 に持つ。Cloudflare Access は「ポータルに入れる社員かどうか」までしか見ない。役割の判定はポータル側の責任である。

6工程 1管理者：アプリ枠をつくる管理者

画面

ポータル https://apps.synon.co.jp/admin/new で 6 項目を入れて［作成］。

裏で起きること

［作成］を押してから、つくる人に zip が渡るまで 9 手順・所要 40〜90 秒。ポータルは Queue に積んで即座に「準備中」を返し、進捗を画面で更新する。

完了条件

• https://mitsumori-stg.apps.synon.co.jp を開くと、テンプレートの「準備できました」画面が出る
• 社外のブラウザ（別アカウント）で開くと Access のログイン画面で止まる
• ポータルの一覧に「見積書つくるくん／準備完了」が出ている
• 担当者に Chatwork が届いている

7工程 2つくる人：受け取るつくる人

ポータルのアプリ詳細画面の［プロジェクトを受け取る］を押すと zip が落ちる。

mitsumori.zip
├── PROJECT.md              ← ★まずこれを Cowork に読ませる（作り方の説明書）
├── app.config.json         ← つくる人が触れる唯一の設定
├── .appmeta.json           ← slug とリポジトリ名（触らない）
├── data/                   ← ★データの置き場（→ 15 章）
│   ├── data.md                 表の作り方の説明
│   ├── migrations/
│   │   └── 0001_init.sql       表の定義。ここに書いたものが配信先に作られる
│   └── seed/
│       └── .gitkeep            初期データ（CSV / SQL）を置くと初回だけ入る
├── src/
│   ├── client/             ← 画面（React）
│   │   ├── App.tsx  main.tsx  index.html  styles.css
│   └── worker/             ← サーバ（API）
│       ├── index.ts
│       ├── lib/access.ts       ログインした人が誰かを取り出す（触らない）
│       ├── lib/db.ts           表を読み書きする道具
│       └── routes/sample.ts    お手本の API 1 本
├── docs/
│   └── SPEC.md             ← /service-spec が書き込む仕様書
└── .claude/
    ├── skills/             ← Cowork のスキル 4 本
    │   ├── service-spec/       何を作るかを決める
    │   ├── service-build/      仕様書どおりに実装する
    │   ├── service-pack/       アップロード用 zip をつくる
    │   └── service-fix/        配信が失敗したときに直す
    └── CLAUDE.md           ← Claude への恒久的な指示（触らない）

zip に入っていないもの：node_modules/、.git/、wrangler.jsonc、.github/、package-lock.json、実データ。理由は 15 章と 16 章で説明する。つくる人はこれらの存在を知らなくてよい。

8工程 3つくる人：Cowork で実装するつくる人

1. Cowork で新しいプロジェクトを作る（プロジェクト名 = アプリ名）
2. zip を展開したフォルダを、そのプロジェクトの作業フォルダとして接続する
3. Claude に「PROJECT.md を読んで」と言う。以降はスキルが誘導する

スキル 4 本の役割

Cowork でできること・できないこと

9工程 4つくる人：詰めて上げるつくる人

詰める（/service-pack）

$ /service-pack

  ✔ 構文チェック（TypeScript / SQL / JSON）… OK
  ✔ 禁止事項チェック … OK
  ✔ 保護パスは含めない … OK（4 ファイルを除外）
  ✔ サイズ … 312 KB / 上限 20 MB
  ✔ ファイル数 … 38 / 上限 500

  できました: upload/mitsumori-20260828-1642.zip
  ポータルの［新しい版を上げる］に、この zip を投げてください。

構文チェックをローカルでやるのがこのスキルの存在意義である。ビルドは Actions でしか回らないので、明らかな構文エラーを 2 分待ってから知るのは無駄が大きい。tsc は使えない（node_modules が無い）ので、Claude 自身に読ませて確認させるという素朴な方法を採る。完全ではないが、括弧の閉じ忘れレベルは拾える。

上げる

画面は「配信中（1/3 コミット済み）」のように進む。約 2 分で「試用環境に出ました」になる。失敗したら赤くなり、Actions のログの末尾 60 行がそのまま画面に出る。ここをコピーして /service-fix に貼るのが直しかたの導線。

10工程 5試用環境で確かめるつくる人

https://<slug>-stg.apps.synon.co.jp を開く。確かめることは 6 点（既存資料と同じ 6 点を使う）。

3 と 6 は必須。この 2 つが、この基盤で最も多い 2 種類の失敗をそれぞれ潰す。

11工程 6承認者：本番公開承認者

ポータルのアプリ詳細に、承認者にだけ［本番公開］ボタンが出る。押す前に見えるもの:

• 試用環境の URL（開いて触れる）
• 前回の本番版との差分（ファイル一覧と、選べば中身も）
• data/migrations/ の変更の有無（あれば黄色の警告）
• 「破壊的な変更（DROP TABLE / DROP COLUMN / DELETE FROM）を検出しました」の赤警告（あれば エンジニアの承認が必須に切り替わる）
• 前回の公開日時と公開者

［本番公開］を押すと、ポータルが GitHub の staging を main にマージする（merge API）。マージは GitHub App のトークンで行うため、main への push を待つ Actions が起動する（→ 20 章 落とし穴 3）。約 2 分で本番に出る。

12工程 7直す・戻す全員

13工程 8やめる管理者

使われなくなったアプリの畳みかた。「消す」を最後に置き、途中で止められるようにする。

14リポジトリとブランチ用意する人

アプリを 1 リポジトリ 1 本にするのは、権限とロールバックを単純にするためである。モノレポにすると「A さんの変更で B さんのアプリが落ちる」が起き、差分プレビューも複雑になる。

15★ データの外出し設計用意する人

「テンプレートではデータフォルダを外出しにして、配信先で初期作成される設計」を具体化する。この章がこの設計書で最も重要である。

「配信先で初期作成される」の実装

3 段階で作られる。すべて冪等（何回やっても同じ結果）にするのが設計条件。

-- テンプレートの data/migrations/0000_apphub.sql（保護パス。つくる人は触らない）
CREATE TABLE IF NOT EXISTS _apphub_seeds (
  file       TEXT PRIMARY KEY,
  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
);

つくる人に見せるルール（data/data.md の中身）

1. 表を作りたい／項目を足したいときは data/migrations/ に新しいファイルを足す。既にあるファイルは直さない
2. ファイル名は 0002_やること.sql のように 4 桁の番号 + 内容。番号は前より大きく
3. 表を消す・項目を消す SQL を書くと、公開のときにエンジニアの承認が要る（データが消えるため）
4. 初期データを入れたいときは data/seed/ に CSV を置く。初回の 1 回だけ入る
5. 実際の業務データはここには置かない。置いても配信先には反映されず、しかも社内の記録に残り続ける

本番と試用でデータを分ける

16保護パスと生成物用意する人

アップロードされた zip の中のファイルは、パスによって 3 通りに扱われる。

なぜ wrangler.jsonc を生成物にするのか

• リポジトリに wrangler.jsonc を置かない（.gitignore に入れる）
• Actions のビルド冒頭で scripts/gen-wrangler.mjs が app.config.json ＋ Actions の環境変数（資源 ID） から生成する
• 資源 ID は org secret ではなく リポジトリ変数（Actions variables） に入れる。秘密ではないが環境ごとに違うため

  app.config.json  ─┐
                    ├─→ scripts/gen-wrangler.mjs ─→ wrangler.jsonc ─→ wrangler deploy
  Actions variables ┘        （allowlist で検証）
   D1_ID / D1_ID_STG / R2_NAME / KV_ID / ACCESS_AUD …

生成に失敗したら配信は止まる。app.config.json に allowlist 外の値が書いてあったら、その場で落として理由を画面に出す。

保護パスの上書きはいつ起きるか

ポータルがコミットを組み立てるときに、毎回。zip の中身を無視して synon/apphub-template の現行 main の該当ファイルを読み、それをコミットに含める。

• テンプレートの取得は 5 分キャッシュ（KV）。全アプリで同じものを読むため
• テンプレートを直した直後に全アプリが壊れるリスクがあるので、apphub-template の main は必ず PR 経由・エンジニア 2 名承認にする

17app.config.json 仕様用意する人

つくる人（と Claude）が触れる唯一の設定ファイル。

{
  // 表示名。ポータルの一覧とアプリのタイトルに出る
  "name": "見積書つくるくん",

  // 使うもの。false にすると wrangler.jsonc から丸ごと消える
  "uses": {
    "d1": true,      // 表（データベース）
    "r2": true,      // ファイルの保管
    "kv": false,     // 早見表（キャッシュ）
    "ai": false      // Workers AI（従量課金なので既定 false）
  },

  // 定期実行。cron 式。最大 3 本
  "cron": ["0 0 * * *"],   // UTC 0:00 = 日本時間 9:00

  // 追加で使う npm パッケージ。allowlist 内のみ
  "packages": ["zod", "date-fns"],

  // 見せる範囲。Access のポリシーになる。ポータル側でも検証する
  "visibleTo": ["全社"],

  // 配信結果の通知先（Chatwork のルーム ID）
  "notify": { "chatwork": "123456789" },

  // アップロード可能なファイルの上限（R2 を使う場合）
  "upload": { "maxMb": 10, "allow": ["pdf", "png", "jpg", "xlsx", "csv"] }
}

packages の allowlist

初期の allowlist は次の 10 個だけにし、追加要望はエンジニアが 1 件ずつ判断する。

18ポータルのアーキテクチャ用意する人

なぜ Queue を挟むのか

zip 1 本のコミットは ファイル数前後の GitHub API 呼び出し（blob 作成 → tree → commit → ref 更新）になる。40 ファイルで 43 回。ネットワーク待ちが支配的で、リクエストの中で全部やると利用者を 20〜40 秒待たせる。

• API は R2 に置いて enqueue し、即座に 202 を返す
• コンシューマは max_batch_size: 1、max_retries: 3。冪等性は「同じ tree なら同じ commit になる」ことで担保（同一内容の再実行は空コミットになるのでスキップ）
• Queue は Workers Paid 前提の機能。Free では使えない（これも Paid が必須である理由の 1 つ）

19ポータルのデータモデル用意する人

-- アプリ台帳
CREATE TABLE apps (
  id            TEXT PRIMARY KEY,            -- ULID
  slug          TEXT NOT NULL UNIQUE,        -- mitsumori
  name          TEXT NOT NULL,
  status        TEXT NOT NULL,               -- provisioning|ready|failed|suspended|archived
  owner_email   TEXT NOT NULL,               -- つくる人
  approver_email TEXT NOT NULL,              -- 承認者
  repo_full     TEXT,                        -- synon/app-mitsumori
  repo_id       INTEGER,                     -- GitHub の数値 ID（org secret 付与に使う）
  uses_json     TEXT NOT NULL,
  visible_to    TEXT NOT NULL,
  cf_json       TEXT,                        -- 払い出した資源の ID
  prod_url      TEXT, stg_url TEXT,
  created_by    TEXT NOT NULL,
  created_at    TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
);

-- アップロードされた zip 1 回分
CREATE TABLE uploads (
  id          TEXT PRIMARY KEY,
  app_id      TEXT NOT NULL REFERENCES apps(id),
  uploader    TEXT NOT NULL,
  r2_key      TEXT NOT NULL,                 -- uploads/<app>/<id>.zip
  bytes       INTEGER NOT NULL,
  file_count  INTEGER NOT NULL,
  diff_json   TEXT NOT NULL,                 -- {added:[],changed:[],deleted:[]}
  verdict     TEXT NOT NULL,                 -- pending|ok|hold|accepted|rejected
  reject_reason TEXT,
  commit_sha  TEXT,
  created_at  TEXT NOT NULL DEFAULT (datetime('now'))
);

-- 配信 1 回分（staging も本番も）
CREATE TABLE deployments (
  id          TEXT PRIMARY KEY,
  app_id      TEXT NOT NULL REFERENCES apps(id),
  env         TEXT NOT NULL,                 -- staging|production
  commit_sha  TEXT NOT NULL,
  tree_sha    TEXT NOT NULL,                 -- ★ロールバック用
  run_id      INTEGER,
  status      TEXT NOT NULL,                 -- queued|building|success|failed
  log_tail    TEXT,                          -- 失敗時の末尾 60 行
  actor       TEXT NOT NULL,
  started_at  TEXT NOT NULL DEFAULT (datetime('now')),
  finished_at TEXT
);

-- 監査ログ（追記のみ・削除する API を作らない）
CREATE TABLE audit (
  id     INTEGER PRIMARY KEY AUTOINCREMENT,
  at     TEXT NOT NULL DEFAULT (datetime('now')),
  actor  TEXT NOT NULL,
  action TEXT NOT NULL,   -- app.create / upload / promote / rollback / suspend …
  app_id TEXT,
  detail TEXT
);

20GitHub 連携の設計用意する人

GitHub App の権限（過不足なく）

Webhook は workflow_run と push を購読し、/api/webhooks/github で受ける（署名検証必須）。

トークンの流れ

落とし穴 3 点（実装前に必ず読むこと）

全置換コミットの作り方

1. GET  /repos/{o}/{r}/git/ref/heads/staging          → 現在の commit sha
2. GET  /repos/{o}/{r}/git/commits/{sha}              → 現在の tree sha
3. GET  /repos/{o}/{r}/git/trees/{tree}?recursive=1   → 現在の全ファイル（差分表示用）
4. 採用するファイルごとに POST …/git/blobs           → blob sha（base64 で送る）
   ※ 中身が変わっていないファイルは 3 で得た blob sha を再利用し、POST しない
5. POST …/git/trees   base_tree を付けない ← ★全置換の要
      tree: [{path, mode:"100644", type:"blob", sha}, …]
6. POST …/git/commits  parents:[現在の sha]  tree:新 tree
7. PATCH …/git/refs/heads/staging   sha:新 commit  force:false

21CI/CD — deploy.yml の設計用意する人

  push (staging)   ──┐
  push (main)      ──┤
  workflow_dispatch──┴─→  1. 環境を決める（ref=main → production / それ以外 staging）
                          2. app.config.json を検査（allowlist）
                          3. package.json と wrangler.jsonc を生成
                          4. npm install
                          5. 構文チェック（tsc --noEmit）      ★
                          6. ビルド（vite build）
                          7. D1 migrations を適用               ★
                          8. seed を適用（未適用のものだけ）
                          9. wrangler deploy
                         10. 疎通確認（/healthz が 200 か）      ★
                         11. 結果をポータルに POST ＋ Chatwork

★ の 3 つがこの基盤の品質を決める

• 5（構文チェック） … 非エンジニアのコードは型が合わないことが日常。ここで落としてエラー本文をそのままポータルに返す。/service-fix が読むのはこの本文
• 7（migrations） … wrangler d1 migrations apply --remote。本番では 9 の前に必ず流す。逆順にすると「新しいコードが古い表を触る」瞬間ができる
• 10（疎通確認） … デプロイが成功しても起動時に落ちるケースがある。/healthz を叩いて 200 でなければ 失敗として扱い、直前の版に自動で戻す

失敗したときの扱い

secrets と variables の置き場

アプリ固有の秘密をつくる人に扱わせないのは原則 2 のとおり。「Chatwork に通知したい」のような要望は、テンプレート側に共通の通知関数を用意して、鍵はプラットフォーム側が持つ形にする。

22資源の自動払い出しと認証用意する人

払い出す API（すべて CF_API_TOKEN で。ポータルから叩く）

認証は 3 層

app.config.json の visibleTo と Access ポリシーは、ポータルが同期する。つくる人が visibleTo を変えて zip を上げたら、ポータルはその場では反映せず、承認者に確認を出す。「見せる範囲を広げる」は本番公開と同じ重さの操作である。

23zip 受け入れ検査仕様用意する人

アップロードから差分プレビューまでのあいだに、次の検査を順に通す。1 つでも落ちたら受け付けない。

入口（同期・Worker 内）

中身（Queue コンシューマ内）

24命名規約と上限管理者

命名（slug から機械的に決まる。例外を作らない）

slug の規則: 半角小文字英数とハイフン、3〜20 文字、数字始まり不可、予約語（api admin www apps portal new stg）不可。

上限（ポータルが強制する）

25費用決める人

Workers Paid が必須である理由（Free では成立しない）

増えるとしたらどこか

• R2 の保管量。ファイル添付を多用するアプリが数本できると 10 GB を超える。$0.015/GB・月なので 100 GB でも $1.5。驚くほどではない
• Workers AI。ai を true にしたアプリが増えると従量課金になる。既定 false、有効化は管理者承認にしてある
• GitHub Actions の実行時間。プライベートリポジトリは Team で 3,000 分／月。1 回の配信が約 90 秒なので 月 2,000 回まで。実際には 100 回前後

26失敗モードと復旧管理者

想定される失敗を、起きる頻度の高い順に並べた。1 週目に必ず出るものから書いてある。

復旧手段の一覧（どこに何が残っているか）

27実装の進め方（フェーズ 0〜4）用意する人

フェーズ 0 — 前提の実測（半日〜1 日）

• Static Assets を使う Worker に Cf-Access-Jwt-Assertion ヘッダが付くか（→ 28 章 未確認 1）
• GitHub App の installation token で POST /orgs/synon/repos が通るか
• 同トークンで .github/workflows/deploy.yml を含むコミットが push できるか（Workflows 権限）
• その push で Actions が起動するか
• PUT /orgs/synon/actions/secrets/CF_API_TOKEN/repositories/{id} が通るか
• Custom Domain の作成が、Worker が存在する状態で通るか
• Access アプリの API 作成が通り、作った直後にログインを要求するか

フェーズ 1 — 手動で 1 本通す（2 日）

ポータルを作らない。エンジニアが手で全部やる。

• テンプレートリポジトリ apphub-template を cf-internal-app-starter から作る（data/ の外出しと wrangler.jsonc 生成を入れる）
• app-sample を手で作り、手で資源を払い出し、手でコミットし、deploy.yml を通す
• 試用と本番の 2 環境が実際に動くところまで

ここで deploy.yml が完成する。これがフェーズ 1 の成果物。ポータルは deploy.yml を起動するだけの存在なので、先にこちらを固める。

フェーズ 2 — ポータルの読み取りだけ（3 日）

• Access の後ろで動く Worker、D1 のスキーマ、アプリ一覧・詳細・配信履歴の表示
• 書き込み API はまだ作らない。apps テーブルは手で入れる

フェーズ 3 — 配信の自動化（5 日）

• GitHub App 連携（トークン取得・全置換コミット・dispatch）
• zip アップロード → 検査 → 差分プレビュー → Queue → コミット
• webhook で結果を受けて画面に出す ／ /service-pack スキル

フェーズ 4 — 枠の自動作成と本番公開（4 日）

• 新規作成（資源の払い出し・初回コミット・ドメイン・Access）
• 本番公開ボタン・ロールバック・監査ログの画面

展開の順序

28未確認事項と撤退基準全員

実機で潰すこと（フェーズ 0 で）

撤退基準（先に決めておく）

3 方式 ＋ 本方式の使い分け（既存資料との接続）

既存資料の判定 5 問はそのまま使える。アプリハブはプラン B の置き換えなので、「プラン B」と書いてあるところを読み替える。

A付録 — 実装一式（synon-apphub-kit.zip）の中身用意する人

synon-apphub-kit/
├── README.md                       全体の説明と読む順番
├── APPLY.md                        ★導入手順（この順にやれば動く）
├── portal/                         ポータル本体
│   ├── package.json  wrangler.jsonc  tsconfig.json
│   ├── schema/0001_init.sql        19 章の DDL
│   ├── src/index.ts                ルーティング
│   ├── src/types.ts
│   ├── src/lib/access.ts           Cf-Access-Jwt-Assertion の検証
│   ├── src/lib/github.ts           ★App JWT / installation token / 全置換コミット
│   ├── src/lib/cf.ts               D1・R2・KV・Custom Domain・Access の払い出し
│   ├── src/lib/zip.ts              ★展開と 22 項目の検査
│   ├── src/lib/util.ts             ULID・監査ログ・Chatwork・HMAC
│   ├── src/routes/apps.ts          一覧・作成・詳細・ダウンロード
│   ├── src/routes/uploads.ts       アップロード・差分・確定
│   ├── src/routes/deploy.ts        本番公開・ロールバック
│   ├── src/routes/webhooks.ts      Actions からの結果受け
│   ├── src/queue/consumer.ts       ★重い処理の本体
│   └── public/index.html           管理画面（単一 HTML）
├── template/                       テンプレートに足す差分
│   ├── app.config.json  allowlist.json  PROJECT.md
│   ├── data/data.md                つくる人向けの説明
│   ├── data/migrations/0000_apphub.sql
│   ├── scripts/gen-wrangler.mjs    ★app.config.json → wrangler.jsonc
│   ├── scripts/apply-seed.mjs      初期データを 1 回だけ入れる
│   ├── scripts/report.mjs          配信結果をポータルに返す
│   └── .github/workflows/deploy.yml
├── skills/                         Cowork のスキル 4 本
│   ├── service-spec/SKILL.md   service-build/SKILL.md
│   └── service-pack/SKILL.md   service-fix/SKILL.md
└── docs/OPERATIONS.md              運用手順（枠の撤去・秘密の登録・棚卸し）

B付録 — 一次情報と社内の関連資料全員

一次情報

• Cloudflare Workers — Limits（リクエストボディ上限はゾーンプラン依存 Free/Pro 100 MB、CPU 時間、サブリクエスト数）
• Cloudflare D1 — Limits（Free 10 個 / Paid 50,000 個、容量 500 MB / 10 GB、クエリ数 50 / 1000）
• Cloudflare Access for Workers（Worker 単位・アカウント単位、Static Assets 併用時に ctx.access が渡らない）
• Cloudflare Changelog — You can now enable Access on a Worker or all Workers at once（2026-08-14）
• GitHub Docs — GITHUB_TOKEN（GITHUB_TOKEN による push は次のワークフローを起動しない／App トークンを使え）
• GitHub Community Discussion #52316（installation token でのテンプレート生成が「Resource not accessible by integration」になる報告）
• GitHub Docs — Generating an installation access token for a GitHub App

社内の関連資料

同じフォルダ /Users/synon/Documents/Synon/プロジェクト/CloudFlare/：