당근을 닮은 해요체와 클로드코드 이야기
해요(Haeyo) - 26.04.01까지 운영:
haeyo.vercel.app
해요체로 블로그 갈아엎기
블로그에 작성된 모든 글을 ‘해요’체로 수정하기 위해 작업을 시작했어요. 2022년부터 지식 공유를 목적으로 티스토리를 운영했는데, 솔직한 경험과 생각을 중심으로 공유하고 싶어서 현재 보시는 jekyll 블로그로 분리했어요. Jekyll은 저를 솔직하게 보여주는 공간이라 친근한 말투를 사용하려 했고, 그 첫 단계가 ‘해요’체 사용이에요. 하지만 비공개 글을 포함해 50개가 넘는 포스트가 있고, 한 포스트 당 평균 6000자에 가까워서 ‘해라’체로 작성된 글을 모두 옮기기 어려웠어요. 그래서 말투와 문법을 자동 교정하는 CLI 툴을 만들었어요.
사용해보니 생각보다 결과가 좋아 남는 토큰을 활용해 웹 서비스로 공유했어요. 친근하고 읽기 쉬운 문장을 만드는 ‘해요(Haeyo)’의 개발과 배포 과정을 이야기해 볼게요.
당근과 토스의 라이팅을 프롬프트로
‘해요’체로 옮기기 위해 가장 먼저 참고한 자료는 당근의 라이팅이에요. 당근 블로그를 보면 편안하고 따뜻한 느낌의 ‘해요’체와 신뢰감을 주는 ‘하십시오체’를 함께 사용해요. 하지만 최근 글이나 기술 블로그를 보면 주로 ‘해요’체를 중심으로 사용하고 있어요. 저도 일관된 톤을 위해 ‘해요’체로 통일하는 방식을 선택했어요.
‘해요’체를 잘 사용하는 기업 중 하나가 토스이에요. 토스 블로그에 따르면 ‘명확하고, 간결하며, 친근하고, 존중하며, 공감하는’ 보이스를 지향한다고 해요. 이런 정체성을 표현하기 위해 사용한 톤을 테크니컬 라이팅 가이드를 통해 공개했어요. 라이팅 가이드는 문장 구성 방법을 자세히 다루고 있어요.
그래서 저는 당근과 토스의 라이팅을 참고해 LLM 프롬프트를 구성했어요. 필요한 자료를 수집한 뒤 GPT의 도움을 받아 프롬프트를 정리했어요. 작업은 톤을 바꾸는 1차 수정과 문장을 교정하는 2차 수정으로 이루어져요.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
[System]
당신은 **기술 조직의 공식 문서를 정제·편집하는 전문 라이터(편집자)**로 동작해요.
입력으로 제공되는 한국어 마크다운 문서는 기술적 사실과 논리 구조가 이미 확정된 상태이며,
당신의 역할은 **내용(사실·수치·정의 등)을 변경하지 않고 표현만 다듬는 것**이에요.
...
[User]
아래 기준에 따라, 제공되는 한국어 마크다운 문서를 재작성하세요. 입력 문서의 사실·구조는 그대로 두고 어투와 흐름만 정돈해요.
## 목표
## 절대 수정하지 말 것
## 허용 수정 범위
## 예제
## 편집 대상 문서
아래 JSON 배열은 편집 대상 문서의 줄 목록이에요. 각 항목의 index는 줄 번호이고, text는 해당 줄 내용이에요.
## 출력 형식
수정이 필요한 줄만 JSON으로 출력하세요. 변경 없는 줄은 출력하지 마세요.
출력 형식:
{
"changes": [
{ "index": 0, "corrected": "수정된 줄 내용" }
]
}
...
1차 프롬프트는 ‘해요’체 변환을 중심으로 구성했어요. 주로 당근의 톤을 참고해 문장을 수정하도록 했고, 출력은 JSON 형식으로 수정된 문장만 내보내도록 했어요. 이 방식은 (1) 불필요한 수정을 줄이고 (2) 출력 토큰 비용을 절감할 수 있어요. 1차 수정은 톤을 제외한 문장 구성은 최대한 바꾸지 않도록 했어요. 반면 2차 수정은 문장 교정을 위해 더 강하게 개입해요.
1
2
3
4
5
6
7
8
9
10
11
12
13
[System]
당신은 한국어 기술 문서 스타일 리뷰 및 수정 전문 LLM에요.
입력으로 주어지는 글을 읽고, 제공된 체크리스트를 기준으로 문장을 검토해요.
...
[User]
아래 지시를 따른다.
## 절대 수정하지 말 것 (가이드 위반 여부와 무관)
## 검토 및 수정 규칙
## 가이드
## 편집 대상 문서
## 출력 형식
2차 프롬프트는 ‘해요’체로 수정된 문장에서 문법 실수, 어색한 표현, 복잡한 구조 등을 찾아 교정해요. 문장을 읽기 쉽게 만드는 역할이에요. ## 가이드는 토스 라이팅 가이드 중 현재 톤에 맞는 요소만 추출해 구성했어요. 예를 들어, ‘능동형으로 표현한다’, ‘불필요한 한자어를 제거한다’ 등이 있어요. 이제 정리한 프롬프트를 실제 서비스에 적용하는 작업을 할게요.
아키텍쳐 그려보기
프론트엔드는 SvelteKit을 사용했어요. 본 서비스는 API 엔드포인트를 통해 2단계 LLM 추론을 수행하기 때문에 별도의 백엔드 구성 없이 API routes를 지원하는 풀스택 프레임워크를 사용하면 돼요. 그래서 풀스택 개발이 가능한 ‘Next.js’, ‘Nuxt.js’, ‘SvelteKit’을 후보로 고려했어요. 적절한 프레임워크를 선택하기 위해 현재 상황을 살펴봤어요. 초기 운영 비용을 최소화하기 위해 서버리스 환경의 무료 티어를 활용할 계획이에요. 무료 티어는 상대적으로 적은 리소스(CPU/RAM)를 사용한다는 점을 고려했어요. 두 번째로, 제작하는 서비스가 복잡하지 않은 점이에요. 텍스트를 입력받아 2번의 API 요청만 주고받는 단순한 구조라 SvelteKit이면 충분하다고 판단했어요. Next.js나 Nuxt.js는 런타임에 가상 DOM을 조작하지만, SvelteKit은 빌드 타임에 바닐라 JS로 컴파일해 DOM을 직접 조작해요. 덕분에 적은 리소스로 운영할 수 있고 번들 크기가 작아 콜드 스타트도 비교적 빨라요.
배포는 Vercel을 사용했어요. Vercel은 GitHub과 연동해 코드 한 줄 없이 프론트엔드를 배포할 수 있는 Frontend-as-a-Service(FaaS) 플랫폼이에요. Vercel은 월 1,000,000번의 무료 요청을 지원해 토이 프로젝트 배포에 적합해요. 배포 후 사용자가 소비한 토큰과 응답 시간을 수집하기 위해 Turso DB를 사용했어요. Turso는 SQLite의 오픈소스 포크인 libSQL 기반 관계형 DB로, 개발 환경에서 사용한 SQLite 쿼리를 배포 환경에서도 사용할 수 있고, 매우 가벼우며, Vercel과 연동이 쉽다는 장점이 있어요. 단순 로그 수집에는 화려한 DB 기술이 필요 없다고 판단해 Vercel과 Turso를 이용해 배포 환경을 구축했어요.
LLM 모델로는 GPT 모델군을 사용했어요. OpenAI를 선택한 이유는 한 달 내 만료되는 토큰을 소진하기 위해서였어요. 토큰 만료 후에는 Claude나 ClovaX로 전환하는 방안도 고려 중이에요. 모델 선택에 관한 자세한 내용은 아래 챕터에서 다룰게요.
추론 속도 줄이기
초기 프로토타입은 GPT-5-mini를 사용했어요. 성능이 뛰어나고 토큰 비용도 저렴해서 선택했는데, 실행해보니 응답 속도가 매우 느렸어요.
| 모델 | 응답 속도 (s) | 입력 비용 ($/1만 토큰) | 출력 비용 ($/1만 토큰) |
|---|---|---|---|
| GPT-5 | 36.38 | 1.25 | 10.00 |
| GPT-5 mini | 10.94 | 0.25 | 2.00 |
| GPT-5 nano | 19.01 | 0.05 | 0.40 |
| GPT-4.1 mini | 3.30 | 0.40 | 1.60 |
| GPT-4o mini | 5.59 | 1.10 | 4.40 |
위 표는 1차 수정에 대한 API 응답 속도를 비교한 결과예요. GPT-5 시리즈가 다른 모델에 비해 유독 오래 걸렸어요. 확인해보니 GPT-5는 추론에 특화된 모델로, 이전과 달리 reasoning_effort 파라미터를 사용해 내부에서 반복적인 추론을 수행하기 때문에 응답이 오래 걸렸어요. 하지만 ‘해요’체 다듬기 작업에는 추론 성능이 크게 필요하지 않았고, 실제 출력 결과도 GPT-5와 GPT-4.1-mini가 크게 다르지 않았어요. 그래서 1차 수정 API는 GPT-4.1-mini를 사용하기로 했어요.
2차 수정은 모델 선택에 따라 출력 퀄리티가 달라졌어요. GPT-5-nano는 교정할 문장을 찾지 못해 빈 리스트를 반환했어요. GPT-5-mini와 GPT-4.1-mini는 문장을 잘 수정했지만 약간의 차이가 있었어요.
수정전: “일부 과제에서 baseline 모델들은 0점을 달성했으나, gemini-robotics는 과제에 따라 적게는 45%부터 높게는 100%의 성공률을 보이며 다른 모델 대비 눈에 띄게 높은 성공률을 보였습니다.”
GPT-5-mini: “일부 과제에서 baseline 모델들은 0점을 기록하는 반면, gemini-robotics는 과제에 따라 성공률이 적게는 45%에서 많게는 100%까지 나타나서 다른 모델보다 눈에 띄게 높아요.”
GPT-4.1-mini: “일부 과제에서 baseline 모델들이 0점을 받았으나, Gemini-robotics는 과제별로 최소 45%에서 최대 100% 까지 성공률을 보여 다른 모델보다 눈에 띄게 좋은 성과를 냈어요.”
위 수정 예시에서 GPT-5-mini는 ‘반면’을 사용했고 GPT-4.1-mini는 ‘받았으나’를 사용했어요. 저는 한자어 접속 부사인 ‘반면’보다 ‘~으나’로 이어지는 문장을 선호하기 때문에 GPT-4.1-mini가 더 잘 수행했어요. 다음 문장은 원문에서 ‘성공률’을 두 번 사용해 복잡했는데, 수정된 문장은 모두 잘 다듬어졌어요. GPT-5-mini는 원본 구조를 유지했지만, GPT-4.1-mini는 ‘최소 ~ 최대 ~ 성공률을 보여’로 문장 구조를 수정했어요. 원문을 최대한 해치지 않으려 한 GPT-5-mini 쪽이 더 좋았어요.
수정전: “Gemini-robotics의 가장 큰 장점은 범용 지식을 학습하고 있다는 점이에요.”
GPT-5-mini: (수정없음)
GPT-4.1-mini: “Gemini-robotics는 범용 지식을 학습하는 것이 가장 큰 장점이에요.”
원문은 ‘~장점은’을 주어로 사용했고 GPT-5-mini는 ‘도구나 기술, 시스템을 행동 주체로 사용하지 않는다’는 지시문에 따라 원문을 유지했어요. 반면 GPT-4.1-mini는 ‘Gemini-robotics’를 주어로 사용해 지시문을 따르지 않았어요. 2차 수정은 reasoning 능력이 있는 GPT-5-mini가 더 잘 수행했지만, 응답 시간은 30초 이상으로 GPT-4.1-mini보다 10배 이상 길었어요. UX를 고려해 2차 교정은 선택 가능하도록 하고 기본 설정은 opt-out으로 해 초기 사용 경험을 해치지 않도록 하는 게 좋아 보여요.
클로드와 함께하는 바이브코딩
실제 코딩은 클로드코드를 이용해 바이브 했어요. 무작정 지시를 내리는 것보다 bkit의 PDCA를 사용하면 정교한 지시가 가능해져요. PDCA는 Plan-Do-Check-Act 전략으로 계획을 먼저 세운 뒤 개발을 시작하고, 개발을 마치면 설계대로 잘 구현되었는지 확인하는 사이클을 뜻해요. bkit은 클로드코드에서 PDCA를 적용할 수 있도록 도와주는 플러그인이에요. 개발자가 plan 명령을 실행하면 요구사항 초안이 마크다운 파일로 작성돼요. 개발자가 문서의 세부사항을 수정한 뒤 design 명령으로 아키텍처 설계를 생성해요. 다시 개발자가 문서를 수정한 뒤 do, analyze 순서로 개발과 검토를 진행해요. 마지막으로 개발자가 코드를 직접 리뷰하고 수정을 적용하면 소프트웨어가 완성돼요.
개발은 빨라졌지만 여전히 코드 리뷰는 중요해요. 클로드가 생성한 코드에는 세부 정책에 문제가 있었어요. 예를 들어, CORS 정책을 설정하지 않아 외부에서 API 호출이 가능한 문제가 있었어요. 프론트의 경우, 반응형 디자인을 고려하지 않아 모바일 화면에서 입력창이 지나치게 작아지는 문제도 발견했어요. DB는 불필요하게 테이블을 조회하는 로직이 있어 리소스 낭비가 발생했어요. 물론 소스코드와 문제를 함께 전달하면 클로드가 잘 수정했어요. 이런 점을 보면 개발자가 코드를 살펴보며 예상되는 문제를 조기에 발견하고 대처하는 능력은 여전히 중요해 보여요.
클로드코드와 Vercel을 사용하니 개발, 리뷰, 배포까지 이틀만에 완료했어요. 이제는 코드만 잘 짜는 건 정말 의미가 없어진 듯 해요. 문제를 정의하고, 설계를 최적화하고, 문제를 조기에 찾아내는 사고력과 판단력이 중요하다는 걸 다시 한 번 깨달았어요. 서비스는 GPT 토큰이 만료되면 4월 초에 내릴 생각이에요. 이번에는 제가 필요한 건 만들어 봤다면 다음에는 사람들이 필요한 서비스를 만들고 트래픽을 늘리는 게 목표에요. 이번 프로젝트를 연습 삼아 더 재밌는 프로젝트로 돌아올게요.
인터넷에는 아마추어들이 만든 웹사이트, 이메일, 동영상이 가득하다. 이 아마추어들은 자신이 좋아하는 것을 만든다. 그건 괜찮다. 전문가들은 당신을 위해 다른 사람들이 좋아할만한 것을 디자인한다. 사람들에게 그들만의 마법을 연상시키는 외양과 느낌을 창조한다. - 세스 고딘, ‘마케팅이다’.