PSYCHO-Py800MCP: Instructions file for Codex

AGENTS.md — PSYCHO-Py800MCP エージェント開発指示書

このファイルはAIエージェント（Claude Code等）が本プロジェクトを操作する際の 作法・制約・文脈を定義する。人間が読む設計書は /docs/ を参照。

---

プロジェクト文脈

PSYCHO-Py800MCPはオシロスコープ・ロジアナ・WebCam・顕微鏡をMCPで統合し、
AIがスケマティックベースで波形を読む、Mac/Win常駐Pythonアプリ。

開発者（齋藤みつる）はZeroRoomLab（山形県高畠町）を拠点とする
コンテンツクリエイター・エンジニア・独立研究者。
実機（SIGLENT SDS1204X-E・Hackintosh）で実際に使うことを前提とした現場駆動開発。

停滞・放置期間が発生することも前提とする。
エージェントはこれを「プロジェクト停止」と判断せず、再開時に /notes/ を確認してから状況を再確認すること。

---

責任の境界（最重要）

Claude/エージェント → 指揮・提案・コード生成のみ
エッジ端末         → SCPIコマンド実行（ここに責任が宿る）
人間（執行官）     → プローブを当てる・Startを押す

エージェントはSCPIコマンドを人間の確認なしに自動実行するコードを書かない。 すべての実機通信は、対象機器、許可操作、上限、TTL、解除条件を持つApprovalSessionの内側で行う。 Phase 0では実験ゲートを閉じ、実機通信を実装・実行しない。query-only実験も別の明示承認後に開始する。

---

アーキテクチャ概要

src/gui/      - PyQt6常駐アプリ（メニューバー/タスクトレイ）
src/psycho_py800mcp/*_mcp_server.py - FastMCPサーバー（公式`mcp` packageとの名前衝突を避ける）
src/engine/   - ゲシュタルト係数エンジン
src/audio/    - eSpeak NG音声統合
src/evidence/ - 証拠保全（SQLite + HDF5）
docs/         - 仕様書（変更時は必ず更新）
notes/        - 実験ノート・作業ログ（セッション終了時に追記）

詳細は docs/interface_spec.md を参照。

---

コーディング規約

言語・ライブラリ

• Python 3.11+
• GUI: PyQt6（システムトレイ・メインウィンドウ）
• MCPサーバー: fastmcp
• SCPI通信: pyvisa or socket直接（pyvisa-py使用、NI-VISA不要）
• 波形処理: numpy / scipy
• 波形保存: h5py（HDF5）
• 証拠ログ: sqlite3（標準ライブラリ）
• 音声: espeak-ng（CLIラップ or py-espeak-ng）
• スケマティック: kicad-python or skidl

命名規則

# クラス: PascalCase
class GestaltEngine:

# 関数・変数: snake_case
def calculate_coefficient(net_name: str) -> int:

# 定数: UPPER_SNAKE_CASE
MAX_COEFFICIENT = 500
TRIGGER_THRESHOLD = 300

# MCP ツール名: snake_case（動詞_名詞）
def get_waveform_summary(channel: int, duration: float):
def set_trigger(mode: str, level: float):

エラーハンドリング

# ハードウェア応答なし → 必ず明示的に返す
# 「ハードあかん」以上の情報をClaude側に送らない（見えないものは見えない）
return {"status": "error", "message": "device_not_responding", "detail": str(e)}

---

ゲシュタルト係数エンジン

src/engine/gestalt.py に実装。

COEFFICIENT_WEIGHTS = {
    "voltage_unknown":      40,
    "gnd_not_isolated":     80,
    "voltage_over_50v":    100,
    "confidence_low":       60,   # confidence < 0.5
    "adjacent_net_risk":    30,
    "protocol_unanalyzed":  20,
}

THRESHOLDS = {
    "normal":       (0,   100),   # 通常プローブ
    "recommend":  (100,   300),   # 差動プローブ推奨
    "required":   (300,   400),   # 差動プローブ必須＋高圧モード
    "critical":   (400,   500),   # 2名体制・監視官承認必須
}