웹 시황 대시보드

다른 캡스톤처럼 빈 폴더에서 superpowers 워크플로로 설계하고 Phase 단위로 빌드합니다. 다른 점은 일하는 방식입니다. 조사, 구현, 리뷰를 서브에이전트에게 나눠 맡기고, 참가자는 짧게 지시한 뒤 결과를 대조합니다. 목표물은 실존 프로젝트 stock-monitoring(FastAPI + React + Bedrock, AWS ECS 운영)을 135분 스코프로 줄인 웹 시황 데스크입니다. 실데이터이며 45초마다 바뀝니다.

1. Dashboard (메인 화면)

2. StockDetail (종목 상세)

이 캡스톤을 마치면 다음 다섯 가지를 설명할 수 있고, 다시 만들 수 있습니다.

이 캡스톤은 새 기술을 가르치지 않습니다. Ch1~6에서 배운 것을 실전 배치합니다.

원작 stock-monitoring(2026.09 기준)의 실코드에서 뽑은 정답지입니다. M1에서 서브에이전트가 돌려준 docs/blueprint.md를 이 표와 대조하고, 빠진 항목이 있으면 한 문장으로 보충을 지시하세요. 계획이 이상하게 흐를 때도 여기로 돌아옵니다.

[폴링 경로]  45초마다 (장 마감 시 600초)
Browser ── react-query ──> FastAPI ──> TTL Cache ──(miss, single-flight)──> yfinance (US + KR .KS/.KQ)
   ^                          |            |
   +──── JSON 완결 응답 ──────+      (hit) 즉시 반환, 업스트림 무호출

[스트리밍 경로]  버튼 눌렀을 때만
Browser ── fetch(SSE) ──> FastAPI ── converse_stream ──> Bedrock (Sonnet 4.6)
   ^                          |
   +── phase → delta* → final +   (한 글자씩, react-query를 쓰지 않는 유일한 경로)

Level 200의 핵심 구분입니다: 완결된 결과를 주기적으로 당기는 경로(폴링)와 부분 결과를 밀어 받는 경로(스트리밍)는 캐시 전략도, 프런트 도구도 다릅니다. 이 캡스톤은 둘을 한 앱에서 병용합니다.

워크샵 스코프는 핵심 구성만: MarketStrip + StockTable + StockHeader + PriceChart(캔들) + ReturnsRow + Week52Bar + AIPanel. 나머지는 퀄리티 강화 라운드의 카드로 남깁니다.

Python과 Node 확인, 프로젝트 폴더, 원작 참고본, 그리고 Bearer 키(.env)까지 준비합니다. 키는 Phase 4의 AI 스트리밍에 필요합니다.

python3 --version && node --version    # Python 3.11+, Node 20+
mkdir -p ~/capstone/capstone-2/.claude/agents && cd ~/capstone/capstone-2
git init -q 2>/dev/null; git config user.name "capstone"; git config user.email "capstone@lab.local"
[ -d ~/capstone/ref/stock-monitoring ] || git clone -q --depth 1 https://github.com/whchoi98/stock-monitoring ~/capstone/ref/stock-monitoring
ls ~/capstone/ref/stock-monitoring    # backend  docs  frontend  infra ...

~/capstone/ref/stock-monitoring은 M1에서 서브에이전트가 읽을 원작 참고본입니다. 프로젝트 폴더 밖에 두어 내 git 이력과 섞이지 않게 합니다. .claude/agents를 세션 시작 전에 만들어 두면 M1에서 만드는 서브에이전트를 세션 재시작 없이 인식합니다.

다른 캡스톤에서 이미 만들었다면 ~/capstone/.env가 있으니 1/2는 건너뛰세요.

mkdir -p ~/capstone
grep -q AWS_BEARER_TOKEN_BEDROCK ~/capstone/.env 2>/dev/null || cat >> ~/capstone/.env << 'ENVEOF'
AWS_BEARER_TOKEN_BEDROCK=<발급받은 Bedrock API 키>
ENVEOF

set -a; source ~/capstone/.env; set +a
aws bedrock-runtime converse \
  --region ap-northeast-2 \
  --model-id global.anthropic.claude-sonnet-4-6 \
  --messages '[{"role":"user","content":[{"text":"ping"}]}]' \
  --inference-config '{"maxTokens":30}' \
  --query 'output.message.content[0].text' --output text

서브에이전트 두 개가 원작을 병렬로 읽어 청사진과 config를 돌려주면, 그것을 바탕으로 짧은 프롬프트 하나로 설계합니다.

이 미션의 바탕 학습: Ch2 Task 디스패치의 병렬 호출 패턴과 Capstone Setup의 superpowers 워크플로.

cd ~/capstone/capstone-2 && claude --add-dir ~/capstone/ref/stock-monitoring

--add-dir는 프로젝트 밖의 원작 폴더를 이 세션의 작업 범위에 넣습니다 (Reference 2). 서브에이전트가 원작 파일을 읽을 때마다 권한 확인이 뜨지 않습니다.

~/capstone/ref/stock-monitoring 에 원작 시황 대시보드가 있어. Explore 서브에이전트 두 개를 병렬로 띄워 조사해 줘.
- 하나는 구조, API 라우트, 화면 구성, 캐시와 AI 스트리밍 방식을 요약
- 하나는 backend/app/core/config.py에서 지수, 종목(미국 100, 한국 100, 한글명과 섹터 포함), 경제지표 상수를 추출
요약은 docs/blueprint.md로, 상수는 backend/app/core/config.py로 저장하고 커밋해 줘. 코드는 참고만 하고 옮기지 마.

두 서브에이전트는 백그라운드로 돕니다. 기다리는 동안 다음 입력으로 리뷰어를 미리 만들어 둡니다. 이 리뷰어는 M2~M4에서 계속 씁니다.

조사가 도는 동안 이 프로젝트에 code-reviewer 서브에이전트를 만들어 줘.
도구는 읽기 전용(Read, Grep, Glob, git diff)만 주고, 버그와 캐시 동시성 문제 중 확신이 높은 것만 보고하게. 만들고 커밋해 줘.

/superpowers:brainstorming docs/blueprint.md를 바탕으로 원작을 135분 버전으로 줄인 "Market Desk on Web"을 설계하자.
범위는 대시보드, 종목 상세(캔들 차트), AI 분석 스트리밍까지. 화면은 원작의 터미널 UI를 따르고 종목은 시장별 20개만 켜.
배포와 테스트는 생략하고 curl과 브라우저로 검증한다. 결정이 필요하면 최소한으로만 물어봐.

브레인스토밍이 끝나면 아래 한 줄로 계획을 만들고 Phase 4개 구성을 승인하세요. 계획 끝에 실행 방식을 묻는 질문이 나오면 Subagent-Driven을 고릅니다. 태스크마다 새 서브에이전트가 구현하고, 태스크 사이에 리뷰가 붙는 방식입니다.

/superpowers:writing-plans Phase 4개로 나눠 줘: 백엔드 코어, 대시보드, 종목 상세, AI 스트리밍과 통합 서빙.

FastAPI가 overview / quotes / 종목 상세 / 차트를 캐시 뒤에서 돌려주면 이 Phase는 끝입니다. 구현은 서브에이전트가, 리뷰는 M1에서 만든 code-reviewer가 맡습니다.

이 미션의 바탕 학습: Ch1의 지시 → 실행 → 검증 루프, Ch2의 명시적 호출 패턴.

/superpowers:subagent-driven-development 계획의 Phase 1만 진행하고 멈춰줘. 끝나면 uvicorn 실행과 curl 검증 방법을 알려줘.

cd backend && .venv/bin/uvicorn app.main:app --port 8000 &
sleep 3
curl -s localhost:8000/api/market/overview | head -c 300; echo
time (curl -s "localhost:8000/api/market/quotes?market=kr" | head -c 200; echo)
time (curl -s "localhost:8000/api/market/quotes?market=kr" | head -c 200; echo)   # 두 번째는 캐시로 즉시
curl -s "localhost:8000/api/stocks/AAPL/chart?period=1m" | head -c 200; echo

라우트 모양이 이 명령과 조금 다르게 설계됐다면 Claude가 알려 준 검증 명령을 쓰세요. 중요한 것은 두 번째 quotes 호출이 즉시 오는지입니다.

code-reviewer 서브에이전트로 캐시 모듈을 리뷰해 줘. 지적마다 맞는지 직접 확인하고, 확인된 것만 고쳐서 커밋해.

import time, threading
_store, _locks = {}, {}
def get_or_fetch(key: str, ttl: int, fetch):
    now = time.time()
    hit = _store.get(key)
    if hit and now - hit[0] < ttl:
        return hit[1]
    lock = _locks.setdefault(key, threading.Lock())
    with lock:                       # 같은 키 동시 요청은 한 번만
        hit = _store.get(key)
        if hit and time.time() - hit[0] < ttl:
            return hit[1]
        val = fetch()
        _store[key] = (time.time(), val)
        return val

React 대시보드가 45초마다 숨 쉬고, 종목을 클릭하면 캔들 차트가 있는 상세 화면이 열립니다.

이 미션의 바탕 학습: Ch2의 자동 디스패치 패턴. 이번에는 리뷰어 이름을 부르지 않아도 메인이 description을 보고 code-reviewer를 고릅니다.

/superpowers:subagent-driven-development Phase 2(대시보드)를 진행하고 멈춰줘. 끝나면 dev 서버 실행 방법을 알려줘.

cd frontend && npm run dev   # 브라우저에서 /proxy/5173/

/superpowers:subagent-driven-development Phase 3(종목 상세)를 진행하고 멈춰줘.

지금까지의 프런트 변경 사항을 리뷰해 줘

화면이 원작과 다르게 느껴지면 스펙을 새로 쓰지 말고 원작을 다시 읽게 하세요. 서브에이전트가 원작의 규칙을 찾아오고, 메인은 우리 구조에 맞춰 반영합니다.

종목 테이블이 원작보다 밋밋해. Explore 서브에이전트로 원작 StockTable과 tokens.css를 확인하고, 우리 테이블을 그 규칙에 맞춰 줘.

분석 버튼을 누르면 Bedrock의 답이 한 글자씩 흘러드는 것, 이 캡스톤의 하이라이트입니다.

이 미션의 바탕 학습: Ch3에서 본 Bedrock 라우팅과 자격의 배경, 그 위에서 도는 스트리밍 계약.

/superpowers:subagent-driven-development Phase 4(AI 스트리밍과 통합 서빙)를 진행해 줘. 키는 환경변수 AWS_BEARER_TOKEN_BEDROCK을 쓰고, 키가 없으면 AI 패널만 꺼지게.

set -a; source ~/capstone/.env; set +a   # Bearer 키 로드
make run    # 프론트 빌드 → :8000 통합 서빙, 브라우저에서 /proxy/8000/

code-reviewer로 이번 작업 전체를 마지막으로 리뷰해 줘. 확인된 문제만 고치고 make run으로 다시 띄운 뒤 커밋해.

대시보드 → 종목 상세 → 분석 스트리밍까지 한 바퀴 돌리고, 흐르는 화면의 스크린샷을 Slack에 공유하세요. 그게 배포입니다. 원작은 여기에 계층형 캐시(DynamoDB L2)와 ECS Fargate 배포까지 얹혀 운영 중입니다, 다음 단계가 궁금하다면 그 방향입니다. 그리고 Ch5의 헤드리스 패턴으로 /api/health 스모크를 파이프라인화하면 운영의 첫 발입니다.

핵심 구성이 돌았다면 이제 데스크를 내 것으로 만드는 시간입니다. 강화 카드는 모두 원작에 실제로 있는 기능입니다. 요령은 M1과 같습니다: 원작 구현은 서브에이전트가 읽고, 참가자는 기능 이름과 조건 한 줄만 말합니다. 한 번에 하나, 화면으로 확인하고, 마음에 들면 커밋.

원작의 [기능 이름]이 어떻게 구현됐는지 Explore 서브에이전트로 확인해 줘.
우리 구조에 맞게 줄인 계획을 먼저 보여 주고, 승인하면 구현해. [지킬 조건 한 줄]

원작의 종목 검색(SymbolSearch, ⌘K)이 한글명과 초성을 어떻게 맞추는지 Explore 서브에이전트로 확인해 줘.
우리 구조에 맞게 줄인 계획을 먼저 보여 주고, 승인하면 구현해. "ㅅㅅㅈㅈ"로 삼성전자가 나와야 해.

원작의 관심 종목 ★과 가격 알림이 어떻게 구현됐는지 Explore 서브에이전트로 확인해 줘.
우리 구조에 맞게 줄인 계획을 먼저 보여 주고, 승인하면 구현해. 사용자 상태는 원작처럼 브라우저 localStorage에만 둬.

원작 PriceChart의 MA5/MA20, 볼린저 밴드, RSI, MACD가 어떻게 구현됐는지 Explore 서브에이전트로 확인해 줘.
우리 구조에 맞게 줄인 계획을 먼저 보여 주고, 승인하면 구현해. 보조 패널은 크로스헤어를 공유하게.

원작 AIPanel의 자유 질문이 어떻게 구현됐는지 Explore 서브에이전트로 확인해 줘.
우리 구조에 맞게 줄인 계획을 먼저 보여 주고, 승인하면 구현해. 질문은 1~200자, 프롬프트 안에서 구분자로 격리해.

원작의 호가창(OrderBook)과 투자자 동향(InvestorPanel)이 어떻게 구현됐는지 Explore 서브에이전트로 확인해 줘.
우리 구조에 맞게 줄인 계획을 먼저 보여 주고, 승인하면 구현해. 시뮬레이션 데이터는 응답에 "simulated": true를 붙여.

원작의 종목 뉴스(StockNews)와 기사 분석(ArticleAnalysis)이 어떻게 구현됐는지 Explore 서브에이전트로 확인해 줘.
우리 구조에 맞게 줄인 계획을 먼저 보여 주고, 승인하면 구현해. 기사 본문 조회에는 원작의 SSRF 가드를 꼭 넣어.

여기부터는 정해진 카드가 없습니다. 당신이 프로덕트 오너입니다. 원작에 있는 기능(섹터 등락 바, 라이트 테마, 설치형 PWA)은 위의 이식 틀로, 원작에 없는 기능(지표 스파크라인, 등락률 순위 하이라이트 등)은 아래처럼 brainstorming으로 시작하세요.

/superpowers:brainstorming 내 데스크에 [내가 원하는 기능]을 추가하고 싶어.
기존 캐시, 폴링, 스트리밍 계약은 깨지 않는 선에서 설계하고, 결정은 최소한으로만 물어봐.

Phase 빌드가 끝났다면 이제 바이브 코딩입니다: 완성 화면의 묘사를 주고 "이렇게 나오게 해줘"를 반복하는 루프. 아래 세 장면은 원작이 실제로 도달한 터미널 화면을 글로 옮긴 것입니다. 내 화면과 다른 점을 찾아 하나씩 주문하세요.

- 상단 sticky 마켓 스트립: 지수 5종과 지표가 한 줄로 흐르고, 등락은 상승 빨강 ▲ / 하락 파랑 ▼
- 패널 그리드: 위젯마다 1px 테두리와 6px 라운드 패널, 헤더는 대문자 영문 eyebrow + 한국어 제목
- 종목 테이블: US/KR 탭, 숫자와 심볼은 고정폭 서체로 우측 정렬, 행 호버 하이라이트, 선택은 앰버
- 하단 상태 바: 장 상태 점(초록은 상태 전용), 폴링 주기, KST 시계

- StockHeader: 심볼과 이름, 현재가 크게, 등락은 색 + ▲▼, 거래량은 축약(1.2M)
- 캔들 차트: 기간 탭(1W/1M/3M/6M/1Y/5Y) 중 활성 탭은 앰버, 상승 빨강/하락 파랑 캔들, 크로스헤어
- ReturnsRow: 기간 수익률이 한 줄에, 양수 빨강/음수 파랑
- Week52Bar: 52주 저가~고가 바 위에 현재가 마커
- 확장 후보(원작에 있는 것): 워치리스트 레일, 호가창 OrderBook, 투자자 동향 InvestorPanel, 종목 뉴스 StockNews,
  기사 AI 분석 ArticleAnalysis - 끌리는 것 하나를 강화 카드의 이식 틀로 추가

- 분석 버튼(앰버)을 누르면 phase 배지가 fetching → analyzing 으로 바뀌고
- 본문은 delta가 도착하는 대로 타자기처럼 자라며, 마크다운(## 절, 굵은 키워드)이 살아 있다
- 스트리밍 중 다시 누르면 진행 중인 요청을 취소하고 새로 시작
- 키가 없을 때는 "AI 분석 비활성" 안내만 조용히

지금까지 만든 것은 결과물입니다. 이 옵션은 그 결과물을 만든 작업 환경, 즉 하네스 (CLAUDE.md, hooks, skills, commands, agents)를 표준 구조로 성숙시키고(project-init), 그 품질을 6개 차원(정확성, 안전성, 완전성, 실행 가능성, 일관성, 검증 가능성)에서 채점받는(harness-eval) 단계입니다. superpowers의 3단(brainstorm, writing-plans, executing-plans) 뒤에 4단 성숙화와 5단 평가를 붙이는 셈입니다. 캡스톤 공통의 마무리 의식입니다.

이 미션의 바탕 학습: Ch4의 훅과 스킬을 팀 자산으로 승격하는 감각, 그리고 Reference 3의 플러그인 생태계.

claude plugin marketplace add https://github.com/whchoi98/project-init
claude plugin install project-init@project-init
claude plugin marketplace add https://github.com/whchoi98/harness-eval
claude plugin install harness-eval@harness-eval
claude plugin list

설치 후 새 Claude 세션을 시작하세요, superpowers 때와 같은 규칙입니다.

/project-init:init-project .

이 프로젝트의 하네스는 아직 얇습니다(FastAPI 앱과 React 앱 하나씩). 기존 프로젝트 감지 모드가 있는 것은 보존하고, 없는 것(문서 스캐폴딩, 시크릿 스캔 훅, /review 커맨드, 테스트 골격 등)만 채웁니다. CLAUDE.md가 이미 있으면 덮어쓰기 전에 물어봅니다. 끝나면 이어서:

/project-init:sync-docs

## Sync Report
### Quality Scores (Before -> After)
| ./CLAUDE.md           | D (48) | B (82) | +34 |
| ./backend/CLAUDE.md   | F (10) | C (61) | +51 |
### Changes Made
- Files created: 4 / Files updated: 2 / Runbooks missing: 1

/harness-eval:quick

{"mode": "quick", "scores": {"overall": 7.0, "grade": "B"}, "checklist": {"pass": 12, "warn": 3, "fail": 1}}

이 캡스톤의 비자명한 지식은 스트리밍 계약입니다. "왜 AI만 fetch를 직접 쓰는가, 왜 장 마감엔 600초로 늦추는가"를 CLAUDE.md의 패턴으로 기록해 두면 sync-docs 점수가 오르고, 다음에 이 저장소를 여는 Claude가 같은 원칙으로 확장합니다. 여유가 있다면 결정을 기록으로 남기세요:

/add-adr streaming-ai-contract
/add-runbook market-web-run