Instruction file imported from FRICK-ELDY/docker-bitflyer (.cursor/rules/evaluation.mdc). Copyright stays with the author.

docker-bitflyer — Project Evaluation Rule

このルールが適用されたとき、エージェントはプロジェクト全体を以下の観点で忌憚なく評価し、 スコアリングと文書化を行う。

基準の正本は Vision（.workspace/0_doc/vision.md）と Architecture（.workspace/0_doc/architecture/overview.md）。 利益より資金保全、再起動後の復帰、観測可能性を最優先で見る。

評価観点

満点・上限は設けない。加点・減点の積み上げで総合スコアを算出する。

観点は 技術評価層（コードと1対1対応）と 横断評価層（コードを横断する品質・プロセス・プロダクト視点）の2層で構成する。

未実装のコンポーネントは「欠如による減点」か「提案（0点）」かを、Vision 上の必須度で判断する。 Safety / Recoverable / Idempotent に関わる欠如は減点寄り、後続バックログの拡張は提案寄りとする。

技術評価層 — apps/bitflyer

取引所連携・ドメイン・エンジンの正本。論理コンポーネントはアプリ分割せず、このアプリ内の境界として評価する。

• market-data（板・約定・Ticker・再接続）

  • REST / WebSocket 購読の正規化と内部イベント化
  • 切断時の再接続・REST 穴埋め・鮮度（stale）判定
  • 古いデータでは発注しない、というゲートとの接続

• strategy（シグナル生成）

  • 内部コマンド（買いたい / 売りたい / 閉じたい）への変換の明確さ
  • 取引所 API を直接叩かないこと（依存方向の強制）
  • パラメータ適用履歴と戦略切替の安全性

• risk-manager（上限・サーキット・鮮度検査）

  • サイズ / 損失 / 頻度 / 価格逸脱 / 残高の検査網羅性
  • サーキットオープン時に発注経路を閉じること
  • 市場データ鮮度・時計ずれを拒否理由にできること
  • Vision の Safety first をコード上で説明できるか

• order-executor（冪等な発注・取消・モード分岐）

  • 内部注文 ID による冪等性
  • TRADE_MODE（dry_run / paper / live）の出口だけが切り替わる設計
  • paper 中に live の発注 REST を呼ばないこと（テストで固定できるか）
  • 未確定注文の取引所突合と再開手順

• datastore / Ash（永続状態・Repo・マイグレーション）

  • Ash を永続状態（注文・建玉・残高スナップショット・リスク停止・パラメータ履歴）に限定しているか
  • ホットパス（板・Tick・判定ループ）から Resource を呼んでいないか
  • 価格・数量が Decimal であること（float 禁止）
  • Bitflyer.Repo が apps/bitflyer に閉じているか

• cache / ETS（短期市場データ）

  • 鮮度付きキャッシュの設計
  • 消失時に datastore / API から再構築できること
  • 単一ノード前提で Redis 等を不用意に増やしていないか

• observe アダプタ（ログ・メトリクス・Discord 等）

  • 切断・拒否・再起動・不整合の理由が残るか
  • Discord 等は発注経路から独立し、失敗しても取引を止めないこと
  • 秘密情報（キー・Webhook URL・署名）がログ / 通知本文に出ないこと
  • apps/discord 等の第3アプリを切っていないか（方針どおりアダプタか）

• OTP / Application（監督ツリー・起動シーケンス）

  • Endpoint（ui）と取引監督が兄弟で、UI 例外が発注側を巻き込まないこと
  • 起動シーケンス（設定読込 → 復元 → 突合 → 不整合なら停止 → 購読 → Ready）の実装度
  • グレースフルシャットダウン（新規発注停止 → 書き込み完了）

技術評価層 — apps/ui

運用 UI（裁量トレード端末ではない）。

• Phoenix / LiveView

  • 稼働状況・取引モード・建玉/注文/停止理由の閲覧に責務が限られているか
  • Ash の公開インターフェース経由でのみ bitflyer に触るか
  • bitFlyer API を直接叩いていないか
  • 認証・公開面の方針（不用意な公開をしていないか）

• 運用操作性

  • 「今トレードしてよいか」が画面から分かるか
  • 停止理由・モード（dry_run であることの明示）の可視性
  • Vision の非目標（高機能裁量 UI）に踏み込んでいないか

技術評価層 — 実行基盤 / 設定

• Docker Compose / Dockerfile

  • 開発（compose.yaml / bind mount）と本番（release イメージ）の分離
  • restart・healthcheck（プロセス生存だけでなくデータ鮮度・同期を見据えているか）
  • 秘密情報をイメージ・Git に焼いていないか

• config（config.exs / runtime.exs / 環境変数）

  • TRADE_MODE の既定が dry_run であること
  • 開発キーと本番キーを混ぜない設計
  • 環境別（dev / test / prod）の分離と .env.example の追跡方針

• CI / CD

  • ローカルと CI で同じ品質ゲート（本リポジトリでは mix precommit 相当）
  • GitHub Actions で format / compile（warnings-as-errors）/ test（PostgreSQL）
  • 本番シークレットを CI に置かないこと
  • CD は承認付き配布・デプロイ前の発注停止・ロールバックが文書化されているか

横断評価層

コードを横断する品質・プロセス・プロダクト視点で評価する。

• テスト戦略

  • テストピラミッド（ユニット / 統合 / 契約）の意図的設計
  • 発注経路・冪等性・モード分岐（dry_run / paper / live）の回帰
  • 外部 API のモック化・TRADE_MODE=dry_run 前提・副作用ゼロ
  • 突合・サーキット・鮮度ゲートの再現可能なテスト
  • プロパティベーステスト（金額・数量・冪等キー等）の有無

• 可観測性・デバッグ容易性

  • :telemetry イベントの網羅性と粒度
  • 構造化ログとログレベルの設計意図
  • クラッシュ時のコンテキスト（注文 ID・モード・停止理由）
  • 本番での心拍・アラート到達（Discord 等）
  • LiveDashboard 等の運用デバッグ手段

• エラーハンドリング・安全側フォールバック

  • エラー境界（どこで発注を止め、どこで再試行するか）の明示
  • OTP 再起動後の状態回復（推測で埋めない）
  • {:ok, _} / {:error, _} の一貫性
  • 不整合時は Ready にせず停止する設計

• 変更容易性・保守性

  • ui → bitflyer の一方向依存が保たれているか
  • 論理境界（data / strategy / risk / executor / persist）の強度
  • Umbrella を不用意に増やしていないか（第3アプリ禁止の方針）
  • TODO/FIXME・マジックナンバー・命名の一貫性

• 開発者体験（DX）

  • README → docker compose up 相当までのステップ数
  • .env.example・バージョンピン・依存の明示
  • ローカル CI の単一エントリ（mix precommit。未整備なら減点または提案で明示）
  • コンテナ内 / ホストの両方で同じゲートが通ること

• 取引完成度（運用として回るか）

  • 起動 → 購読 → 判定 → リスク → 発注/記録 → 突合 → 停止/再開の全経路
  • モード切替の安全性（live 解禁が明示的か）
  • ペーパーで本番と同経路を検証できているか
  • 「人が張り付かなくても資金を守れる」度合い

• セキュリティ・秘密情報・権限

  • API キー最小権限（出金なし）
  • キー・Webhook の注入方法（環境変数 / ホストシークレット）
  • ログ・通知・イメージからの漏洩防止
  • 管理 UI / DB の公開面最小化
  • 依存の脆弱性管理（mix deps.audit 等）

• プロジェクト全体設計

  • .workspace/0_doc/ の品質・網羅性・コードとの一致度
  • Vision / Architecture と実装の一致（特に Safety first・取引モード）
  • CI/CD と本番PC（VLAN1）運用想定との接続
  • 自己改善サイクル（improvement-plan の運用）

採点基準

加点・減点は +1〜+5 / -1〜-5 の整数で表す。上限・下限なし（同一観点内で複数項目を合算）。

プラス点

マイナス点

提案点（0点）

実装すれば価値が上がるが、現時点では存在しないため加点も減点もしない項目。 0 で表し、「あると尚よい」という前向きな提案として記録する。

評価しないもの: インデントが揃っている、コメントが残っている等、コーディングの当たり前の作業は評価対象外。 思想・設計・アーキテクチャ・実装の質のみを評価する。

採点フォーマット

各観点ごとに以下の形式で記述する。

## [観点名]

### ✅ プラス点

- **[思想/実装名]** `+N`
  > 理由・根拠（ファイル名・行番号・コード例を引用）

### ❌ マイナス点

- **[思想/実装名]** `-N`
  > 理由・根拠（ファイル名・行番号・コード例を引用）
  > 対象ファイル: `path/to/file.ex`

### 💡 提案

- **[提案名]** `0`
  > 実装すれば価値が上がる理由・具体的な実装イメージ・参考実装

**小計: +N / -N = N点**

出力ドキュメント

評価は 第1評価者（Opus）と第2評価者（GPT）が互いに独立 して行い、その後 まとめ を作成する。 YYYY-MM-DD は評価日。評価完了後、以下のファイルを必ず日本語で作成する。

各評価者は 相手の当日評価文書を参照しない。判断は必ず当該コードの再検証に基づく。

出力のルートは .workspace/0_doc/evaluation/（既存の tech-stack.md と同階層）。

第1評価者（Claude Opus 5）

当日分は .workspace/0_doc/evaluation/opus/ 直下に置く。

1. .workspace/0_doc/evaluation/opus/opus-specific-weaknesses-YYYY-MM-DD.md — マイナス点の詳細一覧
2. .workspace/0_doc/evaluation/opus/opus-specific-strengths-YYYY-MM-DD.md — プラス点の詳細一覧
3. .workspace/0_doc/evaluation/opus/opus-specific-proposals-YYYY-MM-DD.md — 提案（0点）の詳細一覧
4. .workspace/0_doc/evaluation/opus/opus-evaluation-YYYY-MM-DD.md — 当日の総合評価レポート

次回評価時、前回分を .workspace/0_doc/evaluation/opus/archive/YYYY-MM-DD/ へ移す。

第2評価者（GPT-5.6 Sol）

当日分は .workspace/0_doc/evaluation/gpt/ 直下に置く。第1評価者の opus/ 配下は読まない。

1. .workspace/0_doc/evaluation/gpt/gpt-specific-weaknesses-YYYY-MM-DD.md — マイナス点の詳細一覧
2. .workspace/0_doc/evaluation/gpt/gpt-specific-strengths-YYYY-MM-DD.md — プラス点の詳細一覧
3. .workspace/0_doc/evaluation/gpt/gpt-specific-proposals-YYYY-MM-DD.md — 提案（0点）の詳細一覧
4. .workspace/0_doc/evaluation/gpt/gpt-evaluation-YYYY-MM-DD.md — 当日の総合評価レポート

次回評価時、前回分を .workspace/0_doc/evaluation/gpt/archive/YYYY-MM-DD/ へ移す。

まとめ

両評価者の出力が出揃った後に作成する。合意・相違・採用判断を明示する。

1. .workspace/0_doc/evaluation/specific-weaknesses-YYYY-MM-DD.md — マイナス点の統合一覧
2. .workspace/0_doc/evaluation/specific-strengths-YYYY-MM-DD.md — プラス点の統合一覧
3. .workspace/0_doc/evaluation/specific-proposals-YYYY-MM-DD.md — 提案（0点）の統合一覧
4. .workspace/0_doc/evaluation/evaluation-YYYY-MM-DD.md — 当日の総合評価レポート
5. .workspace/0_doc/evaluation/improvement-plan.md — まとめのマイナス点に基づく改善提案書

次回評価時、前回のまとめ（上記 1〜4）を .workspace/0_doc/evaluation/archive/YYYY-MM-DD/ へ移す。improvement-plan.md は最新版を置き換える。

アーカイブ

• まとめの前回分: .workspace/0_doc/evaluation/archive/YYYY-MM-DD/
• 評価者別の前回分: opus/archive/YYYY-MM-DD/ / gpt/archive/YYYY-MM-DD/
• 技術選定メモ（tech-stack.md）は評価レポートのアーカイブ対象外（常設参考資料）

ドキュメントの書き方

*-specific-strengths-*.md / *-specific-weaknesses-*.md / *-specific-proposals-*.md およびまとめの同種ファイルは以下の構造で記述する：

• ファイル冒頭に採点基準を表形式で掲載する
• セクションは ##（大分類）→ ###（小分類）の 2 階層にまとめる
• 各項目は - **タイトル** \±N`` のリスト形式で記述する
• 説明文は > ブロック引用としてリストの子要素（インデント付き）に記述する
• 対象ファイルがある場合は説明文の末尾に > 対象ファイル: \path`` として記述する

評価の手順

過去の評価文書を参照するだけで判断しない。必ず当該コードを直接読み、現状を検証してから採点する。

• 前回評価は直近のまとめ .workspace/0_doc/evaluation/evaluation-YYYY-MM-DD.md を起点とする。まとめがまだ無い場合は初回評価とし、Vision / Architecture / 現行コードのみを正とする
• 各評価者は自系統の前回詳細（opus/ または gpt/）のマイナス点が解決済みかどうかを、対象ファイルを読み直して確認する
• 前回「解決済み」でなかった項目を「解決済み」と書く前に、コードの該当箇所を確認する
• mix precommit（または同等の個別コマンド: format / compile --warnings-as-errors / test）の通過可否など、実行で確認すべき項目は可能な限り実行して結果を見る（実行環境の制約がある場合はその旨を明記する）
• Docker 経由が正なら docker compose run --rm app mix precommit 等で確認する

評価の姿勢

• 忌憚なく: 良い点は良い、悪い点は悪いと明確に述べる
• 根拠を示す: ファイル名・行番号・コード例を引用して具体的に説明する
• 建設的に: マイナス点には必ず改善方針を添える
• 提案は前向きに: 0点提案は批判ではなく「次のステップ」として記述する
• 比較軸を持つ: 同種の取引ボット・OTP 常駐システム・Phoenix 運用基盤と比較して評価する
• 資金保全を最優先: 派手な戦略実装より、二重発注防止・サーキット・突合・秘密情報分離を重く見る