ec-ops — 輸入無在庫販売 EC 自動運営システム

テーマ: HOOTL（Human Out of The Loop） — 人間介在なしで 24h 自動運営

プロジェクト: .AI 自動運転部 水曜日チーム

フェーズ: Phase 1 完了（533テスト PASS / 2026-05-15）

HOOTL: 人間の介在を最小化し、AI が自律的に事業運営・自己改善するシステム。

人間が関与するのは kill switch / KPI 設定 / 閾値変更 / 事後監査 の 4 種のみ。

---

アーキテクチャ（5層構造）

設計書: ADR-002 / docs/02_アーキテクチャ/

---

業務エージェント（L2: AgentRunner 経由 claude -p）

各エージェントは agents/{name}/agent.md を読み込み、AgentRunner 経由で claude -p --add-dir を起動する。

audit_evaluator / applier は L4 HOOTL 改善層のエージェント。

scout / chain_pick / inventory_sync は task-820 で LLM-Free ジョブへ移行完了。

---

LLM-Free ジョブ（jobs/{name}/job.py 直接起動）

LLM を使用しない高頻度・決定論的処理は jobs/{name}/job.py として独立させ、

JOB_TRIGGERS 経由で直接 Popen 起動する（AgentRunner を経由しない）。

---

エージェント三層構造（agent.md / .claude/skills/{name}-toolkit/SKILL.md / skill_refs）

LLM 品質を長期維持するため、各エージェントの知識を 3 層に分離する。

agents/{name}/
├── agent.md                        # 実行プロンプト定義（AgentRunner が読み込む）
├── manifest.yaml                   # エージェント設定（必須ファイル・保護セクション定義）
├── .claude/
│   └── skills/
│       └── {name}-toolkit/
│           └── SKILL.md            # スキル定義（LOCKED/EDITABLE セクション、Claude Code auto-discover）
├── skill_refs/                     # 参照スキル群（criteria / checklist / persona 等、.claude/ 外）
│   ├── criteria.md
│   ├── checklist.md
│   └── ...
└── scripts/                        # fetch_*.py / save_result.py（DB アクセス層）

SKILL.md の LOCKED / EDITABLE マーカー: <!-- LOCKED: section=xxx --> / <!-- /LOCKED -->

詳細: 三層構造アーキテクチャ設計書

---

四層防御（自動変更の安全保護）

L4 HOOTL 改善層がエージェントを自動改変する際の安全機構。

git hook インストール:

bash scripts/install-hooks.sh

---

CLI 7 種（L0: tools）

各 CLI は独立した pyproject.toml を持ち、tools/{name}/ で管理。

---

フォルダ構成

ec-ops/
├── agents/                    # L2: 10 LLM エージェント
│   └── {name}/
│       ├── agent.md           # 実行プロンプト（AgentRunner が読み込む）
│       ├── manifest.yaml      # エージェント設定
│       ├── .claude/
│       │   └── skills/
│       │       └── {name}-toolkit/
│       │           └── SKILL.md   # スキル定義（Claude Code auto-discover）
│       ├── skill_refs/        # 参照スキル群（.claude/ 外）
│       └── scripts/           # fetch_*.py / save_result.py
│
├── jobs/                      # LLM-free ジョブ（5 種）
│   └── {name}/
│       └── job.py
│
├── src/                       # L1: ワークフロー管理
│   ├── runner.py              # APScheduler + エントリポイント
│   ├── chain_runner.py        # AGENT_TRIGGERS / JOB_TRIGGERS レジストリ
│   └── db/                   # DB スキーマ・repository
│
├── lib/                       # 共通ライブラリ
│   └── agent_framework.py     # AgentRunner / ClaudeRunner / ChainEmitter
│
├── improvement/               # L4: HOOTL 改善層
│   ├── engine.py              # ImprovementEngine
│   └── ...
│
├── tools/                     # L0: CLI 7 種
│   └── {name}/
│       ├── pyproject.toml
│       └── {name}/            # CLI 実装
│
├── docs/                      # 設計ドキュメント
│   ├── 02_アーキテクチャ/
│   ├── 03_設計/
│   ├── 06_意思決定/           # ADR（ADR-002 等）
│   └── architecture/          # 三層構造・runner-framework 設計書
│
├── migrations/                # DB マイグレーション
├── tests/                     # 統合テスト
├── config/                    # システム設定（system.yaml 等）
├── secrets/                   # 認証情報（git 管理外）
├── docker-compose.yml         # runner + urium-server 2コンテナ構成
└── pyproject.toml             # プロジェクト設定・依存関係

---

セットアップ

開発環境（ローカル）

# 依存関係インストール（uv 推奨）
uv sync

# または pip
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# git hook インストール（四層防御有効化）
bash scripts/install-hooks.sh

本番環境（Docker Compose）

# 認証情報の配置
mkdir -p ~/.ec-ops
cp path/to/shopify-token.json ~/.ec-ops/
cp path/to/cj-token.json ~/.ec-ops/

# Claude Code subscription 認証（ホストで事前に claude login 済みであること）
# ~/.claude と ~/.claude.json がコンテナにマウントされる

# 環境変数設定
cp .env.example .env
# .env の EC_OPS_DB_PATH / URIUM_* 等を環境に合わせて編集

# 起動（urium-server + runner の 2 コンテナ）
docker-compose up -d

# ログ確認
docker-compose logs -f runner

テスト実行

# 全テスト
uv run pytest

# 特定エージェント
uv run pytest agents/description/tests/ -v

---

開発手順

通常の feature 開発

# 1. feature ブランチ作成（起点は dev）
git checkout dev && git pull
git checkout -b feature/my-work

# 2. 実装 → テスト → ruff / mypy 確認
uv run pytest
uv run ruff check . && uv run mypy .

# 3. コミット（四層防御 hook が自動チェック）
git add ... && git commit -m "feat: ..."

# 4. dev にマージ（PR レビュー後）

エージェントへの変更

ワークフローチェーン

[scheduler cron]
  ├→ schedule.daily_scout     → scout (job) → scout.completed
  │                                             ├→ guardrail → guardrail.completed
  │                                             └→ pricing (job)
  ├→ schedule.chain_pick      → chain_pick (job) → chain_pick.picked
  │                                                   └→ guardrail → guardrail.completed
  ├→ schedule.inventory_sync  → inventory_sync (job)
  ├→ schedule.daily_pricing   → pricing (job)
  └→ daily.trigger            → audit_evaluator → audit-evaluator.proposal_ready
                                                     └→ applier

[guardrail.completed]
  └→ description → description.completed
       └→ description_reviewer
            ├─ approved → site_ops → site-ops.listed
            │                          ├→ site_reviewer
            │                          └→ vision_qa
            └─ failed  → (drop)

[site-reviewer.failed]
  └→ site_ops (再生成モード) → site-ops.regenerating → description

kill switch

# 全エージェント停止（緊急時）
ecopscli kill-switch enable

# 再開
ecopscli kill-switch disable

---

既知の課題・制限事項

現時点で認識している制限事項と対応方針を記録する。

---

参照ドキュメント

---

ブランチ運用