portfolio-agent: Instructions file for Claude Code

CLAUDE.md — 포트폴리오 의사결정 에이전트

개인용 투자 의사결정 지원 에이전트. 내 보유 포트폴리오를 읽고 근거와 무효화 조건이 붙은 판단(보유/축소/추가)을 내린다. 뉴스 요약기가 아니라 의사결정 시스템이다.

이 파일은 실행 체크리스트가 아니라 행동 계약이다. 작업 목록은 TASKS.md에 있다.

---

최우선 규율 (절대 위반 금지)

• IMPORTANT: 토스 API는 읽기 전용이다. 주문·거래·정정·취소 엔드포인트는 코드에 존재해서도 안 된다. sources 클라이언트에 매매 함수를 만들지 마라.
• IMPORTANT: 수치는 LLM이 생성하지 않는다. 가격은 토스, 재무·공시는 DART/EDGAR 원문에서 온다. 계산(집중도·상관·리스크·리밸런싱)은 engines/의 코드가 한다. LLM은 그라운딩된 텍스트 위에서 요약·종합·논지 판정만.
• IMPORTANT: 모든 판단에는 (a) 근거 원문 링크와 (b) 무효화 조건("이 판단이 뒤집히려면 무엇이 참이어야 하는가")이 반드시 붙는다. 이 두 필드가 없는 추천은 불완전한 출력으로 간주하고 반려하라.
• 사실 하나당 소스 오브 트루스 하나. 구조화된 논지 상태는 MySQL, 서술·추론 원문은 마크다운 vault. 같은 사실을 두 곳에 쓰지 마라(중복 = drift).
• 벡터 검색은 수치 경로에 절대 넣지 마라. 벡터는 "주제적으로 비슷한 과거 노트/사례" 회수 전용이다.
• 관찰 트랙(기술적 분석·뉴스 감성)은 Obsidian 병렬 전용이다. 코드 지표·YOLO 차트 패턴·FinBERT 뉴스 감성 — 전부 확률적/관찰 신호이고, 의사결정 엔진·그라운딩 번들(E#)·게이트·논지 상태머신에 절대 들어가지 않는다 (벡터와 같은 격리 범주). engines/technical.py·engines/patterns.py·engines/sentiment.py·knowledge/charts.py·sentiment_export.py. 강한 신호는 다이제스트 '판단 필요'로 표면화해 사람이 /review 하는 트리거로만 쓴다. 상세: docs/technical.md·docs/sentiment.md.
• 시크릿은 코드·커밋에 넣지 마라. 전부 .env. 노출 시 즉시 재발급.

작업 방식

• 확실하지 않으면 진행하지 말고 물어라. 두 접근이 갈리면 둘 다 설명하고 내가 고르게 하라.
• 요청 범위 밖 리팩터링 금지. 최소 변경.
• 논리 단위별로 커밋을 분리하라. 한 번에 몰아 커밋하지 마라.
• 코드 변경 후 관련 테스트를 돌려라.
• 기능은 한 번에 하나. end-to-end 검증 후에만 완료로 표시.

---

스택

• 언어: Python 3.11+
• 정형 저장소: MySQL (Repository 추상화로 감싼다 — 엔진 교체 가능하게)
• 비정형 지식: 마크다운 vault (vault/), Obsidian은 같은 폴더를 보는 human 뷰어일 뿐
• 데이터 소스(읽기전용): 토스증권 오픈 API, OpenDART, SEC EDGAR, (보조) 뉴스 API
• 에이전트: Claude Code (오케스트레이터) + 커스텀 MCP 서버(stdio)
• 벡터(지연): 코퍼스 쌓이면 sqlite-vec/numpy 파생 인덱스

아키텍처 개요 (계층)

Claude Code (오케스트레이터)
  └─ MCP 서버 (stdio, 읽기전용)
       ├─ sources 클라이언트 : 토스·DART·EDGAR 읽기
       ├─ engines           : quant(계산) · thesis(논지 상태머신)
       └─ synthesis         : 근거+무효화 조건 판단 (LLM)
  └─ 저장 : MySQL(정형 SoT) · 마크다운 vault(Obsidian)

디렉토리 구조

portfolio-agent/
├── CLAUDE.md
├── TASKS.md                  # 작업 백로그 (이 파일 아님)
├── .env.example              # 키 목록만. 실제 .env는 gitignore
├── .mcp.json                 # 프로젝트 스코프 MCP 서버 (secrets는 ${ENV})
├── config/settings.py        # 목표 비중(core-satellite), 임계치, 경로
├── src/
│   ├── storage/              # Repository 인터페이스 + mysql_repo + schema.sql
│   ├── knowledge/            # vault(.md) read/write
│   ├── sources/              # toss_client(읽기전용)·dart_client·edgar_client
│   ├── engines/              # quant.py(계산, LLM 없음)·thesis.py(상태머신)
│   ├── synthesis/            # prompts.py·decision.py (근거+무효화 강제)
│   ├── mcp/                  # portfolio_server.py·sources_server.py
│   └── cli/                  # brief.py (온디맨드 심층 판단 + 백그라운드 감시)
├── vault/                    # theses/ · reflections/ · engineering-journal/
└── tests/