PlatformIO環境でエージェント開発を快適にするためのAGENTS.md

概要

PlatformIOプロジェクトをAIエージェント（Codex, Claude code)と連携して開発する際、環境構築やビルド手順、USB権限などで失敗しやすいポイントがあります。
その対策として、プロジェクトルートにAGENTS.mdを置いておくと便利です。
要点は以下のとおりです。

• penv は PlatformIO の Python 仮想環境。AIエージェント経由でも必ず有効化してからビルドする。
• USB 書き込みには昇格権限が必要。with_escalated_permissions を明示することで安全に許可できる。
• シリアルモニタは pyserial 経由の方が安定して動作する。

サンプル

以下はCodex向けのサンプルです。

AGENTS.md

# 概要

PlatformIO開発環境

# 書き込み手順

1. `source ~/.platformio/penv/bin/activate`
2. `PLATFORMIO_CORE_DIR=.pio pio run`
3. `source ~/.platformio/penv/bin/activate && PLATFORMIO_CORE_DIR=.pio pio run -t upload`  
   ※ `shell` ツール実行時は `with_escalated_permissions: true` と  
   `justification: "Firmware upload requires unrestricted USB device access beyond sandbox permissions."` を必ず指定する。

# シリアルモニタの確認方法

- PlatformIO のシリアルモニタはターミナル環境によって ioctl エラーになる場合があるため、代わりに PlatformIO 仮想環境に入って Python の `pyserial` を使用する。
- 実行例:
  ```
  source ~/.platformio/penv/bin/activate
  python - <<'PY'
  import serial
  import time
  port = '/dev/ttyACM0'
  baud = 115200
  with serial.Serial(port, baud, timeout=0.5) as ser:
      start = time.time()
      while time.time() - start < 5:
          raw = ser.readline()
          if raw:
              print(raw.decode('utf-8', errors='replace').strip())
  PY
  ```
- `port` は `pio device list` で接続先デバイス（例: `/dev/ttyACM0`）を確認してから指定する。

# エージェント指針

- コード修正を行った場合は、上記手順に従いビルドと書き込みまで必ず完遂し、その結果を報告する。
- 書き込み後はユーザーへリセット操作と動作確認の案内を行う。

# 注意

- `sudo` 実行はパスワード入力ができないため失敗する。必ず `with_escalated_permissions` を使うか、udev で一般ユーザーに権限を与える。