1주차 - 동작하는 OS 뼈대

[dev-yeojin]

개요

한국·미국 주식을 적립식(장기) 으로 관리하는 개인 투자 OS stock-os를 만들었습니다.
매일 아침 시장·내 투자 성향·보유 종목을 비교해 개인화된 데일리 조언을 받고, 매매가 일어나면
기록으로 남겨 학습합니다.
돈을 움직이는 행위는 100% 사람이 하고, AI는 정보·기록·조언까지만 합니다.

무엇을 만들었나

메인 루프
① 성향 인터뷰 → ② 데일리 조언 → ③ 사람의 실행 → ④ 학습·기록 (②↔④ 매일 반복)

무엇을 만들었나

메인 루프
① 성향 인터뷰 → ② 데일리 조언 → ③ 사람의 실행 → ④ 학습·기록 (②↔④ 매일 반복)

Subagents (.claude/agents/ — 역할 = 독립 컨텍스트 프로세스)

서브에이전트	루프 단계	컨텍스트 분리 이유	도구	모델	출력
market-scanner	② 수집	웹 조회가 무거움(토큰 격리)	Read, WebSearch, WebFetch	sonnet	시장 스냅샷 + 출처
portfolio-analyst	② 판단	개인화 분석 컨텍스트 격리	Read, Write, Edit	opus	데일리 리포트 저장
return-calculator	④·온디맨드	격리 아님 — 재사용(DRY)·계산 일관성(공유 SSOT)	Read	sonnet	실질 실현손익 + journal용 한 줄
monthly-reviewer	④ 복기	월간 분석 컨텍스트 격리	Read, Edit, Write	sonnet	월간 리뷰 append

Skills (.claude/skills/)

스킬	루프 단계	트리거(예)	하는 일	실행 컨텍스트
daily-report	② 데일리 조언	"데일리", "오늘 리포트"	scanner 병렬 수집 → 메인 취합 → analyst 판단 → 04_daily/YYYY-MM-DD.md 저장	메인(오케스트레이션)
log-trade	④ 학습·기록	"샀어", "팔았어", "매매 기록"	체결·감정·thesis를 되물어 holdings + trade-journal 동시 갱신	메인(대화형)
pre-trade-check	③′ 실행 직전	"이거 사도 돼?", "팔까 말까"	원칙·약점(FOMO·물타기)에 비춰 시나리오로 되짚음(주문 안 함)	메인(로컬·결정론)
rebalance-check	온디맨드	"리밸런싱 체크", "비중 점검"	현재 비중을 목표(미국7:한국3·단일종목20%·±5%p)와 대조	메인(로컬·결정론)
realized-return	온디맨드	"실수익 계산"	세후·수수료·환율 차감 실질 실현손익(표면 vs 실질)	메인 + return-calculator 위임
thesis-review	온디맨드(분기)	"thesis 점검", "논리 유효해?"	종목별 매수 논리를 최신 사실과 대조 → 유효/관찰/훼손 판정	메인 + market-scanner 재사용

Hook · 자동화 (automation/, .claude/settings.json)

구성요소	종류	트리거	하는 일
holdings-journal-guard.sh	PostToolUse hook	holdings.md Write/Edit	trade-journal도 갱신했는지 리마인드 (차단 아닌 nudge, exit 2)
com.stock-os.daily-report	launchd (plist + 러너)	매일 아침(평일) 자동	데일리 조언 파이프라인 실행 (--allowedTools 최소권한, Bash 불허)

상태·데이터 파일

• 00_principles(규칙 SSOT) · 01_profile(성향) · 02_portfolio(holdings·watchlist) ·
  03_journal(매매 일지) · 04_daily(리포트) · 05_reference(세금·데이터 출처)

접근 방식

• 역할을 프로세스로: 각 역할을 독립 컨텍스트 subagent(agents/)로 분리하고, 메인 에이전트는
  직접 일하지 않는 오케스트레이터로 두었습니다. 컨텍스트 격리로 토큰 효율·역할 응집을 얻습니다.
• 의존성 기준 병렬화: 데일리 조언에서 의존성 없는 수집(macro·tickers)은 market-scanner를
  병렬 fan-out, 수집 결과에 의존하는 판단(portfolio-analyst)은 순차로 실행합니다.
• 대화형은 스킬, 순수 계산은 서브에이전트: 매매 기록은 감정·thesis를 되물어야 해서
  (subagent는 사용자와 대화 불가) 메인 컨텍스트 스킬 log-trade로, 세율·환율 계산은 재사용을 위해
  return-calculator 서브에이전트로 나눴습니다.
• 커널 규칙을 hook으로 강제: "기록 없는 매매 없음"은 사람이 아니라 하니스가 실행하는
  자동 동작이라 메모리·선호로는 보강 불가 → PostToolUse hook으로 nudge합니다.

설계 의도 (핵심 결정과 근거)

• 왜 역할 분리(사람/AI)인가: 투자 OS에서 가장 위험한 건 AI가 주문을 내는 것. 가드레일(§6)로
  실제 주문·송금·환전 실행을 금지하고 AI를 조언·기록에 묶었습니다.
• 왜 return-calculator를 공유 SSOT로 뽑았나: realized-return과 log-trade(매도 경로)가
  세율·환율 공식을 각자 구현하면 숫자가 어긋납니다. DRY·계산 일관성을 위해 하나의 계산 출처로 모았습니다.
• 왜 log-trade는 서브에이전트로 안 뽑았나: 매매 기록은 체결 상세·그때 감정·thesis를 되묻는
  대화형 작업인데, 서브에이전트는 프롬프트 1개만 받고 결과만 반환하므로 대화가 불가능합니다.
• 왜 로컬 전용·최소권한 자동화인가: 개인화의 핵심인 holdings.md가 로컬 전용(gitignore)이라
  클라우드 에이전트는 접근 불가 → launchd 로컬 스케줄. 무인 실행은 --dangerously-skip-permissions
  대신 --allowedTools(Bash 불허)로 최소권한만 부여합니다.
• 왜 hook이 차단이 아니라 nudge인가: journal 갱신은 편집 뒤에 오는 게 정상 흐름이라 편집을
  막지 않고 exit 2로 리마인드만 Claude 루프에 피드백해 후속 조치(log-trade)를 유도합니다.
• 왜 실수익(세후·수수료·환율) 기준인가: 표면 수익률은 착시라, 모든 수익률을 실질 기준으로
  말하도록 커널(§1)에 못 박았습니다.

실행 흐름 (데일리 조언 ②)

[병렬] market-scanner(macro) ┐
[병렬] market-scanner(tickers) ┘─→ [메인 취합] ─→ [순차] portfolio-analyst ─→ 04_daily/YYYY-MM-DD.md 저장

향후 계획 (로드맵)

지금은 매매 기록이 대화형 수기 입력(log-trade)이고 데일리 시세는 웹 조회(market-scanner)에 의존합니다.
다음 단계에서는 증권사 API를 연결해 이 두 축을 자동화할 계획입니다.

• 매매 자동 수집: 데일리로 모으는 체결 내역을 증권사 API로 받아 holdings.md + trade-journal.md에
  자동 기록합니다. 수기 입력 오류를 없애고, 커널 §1 "기록 없는 매매 없음"을 API 동기화로 강제합니다.
• 시세 자동 조회: 데일리 시세·잔고를 API로 직접 조회해 로컬 파일(시세 스냅샷)에 기록하고,
  그 데이터로 데일리 보고서를 생성합니다. 웹 조회 신뢰도 의존을 줄입니다.
• 유지되는 원칙: API 연동 후에도 가드레일(§6)은 그대로 — 조회·기록·보고서까지만 자동화하고,
  실제 주문·송금·환전은 100% 사람이 합니다. 데이터는 로컬 파일에 저장해 개인 자산 정보의 로컬 전용 원칙을 지킵니다.