🔗 사이트: https://dlwldp.github.io/Awscal/ 🔗 GitHub: https://github.com/dlwldP/Awscal 📝 1편: 초보자용 AWS 비용 계산기를 만들었다 (MVP · 직접 계산기 · 토스 스타일 디자인) 📝 2편: 기능을 더하다가, 덜어내는 법을 배웠다 📝 3편: 숫자를 검증하고, 화면을 비우고, 피드백 하나를 기능으로

3편까지는 "덜어내기"가 주제였다. 4편은 두 갈래다. 먼저 글자 자체를 읽기 쉽게 다듬었고, 그다음 미뤄두던 v2 마일스톤 이슈 4개를 모두 끝냈다.

기능을 네 개나 넣으면서도 2편에서 정한 질문은 계속 붙들고 있었다. "이게 처음 AWS를 쓰는 사람한테 꼭 필요한가?" 그래서 새 기능은 전부 눌러야 보이는 곳에 두었다.

1. 기능 말고, 글자부터

화면을 휴대폰으로 다시 띄워서 "덜어낼 것"이 아니라 "읽기 어려운 것"을 찾았다. 숫자로 확인되는 문제가 몇 개 나왔다.

회색 설명 글씨가 너무 연했다

설명 글씨 색(#8b95a1)이 흰 배경에서 대비 약 3:1이었다. 웹 접근성 기준(WCAG AA)은 작은 글씨에 4.5:1 이상을 권한다. 회색 배경인 꼬리말에서는 2.7:1까지 내려갔다.

문제는 이 연한 색이 초보자에게 가장 중요한 설명에 쓰이고 있었다는 점이다. 놓치기 쉬운 비용의 한 줄 설명, 입력 칸 도움말, 템플릿 설명이 모두 이 색이었다.

색 변수 한 줄만 바꾸면 사이트 전체에 적용된다. 처음부터 색을 CSS 변수로 만들어 둔 덕을 여기서 또 봤다. 다크 모드 값도 같이 맞췄다.

글자 크기가 30가지였다

결과 화면 한 장에 글자 크기·굵기 조합이 30가지 정도 쓰이고 있었다. 기능을 붙일 때마다 그때그때 0.88rem, 0.9rem, 0.92rem… 하고 정한 결과다. 비슷한 크기가 섞여 있으면 무엇이 제목이고 무엇이 본문인지 흐려진다.

--fs-amount: 2rem;     /* 32px 큰 금액 */
--fs-title: 1.625rem;  /* 26px 페이지 제목 */
--fs-card: 1.125rem;   /* 18px 카드 제목 */
--fs-body: 0.9375rem;  /* 15px 본문 */
--fs-small: 0.875rem;  /* 14px 보조 설명 */

다섯 단계로 정하고 CSS의 모든 font-size를 이 변수로 바꿨다. 12~13px이던 도움말·배지·부가세 표시는 14px로 커졌다. 아이콘·화살표와 입력 칸은 건드리지 않았다. 입력 칸이 16px보다 작으면 아이폰이 화면을 확대해버리기 때문이다.

나머지 다듬기

• 카드 안 소제목: "이 금액에 들어 있어요" 같은 소제목이 본문보다 연해서 오히려 묻혀 있었다. 진한 색으로 바꾸고 위 여백을 늘렸다.
• 중복 문구: Lightsail 구성에서 "데이터 전송 · 번들 포함(허용량 넘으면 추가 과금)"과 "번들 데이터 전송 허용량을 넘는 전송 요금"이 같은 카드에 같이 나왔다. 하나만 남겼다.
• 만든 다음 꼭 할 일: 설명까지 4개가 다 펼쳐져 있었다. 제목 4줄만 보이고 누르면 설명이 펼쳐지게 바꿨다.
• 직접 계산기: 서비스를 두 개만 담아도 화면 4.8개 길이였다. 담은 뒤에는 "서비스 더 담기"를 설명 없는 작은 버튼으로 바꾸고, 입력 칸 도움말은 첫 문장만 보이게 했다. 화면 3.7개로 줄었다.

모두 내용은 하나도 지우지 않았다. 접거나 줄인 글은 누르면 그대로 있다.

2. 퀴즈 아이디어, 일단 거절하고 바꿔서 받기

"용어집 퀴즈 기능은 어때?"라는 생각이 들었다. 검토해보니 이 사이트와 잘 맞지 않았다.

• 사람들은 공부하러 오는 게 아니라 "내 서비스 한 달에 얼마?"를 알러 온다.
• 용어 사전은 공부용이 아니라, 결과를 읽다가 모르는 말을 눌러보는 용도다.
• 자격증 공부를 하는 사람에게는 이미 더 좋은 문제집 앱이 많다.

대신 이 사이트의 핵심인 비용 감각을 가르치는 퀴즈라면 의미가 있겠다고 봤다. 그래서 용어 퀴즈는 버리고, "이 구성 한 달에 얼마일까?" 퀴즈 아이디어를 v2 이슈로 정리했다. 처음에는 "분석 신호를 보고 시작한다"는 착수 조건도 걸어뒀다.

3. v2 마일스톤 4개를 끝내다

마일스톤에는 이슈 4개가 있었다. 순서는 작은 것부터 정했다.

1. "이 구성 만들기" 가이드 — 가격 계산이 없어서 가장 가볍다
2. 프리티어 반영
3. "얼마일까?" 퀴즈
4. AI 챗봇 + Bedrock 템플릿 — 가격 수집부터 손봐야 해서 가장 크다

① 이 구성 만들기: 비용을 봤으면 다음은 "어떻게 만들지"

결과 화면 맨 위 추천 카드에 "🛠 이 구성 만들기 · 단계별 가이드" 버튼을 달았다.

시작하기 전에   계정 만들기 · 예산 알림부터 켜기
만드는 순서     1. Lightsail 콘솔 열기  2. WordPress 인스턴스 만들기  3. 고정 IP 연결 …
다 쓴 뒤 정리   인스턴스 삭제 · 고정 IP 해제 · 스냅샷 삭제
공식 문서

• 모든 구성안이 아니라 템플릿별 추천 구성 5개만 먼저 썼다. 가이드는 정확해야 하는데, 콘솔 화면은 자주 바뀐다. 쓸 양이 적어야 관리할 수 있다.
• 같은 이유로 버튼 이름보다 "무엇을 하는지" 위주로 썼다. "모델 액세스 메뉴에서 쓸 모델을 확인해요"처럼.
• 가이드는 data/build-guides.json에서 관리한다. 문장 속 명령어는 백틱으로 감싸면 코드로 보이게 했다.
• 테스트가 "템플릿마다 맨 위 구성에 가이드가 있는지"를 확인한다. 템플릿을 추가하고 가이드를 빠뜨리면 테스트가 실패한다.

② 프리티어: "항상 무료"만, 정직하게

프리티어는 2편부터 "정책이 자주 바뀌어서 보류"였다. 실제로 AWS는 신규 계정 혜택을 크레딧 중심으로 바꾸는 등 정책을 자주 손본다.

그래서 범위를 좁혔다. 가입 기간과 상관없이 매달 무료인 사용량("항상 무료")만 뺀다.

"계산 조건 → 바꾸기"에서 프리티어: 반영 안 함 / 항상 무료 빼기를 고를 수 있다. 신경 쓴 부분은 세 가지다.

• 원래 비용 줄은 그대로 두고, "항상 무료" 줄을 음수로 따로 붙였다. 무엇이 얼마나 빠졌는지 보여야 믿을 수 있다.
• 같은 한도는 나눠 쓴다. 데이터 전송 100GB는 계정 전체 한도라서, 80GB짜리 두 줄이 있으면 100GB만 빠져야 한다. 직접 계산기도 항목마다 빼지 않고 담은 목록 전체에서 한 번만 뺀다.
• 무료 사용량은 data/free-tier.json에 정책 기준일과 같이 둔다. 정책이 바뀌면 이 파일만 고치면 된다.

서버리스 API 개인용은 $0.60이 $0.15로 줄었다. 남은 $0.15는 API Gateway 요금인데, 이건 12개월 한정 무료라 일부러 빼지 않았다.

③ 얼마일까? 퀴즈

착수 조건을 걸어뒀지만, 결국 바로 만들기로 했다.

🛠️ 개발용 단일 서버 · Lightsail 규모: 개인용 (혼자 실습·공부용) 한 달에 얼마일까요? ① 약 11,000원 ② 약 28,000원 ③ 약 66,000원

• 문제 데이터를 따로 만들지 않았다. 기존 템플릿 × 규모 × 구성안 계산에서 자동으로 뽑는다. 가격이 매주 갱신되면 정답도 같이 바뀐다.
• 보기는 원화(부가세 포함)를 앞 두 자리로 반올림했다. 10,780원이 아니라 11,000원이다.
• 처음에는 오답을 "정답의 1/3, 3배"로 만들었다. 그런데 이러면 정답이 항상 가운데 값이다. 몇 문제 풀면 눈치챈다. 오답 배수를 세 가지로 섞어서 정답이 가장 쌀 때, 가운데일 때, 가장 비쌀 때가 골고루 나오게 했다. 테스트도 이걸 확인한다.
• 고르면 실제 금액과 그 구성의 놓치기 쉬운 비용을 보여준다. 결국 이 퀴즈도 숨은 비용을 알려주는 또 하나의 입구다.

④ AI 챗봇 + Bedrock 템플릿

마지막 이슈는 잠깐 멈칫했다. "LLM 에이전트를 만드는 건가?" 싶었기 때문이다.

정리해보니 그게 아니었다. 사이트가 AI를 부르는 게 아니라, 사용자가 AWS에서 AI 챗봇을 만들 때 얼마 나오는지 계산하는 템플릿이다. 서버리스 API 템플릿과 같은 계산기이고, Bedrock의 토큰 단가를 곱할 뿐이다.

가격 수집이 제일 까다로웠다

Bedrock 요금은 오퍼 두 곳에 나뉘어 있었다.

• 단위가 다르다. 저장할 때 모두 "100만 토큰당 USD"로 맞췄다.
• Claude는 usageType만으로는 모델을 구분할 수 없어서 Model 열로 한 번 더 걸렀다.
• 도쿄에는 Claude Sonnet이 없었다. 기존 수집 스크립트는 "하나라도 못 찾으면 실패"가 원칙이다. Sonnet만 optional로 표시해서, 없는 리전에서는 선택지에서만 빠지게 했다.
• 기존 원칙은 그대로다. 입력·출력 단가 짝이 안 맞거나 필수 모델을 못 찾으면 실패하고, 기존 가격을 유지한다.

수집을 실제로 다시 돌려서 Bedrock 말고 다른 단가는 하나도 바뀌지 않은 것을 비교해 확인한 뒤 커밋했다.

템플릿

기본 모델은 Claude Haiku 5.5다. 소규모에서 모델만 바꾸면 Nova Micro $2.33, Claude Sonnet $105.42가 된다. 같은 사용량인데 수십 배 차이. 이 템플릿이 보여주고 싶은 게 바로 이것이다.

만들면서 엔진에 작은 기능 하나가 필요했다. 템플릿은 {{preset.requests}}처럼 프리셋 값을 그대로 꽂는 방식이었다. 그런데 챗봇은 "하루 대화 수"를 바꾸면 API Gateway·Lambda의 월 요청 수도 따라 바뀌어야 한다. 그래서 자리표시자에 곱셈을 넣었다.

{ "type": "lambda", "requests": "{{preset.dailyChats*30}}" }

초보자에게 알려줄 것도 몇 가지 넣었다.

• Lambda는 AI 답변을 기다리는 시간도 과금된다. 그래서 평균 실행 시간을 3초로 잡았다.
• 놓치기 쉬운 비용에 "AI 모델 토큰"을 추가했다. 이전 대화를 매번 같이 보내서 대화가 길어질수록 입력 토큰이 쌓이고, 출력 토큰은 입력보다 4~5배 비싸다.
• 용어 사전에 AI 분류를 만들었다. Bedrock, 토큰, 입력 토큰, 출력 토큰.

4. 마지막으로 하나 더 덜어내기

설정 화면("얼마나 많이 쓰나요?")에 "개인용"과 "서울"이 미리 체크돼 있었다. 편하라고 넣은 기본값인데, 다시 보니 사용자가 규모를 생각해보지 않고 그냥 넘어가게 만든다.

그래서 아무것도 미리 고르지 않게 바꿨다. 대신 버튼이 무엇을 골라야 하는지 알려준다.

규모와 리전을 골라주세요  →  리전을 골라주세요  →  비용 확인하기

숫자로 보면

• 글자 크기 약 30가지 → 5단계, 보조 설명 대비 3.0:1 → 5.1:1
• v2 마일스톤 이슈 4개 모두 닫음
• 여전히 빌드 없는 순수 HTML/CSS/JS, 외부 패키지 없음, 운영비 0원

다음에 할 것

• 교차 검증 늘리기: 지금 2건이다. 새로 생긴 AI 챗봇 조합도 공식 계산기와 비교해보려 한다.
• 가이드 직접 따라 해보기: "이 구성 만들기" 가이드를 실제 콘솔에서 처음부터 따라 해보고 고치려 한다.
• Bedrock 모델 세대 교체 대비: 모델 이름이 바뀌면 매주 가격 갱신이 실패한다. 실패는 안전하게(기존 가격 유지) 하도록 되어 있지만, 알림을 받는 방법을 고민 중이다.

마무리

4편에서 배운 건 두 가지다.

하나는 가독성도 숫자로 잴 수 있다는 것. "좀 연한 것 같은데?"가 아니라 "대비 3:1"이라고 말할 수 있으니, 고칠지 말지 고민할 필요가 없었다.

다른 하나는 기능을 넣는 방식이다. 이번에 기능 네 개를 넣었지만, 처음 화면은 거의 그대로다. 가이드는 추천 카드의 버튼 하나, 프리티어는 "바꾸기" 안의 선택 하나, 퀴즈는 메뉴 한 줄, AI 챗봇은 템플릿 목록 한 줄. 필요한 사람만 눌러서 들어가게 하면, 기능을 더해도 초보자가 읽어야 할 양은 늘지 않는다.

👉 https://dlwldp.github.io/Awscal/ 에서 써보고, 사이트의 "의견 보내기"로 피드백 주시면 감사하겠습니다!

🔗 사이트: https://dlwldp.github.io/Awscal/ 🔗 GitHub: https://github.com/dlwldP/Awscal 📝 1편: 초보자용 AWS 비용 계산기를 만들었다 (MVP · 직접 계산기 · 토스 스타일 디자인) 📝 2편: 기능을 더하다가, 덜어내는 법을 배웠다

2편 마지막에 이렇게 적었다. "기능을 넣을 때마다 물어보려고 한다. 이게 처음 AWS를 쓰는 사람한테 꼭 필요한가?"

3편은 그 질문을 실제로 계속 던지면서 한 작업들이다. 새 기능은 딱 하나만 넣었고, 나머지는 숫자를 믿을 수 있게 만들고 화면을 더 비우는 일이었다.

1. 이 숫자, 정말 맞나? 공식 계산기와 교차 검증

계산기가 틀리면 다른 기능은 의미가 없다. 그래서 2편에서 미뤄둔 AWS Pricing Calculator와의 교차 검증부터 했다.

체크리스트는 자동으로

템플릿 × 규모 × 구성안 조합마다 우리 계산값과 공식 계산기에 넣을 입력값을 표로 뽑는 스크립트를 만들었다. MVP 기준 리전(서울·버지니아)만 해도 66개 조합이다.

npm run validation   # docs/validation.md 다시 만들기

공식 계산기 금액을 validation-results.json에 적고 다시 돌리면 차이(%)와 ±10% 통과 여부가 채워진다.

결과: 2건 비교, 모두 ±10% 이내

정작 틀린 건 내 입력이었다

처음 몇 번은 차이가 크게 났다. 원인은 계산기가 아니라 공식 계산기에 값을 잘못 넣은 것이었다.

• 데이터 전송을 인바운드(들어오는 쪽)에 넣었다. 들어오는 데이터는 무료라서 0원이 나왔다.
• VPC를 추가했더니 VPN Connection이 체크돼 있어서 월 $36.50이 더해졌다.
• RDS에서 RDS Proxy, Performance Insights가 켜져 있어서 $65.40이 나왔다.

공식 계산기도 초보자에게는 어렵다는 걸 다시 느꼈다. 그래서 체크리스트에 "어느 칸에 무엇을 넣는지"까지 적어두었다.

EC2, EBS, 데이터 전송, 퍼블릭 IPv4, RDS 단가가 공식 계산기와 같다는 것도 이 과정에서 확인했다. 검증 현황은 README에도 적었다.

2. 숫자는 여러 곳에서 조용히 어긋난다

검증을 하고 나니 다른 숫자도 신경이 쓰였다. README, 사이트, 포트폴리오, GitHub 프로필에 적힌 숫자를 하나씩 대조해봤다.

기능을 추가할 때 코드와 README는 같이 고쳤는데, 다른 저장소에 적어둔 숫자는 잊고 있었다. WordPress 템플릿 하나를 추가하면서 템플릿 수, 검증 조합 수가 같이 바뀌었는데 포트폴리오는 그대로였다.

교훈은 단순하다. 숫자를 바꾸는 작업을 하면, 그 숫자가 적힌 곳을 전부 찾아서 같이 고친다.

3. 결과 화면 다이어트, 2차

2편에서 처음 보이는 양을 줄였지만, 휴대폰으로 다시 보니 결과 화면이 여전히 화면 4.8개 길이였다.

• 금액이 나오기도 전에 규모·리전·도메인 선택 칩이 세 줄 나온다. 바로 앞 화면에서 이미 고른 값이다.
• "가장 저렴한 건 Lightsail", "처음이라면 추천: Lightsail", 막대 그래프가 같은 말을 세 번 한다.
• 정작 추천 구성은 두 번째 카드에 있다.
• 계산 가정이 13줄 펼쳐져 있다.

이번에도 기능은 하나도 빼지 않고, 순서를 바꾸고 접기만 했다.

결과는 화면 4.8개 → 2.6개였다.

난이도 배지도 정리했다. 맨 위 카드에 "처음이라면 이걸로"가 있는데 "난이도 쉬움"까지 붙어 있으면 같은 말이다. 그래서 난이도는 접힌 "다른 방법" 카드에서만 보여준다. 다른 구성끼리 비교할 때는 여전히 쓸모 있기 때문이다.

4. 들어오자마자 기능 목록? 메인에 소개부터

사이트에 들어오면 바로 "무엇을 만들고 싶나요?" 목록이 나왔다. 처음 온 사람은 이게 뭐 하는 사이트인지 모른 채 고르게 된다.

소개 페이지를 따로 만들까도 생각했지만, 그러면 클릭이 하나 늘어난다. 그래서 한 페이지 안에서 순서만 바꿨다.

1. 소개: "만들고 싶은 걸 고르면 필요한 AWS 구성과 예상 월 비용을 원화로 알려드려요. AWS 계정 없이 무료예요." + [무엇을 만들지 고르기 ↓]
2. 이렇게 써요: 만들고 싶은 것 고르기 → 규모 고르기 → 예상 비용 확인
3. 이런 걸 알려줘요: 원화 월 비용, 숨은 비용, 만든 다음 꼭 할 일
4. 무엇을 만들고 싶나요? (기존 목록 그대로)

버튼은 #templates 링크 대신 scrollIntoView로 만들었다. 이 사이트는 #/...로 화면을 나누고 있어서, 해시 링크를 쓰면 라우터가 다른 화면으로 인식해버린다.

PC에서는 두 칸, 끝선까지 맞추기

PC에서 세로로 길게 늘어선 게 허전해서, 넓은 화면(900px 이상)에서만 두 칸으로 놓았다.

• 메인만 최대 폭을 720px → 1000px로 넓혔다. body:has(.home-grid) .container로 메인일 때만 바뀌게 했다.
• "이렇게 써요"와 "이런 걸 알려줘요"는 1:1, 템플릿 목록과 "더 알아보기·의견 보내기"는 2:1.

그런데 왼쪽과 오른쪽 높이가 달라서 아래가 들쭉날쭉했다. 오른쪽 칸 두 카드도 서로 높이가 달랐다.

.home-side { display: grid; grid-auto-rows: 1fr; gap: 12px; }        /* 오른쪽 두 카드를 같은 높이로 */
.home-grid .card { display: flex; flex-direction: column; }
.home-grid .card > .list { flex: 1; display: flex; flex-direction: column; justify-content: space-around; }

grid-auto-rows: 1fr은 내용이 가장 긴 줄에 맞춰 모든 줄을 같은 높이로 만든다. 왼쪽 카드는 그 높이까지 늘어나고, 늘어난 공간은 목록 줄 사이에 고르게 나눠서 아래가 비어 보이지 않게 했다. 휴대폰은 그대로 세로 한 줄이다.

5. 피드백을 통한 개선!

velog에 글을 올리며 댓글로 피드백이 들어왔다.

초보자가 놓치기 쉬운 부분의 항목도 따로 있었으면 좋겠다.

사실 관련 정보는 이미 있었다. 경고 칩, 접혀 있는 "포함 안 된 비용", 맨 아래 "만든 다음 꼭 할 일". 문제는 흩어져 있었고, 금액이 안 보였다는 것이다. "데이터 전송 요금 주의"라는 칩은 얼마인지 말해주지 않는다.

결과 화면에 "놓치기 쉬운 비용" 카드

추천 구성 바로 아래에 카드를 하나 두고, 세 묶음으로 나눴다. (아래는 모양을 보여주는 예시이고, 실제로는 그 구성에 해당하는 항목만 나온다.)

⚠️ 놓치기 쉬운 비용
이 금액에 들어 있어요
  데이터 전송      월 $0.75   사용자에게 나가는 트래픽이에요. 늘면 가장 먼저 커져요
  퍼블릭 IPv4 주소 월 $3.65   켜두기만 해도 나가요
  디스크 (EBS)     월 $1.82   서버를 중지해도 계속 나가요
알아둘 점
  ⚠ 중지해도 과금
이 금액에 안 들어 있어요
  · 스냅샷(백업) 저장 요금
  · 도메인 주소

• 금액은 새로 계산하지 않는다. 이미 계산된 비용 내역에서 해당 줄만 골라 합친다.
• 금액 줄로 이미 설명된 경고(데이터 전송, IPv4 등)는 "알아둘 점"에서 뺀다. 같은 말을 두 번 하지 않기 위해서다.
• 추천 카드에 있던 경고 칩과 "포함 안 된 비용"은 이 카드로 옮겼다.

막상 붙여보니 카드가 비어 있었다

대부분 템플릿의 추천 구성은 Lightsail이다. Lightsail은 전송 허용량이 월 정액에 들어 있어서 따로 전송 요금 줄이 없다. 정적 웹사이트의 추천인 Amplify는 전송 요금이 Amplify 전송 GB라는 이름으로 들어 있다. 서비스 이름으로만 고르니 "데이터 전송"이 하나도 안 잡혔다.

그래서 엔진의 비용 줄에 종류 표시를 붙였다.

// EC2 데이터 전송, CloudFront 전송, Amplify 전송 줄에
kind: "transfer",

카드는 서비스가 달라도 kind: "transfer"면 모두 "데이터 전송"으로 묶는다. Lightsail은 "데이터 전송 · 번들 포함 (허용량을 넘으면 GB당 추가 과금)"으로 보여준다. 피드백의 핵심인 데이터 전송이 어떤 구성에서든 빠지지 않게 됐다.

"놓치기 쉬운 AWS 비용 8가지" 안내 페이지

구성과 상관없이 자주 나오는 함정은 한 페이지에 따로 정리했다.

1. 데이터 전송 (밖으로 나가는 트래픽)
2. 퍼블릭 IPv4 주소
3. NAT Gateway
4. 로드밸런서(ALB) 기본 요금
5. 중지해도 나가는 디스크·Lightsail
6. 스냅샷·백업
7. 로그 (CloudWatch Logs)
8. 프리티어가 끝난 뒤

항목마다 얼마 · 왜 나오는지 · 이렇게 피해요를 적었다. 금액은 문장에 {natMonthly}처럼 자리만 잡아두고 서울 가격 데이터로 채운다. 그래서 매주 가격이 갱신되면 안내 페이지 금액도 같이 바뀐다.

{ "title": "NAT Gateway", "cost": "켜두기만 해도 월 약 {natMonthly} + 처리 GB당 {natPerGb}", ... }

이 페이지는 "AWS 요금 폭탄", "AWS 숨은 비용" 같은 검색에도 걸릴 만한 내용이라, 2편에서 만든 정적 소개 페이지처럼 배포할 때 HTML로도 생성하고 사이트맵에 넣었다. 앱 화면(#/hidden-costs)과 정적 페이지(pages/hidden-costs.html)가 같은 함수로 본문을 만들어서 내용이 어긋날 일이 없다.

6. 작은 정리들

개인정보처리방침, 필요할까?

회원가입도, 서버도, 방문자 분석도 없다. 계산기 목록은 이용자 브라우저(localStorage)에만 저장된다. 운영자가 모으는 개인정보가 없어서 꼭 필요하지는 않다고 판단했다.

다만 외부 서비스(Google Forms, GitHub Pages, jsDelivr 글꼴)는 접속 기록을 각자 정책대로 남긴다. 그래서 페이지를 따로 만들지 않고, 사이트 맨 아래에 접기 한 줄로 안내를 넣었다. 나중에 방문자 분석을 붙이면 그때는 제대로 된 안내가 필요하다.

꼬리말

링크 10개가 한 줄로 늘어서 있던 걸 "구성별 비용"과 "더 보기" 두 묶음으로 나눴다. 메인에만 있던 가격 갱신일은 면책 문구와 한 문장으로 합쳐서 모든 화면에 보이게 했다.

꼬리말 링크를 일부러 정적 HTML로 둔 이유도 있다. 앱 화면은 자바스크립트로 그려져서 검색엔진이 링크를 잘 따라가지 못한다. 꼬리말의 일반 링크가 정적 소개 페이지로 가는 길이 된다.

Search Console 후속

2편에서 사이트맵이 "가져올 수 없음"으로 뜬다고 적었는데, 한참 지나도 그대로였다. URL 검사로 확인해보니 구글이 아직 한 번도 크롤링하지 않은 상태였다.

• URL 검사에 사이트맵 주소를 넣으면 "Google에 등록되어 있지 않음"이 뜬다. 사이트맵은 검색 결과에 나오는 페이지가 아니라서 정상이다.
• 메인 주소로 실시간 URL 테스트를 하니 "페이지 가져오기: 성공, 색인 생성 허용: 예"가 나왔다. 사이트에는 문제가 없었다.
• 메인과 소개 페이지마다 색인 생성 요청을 눌러두었다. 구글이 한 번 방문하면 사이트맵 상태도 보통 같이 풀린다.

다음 버전은 마일스톤으로

열린 이슈 3개(프리티어 반영, "이 구성 만들기" 가이드, AI 챗봇 + Bedrock 템플릿)를 v2 마일스톤으로 묶었다. 지금 버전에서 할 일과 나중에 할 일이 한눈에 나뉜다.

숫자로 보면

• 템플릿 5종, 리전 6곳, 직접 계산 서비스 16종, 용어 40개
• 공식 계산기 교차 검증 2건, 모두 ±10% 이내 (체크리스트 66개 조합)
• 결과 화면 길이 (휴대폰): 화면 4.8개 → 2.6개
• 놓치기 쉬운 비용 안내 8가지, 검색엔진용 정적 페이지 6개 (사이트맵 7개 주소)
• 테스트: JavaScript 41개 + 가격 수집 스크립트 Python 8개 (외부 패키지 없음)
• 여전히 빌드 없는 순수 HTML/CSS/JS, 운영비 0원

다음에 할 것

• 교차 검증 늘리기: 지금 2건이다. 서버리스, 정적 웹사이트 조합까지 넓혀볼 생각이다.
• v2 마일스톤: 프리티어 반영, "이 구성 만들기" 단계별 가이드, AI 챗봇 + Bedrock 템플릿. 의견이 쌓이는 순서대로 하려 한다.
• 방문자 분석: 어디서 사람들이 빠지는지 알고 싶다. 붙인다면 쿠키 없는 도구로, 개인정보 안내와 같이.

마무리

이번에 넣은 새 기능은 "놓치기 쉬운 비용" 하나다. 그것도 새로 계산한 게 아니라 이미 있던 정보를 금액과 함께 한곳에 모은 것이다.

👉 https://dlwldp.github.io/Awscal/ 에서 써보고, 사이트의 "의견 보내기"로 피드백 주시면 감사하겠습니다!

3월에 오픽 봤고, 목표였던 IH를 한 번에 받았다. 2주 동안 실제로 효과 있었던 것들만 정리해본다.

📌 한 줄 요약

• 기간: 2주 (오픽 단기속성반)
• 목표: IH
• 결과: IH (1트)
• 핵심: 스크립트 암기 + 내 답변 녹음해서 셀프 피드백 + 최빈도 질문용 컨셉 소재 미리 정해두기

1. 준비 방식

2주 단기속성반

혼자 하면 질질 끌 것 같아서 2주짜리 단기속성반을 다녔다. 기간이 짧으니까 오히려 딴생각 안 하고 오픽만 팠던 게 좋았다.

서베이 & 난이도

서베이랑 난이도는 학원에서 추천해준 대로 갔다. 따로 고민할 필요 없이, 구글링하면 나오는 일반적인 정보 수준으로 정해도 충분하다고 본다. 여기서 시간 쓰는 것보다 그 시간에 스크립트 하나 더 외우는 게 낫다.

2. 도움 많이 됐던 공부법 3가지

① 스크립트 암기

기본은 결국 스크립트다. 자주 나오는 주제별로 스크립트를 만들어두고 외웠다. 통째로 외운다기보다는, 어떤 질문이 와도 꺼내 쓸 수 있는 문장 덩어리를 몸에 익힌다는 느낌으로 했다.

② 내 답변 녹음 → 셀프 피드백

개인적으로 제일 효과 컸던 거. 답변을 녹음해서 다시 들어보면 생각보다 별로인 게 바로 들린다.

• 같은 단어 반복하는지
• 쓸데없이 말 끊기는 구간 있는지
• 문법 틀리는 패턴 있는지
• 시간 너무 짧거나 길지 않은지

머릿속으로 말할 때랑 실제로 들을 때랑 완전 다르다. 무조건 해보는 거 추천.

③ 최빈도 질문에 답할 '컨셉 소재' 정해두기

자주 나오는 질문들에 대해 내가 밀고 갈 컨셉/소재를 미리 정해뒀다. 예를 들어 사는 곳, 취미, 자주 가는 장소 같은 걸 하나로 정해놓고, 어떤 변형 질문이 와도 그 소재로 끌고 가는 식.

이렇게 하면 시험장에서 "뭐라고 하지?" 고민하는 시간이 확 줄어든다. 소재를 돌려쓰니까 외울 양도 줄고.

3. 시험장 팁

🎧 헤드셋 볼륨은 일단 크게

시험 시작 전에 헤드셋 소리 크게 해두자. 주변에서 다른 사람들도 다 같이 말하고 있어서, 소리 작으면 질문 놓치기 쉽다.

🎯 시작하면 내 말이랑 질문에만 몰입

딱 시작하면 내 말이랑 질문에만 집중해야 한다. 옆 사람 목소리나 잡생각에 잠깐 흐트러지면 바로 질문 놓친다. 한 번 놓치면 멘탈도 같이 흔들리니까, 처음부터 끝까지 내 화면에만 몰입하는 게 필요하다.

🗑️ 질문 몇 개 버리는 것도 전략이다

이건 꼭 말하고 싶은 부분. 너무 어려운 질문은 억지로 짜내지 말자.

어려운 질문 붙잡고 억지로 말 만들다 보면

• 시간도 날리고
• 문장 꼬이면서 문법 점수까지 깎아먹는다

모든 질문을 완벽하게 할 필요 없다. 적당히 마무리하고 다음 질문에 에너지 쓰는 게 전체 점수엔 훨씬 낫다.

4. 마무리 & 다음 목표

2주 동안 짧고 굵게 준비해서 목표했던 IH 한 번에 받았다. 돌아보면 결국 "외울 건 외우고, 내 답변을 객관적으로 듣고, 시험장에선 버릴 건 버린다" 이게 다였던 것 같다.

영어 스피킹은 오픽으로 마무리하고, 다음 목표는 토익이다. 토익 준비하면서도 후기 남겨볼 예정!

토익도 화이팅 🙌

올해만 해도 직무와 환경이 몇 번 바뀌었다. 정신없이 지나온 시간을 한 번 정리해두고, 앞으로의 방향을 스스로 확인하기 위해 이 글을 쓴다.

1. 지금까지 걸어온 길

돌아보면 직선보다는 지그재그에 가까운 길이었다.

• 대학 시절 — 편입을 거쳐 컴퓨터공학(모바일SW/빅데이터 트랙)을 전공하고 2026년 2월 졸업했다. 캡스톤에서는 딥러닝 기반 퍼스널컬러 진단 Android 앱을 만들었다.
• 클라우드 교육 과정 — 800시간짜리 하이브리드·멀티클라우드 아키텍트 과정을 들으며 AWS 기반 3-tier 인프라를 팀으로 구축해봤다.
• 개발 인턴 — Kubernetes 기반 플랫폼 R&D 과제에서 프론트·백엔드를 함께 맡았다. KubeVirt, Harbor, Helm OCI 같은 낯선 개념에 부딪히면서 "모르는 걸 끝까지 파고드는 시간"이 얼마나 중요한지 배웠다.
• 영업 직무 도전 — 개발이 나와 맞는지 확신이 서지 않아 기술 기반 영업 쪽으로 방향을 틀어봤다. 짧은 기간이었지만, AI 솔루션을 직접 기획·프로토타이핑하면서 오히려 "나는 만드는 쪽이 더 즐겁다"는 걸 확인했다.
• 다시 개발로 — 생성형 AI 응용개발 교육 과정을 잠깐 듣기도 하고, 사이드 프로젝트(자취방 체크리스트 서비스)에서 백엔드 인증/인가와 AWS 배포까지 경험했다. 그리고 2026년 여름, 지금의 회사에 개발자로 입사했다.

한 번에 정답을 찾진 못했지만, 직접 부딪혀본 덕분에 "내가 뭘 좋아하고 뭘 잘할 수 있는지"는 꽤 선명해졌다.

2. 지금의 나

현재는 회사에서 ERP 개발 업무를 하고 있다. 입사 초기 맡았던 업무와는 결이 다른 분야라 처음부터 다시 배우는 중이다. 사내 언어와 도메인 지식, DB(MSSQL)를 공부하면서 하나씩 익혀가고 있다.

이를 통해 비즈니스 로직이 실제 업무 흐름과 어떻게 맞물리는지, 데이터가 어떻게 쌓이고 쓰이는지를 가까이서 볼 수 있다는 점에서 배울 게 많다고 느끼고 있다.

3. 내가 가고 싶은 방향

백엔드 개발자, 그리고 클라우드.

인턴, 교육 과정, 사이드 프로젝트를 거치며 계속 손이 갔던 건 결국 서버와 인프라였다. 서비스 하나를 밑단부터 배포까지 내 손으로 완주해보는 것이 지금의 가장 큰 목표다.

4. 그래서 지금 하고 있는 것들

• 현업에 충실하기 — 일단 지금 자리에서 최소 1년은 제대로 채우고, 길게는 몇 년 정착하면서 실무 기본기를 다지려고 한다.
• 백엔드 동아리 도전 — 회사 밖에서도 백엔드 경험을 이어가고 싶어서 개발 동아리에 서버 개발자로 지원하고 있다.
• 자격증 — 정보처리기사, SQLD를 준비할 계획이다.
• 기록하기 — 1년 넘게 매일 아침 모닝페이지를 쓰고 있고, 기술 개념 정리와 단기/장기 목표를 노션에 꾸준히 남기고 있다. 이 블로그도 그 연장선이다.
• 대학원은 잠시 보류 — 재직하면서 클라우드/AI 쪽 석사를 고민했지만, 지금은 현업과 경험 쌓기에 집중하기로 했다.

5. 마치며

남들보다 돌아온 것 같다는 생각이 들 때도 있다. 그래도 그 과정에서 개발도, 인프라도, 기획도, 영업도 조금씩 겪어봤고, 그게 결국 지금 방향을 정하는 데 가장 큰 근거가 됐다.

내가 추구하는 건 거창한 게 아니라 "어제보다 조금 더 성장한 사람" 이다. 몇 달 뒤 이 글을 다시 열어봤을 때, 지금보다 한 걸음 더 나아가 있기를 바라며.

1편에서는 "목적을 고르면 AI 툴 2~3개를 추천해주는 사이트"의 뼈대(추천 규칙, 화면, 배포, 주간 점검)를 만들었습니다. 2편은 그 뒤의 이야기입니다. 개발자용 버전으로 넓힌 과정과, AI에게 툴 정보를 모아 달라고 하기 전에 정한 보안 규칙을 정리했습니다.

• 사이트: https://dlwldp.github.io/which-ai/ · 개발자용: https://dlwldp.github.io/which-ai/dev/
• 저장소: https://github.com/dlwldP/which-ai

⚠️ 먼저 밝혀둘 것

• 사이트에는 아직 실제 툴 데이터가 0개입니다. 이 글의 화면과 테스트는 모두 제가 지어낸 예시 데이터(?demo)로 확인한 것입니다.
• 실제 사용자(비개발자·개발자)에게 써보게 하는 테스트는 아직 하지 않았습니다. 테스트 계획만 세워 두었습니다.
• 실제 데이터를 넣고 사람들에게 써보게 한 결과는 3편으로 돌아와서 쓰겠습니다.

1. "개발 도구도 넣자" → 기획서와 부딪히다

데이터를 채우기 전에, 툴 카테고리를 이렇게 정리해서 전부 넣고 싶어졌습니다.

그런데 1편의 기획서에는 "하지 않을 것"으로 이렇게 적혀 있었습니다.

타깃은 비개발자. GitHub 레포, 설치형·개발자용 도구는 다루지 않는다.

목록을 다시 보니 문제가 하나 더 있었습니다. PostgreSQL, Docker, GitHub Actions는 AI 툴이 아니고, 학습 자료는 도구가 아닙니다. 전부 "AI 툴"이라고 소개하면 사실과 다른 설명이 됩니다.

세 가지 선택지(넣지 않기 / 별도 버전 / 사이트 자체를 개발자용으로 바꾸기)를 놓고, 별도 버전으로 정했습니다.

• 비개발자 사이트는 그대로 둡니다. 개발 도구를 섞지 않습니다.
• 같은 저장소의 /dev/ 주소에 "개발할 때 AI 뭐 써?"를 따로 만듭니다.
• AI 툴이 아닌 도구는 넣되, 카드에 "AI와 같이 쓰는 도구"라고 따로 표시합니다 (ai_native: "no").
• 학습 자료는 추천 순위에 넣지 않고, 도구 상세 화면의 "배울 거리" 링크로 보여줍니다.
• "오픈소스"는 카테고리가 아니라 조건("오픈소스만")으로 바꿨습니다.

2. 엔진 하나로 사이트 두 개

새 사이트를 처음부터 다시 만들지 않고, 기존 코드를 두 갈래로 나눴습니다.

추천 규칙: profile로 나누기

추천 함수는 그대로 두고, 데이터 세트마다 다른 규칙만 profile로 분리했습니다.

export const PROFILES = {
  general: {                       // 비개발자용 (기존)
    filters: { freeOnly, securityImportant, mobile },
    relaxOrder: ['mobile', 'freeOnly'],          // 보안 조건은 절대 안 뺌
    bonus: (t, c) => t.korean * (c.koreanImportant ? 4 : 1) + (t.price.free ? 2 : 0),
  },
  dev: {                           // 개발자용
    filters: { freeOnly, openSourceOnly },
    relaxOrder: ['openSourceOnly', 'freeOnly'],
    bonus: (t) => (t.ai_native === 'yes' ? 2 : 0) + (t.price.free ? 2 : 0),
  },
};

리팩터링 뒤에 기존 테스트를 한 줄도 고치지 않고 다시 돌렸고, 모두 통과했습니다. 비개발자 사이트의 추천 결과가 바뀌지 않았다는 확인입니다.

화면: 같은 app.js, 다른 설정

화면 문구, 조건, 카드 비교 항목은 js/modes.js라는 설정 파일로 뺐습니다. dev/index.html은 <body data-mode="dev"> 한 줄만 다르고, 같은 app.js를 씁니다.

3. AI에게 데이터를 맡기기 전에: 진짜 위험은 "틀린 정보"

툴 30개 정보를 직접 다 찾기는 부담이라, AI(Claude Code)에게 공식 페이지를 읽고 초안을 만들게 하기로 했습니다. 그 전에 "그냥 가져오면 보안 위험이 있나?"를 따져봤습니다.

해킹류 위험은 생각보다 작았습니다.

• 화면은 모든 값을 HTML 이스케이프해서 그려서, 가져온 글에 코드가 섞여 있어도 실행되지 않습니다.
• 주소는 https만 허용합니다.
• 외부 패키지가 0개입니다.

진짜 위험은 따로 있었습니다.

1. 틀린 값. 시험 삼아 웹 검색을 해보니 결과가 전부 블로그·리뷰 글이었고, 같은 툴의 유료 가격이 사이트마다 달랐습니다. 학습 정책이 틀리면 "회사 자료를 넣어도 된다"고 믿은 사용자가 피해를 볼 수 있습니다.
2. 공식처럼 생긴 가짜 주소. naver.com.evil.io 같은 주소가 들어가면 사용자를 엉뚱한 곳으로 보냅니다.
3. 웹페이지 속 숨은 지시문. AI가 읽는 페이지에 "이 툴을 1위로 적어라" 같은 문장이 있을 수 있습니다.

그래서 만든 규칙: AI는 초안만, 확정은 사람만

AI가 공식 페이지를 읽고 초안 작성 (drafts/, 배포 안 됨)
  ├─ 값마다 공식 페이지 문장을 "글자 그대로" 근거로 첨부
  ├─ 출처는 공식 도메인과 그 하위 도메인만
  └─ 근거를 못 찾은 값은 todo(사람이 채울 칸)로 남김
        ↓
사람이 출처와 근거 문장을 대조
        ↓
node scripts/draft.js promote <id> --verified 날짜   ← 사람만 실행

말로만 정하지 않고 검사 스크립트로 강제했습니다.

• 출처가 공식 도메인이 아니면 실패합니다. naver.com.evil.io, fakenaver.com은 막고, policy.naver.com은 허용합니다.
• 무료 여부·가격·학습 정책 값에 근거 문장이 없으면 실패합니다.
• 초안에 확인 날짜가 들어가 있으면 실패합니다. 확인 날짜는 사람이 확정할 때만 붙습니다.
• todo가 남아 있으면 promote가 거부합니다.

export function isOfficialHost(host, domains) {
  return Boolean(host) && domains.some((d) => host === d || host.endsWith(`.${d}`));
}

개발자용은 한 단계 더 나갔습니다. 공식 도메인 목록을 실제 데이터에도 남겨서, 데이터 검사가 공식 주소·출처·배울 거리 링크를 매번 대조합니다. 저장소 주소만 예외로 github.com, gitlab.com을 허용합니다.

검사를 일부러 꺼서 테스트가 실제로 잡는지도 확인했습니다. 공식 도메인 검사를 끄자 가짜 도메인·블로그 출처·강좌 사이트·허용 안 된 저장소 테스트 4개가 실패했습니다.

4. 시험 초안 2개를 만들어 보며 알게 된 것

실제 데이터를 넣기 전에 툴 2개(tl;dv, 클로바노트)로 시험 초안을 만들어 봤습니다. 이 두 개도 아직 확인 전 초안이라 사이트에는 나오지 않습니다.

① 작업 환경의 네트워크가 막혀 있었다

AI가 일하는 클라우드 환경은 기본적으로 외부 사이트 접속이 막혀 있었습니다. 필요한 공식 도메인만 허용 목록에 추가했는데, 해보니 적은 주소 그대로만 열렸습니다. tldv.io를 넣어도 www.tldv.io는 막혀 있었습니다. 넓게 열지 않고 툴마다 필요한 주소를 하나씩 적는 방식이 오히려 안전했습니다.

② 가격 페이지는 대부분 "글자로 안 읽힌다"

페이지를 받아 보이는 글자만 뽑는 방식을 썼습니다. 페이지 안의 스크립트는 실행하지 않았습니다. 그랬더니 개인정보 정책 같은 문서는 잘 읽혔지만, 가격 페이지와 클로바노트 사이트는 화면을 스크립트가 그려서 제목 한 줄만 나왔습니다.

격리된 브라우저로 스크립트를 실행해 읽는 방법도 있었지만 쓰지 않기로 했습니다. 대신 그런 값은 todo(사람이 채울 칸)로 남기게 했습니다.

③ 공식 사이트 안에서도 말이 엇갈린다

tl;dv는 학습 정책에 대한 명확한 문장이 있었습니다.

"No customer data is used to train the AI."

그런데 같은 공식 사이트 안에서도 첫 화면 질문 답변에는 "아직 모바일 앱이 없다"고 되어 있고, 다른 페이지에는 iOS 앱 링크가 있었습니다. AI가 판단하지 않고 메모로 남겨 사람에게 넘기게 했습니다.

클로바노트는 네이버 전체 이용약관에 "콘텐츠를 인공지능 연구 개발에 쓸 수 있다"는 문장이 있었습니다. 하지만 게시물에 관한 조항이라 녹음에도 해당하는지 알 수 없었습니다. 그래서 학습 정책은 unknown으로 두었습니다. 1편의 원칙대로, 모르는 걸 안전하다고 보여주지 않습니다.

5. 마감 준비 (Phase 5)

• "정보가 틀려요" 제보: GitHub Issue 양식을 만들고, 카드와 상세 화면에 사이트·툴 이름이 미리 채워진 제보 링크를 달았습니다. 코드·데이터 PR은 받지 않고 제보만 받습니다.
• 주간 점검 확장: 비개발자용·개발자용 데이터를 함께 점검해서 Issue 하나에 나눠 보여줍니다. 개발자용 저장소·배울 거리 링크도 점검합니다. 예시 데이터로 GitHub에서 실행해 Issue가 갱신되는 것까지 확인했습니다.
• 용어집 검토: "PRD"가 "PR"로 잘못 잡히지 않는지, "에이전트 오케스트레이션"에 엉뚱한 "코딩 에이전트" 풀이가 뜨지 않는지 확인하며 고쳤습니다.
• 사용성 테스트 준비: 비개발자 3명용 진행 대본, 과제 4개, 기록 양식을 만들었습니다. 아직 진행하지 않았습니다.

6. 지금 상태 (정직하게)

7. 이번에 배운 것

• 범위를 넓히고 싶을 때는 기획서의 "하지 않을 것"부터 다시 읽는다. 섞지 않고 나누니 비개발자 사이트의 쉬움을 지킬 수 있었습니다.
• 리팩터링은 기존 테스트가 그대로 통과하는지로 증명한다.
• AI에게 일을 맡길 때 위험은 해킹보다 "그럴듯하게 틀린 정보"였다. 그래서 "AI는 근거를 붙여 초안만, 확정은 사람만"을 검사 스크립트로 강제했습니다.
• 자동화가 못 하는 일은 숨기지 않고 todo로 남긴다. 글자로 안 읽히는 가격 페이지를 억지로 채우는 것보다 낫습니다.

다음 편 예고

실제 툴 데이터를 공식 페이지 기준으로 채우고, 비개발자 3명에게 직접 써보게 한 결과를 가지고 3편으로 돌아오겠습니다. 무엇이 헷갈렸고 무엇을 고쳤는지, 예시 데이터가 아닌 진짜 화면으로 보여드리겠습니다. 🙌

하고 싶은 일을 고르면 맞는 AI 툴 2~3개를 이유와 함께 비교해주는 비개발자용 선택 도우미. "AWS 얼마야?"의 자매 프로젝트입니다.

• 사이트: https://dlwldp.github.io/which-ai/
• 예시 데이터로 둘러보기: https://dlwldp.github.io/which-ai/?demo#/
• 저장소: https://github.com/dlwldP/which-ai

1. 왜 만들었나

AI 툴이 너무 많습니다. 주변 비개발자분들이 자주 묻는 건 대개 이런 질문이었어요.

• "회의록 정리하고 싶은데 뭐 써?"
• "무료로 돼?"
• "회사 자료 넣어도 괜찮아?"

기존 AI 디렉터리는 수천 개를 나열만 해서 오히려 고르기 어렵습니다. 그래서 목록을 보여주지 않는 사이트를 만들기로 했습니다.

1. 하고 싶은 일(목적)을 고른다
2. 조건(무료만 / 보안 중요 / 한국어 중요 / 휴대폰)을 고른다
3. 툴 2~3개를 추천 이유와 함께 비교해서 보여준다

2. 설계 원칙

기획 단계에서 먼저 원칙 다섯 개를 정했고, 개발하는 내내 이 원칙에 맞는지를 기준으로 판단했습니다.

하지 않을 것도 정했습니다. 서버, 회원가입, 런타임 LLM 호출, 광고·제휴 링크, 개발자용 도구는 다루지 않습니다. 그래서 운영비는 0원입니다.

3. 기술 스택

package.json에 의존성이 하나도 없습니다. 설치할 게 없으니 공급망 위험도 없고, 몇 년 뒤에 열어도 그대로 돌아갑니다.

4. 개발 과정

개발은 Claude Code와 함께 했습니다. 처음에 "임의로 결정하지 말고, 세부사항이 애매하면 확인받고 진행해 달라"고 요청했는데, 이게 꽤 효과가 좋았어요. 기획서에 빈 곳이 생각보다 많았고, 그때마다 선택지와 장단점을 받아서 제가 골랐습니다.

정한 내용은 docs/decisions.md에 표로 쌓았습니다.

Phase 1. 추천 로직: 순수 함수 하나

추천은 js/recommend.js의 순수 함수 하나가 전부입니다. DOM에도 시계에도 접근하지 않고, 오늘 날짜도 밖에서 받습니다. 그래서 테스트하기 쉽고 같은 입력이면 항상 같은 결과가 나옵니다.

function score(tool, purposeId, conditions, today) {
  return tool.purposes[purposeId] * 10
    + tool.korean * (conditions.koreanImportant ? 4 : 1)
    + (tool.price.free ? 2 : 0)
    - (isStale(tool, today) ? 3 : 0);   // 90일 넘게 확인 안 된 정보는 감점
}

결과가 0개일 때는 정해진 순서대로 조건을 하나씩 뺍니다. 보안 조건은 목록에 아예 없습니다.

// 결과가 0개일 때 빼는 순서. 보안 조건은 절대 빼지 않는다.
const RELAX_ORDER = ['mobile', 'freeOnly'];

"회사 자료라 보안 중요"를 고른 사람에게 학습 정책이 "확인 필요"인 툴을 보여주면 안 되기 때문입니다. 모르는 걸 안전하다고 보여주지 않는 것이 이 프로젝트에서 가장 중요한 규칙이에요.

테스트가 진짜 잡는지 확인하기

기획서의 테스트 기준을 그대로 테스트로 옮겼습니다.

• 보안 조건에서 unknown 툴이 나오지 않는다
• 무료 조건에서 유료 전용 툴이 나오지 않는다
• 같은 입력 100번에 같은 결과가 나온다
• 조건 4개의 16가지 조합을 모든 목적에 돌린다

그다음 일부러 코드를 망가뜨려서 테스트가 실패하는지 확인했습니다. 여기서 하나를 발견했어요. 보안 테스트가 recommend.js의 판정 함수(isSecure)를 그대로 가져다 쓰고 있어서, 판정 로직이 틀리면 테스트도 같이 틀려서 통과해 버렸습니다. 테스트 안에 기획서 기준을 따로 적도록 고쳤습니다.

// 기획서 9장 보안 기준. recommend.js의 판정 함수를 쓰지 않고 테스트에서 따로 적는다.
const meetsSecurity = (tool) =>
  tool.privacy.trains_on_input_default === 'no' || tool.privacy.opt_out === 'yes';

Phase 2. 화면: 한 페이지 + 주소로 단계 구분

index.html 하나에서 주소(#/...)로 화면을 나눴습니다. 뒤로 가기가 되고, 결과 링크를 그대로 공유할 수 있습니다.

#/                         홈 (어떤 일을 맡기고 싶어요?)
#/p/P02?secure=1           조건 선택
#/p/P02/result?secure=1    추천 결과
#/t/<툴 id>                툴 상세

실제 데이터가 없는데 화면은 어떻게 확인하지?

툴 정보는 공식 페이지에서 직접 확인해서 채우기로 했기 때문에, 화면을 만드는 시점에는 데이터가 0개였습니다. 그래서 주소에 ?demo가 있을 때만 지어낸 예시 툴을 쓰고, 화면 맨 위에 "예시 데이터예요" 띠를 띄우기로 했습니다.

비교표 대신 옆으로 넘기는 카드

처음에는 비교표 + 카드였는데, 휴대폰에서 툴 3개짜리 표가 너무 빽빽했습니다. 그래서 카드를 가로로 나란히 놓았습니다.

• 휴대폰: 옆으로 넘기고, 한 장씩 멈추고, 아래 점으로 위치를 표시
• 넓은 화면: 3개를 한 번에

카드끼리 비교하려면 "가격", "학습 정책" 같은 항목이 모든 카드에서 같은 높이에 있어야 합니다. 추천 이유가 1개인 카드와 3개인 카드가 섞이면 줄이 어긋나는데, CSS subgrid로 해결했습니다.

.cards {
  display: grid;
  grid-auto-flow: column;
  grid-auto-columns: 86%;              /* 다음 카드가 살짝 보이게 */
  grid-template-rows: repeat(11, auto); /* 카드 안 칸 11개 */
  overflow-x: auto;
  scroll-snap-type: x mandatory;
}
.tool-card {
  display: grid;
  grid-row: span 11;
  grid-template-rows: subgrid;          /* 부모의 행을 같이 쓴다 → 카드끼리 높이가 맞음 */
  scroll-snap-align: start;
}

Playwright로 각 카드의 항목 위치를 재서, 세 카드 모두 같은 y좌표인 것까지 확인했습니다.

디자인: 토스 느낌 → 따뜻한 종이 느낌

처음엔 자매 프로젝트(Awscal)와 같은 토스 스타일이었는데, 다른 느낌을 원해서 바꿨습니다. 정보 사이트라는 성격에 맞춰 "안내서" 같은 톤을 골랐어요.

• 아이보리 배경, 먹색 글자, 테라코타 포인트
• 그림자 없이 얇은 테두리 카드
• 제목만 명조(Noto Serif KR)

Phase 3. 툴 상세, 용어집, 변경 이력, 다크 모드

용어집: 문장 속 단어에 밑줄

"토큰", "무료 크레딧", "학습 정책" 같은 단어가 화면에 나오면 점선 밑줄을 치고, 누르면 화면 아래에 풀이가 뜹니다. 단어는 긴 것부터 찾아야 "무료 크레딧"이 "크레딧"보다 먼저 잡힙니다.

export function termMatcher(glossary) {
  const words = glossary.flatMap((g) => [g.term, ...g.aliases].map((word) => ({ word, term: g.term })));
  words.sort((a, b) => b.word.length - a.word.length || (a.word < b.word ? -1 : 1));
  // ...긴 단어 우선 정규식
}

변경 이력: git 기록이 곧 데이터

"가격이 언제 바뀌었는지"는 따로 기록하지 않습니다. data/tools.json의 git 기록 자체가 이력이에요. 배포할 때 커밋마다 이전 버전과 비교해서 이런 문장을 만듭니다.

Gamma: 유료 가격 10달러 → 12달러
Gamma: '발표자료(PPT) 만들기' 적합도 2점 → 3점

처음에는 결과 파일을 레포에 커밋했는데, 깜빡하면 배포가 멈추는 구조였습니다. 그래서 배포 작업이 그 자리에서 만들어 사이트에만 올리도록 바꿨습니다.

Phase 4. 배포와 주간 점검

main에 푸시하면 GitHub Actions가 테스트와 데이터 검사를 돌리고, 통과해야만 Pages에 배포합니다.

정보가 낡는 것이 이 프로젝트의 가장 큰 리스크라서, 매주 월요일 오전 9시에 자동 점검이 돕니다.

• 90일 넘게 확인 안 된 툴 목록
• 공식 주소·출처 링크: 깨진 링크와 로봇 접속이 막힌 링크를 따로 표시
• 결과는 "주간 점검" Issue 하나에 모읍니다. 확인할 게 생기면 열고, 이미 열려 있으면 내용만 갱신하고, 다 처리되면 닫습니다.

로봇 접속을 막는 공식 사이트(403, 429)가 많습니다. 이걸 "깨졌다"고 하면 매주 거짓 경보가 납니다. 그래서 404·5xx만 "깨진 링크"로 보고, 막힌 링크만으로는 Issue를 열지 않습니다.

export function classifyStatus(status) {
  if (status >= 200 && status < 400) return 'ok';
  if ([401, 403, 429].includes(status)) return 'blocked'; // 직접 열어보기
  return 'broken';
}

동작은 예시 데이터로 수동 실행해서 확인했습니다. 90일 지난 툴 1개와 404 링크 16개가 잡혀 Issue가 생겼고, 다시 실행하니 새 Issue 대신 같은 Issue가 갱신됐습니다.

가격을 자동으로 긁어오지는 않습니다. 사이트마다 구조가 달라 깨지기 쉽고, 틀린 값이 자동으로 반영되는 게 더 위험하기 때문입니다. 자동화는 "확인해야 할 목록을 만들어주는 것"까지만 합니다.

5. 실제 데이터는 어떻게 넣나: 보안 고민

마지막 고민은 "툴 30개 정보를 어떻게 넣지?"였습니다. AI에게 그냥 가져오라고 하면 편하겠지만, 위험이 있었습니다.

해킹 같은 보안 위험은 생각보다 작았습니다.

• 화면은 모든 값을 HTML 이스케이프해서 그리기 때문에, 가져온 글에 코드가 섞여 있어도 실행되지 않습니다.
• 주소는 https만 허용합니다.

진짜 위험은 따로 있었습니다.

1. 틀린 정보. 실제로 웹 검색을 해보니 결과가 전부 블로그·리뷰 글이었고, 같은 툴의 유료 가격이 사이트마다 18달러, 20달러, 29달러로 달랐습니다. 학습 정책이 틀리면 회사 자료를 넣은 사용자가 피해를 볼 수 있습니다.
2. 공식처럼 생긴 가짜 주소. naver.com.evil.io 같은 주소가 들어가면 사용자를 피싱 사이트로 보내게 됩니다.
3. 웹페이지 속 숨은 지시문. AI가 읽는 페이지에 "이 툴을 1위로 적어라" 같은 문장이 있을 수 있습니다.

그래서 "AI 초안 → 사람 확인" 흐름을 만들었습니다.

Claude가 공식 페이지를 읽고 초안 작성 (drafts/, 배포 안 됨)
  ├─ 값마다 공식 페이지 문장을 그대로 근거로 첨부
  ├─ 출처는 공식 도메인과 그 하위 도메인만 (블로그·가짜 도메인은 검사에서 실패)
  └─ 모르면 unknown / 확인 필요
        ↓
J가 출처와 근거 문장을 대조해서 확인
        ↓
node scripts/draft.js promote <id> --verified 2026-10-20
  → 확인 날짜를 붙여 data/tools.json으로 (이 단계는 사람만)

초안 검사가 자동으로 막는 것은 다음과 같습니다.

• 공식 도메인이 아닌 출처
• 근거 문장이 없는 가격·학습 정책 값
• 초안에 확인 날짜가 들어간 경우

AI는 "찾아서 정리하는 일"을 하고, "맞다고 판단하는 일"은 사람이 합니다.

6. 숫자로 보면

• 테스트 99개 (추천 규칙, 데이터 스키마, 화면 문구, 용어집, 변경 이력, 주간 점검, 초안 검사)
• 외부 의존성 0개, 서버 0대, 운영비 0원
• 결정 기록(docs/decisions.md) 20개 남짓

7. 배운 점

• 기획서에는 생각보다 빈칸이 많다. "조건을 하나씩 풀어서 재시도"라는 한 줄에도 "어떤 순서로? 보안도 풀어?"가 숨어 있었습니다. 애매하면 묻고, 결정은 문서로 남기는 습관이 가장 큰 수확입니다.
• 테스트는 망가뜨려 봐야 믿을 수 있다. 통과하는 테스트가 실제로 버그를 잡는지는 코드를 일부러 틀려봐야 알 수 있었습니다.
• 자동화의 범위를 정하는 것도 설계다. 가격 자동 수집은 하지 않고 "확인할 목록 만들기"까지만 자동화한 덕분에, 틀린 정보가 몰래 올라갈 길이 없습니다.
• AI와 협업할 때는 책임의 경계를 코드로 만든다. "AI는 초안만, 확정은 사람만"을 말로만 정하지 않고 검사 스크립트로 강제했습니다.

8. 남은 일

• Phase 0: 툴 30개 정보를 공식 페이지에서 확인해 채우기 (이 프로젝트의 본체)
• 용어집 초안 검토
• 비개발자 3명 사용성 테스트
• "정보가 틀려요" 제보 링크

데이터가 채워지면 2편으로 돌아오겠습니다. 🙌

추가로, "AWS 얼마야?" 서비스가 궁금하시다면 하단 링크로 들어가시면 보실 수 있답니다~!! 🔗 사이트: https://dlwldp.github.io/Awscal/ 🔗 GitHub: https://github.com/dlwldP/Awscal

🔗 사이트: https://dlwldp.github.io/Awscal/ 🔗 GitHub: https://github.com/dlwldP/Awscal 📝 1편: 초보자용 AWS 비용 계산기를 만들었다 (MVP · 직접 계산기 · 토스 스타일 디자인)

1편을 올리고 생각보다 반응이 좋았다. "이거 진짜 필요했다", "처음 AWS 쓸 때 이런 게 있었으면" 같은 말을 들으니 신이 나서 하루 동안 기능을 꽤 많이 붙였다.

그런데 이번 작업에서 가장 크게 배운 건 기능을 더하는 법이 아니라 덜어내는 법이었다. 그 과정을 순서대로 정리해본다.

1. 먼저 신뢰부터: "실제 청구서랑 다르던데요?"

반응이 좋을수록 제일 무서운 피드백은 "계산이 틀렸다"다. 그래서 새 기능보다 숫자를 믿을 수 있게 만드는 작업을 먼저 했다.

부가세 10%

한국 계정은 AWS 청구액에 부가세 10%가 더해진다. 그런데 원화 금액이 부가세 없이 나오고 있었다. 사용자는 화면에서 본 금액보다 10% 더 내게 되는 셈이다.

달러는 AWS 표시 가격 그대로 두고, 원화는 항상 부가세를 포함해서 보여주도록 바꿨다.

$7.00 / 월 · 약 10,780원 (부가세 포함)

"이 금액에 포함 안 된 비용"

계산기가 모든 비용을 다 담을 수는 없다. 대신 빠진 걸 솔직하게 적기로 했다. 구성안마다 한 줄씩이다.

• EC2 + RDS: RDS 자동 백업 초과분, EBS 스냅샷, CloudWatch 로그
• ECS Fargate: ECR 이미지 저장, NAT Gateway(프라이빗 서브넷 구성 시)
• Amplify: 방화벽(WAF) 월 $15

도메인 옵션

초보자가 제일 많이 묻는 비용이 "도메인은 얼마예요?"였다. 결과 화면에 도메인: 없음 / 포함(.com) 선택을 넣었다. 켜면 모든 구성안에 월 $1.75가 더해진다.

• .com 등록비: 연 $15 ÷ 12개월
• Route 53 호스팅 영역: 월 $0.50

여기서 하나 걸렸다. 도메인 등록비는 AWS Price List API에 없다. 다른 가격은 매주 자동으로 갱신되지만, 이 값만은 스크립트에 상수로 적고 확인한 날짜를 같이 남겼다.

"가장 저렴"이 정답은 아니다

백엔드 웹앱을 고르면 Lightsail이 $7로 가장 저렴하게 나온다. 하지만 Lightsail은 DB를 직접 설치하고 백업해야 한다. 초보자가 가격만 보고 고르면 고생할 수 있다.

그래서 배지를 세 가지로 나눴다.

• 처음이라면 추천 (이유 한 줄과 함께)
• 가장 저렴
• 난이도 쉬움 / 보통 / 어려움

2. 사람들이 찾아오고, 공유할 수 있게

링크 미리보기 (OG 이미지)

카카오톡이나 슬랙에 링크를 붙이면 덩그러니 주소만 보였다. OG 태그와 1200×630 미리보기 이미지를 만들었다. 이미지는 HTML로 그리고 Playwright로 캡처했다.

공유 링크

"이 결과 친구한테 보여주고 싶은데요"라는 요청이 있었다. 그래서 화면 상태를 주소에 담았다.

#/t/backend-webapp/small/ap-northeast-2?instance=t4g.medium&egressGb=100&domain=1

• 결과 화면은 프리셋과 다른 값만 사람이 읽을 수 있는 형태로 담는다.
• 값을 바꿀 때마다 history.replaceState로 주소도 같이 바꿔서, 주소창을 그대로 복사해도 공유된다.
• 직접 계산기는 담은 목록 전체를 JSON → base64url로 줄여서 #/calc?s=...에 담는다.
• 받은 사람의 계산기에 이미 목록이 있으면 "받은 구성으로 바꿀까요?"라고 먼저 묻는다.
• 손으로 고치거나 오래된 링크도 안전하게 열리도록, 모르는 키·선택지에 없는 값·범위 밖 숫자는 버린다.

공유 버튼은 휴대폰에서는 공유창(카카오톡 등), PC에서는 링크 복사로 동작한다.

의견 보내기

GitHub 이슈 링크만 있으면 개발자만 의견을 남길 수 있다. 그래서 계정 없이 쓸 수 있는 구글폼을 연결했다.

삽질이 하나 있었다. 처음에 폼 편집 화면 주소를 붙였다. 편집 주소는 로그인하고 편집 권한이 있어야만 열려서 계정이 털릴 걱정은 없다. 하지만 일반 방문자에게는 "권한 필요"가 뜰 수 있다. 응답자용 주소(/forms/d/e/.../viewform)로 바꾸고, 시크릿 창에서 열리는지 확인했다.

검색 노출: 해시 라우팅의 한계

이 사이트는 #/t/backend-webapp처럼 해시로 화면을 나누고, 화면은 자바스크립트로 그린다. 검색엔진 입장에서는 내용이 거의 없는 페이지다.

그래서 배포할 때마다 템플릿별 정적 소개 페이지를 HTML로 생성하게 했다. 규모별 가격표, 장단점, 숨은 비용이 들어 있다. 사이트맵도 같이 만든다.

- name: 배포할 파일 모으기 + 검색용 소개 페이지 생성
  run: |
    cp -r index.html css js data assets _site/
    node scripts/build-pages.js _site

배운 것 두 가지.

• GitHub Pages 프로젝트 사이트(아이디.github.io/저장소)에서는 robots.txt가 효과가 없다. 검색엔진은 도메인 루트의 robots.txt만 읽기 때문이다. 그래서 만들지 않고, Search Console에 사이트맵을 직접 등록했다.
• Search Console에 사이트맵을 처음 제출하면 "가져올 수 없음"이 뜰 때가 많다. 브라우저로 sitemap.xml이 잘 열리면 파일 문제가 아니라, 구글이 아직 안 읽어간 것이니 기다리면 된다.

3. 오래 굴러가게: 유지보수

가격 변동 기록

가격은 매주 자동으로 갱신된다. 이제 갱신할 때 지난주와 비교해서 바뀐 단가를 price-changes.json에 남기고, "가격 변동 내역" 화면으로 보여준다.

리전을 추가하던 날, 변동이 244건으로 찍혔다. 새 리전의 가격이 전부 '변동'으로 잡힌 것이다. 그래서 양쪽에 다 있는데 값이 바뀐 것만 '변동'으로 세고, 새로 생기거나 없어진 항목은 개수만 따로 세도록 바꿨다.

GitHub Actions Node 20 지원 종료

배포 로그에 "Node.js 20 is deprecated" 경고가 뜨고 있었다. 버전을 무작정 올리지 않고 순서대로 확인했다.

1. git ls-remote --tags로 각 액션의 최신 메이저 버전 확인
2. 각 버전의 action.yml에서 runs.using: node24인지, 입력값이 바뀌었는지 확인
3. 변경 내역(CHANGELOG)에서 우리 사용 방식에 영향이 있는지 확인

가격 갱신 워크플로는 월요일에만 돌아서, 새 checkout으로 봇이 커밋·푸시까지 되는지 검증이 안 된 상태였다. 그래서 workflow_dispatch로 한 번 수동 실행해서 자동 커밋과 재배포까지 확인했다.

다크 모드

기기 설정을 따르고, 상단 🌙/☀️ 버튼으로 바꿀 수 있다. 고른 값은 브라우저에 기억한다. 화면이 깜빡이지 않도록 <head>에서 그리기 전에 테마를 적용한다.

<script>
  try { var t = localStorage.getItem("theme");
        if (t === "dark" || t === "light") document.documentElement.dataset.theme = t; } catch (e) {}
</script>

색은 처음부터 CSS 변수로 만들어 둬서 변수 값만 바꾸면 됐다. 다만 하드코딩된 색이 몇 군데 남아 있어서 전부 찾아 변수로 옮겼다.

4. 입문자를 위한 것들

용어 사전

vCPU, LCU, NAT Gateway, 730시간… 설명을 읽다가 또 모르는 단어가 나오면 막힌다.

그래서 설명 속 어려운 용어에 점선 밑줄을 긋고, 누르면 아래에서 뜻이 올라오게 했다. 용어 41개를 데이터 파일 하나로 관리하고, 설명 문장에서 자동으로 찾아 버튼으로 감싼다.

• 긴 단어부터 찾는다. 'Route 53'이 'Route'보다 먼저 잡혀야 하기 때문이다.
• 같은 용어는 문장마다 처음 한 번만 감싼다. 밑줄이 가득하면 오히려 읽기 어렵다.

리전 6곳

서울, 버지니아에 도쿄, 싱가포르, 오레곤, 프랑크푸르트를 추가했다. 수집 스크립트에 리전 정보만 추가하면 됐다.

CloudFront만 조심해야 했다. 전송 요금이 리전이 아니라 엣지 지역별로 나뉜다. 도쿄는 JP, 프랑크푸르트는 EU, 서울·싱가포르는 AP 접두사를 쓴다.

WordPress 템플릿

블로그를 만들고 싶은 사람이 가장 많을 것 같아서 추가했다.

• Lightsail WordPress (처음이라면 추천): WordPress가 설치된 월 정액 서버
• EC2 단독: 서버 한 대에 WordPress와 MySQL을 직접 설치
• EC2 + RDS: 중규모는 웹 서버 2대 + 로드밸런서

블로그는 보통 도메인을 쓰니까, 이 템플릿만 도메인을 기본 '포함'으로 했다.

구성 다이어그램

"EC2 + RDS + ALB가 어떻게 연결되는지" 그림으로 보여준다. 사용자 → 로드밸런서 → EC2 → RDS 흐름을 상자로 그리고, 상자마다 그 부분의 월 비용을 적는다.

• 템플릿마다 그림을 따로 만들지 않고, 구성안의 리소스 목록을 보고 자동으로 그린다.
• 퍼블릭 IPv4와 NAT는 주황색 꼬리표로 눈에 띄게 했다.
• 테스트에서 그림 속 비용을 전부 더하면 카드의 합계와 정확히 같은지 모든 템플릿·규모·구성안에 대해 확인한다. 그림과 숫자가 어긋나면 그림이 오히려 오해를 만들기 때문이다.

5. 그리고, 덜어내기

여기까지 하고 휴대폰으로 결과 화면을 열어봤다.

• 위쪽에 선택 칩 3줄 (규모 3개, 리전 6개, 도메인 2개)
• 공유 버튼
• 요약 + 추천 + 막대 그래프
• 값 바꾸기 칸 최대 10개
• 카드마다 세로로 긴 다이어그램
• 경고 칩 최대 5개

"기능이 많아서 오히려 쓰기 꺼려진다"는 반응이 나올 만했다. 이 서비스의 목적은 기능을 많이 담는 게 아니라 AWS를 잘 모르는 사람이 쉽게 쓰는 것이다.

그래서 기능은 하나도 빼지 않고, 처음 보이는 양만 줄였다.

• 템플릿마다 "핵심 칸 3개"를 데이터로 정했다. 예를 들어 개발 서버는 사양 · 켜두는 시간 · 전송량이다.
• 숨겨둔 칸의 값을 바꾼 공유 링크를 열면 "더 보기"가 자동으로 펼쳐진다. 바뀐 값이 숨어 있으면 안 되니까.

그리고 큰 기능 대신 4줄짜리 안내를 하나 넣었다. 요금 폭탄은 대부분 이 네 가지를 놓쳐서 생기기 때문이다.

만든 다음 꼭 할 일

1. 예산 알림부터 켜기 (AWS Budgets)
2. 안 쓰면 '중지'보다 '삭제' (Lightsail·NAT·로드밸런서는 켜두기만 해도 과금)
3. 다 쓴 뒤 남은 것 정리 (퍼블릭 IP·스냅샷·디스크)
4. 첫 달 청구서 확인

계획해뒀던 기능 이슈 중 세 개는 하지 않기로 하고 닫았다.

• 결과 이미지 저장: 공유 링크로 충분하고, 버튼만 하나 더 늘어난다.
• 컨테이너 앱 템플릿: 도커·ECS는 입문자 대상이 아니다.
• 환율 자동 갱신: 고정 환율과 기준일 표시로 충분하다.

숫자로 보면

• 템플릿 5종, 리전 6곳, 직접 계산 서비스 16종, 용어 41개
• 테스트: JavaScript 39개 + 가격 수집 스크립트 Python 8개 (외부 패키지 없음)
• 여전히 빌드 없는 순수 HTML/CSS/JS, 운영비 0원 (GitHub Pages)

다음에 할 것

• 공식 Pricing Calculator 교차 검증: 대표 조합 5개부터 직접 비교해볼 예정이다.
• 프리티어 반영: 입문자에게 정말 유용하지만 정책이 자주 바뀌어서 보류 중이다.
• AI 챗봇 + Bedrock 템플릿: 관심은 많지만 토큰 요금은 입문자에게 어렵다. 의견이 쌓이면 결정하려 한다.

마무리

하루 동안 기능을 잔뜩 붙이고 나서야 알았다. 초보자를 위한 도구에서 기능 하나를 더하는 건, 그 사람이 읽어야 할 것을 하나 더 늘리는 일이기도 하다.

그래서 앞으로 기능을 넣을 때마다 이렇게 물어보려고 한다. "이게 처음 AWS를 쓰는 사람한테 꼭 필요한가?"

이번에도 개발은 Claude Code(AI 코딩 에이전트)와 함께 했다. 무엇을 넣고 뺄지는 하나씩 확인하며 결정했다.

👉 https://dlwldp.github.io/Awscal/ 에서 써보고, 사이트의 "의견 보내기"로 피드백 주시면 감사하겠습니다!

🔗 사이트: https://dlwldp.github.io/Awscal/ 🔗 GitHub: https://github.com/dlwldP/Awscal

왜 만들었나

처음 AWS에 뭔가를 올려보려고 할 때마다 같은 벽에 부딪혔다.

• 공식 Pricing Calculator는 서비스 이름을 알아야 쓸 수 있다. "Spring Boot 앱 하나 띄우려면 뭐가 필요하지?"부터 모르는 상태에선 어디서부터 입력해야 할지 모른다.
• 단위가 어렵다. vCPU-시간, GB-월, LCU, 100만 건당…
• 숨은 비용을 모르고 지나친다. 퍼블릭 IPv4, NAT Gateway, 데이터 전송량 같은 건 막상 청구서를 받고 나서야 알게 된다.

그래서 "하고 싶은 것"을 고르면 필요한 구성과 월 비용을 쉽게 비교해주는 계산기를 만들었다. AWS 계정 연동 없이, 누구나 바로 쓸 수 있게.

무엇을 할 수 있나

1. 구성 추천 — 목적만 고르면 구성 2~3가지를 비교

정적 웹사이트 / 백엔드 웹앱 / 서버리스 API / 개발용 단일 서버 중 하나를 고르고, 규모(개인용·소규모·중규모)와 리전(서울·버지니아)을 고르면 끝이다. 결과까지 2번만 클릭하면 된다.

예를 들어 "백엔드 웹앱 · 개인용 · 서울"을 고르면 이렇게 나온다.

같은 일을 하는데 5배 가까이 차이가 난다. 물론 Lightsail은 DB를 서버에 직접 설치해야 하는 등 트레이드오프가 있어서, 구성마다 장점·단점도 같이 보여준다.

2. "이 비용은 왜 나오나요?"

각 항목을 누르면 왜 이 비용이 나오는지 한 줄 설명과 계산식이 나온다. 그리고 놓치기 쉬운 비용은 숨은 비용 경고로 따로 표시한다.

직접 만들면서 다시 정리한 숨은 비용들 (서울 리전 기준):

3. 값 직접 바꿔보기

프리셋이 내 상황과 딱 맞진 않으니까, 결과 화면에서 서버 사양·대수·트래픽 같은 값을 바꾸면 바로 다시 계산되게 했다.

4. 직접 계산하기

쓸 서비스를 이미 안다면 서비스를 하나씩 담아서 계산할 수 있다. EC2, RDS, S3, Lambda, NAT Gateway 등 15종을 지원하고, "평일 낮에만 켜두기(월 176시간)" 같은 사용 시간도 넣을 수 있다. 구성 추천 결과를 그대로 계산기로 가져와서 이어서 조정할 수도 있다.

기술 스택: 최대한 단순하게

처음 기획에선 React + Vite + TypeScript + Tailwind를 쓰려고 했다. 그런데 계산은 전부 브라우저에서 할 수 있고, 화면도 몇 개 안 된다. 가장 쉬운 스택으로 가기로 하고 프레임워크를 빼버렸다. 결과적으로 index.html 하나에 JS 모듈 몇 개, 그리고 JSON 데이터 파일이 전부다.

백엔드가 없다는 게 핵심이다. 서버 비용도, 보안 걱정도, API 키도 없다. AWS 비용 계산기를 만들면서 정작 운영비는 0원이다.

[GitHub Actions 주 1회] → AWS 가격 받아서 prices.json 갱신 → 커밋 → 배포
[브라우저] templates.json + prices.json → 계산 엔진 → 화면

가격 데이터는 어디서? — AWS Price List Bulk API

AWS는 모든 서비스의 가격표를 인증 없이 받을 수 있는 공개 파일로 제공한다.

https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/{서비스}/current/{리전}/index.csv

문제는 크기다. EC2 가격 파일 하나가 서울 리전만 약 300MB, 버지니아는 480MB다. 내가 필요한 건 그중 t4g.small 시간당 가격 같은 숫자 몇십 개뿐이다.

그래서 수집 스크립트는 이렇게 만들었다.

1. CSV를 스트리밍으로 한 줄씩 읽는다 (메모리에 통째로 올리지 않음)
2. 필요한 항목만 적어둔 화이트리스트와 맞는 행만 남긴다
3. 수십 KB짜리 prices.json을 만든다

def stream_csv(url):
    resp = urllib.request.urlopen(url, timeout=600)
    text = io.TextIOWrapper(resp, encoding="utf-8", newline="")
    for _ in range(5):  # 메타데이터 줄 건너뛰기
        text.readline()
    yield from csv.DictReader(text)

외부 패키지 없이 표준 라이브러리만 써서, 두 리전 전체를 약 30초에 처리한다.

삽질 기록

① us-east-1만 usageType에 리전 접두사가 없다

서울은 APN2-ReadRequestUnits처럼 리전 접두사가 붙는데, 버지니아는 그냥 ReadRequestUnits다. 처음엔 "대문자 접두사가 붙어 있으면 리전 접두사"로 처리했다. 그랬더니 IA-ReadRequestUnits(DynamoDB 저빈도 액세스 테이블)까지 같은 항목으로 잡혀서 가격이 두 개가 나왔다. 결국 리전별 접두사를 명시(APN2, USE1)하는 방식으로 바꿨다.

② 애매하면 실패하게

같은 항목에 가격이 두 개 잡히거나 못 찾으면 스크립트가 에러로 멈추게 했다. 매주 자동으로 돌아가는 작업이라 조용히 틀린 값이 들어가는 게 제일 무섭다. 실패하면 커밋을 안 하니 기존 가격이 그대로 남는다.

③ Lightsail은 744시간

Lightsail 1GB 번들의 시간당 가격은 $0.0094다. 730시간을 곱하면 $6.86인데 실제 번들 가격은 $7이다. 알고 보니 Lightsail은 31일(744시간) 기준 월 정액이고, 시간당 가격은 잘려서 공개된다 (0.0094 × 744 = 6.9936). 그래서 Lightsail만 744시간을 곱하고 센트 단위로 올림 처리했다.

④ CloudFront는 리전 파일이 아니라 글로벌 파일에

CloudFront 전송 요금은 리전이 아니라 사용자가 접속하는 엣지 위치(한국은 "Asia Pacific")에 따라 다르다. 그래서 리전별 파일에는 없고 글로벌 파일에서 찾아야 했다.

계산 엔진: 템플릿은 데이터로

계산 규칙은 단순하다.

• 한 달 = 730시간 (공식 계산기와 같은 기준)
• 시간 과금: 시간당 단가 × 사용 시간 × 수량
• 사용량 과금: 단위 단가 × 사용량

중요하게 생각한 건 템플릿을 추가할 때 계산 코드를 고치지 않아도 되게 하는 것이었다. 구성은 전부 JSON으로 정의하고, {{preset.이름}} 자리에 프리셋 값이 들어간다.

{
  "id": "ec2-rds",
  "name": "EC2 + RDS",
  "resources": [
    { "type": "ec2", "instance": "{{preset.instance}}", "count": "{{preset.count}}" },
    { "type": "publicIpv4", "count": "{{preset.count}}" },
    { "type": "alb", "count": "{{preset.albCount}}", "lcu": "{{preset.albLcu}}" },
    { "type": "publicIpv4", "count": "{{preset.albCount}}", "multiplier": 2 },
    { "type": "rds", "instance": "{{preset.dbInstance}}", "storageGb": "{{preset.dbStorageGb}}" },
    { "type": "dataTransferOut", "gb": "{{preset.egressGb}}" }
  ]
}

엔진은 리소스 타입별 계산 함수(ec2, rds, lambda, …)만 갖고 있다. 각 함수는 금액, 계산식, "왜 나오는지" 설명, 숨은 비용 경고를 함께 돌려준다. 직접 계산기도 같은 엔진을 쓴다.

가격 데이터에 값이 없으면 0원으로 넘어가지 않고 에러를 낸다. 계산기에서 "$0.00"이 나오는 버그가 제일 위험하다고 봤다.

배포: GitHub Pages + GitHub Actions

정적 파일뿐이라 GitHub Pages로 충분했다. 워크플로는 두 개다.

• deploy.yml: main에 푸시하면 테스트 → Pages 배포
• update-prices.yml: 매주 월요일 09:00(KST)에 가격 수집 → 테스트 → 커밋 → 배포

여기서 하나 걸렸다. GITHUB_TOKEN으로 한 푸시는 다른 워크플로를 트리거하지 않는다. 가격 갱신 커밋을 올려도 배포 워크플로가 안 돈다. 그래서 배포 워크플로를 workflow_call로 재사용하게 만들고, 가격 갱신 워크플로가 끝나면 직접 호출하게 했다.

deploy:
  needs: update
  uses: ./.github/workflows/deploy.yml

재사용 워크플로 안에서 checkout을 그냥 하면 커밋 전 SHA를 받아온다. 그래서 ref: ${{ github.ref_name }}으로 최신 main을 받게 했다.

처음엔 서비스 주제에 맞춰 S3 + CloudFront로 배포하려 했다. 그런데 정적 사이트라 GitHub Pages로 충분하고, AWS 자격증명을 관리할 필요도 없어서 Pages로 결정했다.

디자인: 토스처럼

AWS가 어려운 사람이 대상이라 한 화면에 하나씩, 큰 숫자로 보여주는 데 집중했다.

• 흰 카드 + 파란 포인트 색, 한 줄 레이아웃
• 결과 맨 위에 "가장 저렴한 건 ○○예요, 월 $7.00"
• 자세한 내역·장단점은 접어두고 필요할 때만 펼치기
• 어려운 용어 옆에는 쉬운 설명 ("t4g는 ARM(더 저렴), t3는 x86이에요")

디자인하다 만난 버그: 클릭이 사라진다

"값 직접 바꿔보기"에서 숫자를 고친 뒤 바로 아래 "펼치기"를 누르면 첫 클릭이 무시되는 문제가 있었다.

원인은 이랬다. 숫자 칸에 input과 change 이벤트를 둘 다 걸어두었는데, 다른 곳을 클릭하는 순간 숫자 칸의 포커스가 빠지면서 change가 발생한다. 그 순간 결과 카드를 다시 그리면서 내가 누르려던 버튼이 새 요소로 바뀌어버린 것이다.

숫자 칸은 input에서만, 선택 칸은 change에서만 다시 계산하게 바꿔서 해결했다. 그리고 다시 그릴 때 펼쳐둔 카드가 닫히지 않도록 열림 상태를 기억했다가 되살리게 했다.

테스트

• node --test로 계산 엔진 단위 테스트 25개 (외부 패키지 없음)
• 모든 템플릿 × 프리셋 × 리전에서 결과가 나오는지
• 규모가 커지면 비용도 커지는지
• 가격 데이터가 없으면 0원이 아니라 에러가 나는지
• 모든 프리셋 사용량이 첫 요금 구간 안에 있는지
  • S3, 데이터 전송처럼 구간별로 단가가 달라지는 요금은 첫 구간 단가만 쓰도록 단순화했다. 프리셋이 첫 구간을 넘지 않으면 이 단순화로 생기는 오차가 0이 된다.
• 직접 계산기의 입력 칸 정의와 엔진이 서로 맞는지

한계와 다음 계획

이 계산기는 예상치다. 일부러 단순화한 부분이 있다.

• 프리티어·크레딧은 반영하지 않는다. 신규 계정은 실제로 더 적게 나올 수 있다.
• 구간 요금은 첫 구간 단가만 쓴다 (넘으면 화면에서 알려준다).
• Lightsail 번들의 전송 허용량 초과분은 계산하지 않는다.
• 공식 Pricing Calculator와 ±10% 이내인지 확인하는 교차 검증 체크리스트를 만들어 두었고, 하나씩 확인하는 중이다.

다음에 해보고 싶은 것들은 GitHub 이슈로 정리해뒀다.

• 결과 공유 URL, 이미지로 저장
• 구성 다이어그램 자동 생성
• "이 구성 만들기" 단계별 가이드
• 템플릿 추가: WordPress, 컨테이너 앱, AI 챗봇 + Bedrock
• 환율 자동 갱신

마무리

AWS 비용이 어려운 이유는 계산이 복잡해서라기보다, 무엇이 필요한지 모르고, 무엇이 숨어 있는지 모르기 때문이라고 생각한다. 이 계산기가 처음 AWS에 뭔가를 올려보려는 사람에게 "생각보다 별거 아니네" 혹은 "아, 이건 조심해야겠다"를 알려주는 도구가 됐으면 좋겠다.

개발은 Claude Code(AI 코딩 에이전트)와 함께 진행했다. 기획서를 주고, 스택·배포 방식·프리셋 수치 같은 결정은 하나씩 확인하며 만들었다.

👉 https://dlwldp.github.io/Awscal/ 에서 써보고 피드백 주시면 감사하겠습니다!

"왜 이 파드가 죽어?"라고 물으면, 에이전트가 조회만 해서 원인 후보와 근거를 보여주는 도구를 만들었다.

들어가며

쿠버네티스에서 장애가 나면 늘 같은 루틴을 반복한다.

kubectl get pods
kubectl describe pod ...
kubectl logs ... --previous
kubectl get events --sort-by=.lastTimestamp

명령어 네 개를 오가면서 단서를 머릿속으로 이어 붙여야 한다. 익숙하면 금방이지만, 주니어 시절의 나는 어디부터 봐야 할지를 몰랐다.

그래서 이걸 LLM 에이전트에게 맡기는 도구를 기획했다. 다만 조건을 세 가지 걸었다.

1. 실행 권한 없음: 에이전트는 조회만 한다. apply, delete, exec, scale은 존재조차 하지 않는다.
2. 증거 없는 주장 금지: 모든 결론에는 실제 조회 결과(증거) 링크가 붙어야 한다.
3. 정확도를 숫자로: 정해진 장애 시나리오로 맞혔는지 자동 채점한다.

LLM이 "그럴듯한 헛소리"를 하는 걸 막는 게 이 프로젝트의 핵심이다.

기획: 범위를 먼저 못 박기

바이브코딩(AI와 함께 코딩)으로 진행할 생각이라 기획서를 먼저 꼼꼼하게 썼다. AI는 "편의상" 기능을 붙이려는 경향이 있어서, 하지 않을 것을 명시해 두는 게 중요했다.

Non-goals

• 클러스터 상태를 바꾸는 모든 동작
• Secret 조회
• 인증·멀티테넌시 (로컬 단일 사용자 전제)

그리고 CLAUDE.md에 작업 규칙을 적었다.

- 기획서가 단일 진실 공급원이다.
- 절대 금지: 클러스터 상태를 변경하는 코드, secrets 조회, kubectl 셸 실행.
- 도구 추가·변경은 사람이 기획서를 먼저 고친 뒤에만 한다.
- 한 번에 한 Phase만 작업한다. 완료 조건을 확인한 뒤 멈춘다.

기술 스택

개발 단계

Phase를 7개로 나눴다. 가장 신경 쓴 건 평가 하네스(Phase 3)를 UI(Phase 5)보다 먼저 만드는 것이었다. 프롬프트나 도구를 고칠 때마다 정확도가 떨어졌는지 바로 알 수 있어야, "고쳤더니 다른 게 망가짐"을 막을 수 있다.

Phase 0: 장애를 일부러 만들기

평가하려면 정답이 있는 장애가 필요하다. kind 클러스터에 일부러 망가진 Deployment 6개를 띄웠다.

S1 로그에는 일부러 가짜 키(api_key=kl-fake-...)를 남겨 뒀다. 마스킹이 제대로 되는지 평가할 때 같이 검사하기 위해서다.

chaos/expected.yaml이 곧 평가 정답지다.

- id: S1
  question: "kubelens-chaos 네임스페이스의 payment-api가 계속 재시작돼. 왜 그래?"
  must_match:
    - ["DB_HOST"]
    - ["환경변수", "환경 변수", "environment variable", "env"]
  must_not_appear:
    - "kl-fake-0000000000000000"

must_match는 그룹 리스트다. 모든 그룹이 충족되어야 적중이고, 그룹 안에서는 대안 중 하나만 나오면 된다.

Phase 1: "Read-only by construction"

이 프로젝트에서 가장 공들인 부분이다. "조회만 한다"를 약속이 아니라 구조로 보장하고 싶었다.

1층: RBAC

앱 전용 ServiceAccount에는 get/list 권한만 준다. secrets, configmaps, pods/exec는 아예 빠져 있다.

rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log", "events", "nodes", "namespaces", "services"]
    verbs: ["get", "list"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets"]
    verbs: ["get", "list"]

kubectl auth can-i로 허용 9개, 차단 9개 항목을 자동 검사하는 스크립트도 만들었다.

2층: get/list만 노출하는 래퍼

도구는 kubernetes client의 CoreV1Api를 직접 만지지 않는다. 조회 메서드만 정의된 ReadOnlyKube를 거친다.

class ReadOnlyKube:
    """allowlist된 조회 메서드만 노출하는 래퍼."""

    __slots__ = ("_core", "_apps", "_version")

    def list_pod(self, namespace: str, label_selector: str | None = None): ...
    def read_pod(self, namespace: str, name: str): ...
    def read_pod_log(self, namespace, name, *, container, previous, tail_lines): ...
    # create_ / delete_ / patch_ 같은 건 아예 없다

__slots__를 써서 원본 API 객체로 우회할 속성을 붙일 수 없게 했다.

3층: 테스트가 소스를 검사한다

AST로 도구 레이어 소스를 훑어서 금지된 호출이 없는지 검사한다.

FORBIDDEN_CALL_PREFIXES = ("create_", "delete_", "patch_", "replace_", "connect_")
FORBIDDEN_IMPORTS = {"subprocess", "os.system", "kubernetes.stream", "shlex", "pty"}

나중에 누가(AI 포함) 편의상 쓰기 API를 넣으면 테스트가 바로 빨간불을 띄운다.

마스킹 → 절단 순서

모든 도구 출력은 마스킹을 먼저 하고, 그다음 4,000자로 절단한다. 순서를 반대로 하면 비밀값이 절단 경계에 걸려 password=hunt처럼 반쪽만 남는다. 그러면 마스킹 패턴을 피해 갈 수 있다.

절단할 때는 앞 30%와 뒤 70%를 남긴다. 표 헤더는 앞에 있고, 장애 원인은 보통 로그 끝에 있기 때문이다.

트러블슈팅: 마스킹이 내 출력을 먹었다

파드의 env를 보여줄 때 secret 참조는 값을 읽지 않고 이렇게 표시하려고 했다.

DB_PASSWORD=<secret db key password, value not read>

그런데 테스트가 실패했다. 출력이 DB_PASSWORD=***로 바뀌어 있었다. 내가 만든 마스킹 정규식(password=...)이 안내 문구까지 비밀값으로 보고 가려 버린 것이다. 형식을 DB_PASSWORD from secret db key password (value not read)로 바꿔서 해결했다. 마스킹은 생각보다 넓게 먹는다.

Phase 2: LangGraph 에이전트

그래프는 기획서 그대로 만들었다.

질문 → plan → tool_loop(agent ⇄ tools, 최대 8회) → synthesize → validate → 결과
                                                          └ 증거 없음 → 1회 재생성

증거 링크 검증

도구를 호출할 때마다 tc_1, tc_2 같은 ID를 붙여서 LLM에 돌려준다.

[evidence_id: tc_3]
# logs kubelens-chaos/payment-api-xxx previous=True tail=200
INFO starting payment-api v1.4.2
DEBUG loaded config api_key=***
FATAL required environment variable DB_HOST is not set

최종 보고서의 모든 원인 후보는 evidence_refs에 실제로 존재하는 ID를 하나 이상 넣어야 한다. 비어 있거나 없는 ID를 대면 피드백과 함께 1회 재생성하고, 그래도 안 되면 실패로 표시한다.

def validate_diagnosis(diagnosis, evidence) -> list[str]:
    known = {e.id for e in evidence}
    for cause in diagnosis.root_causes:
        if not cause.evidence_refs:
            errors.append("evidence_refs가 비어 있음")
        elif unknown := [r for r in cause.evidence_refs if r not in known]:
            errors.append(f"존재하지 않는 evidence_id {unknown}")

트러블슈팅: 강제 tool call이 막힌 모델

LangChain의 with_structured_output()은 기본적으로 강제 tool call로 구조화 출력을 받는다. 그런데 Sonnet 5.5에서는 tool_choice를 any나 tool로 강제하면 400 에러가 난다.

그래서 두 가지로 우회했다.

• 도구 루프는 tool_choice: auto로 두고 프롬프트로 유도한다.
• 최종 보고서는 method="json_schema"로 받는다(API의 output_config.format).

synthesizer = chat.with_structured_output(
    Diagnosis, method="json_schema", include_raw=True
)

include_raw=True로 원본 응답도 함께 받아서, 모델이 응답을 거부(stop_reason == "refusal")했거나 파싱에 실패했으면 명확한 에러로 처리했다.

도구 정의는 한 곳에서만

LLM에 넘기는 도구 JSON Schema를 손으로 따로 쓰지 않았다. Phase 1 도구 함수의 시그니처와 타입 힌트에서 자동 생성한다. 도구 allowlist의 출처가 하나라서, 도구 목록과 LLM 도구 정의가 어긋날 일이 없다.

Phase 3: 평가 하네스

make eval 한 줄로 S1~S6을 실제 에이전트로 진단하고 채점한다.

• 1순위 원인 후보(제목+설명)에 정답 키워드 그룹이 모두 있으면 적중
• 증거 검증 실패면 오답
• 최종 출력이나 LLM에 넘어간 도구 출력에 비밀값이 있으면 오답
• 도구 호출 수, 응답 시간, 토큰 비용도 함께 집계

목표는 6개 중 5개 이상 1순위 적중 + 모든 원인 후보에 증거 링크다.

실제 LLM 평가는 비용이 들어서 CI에서 push마다 돌리지 않고, GitHub Actions의 Run workflow로 수동 실행할 때만 돌게 했다.

⚠️ 이 글을 쓰는 시점에는 아직 실제 LLM으로 평가를 돌리지 않았다. 결과 표는 다음 글에서 공개할 예정이다.

Phase 4: FastAPI + SSE

질문을 보내면 SSE로 진행 상황이 실시간으로 흘러온다.

event: thinking    → 조사 계획 수립 중
event: tool_start  → list_pods 실행
event: tool_end    → 12ms, ok
...
event: final       → 진단 결과 JSON

LangGraph는 동기로 돌기 때문에 워커 스레드에서 실행하고, 이벤트는 loop.call_soon_threadsafe로 asyncio 큐에 넣어서 스트리밍했다.

에이전트 내부 ID(tc_3)는 DB에 저장할 때 ToolCall.id로 바꿔서 저장한다. 그래서 진단 결과의 증거 링크가 곧 DB의 도구 호출 기록을 가리키고, 새로고침해도 증거를 다시 열 수 있다.

도구 출력 원문은 SSE로 보내지 않는다. 트레이스에는 도구명·인자·소요시간만 흘리고, 원문은 증거를 클릭했을 때 API로 따로 조회한다.

트러블슈팅: DetachedInstanceError

SQLModel 세션에서 클러스터 객체를 꺼낸 뒤 워커 스레드에서 속성을 읽으려다 이 에러를 만났다.

DetachedInstanceError: Instance <Cluster> is not bound to a Session

commit()하면 객체 속성이 만료(expire)되는데, 세션을 닫은 뒤 다른 스레드에서 접근하니 다시 불러올 수가 없었던 것이다. 필요한 값(kubeconfig_path, context)만 커밋 전에 지역 변수로 꺼내 두는 방식으로 해결했다.

Phase 5: React UI

화면은 3개다.

1. 클러스터 설정: kubeconfig context 선택 → 연결 테스트(서버 버전 표시) → 저장
2. 진단 화면: 왼쪽 세션 목록 / 가운데 대화와 진단 카드 / 오른쪽 실시간 도구 트레이스
3. 증거 모달: 도구명·인자·마스킹된 원본 출력·절단 여부

SSE가 POST 요청이라 EventSource를 쓸 수 없었다. 그래서 fetch 스트림을 직접 읽어서 \n\n 단위로 파싱했다.

빌드된 UI는 FastAPI가 같이 서빙한다. make setup → make api 두 줄이면 브라우저에서 바로 쓸 수 있다.

테스트 전략: API 키 없이 어디까지 검증할까

LLM이 들어간 시스템은 테스트가 까다롭다. 매번 실제 모델을 부르면 비용이 들고 결과도 매번 다르다. 그래서 가짜 LLM을 만들었다. 정해진 대본대로 도구를 호출하고, 받은 증거 ID를 그대로 인용해 보고서를 만든다.

이걸 팩토리 주입으로 갈아 끼울 수 있게 했다.

KUBELENS_LLM_FACTORY=tests.fake_llms:scripted_llms \
  uv run uvicorn kubelens.api.app:app

덕분에 CI에서 실제 kind 클러스터 + 가짜 LLM 조합으로 전체 흐름을 검증할 수 있다.

Playwright e2e는 클러스터 설정 → 질문 → 트레이스 → 진단 카드 → 증거 모달 → 새로고침 후 기록 유지까지 확인한다.

트러블슈팅: 클라우드 개발 환경에서 kind가 안 뜬다

원격 개발 환경에서 kind create cluster를 하니 control-plane이 뜨지 않았다.

runc create failed: unable to start container process:
can't get final child's PID from pipe: EOF

컨테이너 안에서 다시 컨테이너를 띄우는 중첩 구조라 runc가 실패한 것이다. 로컬 검증을 포기하고 GitHub Actions에서 kind를 띄우는 CI를 만들었다. 결과적으로 이게 더 좋았다. 매 push마다 깨끗한 클러스터에서 처음부터 검증된다.

첫 CI는 kind 설치 단계에서 바로 실패했다. /usr/local/bin에 바로 쓰려면 sudo가 필요했다. 임시 폴더에 받은 뒤 sudo install로 바꿔 해결했다.

트러블슈팅: 데모 GIF 녹화

처음엔 Playwright의 동영상 녹화로 GIF를 만들려 했는데, 개발 환경에 Playwright가 요구하는 ffmpeg 버전이 없어서 영상 파일이 조용히 안 만들어졌다. 녹화 방식을 바꿔서 일정 간격으로 스크린샷을 찍고, 시스템 ffmpeg로 이어 붙이는 방식으로 해결했다. 환경 의존성이 줄어서 오히려 더 안정적이다.

현재 상태와 다음 할 일

검증 완료 (CI, 실제 kind 클러스터)

• read-only RBAC, 장애 6종 재현, 도구 8개, 마스킹·절단
• 에이전트 그래프 흐름(가짜 LLM), API·SSE, UI 전체 흐름

남은 것

• 실제 Claude 호출로 S1~S6 정확도 측정 (make eval)
• 브라우저에서 S1~S3 직접 확인
• 실제 진단 화면으로 데모 GIF 만들기

회고

• "하지 않을 것"을 먼저 적은 게 가장 효과적이었다. AI와 함께 개발할 때 범위가 새는 걸 막아 줬다.
• 안전은 약속보다 구조로. RBAC, 래퍼, 소스 검사 테스트로 세 겹을 쌓으니 "정말 조회만 하나?"라는 질문에 코드로 답할 수 있게 됐다.
• LLM 시스템도 테스트할 수 있다. 가짜 LLM을 주입하면 비싼 모델 호출 없이도 배선은 거의 다 검증된다. 남는 건 "답이 맞느냐"뿐이고, 그건 평가 하네스의 몫이다.
• 평가를 먼저 만들기. 아직 숫자는 없지만, 프롬프트를 고칠 준비는 끝났다.

다음 글에서는 실제 평가 결과와 프롬프트 튜닝 과정을 정리해 보겠다.

시리즈: Subhelp — iOS 구독 관리 앱 개발기 이번 글: 계정 삭제 요건, Supabase Edge Function, 비밀 키 관리, 개인정보 라벨, 회고

계정 삭제는 선택이 아니다

App Store는 계정을 만들 수 있는 앱이라면 앱 안에서 계정 삭제 기능을 제공하라고 요구합니다. Apple 로그인을 쓴다면 삭제할 때 Apple 토큰도 철회해야 합니다. 빠지면 심사에서 거절될 수 있습니다.

토큰을 철회하지 않으면 사용자의 Apple ID에는 "이 앱에 Apple로 로그인함" 연결이 계속 남습니다.

왜 Edge Function이 필요했나

토큰 철회 요청에는 Apple 개인 키(.p8)로 서명한 client_secret이 필요합니다. 이 키를 앱에 넣으면 누구나 앱 파일에서 꺼낼 수 있습니다.

그래서 키는 Supabase Edge Function(서버)에만 두었습니다. Edge Function은 Supabase 안에서 실행되는 작은 서버 코드(Deno/TypeScript)라 따로 서버를 운영하지 않아도 됩니다.

흐름

설정 > 계정 삭제 > 확인
 → Apple로 한 번 더 확인 (일회용 authorizationCode 획득)
 → Edge Function `delete-account` 호출
     1) Authorization 헤더로 요청한 사용자 확인
     2) authorizationCode → Apple에서 토큰 교환 → 토큰 철회
     3) Supabase 계정 삭제 (구독은 on delete cascade로 함께 삭제)

삭제 직전에 Apple 확인을 한 번 더 받는 이유는, 철회에 필요한 authorizationCode가 일회용이라 로그인 시점의 코드를 쓸 수 없기 때문입니다. 많은 앱에 "계정을 삭제하려면 다시 로그인해주세요" 단계가 있는 이유입니다.

Apple client_secret 만들기

import { importPKCS8, SignJWT } from "npm:jose@5";

async function makeClientSecret(clientId: string): Promise<string> {
  const key = await importPKCS8(requireEnv("APPLE_PRIVATE_KEY"), "ES256");
  const now = Math.floor(Date.now() / 1000);
  return await new SignJWT({})
    .setProtectedHeader({ alg: "ES256", kid: requireEnv("APPLE_KEY_ID") })
    .setIssuer(requireEnv("APPLE_TEAM_ID"))
    .setIssuedAt(now)
    .setExpirationTime(now + 300)            // 5분만 유효
    .setAudience("https://appleid.apple.com")
    .setSubject(clientId)                    // 앱 번들 ID
    .sign(key);
}

토큰 교환 → 철회

const tokenResponse = await postForm("https://appleid.apple.com/auth/token", {
  client_id: clientId,
  client_secret: clientSecret,
  code: authorizationCode,
  grant_type: "authorization_code",
});
const tokens = await tokenResponse.json();

await postForm("https://appleid.apple.com/auth/revoke", {
  client_id: clientId,
  client_secret: clientSecret,
  token: tokens.refresh_token ?? tokens.access_token,
  token_type_hint: tokens.refresh_token ? "refresh_token" : "access_token",
});

설계에서 정한 것

• Apple 철회가 실패해도 사용자의 삭제 요청은 처리한다. 결과는 응답의 appleTokenRevoked로 따로 알리고 함수 로그에 남긴다
• 함수가 아직 배포되지 않았거나 호출에 실패하면, 앱은 DB 함수 delete_account()로 계정만 삭제한다 (Apple 철회 생략)
• 계정 삭제는 사용자 권한으로 할 수 없어서 함수 안에서만 service_role 키로 삭제한다. 이 키는 Supabase가 함수에 자동으로 넣어주므로 저장소 어디에도 없다

Edge Function도 CI로 검사

CI에 Deno 작업을 추가해서 배포 전에 문법 오류를 잡습니다.

edge-functions:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: denoland/setup-deno@v2
    - run: |
        deno check supabase/functions/delete-account/index.ts
        deno lint supabase/functions/
        deno fmt --check --line-width 120 supabase/functions/

비밀 키 관리 원칙

• 커밋되는 설정 파일(Base.xcconfig, *.example)에는 빈 값과 예시 값만 둔다
• .gitignore: Config/Local.xcconfig, supabase/functions/.env, *.p8, *.p12, *.mobileprovision
• Info.plist·entitlements는 $(SUPABASE_URL) 같은 변수만 참조하고, 실제 값은 빌드할 때 채워진다
• 서버 설정이 비어 있으면 서버 코드는 아예 동작하지 않는다

개인정보 라벨도 바뀐다

로그인 기능이 생기면서 "데이터 수집 안 함"이 아니게 됐습니다. PrivacyInfo.xcprivacy에 수집 항목을 선언했고, App Store Connect 개인정보 라벨에도 같게 적어야 합니다.

로그인을 선택 기능으로 둔 것도 이 때문입니다. 로그인하지 않으면 데이터는 여전히 기기에만 남습니다.

회고

잘한 것

• 계산 로직을 Domain의 순수 함수로 분리하고 테스트를 먼저 붙였다. 결제일 계산, 무료체험 규칙, 통계, 동기화 병합 규칙까지 총 38개 테스트가 있다. 나중에 바뀐 요구사항(무료체험 규칙 등)도 테스트로 바로 확인할 수 있었다
• 서버를 "선택"으로 붙였다. 설정 값이 없으면 서버 코드가 아예 돌지 않아서, 로컬 앱의 안정성을 해치지 않는다
• CI를 처음부터 붙였다. type-check 시간 초과처럼 로컬에서 놓치기 쉬운 문제를 push 직후에 잡았다
• 비밀 값은 처음부터 변수로 분리했다. 저장소 전체 기록을 검사해도 실제 키 값이 없다

아쉬운 것 / 남은 것

• CI는 시뮬레이터 빌드와 계산 로직까지만 검증한다. 실기기 알림, 위젯 갱신, 로그인·동기화, 계정 삭제는 직접 확인해야 한다
• Edge Function은 문법 검사만 통과했다. 실제 Apple 키로 배포한 뒤 철회까지 되는지 확인이 필요하다

다음 단계

• 실기기 테스트, TestFlight 배포
• 인터랙티브 위젯 (App Intents) — 위젯에서 바로 확인·체크
• 무료체험 종료 Live Activity
• 실시간 환율 API + 캐싱
• 서비스별 해지 링크 모음
• 공유 구독(가족 요금제 N빵) — Supabase 위에 확장

시리즈: Subhelp — iOS 구독 관리 앱 개발기 이번 글: 원격 프리셋, Apple 로그인, 동기화 규칙(Last-Write-Wins + Tombstone), 트러블슈팅 3가지

원칙: 로그인은 "선택"

기획 원칙은 "계정 없이 바로 쓴다"였습니다. 하지만 기기를 바꾸면 데이터가 사라지는 문제가 남아 있었습니다. 그래서 서버를 붙이되 로그인은 선택 기능으로 했습니다.

• 로그인하지 않아도 모든 기능이 동작한다
• Supabase 설정 값이 비어 있으면 서버 기능이 화면에서 아예 숨겨진다
• 로그인하면 구독이 서버에 백업되고 여러 기기에서 동기화된다
• 로그아웃하거나 계정을 삭제해도 이 기기의 구독은 남는다

enum SupabaseService {
    static let client: SupabaseClient? = {
        guard let url = AppConfig.supabaseURL, let key = AppConfig.supabaseAnonKey else { return nil }
        return SupabaseClient(supabaseURL: url, supabaseKey: key)
    }()
}

클라이언트는 공식 supabase-swift SDK를 XcodeGen packages로 추가했습니다. 인증 토큰 갱신·세션 저장을 SDK가 처리해 줍니다.

원격 프리셋

추가 화면의 프리셋을 서버(presets 테이블)에서 받아옵니다. 앱을 업데이트하지 않고도 프리셋을 추가·수정할 수 있습니다.

• 로그인 없이 누구나 읽기 가능 (RLS: to anon, authenticated using (is_active))
• 받은 목록은 기기에 캐시
• 서버가 없거나 실패하면 앱에 들어 있는 기본 프리셋 사용
• 모르는 카테고리가 오면 "기타"로 처리

DB 설계와 RLS

create table public.subscriptions (
  id                  uuid primary key,           -- 앱에서 만든 UUID 그대로 (기기 ↔ 서버 동일 ID)
  user_id             uuid not null default auth.uid()
                      references auth.users (id) on delete cascade,
  name                text not null,
  price               numeric(12, 2) not null check (price > 0),
  currency_code       text not null default 'KRW',
  cycle               text not null check (cycle in ('weekly', 'monthly', 'yearly')),
  cycle_interval      int  not null default 1,
  start_date          date not null,
  notify_days_before  int,
  is_active           boolean not null default true,
  trial_end_date      date,
  updated_at          timestamptz not null default now(),
  deleted_at          timestamptz                  -- 삭제 기록(tombstone)
  -- ...
);

alter table public.subscriptions enable row level security;

create policy "본인 구독 읽기" on public.subscriptions
  for select to authenticated using ((select auth.uid()) = user_id);
-- insert / update / delete도 같은 조건

앱에는 공개 키(anon)만 넣고, 데이터는 RLS(행 단위 보안)가 지킵니다. 다른 사람의 행은 읽을 수도, 쓸 수도 없습니다.

Apple 로그인

SignInWithAppleButton으로 Apple 인증을 받고, 그 ID 토큰으로 Supabase에 로그인합니다. 재전송 공격을 막기 위해 nonce를 씁니다.

func prepareAppleRequest(_ request: ASAuthorizationAppleIDRequest) {
    let nonce = Self.randomNonce()
    currentNonce = nonce
    request.requestedScopes = [.email]
    request.nonce = Self.sha256(nonce)          // Apple에는 해시를 보내고
}

// 완료 후
try await client.auth.signInWithIdToken(
    credentials: OpenIDConnectCredentials(provider: .apple, idToken: idToken, nonce: nonce)  // Supabase에는 원문
)

동기화 규칙: Last-Write-Wins + Tombstone

구독 수가 많지 않으니 매번 서버의 내 구독 전체를 받아 비교합니다. 마지막 동기화 시점을 관리하지 않아도 되어 단순하고 안전합니다.

비교 규칙은 순수 함수 SyncPlanner(Domain)로 분리해서 단위 테스트했습니다.

enum SyncPlanner {
    static func plan(local: [SyncRecord], remote: [SyncRecord], tombstones: Set<UUID>) -> SyncPlan
}

struct SyncPlan: Equatable {
    var push: Set<UUID> = []          // 기기 → 서버
    var apply: Set<UUID> = []         // 서버 → 기기
    var deleteLocal: Set<UUID> = []
    var deleteRemote: Set<UUID> = []
    var clearTombstones: Set<UUID> = []
}

왜 삭제할 때 서버 행을 바로 지우지 않나

기기 A에서 지운 구독을 서버에서도 바로 지우면, 기기 B는 "서버에 없는데 내 기기엔 있다 → 새로 만든 구독이구나" 하고 다시 업로드합니다. 그래서 행은 남기고 deleted_at만 표시해서, 다른 기기가 "삭제됐다"는 사실을 알 수 있게 했습니다.

이 기기에서 로그인 상태로 지운 구독은 DeletionTombstone이라는 작은 SwiftData 모델에 기록해 두고, 다음 동기화 때 서버에 삭제 표시를 남긴 뒤 정리합니다.

동기화 시점

• 로그인 직후, 앱 실행·포그라운드 복귀 때
• 구독을 바꾼 1.5초 뒤 (연속 수정은 하나로 묶음)

수정 시각(updatedAt)은 모든 수정 경로에서 빠짐없이 갱신되도록 touch() 하나로 모았습니다. SwiftData의 자동 저장이 먼저 돌면 "어떤 모델이 바뀌었는지" 정보를 잃을 수 있어서, 변경을 감지하는 대신 수정하는 곳에서 직접 표시하는 방식을 택했습니다.

트러블슈팅 1: 동기화할 때마다 업로드가 반복됨

Swift의 Date는 마이크로초 단위까지 갖고 있고, 서버에는 밀리초 단위로 저장했습니다. 그래서 업로드 직후에도 "기기 시각 .123456 > 서버 시각 .123"이 되어 매번 다시 업로드했습니다.

extension Date {
    var truncatedToMilliseconds: Date {
        Date(timeIntervalSince1970: (timeIntervalSince1970 * 1000).rounded(.down) / 1000)
    }
}

• 수정 시각을 저장할 때 밀리초로 자른다
• 서버 값을 기기에 반영할 때는 서버 시각을 그대로 쓴다
• 비교할 때도 1ms 이내 차이는 같은 것으로 본다

Postgres가 마이크로초(6자리)로 돌려줄 때도 있어서, 파싱 전에 소수점 아래를 3자리로 맞췄습니다.

트러블슈팅 2: "알림 끔"이 서버에 반영되지 않음

Swift의 기본 Codable은 nil 값을 키째 빼버립니다 (encodeIfPresent). upsert 요청에서 키가 빠지면 서버는 그 컬럼을 건드리지 않습니다. 그래서 알림을 꺼도(nil) 서버에는 이전 값이 그대로 남았습니다.

// nil도 null로 보내도록 직접 인코딩
func encode(to encoder: Encoder) throws {
    var container = encoder.container(keyedBy: CodingKeys.self)
    try container.encode(notifyDaysBefore, forKey: .notifyDaysBefore)   // nil → null
    try container.encode(trialEndDate, forKey: .trialEndDate)
    // ...
}

트러블슈팅 3: 가격 소수점 오차

numeric 컬럼은 JSON 숫자로 오는데, 이를 Decimal로 디코딩할 때 9.9900000001 같은 오차가 생길 수 있습니다. 소수 둘째 자리로 반올림했습니다.

var input = value, result = Decimal()
NSDecimalRound(&result, &input, 2, .plain)

날짜 형식

• 첫 결제일 같은 날짜는 date 컬럼("2026-10-13"), 기기 시간대 기준 자정으로 변환
• 수정 시각 같은 시각은 timestamptz(ISO 8601, UTC)

둘을 섞으면 시간대 때문에 날짜가 하루 밀릴 수 있어서 변환 함수를 따로 뒀습니다.

다음 글

계정 삭제와 Apple 토큰 철회(Edge Function), 그리고 비밀 키 관리 원칙을 다룹니다.

시리즈: Subhelp — iOS 구독 관리 앱 개발기 이번 글: 통계 탭(MVP 2), 결제 캘린더, 비싼 구독 순위, 연간 결제 예고, 정렬·필터, type-check 시간 초과 트러블슈팅

통계 기능

탭은 홈 / 구독 / 통계 / 설정 4개가 됐고, 홈에 있던 카테고리 차트는 통계 탭으로 옮겼습니다.

계산은 Domain에, 결과는 인덱스로

계산은 모두 InsightCalculator(Domain)에 넣었습니다. 결과를 SwiftData 모델 대신 입력 배열의 인덱스로 돌려줘서, Domain이 UI나 DB에 의존하지 않고 테스트할 수 있게 했습니다.

struct ScheduledPayment: Hashable {
    let planIndex: Int   // 입력 배열의 인덱스
    let date: Date
}

struct InsightCalculator {
    var billing: BillingCalculator
    var cost: CostCalculator

    func payments(in month: Date, of plans: [BillingPlan]) -> [ScheduledPayment]
    func ranking(of plans: [BillingPlan], limit: Int?) -> [RankedPlan]
    func upcomingRenewals(of plans: [BillingPlan], within days: Int = 30) -> [ScheduledPayment]
    func categoryTotals(of items: [(category: String, plan: BillingPlan)]) -> [CategoryTotal]
}

뷰에서는 subscriptions[payment.planIndex]로 원래 모델을 찾습니다.

규칙:

• 체험 중인 구독은 순위·카테고리 합계에서 제외
• 캘린더·연간 예고에는 체험 종료 이후의 결제만 표시
• "연간 결제" = 연결제, 또는 12개월 이상 간격의 월결제

결제 캘린더 직접 그리기

LazyVGrid 7열로 달력을 그렸습니다. 첫째 주 앞의 빈칸은 기기의 주 시작 요일(calendar.firstWeekday)에 맞춰 계산합니다.

private var gridDays: [Date?] {
    guard let interval = calendar.dateInterval(of: .month, for: month),
          let dayCount = calendar.range(of: .day, in: .month, for: month)?.count
    else { return [] }
    let firstWeekday = calendar.component(.weekday, from: interval.start)
    let leading = (firstWeekday - calendar.firstWeekday + 7) % 7
    let days = (0..<dayCount).compactMap { calendar.date(byAdding: .day, value: $0, to: interval.start) }
    return Array(repeating: nil, count: leading) + days.map { Optional($0) }
}

• 날짜 칸마다 결제가 있는 구독의 색 점을 최대 3개까지 표시
• 위쪽에 그 달의 결제 건수와 총액
• VoiceOver: "10월 15일, 결제 2건"

차트와 범례 색 맞추기

Swift Charts의 기본 색과 직접 만든 범례 목록의 색이 어긋났습니다. chartForegroundStyleScale로 순서대로 색을 지정해서 맞췄습니다.

Chart(categoryTotals) { item in
    SectorMark(angle: .value("금액", item.monthlyCost.doubleValue),
               innerRadius: .ratio(0.6), angularInset: 1.5)
        .foregroundStyle(by: .value("카테고리", item.category))
}
.chartForegroundStyleScale(domain: categoryTotals.map(\.category),
                           range: categoryTotals.indices.map(chartColor))

정렬·필터

• 툴바 메뉴에서 정렬(결제일순/금액순/이름순)과 카테고리 필터 선택
• 정렬 방식은 @AppStorage로 기억
• 필터가 켜져 있으면 목록 위에 "○○ 필터 해제" 버튼
• 금액순은 월 환산 기준(달러는 원화로 환산)

트러블슈팅: type-check 시간 초과

MVP 2 코드를 올렸더니 CI에서 빌드가 실패했습니다. 테스트가 아니라 컴파일 단계였습니다.

InsightCalculator.swift:30:9: error: the compiler is unable to type-check
this expression in reasonable time; try breaking up the expression into
distinct sub-expressions

원인은 이런 긴 체인이었습니다.

// ❌ 이전
plans.enumerated()
    .flatMap { index, plan in
        billing.paymentDates(in: month, plan).map { ScheduledPayment(planIndex: index, date: $0) }
    }
    .sorted { $0.date == $1.date ? $0.planIndex < $1.planIndex : $0.date < $1.date }

클로저의 타입을 명시하지 않은 상태에서 flatMap + map + sorted + 삼항연산자 + 비교 연산자가 겹치면, 컴파일러가 가능한 타입 조합을 너무 많이 시도합니다.

// ✅ 이후: 반복문 + 명시적 타입 + if
var result: [ScheduledPayment] = []
for (index, plan) in plans.enumerated() {
    for date in billing.paymentDates(in: month, plan) {
        result.append(ScheduledPayment(planIndex: index, date: date))
    }
}
result.sort { (lhs: ScheduledPayment, rhs: ScheduledPayment) -> Bool in
    if lhs.date != rhs.date { return lhs.date < rhs.date }
    return lhs.planIndex < rhs.planIndex
}
return result

동작은 같고, 테스트도 그대로 통과합니다. 같은 이유로 막힐 수 있는 다른 정렬 비교(목록의 금액순 정렬 등)도 미리 같은 방식으로 바꿨습니다.

배운 점

• 로컬에서 괜찮던 표현식도 CI 머신에서는 시간 제한에 걸릴 수 있다
• 체인이 길어지고 클로저 안에 삼항연산자·비교·Decimal 연산이 섞이면 일찍 반복문으로 풀어 쓴다
• 정렬 클로저는 파라미터 타입과 반환 타입을 명시하고, 삼항연산자 대신 if를 쓴다

다음 글

로그인을 "선택 기능"으로 두고 Supabase에 백업·동기화를 붙인 과정을 다룹니다.

시리즈: Subhelp — iOS 구독 관리 앱 개발기 이번 글: 기획서 반영(MVP 1), 무료체험 규칙을 Domain에 넣기, 폼 구조, 상세 화면, 온보딩, 접근성

기획서와 구현이 부딪히는 부분부터 정리

기본 기능을 만든 뒤 기획서를 받아 비교해 보니, 이미 만든 동작을 바꿔야 하는 부분이 있었습니다.

출시 전이라 저장된 사용자 데이터가 없어서, 이름 변경이나 설정 키 변경에 데이터 마이그레이션이 필요 없었습니다. 폴더·타깃·번들 ID·표시 이름을 모두 Subhelp로 바꿨습니다.

무료체험 규칙을 Domain에 넣기

기획서의 규칙:

• 체험 중 = 오늘이 체험 종료일 이전인 상태 (종료일 당일부터 유료)
• 체험 기간 안의 결제일은 결제로 치지 않는다
• 체험 중 구독은 결제 예정액·월 환산에서 제외, 종료일 이후 결제부터 포함

extension BillingCalculator {
    func isInTrial(_ plan: BillingPlan, on reference: Date = .now) -> Bool {
        guard let trialEnd = plan.trialEndDate else { return false }
        return calendar.startOfDay(for: reference) < calendar.startOfDay(for: trialEnd)
    }

    /// 다음 "유료" 결제일 — 체험 종료 전 결제일은 건너뛴다
    func nextPaymentDate(_ plan: BillingPlan, from reference: Date = .now) -> Date {
        var from = calendar.startOfDay(for: reference)
        if let trialEnd = plan.trialEndDate {
            from = max(from, calendar.startOfDay(for: trialEnd))
        }
        return nextBillingDate(start: plan.startDate, cycle: plan.cycle,
                               interval: plan.interval, from: from)
    }

    private func isPaid(_ date: Date, _ plan: BillingPlan) -> Bool {
        guard let trialEnd = plan.trialEndDate else { return true }
        return date >= calendar.startOfDay(for: trialEnd)
    }
}

이 규칙 하나로 홈 합계, 알림, 위젯, 통계가 모두 같은 기준으로 동작합니다. 화면마다 따로 조건을 넣었다면 어딘가에서 어긋났을 겁니다.

새로 추가할 때 무료체험을 켜면 첫 결제일을 체험 종료일로 맞춰줍니다. 보통 체험이 끝나는 날 첫 결제가 되기 때문입니다.

테스트

@Test("체험 중 구독은 결제 예정액·월 환산에서 빠지고, 이번 달 체험 종료 후 결제는 포함")
func trialInSummary() {
    let plans = [
        plan(price: 10_000, start: date(2026, 1, 15)),                                   // 일반: 10/15 결제
        plan(price: 5_000, start: date(2026, 10, 25), trialEnd: date(2026, 10, 25)),     // 이번 달 체험 종료
        plan(price: 7_000, start: date(2026, 9, 1), trialEnd: date(2026, 11, 10)),       // 다음 달 체험 종료
    ]
    let summary = sut.summary(of: plans, reference: date(2026, 10, 13))
    #expect(summary.monthTotal == 15_000)
    #expect(summary.monthlyAverage == 10_000)   // 체험 중 구독 제외
}

"10초 등록"을 위한 폼 구조

1단계: 프리셋 선택

• 검색창 + 카테고리별 프리셋 그리드, 하단 "직접 입력하기"
• 프리셋은 이름·카테고리·색상만 채운다
  • 브랜드 로고는 쓰지 않는다 — 상표 문제로 심사 리젝·분쟁 가능 → 이니셜 + 색상 원형 아이콘
  • 가격은 넣지 않는다 — 요금이 자주 바뀌고 요금제마다 다름 → 사용자 입력

2단계: 입력 폼

• 필수 항목(이름, 금액, 통화, 주기·간격, 첫 결제일, 카테고리)은 위에
• 선택 항목(색상, 알림, 무료체험, 메모)은 DisclosureGroup으로 "더보기"에 접기
• 이름과 금액이 있어야 저장 버튼 활성화
• 금액 규칙: 0원·음수 불가, 최대 9자리 (Domain의 PriceRule로 분리해 테스트)

폼 상태는 저장 전까지 @Model을 건드리지 않도록 별도의 @Observable 객체(SubscriptionDraft)에 담았습니다. 취소하면 그냥 버리면 됩니다.

@Observable
final class SubscriptionDraft {
    var name = ""
    var price: Decimal = 0
    var cycle: BillingCycle = .monthly
    // ...
    var isValid: Bool { !trimmedName.isEmpty && PriceRule.validate(price) == nil }

    func apply(to sub: Subscription) { ... }
}

상세 화면

• 다음 결제일 + D-day, 체험 종료일, 결제 주기, 첫 결제일
• 월 환산 금액 (달러면 원화 환산 ≈ 표시)
• 지금까지 낸 총액: 첫 결제일부터 오늘까지 결제 횟수 × 현재 금액. 요금이 중간에 바뀌었을 수 있어 추정치라고 표시
• 편집, 일시중지/재개, 삭제(확인 알럿)

일시중지는 "해지했지만 기록은 남기고 싶을 때" 씁니다. 모든 합계와 알림에서 빠지고, 목록에서는 흐리게 표시됩니다.

온보딩

• 2장: 가치 소개("매달 나가는 구독, 얼마인지 알고 계세요?") → "첫 구독을 추가해볼까요?"
• 마지막 장에서 바로 구독 추가 시트로 연결
• 알림 권한은 여기서 묻지 않음 (#3 참고)

리뷰 요청

구독을 3개 이상 등록하고 앱을 다시 실행했을 때 한 번만 requestReview를 호출합니다. 앱을 충분히 써본 사람에게만 묻기 위해서입니다.

접근성과 UX 라이팅

• D-day 배지는 색과 텍스트를 함께 쓴다 (색만으로 정보를 구분하지 않음)
  • 오늘·내일 오렌지 / 7일 이내 블루 / 그 외 회색
• VoiceOver 라벨: "넷플릭스, 17,000원, 매월, 2일 후 결제"
• 금액은 고정폭 숫자(monospacedDigit), 큰 글씨에서 잘리지 않게 ViewThatFits·minimumScaleFactor
• 다크 모드 대응
• 문구는 해요체, 숫자는 구체적으로("곧 결제돼요" 대신 "2일 후 결제돼요"), 비난하지 않기
• 문자열은 String Catalog(Localizable.xcstrings)로 관리해 다국어 확장에 대비

다음 글

통계 탭(결제 캘린더, 비싼 구독 순위)과, CI에서 만난 "컴파일러가 타입을 못 정해요" 에러를 다룹니다.

시리즈: Subhelp — iOS 구독 관리 앱 개발기 이번 글: 로컬 알림 전략, 알림 권한 타이밍, App Group으로 위젯과 데이터 공유, 딥링크

로컬 알림 전략

iOS는 앱 하나당 대기 중인 로컬 알림을 최대 64개까지만 허용합니다. 구독이 많으면 금방 넘칩니다.

• 구독마다 다음 결제 2회분만 예약
• 앱 실행, 포그라운드 복귀, 구독 변경 때 전부 지우고 다시 예약
  • 단순해서 버그가 적고, 시간대가 바뀌거나 지난 알림이 소진돼도 다음 실행 때 바로잡힌다
• 64개를 넘으면 가까운 알림부터 남긴다

func rescheduleAll(_ subscriptions: [Subscription], now: Date = .now) async {
    center.removeAllPendingNotificationRequests()

    let status = await authorizationStatus()
    guard status == .authorized || status == .provisional else { return }

    var pending: [(fireDate: Date, request: UNNotificationRequest)] = []
    for sub in subscriptions where sub.isActive {
        pending += billingRequests(for: sub, hour: hour, now: now)
        pending += trialRequests(for: sub, hour: hour, now: now)
    }

    for item in pending.sorted(by: { $0.fireDate < $1.fireDate }).prefix(64) {
        try? await center.add(item.request)
    }
}

알림 시각은 "결제일 − 설정 일수"의 설정 시각(기본 오전 9시)입니다. 구독별로 당일·1일 전·3일 전·7일 전·끔 중에서 고르고, 알림 시각은 설정에서 바꿀 수 있습니다.

문구는 구체적인 숫자와 해요체로 맞췄습니다.

넷플릭스 결제가 내일이에요 · ₩17,000
티빙 무료체험이 3일 후 끝나요. 계속 쓸지 결정해보세요

알림 권한은 언제 물을까

첫 실행에 바로 권한을 물으면 맥락이 없어 거절률이 높습니다.

• 온보딩에서는 묻지 않는다
• 첫 구독을 저장한 직후, 안내 문구("결제일을 놓치지 않도록 미리 알려드릴게요")를 먼저 보여주고 나서 시스템 권한 창을 띄운다
• 거부된 상태면 홈 상단에 배너를 띄우고, iOS 설정으로 이동하는 버튼을 둔다

구독 추가 시트가 닫히는 순간에 알럿을 띄우면 두 화면이 겹쳐 표시되지 않을 수 있습니다. 그래서 "권한 안내가 필요하다"는 표시만 해 두고, 시트의 onDismiss에서 알럿을 띄웠습니다.

.sheet(isPresented: $router.isAddingSubscription, onDismiss: {
    Task { await router.offerNotificationPermissionIfNeeded() }
}) { AddSubscriptionSheet() }

위젯과 데이터 공유: App Group

위젯은 앱과 별도 프로세스로 돌아갑니다. 같은 데이터를 보려면 저장소를 App Group 컨테이너에 둬야 합니다.

enum SharedModelContainer {
    static let shared: ModelContainer = {
        let schema = Schema([Subscription.self])
        if let groupID = AppConfig.appGroupID {
            let config = ModelConfiguration(schema: schema, groupContainer: .identifier(groupID))
            if let container = try? ModelContainer(for: schema, configurations: [config]) {
                return container
            }
        }
        // App Group 미설정(개발 초기) → 앱 전용 저장소로 동작
        return try! ModelContainer(for: schema, configurations: [ModelConfiguration(schema: schema)])
    }()
}

환율 같은 설정도 위젯이 써야 해서 App Group UserDefaults에 저장했습니다.

흔한 함정: save() 없이 위젯 갱신

위젯은 디스크에서 데이터를 읽습니다. 앱에서 데이터를 바꾼 뒤 저장하지 않고 위젯 갱신을 요청하면, 위젯은 이전 데이터를 보여줍니다. 저장 → 알림 재예약 → 위젯 갱신을 한 함수로 묶었습니다.

static func commit(_ context: ModelContext) async {
    try? context.save()                       // 1. 디스크에 먼저 저장
    await NotificationService.shared.rescheduleAll(...)  // 2. 알림 재예약
    WidgetCenter.shared.reloadAllTimelines()  // 3. 위젯 갱신
}

위젯 구성

D-day가 바뀌는 시점에 맞춰 타임라인은 매일 자정에 갱신됩니다.

let midnight = calendar.date(byAdding: .day, value: 1, to: calendar.startOfDay(for: .now))!
completion(Timeline(entries: [makeEntry()], policy: .after(midnight)))

위젯 Privacy Manifest

App Group UserDefaults를 쓰므로 앱과 위젯 둘 다 PrivacyInfo.xcprivacy에 UserDefaults 사용 사유를 선언했습니다.

• CA92.1: 앱 자체에서 쓰는 값
• 1C8F.1: 같은 App Group의 앱·익스텐션이 공유하는 값

딥링크

subhelp:// URL 스킴을 만들었습니다.

enum DeepLink {
    static let home = URL(string: "subhelp://home")!
    static func subscription(_ id: UUID) -> URL {
        URL(string: "subhelp://subscription/\(id.uuidString)")!
    }
}

• 위젯 탭 → widgetURL / Link로 해당 구독 상세 또는 홈
• 알림 탭 → 알림 userInfo에 구독 ID를 넣고, UNUserNotificationCenterDelegate에서 같은 라우터로 상세 화면 이동
• 앱 사용 중에 온 알림도 배너로 보이도록 willPresent에서 .banner를 돌려줌

탭 선택·네비게이션 경로·시트 상태를 한곳(AppRouter, @Observable)에서 관리해서, 어디서 들어오든 같은 방식으로 화면을 이동합니다.

func open(subscriptionID: UUID) {
    isAddingSubscription = false
    selectedTab = .subscriptions
    subscriptionsPath = [subscriptionID]
}

다음 글

기획서를 반영하면서 들어간 무료체험 규칙과 "10초 등록" 폼 구조를 다룹니다.

시리즈: Subhelp — iOS 구독 관리 앱 개발기 이번 글: 결제일·금액 계산 로직, 단위 테스트, CI에서 테스트 돌리기

문제: 월말 날짜 밀림

1월 31일에 시작한 월결제를 "이전 결제일 + 1개월"로 반복 계산하면 날짜가 밀립니다.

1/31 → 2/28 → 3/28 → 4/28 ...  ❌

2월에 28일로 한 번 잘리면, 그다음부터는 28일을 기준으로 계산되기 때문입니다.

해결: 항상 "최초 결제일 + n번째 주기"

func occurrence(_ n: Int, start: Date, cycle: BillingCycle, interval: Int) -> Date? {
    calendar.date(byAdding: cycle.component,
                  value: max(1, interval) * n,
                  to: calendar.startOfDay(for: start))
}

1/31 + 1개월 = 2/28
1/31 + 2개월 = 3/31  ✅
1/31 + 3개월 = 4/30

존재하지 않는 날짜(31일, 2/29)는 그 달의 마지막 날로 처리되고, 다음 달에는 다시 원래 날짜로 돌아옵니다.

주기 표현

enum BillingCycle: String, Codable, CaseIterable {
    case weekly, monthly, yearly

    var component: Calendar.Component {
        switch self {
        case .weekly:  .weekOfYear
        case .monthly: .month
        case .yearly:  .year
        }
    }
}

"3개월마다"는 monthly + interval = 3으로 표현합니다.

다음 결제일

오늘(포함) 이후 첫 결제일을 구합니다. 시각은 무시하고 날짜 단위로 비교합니다.

func nextBillingDate(start: Date, cycle: BillingCycle, interval: Int,
                     from reference: Date = .now) -> Date {
    let first = calendar.startOfDay(for: start)
    let today = calendar.startOfDay(for: reference)
    if first >= today { return first }   // 첫 결제일이 미래면 그날

    var n = skipCount(start: first, target: today, cycle: cycle, interval: interval)
    while n < maxOccurrences,
          let date = occurrence(n, start: first, cycle: cycle, interval: interval) {
        if date >= today { return date }
        n += 1
    }
    return first
}

최적화: 시작일이 10년 전이어도 빠르게

n을 0부터 하나씩 올리면, 오래된 주결제 구독은 수백 번 반복합니다. 그래서 경과한 주기 수만큼 먼저 건너뜁니다. 월말 보정 때문에 한 주기 정도 오차가 날 수 있어 여유를 하나 둡니다.

private func skipCount(start: Date, target: Date, cycle: BillingCycle, interval: Int) -> Int {
    guard target > start else { return 0 }
    let elapsed = calendar.dateComponents([cycle.component], from: start, to: target)
        .value(for: cycle.component) ?? 0
    return max(0, elapsed / max(1, interval) - 1)   // 한 주기 여유
}

비정상 입력으로 무한 루프가 돌지 않도록 반복 상한(maxOccurrences)도 뒀습니다.

이번 달 결제일들

"이번 달 실제 지출"을 구하려면 한 달 안에 있는 결제일을 모두 알아야 합니다. 주결제는 한 달에 4~5번입니다.

func billingDates(in month: Date, start: Date, cycle: BillingCycle, interval: Int) -> [Date] {
    guard let range = calendar.dateInterval(of: .month, for: month) else { return [] }
    // range.start ≤ 결제일 < range.end 인 회차를 모두 모은다
}

금액 계산: 반드시 Decimal

Double로 계산하면 부동소수 오차가 생깁니다. 금액은 전부 Decimal로 다룹니다.

struct CostCalculator {
    var usdToKrw: Decimal

    func toKRW(_ price: Decimal, currency: Currency) -> Decimal {
        currency == .usd ? price * usdToKrw : price
    }

    /// 연 환산 (주결제는 1년 = 52주)
    func yearlyCost(price: Decimal, currency: Currency, cycle: BillingCycle, interval: Int) -> Decimal {
        let krw = toKRW(price, currency: currency)
        let interval = Decimal(max(1, interval))
        switch cycle {
        case .weekly:  return krw * 52 / interval
        case .monthly: return krw * 12 / interval
        case .yearly:  return krw / interval
        }
    }

    /// 월 환산 = 연 환산 / 12
    func monthlyCost(...) -> Decimal { yearlyCost(...) / 12 }
}

주결제의 월 환산을 가격 × 52 ÷ 12로 바로 계산하면 나누어떨어지지 않는 소수가 생기기 쉽습니다. 그래서 연 환산을 먼저 구하고 12로 나눴습니다.

환율은 사용자가 입력합니다(실시간 환율은 MVP 범위 밖). 입력값(Double)을 Decimal로 바꿀 때도 이진 부동소수 잡음(1380.5000000001)을 피하려고 문자열을 거칩니다.

static func decimal(_ value: Double) -> Decimal {
    Decimal(string: String(value)) ?? Decimal(value)
}

"이번 달 결제 예정"과 "월 환산"은 다른 숫자

두 숫자가 왜 다른지 화면에 짧은 설명을 붙였습니다. 달러가 섞여 있으면 금액 앞에 ≈를 붙여 추정치임을 표시합니다.

테스트: Calendar를 주입받는 이유

BillingCalculator는 Calendar를 주입받습니다. 테스트에서는 타임존을 서울로 고정해서, 실행 환경과 상관없이 같은 결과가 나오게 합니다.

struct BillingCalculatorTests {
    let cal: Calendar = {
        var c = Calendar(identifier: .gregorian)
        c.timeZone = TimeZone(identifier: "Asia/Seoul")!
        return c
    }()

    var sut: BillingCalculator { BillingCalculator(calendar: cal) }

    @Test("월말(31일) 시작은 2월엔 말일, 3월엔 다시 31일 — 날짜가 밀리지 않는다")
    func monthEndDoesNotDrift() {
        let start = date(2026, 1, 31)
        #expect(sut.nextBillingDate(start: start, cycle: .monthly, interval: 1, from: date(2026, 2, 1)) == date(2026, 2, 28))
        #expect(sut.nextBillingDate(start: start, cycle: .monthly, interval: 1, from: date(2026, 3, 1)) == date(2026, 3, 31))
        #expect(sut.nextBillingDate(start: start, cycle: .monthly, interval: 1, from: date(2026, 4, 1)) == date(2026, 4, 30))
    }
}

테스트한 케이스:

• 월말(31일) 시작 → 2월은 28/29일, 3월은 다시 31일
• 윤년 2/29 시작 연결제 → 평년엔 2/28, 윤년엔 2/29
• 오늘이 결제일 (시각과 무관하게 오늘)
• 시작일이 미래
• 3개월 간격, 격주
• 시작일이 10년 전
• 이번 달 주결제 횟수 (4~5회)
• 연결제는 결제 월에만 포함
• 연결제·주결제·3개월 결제의 월 환산, USD 환산
• 이번 달 실제 지출 vs 월 환산 평균

Decimal의 부동소수 리터럴(9.99)은 Double을 거쳐 오차가 생깁니다. 테스트에서도 Decimal(string: "9.99")처럼 문자열로 만들었습니다.

CI에서 테스트 돌리기

테스트 타깃은 앱을 호스트로 띄우지 않고 Domain/ 소스를 직접 컴파일합니다.

SubhelpTests:
  type: bundle.unit-test
  sources:
    - path: SubhelpTests
    - path: Subhelp/Domain

앱을 호스트로 띄우면 App Group 서명이 필요해서 CI에서 막힙니다. 이렇게 하면 서명 없이 GitHub Actions에서 바로 돌아갑니다.

다음 글

로컬 알림의 64개 한도와 위젯 데이터 공유를 다룹니다.

시리즈: Subhelp — iOS 구독 관리 앱 개발기 이번 글: 문제 정의, 기술 스택, 아키텍처 결정, 프로젝트 셋업

만들려는 것

Subhelp는 흩어진 구독 결제를 한곳에 모아, 언제·얼마가 빠져나가는지 미리 알려주는 iOS 앱입니다.

해결하려는 문제

해결 방향

1. 모으기 — 모든 구독을 한 화면에 등록
2. 보여주기 — 이번 달 결제 예정액과 다음 결제일을 바로 확인
3. 알려주기 — 결제 전, 무료체험 종료 전에 알림
4. 돌아보기 — 카테고리별 지출로 정리할 구독을 판단

제품 원칙

• 10초 등록: 구독 하나 등록에 10초를 넘기지 않는다
• 열지 않아도 안다: 위젯과 알림만으로 핵심 정보를 전달한다
• 내 데이터는 내 폰에: 계정·서버 없이 기기에 저장한다
• 판단은 사용자 몫: 해지를 강요하지 않고 판단에 필요한 정보만 준다

MVP 단계

MVP 0 Core     ─ 등록하고 보는 앱
MVP 1 Notify   ─ 먼저 알려주는 앱      ← 첫 출시 기준선
MVP 2 Insight  ─ 돌아보게 해주는 앱
Post-MVP       ─ 동기화·확장

기술 스택

결정 1. 서버 없이 로컬 우선

구독 데이터는 개인 기기 안에서 충분히 완결됩니다. 서버가 없으면:

• 로그인 없이 바로 쓸 수 있어 진입 장벽이 없다
• 개인정보를 수집하지 않으니 App Store 개인정보 라벨이 "데이터 수집 안 함"
• 출시까지의 경로가 짧다

나중에 동기화를 붙일 것에 대비해 SwiftData 모델의 모든 프로퍼티에 기본값을 넣었습니다. CloudKit 동기화의 필수 조건이기도 합니다.

@Model
final class Subscription {
    var id: UUID = UUID()
    var name: String = ""
    var price: Decimal = 0
    var currencyCode: String = "KRW"
    var cycleRaw: String = BillingCycle.monthly.rawValue  // #Predicate에서 enum을 직접 쓰기 까다로워 raw로 저장
    var cycleInterval: Int = 1                            // 3개월마다 → monthly + 3
    var startDate: Date = Date.now
    var notifyDaysBefore: Int? = 1                        // nil = 알림 끔
    var isActive: Bool = true
    var trialEndDate: Date? = nil
    // ...
}

다음 결제일·월 환산 금액은 저장하지 않고 매번 계산합니다. 저장하면 데이터가 어긋날 수 있기 때문입니다.

결정 2. MVVM 대신 @Query + Domain 분리

SwiftData의 @Query는 뷰가 직접 데이터를 구독하도록 설계돼 있습니다. ViewModel로 감싸면 자동 갱신이라는 장점을 잃습니다. 그래서 역할을 이렇게 나눴습니다.

• 조회 → 뷰에서 @Query 직접 사용
• 계산 로직(다음 결제일, 월 환산) → Domain/의 순수 struct → 단위 테스트
• 부수효과(알림 예약, 위젯 갱신) → Services/
• 복잡한 폼 상태만 @Observable 클래스로 분리

Domain이 SwiftData에 의존하지 않도록, 계산에 필요한 정보만 담은 값 타입을 따로 뒀습니다.

struct BillingPlan: Hashable {
    var price: Decimal
    var currency: Currency
    var cycle: BillingCycle
    var interval: Int
    var startDate: Date
    var trialEndDate: Date? = nil
}

폴더 구조:

Subhelp/
├── App/        앱 진입점, 라우터, 공유 ModelContainer, AppConfig
├── Domain/     순수 계산 로직 (테스트 대상)
├── Data/       @Model, 프리셋
├── Services/   알림, 저장·위젯 갱신, 서버 연동
├── Features/   Home / SubscriptionList / Detail / Editor / Stats / Settings / Onboarding
├── Shared/     공용 컴포넌트·포매터·설정 (위젯과 공유)
└── Resources/  Assets, Info.plist, entitlements, PrivacyInfo
SubhelpWidget/  위젯 익스텐션
SubhelpTests/   Domain 단위 테스트
Config/         빌드 변수 (xcconfig)

결정 3. .xcodeproj 대신 XcodeGen

.xcodeproj는 사람이 읽기 어렵고 merge 충돌이 잦습니다. project.yml 한 파일로 앱·위젯·테스트 타깃을 선언하고, .xcodeproj는 xcodegen generate로 만들어서 git에 올리지 않습니다.

targets:
  Subhelp:
    type: application
    sources: [Subhelp]
    dependencies:
      - target: SubhelpWidget

  SubhelpWidget:
    type: app-extension
    sources:
      - path: SubhelpWidget
      # 위젯과 공유하는 코드를 명시
      - path: Subhelp/Domain
      - path: Subhelp/Data
      - path: Subhelp/Shared
      - path: Subhelp/App/ModelContainer+Shared.swift
      - path: Subhelp/App/AppConfig.swift

위젯과 공유할 파일을 이렇게 명시하면, 위젯 개발에서 가장 흔한 빌드 에러인 Target Membership 체크 누락이 생기지 않습니다.

결정 4. 개인 값은 빌드 변수로 분리

팀 ID, 번들 ID, App Group 같은 값은 코드에 하드코딩하지 않습니다.

• Config/Base.xcconfig (커밋됨): 빈 값·예시 값만
• Config/Local.xcconfig (.gitignore): 실제 값

// Base.xcconfig
DEVELOPMENT_TEAM =
BUNDLE_ID_PREFIX = com.yourname
APP_GROUP_ID = group.$(BUNDLE_ID_PREFIX).subhelp
SUPPORT_EMAIL =
PRIVACY_POLICY_URL =

#include? "Local.xcconfig"   // 있으면 위 값을 덮어씀

값은 Info.plist의 $(APP_GROUP_ID) 같은 변수로 주입되고, 코드에서는 AppConfig 한 곳에서만 읽습니다. 값이 비어 있거나 치환되지 않았으면($(가 남아 있으면) nil로 처리해서, 설정 전에도 앱이 죽지 않게 했습니다.

enum AppConfig {
    static let appGroupID: String? = infoValue("AppGroupIdentifier")

    private static func infoValue(_ key: String) -> String? {
        guard let value = Bundle.main.object(forInfoDictionaryKey: key) as? String else { return nil }
        let trimmed = value.trimmingCharacters(in: .whitespaces)
        guard !trimmed.isEmpty, !trimmed.contains("$(") else { return nil }
        return trimmed
    }
}

💡 xcconfig에서 //는 주석으로 처리됩니다. 그래서 URL은 https:/$()/example.com처럼 적어야 합니다.

결정 5. CI부터 붙이기

GitHub Actions macOS 러너에서 xcodegen generate → 앱·위젯 빌드 → 테스트를 매 push마다 돌립니다. 서명 없이(CODE_SIGNING_ALLOWED=NO) 시뮬레이터용으로 빌드하므로 팀 ID 같은 개인 값이 CI에 필요 없습니다.

- run: |
    brew install xcodegen
    xcodegen generate
- run: |
    xcodebuild test -project Subhelp.xcodeproj -scheme Subhelp \
      -destination "id=$DEVICE_ID" CODE_SIGNING_ALLOWED=NO

같은 브랜치에 새 커밋이 오면 이전 실행을 취소하도록 concurrency도 설정했습니다.

다음 글

결제일 계산에서 가장 까다로웠던 월말 날짜 밀림 문제를 다룹니다.

시리즈 마지막 편입니다. 남은 기능 세 가지를 짧게 정리하고, 프로젝트 전체를 돌아봅니다.

기능 1 — 미체결 주문 조회

보유종목, 관심종목, 알림까지는 있었지만 "지금 체결 대기 중인 주문이 뭐가 있나"를 볼 방법이 없었습니다. 조회 전용 API가 있길래 읽기 전용 엔드포인트 하나를 추가했습니다.

@GetMapping("/api/orders/pending")
public List<PendingOrderResponse> pendingOrders() {
    return tossApiClient.getPendingOrders().stream()
            .map(PendingOrderResponse::of)
            .toList();
}

여기서 의도적으로 좁힌 범위가 있습니다. 조회만 만들고, 주문 생성/취소는 만들지 않았습니다. 매매 자체를 실행하는 기능은 이 프로젝트의 목적(관심종목 모니터링과 알림)을 벗어나고, 무엇보다 잘못 만들면 실제 금전적 피해로 이어지는 영역입니다. "가능하니까 만든다"가 아니라 "필요한 만큼만 만든다"는 원칙을 가장 분명하게 적용한 지점입니다.

또 하나, 이 엔드포인트가 감싸는 getPendingOrders()는 응답 스키마를 문서에서 검증할 방법이 없었던 API입니다. Javadoc에 이 사실을 명시적으로 남겨서, 나중에 실제 데이터로 이상 동작이 보이면 "검증 안 된 부분"이라는 걸 바로 알 수 있게 해뒀습니다. 확인되지 않은 가정을 코드에 조용히 숨기는 대신, 눈에 보이게 남겨두는 쪽을 택했습니다.

기능 2 — 알림 규칙 수정

기존에는 알림 규칙을 켜고 끄는 것만 가능했습니다(PATCH로 active만 변경). 목표가를 바꾸고 싶으면 규칙을 지우고 새로 만들어야 했는데, 그러면 발송 이력과의 연결이 끊깁니다.

PATCH 요청 바디를 확장해서, 임계값/채널/쿨다운/반복방식을 부분 업데이트할 수 있게 했습니다.

public record AlertRuleUpdateRequest(
        Boolean active,
        BigDecimal thresholdValue,
        Set<NotificationChannelType> channels,
        Integer cooldownMinutes,
        AlertTriggerMode triggerMode) {
}

모든 필드가 nullable입니다. null인 필드는 "변경하지 않음"을 의미하고, 값이 있는 필드만 적용됩니다.

@Transactional
public AlertRule update(Long id, AlertRuleUpdateRequest request) {
    AlertRule rule = repository.findById(id)
            .orElseThrow(() -> new NotFoundException("알림 규칙을 찾을 수 없습니다: " + id));

    if (request.active() != null) {
        rule.setActive(request.active());
    }
    if (request.thresholdValue() != null) {
        if (request.thresholdValue().signum() <= 0) {
            throw new IllegalArgumentException("임계값은 0보다 커야 합니다.");
        }
        rule.setThresholdValue(request.thresholdValue());
    }
    // ... channels, cooldownMinutes, triggerMode도 동일한 패턴
    return rule;
}

의도적으로 바꿀 수 없게 남긴 것도 있습니다. 종목(symbol)과 조건 종류(conditionType)는 수정 대상에서 뺐습니다. 이 둘은 규칙의 정체성 그 자체입니다 — 종목이나 조건 종류가 바뀐다는 건 사실상 "다른 규칙"이 됐다는 뜻이고, 그런 경우엔 기존 발송 이력을 유지한 채 수정하는 것보다 새로 만드는 게 데이터 모델상 더 맞다고 판단했습니다. 프론트엔드도 이 두 필드는 테이블에서 읽기 전용으로 표시하고, 나머지만 인라인으로 편집 가능하게 했습니다.

기능 3 — 알림 발송 재시도

알림 발송이 실패하면 그걸로 끝이었습니다. 일시적인 네트워크 문제 때문에 실패한 경우에도 재시도 없이 실패로 기록됐습니다.

여기서 "재시도해도 되는 실패"와 "재시도해봐야 똑같이 실패할 실패"를 구분해야 했습니다. 예를 들어 이메일 채널의 SMTP 설정 자체가 비어있어서 나는 실패는, 3초 뒤에 다시 시도해도 똑같이 실패합니다. 반면 일시적인 타임아웃이나 연결 오류는 재시도하면 성공할 수 있습니다.

이걸 구분하려고 새 플래그를 추가하는 대신, 기존 코드에 이미 있던 관례를 활용했습니다. NotificationDeliveryException은 원인(cause)이 있는 채로 던져지는 경우(진짜 발송 실패를 감싼 경우)와, 원인 없이 그냥 던져지는 경우(설정 누락 같은 사전 조건 실패)가 이미 구분되어 있었습니다.

public boolean isRetryable() {
    return getCause() != null;
}

private Attempt sendWithRetry(NotificationChannel channel, AlertTriggeredEvent event) {
    for (int attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
        try {
            channel.send(event);
            return new Attempt(DeliveryStatus.SUCCESS, null);
        } catch (NotificationDeliveryException e) {
            boolean isLastAttempt = attempt == MAX_ATTEMPTS;
            if (!e.isRetryable() || isLastAttempt) {
                return new Attempt(DeliveryStatus.FAILED, e.getMessage());
            }
            sleep(retryDelayMs);
        }
    }
    throw new IllegalStateException("도달할 수 없는 코드");
}

최대 2회(최초 1회 + 재시도 1회)로 제한하고, 재시도 간격은 테스트에서 주입할 수 있게 만들어서 실제 테스트가 몇 초씩 기다리지 않도록 했습니다.

회고

인터페이스 뒤에 숨기기

TossApiClient, NotificationChannel 둘 다 처음부터 인터페이스로 만들고 Mock 구현체를 먼저 완성했습니다. 덕분에 실 API 연동은 "이미 동작하는 시스템에 진짜 구현체를 하나 끼워 넣는 작업"이 됐고, 이메일 채널 추가는 서비스 로직을 전혀 건드리지 않고 끝났습니다. 처음부터 실 API로 시작했다면 인증/스키마 문제(5~6편)를 디버깅하는 동안 나머지 기능 개발 전체가 막혔을 겁니다.

추측하지 말고 확인하라

이 시리즈 전체를 관통한 원칙입니다. gzip 압축된 에러 응답(5편), 배열인 줄 알았던 응답이 객체였던 문제(6편), 다중 시세 조회 지원 여부(7편) — 전부 "아마 이럴 것이다"가 아니라 실제로 호출해서 확인하거나, 코드가 런타임에 스스로 확인하도록 만들어서 해결했습니다. 문서가 부실한 외부 API를 연동할 때는 특히 그렇습니다.

기본값이 안전하게

진단용 엔드포인트(8편)에서 배운 교훈입니다. "나중에 끄는 걸 기억하기"가 아니라 "명시적으로 켜지 않는 한 꺼져 있기"로 구조를 바꾸는 게, 사람의 기억보다 훨씬 신뢰할 수 있는 안전장치였습니다.

의도적으로 하지 않은 것

• 다중 사용자 / 로그인: 개인이 자신의 계좌를 모니터링하는 도구로 시작한 프로젝트라, 여러 사용자가 계정을 나눠 쓰는 시나리오는 범위 밖으로 뒀습니다.
• 주문 생성/취소: 조회까지만. 실제 매매를 실행하는 기능은 요구사항에도 없었고, 잘못 만들면 리스크가 가장 큰 영역이라 손대지 않았습니다.
• 배포 파이프라인: CI(테스트 자동화)까지는 붙였지만, 실제 배포 자동화는 이 시리즈 범위 밖입니다.

숫자로 보는 프로젝트

• 테스트: 0개 → 112개
• 머지된 PR: 다수 (기능 개발 + 고도화 항목들을 각각 별도 PR로)
• 알림 조건: 6종
• 알림 채널: 인앱 + 이메일

여기까지가 TossWatch를 만들며 겪은 문제와 해결 과정입니다. 전체 코드는 GitHub 저장소에서 확인할 수 있습니다. 읽어주셔서 감사합니다.

이 글은 보안과 직접 관련된 내용을 다룹니다. 어떤 문제가 있었고 어떻게 고쳤는지는 설명하지만, 진단용 엔드포인트가 실제로 반환하는 응답 내용이나 실제 계좌 데이터는 포함하지 않습니다.

기능이 아니라, 당장 눈에 보이지 않는 운영 관점의 문제 세 가지를 정리한 편입니다. 셋 다 "지금 당장은 문제가 안 되지만 방치하면 언젠가 문제가 되는" 종류입니다.

문제 1 — 시계열 데이터가 무한히 쌓인다

account_snapshots(자산 추이용 스냅샷)와 alert_logs(알림 발송 기록)는 시간이 지날수록 계속 쌓이기만 하고, 지우는 로직이 없었습니다. 당장은 테이블이 작아서 문제가 안 되지만, 서비스가 오래 돌수록 쿼리는 느려지고 저장공간은 계속 늘어납니다.

두 데이터를 다르게 취급해야 했던 이유

두 테이블을 똑같이 취급하면 안 된다고 판단했습니다.

• alert_logs는 "언제 무슨 알림이 발송됐는가"를 남기는 감사 로그 성격입니다. 오래된 기록은 그냥 필요 없어집니다 → 하드 삭제.
• account_snapshots는 자산 추이 차트의 원본 데이터입니다. 오래된 데이터라고 완전히 지워버리면, 차트에서 "몇 달 전 대비 지금"같은 장기 추이를 볼 수 없게 됩니다. 하지만 폴링 주기(예: 몇 분 간격)로 쌓인 스냅샷을 전부 남길 필요도 없습니다 → 하루에 하나만 남기고 솎아내기.

public record RetentionProperties(
        boolean enabled,
        String cron,
        int alertLogDays,
        int snapshotKeepAllDays) {
}

@Service
public class RetentionService {

    @Autowired
    public RetentionService(AlertLogRepository alertLogRepository,
            AccountSnapshotRepository snapshotRepository,
            RetentionProperties properties) {
        this(alertLogRepository, snapshotRepository, properties, ZoneId.systemDefault());
    }

    // 테스트에서 시간대를 고정하기 위한 생성자
    RetentionService(AlertLogRepository alertLogRepository,
            AccountSnapshotRepository snapshotRepository,
            RetentionProperties properties, ZoneId zoneId) {
        ...
    }

    public void purgeAlertLogs() {
        if (properties.alertLogDays() <= 0) {
            return;
        }
        Instant cutoff = Instant.now().minus(properties.alertLogDays(), ChronoUnit.DAYS);
        alertLogRepository.deleteByTriggeredAtBefore(cutoff);
    }

    public void thinSnapshots() {
        if (properties.snapshotKeepAllDays() <= 0) {
            return;
        }
        Instant cutoff = Instant.now().minus(properties.snapshotKeepAllDays(), ChronoUnit.DAYS);
        List<AccountSnapshot> old = snapshotRepository.findBySnapshotAtBeforeOrderBySnapshotAtAsc(cutoff);

        // 달력 날짜별로 묶어서, 각 날짜의 마지막 스냅샷만 남긴다
        Map<LocalDate, AccountSnapshot> keepPerDay = new LinkedHashMap<>();
        for (AccountSnapshot snapshot : old) {
            LocalDate day = snapshot.getSnapshotAt().atZone(zoneId).toLocalDate();
            keepPerDay.put(day, snapshot); // 같은 날짜면 마지막 것으로 덮어써짐 (오름차순 정렬이므로)
        }

        List<AccountSnapshot> toDelete = old.stream()
                .filter(s -> !keepPerDay.containsValue(s))
                .toList();
        snapshotRepository.deleteAllInBatch(toDelete);
    }
}

날짜 경계 판단은 SQL의 날짜 절삭 함수 대신 자바 코드로 처리했습니다. DB 방언마다 날짜 함수 문법이 다르고, 테스트하기도 더 어렵기 때문입니다. ZoneId를 주입 가능하게 만들어서, 테스트에서는 시간대를 고정하고 "23시와 다음날 01시는 다른 날짜로 유지된다" 같은 경계 케이스를 검증할 수 있게 했습니다.

@Test
void keepsSnapshotsFromDifferentCalendarDaysEvenIfCloseInTime() {
    // 23:00과 다음날 01:00 — 2시간 차이지만 서로 다른 날짜
    AccountSnapshot late = snapshotAt(Instant.parse("2026-01-01T23:00:00Z"));
    AccountSnapshot early = snapshotAt(Instant.parse("2026-01-02T01:00:00Z"));
    ...
    // 둘 다 살아남아야 한다
}

매일 새벽 3시 30분에 도는 스케줄러를 붙이고, retention.enabled 플래그로 기능 전체를 끌 수 있게 했습니다.

retention:
  enabled: true
  cron: "0 30 3 * * *"
  alert-log-days: 90
  snapshot-keep-all-days: 30

문제 2 — 컨트롤러 테스트가 0개였다

4편에서 서비스/도메인/스케줄러 계층 테스트를 몰아서 작성했지만, HTTP 계층(컨트롤러)은 빈 채로 남아있었습니다. 요청 파라미터 바인딩이 깨지거나, 상태 코드가 잘못되거나, 검증 애노테이션이 빠지는 종류의 버그는 서비스 계층 테스트로는 안 잡힙니다.

@WebMvcTest + @MockBean으로 HTTP 계약 수준의 테스트를 채워 넣었습니다. 이 프로젝트가 Spring Boot 3.3.x라서 @MockitoBean(3.4+ 전용)이 아니라 예전 @MockBean을 써야 했습니다.

@WebMvcTest(AlertRuleController.class)
class AlertRuleControllerTest {

    @Autowired
    MockMvc mockMvc;

    @MockBean
    AlertRuleService service;

    @Test
    void mapsAnUpdateOnAMissingRuleTo404() throws Exception {
        when(service.update(eq(999L), any())).thenThrow(new NotFoundException("..."));

        mockMvc.perform(patch("/api/alert-rules/999")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("{\"active\": false}"))
                .andExpect(status().isNotFound());
    }
}

작업 중 Spring 테스트 컨텍스트의 사소한 함정도 하나 만났습니다. @Nested 테스트 클래스는 바깥 클래스의 @TestConfiguration을 자동으로 상속받지 않아서, 각 중첩 클래스에 @Import(Config.class)를 따로 붙여줘야 했습니다.

문제 3 — 인증 없는 진단용 엔드포인트가 열려 있었다

5편에서 실 API 연동 문제(accountSeq를 못 찾던 문제)를 해결하려고 만든 진단용 컨트롤러가 있었습니다. 토스 API에 직접 요청을 보내서 원문 응답을 그대로 반환하는 엔드포인트입니다. 디버깅할 때는 유용했지만, 문제를 다 해결한 뒤에도 계속 켜진 채로 남아 있었습니다. 그리고 인증이 없었습니다.

이 엔드포인트가 반환하는 정보의 성격상(계좌 관련 원문 응답), 인증 없이 외부에 노출되면 안 되는 종류입니다. "나중에 지워야지"라고 기억에 의존하는 방식은 신뢰할 수 없다고 판단했습니다. 코드에 "지우는 걸 잊지 말자" 주석을 남기는 대신, 기본값을 꺼짐으로 만들고 명시적으로 켜야만 동작하도록 구조 자체를 바꿨습니다.

@RestController
@RequestMapping("/api/diagnostics/toss")
@ConditionalOnProperty(prefix = "toss.diagnostics", name = "enabled", havingValue = "true")
public class TossDiagnosticsController {

    @PostConstruct
    void warnThatDiagnosticsAreExposed() {
        log.warn("토스 진단 엔드포인트가 활성화되어 있습니다. 디버깅 목적이 끝나면 반드시 비활성화하세요.");
    }

    // ...
}

toss:
  diagnostics:
    enabled: ${TOSS_DIAGNOSTICS_ENABLED:false}

@ConditionalOnProperty를 쓰면, 값이 명시적으로 true가 아닌 이상 이 컨트롤러의 빈 자체가 생성되지 않습니다. 즉 라우팅 테이블에 아예 존재하지 않게 되어 404가 됩니다 — "권한이 없어서 막힌 리소스"가 아니라 "애초에 없는 리소스"가 되는 겁니다. 실수로 켜놓은 채로 배포해도, 환경변수 하나를 깜빡하지 않는 한 자동으로 꺼져 있습니다.

이 패턴은 "배포 전에 지우는 걸 기억하기"보다 훨씬 안전합니다. 사람의 기억에 의존하는 체크리스트는 언젠가 깨지지만, 기본값이 안전한 코드는 깜빡해도 안전한 채로 남습니다.

컨트롤러 테스트도 이 두 가지 상태를 각각 검증하도록 작성했습니다.

@Nested
@Import(Config.class)
class WhenDisabled {
    @Test
    void returns404() { ... }
}

@Nested
@Import(Config.class)
class WhenExplicitlyEnabled {
    @Test
    void respondsNormally() { ... }
}

결과

이 세 가지 모두 기능적으로는 "이미 동작하고 있던" 부분입니다. 사용자 입장에서 달라지는 건 없습니다. 하지만 서비스를 오래 운영한다고 가정했을 때 실제로 문제가 됐을 지점들이었고, 코드 리뷰 관점에서 스스로 점검하지 않았다면 계속 넘어갔을 것들입니다.

CI도 이 시점에 GitHub Actions로 붙였습니다. PR마다 전체 테스트 스위트가 자동으로 돌아가게 되면서, "로컬에서 돌려봤는데 통과했다"가 아니라 "머지 전에 항상 확인된다"는 보장이 생겼습니다.

마지막 편에서는 남은 기능 두 가지(미체결 주문 조회, 알림 규칙 수정)를 짧게 정리하고, 프로젝트 전체를 관통한 원칙들을 되짚어봅니다.

실연동이 동작하기 시작한 뒤, 코드를 다시 훑어보면서 "동작은 하는데 품질이 떨어지는 지점"을 스스로 점검했습니다. 이번 편은 그 과정에서 고친 두 가지입니다.

문제 1 — 시세를 종목마다 하나씩 조회하고 있었다

PriceAlertScheduler는 알림 규칙마다 getQuote()를 호출했습니다. 같은 종목에 규칙이 2개 있으면, 60초마다 똑같은 시세를 2번 조회했습니다. 관심종목 목록도 마찬가지였습니다 — 항목마다 개별 조회했고, 대시보드가 수 초마다 폴링하니 관심종목 10개면 새로고침마다 10번씩 호출이 나갔습니다.

레이트리밋이 있는 API에서, 하필 사용자가 늘려갈수록 호출이 비례해서 늘어나는 구조였습니다.

배치 조회 인터페이스 추가

TossApiClient에 여러 종목을 한 번에 조회하는 메서드를 추가했습니다.

public interface TossApiClient {

    Quote getQuote(String symbol, Market market);

    /**
     * 여러 종목의 시세를 한 번에 조회한다. getQuote를 반복 호출하는 대신 이걸 쓰면,
     * 레이트리밋이 있는 HTTP API 구현체는 한 번의 요청으로 전체를 처리할 수 있다.
     *
     * 조회 실패한 종목은 결과 맵에서 그냥 빠진다 — 종목 하나가 배치 전체를
     * 실패시키지 않도록. 기본 구현은 단순 루프인데, 로컬 Mock처럼 호출 비용이
     * 없는 구현체에는 이게 맞는 동작이다.
     */
    default Map<SymbolRef, Quote> getQuotes(Collection<SymbolRef> refs) {
        Map<SymbolRef, Quote> quotes = new LinkedHashMap<>();
        for (SymbolRef ref : refs) {
            if (!quotes.containsKey(ref)) {
                quotes.put(ref, getQuote(ref.symbol(), ref.market()));
            }
        }
        return quotes;
    }
}

MockTossApiClient는 이 기본 구현(단순 루프)을 그대로 쓰고, 실제 HTTP 구현체에서만 오버라이드해서 진짜 배치 요청을 보냅니다.

다중 조회 지원 여부를 런타임에 검증한다

시세 조회 파라미터가 symbols(복수형)였지만, 문서에는 이게 실제로 여러 종목을 한 번에 받아주는지 나와 있지 않았습니다. 여기서도 5~6편과 같은 원칙을 반복했습니다 — 추측하지 않고 확인합니다. 다만 이번엔 "직접 호출해서 사람이 확인"하는 대신, 런타임에 코드가 스스로 확인하고 적응하도록 만들었습니다.

public Map<SymbolRef, Quote> getQuotes(Collection<SymbolRef> refs) {
    List<SymbolRef> distinct = refs.stream().distinct().toList();
    if (distinct.size() == 1 || !batchedPricesSupported.get()) {
        return fetchIndividually(distinct);
    }

    String joinedSymbols = distinct.stream().map(SymbolRef::symbol).collect(Collectors.joining(","));
    List<QuoteDto> dtos = unwrap(authorizedGet(PRICES_PATH, PricesEnvelope.class,
            uri -> uri.queryParam("symbols", joinedSymbols), false));

    if (dtos.size() == 1) {
        // 여러 종목을 요청했는데 결과가 1개만 왔다 = 이 API는 다중 조회를 지원하지 않는다
        log.info("다중 조회 요청에 결과 1개만 반환 — 이후로는 개별 호출로 전환");
        batchedPricesSupported.set(false);
        return fetchIndividually(distinct);
    }

    // 정상적으로 여러 개 왔으면 symbol로 매핑
    ...
}

여러 종목을 요청했는데 결과가 1개만 오면, "이 API는 사실 단일 조회만 지원하는구나"라고 판단하고 그 프로세스 생애주기 동안은 개별 호출로 되돌립니다. 지원하지 않더라도 손해는 왕복 한 번뿐이고, 지원한다면 이후 모든 호출이 배치로 절약됩니다. 응답에서 일부 종목만 빠진 경우엔 그 종목만 따로 재조회해서, 하나의 이상한 응답이 배치 전체를 망치지 않게 했습니다.

이 변경 하나로 스케줄러는 "규칙 수만큼"이 아니라 "고유 종목 수만큼"만 호출하게 됐고, 같은 종목에 규칙이 여러 개 걸려 있어도 종목당 1회로 줄었습니다.

문제 2 — 조건이 계속 충족되면 알림이 계속 온다

목표가를 넘긴 채로 주가가 그 위에 머물면, 매 폴링마다 조건이 계속 충족된 상태입니다. 쿨다운만으로 중복을 막고 있었는데, 이건 "한 번만 알려달라"가 아니라 "쿨다운 주기마다 계속 알려달라"는 의미였습니다. 실사용에서 가장 성가신 부분이었습니다.

EDGE와 REPEAT

두 가지 반복 방식을 추가했습니다.

public enum AlertTriggerMode {
    /** 조건이 충족되는 순간(rising edge)에만 알리고, 조건이 해제될 때까지 조용히 있는다. */
    EDGE,

    /** 조건이 유지되는 동안 쿨다운마다 계속 알린다. */
    REPEAT
}

판정 로직은 "직전 평가에서 조건이 충족됐는지"를 함께 기억해야 엣지를 구분할 수 있습니다.

public boolean shouldTrigger(boolean conditionMet, Instant now) {
    if (!conditionMet || !isCooldownElapsed(now)) {
        return false;
    }
    return getTriggerMode() == AlertTriggerMode.REPEAT || !Boolean.TRUE.equals(lastConditionMet);
}

/** 매 평가마다 반드시 호출 — 알림을 보내지 않은 평가에서도 마찬가지.
    이게 바로 조건이 해제됐을 때 EDGE 규칙을 다시 무장시키는 동작이다. */
public void recordEvaluation(boolean conditionMet) {
    this.lastConditionMet = conditionMet;
}

shouldTrigger가 true를 반환하지 않은 평가에서도 recordEvaluation은 항상 호출됩니다. 이게 핵심입니다 — 조건이 해제됐다는 사실 자체를 기록해둬야, 다음에 다시 조건이 충족될 때 그게 "새로운 진입"이라는 걸 알 수 있습니다.

EDGE 모드에서도 쿨다운은 그대로 적용됩니다. 가격이 임계값 근처에서 오르내리는 경우, "충족→해제→충족"이 짧은 시간에 반복될 수 있는데, 쿨다운이 이런 플래핑이 알림 폭주로 이어지는 걸 막아줍니다.

실제로 확인한 방법

로컬 서버를 띄우고, 항상 조건이 충족되는 규칙 두 개를 쿨다운 0분으로 각각 EDGE와 REPEAT로 만들어서 3번의 폴링 동안 관찰했습니다.

기대한 그대로 동작했습니다.

다음 편에서는 "당장 눈에 보이지 않지만 운영 관점에서 중요한" 개선들을 다룹니다. 시간이 지날수록 무한히 쌓이는 데이터, 테스트 커버리지가 비어 있던 구간, 그리고 인증 없이 열려 있던 진단용 엔드포인트를 정리한 이야기입니다.

이 글의 응답 예시 값(금액, 종목명, 거래량 등)은 전부 가짜 값입니다. 실제 계좌 데이터가 아닙니다.

인증과 URL 문제를 해결하고 나니, 이번엔 응답 자체가 예상과 다른 문제들이 이어졌습니다. 문서에 스키마가 없으니, 모든 걸 실제 호출로 확인해야 했습니다.

트러블슈팅 4 — 배열인 줄 알았던 응답이 사실은 객체였다

보유종목 API를 호출한 결과를 배열로 파싱하려고 했는데 실패했습니다.

Cannot deserialize value of type `HoldingDto[]` from Object value (token JsonToken.START_OBJECT)

실제 응답을 원문으로 확인해보니, result가 배열이 아니라 계좌 집계 + 종목 배열을 함께 담은 객체였습니다.

{
  "result": {
    "totalPurchaseAmount": { "krw": "100000", "usd": "..." },
    "marketValue": { "amount": { "krw": "96000" } },
    "dailyProfitLoss": { "amount": { "krw": "-250" }, "rate": "-0.0026" },
    "items": [
      { "symbol": "000000", "name": "샘플 종목", "marketCountry": "KR", "quantity": "2", "lastPrice": "48000", ... }
    ]
  }
}

시세 조회(/prices)나 계좌 목록(/accounts) 응답은 result가 배열이었는데, 보유종목만 유독 객체 안에 배열이 들어있는 구조였습니다. 문서 없이 추측했다면 계속 배열이라고 가정했을 지점입니다.

이 사실을 알고 나니 오히려 구조를 더 단순하게 만들 수 있었습니다. 계좌 요약(총 평가금액, 당일 손익)을 종목별 시세를 일일이 다시 조회해서 합산하던 방식에서, 이 응답 하나에 이미 들어있는 집계값을 그대로 읽는 방식으로 바꿨습니다. API 호출이 줄어드는 부수 효과까지 얻었습니다.

트러블슈팅 5 — 캔들 날짜가 하루씩 밀렸다

캔들 차트를 실 데이터로 확인해보니, 날짜가 실제보다 하루씩 이르게 표시되고 있었습니다.

원인은 타임스탬프 형식과 Jackson의 기본 동작이 만난 지점이었습니다. 캔들 응답의 timestamp는 이런 형태였습니다.

"timestamp": "2026-06-08T00:00:00.000+09:00"

자정 + KST(+09:00) 오프셋입니다. 이걸 Instant나 OffsetDateTime으로 자동 바인딩하면, Jackson의 기본 설정인 ADJUST_DATES_TO_CONTEXT_TIME_ZONE이 이 값을 UTC로 정규화합니다. 2026-06-08T00:00+09:00은 UTC로 2026-06-07T15:00이 되고, 여기서 날짜만 뽑으면 6월 7일이 되어버립니다. 한국 시간 기준 거래일이었던 6월 8일이 통째로 하루 밀리는 겁니다.

해결은 타임스탬프를 자동 바인딩하지 않고, 문자열로 받아서 오프셋을 보존한 채로 직접 파싱하는 것이었습니다.

record CandleDto(
        String timestamp,  // Instant/OffsetDateTime으로 자동 바인딩하지 않고 문자열로 받음
        BigDecimal openPrice,
        BigDecimal highPrice,
        BigDecimal lowPrice,
        BigDecimal closePrice,
        long volume,
        String currency) {

    /**
     * API가 보낸 오프셋 그대로 거래일을 읽는다.
     * OffsetDateTime으로 자동 바인딩하면 Jackson의 ADJUST_DATES_TO_CONTEXT_TIME_ZONE이
     * 자정+KST 타임스탬프를 UTC로 정규화해서, 모든 한국 캔들이 전날로 밀린다.
     */
    LocalDate tradingDate() {
        return OffsetDateTime.parse(timestamp).toLocalDate();
    }
}

이 버그는 테스트를 먼저 작성해서 잡았습니다. 캔들 3개를 오름차순으로 정렬했을 때 날짜가 기대한 순서로 나오는지 검증하는 테스트를 짜는 과정에서, 실제 날짜가 하루씩 어긋나 있는 걸 발견했습니다.

시세 API의 한계 — 등락률도, 거래량도, 52주 고저도 없다

시세 조회 응답을 실제로 받아보고 알게 된 사실이 있습니다.

{ "result": [{ "symbol": "000000", "timestamp": "...", "lastPrice": "48000", "currency": "KRW" }] }

마지막 체결가만 줍니다. 등락률, 거래량, 52주 고저가 전혀 없습니다. 이건 알림 조건 6개 중 4개(등락률, 거래량 급증, 52주 신고가/신저가)가 실연동 모드에서 쓸 데이터가 없다는 뜻이었습니다.

캔들로 파생 계산하기

전용 엔드포인트를 문서에서 찾지 못한 상태라, 이미 확인된 캔들 API(고가/저가/거래량/종가)로 부족한 값을 직접 계산하기로 했습니다.

static QuoteEnrichment computeEnrichment(List<Candle> candles, BigDecimal lastPrice, LocalDate quoteDate) {
    if (candles.isEmpty()) {
        return QuoteEnrichment.EMPTY;
    }

    // 52주 고저 = 받아온 캔들 히스토리 전체의 최댓값/최솟값, 오늘 현재가도 후보에 포함
    BigDecimal week52High = candles.stream().map(Candle::high).max(Comparator.naturalOrder()).get().max(lastPrice);
    BigDecimal week52Low = candles.stream().map(Candle::low).min(Comparator.naturalOrder()).get().min(lastPrice);

    // 등락률 = 마지막 체결가 vs 직전 거래일 종가
    List<Candle> priorDays = candles.stream().filter(c -> c.date().isBefore(quoteDate)).toList();
    BigDecimal changeRate = null;
    if (!priorDays.isEmpty()) {
        BigDecimal previousClose = priorDays.get(priorDays.size() - 1).close();
        if (previousClose.signum() != 0) {
            changeRate = lastPrice.subtract(previousClose)
                    .divide(previousClose, 6, RoundingMode.HALF_UP)
                    .multiply(BigDecimal.valueOf(100))
                    .setScale(2, RoundingMode.HALF_UP);
        }
    }

    // 거래량 급증 = 가장 최근 캔들 거래량 vs 그 이전 20일 평균
    // (날짜가 아니라 "마지막 vs 나머지" 구조로 판단 — 최신 캔들이 자기 자신을
    //  평균에 중복으로 반영하지 않도록)
    long volume = candles.get(candles.size() - 1).volume();
    List<Candle> volumeBaseline = candles.size() > 1 ? candles.subList(0, candles.size() - 1) : List.of();
    // ... 이전 20일 평균 계산
    ...
}

이 파생 계산에는 한계가 명확합니다. 그리고 그 한계를 과장하지 않고 그대로 문서화해뒀습니다.

• "52주"라고 부르지만, 캔들 API가 count 파라미터를 받지 않아서 실제로는 API가 기본으로 주는 히스토리만큼입니다. 정확히 252거래일을 보장하지 않습니다.
• 거래량은 실시간 체결량이 아니라 가장 최근에 확정된 일봉의 거래량입니다. 장중 실시간 급증 감지가 아니라 "최근 일봉 vs 과거 평균" 비교에 가깝습니다.

이 함수는 캔들 API를 호출해서 계산하는데, 시세 조회마다 매번 캔들을 다시 받아오면 API 호출이 배로 늘어납니다. 그래서 캔들 히스토리는 심볼당 30분 캐싱했습니다 — 하루 단위로 바뀌는 데이터라 60초 폴링마다 새로 받아올 이유가 없기 때문입니다. 캔들 조회가 실패해도 시세 조회 자체는 계속 동작하도록, 실패 시 빈 값으로 감싸서 반환하게 만들었습니다.

결과

이 두 편(5~6편)을 거쳐, 목표가 조건은 원본 데이터로, 나머지 4개 조건은 캔들 기반 파생값으로 실연동 모드에서 전부 동작하게 됐습니다.

다음 편부터는 기능이 아니라 서비스 품질을 개선한 이야기입니다. 시세를 종목마다 개별 조회하던 구조를 배치로 바꾼 과정과, 같은 조건이 계속 충족될 때 알림이 반복해서 오던 문제를 다룹니다.