dev-puppeteer/my-deepagent-seed/README.md

# my-deepagent v0.1.0 Seed Assets

이 디렉토리는 새 머신(`/Users/1111615/Desktop/Repository/my-deepagent`)에서 v0.1.0 개발을 시작할 때 사용하는 자산 묶음입니다. 메인 머신에서 **실제 검증 완료** (deepagents 0.6.1 API inspect, OpenRouter ChatOpenAI 인스턴스화, BudgetTracker PoC pytest 5/5 PASS, 시드 yaml/json 18개 validate.py 통과).

## 구성

```
my-deepagent-seed/
├── README.md                           # 이 문서
├── poc/                                # BudgetTracker + CostMiddleware PoC (검증 완료)
│   ├── pyproject.toml
│   ├── src/poc/{budget,pricing,middleware,mock_model}.py
│   └── tests/test_budget.py            # 5/5 PASSED
└── schemas/                            # v0.1.0 시드 자산 (validate.py 통과)
    ├── validate.py
    ├── personas/                       # 10개 yaml
    │   ├── default-interactive@1.yaml
    │   ├── openrouter-claude-spec-writer@1.yaml
    │   ├── openrouter-claude-phase-planner@1.yaml
    │   ├── openrouter-claude-code-editor@1.yaml
    │   ├── openrouter-claude-code-reviewer@1.yaml
    │   ├── openrouter-claude-security-auditor@1.yaml
    │   ├── openrouter-deepseek-verifier@1.yaml
    │   ├── openrouter-claude-debugger@1.yaml
    │   ├── openrouter-deepseek-log-analyzer@1.yaml
    │   └── openrouter-claude-architect@1.yaml
    ├── workflows/                      # 3개 yaml
    │   ├── spec-and-review@1.yaml
    │   ├── bug-fix-with-reproduction@1.yaml
    │   └── code-investigation@1.yaml
    └── artifacts/                      # 4개 JSON Schema 2020-12
        ├── dev/{spec,phase-plan,review-finding-batch}@1.json
        └── common/final-report@1.json
```

## 새 머신으로 옮기는 방법

이 디렉토리는 메인 머신 워크트리 안에 있습니다. 새 머신에서 사용하려면:

### 옵션 A: tar.zst 압축 후 수동 복사 (가장 단순)
```bash
# 메인 머신에서
cd /Users/chungyeong/Desktop/Dev/dev-puppeteer/.claude/worktrees/sad-satoshi-d938d4
tar --zstd -cf /tmp/my-deepagent-seed.tar.zst my-deepagent-seed/
# AirDrop / scp / iCloud Drive 등으로 새 머신에 복사
# 새 머신에서
cd /Users/1111615/Desktop/Repository
tar --zstd -xf my-deepagent-seed.tar.zst
mv my-deepagent-seed my-deepagent   # 이름 변경
```

### 옵션 B: Git push/clone
```bash
# 메인 머신에서 (워크트리에 commit 후)
git add my-deepagent-seed/
git commit -m "feat: my-deepagent v0.1.0 seed assets"
git push origin claude/sad-satoshi-d938d4
# 새 머신에서
git clone <repo-url>
# my-deepagent-seed/ 디렉토리만 추출 후 새 위치로 이동
```

### 옵션 C: 클립보드 (작은 파일은)
각 yaml/json/py를 채팅에서 복사 → 새 머신 에디터에 paste.

## 새 머신 시작 절차 (Step 0)

```bash
cd /Users/1111615/Desktop/Repository/my-deepagent

# 1. uv 설치 (없으면)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Python 프로젝트 초기화
uv init --no-readme

# 3. 의존성 추가 (정확한 1.x 버전)
uv add \
  'deepagents>=0.6.1,<0.7.0' \
  'langchain>=1.3.0,<2.0.0' \
  'langchain-core>=1.4.0,<2.0.0' \
  'langchain-openai>=1.2.1,<2.0.0' \
  'langgraph>=1.2.0' \
  'langgraph-checkpoint-sqlite>=3.1.0' \
  'openai>=2.26.0' \
  'pydantic>=2.9' \
  'pydantic-settings>=2.6' \
  'pyyaml>=6.0' \
  'jsonschema>=4.23' \
  'aiosqlite>=0.20' \
  'alembic>=1.14' \
  'typer>=0.14' \
  'prompt-toolkit>=3.0' \
  'rich>=13.9' \
  'structlog>=24.4' \
  'platformdirs>=4.9' \
  'keyring>=25.7' \
  'zstandard>=0.23' \
  'httpx>=0.28'

uv add --dev 'pytest>=8.3' 'pytest-asyncio>=0.24' 'pytest-httpx>=0.34' 'ruff>=0.8' 'mypy>=1.13' 'pre-commit>=4.0'

# 4. 시드 자산을 docs/schemas/ 로 복사
mkdir -p docs/schemas
cp -r my-deepagent-seed/schemas/personas docs/schemas/
cp -r my-deepagent-seed/schemas/workflows docs/schemas/
cp -r my-deepagent-seed/schemas/artifacts docs/schemas/

# 5. PoC 코드를 참조 (Step 5/8 구현 시 활용)
# 직접 복사하지 말고 패턴/구조만 참조해 src/my_deepagent/ 아래로 재작성

# 6. plan-v2.0 본문을 docs/plan.md로 저장
# (채팅의 plan v2.0 본문을 통째 복사 + 아래 §10 패치 반영)
```

## plan v2.0 §10 middleware 패턴 정정 (필수)

채팅의 plan v2.0 §10 (DeepAgent Session Wrapper)에 적힌 `cost_middleware(run, phase_def)` 함수형은 **잘못된 패턴**입니다. PoC 검증 결과 langchain 1.x의 정확한 패턴은:

```python
from langchain.agents.middleware import AgentMiddleware


class CostMiddleware(AgentMiddleware):
    """Track LLM cost per call. Sub-class pattern (not decorator)."""

    def __init__(
        self,
        tracker: BudgetTracker,
        run_id: UUID | None,
        persona_name: str,
        model_name: str,
    ) -> None:
        super().__init__()
        self.tracker = tracker
        self.run_id = run_id
        self.persona_name = persona_name
        self.model_name = model_name

    async def awrap_model_call(self, request, handler):
        estimated = compute_cost(self.model_name, 1000, 2000)  # worst-case estimate
        await self.tracker.assert_can_call(self.run_id, self.persona_name, estimated)
        response = await handler(request)
        usage = getattr(response, "usage_metadata", None) or {}
        actual = compute_cost(
            self.model_name,
            usage.get("input_tokens", 0),
            usage.get("output_tokens", 0),
        )
        await self.tracker.record(self.run_id, self.persona_name, actual)
        return response
```

핵심:
- `AgentMiddleware` **subclass** (decorator 아님)
- `awrap_model_call` async 메서드 오버라이드 (sync 변형 없음)
- `from langchain.agents.middleware import AgentMiddleware` (정확한 import)
- `create_deep_agent(..., middleware=[CostMiddleware(tracker, run_id, persona.name, persona.model)])`

`audit_tool_middleware`, `safety_middleware`, `fallback_middleware`, `phase_artifact_watcher`도 동일 패턴(class subclass + async method override)으로 구현. plan v2.0 §10 코드 블록을 위 형식으로 교체.

## PoC에서 검증된 핵심 사실

1. **deepagents 0.6.1**: 실제 설치 성공, `create_deep_agent` signature 확인됨 — model/tools/system_prompt/subagents/middleware/checkpointer/interrupt_on/permissions/backend/skills/memory/response_format 등 모두 keyword args
2. **SubAgent는 TypedDict**: `name`, `description`, `system_prompt` 필수. dict 그대로 전달 가능
3. **FilesystemPermission은 dataclass**: `operations` / `paths` (절대 경로 강제, `..`/`~` 금지) / `mode`
4. **LocalShellBackend**: `execute` tool 동작용 backend. `inherit_env=False` 권장 (보안)
5. **OpenRouter 통합 검증**: `ChatOpenAI(model="...", api_key="sk-or-...", base_url="https://openrouter.ai/api/v1", max_tokens=...)` 인스턴스화 성공
6. **AgentMiddleware**: subclass + `awrap_model_call` async 패턴 (위 정정)
7. **BudgetTracker**: SQLite WAL + `ON CONFLICT DO UPDATE` upsert로 concurrent-safe ledger 가능 (PoC 검증)

## v0.1.0 6주 계획 (Step 0 ~ 16)

채팅의 plan v2.0 §25 참조. 각 Step 끝에:
```bash
uv run ruff check . && uv run ruff format --check . && uv run mypy --strict . && uv run pytest
```
모두 PASS → commit → 다음 Step.

## 모델 위임 (메모리 룰)

- Python 구현 → sonnet 서브에이전트
- 코드 리뷰 → opus 서브에이전트
- 리뷰 지적 수정 → sonnet
- 메인 스레드 (Claude Code, Opus 4.7) 는 오케스트레이션만

## 다음 액션 (새 머신에서)

1. 위 "새 머신 시작 절차" 1~6 실행
2. Claude Code 새 세션: `claude`
3. 첫 메시지로 plan v2.0 본문 + 본 README의 §10 정정 패치 + "Step 0부터 진행해" 지시
4. Step 0 (스캐폴딩) → Step 1 (core) → ... 순차 진행
5. 각 Step에서 sonnet 서브에이전트에 실제 구현 위임 (메인 스레드는 오케스트레이션)