Platform City

City Guide / 使い方

Issue から建物を育てる

最初の建物は 最初の建物を建てる の手順で、Issue を使わずに建てます。この章は、その後の変更の進め方です。

建物は一度建てたら終わりではありません。機能を足したいとき、見た目を変えたいとき、不具合を直したいとき、やりたいことをエージェントに伝えます。エージェントはそれを GitLab の Issue に起票し、実装、MR の作成、AI レビュー、マージ、デプロイまでを進めます。あなたが確認するのは、起票前の Issue の下書き 1 回だけです。

スコアや投稿など、再デプロイ後も残したいデータには DynamoDB を使えます。テナント専用のテーブルと接続用の認証が自動で用意されます。保存機能を作るときは、エージェントに DynamoDB にデータを保存する を読ませてください。

開発の単位は Issue

Platform City での開発は、GitLab プロジェクトの Issue を 1 つの単位として進めます。Issue は次の 3 点で構成します。

  • お題: 何を実装したいのか。1 つの Issue に 1 つの変更
  • 完了条件: 何ができれば終わりか。「トップページに自己紹介の写真が表示される」のように、公開 URL を開いて確認できる形で書く
  • 制約: 変えてはいけないもの、守ってほしいもの。「ポート 8080 と /healthz はそのまま」など

この形に整えるのはエージェントの仕事です。あなたは「何をしたいか」を伝えるだけで構いません。エージェントは伝えられた内容を上の 3 点に下書きし、あなたに見せてから起票します。

自分で Issue を書きたい場合は、GitLab のプロジェクトで Issue を作るときにテンプレート feature を選ぶと同じ形になります。その場合は Issue の番号をエージェントに伝えてください。

エージェントに任せる

プロジェクトの作業フォルダで、エージェントにやりたいことを伝えます。

Platform City の taro-yamada の my-game に、トップページで自己紹介の写真を出す機能を足したい。Issue にしてから実装して

Issue を自分で書いた場合は、番号を指定します。

Platform City の taro-yamada の my-game の Issue #3 を実装して

エージェントは、プロジェクトに同梱された AGENTS.md の手順に沿って次の流れで進めます。

  1. Issue がまだ無ければ、伝えられた内容をお題・完了条件・制約の形に下書きし、あなたに見せます。内容を確認して OK を出すと Issue が起票され、番号が伝えられます。直したい点があればここで伝えてください。あなたが確認するのはこの 1 回だけで、以降に承認を待つ工程はありません
  2. Issue を読み、お題と完了条件を把握します
  3. トピックブランチを作成し、コードを変更します。ローカルで起動し、ポート 8080 で /healthz が 200 OK を返すことを確認します
  4. MR を作成します。説明に Closes #3 と書いておくと、マージ時に Issue が自動で閉じます
  5. AI レビューを受け、指摘があれば修正し、ディスカッションスレッドを解決します
  6. MR をマージします
  7. main ブランチのパイプラインが lint、test、build、image push、deploy を順に実行します
  8. status ツールで配備の結果を確認します

途中でエラーが起きた場合も、返ってくる情報は機械可読で、次に取るべきアクションが付いています。エージェントにそのまま渡してください（壊れたときの直し方 を参照）。

AI レビュー

MR を作成するとき、Reviewer に @GitLabDuo を指定すると GitLab Duo がコードをレビューします。

  • 自己紹介アプリ（onboard で作られたもの）では、AI レビューを一度通過することがマージの条件です。パイプラインの verify-ai-review ジョブが「レビュー済みかどうか」を検証します。手順の詳細は 最初の建物を建てる を参照してください
  • それ以外のテーマ（game、oshi、food、api、meet）では、AI レビューは任意です。指定しなくてもマージできますが、Reviewer に @GitLabDuo を付ければ同じようにレビューを受けられます。付けておくことをおすすめします
glab mr create --fill --reviewer GitLabDuo

AI レビューの指摘をどこまで反映するかは、参加者とエージェントの判断に委ねられています。レビューの内容によってデプロイの合否が決まることはありません。

マージは誰がしてもよい

main ブランチへの直接 push はできませんが、MR のマージはプロジェクトのメンバーであるあなた自身の権限で行えます。あなたがマージしても、エージェントがあなたの認証でマージしても構いません。ブラウザを開く必要はありません。

ルールは 1 つだけです。未解決のディスカッションスレッドが残っている MR はマージできません。AI レビューの指摘に対応したら、スレッドを解決（resolve）してからマージしてください。

glab mr merge <iid>

建物が育つのを確認する

マージ後、main のパイプラインが新しいコンテナイメージを配備している間、Map 上の建物の周囲には足場が組まれます。アプリケーションが正常に応答を返すと足場が外れ、窓に灯りがともります。

Platform City の taro-yamada の my-game の status を見て

status ツールでは、直近のデプロイの進行状況、配備されたイメージ、開始・完了時刻が確認できます。建物から煙が上がった場合は 壊れたときの直し方 を参照してください。

推しアプリの実装では 推しを応援する、グルメ掲示板のアプリでは グルメ掲示板に店を載せる など、区画ごとのページにそれぞれの要件がまとまっています。エージェントに伝える前に一度目を通しておくと、完了条件を区画の要件に合わせて確認できます。

建物カードにアプリを紹介する

アプリの公開 URL 配下で platform-city.json を返すと、建物カードに概要文と画像を載せられます。

{
  "version": 1,
  "displayName": "会場周辺ランチ案内",
  "description": "会場周辺のランチを予算と徒歩時間で探せるアプリです。",
  "image": "assets/preview.webp"
}

displayName はMapなど、最新の建物情報を使う画面に出る1〜120文字の表示名です。省略すると create_app 時の表示名を使います。この値と通常のコードをマージ・デプロイすると、数分後にCityMapの表示が変わります。app ID、公開URL、いいねとアプリのデータは保持されます。

概要文は300文字以内のプレーンテキストです。画像は任意で、アプリから配信する相対パスか公開 HTTPS URL を指定します。PNG・JPEG・WebP を使い、画像は512 KiB以内にします。相対パスはアプリの公開 URL を基準にします。image が未設定なら、入口ページの HTML にある og:image を使います。画像が無ければ通常のカードを表示します。画像は、Mapで区画を見渡す程度にズームすると屋上看板にも表示されます。看板は他の建物が見える大きさに抑え、密集している場所では枚数を減らします。建設中・障害中、自動ツアー中や建物カードを開いているときは、その建物の看板を隠します。看板用の追加設定は不要です。

JavaScript が後から追加する OGP は取得されません。ファイルを変更して通常の CI でデプロイすれば、数分後に反映されます。

https://citymap.core.paas.jp/api/v1/presentation?buildingId=<tenant>/<app> で取得状態と修正方法を確認できます。グルメ情報は同じ文書の food に記述します。グルメ掲示板に店を載せる を参照してください。

アプリを削除する

不要になったアプリはエージェントに delete_app を依頼して削除できます（例:「my-game を削除して」）。エージェントが削除の意思を確認したうえで実行します。

削除すると建物が Map から消え、稼働中のリソースと公開 URL は自動で回収されます。GitLab プロジェクトは削除予約され、約30日後に完全削除されます。

注意点:

  • 元に戻せません。コードもいいねの対象（建物）も消えます
  • 同じ名前でのアプリ再作成は約30日間できません（GitLab の遅延削除とパスが衝突するため）。作り直す場合は別の名前を使ってください
  • 1棟目（self-intro）は削除できません。内容を変えたい場合はリポジトリを編集して再デプロイしてください
  • 自由区画（general）で自分が k8s/ に書いた追加リソースは自動回収されません。残したくない場合は削除前に k8s/ から消して main にマージしてください