클로드코드(Claude Code)로 주식 분석 웹 서비스 만들기 : #3. 웹 페이지 만들기

 

 

 

 

 

Claude Code 활용 프로젝트 · #3

Claude Code로 주식 분석 웹 서비스 만들기
— 개발 착수, 서버 실행까지

2026.05  ·  비전공자 공정 엔지니어의 Claude Code 실전 연습

PRD와 개발계획서를 완성했으니 이제 실제로 코드를 만들 차례다. Claude Code에 문서 경로 하나 던져주는 것만으로 프로젝트 전체가 뚝딱 생성되는 경험은, 처음 해보면 꽤 당황스럽다. 이번 글에서는 폴더 트리 생성부터 프론트·백엔드 서버를 한 번에 켜고 끌 수 있는 실행 파일 제작, 그리고 실제 데이터가 화면에 뜨는 순간까지의 과정을 정리했다.

이전 글 → 클로드코드(Claude Code)로 주식 분석 웹 서비스 만들기 : #2. PRD, 개발계획서 작성하기

01 개발 착수 — PRD 경로 하나로 시작한다

Claude Code에 아래 한 줄을 입력하면 된다. docs 폴더에 저장해둔 PRD와 개발계획서를 읽고, Claude가 src 폴더 안에 전체 폴더 트리를 알아서 구성한다.

Claude Code 프롬프트

# 본인의 실제 경로로 교체할 것
> D:\Dev\Asset_insight\docs 의 stock_dev_plan 와 stock_analyzer_PRD 를 따라
  개발을 진행해줘. src폴더 안에 폴더트리를 생성해주고,
  개인 PC 환경이고 동시 진행 프로젝트가 없어서 docker는 불필요해

폴더 구조 관례 — 프로젝트 루트 아래에 docs(문서류), prompt(대화 이력 메모), src(소스코드) 세 폴더를 만드는 방식을 쓴다. 프롬프트는 바로 입력창에 치기보다 메모장에 먼저 작성한 뒤 붙여넣는 편이 수정이 편하다.

Docker를 빼달라고 명시한 이유는 간단하다. 개인 연습 프로젝트에서 컨테이너 환경까지 구성하는 건 오버스펙이다. 물론 라이브러리 버전 충돌 방지가 필요하다면 사용하는 게 맞다.

 

Claude Code가 PRD를 읽고 백엔드 구조부터 차례로 파일을 생성하는 모습

생성 완료 후 출력된 전체 구조 요약 — FastAPI(백엔드) + Next.js 14(프론트엔드)

02 생성된 프로젝트 구조

Claude가 만들어낸 결과물은 아래 두 축으로 나뉜다.

src/backend — FastAPI + Python

main.py, config.py, database.py, models, schemas, api, services(키움 클라이언트·수집기·분석기·스케줄러), utils 로 구성. APScheduler로 1분/5분 주기 데이터 수집.

src/frontend — Next.js 14 + TailwindCSS

app/layout.tsx, page.tsx, stock/[code], components(RecommendCard, RankingTable, CandleChart), lib(api.ts, format.ts) 로 구성.

파일/디렉토리	역할
services/kiwoom_client.py	키움 REST API 클라이언트 — 토큰 자동 관리
services/collector.py	데이터 수집 → DB 적재
services/analyzer.py	교집합 분석 + 가중 점수 산정 (조회 30% / 외국인 40% / 기관 30%)
services/scheduler.py	APScheduler (1분/5분 주기)
utils/market_hours.py	장 시간 판별 (09:00~15:30, 주말 제외)
alembic/	DB 마이그레이션

03 꿀팁 — start.bat / stop.bat 자동 실행 파일

매번 터미널 두 개 열고 백엔드·프론트엔드 명령어를 따로 치는 건 금방 지친다. 디버깅을 수십 번 반복한다고 생각하면 더욱 그렇다. 아래 프롬프트로 실행 파일을 한 번에 만들면 이후 작업이 훨씬 편해진다.

 

한글 경로 대응, install 포함, 실행 테스트까지 — 세 가지 조건이 핵심이다

Claude Code 프롬프트

> Root 폴더에 Front, Backend 서버를 한번에 키고 끌 수 있는
  start.bat, stop.bat 프로그램을 만들어줘. 이 때 아래 항목을 반영해줘.
  1. 한글경로에 문제 없도록 셋팅
  2. install 포함
  3. 실제 정상 실행 여부 테스트까지 마칠 것

세 가지 조건이 중요한 이유 — 한글 경로 처리를 빠뜨리면 인코딩 오류가 발생하고, install을 포함하지 않으면 라이브러리 누락으로 첫 실행이 실패한다. 실행 테스트 조건을 넣으면 Claude가 bat 파일 생성 후 실제로 돌려보고 오류를 스스로 수정한다.

DBMS 계정 정보를 이 시점에 함께 전달하면 대화 한 번을 아낄 수 있다. 필자는 연습용 프로젝트이므로 별도 계정 없이 PostgreSQL 슈퍼유저 postgres를 그대로 사용했다.

명령이 완료되면 루트 폴더에 start.bat과 stop.bat이 생성된다.

 

docs / prompt / src 폴더와 함께 루트에 생성된 실행 파일들

04 서버 실행 및 접속

start.bat을 실행하면 프론트·백엔드 서버가 동시에 뜬다. 터미널 창이 두 개 열리고, 프론트엔드 창의 Local 주소로 접속하면 된다. 필자는 3000, 3001 포트를 다른 프로젝트가 이미 점유하고 있어 3002번으로 지정했다.

start.bat 실행

→

프론트 + 백엔드 서버 동시 기동

→

http://localhost:3002 접속

왼쪽 Next.js 14 프론트엔드(포트 3002), 오른쪽 FastAPI + uvicorn 백엔드(포트 8002) 동시 기동

장 종료 후 접속 시 — 데이터 없음으로 표시되는 것은 정상이다

처음 접속 시 화면이 비어 있다면 당황하지 않아도 된다. 실시간 데이터를 수집하는 구조라 장이 끝난 시간에는 데이터가 없다. 날짜와 시간을 직접 입력해 조회하면 정상적으로 데이터가 표시된다.

날짜·시간 입력 후 조회 — 매수 추천 Top 10과 조회·외국인·기관 순위 데이터가 정상 출력된다

StockRadar 메인 화면 — 매수 추천 Top 10 카드 + 3열 랭킹 테이블 레이아웃

05 여기까지의 흐름 정리

1. 01 PRD + 개발계획서 작성 — 이전 글에서 완료. docs 폴더에 저장.
2. 02 Claude Code에 개발 지시 — docs 경로와 함께 "docker 불필요" 조건 전달. 전체 폴더 트리 자동 생성.
3. 03 start.bat / stop.bat 생성 — 한글 경로, install 포함, 실행 테스트 세 조건 명시. 이후 디버깅 효율 대폭 향상.
4. 04 서버 실행 및 확인 — start.bat 더블클릭 → localhost 접속 → 날짜·시간 입력 후 데이터 확인.

다음 목표 — 기본 뼈대는 완성됐다. 앞으로는 각종 알고리즘 기반 차트 분석 기능을 추가하고, Local LLM을 연동해 실시간 AI 분석까지 붙이는 것이 최종 목표다.

Summary

PRD 문서 경로 하나와 세 가지 조건(한글 경로, install 포함, 실행 테스트)만 잘 챙기면, Claude Code가 FastAPI + Next.js 풀스택 프로젝트를 뼈대부터 실행 파일까지 완성해준다. 장황한 환경 설정 없이 바로 기능 개발에 집중할 수 있다는 것이 코딩 에이전트 활용의 핵심 장점이다.