# Appbase

> AppBase のアプリを作りたい・直したい・画面やデータを足したい・ステージングに出したい・本番に出したい・元に戻したい・公開したい・デプロイしたい・AppBase のクラウドに載せたい、と言われたとき、または AppSpec（spec/app.yaml・entities・commands）、@appbase/sdk、AppBase へのログインや初期セットアップが話題に上がったときに呼ぶ。AppBase 仕様のアプリをひな形から作り、クラウドの公開 API で検査・ステージング・本番・戻すまで行う。手元にエンジンや Mac アプリは要らない。

- Skill: `ymasaki/appbase` (Agent Skill, multi-file: 22 files)
- Install (CLI): `npx get-skill add ymasaki/appbase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ymasaki/appbase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ymasaki (https://skillmd.com/u/ymasaki)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/ymasaki/appbase

---


# AppBase アプリの開発と公開

AppBase のアプリは **宣言（AppSpec）＋ React の画面** だけでできている。サーバーコード・SQL・独自 API は書けない。
データの保存、権限、状態の変更、ログイン、ステージングと本番の分離は AppBase のクラウドが受け持つ。

| 部品 | 中身 |
|---|---|
| `spec/app.yaml` | アプリ ID・表示名・役割（roles） |
| `spec/entities/<id>.yaml` | データの型 1 つ（項目・状態・権限）。1 ファイル 1 つ |
| `spec/commands/<id>.yaml` | 業務操作 1 つ（申請・承認など。状態を変える唯一の方法）。1 ファイル 1 つ |
| `ui/src/`、`ui/public/` | React + TypeScript の画面。通信は `@appbase/sdk` だけ |

このスキルのフォルダ（この `SKILL.md` があるフォルダ）を `<skill>` と書く。コマンドはすべて次の形で呼ぶ:

```sh
node "<skill>/scripts/appbase.mjs" <コマンド> ...
```

公開はクラウドの公開 API（`https://www.<domain>/_deploy/v1/`、仕様は [api.md](references/api.md)）を通る。
このスクリプトがその呼び出し役なので、API を直接呼ぶスクリプトを新しく書く必要はない（書く場合も api.md に従う）。

## 0. 最初に状態を確かめる

```sh
node --version                                   # 20 以上
node "<skill>/scripts/appbase.mjs" whoami          # ログイン済みか、どの会社のどのサービスか
node "<skill>/scripts/appbase.mjs" apps            # 使えるアプリ ID
```

| 結果 | 次にやること |
|---|---|
| `node` がない・20 未満 | [setup.md](references/setup.md) の「道具」 |
| `ログインしていません` / `期限切れ` | **§1 ログイン**。AppBase のアカウントがまだない人は [setup.md](references/setup.md) |
| `使えるアプリ ID はありません` | 運用者にアプリ ID の登録を依頼してもらう（[setup.md](references/setup.md) の 3） |
| アプリのフォルダ（`spec/app.yaml` がある）がまだない | **§2 新しく作る** |
| アプリのフォルダがある | **§3 作る・直す**、公開を頼まれたら **§4** |

## 1. ログイン（端末をブラウザで承認する）

トークンは利用者がブラウザで承認したときにだけ、この端末に発行される。**トークン・パスワード・鍵を利用者に聞かない。会話に貼ってもらわない。**

```sh
node "<skill>/scripts/appbase.mjs" login-start https://www.<domain>   # 承認用のアドレスと照合コードを表示する
node "<skill>/scripts/appbase.mjs" login-wait                         # 承認されるまで待つ（最大 10 分）
```

1. `login-start` が表示したアドレスと照合コードを、そのまま利用者に伝える。
   「このアドレスを開いて AppBase にログインし、照合コードが同じことを確かめて『承認する』を押してください」。
2. 続けて `login-wait` を実行する（最大 10 分待つので、コマンドの時間制限を 11 分以上にするか、裏で実行して終わりを待つ）。
3. `<domain>` がわからなければ利用者に聞く（会社ごとに違う。例: 管理画面のアドレスが `https://www.example.appbase.work` なら、それがそのまま入る）。

- 資格情報は `~/.config/appbase/credentials.json`（本人だけが読める権限）に保存される。**このファイルを読んだり表示したりしない。**
- ログインは 7 日で切れる。端末を手放すときは `logout`。管理画面の「アカウント設定」→「端末のログイン」で一覧・取り消しができる。

## 2. 新しく作る

作り始める前に、利用者へ次を短く聞く（2〜3 問まで。専門用語は使わない）。

1. 何をするアプリか、誰が使うか（役割は何種類か。例: 申請する人と承認する人）
2. 使うアプリ ID（`apps` に出ている、運用者が登録した ID から選ぶ。後から変えられない）

```sh
node "<skill>/scripts/appbase.mjs" new <作る場所>/<フォルダ名> --id <アプリID> --name "<表示名>"
```

- ひな形・SDK（`ui/vendor/appbase-sdk`）・`npm install`・git の最初のコミットまで行われる。
- できたフォルダの `AGENTS.md`（`CLAUDE.md` から読まれる）に、アプリの中で守る規則と AppSpec の全仕様がある。以後の作業はそのフォルダで行う。
  その中の「最後のメッセージ」「```question ブロック」の書式は Mac アプリの AI 向けなので、Claude Code / Codex では普段どおり会話でよい。

## 3. 作る・直す

**必ず [develop.md](references/develop.md) を読んでから** spec と画面を書く。要点:

- 変更してよいのは `spec/` と `ui/src/`、`ui/public/` だけ。npm の依存の追加、`ui/package.json`・`ui/build.mjs`・`ui/vendor/` の変更はしない。
- 状態の変更（申請・承認など）は commands で宣言する。権限は spec に書き、画面でボタンを隠すことを権限の代わりにしない。
- 値の入った項目の ID を変えたり消したり型を変えたりしない（公開時に拒否される）。追加は安全。
- ユーザーのデータは React のテキストとして表示する。`innerHTML`・`dangerouslySetInnerHTML`・外部スクリプト・外部への `fetch` は使えない。
- 外部連携（`integrations`）・コネクタ（`connectors`）はクラウドでは動かない。使わない。
- 画面の文言は平易な日本語。

仕上げに毎回:

```sh
node "<skill>/scripts/appbase.mjs" check <アプリのフォルダ>   # クラウドで spec を検査 → 型チェック → ビルド（ui/dist）
```

エラーがなくなるまで直してから git にコミットする。

## 4. 公開する（ステージング → 本番 → 戻す）

[deploy.md](references/deploy.md) の手順で行う。要点:

```sh
node "<skill>/scripts/appbase.mjs" stage <アプリのフォルダ> --notes "<利用者向けの変更の説明>"   # 検査・ビルド・アップロード・ステージングへ公開
node "<skill>/scripts/appbase.mjs" status <アプリID>                                            # 各環境の版、止まっている操作
node "<skill>/scripts/appbase.mjs" promote <アプリID> --confirm-production                      # ステージングと同じビルドを本番へ（利用者に確かめてから）
node "<skill>/scripts/appbase.mjs" rollback <アプリID> --env prod --confirm-production          # 本番を一つ前の版へ（データは戻らない）
```

- 最初に `stage` した人がそのアプリのオーナーになる。以後はオーナーだけが公開できる。
- **`--confirm-production` は、利用者が本番に出す・戻すことをこの会話で明確に頼んだときだけ付ける。** 推測で付けない。
- 公開の結果がわからなかった（時間切れ・通信の失敗）ときは、同じ `stage` を繰り返さない。スクリプトが状態を表示するので、
  止まっている操作があれば利用者に確かめて `resume <操作ID> --app <アプリID>` か `cancel <操作ID> --app <アプリID>` を選ぶ（本番の操作は `--confirm-production`）。

## 5. 困ったとき

[troubleshoot.md](references/troubleshoot.md) を見る。アカウントや登録の準備は [setup.md](references/setup.md)。

## やってはいけないこと

- API キー・パスワード・トークンを聞き出す、会話に貼ってもらう、コード・spec・設定値に書く、資格情報のファイルを読む・表示する。
- 公開前の検査（`check`）を飛ばしてステージングに出す。
- 利用者に確かめずに本番へ出す（promote）・戻す（rollback）・本番の操作を再開／取り消す。
- 失敗した公開を、状態を確かめずに同じコマンドで何度も繰り返す。
- 他人のアプリを公開しようとする、運用者の権限や AWS の認証情報を求める。
- `ui/vendor/appbase-sdk` やスクリプトを書き換えて制限を回避する。足りない機能は「AppBase にまだない」と伝える。

## 利用者への最後の案内（例）

```
ステージングに出しました（版 3）。
  ステージング: https://staging.<app-host>.<domain>/
  管理画面（データ・設定値・共有）: https://www.<domain>/login

確かめて問題なければ「本番に出して」と言ってください。同じものを本番に出します。
うまくいかなければ一つ前の版に戻せます（データは戻りません）。
```

`<app-host>` はアプリ ID の `_` を `-` にしたもの。アプリを開くには、管理画面にログインしてからアプリを開く。

