AI coding agent と dev server を共有するなら、「誰が止めるか」まで決める

frontend の修正は終わっているのに、localhost:4321 が残っている。次の task を始めた agent は別の port で dev server を起動し、なぜか古い画面を見ている。

地味ですが、AI coding agent に browser 確認まで任せると起きやすい事故です。

pnpm dev 自体は悪くありません。dev server の持ち主が決まっていないのがまずい。誰が起動したか、既存 process を再利用してよいか、どの時点で ready とみなすか、最後に誰が止めるか。この4点が曖昧なまま、long-running process だけが増えていきます。

Astro 7 と 7.1 の dev server 機能を見ると、この問題をかなり具体的に分解できます。command は Astro 固有ですが、そこから自分の repo に必要な lifecycle を拾っていきます。

start の前に status が要る

agent への指示を pnpm dev から始めると、毎回新しい process を作ろうとします。先に確認するべきなのは、すでに使える instance があるかです。

Astro 7 は project ごとの lockfile を使います。二度目の起動要求が来ても重複 process を増やさず、既存 instance の情報を返します。background mode では server が request を受けられる状態まで待ち、URL と PID を返してから detach します。

必要な lifecycle はこれです。

status
  -> start または reuse
  -> ready check
  -> logs
  -> stop
  -> status

起動 banner が terminal に出ただけでは ready と判定しません。Astro 7 なら /_astro/status を確認できます。別 shell から astro dev status、astro dev logs、astro dev stop も使えます。

framework が違っても、埋める欄は同じです。

• 起動済みか確認する方法
• request を受けられると判断する方法
• log を読む方法
• process を安全に止める方法

この4つのうち一つでも空欄なら、agent に server 管理を丸投げするには早いと思います。

repo に ownership contract を置く

自分なら、まず dev-server-contract.yaml を repo に置きます。公式 schema ではありませんし、標準化するつもりもありません。agent と reviewer が同じ前提を読むためのメモです。

dev_server:
  owner: coding-agent
  start: pnpm dev
  expected_url: http://localhost:4321
  ready_check: http://localhost:4321/_astro/status
  reuse_existing: true
  logs: astro dev logs
  stop: astro dev stop
  cleanup_required: true

owner は、いま動いている process を誰が管理するかを示します。cleanup_required は、task が終わった時に終了確認まで行うという意味です。

stop command の横には、止めてよい process の範囲も書きます。agent が起動前から動いていた server は、人間や別 task が使っているかもしれません。PID が見えたからといって勝手に kill しない。自分で起動した instance だけを片付ける。この線引きも contract に含めます。

たとえば既存 server を人間が管理しているなら、次のように変えられます。

dev_server:
  owner: human
  expected_url: http://localhost:4321
  reuse_existing: true
  allow_agent_start: false
  cleanup_required: false

これなら agent が疎通に失敗した時も、空いている port を探して別 instance を増やすのではなく、blocker として報告できます。

server log と browser error は別々に見る

dev server が正常でも、UI は壊れます。

Astro 7 の agent 向け background mode は JSON logging を有効にし、process の状態を machine-readable にします。一方、Vite 8 の server.forwardConsole は browser console の log と error を dev server terminal 側へ送ります。coding agent を検出した場合は自動で有効になります。

この二つは見ている場所が違います。

checks:
  server:
    - process_is_alive
    - ready_endpoint_returns_success
    - server_log_has_no_fatal_error
  browser:
    - target_page_loaded
    - primary_flow_completed
    - console_error_count_is_0

terminal に error がないから UI も正常、とは言えません。逆に browser console の転送だけで E2E test を置き換えることもできません。ready、server log、browser runtime、実際の操作を別の assertion にしておくと、「起動しました」と「動きました」を混ぜずに済みます。

--ignore-lock は通常運用に混ぜない

Astro 7.1 には astro dev --ignore-lock が追加されました。人間が意図的に二つ目の instance を起動したい時の escape hatch です。

注意点があります。--ignore-lock で起動した instance は独立していて、astro dev stop、status、logs の管理対象になりません。

比較用に二つ目を立てるなら、port と終了担当を別に記録します。

temporary_server:
  reason: verbose logging comparison
  command: astro dev --ignore-lock --port 4322
  expected_url: http://localhost:4322
  owner: human
  cleanup: manual

--ignore-lock を普段の起動 command にしてしまうと、せっかくの lock と lifecycle command を自分から外すことになります。使う理由を説明できないなら使わない。それくらいでよさそうです。

agent への依頼文も lifecycle 順にする

contract を置いても、依頼が「dev server を起動して確認して」だけでは足りません。実行順と最後に返してほしい state を書きます。

既存 dev server の status を最初に確認する。
再利用できる場合は新しく起動しない。

自分で起動した場合:
- URL と PID を作業記録へ残す
- ready check が通るまで待つ
- server log と browser console error を確認する
- task 終了後に自分で起動した server だけを停止する

最後に status を再実行し、残っている process と owner を報告する。
人間が起動した process は停止しない。

返却フォーマットも決めておくと review が楽です。

## Dev server result

- action: reused | started | blocked
- URL: http://localhost:4321
- PID: 12345
- ready: pass
- server errors: 0
- browser console errors: 0
- cleanup: stopped | left running
- remaining owner: none | human | coding-agent

「確認済み」という一行より、どの instance を見て、最後に何が残ったかの方が役に立ちます。

まず同じ task を2回実行してみる

contract が機能するかは、小さく確認できます。

1. dev-server-contract.yaml を一つの repo に置く
2. agent に画面修正と browser 確認を依頼する
3. 同じ依頼をもう一度実行する
4. 二度目が既存 instance を再利用したか確認する
5. cleanup 後に status と port を確認する

見たいのは一度目より二度目です。古い process を踏まず、同じ port を奪い合わず、終了後の state を説明できるところまで確認します。

AI coding agent へ起動 command を教えるのは簡単です。実際に困るのは、その process が次の task まで残った時です。

dev server を agent と共有するなら、start と同じ場所に status、ready、logs、stop を書く。そして「誰が止めるか」を決める。自動化の範囲を増やす前に、まずここを固定します。

Source notes

• Astro: Astro 7.1
• Astro: Astro 7
• Vite: Announcing Vite 8