xhh/financial-data-platform
1
0
Fork 0
Code Issues 16 Pull requests Projects Releases Packages Wiki Activity Actions

Claude 스킬 시범 전환: 유동성 분석 -> /api/analysis/liquidity-snapshot #6

New issue
Closed
opened 2026-04-22 00:26:29 +09:00 by xhh · 5 comments
xhh commented 2026-04-22 00:26:29 +09:00
Owner
Copy link

매크로 리포트 스킬의 유동성 분석 섹션 1개만 DB API 호출로 전환. 기존 경로 병행 유지하며 A/B.

매크로 리포트 스킬의 유동성 분석 섹션 1개만 DB API 호출로 전환. 기존 경로 병행 유지하며 A/B.
xhh commented 2026-04-26 13:35:27 +09:00
Author
Owner
Copy link

스킬 레포 작업 세션용 가이드

이 작업은 D:\source\claude-plugin 레포에서 새 Claude 세션을 열어 진행한다. 이 financial-data-platform 레포는 더 이상 손대지 않는다 (선행 #62 capabilities 엔드포인트, #14 liquidity-snapshot 엔드포인트는 이미 main 에 있음).

1. 작업 위치

D:\source\claude-plugin\
├── macro-report\
│   ├── agents\
│   │   ├── macro-scanner.md   ← 이번 변경 핵심 (수집 로직)
│   │   └── macro-writer.md
│   ├── commands\
│   │   ├── generate.md
│   │   ├── report.md          ← 단일 보고서 트리거
│   │   ├── synthesize.md
│   │   └── backtest.md
│   └── skills\macro-report-workflow\
│       ├── SKILL.md
│       └── references\
│           └── question-liquidity.md   ← 19개 항목 정의
└── README.md

레포는 마켓플레이스 본체. macro-report 외에도 dailylog, nanobanana, stock-analysis 등 별도 스킬 폴더 공존 — 이번 작업은 macro-report 디렉토리만 수정.

2. 변경 대상

1차 시범 전환 — liquidity 보고서 한 종에 한정.

macro-scanner.md 의 Phase 2 데이터 수집 로직에 다음 분기를 끼워 넣는다:

"report_type 이 liquidity 이면, WebSearch 전에 먼저 https://stock.xhhan.com/api/meta/capabilities 를 fetch 해 사용 가능한 데이터를 파악한 뒤, API 가 커버하는 항목은 해당 엔드포인트로 받고, 못 하는 항목만 WebSearch fallback."

기존 5개 보고서 모두에 동시에 적용하지 않는 이유 — 토큰 절감 효과를 분리 측정해야 #7 이 의미를 가짐.

3. 호출 흐름

[1] GET /api/meta/capabilities          (text/markdown, ~3KB)
    → 사용 가능한 엔드포인트/심볼/테이블 커버리지 한 번에 흡수

[2] 본격 수집 (liquidity 한정):
    GET /api/analysis/liquidity-snapshot   ← M2/RRP/TGA/WALCL + 순유동성
    GET /api/analysis/yield-curve          ← 10Y-2Y, 3개월 전 비교, 역전 플래그
    GET /api/indicators/{symbol}            ← FRED 시리즈 시계열 (M2SL, BAMLH0A0HYM2 등)
    GET /api/indicators/latest              ← 전체 FRED 최신값 일괄
    GET /api/prices/{symbol}                ← VIX, DXY, BTC, TLT 등
    GET /api/margin-debt/recent             ← FINRA 마진 부채

[3] WebSearch fallback (capabilities 가 안 알려준 항목):
    - CME FedWatch 확률 (Fed Funds Futures 자체는 ZQ=F 가격으로 있음, 확률 역산은 미구현)
    - MMF 잔액 (ICI)
    - SLOOS, 소비자 심리, 자사주 매입 규모
    - QRA 발행 계획, TIC 외국인 흐름 (#9, #10 으로 추적 중)
    - 지정학 리스크 정량화

중요: 위 매핑은 capabilities 응답이 동적이라 하드코딩 금지. 스킬 프롬프트에는 "capabilities 응답에 path 가 있으면 API 호출, 없으면 WebSearch" 규칙만 박고, 매핑은 capabilities 가 결정하게 둔다. 새 엔드포인트가 financial-data-platform 에 추가되면 스킬 수정 없이 자동 인지.

4. A/B 병행 유지 방법

#7 측정 + 회귀 안전을 위해 두 경로를 모두 유지:

  • 새 경로 (default-on): capabilities 우선
  • 기존 경로 (fallback / off-switch): 환경변수 MACRO_SKIP_API=1 또는 report 커맨드 인자 --no-api 가 있을 때 기존 WebSearch-only 흐름

이 토글은 macro-scanner.md 의 Phase 0 직전에 한 줄 분기 추가로 충분.

5. 토큰 측정 (#7) 짝지어 진행

스킬 레포 세션에서 #6 끝나면 바로 #7 도 묶어서 처리하는 게 효율적:

  • A/B 두 경로로 같은 날 같은 데이터 한 번씩 실행
  • macro-scanner 가 받은 입력 길이 + Web 응답 토큰 합산 (Read/WebFetch 응답 추정)
  • 결과를 D:\source\claude-plugin\macro-report\skills\macro-report-workflow\references\token-savings.md 같은 곳에 표로 기록 (B/A 절감률 + 항목별 분해)
  • 통합 로드맵의 핵심 검증 지표

6. 이 레포(financial-data-platform) 쪽에서 추후 검토할 것

스킬 레포 작업 중 발견될 수 있는 후속 — 발견 시 별도 이슈로:

  • CME FedWatch 확률 역산: ZQ=F 월물 체인은 이미 수집 중 (#8). 확률 계산만 추가하면 capabilities 에서 새 엔드포인트로 제공 가능 → 스킬 자동 인지
  • MMF / SLOOS / QRA / TIC: #9, #10, 신규 이슈 후보. 현재 capabilities 가 "데이터 없음" 으로 알리고 스킬이 WebSearch fallback 하는 흐름 정상 동작 — data_gaps 로 자동 기록되도록 #15 진행 시 자연스럽게 통합
  • /api/analysis/* 추가 편의 엔드포인트: 스킬이 자주 같은 시리즈를 묶어 가져온다면 (예: 마진 부채 + GDP 비율 + MoM 변화) 한 번에 주는 엔드포인트 신설 검토. 단, capabilities 디스커버리가 잘 작동한다면 스킬 측에서 단순 조합으로 충분할 가능성 — 측정 결과 보고 결정

7. 시작 명령 (스킬 레포 새 세션에서)

D:\source\claude-plugin 으로 작업 디렉토리 변경 후 Claude 세션 시작.

요청 예시:
"financial-data-platform 의 #6 작업을 시작해줘.
macro-report 의 macro-scanner 를 capabilities 우선 흐름으로 전환.
liquidity 보고서 한정, A/B 토글 유지. 진행 가이드는
git.xhhan.com/xhh/financial-data-platform/issues/6 의 댓글 참고."

선행/관련

  • 선행: #62 (/api/meta/capabilities 마크다운 디스커버리, 완료)
  • 선행: #14 (/api/analysis/liquidity-snapshot, 이미 운영 중)
  • 짝꿍: #7 (토큰 절감 측정, 같은 세션에서 묶어 처리 권장)
  • 후행: #15 (data_gaps 피드백 루프 — 스킬 운영 1~2주 데이터 쌓인 뒤)
## 스킬 레포 작업 세션용 가이드 이 작업은 **`D:\source\claude-plugin`** 레포에서 새 Claude 세션을 열어 진행한다. 이 financial-data-platform 레포는 더 이상 손대지 않는다 (선행 #62 capabilities 엔드포인트, #14 liquidity-snapshot 엔드포인트는 이미 main 에 있음). ### 1. 작업 위치 ``` D:\source\claude-plugin\ ├── macro-report\ │ ├── agents\ │ │ ├── macro-scanner.md ← 이번 변경 핵심 (수집 로직) │ │ └── macro-writer.md │ ├── commands\ │ │ ├── generate.md │ │ ├── report.md ← 단일 보고서 트리거 │ │ ├── synthesize.md │ │ └── backtest.md │ └── skills\macro-report-workflow\ │ ├── SKILL.md │ └── references\ │ └── question-liquidity.md ← 19개 항목 정의 └── README.md ``` 레포는 마켓플레이스 본체. `macro-report` 외에도 `dailylog`, `nanobanana`, `stock-analysis` 등 별도 스킬 폴더 공존 — 이번 작업은 **macro-report 디렉토리만** 수정. ### 2. 변경 대상 **1차 시범 전환 — `liquidity` 보고서 한 종에 한정.** `macro-scanner.md` 의 Phase 2 데이터 수집 로직에 다음 분기를 끼워 넣는다: > "report_type 이 `liquidity` 이면, **WebSearch 전에 먼저** `https://stock.xhhan.com/api/meta/capabilities` 를 fetch 해 사용 가능한 데이터를 파악한 뒤, API 가 커버하는 항목은 해당 엔드포인트로 받고, 못 하는 항목만 WebSearch fallback." 기존 5개 보고서 모두에 동시에 적용하지 않는 이유 — 토큰 절감 효과를 분리 측정해야 #7 이 의미를 가짐. ### 3. 호출 흐름 ``` [1] GET /api/meta/capabilities (text/markdown, ~3KB) → 사용 가능한 엔드포인트/심볼/테이블 커버리지 한 번에 흡수 [2] 본격 수집 (liquidity 한정): GET /api/analysis/liquidity-snapshot ← M2/RRP/TGA/WALCL + 순유동성 GET /api/analysis/yield-curve ← 10Y-2Y, 3개월 전 비교, 역전 플래그 GET /api/indicators/{symbol} ← FRED 시리즈 시계열 (M2SL, BAMLH0A0HYM2 등) GET /api/indicators/latest ← 전체 FRED 최신값 일괄 GET /api/prices/{symbol} ← VIX, DXY, BTC, TLT 등 GET /api/margin-debt/recent ← FINRA 마진 부채 [3] WebSearch fallback (capabilities 가 안 알려준 항목): - CME FedWatch 확률 (Fed Funds Futures 자체는 ZQ=F 가격으로 있음, 확률 역산은 미구현) - MMF 잔액 (ICI) - SLOOS, 소비자 심리, 자사주 매입 규모 - QRA 발행 계획, TIC 외국인 흐름 (#9, #10 으로 추적 중) - 지정학 리스크 정량화 ``` **중요**: 위 매핑은 capabilities 응답이 동적이라 **하드코딩 금지**. 스킬 프롬프트에는 "capabilities 응답에 path 가 있으면 API 호출, 없으면 WebSearch" 규칙만 박고, 매핑은 capabilities 가 결정하게 둔다. 새 엔드포인트가 financial-data-platform 에 추가되면 스킬 수정 없이 자동 인지. ### 4. A/B 병행 유지 방법 #7 측정 + 회귀 안전을 위해 두 경로를 모두 유지: - **새 경로** (default-on): capabilities 우선 - **기존 경로** (fallback / off-switch): 환경변수 `MACRO_SKIP_API=1` 또는 `report` 커맨드 인자 `--no-api` 가 있을 때 기존 WebSearch-only 흐름 이 토글은 `macro-scanner.md` 의 Phase 0 직전에 한 줄 분기 추가로 충분. ### 5. 토큰 측정 (#7) 짝지어 진행 스킬 레포 세션에서 #6 끝나면 바로 #7 도 묶어서 처리하는 게 효율적: - A/B 두 경로로 같은 날 같은 데이터 한 번씩 실행 - macro-scanner 가 받은 입력 길이 + Web 응답 토큰 합산 (Read/WebFetch 응답 추정) - 결과를 `D:\source\claude-plugin\macro-report\skills\macro-report-workflow\references\token-savings.md` 같은 곳에 표로 기록 (B/A 절감률 + 항목별 분해) - 통합 로드맵의 핵심 검증 지표 ### 6. 이 레포(financial-data-platform) 쪽에서 추후 검토할 것 스킬 레포 작업 중 발견될 수 있는 후속 — 발견 시 별도 이슈로: - **CME FedWatch 확률 역산**: `ZQ=F` 월물 체인은 이미 수집 중 (#8). 확률 계산만 추가하면 capabilities 에서 새 엔드포인트로 제공 가능 → 스킬 자동 인지 - **MMF / SLOOS / QRA / TIC**: #9, #10, 신규 이슈 후보. 현재 capabilities 가 "데이터 없음" 으로 알리고 스킬이 WebSearch fallback 하는 흐름 정상 동작 — data_gaps 로 자동 기록되도록 #15 진행 시 자연스럽게 통합 - **`/api/analysis/*` 추가 편의 엔드포인트**: 스킬이 자주 같은 시리즈를 묶어 가져온다면 (예: 마진 부채 + GDP 비율 + MoM 변화) 한 번에 주는 엔드포인트 신설 검토. 단, capabilities 디스커버리가 잘 작동한다면 스킬 측에서 단순 조합으로 충분할 가능성 — 측정 결과 보고 결정 ### 7. 시작 명령 (스킬 레포 새 세션에서) ``` D:\source\claude-plugin 으로 작업 디렉토리 변경 후 Claude 세션 시작. 요청 예시: "financial-data-platform 의 #6 작업을 시작해줘. macro-report 의 macro-scanner 를 capabilities 우선 흐름으로 전환. liquidity 보고서 한정, A/B 토글 유지. 진행 가이드는 git.xhhan.com/xhh/financial-data-platform/issues/6 의 댓글 참고." ``` ### 선행/관련 - 선행: #62 (`/api/meta/capabilities` 마크다운 디스커버리, **완료**) - 선행: #14 (`/api/analysis/liquidity-snapshot`, 이미 운영 중) - 짝꿍: #7 (토큰 절감 측정, 같은 세션에서 묶어 처리 권장) - 후행: #15 (data_gaps 피드백 루프 — 스킬 운영 1~2주 데이터 쌓인 뒤)
xhh commented 2026-04-26 14:45:50 +09:00
Author
Owner
Copy link

prod 배포 완료 — 스킬 레포 세션 진입 가능

v0.3.6 태그 빌드가 stock.xhhan.com 에 배포되어 본 작업의 선행 조건이 모두 충족됨. 이전 댓글의 작업 가이드 그대로 시작 가능.

검증된 prod 엔드포인트

$ curl -s https://stock.xhhan.com/api/version
{"version":"0.1.0","tag":"v0.3.6","commit_short":"cf46924","build_time":"2026-04-26T05:44:14Z"}

$ curl -s https://stock.xhhan.com/api/meta/capabilities | head -5
# Investment Research Platform — Capabilities

버전 0.1.0 · 생성 2026-04-26T05:45:24Z

스킬은 이 응답을 컨텍스트로 흡수해 사용 가능한 데이터/엔드포인트를 파악한 뒤 호출하세요. 웹서치 대신 본 API 우선.

다음 단계

D:\source\claude-plugin 에서 새 세션을 열어 이전 댓글의 가이드대로 진행. 시작 프롬프트 예시는 그 댓글에 박아둠.

## prod 배포 완료 — 스킬 레포 세션 진입 가능 **v0.3.6** 태그 빌드가 stock.xhhan.com 에 배포되어 본 작업의 선행 조건이 모두 충족됨. 이전 댓글의 작업 가이드 그대로 시작 가능. ### 검증된 prod 엔드포인트 ```bash $ curl -s https://stock.xhhan.com/api/version {"version":"0.1.0","tag":"v0.3.6","commit_short":"cf46924","build_time":"2026-04-26T05:44:14Z"} $ curl -s https://stock.xhhan.com/api/meta/capabilities | head -5 # Investment Research Platform — Capabilities 버전 0.1.0 · 생성 2026-04-26T05:45:24Z 스킬은 이 응답을 컨텍스트로 흡수해 사용 가능한 데이터/엔드포인트를 파악한 뒤 호출하세요. 웹서치 대신 본 API 우선. ``` ### 다음 단계 `D:\source\claude-plugin` 에서 새 세션을 열어 이전 댓글의 가이드대로 진행. 시작 프롬프트 예시는 그 댓글에 박아둠.
xhh commented 2026-04-26 15:44:13 +09:00
Author
Owner
Copy link

PR 머지 완료 — 검증 후속 세션 예정

claude-plugin 측 시범 전환 작업이 #1 으로 머지됨 (squash, v1.4.0). 본 이슈에 명시된 가이드 그대로 적용:

  • liquidity 한정 capabilities 우선 경로
  • 사전 매핑 금지 — Phase 0.5 응답이 매번 결정
  • A/B 토글 (--no-api, MACRO_SKIP_API=1) 유지
  • capabilities 호출 자체 실패 시 자동 degrade
  • ## 수집 메타 섹션으로 #7 측정 데이터 기록

다음 단계 — 별도 세션에서 검증:

  • B 모드 1회 실행 (/macro-report:report liquidity)
  • A 모드 1회 실행 (/macro-report:report liquidity --no-api)
  • claude-plugin/macro-report/skills/macro-report-workflow/references/token-savings.md 측정표에 첫 페어 기록
  • 위 결과를 본 이슈 또는 #7 에 댓글로 정리 → 본 이슈 close

후속 작업 (스킬 → reports 업로드 통합, c) 은 별도 메타 이슈 #67 와 elhaz/claude-plugin#2 에서 추적.

## PR 머지 완료 — 검증 후속 세션 예정 claude-plugin 측 시범 전환 작업이 [#1](https://github.com/elhaz/claude-plugin/pull/1) 으로 머지됨 (squash, v1.4.0). 본 이슈에 명시된 가이드 그대로 적용: - `liquidity` 한정 capabilities 우선 경로 - 사전 매핑 금지 — Phase 0.5 응답이 매번 결정 - A/B 토글 (`--no-api`, `MACRO_SKIP_API=1`) 유지 - capabilities 호출 자체 실패 시 자동 degrade - `## 수집 메타` 섹션으로 #7 측정 데이터 기록 **다음 단계 — 별도 세션에서 검증**: - [ ] B 모드 1회 실행 (`/macro-report:report liquidity`) - [ ] A 모드 1회 실행 (`/macro-report:report liquidity --no-api`) - [ ] `claude-plugin/macro-report/skills/macro-report-workflow/references/token-savings.md` 측정표에 첫 페어 기록 - [ ] 위 결과를 본 이슈 또는 #7 에 댓글로 정리 → 본 이슈 close **후속 작업 (스킬 → reports 업로드 통합, c)** 은 별도 메타 이슈 [#67](https://git.xhhan.com/xhh/financial-data-platform/issues/67) 와 [elhaz/claude-plugin#2](https://github.com/elhaz/claude-plugin/issues/2) 에서 추적.
xhh commented 2026-04-26 21:08:47 +09:00
Author
Owner
Copy link

첫 A/B 페어 측정 완료 (2026-04-26 liquidity)

claude-plugin v1.4.0 검증 세션에서 페어 1쌍 실행 완료.

결과 요약

메트릭 B 모드 (capabilities ON) A 모드 (--no-api) 차이
Scanner 총 토큰 79,767 90,143 -11.5%
소요 시간 357s 488s -26.8%
Tool 호출 42 46 -8.7%
API 호출 14 0 —
Web 검색 14 22 -36.4%
scan_data 크기 20.0 KB 19.0 KB +5.3%
  • 속도 절감 (-26.8%) 이 토큰 절감 (-11.5%) 보다 두드러짐. API 결정적 응답 vs WebSearch 직렬 지연.
  • B 모드가 정량값 정확 (RRP $0.082M, TGA $1.006조). A 는 보수적 추정.
  • B 모드 보고서 종합 점수 72.4 / A 모드 65.79 — 데이터 정확도 차이가 점수에 반영.

산출물

  • 측정표 갱신 PR: elhaz/claude-plugin#3
  • B 모드 보고서: xvault/02_Areas/.../2026-04-26 유동성 환경 분석.md
  • A 모드 보고서: xvault/02_Areas/.../2026-04-26 유동성 환경 분석 (A모드).md

부수 발견

API 함정 1건 — /api/indicators/{symbol}?limit=N 단독 호출 시 1959년 데이터 반환. start_date 명시 필수. 별도 이슈 #69 로 분리.

본 이슈 close 조건 점검

  • B 모드 1회 실행
  • A 모드 1회 실행
  • token-savings.md 첫 페어 기록 (PR #3, 머지 대기)
  • 본 이슈에 결과 코멘트

PR #3 머지 후 close 가능.

## 첫 A/B 페어 측정 완료 (2026-04-26 liquidity) claude-plugin v1.4.0 검증 세션에서 페어 1쌍 실행 완료. ### 결과 요약 | 메트릭 | B 모드 (capabilities ON) | A 모드 (--no-api) | 차이 | |--------|---:|---:|:---:| | Scanner 총 토큰 | 79,767 | 90,143 | **-11.5%** | | 소요 시간 | 357s | 488s | **-26.8%** | | Tool 호출 | 42 | 46 | -8.7% | | API 호출 | 14 | 0 | — | | Web 검색 | 14 | 22 | -36.4% | | scan_data 크기 | 20.0 KB | 19.0 KB | +5.3% | - **속도 절감 (-26.8%)** 이 토큰 절감 (-11.5%) 보다 두드러짐. API 결정적 응답 vs WebSearch 직렬 지연. - B 모드가 정량값 정확 (RRP $0.082M, TGA $1.006조). A 는 보수적 추정. - B 모드 보고서 종합 점수 72.4 / A 모드 65.79 — 데이터 정확도 차이가 점수에 반영. ### 산출물 - 측정표 갱신 PR: [elhaz/claude-plugin#3](https://github.com/elhaz/claude-plugin/pull/3) - B 모드 보고서: `xvault/02_Areas/.../2026-04-26 유동성 환경 분석.md` - A 모드 보고서: `xvault/02_Areas/.../2026-04-26 유동성 환경 분석 (A모드).md` ### 부수 발견 API 함정 1건 — `/api/indicators/{symbol}?limit=N` 단독 호출 시 1959년 데이터 반환. `start_date` 명시 필수. 별도 이슈 #69 로 분리. ### 본 이슈 close 조건 점검 - [x] B 모드 1회 실행 - [x] A 모드 1회 실행 - [x] token-savings.md 첫 페어 기록 (PR #3, 머지 대기) - [x] 본 이슈에 결과 코멘트 PR #3 머지 후 close 가능.
xhh commented 2026-04-26 21:13:35 +09:00
Author
Owner
Copy link

Close — 모든 조건 충족

  • B 모드 1회 실행 → 2026-04-26 유동성 환경 분석.md
  • A 모드 1회 실행 → 2026-04-26 유동성 환경 분석 (A모드).md
  • token-savings.md 첫 페어 기록 — elhaz/claude-plugin#3 squash 머지 (6577386)
  • 결과 코멘트 — 본 이슈 + #7

후속:

  • API 함정은 #69 로 분리
  • 페어 누적·평균 절감률 산출은 #7 에서 추적
## Close — 모든 조건 충족 - [x] B 모드 1회 실행 → `2026-04-26 유동성 환경 분석.md` - [x] A 모드 1회 실행 → `2026-04-26 유동성 환경 분석 (A모드).md` - [x] token-savings.md 첫 페어 기록 — [elhaz/claude-plugin#3](https://github.com/elhaz/claude-plugin/pull/3) squash 머지 (`6577386`) - [x] 결과 코멘트 — 본 이슈 + #7 후속: - API 함정은 #69 로 분리 - 페어 누적·평균 절감률 산출은 #7 에서 추적
xhh closed this issue 2026-04-26 21:13:35 +09:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
v0.4.0
v0.3.6
v0.3.5
v0.3.4
v0.3.3
v0.3.2
v0.3.1
v0.3.0
v0.2.0
v0.1.2
v0.1.1
v0.1.0
v0.0.1-test
Labels
Clear labels   
api
FastAPI 관련

  
bug
버그

  
chore
잡다한 정리

  
collector
데이터 수집기

  
decision-needed
의사결정 필요

  
docs
문서

  
enhancement
기존 기능 개선

  
feature
새 기능

  
feedback-loop
피드백 루프

  
frontend
프론트엔드 (Streamlit, Admin UI)

  
infra
Docker/CI/CD

  
skill
Claude 스킬

  
test
테스트 코드/회귀 방지

No labels
api
bug
chore
collector
decision-needed
docs
enhancement
feature
feedback-loop
frontend
infra
skill
test
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
xhh/financial-data-platform#6
No description provided.