안녕하세요, 카카오 기술 블로그 독자 여러분!

Technical Writing(TW) 에이전트 프로젝트의 네 번째 소식입니다. 정말 오랜만이에요. AI야, 문서 좀 대신 써 줘 - 3. 짧고 간결하게! 연재 후 지난 4개월간 저는 쏟아지는 기술 소식 속에서도 본업을 꾸준히 이어가고 있었습니다. 그동안 AI 기술과 서비스들이 눈에 띄게 발전했으니, 이번에는 프로젝트를 좀 더 수월하게 이어갈 수 있지 않을까 기대하는 마음으로 다시 시작해 보려고 해요.

해야 할 일

지금까지의 TW 에이전트 프로젝트 진행 상황은 아래와 같아요.

최신 AI 모델들이 기술 문서를 얼마나 잘 이해하는지 실험
복잡한 기술 정보를 이해하고 명확하게 설명하는 능력 검증
카카오 기술 문서 템플릿과 스타일 가이드 준수 능력 확인

지금까지는 가능성을 확인하는 과정이었다면, 이제 진짜로 TW 에이전트를 만들어 볼 시간이에요. 먼저 사내 웹 서비스 형태의 TW 에이전트를 만들어보려고 해요. 간단한 스크립트 형태로 만들어 보는 것도 방법이지만, 이왕 만드는 거 동료들과 함께 사용할 수 있는 웹 서비스 개발에 도전해 보기로 했어요.

어떤 서비스를 만들까?

먼저, TW 에이전트가 어떤 서비스인지 정해야 해요. 그래서 Claude와 함께 TW 에이전트 서비스를 기획했어요. Claude에게 필수 기능, 사용자 흐름, 제약 조건 등을 설명하고, 이를 바탕으로 서비스 기획서를 작성해 달라고 요청했습니다.

작성된 기획서는 제가 검토해서 불필요하거나 지나치게 복잡한 내용이 없는지 확인했어요. 아래는 TW 에이전트의 서비스 기획서 일부입니다.

# 기술 문서 작성 서비스 기획서

## 1. 서비스 개요

### 1.1 서비스명

**TW Agent (Technical Writing Agent)**
*AI 기반 카카오 기술 문서 자동 작성 서비스*

### 1.2 서비스 목적

-  **문제 정의**: 개발자들이 기술 문서 작성에 많은 시간을 소모하고, 일관성 있는 문서 작성에 어려움을 겪고 있음
-  **해결 방안**: AI를 활용하여 카카오 표준 템플릿과 스타일 가이드에 맞는 기술 문서를 자동 생성
-  **기대 효과**: 문서 작성 시간 단축, 품질 일관성 확보, 개발자 생산성 향상

### 1.3 핵심 가치 제안
1.  **시간 절약**: 기존 문서 작성 시간의 70% 단축
2.  **품질 보장**: 카카오 표준에 100% 부합하는 문서 생성
3.  **사용 편의성**: 복잡한 프롬프트 작성 없이 폼 기반 간편 입력
4.  **재사용성**: 한 번 분석한 원본 문서로 다양한 유형의 기술 문서 생성

TW 에이전트 서비스를 어떤 형태로 사용자에게 제공할 것인지 대략적인 설계도 준비했어요. 사용 가능한 사내 인프라와 도구 정보를 제공하고, 효율적인 조합이나 파일 구조 설계 방식을 조언 받으며 고민했어요.

아래는 TW 에이전트의 초기 설계 문서 일부입니다. 실제 구현 시에는 다소 변경된 부분들이 있어요.

# 기술 문서 작성 서비스 설계 요약

## 프로젝트 개요

-  **목표**: AI를 활용한 카카오 기술 문서 자동 작성 서비스
-  **아키텍처**: Next.js 풀스택 + 사내 Inference API 연동
-  **핵심 특징**: 2단계 처리 (문서 분석 → 최종 생성)

## 기술 스택

Frontend: Next.js (14 이상) + TypeScript + Tailwind CSS
Backend: Next.js API Routes
AI 연동: 사내 Inference API (여러 모델 지원)
Storage: 파일 기반 (초기) → SQLite (확장)
Deployment: Docker 이미지 + Kubernetes

## 핵심 아키텍처: 2단계 문서 처리

### 1단계: 문서 분석 & 중간 저장

원본 문서(들) → AI 분석 → 구조화된 데이터 → 중간 저장소

- 긴 문서는 청크 단위로 분석
- 분석 결과를 구조화하여 저장
- 토큰 효율성 및 디버깅 용이성 확보

### 2단계: 최종 문서 생성

중간 분석 데이터 + 사용자 요구사항 → AI 생성 → 최종 기술 문서

- 카카오 템플릿 & 스타일 가이드 적용
- 사용자별 맞춤 요구사항 반영

어떻게 서비스를 만들까?

서비스 기획서와 설계 문서를 정리한 뒤, 막상 개발을 시작하려니 문제가 생겼습니다. TW 에이전트를 함께 개발해 줄 개발자 동료가 없었습니다! 게다가 저 자신도 개발자로 일한 경험이 전혀 없었고요.

다만, 개발자를 위한 기술 문서를 써 온 테크니컬 라이터로서 기술에 대한 기본적인 이해와 간단한 코드를 다룰 수 있는 정도의 경험은 있었어요. 그래서 제가 선택한 방법은 바이브 코딩(Vibe Coding)이었습니다.

최근에는 코드 자동 완성이나 AI 기반 코딩 도구들이 정말 다양해졌죠. 저도 평소에 간단한 업무용 도구들을 바이브 코딩으로 직접 만들어 쓰곤 했어요. 예를 들어, 사내 네트워킹 행사를 위한 테이블 배정 앱이나 사내 발표를 위한 웹 프레젠테이션 같은 것들을 만들어 사용했어요.

사내 네트워킹 행사용 테이블 배정 앱

이번 프로젝트도 그 연장선에서 자연스럽게 바이브 코딩을 시도하게 됐습니다.

제가 바이브 코딩에 주로 사용하는 도구는 Claude Code에요. VS Code의 플러그인으로 편리하게 변경사항을 파악하며 바이브 코딩을 할 수 있거든요.

Claude Code에 서비스 기획서, 설계 문서, 도메인명, 데이터베이스 스키마(Schema), 쿠버네티스 배포 설정 등 프로젝트 개발에 필요한 상세 정보를 전달하며 매일 조금씩 개발을 진행했습니다.

카카오는 사내에서 크루들이 AI 활용 경험을 활발히 공유하고 있어요. 덕분에 바이브 코딩에 참고할 자료도 많았어요. 그 중 일부는 AI Native: 실행과 확산 사례집에서 확인하실 수 있어요.

첫 번째 결과물

매일 조금씩 개발을 진행한 결과, 그럴듯한 TW 에이전트 웹 사이트가 만들어졌어요. 오, 놀라워라!

TW 에이전트 웹 사이트는 “당신의 AI 테크니컬 라이터”라는 야심찬 문구도 내걸고 있습니다. 이 웹 사이트가 제공하는 기능은 아래와 같아요.

카카오 사내 Google Workspace 계정 기반 로그인
여러 개의 기술 문서를 포함하는 프로젝트
사용자 요구사항과 참고 자료 입력
LLM을 사용한 요구사항 분석과 기술 문서 작성 계획 수립
기술 문서 작성 계획에 대한 피드백과 보완
LLM을 사용한 기술 문서 작성
기술 문서 작성 결과 미리보기

이러한 기능을 바탕으로 기술 문서가 작성되는 과정은 아래와 같습니다.

사용자가 기술 문서에 해당하는 서비스를 프로젝트로 등록합니다.
사용자가 특정 프로젝트에 필요한 기술 문서 작성을 요청합니다. 요청 시, 기술 문서 초안이나 참고 자료와 요구사항을 입력합니다.
AI가 입력받은 자료와 요구사항을 분석하고 문서 작성 계획을 수립합니다.
사용자가 문서 작성 계획을 검토하고 승인합니다. 필요 시, 피드백을 제출해 문서 작성 계획을 다시 생성할 수 있습니다.
AI가 승인된 작성 계획을 바탕으로 기술 문서를 생성합니다. 추가 확인이 필요한 부분에 대해서는 AI가 질문 목록을 생성합니다.
사용자가 작성된 기술 문서와 질문지를 검토합니다. 필요 시, 결과물을 가지고 다시 기술 문서 작성을 요청할 수 있습니다.

나름대로 실제 기술 문서 작성 과정을 본떠 만들었지만, 작성된 기술 문서의 품질은 기대 이하였습니다. 동료들이 실제로 사용하려면 글쓰기 성능을 개선해야 할 것 같네요.

바이브 코딩을 하며 배운 것

그동안은 바이브 코딩으로 간단한 도구 정도만 만들었을 뿐, TW 에이전트처럼 프론트엔드와 백엔드, DB까지 갖춘 본격적인(?) 서비스를 만들어 본 건 처음이었어요.

그래서 이래저래 시행착오도 많았습니다. 기능 하나하나 구현하는 과정이 험난했습니다. 매일 토큰 부족에 시달리며 조금 더 효율적으로 개발을 진행하려고 노력했습니다. 그 노력을 통해 깨달은 교훈이 있어요.

좋은 프롬프트를 쓰자

처음에는 Claude Code에 원하는 바를 하나씩 설명했지만, 나중에는 해야 할 일에 대해서 Claude 앱에서 AI와 먼저 논의하고, Claude Code에 전달할 프롬프트를 함께 설계했어요. 잘 작성된 프롬프트로 토큰을 많이 아낄 수 있었어요.

예를 들어, 구글 로그인 기능을 구현하고 싶을 때는 아래와 같이 구체적인 프롬프트를 입력하면 더 수월했어요.

# 나쁜 사례
구글 로그인 구현해 줘.

# 좋은 사례
Next.js 14 (App Router) 프로젝트에 구글 Workspace 계정으로 로그인할 수 있도록 Google OAuth 2.0 로그인을 구현해주세요.

요구사항:
- next-auth v5를 사용하여 구글 소셜 로그인 설정
- 로그인 성공 시 사용자 정보(이름, 이메일, 프로필 이미지)를 세션에 저장
- 로그인/로그아웃 버튼이 있는 간단한 UI 컴포넌트 포함
- 환경변수(.env.local) 설정 방법과 Google Cloud Console에서 OAuth 클라이언트 ID 발급받는 방법을 주석으로 설명

콘솔에서 확인할 수 있는 정보:
- 클라이언트 ID:72298…
- 승인된 JavaScript 원본: https://techwriter…

단, 프롬프트를 준비하는 과정에 주의사항이 있어요. 프롬프트 자체가 너무 길면 사용량 제한도 그만큼 빠르게 다가왔습니다. 지나치게 구체적인 요구사항들이 서로 충돌하면서 결과물의 품질이 오히려 낮아지는 경우도 있었고요.

개발 지식은 다다익선

요즘은 Lovable, V0 같은 도구를 쓰면 정말 아무 것도 모른 채로 서비스를 만드는 게 가능한 시대라지만, 실제 서비스에서 발생하는 각종 에러나 예외를 처리할 수 있으려면 개발 지식이 필요했습니다.

그때마다 테크니컬 라이터로서 쌓아온 개발 지식이 큰 도움이 됐어요. 서당개 삼년이면 풍월을 읊는다더니! 가끔은 사용량 제한에 걸리는 바람에 직접 코딩을 마무리해서 그 날의 목표를 마무리하기도 했고요.

그리고 개발 공부를 해두지 않았다면 사내 인프라와 시스템을 사용해 프로젝트를 배포하고 운영하는 것도 불가능했을 것 같아요. 클러스터 생성부터 서비스 배포까지, 카카오의 사내 개발 환경을 온전히 활용해 볼 수 있어서 행복했습니다.

때때로 정리정돈

바이브 코딩을 신나게 하다보면, 어느 순간 제가 읽고 이해할 수 없는 코드들이 누적돼 관리가 어려워지곤 합니다. 그래서 며칠에 한 번씩 더 이상 사용하지 않거나 비효율적인 코드를 정리해달라고 Claude Code에게 요청했어요.

그리고 작업 중 주석과 같이 사람과 AI가 참고할 수 있는 기록들이 잘 남고 있는지 확인했어요. Claude Code 사용 중 기존 대화가 에러로 끊기면, 새로운 세션에서 다시 작업을 이어가야 할 때가 있어요. 그때마다 AI가 프로젝트의 구조와 내용을 다시 파악해야 하기 때문이에요.

테크니컬 라이팅과 프롬프트 엔지니어링

바이브 코딩을 하다 보면, 테크니컬 라이팅과 프롬프트 엔지니어링이 닮았다는 걸 자주 느껴요. 두 작업 모두 명확성, 간결성, 정확성을 핵심 원칙으로 삼고 있거든요.

기술 문서를 쓸 때 독자가 이해하기 쉬운 문장을 고르듯, 좋은 프롬프트를 만들 때도 AI가 이해하기 쉬운 문장을 써야 해요. 또, 대명사 등 오해를 부를 수 있는 표현은 피하고, 의도와 대상을 분명히 드러내야 합니다. 불필요한 수식은 빼고, 정보의 흐름을 단계적으로 따라가기 쉬운 구조를 만들어야 해요.

그래서 저에게 프롬프트를 작성하는 일은 평소의 기술 문서 작성과 크게 다르지 않았어요. 덕분에 프롬프트 엔지니어링 기법들도 훨씬 빠르게 익힐 수 있었습니다. 그저 독자가 AI로 바뀌었다는 느낌이에요.

다음 편 예고

AI가 작성하는 기술 문서의 품질은 어떻게 개선할 수 있을까요? 마지막 편에서는 그 방법에 대한 고민과 실험의 결과를 공유해 보려고 합니다.

그럼, 다음 편에서 또 만나요!

—–

Directed by Yang.me
Written by Talysa.geist
Assisted by Claude and ChatGPT
Special thanks to Benedict.lee

—–

시리즈 모아보기

Vibe Coding 관련 글 모아보기

AI야, 문서 좀 대신 써 줘 - 4. 바이브 코딩