코드에서 문서로, 문서에서 답으로: 클라썸의 사내 AX 이야기
안녕하세요, 클라썸 Platform Engineering 팀의 Naco입니다.
제품 코드로 정책 문서와 사용설명서를 자동으로 만들고, 그 문서로 동료의 질문에 답하기까지 클라썸 팀이 사내 AX를 하며 겪은 문제와 풀어 간 방법을 공유합니다.
“웹페이지를 데이터 소스에 어떻게 추가해요?”
“동기화는 하루에 몇 번 진행되나요?”
“웹페이지 동기화가 실패하면 고객사에 어떻게 안내하기로 했었죠?”
클라썸 사내 메신저에는 이런 질문이 자주 올라옵니다. 내용을 아는 사람에게는 셋 다 쉬운 질문입니다. 하지만 정확하게 답하려면 생각보다 번거로운 과정을 거쳐야 합니다.
제품이 빠르게 업데이트되다 보니 사용설명서는 이미 배포된 제품과 달라져 있습니다. 메신저에서 논의했던 스레드는 한참 위로 밀려나 있습니다. 애써 찾아낸 정책 문서도 시간이 지나 틀려 있어서, 결국 실제 코드를 열어 봐야 답할 수 있습니다. 그러다 급한 마음에 가장 최근에 작업한 담당자를 찾아가게 됩니다.
질문 하나에 두 사람의 시간이 쓰이는 셈입니다. 묻는 사람은 답을 기다리고, 답하는 사람은 하던 일을 멈춥니다. 같은 질문이 다시 오면 이 과정이 처음부터 반복됩니다.
클라썸 팀이 풀고 싶었던 건 이 반복이었습니다. 문서를 대신 써 주는 AI를 만드는 게 아니라, 확인하고 정리하는 일은 자동화에 맡기고 동료들은 판단이 필요한 일에만 시간을 쓰게 하는 것. 사내 AX를 시작하며 세운 목표였습니다.
그래서 이 문제를 두 개의 시스템으로 나눠 풀었습니다.
- 클라썸 콘텐츠 플랫폼(이하 CCP)은 제품 코드를 바탕으로 정책 문서와 사용설명서를 자동으로 생성하고, 검토자가 그 결과를 검토, 수정, 공개하는 서비스입니다.
- 도트는 사내 메신저의 대화 내역과 CCP가 공개한 문서, 사내 위키, 필요하면 제품 코드까지 찾아 답하는 에이전트입니다.
CCP와 도트를 나눈 이유는 맡은 책임이 다르기 때문입니다. 도트가 질문을 받을 때마다 제품 코드를 처음부터 읽고 정책을 새로 판정할 수는 없습니다. 반대로 CCP가 동료들의 모든 질문을 미리 예상해 답을 만들어 둘 수도 없습니다.
그래서 문서를 만드는 쪽이 출처와 검토 상태, 공개할 버전을 책임지고, 답하는 쪽은 그 정보를 바탕으로 질문에 맞는 근거를 고르게 했습니다.
이 글은 CCP가 정책 문서와 사용설명서를 어떻게 만드는지, 검토자가 그 결과를 어떻게 확인해 공개하는지, 도트가 공개된 문서로 어떻게 답하는지를 차례로 따라간 뒤, 그 결과를 정리합니다.
1. 코드에서 정책 문서 만들기
코드가 문서가 되기까지
도메인: 기능을 나누는 기준
이 여정은 올해 3월의 한 회의에서 시작했습니다. 한 번 쓰고 방치되는 PRD나 그때그때 묻는 AI 에이전트에 기대는 대신, 언제나 최신 기능과 정책을 담고 있는 프로덕션 코드에서 답을 만들어 두자는 이야기였습니다. LLM이 코드를 읽고 자연어로 문서를 써 두면, 배포된 제품의 정책과 사용 방법을 바로 파악할 수 있다는 아이디어입니다.
끝없이 바뀌는 코드에서 일정한 품질의 문서를 안정적으로 만들려면 먼저 답해야 할 질문이 있었습니다. “제품을 어떻게 정적으로 나눌 수 있을까?”
출발점은 백엔드는 컨트롤러, 프런트엔드는 라우터를 기준으로 영역을 나누는 것이었습니다. 컨트롤러는 어떤 요청을 받는지, 라우터는 사용자가 어떤 경로로 들어오는지 알려 주는 입구입니다. 이 입구에서 서비스, 엔티티, 컴포넌트를 따라가며 한 기능을 이루는 코드의 범위를 좁혔습니다.
LLM에게 저장소 전체를 주고 매번 새로 분류하게 하는 대신, 코드에서 반복해서 찾을 수 있는 기준을 먼저 세웠습니다. 같은 코드에서는 항상 같은 묶음이 나와야, 바뀐 코드가 어느 문서에 영향을 주는지 자동으로 판단할 수 있기 때문입니다.
이렇게 묶은 단위를 도메인이라고 불렀습니다. 백엔드 코드는 누가 어떤 상태에서 요청할 수 있는지를 정하고, 프런트엔드 코드는 그 기능이 어디에 어떤 모습으로 드러나는지를 정합니다. 도메인은 이 두 쪽의 근거를 하나의 정책 아래 모으는 그릇입니다.
도메인은 세 층으로 설계했습니다.
- Domain Map: 한 도메인의 정책을 쓸 때 실제로 읽을 파일 목록
- Domain Tree: 도메인 사이의 관계를 나타내는 트리 구조
- Domain Dictionary: 코드의 이름과 서비스에서 보이는 이름의 연결
CCP에서는 검토자가 도메인을 더 쉽게 다룰 수 있도록 세 층을 역할에 맞게 나눴습니다.
Tree는 무엇을 어떤 순서로 문서화할지 정하는 편성표가 됐습니다. Dictionary는 코드의 도메인을 어느 문서가 맡는지 잇는 연결표와, 코드의 변수명을 서비스의 표현으로 바꾸는 용어 사전으로 나뉘었습니다.
- 편성표: 어떤 문서를 쓰고 뺄지, 어느 구획에 어떤 순서로 둘지 정의합니다.
- 연결표: 코드의 도메인을 어느 문서가 맡는지 잇습니다.
- 용어 사전: 코드의 변수명을 서비스의 표현으로 바꿉니다
증거 묶음: 코드에서 팩트 추출하기
이제 커넥트의 ‘데이터 소스 관리’ 정책 문서 한 편이 만들어지는 과정을 따라가 보겠습니다. 웹페이지와 유튜브 동기화, 파일 업로드처럼 데이터 소스에 관한 규칙을 모은 문서입니다.
정책 문서에서 가장 틀리기 쉬운 문장은 “최대 몇 개”, “며칠 이내” 같은 한도입니다. LLM에게 코드를 읽고 바로 쓰게 하면, 그 숫자가 정말 코드에서 온 것인지 확인할 방법이 없습니다.
그래서 첫 단계에는 LLM이 관여하지 않습니다. 스캐너가 Domain Map에 적힌 이 문서의 백엔드와 프런트엔드 코드를 읽고, 문서를 쓸 때 참고할 사실을 하나의 증거 묶음으로 만듭니다.
증거 묶음에는 API와 인증 방식, 저장 필드의 타입과 길이, 오류 코드, 알림, 그리고 코드에 적힌 상수가 들어갑니다.
상수는 100 * 1000 * 1000처럼 적힌 값도 미리 계산해 두고, 곱해진 수 하나하나도 후보로 남깁니다. 나중에 원고를 검사할 때 “100MB”의 100이 정말 코드에서 온 숫자인지 확인하기 위해서입니다.
초안 작성: LLM이 필드 채우기
다음으로 LLM이 증거 묶음과 원본 소스 코드를 함께 읽고 초안을 씁니다. 문서의 제목과 다룰 범위, 용어 사전, UX 라이팅 규칙도 함께 프롬프트로 받습니다.
그런데 LLM이 쓴 문장은 어떻게 검사할 수 있을까요? 줄글로 받으면 어느 문장이 어느 코드에서 왔는지, 숫자가 맞는지를 결국 사람이 처음부터 다시 읽어야 합니다.
그래서 초안을 읽기 좋은 문서가 아니라, 한 줄 요약과 주장(claim) 목록이 담긴 커다란 JSON으로 받습니다. 규칙, 한도, 오류 코드, 접근 권한 같은 정책 하나하나가 각각 하나의 주장이 되고, 주장마다 근거가 되는 코드 위치가 붙습니다. LLM이 근거 코드를 찾지 못한 내용은 지어내지 않고 ‘확인하지 못한 것’으로 따로 남깁니다.
이 JSON의 형식, 즉 스키마는 CCP가 미리 정해 둡니다. 한 줄 요약, 주장 목록, 확인하지 못한 것처럼 들어갈 필드가 정해져 있고, LLM은 그 필드를 채울 뿐입니다. 스키마를 정해 두면 좋은 점이 세 가지 있습니다.
- 검사할 수 있습니다. 주장마다 근거 코드가 붙어 있으니, 문장 하나하나를 코드와 대조할 수 있습니다.
- 검토자의 수정이 지켜집니다. 필드마다 따로 저장하므로, 검토자가 어느 필드를 고쳤는지 정확히 알 수 있습니다. 그래서 문서를 다시 생성해도 그 수정을 덮어쓰지 않습니다.
- 어느 문서든 같은 순서로 읽힙니다.
게이트 5종: 통과하지 못한 곳만 LLM이 다시 쓰기
초안은 완성되기 전에 다섯 가지 자동 검사를 통과해야 합니다. 이 검사들을 게이트라고 부릅니다.
- 근거 파일이 이 문서가 맡은 도메인 안에 있는가
- 한도의 숫자가 코드에서 뽑은 상수와 일치하는가
- 용어 사전에 따라 코드 변수명이 서비스 용어로 바뀌었는가
- UX 라이팅 규칙을 지켰는가
- 편성표가 반드시 다루라고 한 사실이 문서에 담겼는가
게이트는 LLM을 쓰지 않는 검사 코드입니다. 같은 원고를 넣으면 언제나 같은 결과가 나옵니다. 근거가 존재하고 그럴듯해 보여도, 원고가 증거 묶음과 어긋나면 통과하지 못합니다. 사람이 일일이 대조하던 일을 매번 같은 기준으로 자동화한 셈입니다.
게이트를 통과하지 못하면 문서를 다시 쓰게 합니다. 처음에는 매번 처음부터 새로 쓰게 하고, 위반이 가장 적은 시도를 골랐습니다. 그런데 다시 쓸수록 문서에서 사실이 줄어들었습니다. 게이트는 주장을 검사하니, 주장을 지울수록 위반도 줄어들었기 때문입니다.
위반이 적은 문서가 좋은 문서는 아니었습니다.
그래서 직전 시도의 산출물과 위반 내용을 함께 넘기고, 통과하지 못한 곳만 고치게 했습니다. 여러 시도 가운데 하나를 고를 때도 위반 수만 보지 않고, 사실을 얼마나 지켜 냈는지를 함께 봅니다.
세 번까지 시도해도 위반 사항이 남으면, 문서를 버리지 않고 일단 다음 단계로 넘깁니다. 대신 남은 위반을 검토자에게 보여 주고, 실제로 코드에 문제가 있는 건 아닌지 확인하게 합니다.
채점: 신뢰 상태와 품질 점수 남기기
CCP는 문서마다 상태를 남깁니다. 정책이 부족한 곳이 있는지, 근거를 확인하지 못한 주장이 있는지를 문서에 그대로 적어 둡니다.
게이트를 통과한 초안은 한 번 더 평가를 받습니다. 초안을 작성한 모델과는 다른 LLM 모델을 이용해 정확성, 빠진 내용, 용어, 흐름, 독자에게 맞는지를 기준으로 점수를 매깁니다.
이 상태와 점수는 문서와 함께 공개됩니다. 나중에 도트가 이 문서를 근거로 답할 때도, 이 정보를 보고 답을 얼마나 확신할지 정합니다.
틀리지 않게, 비싸지 않게
충돌하는 정책과 운영에만 있는 정책 다루기
서로 다른 저장소의 코드가 서로 다른 정책을 말하기도 합니다. 프런트엔드에서만 입력을 막고 API는 막지 않는다거나, 백오피스의 안내 문구가 실제 동작과 다른 경우입니다.
정책 문서를 생성하다 보면 이런 차이가 분명하게 드러납니다. 이때 LLM이 둘 중 그럴듯한 쪽을 골라 버리면, 팀은 그 차이를 알아챌 기회를 잃습니다. 그래서 CCP는 어느 층에서 어떤 차이가 있는지 문장으로 남기고 검토자에게 알립니다. 이 충돌은 검토자가 한쪽을 고를 때까지 문서에서 지워지지 않습니다.
반대로 코드에는 없는 정책도 있습니다. 운영상 꼭 문서에 담아야 하는 사실은 편성표에 ‘반드시 다룰 사실’로 넣습니다. 이 사실은 문서에서도 운영에서 정한 사실로 구분해 표시합니다. 코드가 그렇게 동작하는 것과 팀이 그렇게 정한 것을 독자가 구분할 수 있게 하기 위해서입니다.
지문: 코드가 바뀐 문서만 다시 쓰기
제품 코드는 매주 바뀝니다. 그렇다고 그때마다 모든 문서를 다시 쓰면 시간과 비용이 감당되지 않습니다.
그래서 문서마다 읽은 증거 묶음과 편성표, 용어 사전, 모델 설정을 묶어 고유한 지문을 만듭니다. 지문이 같으면 다시 생성하지 않고 이전 문서를 그대로 사용합니다. 다시 써야 할 때는 무엇이 바뀌어서 다시 쓰는지도 함께 기록해, 그 비용이 꼭 필요했는지 확인할 수 있게 했습니다.
스캐너가 어느 문서에도 속하지 않는 새 코드 영역을 찾으면, 새 문서로 만들지 기존 문서에 붙일지를 검토자에게 묻습니다. 정해지기 전까지 그 영역은 제안으로만 남습니다.
2. 실제 화면으로 사용설명서 만들기
화면이 설명서가 되기까지
소스 코드를 읽고, 설명할 범위를 정하고, 초안을 만들고, 검토자가 고친 내용을 반영한다는 점에서 사용설명서도 정책 문서와 같은 플랫폼 위에서 만들 수 있었습니다.
다만 고객이 직접 읽는 사용설명서에는 더 다듬어진 문장과 실제 제품 화면이 필요합니다. 캡처하고, 자르고, 문서에 붙였고, 제품이 바뀔 때마다 이 일을 다시 해야 했습니다. CCP는 이 과정까지 자동화했고, 그래서 몇 가지 단계가 더 들어갑니다.
첫 번째 질문이었던 ‘웹페이지 동기화하기’를 예로 들어 보겠습니다.
- 데이터 소스 목록에서 ‘업로드’를 클릭합니다.
- 업로드 방식 가운데 ‘개별 웹페이지 동기화’를 선택합니다.
- 웹페이지 이름과 URL을 입력하고 ‘동기화’를 클릭합니다.
세 번의 조작은 모두 다른 화면에서 일어납니다. 독자가 헷갈리지 않으려면, 각 단계의 설명 옆에 바로 그 순간의 화면이 붙어 있어야 합니다. 문장과 그림이 같은 순간을 가리키게 하려면, 글을 쓰기 전에 사용자가 할 일과 촬영할 장면부터 정해야 했습니다.
카탈로그: 제품 화면 분석하기
LLM에게 코드만 주고 사용설명서를 쓰게 하면, 화면을 보지 못하기 때문에 버튼 이름이나 클릭하는 순서처럼 화면을 봐야 알 수 있는 내용이 틀리기 쉽습니다.
그래서 사용설명서도 소스 코드 스캔에서 시작합니다. 스캐너는 라우트와 페이지 컴포넌트뿐 아니라 다음 내용까지 읽어 카탈로그를 만듭니다.
- 화면에 보이는 문구
- 버튼과 입력 같은 조작이 무엇을 하는지
- 그 화면에서 호출하는 API
- 코드에 적힌 한도
예시의 경우 ‘업로드’ 버튼을 클릭하면 창이 열리고, ‘개별 웹페이지 동기화’ 카드로 방식을 고른다는 사실이 카탈로그에 적힙니다. 이 카드가 ‘업로드’를 클릭해야 나타난다는 관계까지 함께 적힙니다. ‘동기화’ 버튼은 올바른 URL이 있어야 켜진다는 조건과 한 번에 100행까지 입력할 수 있다는 한도도 코드에서 뽑아 카탈로그에 담습니다.
원고의 문장은 LLM이 화면을 상상해서 쓴 것이 아니라, 이 카탈로그의 항목을 하나하나 문장으로 옮긴 것입니다.
카탈로그에서 설명서 후보가 나오면, 정책 문서와 마찬가지로 편성표가 무엇을 쓸지 정합니다. 어떤 설명서를 쓰고 뺄지, 어느 구획에 둘지, 반드시 다룰 내용이 무엇인지가 여기서 정해집니다.
시나리오: 촬영 방법 정하기
무엇을 쓸지 정해지면, 그 내용을 보여 줄 장면을 정합니다. 화면마다 촬영 시나리오가 있습니다. 어느 주소에서 시작해 무엇을 클릭하고 무엇이 보일 때까지 기다릴지, 그 화면이 부르는 API에 어떤 응답을 줄지를 적은 파일입니다.
처음 문서화하는 기능이나 새로 생긴 화면에는 아직 시나리오가 없습니다. 이런 화면은 LLM이 시나리오를 새로 쓰게 되는데, 코드만 읽어서는 어떤 API가 언제 불리는지 다 알 수 없습니다. 그래서 시나리오를 쓰기 전에 먼저 Playwright로 화면을 실제로 열어 보고, 어떤 API가 호출되고 화면에 무엇이 보이는지를 기록해 LLM에게 넘깁니다.
화면에 들어갈 데이터도 목적에 맞게 준비합니다. 예를 들어 데이터 소스 목록 화면은 파일, Q&A, 웹페이지, 유튜브처럼 다양한 종류의 항목이 있어야 그 역할이 한눈에 읽힙니다. 연결이 끝난 항목과 진행 중인 항목이 섞여 있어야 여러 상태 표시도 한 장면에 드러납니다. 응답의 모양은 제품 SDK의 응답 스키마로 맞추고, 그 안에 들어갈 값은 LLM이 화면에 맞게 채웁니다.
조작 단위로 장면 촬영하기
모든 화면은 실제 프런트엔드 코드를 실행해 촬영합니다. 시각과 언어, 테마를 고정하고, 촬영 직전에는 설명하려던 요소가 실제로 보이는지 확인합니다.
시나리오에 장면을 일일이 적지는 않습니다. 생성 파이프라인이 조작의 종류를 보고 촬영할 순간을 정합니다. 창을 여는 조작 앞에서는 그 버튼이 보이는 장면을, 방식을 고르는 조작 앞에서는 선택지가 보이는 장면을 남기는 식입니다.
준비하지 않은 API 요청이 나오면 빈 화면을 촬영하지 않고 멈춥니다. 빠진 응답을 채우거나 LLM이 시나리오를 고친 뒤, 그 화면만 다시 촬영합니다. 촬영이 막혀도 사람을 부르기 전에 스스로 고쳐 보는 것입니다.
문장과 장면 맞추기
촬영이 모두 끝나야 원고를 완성합니다. LLM은 카탈로그와 편성표, 촬영한 장면 목록을 받아 단계별 설명을 쓰고, 단계마다 어떤 장면을 붙일지 직접 고릅니다. 고른 장면이 실제로 있는지, 꼭 들어가야 할 장면이 빠지지 않았는지는 정책 문서의 게이트처럼 LLM 없이 검사 코드로 확인합니다.
설명서는 독자가 화면의 어디를 봐야 하는지도 짚어 줘야 합니다. 처음에는 강조할 대상을 LLM이 시나리오에 적어 주기를 기대했습니다. 그런데 LLM은 그 값을 대부분 비워 뒀고, 장면 대부분이 전체 화면 그대로 실렸습니다. 독자는 넓은 화면에서 문장이 안내하는 버튼 하나를 직접 찾아야 했습니다.
답은 시나리오에 이미 있었습니다. 시나리오에는 “무엇을 클릭할지”가 적혀 있습니다. 그래서 다음에 조작할 대상을 초점으로 삼아 강조 표시를 하고, 그 주변을 16:9로 잘라 보여 줍니다.
강조할 초점은 다음 순서로 고릅니다.
- 검토자나 LLM이 지정한 대상
- 다음 조작의 대상
- 그 장면을 만든 조작의 대상
- 장면을 촬영하기 위해 기다리던 요소
이렇게 만들어진 사용설명서는 다음과 같습니다.
같은 일을 두 번 하지 않게
바뀐 화면만 다시 촬영하기
제품이 바뀌면 어떤 화면을 다시 촬영할지 정해야 합니다. 정책 문서처럼 화면마다 그 화면이 의존하는 소스, 촬영 방법과 표시 값, 촬영 규칙, 강조 및 크롭 규칙을 비교합니다.
핵심은 화면의 픽셀을 바꾸는 입력과, 그 위에 얹는 강조만 바꾸는 입력을 나눈 것입니다. 강조 위치만 바뀌었다면 브라우저를 다시 띄워 촬영할 필요가 없습니다. 저장해 둔 원본 위에 강조만 다시 그리면 됩니다.
원고도 마찬가지입니다. 지문이 같으면 그대로 쓰고, 다시 써야 할 때는 이전 원고를 함께 넘겨 바뀐 부분만 고치게 합니다. 제품이 조금 바뀌었다고 설명서 전체의 말투와 구성이 흔들리면, 검토자가 다시 봐야 할 곳이 그만큼 늘어나기 때문입니다.
LLM이 한 번 고친 응답은 다른 화면도 함께 사용하기
한번은 제품이 업데이트되면서 관리자 화면의 공통 헤더가 새 API를 호출하기 시작한 적이 있습니다. 시나리오에는 그 API의 응답이 준비되어 있지 않았으니, 앞에서 본 것처럼 촬영이 중단되었습니다. 그런데 한두 개 화면이 아니라 관리자 화면 수십 개가 같은 이유로 멈췄습니다.
화면마다 LLM이 스스로 고치는 데는 성공했지만, 문제는 모두가 같은 응답을 각자 처음부터 고쳤다는 점입니다. 같은 수정과 재촬영이 화면 수만큼 반복되었고, 그만큼 시간과 비용이 들었습니다.
그래서 한 번의 생성 안에서 LLM이 고친 응답을 함께 공유하도록 했습니다. 처음 고친 응답이 촬영을 통과하면 해당 응답을 후보로 등록해 두고, 같은 API에서 멈추는 화면은 그 후보로 바로 채웁니다. 생성이 끝나면 여러 시나리오가 똑같이 쓴 응답을 공통 응답으로 올려, 다음 생성부터는 문제가 되지 않도록 합니다.
3. 검토하고 공개하기
정책 문서든 사용설명서든, 생성이 끝났다고 바로 공개되지는 않습니다. 검토자가 결과를 보고, 고치고, 승인한 버전만 고객과 도트에게 전달됩니다.
생성을 자동화해도 검토에 시간이 많이 들면 효율은 제자리입니다. 그래서 CCP는 검토자가 봐야 할 곳만 보고, 판단만 하면 되도록 검토 화면을 만들었습니다.
검토 목록: 판단이 필요한 곳만 모으기
생성 파이프라인이 남긴 확인할 점은 문서마다 검토 목록으로 모입니다. 정책이 충돌한 곳, 설명과 장면이 어긋나 보이는 단계처럼 LLM이 초안을 쓰면서 검토자의 판단이 필요하다고 남긴 곳을 한눈에 보여 줍니다.
검토는 실제로 배포될 모습 그대로의 미리보기 위에서 합니다. 지금 공개된 버전과 비교하며 바뀐 곳을 바로 고칠 수 있고, 언제든 LLM이 쓴 초안으로 되돌릴 수 있습니다.
병합: 다시 생성해도 검토자의 수정 지키기
문서를 다시 생성할 때마다 검토자가 고친 문장이 사라진다면, 검토자는 같은 곳을 매번 다시 고쳐야 합니다. 자동 생성이 오히려 일을 늘리는 셈입니다.
1장에서 본 것처럼 CCP는 문서를 필드 단위로 저장합니다. 그래서 검토자가 어느 필드를 고쳤는지 정확히 알고 있고, 다음 생성이 돌아오면 고친 필드마다 아래 세 경우 중 하나로 처리합니다.
- LLM의 새 초안이 예전과 같다면, 검토자가 고친 문장을 그대로 둡니다.
- 새 초안이 달라졌다면 제품이 바뀌었을 수 있으니, 검토자의 문장을 유지하되 새 초안을 함께 보여 줍니다.
- 고친 필드가 새 원고에서 사라졌다면, 조용히 버리지 않고 빠졌다고 알립니다.
어떤 경우에도 검토자의 수정이 모르는 사이에 바뀌거나 사라지지 않습니다.
새 초안을 함께 보여 줄 때는, 검토자가 판단만 하면 되도록 두 문장을 나란히 놓습니다. 달라진 낱말에만 색을 칠하고, ‘내 것 유지’나 ‘AI 제안으로’ 버튼 하나로 고르게 합니다. 내 것을 유지하면 같은 초안으로는 다시 묻지 않습니다.
도우미 에이전트: 원인과 고칠 자리 찾기
검토하다 보면 “이 단계에는 왜 그림이 없지?”, “이 문장은 왜 이렇게 썼지?” 같은 의문이 생깁니다. LLM이 여러 입력을 함께 참고해 결과를 만들기 때문에, 답을 찾으려면 편성표와 시나리오, 촬영 기록을 차례로 열어 봐야 합니다. 검토 시간의 가장 큰 몫은 고치는 일이 아니라 이 원인을 찾는 일이었습니다.
그래서 CCP에는 도우미 에이전트를 두었습니다. 검토자가 보고 있던 문서에서 “3단계에 왜 그림이 없어요?”라고 물으면, 도우미 에이전트가 그 문서의 근거 파일과 생성 기록, 초안과 사전을 읽어 원인을 설명합니다. 그리고 어디를 어떻게 고치면 되는지 제안합니다. 원인을 찾는 일은 도우미 에이전트가, 고칠지 말지는 검토자가 정합니다.
자동 생성: 제품이 배포되면 다시 만들기
검토가 끝나면 승인하고 공개할 수 있습니다. 승인은 그 시점의 원고를 봉인해 하나의 버전으로 만드는 일이고, 공개는 그 버전을 실제로 배포하는 일입니다.
공개는 ‘지금 버전’을 가리키는 포인터를 옮기는 일입니다. 그래서 롤백도 포인터를 예전 버전으로 돌리면 끝납니다. 포인터를 옮기면 사용설명서 사이트와 도트가 검색하는 색인이 함께 같은 버전으로 바뀝니다.
승인과 공개를 나눈 것은 자동 생성과도 맞닿아 있었습니다. 제품이 업데이트되면 문서도 따라 최신이 되도록, CCP는 제품의 운영 배포를 감지하면 스스로 생성을 시작합니다.
자동으로 만든 정책 문서는 승인해 버전으로만 남겨 둡니다. 이어서 사용설명서까지 만든 뒤, 검토가 필요하다고 사내 메신저로 알립니다. 검토자가 사용설명서를 승인하면, 정책 문서도 함께 공개됩니다.
반복되는 일은 최대한 자동화하되, 최종 결정은 사람이 내린다는 원칙을 지킨 것입니다.
4. 도트: 근거를 찾아 답하기
이제 처음의 질문으로 돌아가 보겠습니다. 지금까지는 문서를 만드는 이야기였다면, 여기부터는 그 문서로 답하는 이야기입니다.
도트는 질문을 받으면 먼저 어떤 근거가 필요한지 분류합니다. 사용법을 묻는 질문이면 사용설명서를, 규칙을 묻는 질문이면 정책 문서를 먼저 봅니다. 문서에 없는 지난 논의를 묻는 질문이면 사내 메신저 기록을 찾습니다.
동료는 더 이상 담당자를 찾아갈 필요가 없습니다. 사내 메신저에서 도트를 부르면 됩니다.
사용법과 규칙 질문에 답하기
동료가 사내 메신저에서 도트에게 “웹페이지를 데이터 소스에 어떻게 추가해요?”라고 묻습니다.
도트는 CCP가 만들고 검토자가 승인해 지금 공개된 문서에서 근거를 찾습니다. 앞에서 만든 ‘웹페이지 동기화하기’ 설명서의 단계를 근거로 답하고, 인용한 단계의 화면도 함께 보여 줍니다.
“동기화는 하루에 몇 번 진행되나요?”처럼 한도나 규칙을 묻는 질문에는 사용설명서의 제한 사항과 정책 문서를 근거로 답합니다. 이때 정책 문서의 상태와 품질 점수도 함께 참고합니다. 문서가 공개된 뒤 코드가 바뀌어 근거가 오래됐을 수 있다면, 답에 그렇게 밝힙니다.
문서만으로는 단정할 수 없는 질문도 있습니다. 이때는 문서로 아는 만큼 먼저 답하고, 코드를 직접 확인한 뒤 그 결과를 같은 스레드에 이어서 답합니다. 동료는 코드 확인이 끝날 때까지 기다리지 않아도 됩니다.
사내 메신저 에이전트: 문서에 없는 지난 결정 찾기
세 번째 질문 “웹페이지 동기화가 실패하면 고객사에 어떻게 안내하기로 했었죠?”는 정책 문서나 사용설명서로 답할 수 없습니다. 무엇이 규칙인지가 아니라, 누가 언제 무엇을 정했는지를 묻는 질문이기 때문입니다. 이런 질문은 사내 메신저를 조사하는 에이전트가 맡습니다.
도트는 질문을 받으면 먼저 제목을 붙여 접수하고, 조사하는 동안 진행 상황을 보여 줍니다. 처음에는 동의어와 결론을 나타내는 낱말을 섞어 넓게 검색합니다. 관련 있어 보이는 스레드를 읽다가 새로 드러난 용어로 범위를 좁혀 다시 찾습니다. 부족한 내용은 웹에서 찾기도 하고, 이렇게 모은 근거로 답을 씁니다.
LLM에게 출처까지 쓰게 하면, 있지도 않은 메시지의 링크를 그럴듯하게 만들어 낼 수도 있습니다. 그래서 도트는 조사하면서 실제로 본 메시지를 따로 기록해 두고, 답에 첨부하는 출처는 이 기록에서 만듭니다. 미처 확인하지 못한 내용 역시 함께 적습니다. 아무 말이 없으면 동료는 도트가 모든 채널을 확인했다고 오해하기 쉽기 때문입니다.
권한: 볼 수 없는 것은 답에 쓰지 않기
사내 메신저 에이전트를 만들면서 가장 조심한 건 권한입니다. 도트가 메시지를 읽을 수 있다는 것과, 그 내용을 답에 써도 된다는 것은 다른 문제이기 때문입니다.
도트는 질문한 사람의 권한과 답이 올라갈 채널을 보고, 어떤 메시지를 근거로 쓸지 판단합니다. 예를 들어 공개 채널에서 물었다면, 질문자가 볼 수 있는 비공개 채널의 내용이라도 답에 쓰지 않습니다. 그 답을 다른 사람도 읽기 때문입니다. 답에 쓸 수 없는 메시지는 조용히 빼고, 그런 메시지가 있었다는 사실도 말하지 않습니다.
5. 반복은 LLM에게, 판단은 사람에게
같은 질문 324개로 다시 비교하기
예전의 도트는 CCP 같은 플랫폼과 연결되어 있지 않았고, 사내 메신저를 검색할 수도 없었습니다. 개발자가 AI 코딩 에이전트로 만든 정책 문서를 벡터 DB에 넣어 두고, 최소한의 구현으로 RAG를 하는 정도였습니다.
도트를 지금 구조로 다시 만든 뒤, 예전 도트가 받았던 실제 질문 324개를 새 도트에 그대로 다시 물었습니다. 예전 도트가 답한 질문은 139개, 새 도트가 답한 질문은 208개였습니다. 되묻는 일은 크게 줄었고, 응답은 두 배 넘게 빨라졌습니다.
이 결과는 도트 혼자 만든 것이 아닙니다. 그사이 CCP가 생성한 문서가 연결되고 품질도 좋아진 덕분이기도 합니다. 문서를 만드는 일과 답하는 일이 연결되면서, 질문에 답을 얻는 데 드는 시간이 줄었습니다.
질문 하나에 쓰이던 두 사람의 시간 줄이기
예전에는 문서를 만드는 일이 한 사람의 시간을 통째로 쓰는 번거로운 작업이었습니다. 생성 스크립트를 돌리고, 결과 파일을 받아 고치고, 서버에 직접 올리고 색인했습니다. 제품이 배포되어도 무엇이 바뀌었는지 몰라 답할 근거를 찾지 못하기 일쑤였고, 만들어 둔 문서도 돌릴 때마다 내용이 크게 흔들렸습니다.
이제는 제품이 배포되면 정책 문서와 사용설명서가 자동으로 다시 만들어집니다. 검토자는 검토 목록과 결정 카드를 보며 판단이 필요한 곳만 확인하고 공개합니다. 동료는 사내 메신저에서 도트에게 물어 바로 답을 받습니다.
사람이 하던 일이 사라진 것은 아닙니다. 문서를 쓰고, 화면을 캡처하고, 같은 질문에 반복해서 답하던 시간이 꼭 필요한 판단을 내리는 시간으로 옮겨 갔습니다.
클라썸 팀에게 AX는 단순한 자동화가 아니었습니다.
반복되는 일은 LLM에게 맡기고, 사람은 판단에 집중하게 만드는 일이었습니다.
안녕하세요, 클라썸 Platform Engineering 팀의 Naco입니다.
제품 코드로 정책 문서와 사용설명서를 자동으로 만들고, 그 문서로 동료의 질문에 답하기까지 클라썸 팀이 사내 AX를 하며 겪은 문제와 풀어 간 방법을 공유합니다.
“웹페이지를 데이터 소스에 어떻게 추가해요?”
“동기화는 하루에 몇 번 진행되나요?”
“웹페이지 동기화가 실패하면 고객사에 어떻게 안내하기로 했었죠?”
클라썸 사내 메신저에는 이런 질문이 자주 올라옵니다. 내용을 아는 사람에게는 셋 다 쉬운 질문입니다. 하지만 정확하게 답하려면 생각보다 번거로운 과정을 거쳐야 합니다.
제품이 빠르게 업데이트되다 보니 사용설명서는 이미 배포된 제품과 달라져 있습니다. 메신저에서 논의했던 스레드는 한참 위로 밀려나 있습니다. 애써 찾아낸 정책 문서도 시간이 지나 틀려 있어서, 결국 실제 코드를 열어 봐야 답할 수 있습니다. 그러다 급한 마음에 가장 최근에 작업한 담당자를 찾아가게 됩니다.
질문 하나에 두 사람의 시간이 쓰이는 셈입니다. 묻는 사람은 답을 기다리고, 답하는 사람은 하던 일을 멈춥니다. 같은 질문이 다시 오면 이 과정이 처음부터 반복됩니다.
클라썸 팀이 풀고 싶었던 건 이 반복이었습니다. 문서를 대신 써 주는 AI를 만드는 게 아니라, 확인하고 정리하는 일은 자동화에 맡기고 동료들은 판단이 필요한 일에만 시간을 쓰게 하는 것. 사내 AX를 시작하며 세운 목표였습니다.
그래서 이 문제를 두 개의 시스템으로 나눠 풀었습니다.
- 클라썸 콘텐츠 플랫폼(이하 CCP)은 제품 코드를 바탕으로 정책 문서와 사용설명서를 자동으로 생성하고, 검토자가 그 결과를 검토, 수정, 공개하는 서비스입니다.
- 도트는 사내 메신저의 대화 내역과 CCP가 공개한 문서, 사내 위키, 필요하면 제품 코드까지 찾아 답하는 에이전트입니다.
CCP와 도트를 나눈 이유는 맡은 책임이 다르기 때문입니다. 도트가 질문을 받을 때마다 제품 코드를 처음부터 읽고 정책을 새로 판정할 수는 없습니다. 반대로 CCP가 동료들의 모든 질문을 미리 예상해 답을 만들어 둘 수도 없습니다.
그래서 문서를 만드는 쪽이 출처와 검토 상태, 공개할 버전을 책임지고, 답하는 쪽은 그 정보를 바탕으로 질문에 맞는 근거를 고르게 했습니다.
이 글은 CCP가 정책 문서와 사용설명서를 어떻게 만드는지, 검토자가 그 결과를 어떻게 확인해 공개하는지, 도트가 공개된 문서로 어떻게 답하는지를 차례로 따라간 뒤, 그 결과를 정리합니다.
1. 코드에서 정책 문서 만들기
코드가 문서가 되기까지
도메인: 기능을 나누는 기준
이 여정은 올해 3월의 한 회의에서 시작했습니다. 한 번 쓰고 방치되는 PRD나 그때그때 묻는 AI 에이전트에 기대는 대신, 언제나 최신 기능과 정책을 담고 있는 프로덕션 코드에서 답을 만들어 두자는 이야기였습니다. LLM이 코드를 읽고 자연어로 문서를 써 두면, 배포된 제품의 정책과 사용 방법을 바로 파악할 수 있다는 아이디어입니다.
끝없이 바뀌는 코드에서 일정한 품질의 문서를 안정적으로 만들려면 먼저 답해야 할 질문이 있었습니다. “제품을 어떻게 정적으로 나눌 수 있을까?”
출발점은 백엔드는 컨트롤러, 프런트엔드는 라우터를 기준으로 영역을 나누는 것이었습니다. 컨트롤러는 어떤 요청을 받는지, 라우터는 사용자가 어떤 경로로 들어오는지 알려 주는 입구입니다. 이 입구에서 서비스, 엔티티, 컴포넌트를 따라가며 한 기능을 이루는 코드의 범위를 좁혔습니다.
LLM에게 저장소 전체를 주고 매번 새로 분류하게 하는 대신, 코드에서 반복해서 찾을 수 있는 기준을 먼저 세웠습니다. 같은 코드에서는 항상 같은 묶음이 나와야, 바뀐 코드가 어느 문서에 영향을 주는지 자동으로 판단할 수 있기 때문입니다.
이렇게 묶은 단위를 도메인이라고 불렀습니다. 백엔드 코드는 누가 어떤 상태에서 요청할 수 있는지를 정하고, 프런트엔드 코드는 그 기능이 어디에 어떤 모습으로 드러나는지를 정합니다. 도메인은 이 두 쪽의 근거를 하나의 정책 아래 모으는 그릇입니다.
도메인은 세 층으로 설계했습니다.
- Domain Map: 한 도메인의 정책을 쓸 때 실제로 읽을 파일 목록
- Domain Tree: 도메인 사이의 관계를 나타내는 트리 구조
- Domain Dictionary: 코드의 이름과 서비스에서 보이는 이름의 연결
CCP에서는 검토자가 도메인을 더 쉽게 다룰 수 있도록 세 층을 역할에 맞게 나눴습니다.
Tree는 무엇을 어떤 순서로 문서화할지 정하는 편성표가 됐습니다. Dictionary는 코드의 도메인을 어느 문서가 맡는지 잇는 연결표와, 코드의 변수명을 서비스의 표현으로 바꾸는 용어 사전으로 나뉘었습니다.
- 편성표: 어떤 문서를 쓰고 뺄지, 어느 구획에 어떤 순서로 둘지 정의합니다.
- 연결표: 코드의 도메인을 어느 문서가 맡는지 잇습니다.
- 용어 사전: 코드의 변수명을 서비스의 표현으로 바꿉니다
증거 묶음: 코드에서 팩트 추출하기
이제 커넥트의 ‘데이터 소스 관리’ 정책 문서 한 편이 만들어지는 과정을 따라가 보겠습니다. 웹페이지와 유튜브 동기화, 파일 업로드처럼 데이터 소스에 관한 규칙을 모은 문서입니다.
정책 문서에서 가장 틀리기 쉬운 문장은 “최대 몇 개”, “며칠 이내” 같은 한도입니다. LLM에게 코드를 읽고 바로 쓰게 하면, 그 숫자가 정말 코드에서 온 것인지 확인할 방법이 없습니다.
그래서 첫 단계에는 LLM이 관여하지 않습니다. 스캐너가 Domain Map에 적힌 이 문서의 백엔드와 프런트엔드 코드를 읽고, 문서를 쓸 때 참고할 사실을 하나의 증거 묶음으로 만듭니다.
증거 묶음에는 API와 인증 방식, 저장 필드의 타입과 길이, 오류 코드, 알림, 그리고 코드에 적힌 상수가 들어갑니다.
상수는 100 * 1000 * 1000처럼 적힌 값도 미리 계산해 두고, 곱해진 수 하나하나도 후보로 남깁니다. 나중에 원고를 검사할 때 “100MB”의 100이 정말 코드에서 온 숫자인지 확인하기 위해서입니다.
초안 작성: LLM이 필드 채우기
다음으로 LLM이 증거 묶음과 원본 소스 코드를 함께 읽고 초안을 씁니다. 문서의 제목과 다룰 범위, 용어 사전, UX 라이팅 규칙도 함께 프롬프트로 받습니다.
그런데 LLM이 쓴 문장은 어떻게 검사할 수 있을까요? 줄글로 받으면 어느 문장이 어느 코드에서 왔는지, 숫자가 맞는지를 결국 사람이 처음부터 다시 읽어야 합니다.
그래서 초안을 읽기 좋은 문서가 아니라, 한 줄 요약과 주장(claim) 목록이 담긴 커다란 JSON으로 받습니다. 규칙, 한도, 오류 코드, 접근 권한 같은 정책 하나하나가 각각 하나의 주장이 되고, 주장마다 근거가 되는 코드 위치가 붙습니다. LLM이 근거 코드를 찾지 못한 내용은 지어내지 않고 ‘확인하지 못한 것’으로 따로 남깁니다.
이 JSON의 형식, 즉 스키마는 CCP가 미리 정해 둡니다. 한 줄 요약, 주장 목록, 확인하지 못한 것처럼 들어갈 필드가 정해져 있고, LLM은 그 필드를 채울 뿐입니다. 스키마를 정해 두면 좋은 점이 세 가지 있습니다.
- 검사할 수 있습니다. 주장마다 근거 코드가 붙어 있으니, 문장 하나하나를 코드와 대조할 수 있습니다.
- 검토자의 수정이 지켜집니다. 필드마다 따로 저장하므로, 검토자가 어느 필드를 고쳤는지 정확히 알 수 있습니다. 그래서 문서를 다시 생성해도 그 수정을 덮어쓰지 않습니다.
- 어느 문서든 같은 순서로 읽힙니다.
게이트 5종: 통과하지 못한 곳만 LLM이 다시 쓰기
초안은 완성되기 전에 다섯 가지 자동 검사를 통과해야 합니다. 이 검사들을 게이트라고 부릅니다.
- 근거 파일이 이 문서가 맡은 도메인 안에 있는가
- 한도의 숫자가 코드에서 뽑은 상수와 일치하는가
- 용어 사전에 따라 코드 변수명이 서비스 용어로 바뀌었는가
- UX 라이팅 규칙을 지켰는가
- 편성표가 반드시 다루라고 한 사실이 문서에 담겼는가
게이트는 LLM을 쓰지 않는 검사 코드입니다. 같은 원고를 넣으면 언제나 같은 결과가 나옵니다. 근거가 존재하고 그럴듯해 보여도, 원고가 증거 묶음과 어긋나면 통과하지 못합니다. 사람이 일일이 대조하던 일을 매번 같은 기준으로 자동화한 셈입니다.
게이트를 통과하지 못하면 문서를 다시 쓰게 합니다. 처음에는 매번 처음부터 새로 쓰게 하고, 위반이 가장 적은 시도를 골랐습니다. 그런데 다시 쓸수록 문서에서 사실이 줄어들었습니다. 게이트는 주장을 검사하니, 주장을 지울수록 위반도 줄어들었기 때문입니다.
위반이 적은 문서가 좋은 문서는 아니었습니다.
그래서 직전 시도의 산출물과 위반 내용을 함께 넘기고, 통과하지 못한 곳만 고치게 했습니다. 여러 시도 가운데 하나를 고를 때도 위반 수만 보지 않고, 사실을 얼마나 지켜 냈는지를 함께 봅니다.
세 번까지 시도해도 위반 사항이 남으면, 문서를 버리지 않고 일단 다음 단계로 넘깁니다. 대신 남은 위반을 검토자에게 보여 주고, 실제로 코드에 문제가 있는 건 아닌지 확인하게 합니다.
채점: 신뢰 상태와 품질 점수 남기기
CCP는 문서마다 상태를 남깁니다. 정책이 부족한 곳이 있는지, 근거를 확인하지 못한 주장이 있는지를 문서에 그대로 적어 둡니다.
게이트를 통과한 초안은 한 번 더 평가를 받습니다. 초안을 작성한 모델과는 다른 LLM 모델을 이용해 정확성, 빠진 내용, 용어, 흐름, 독자에게 맞는지를 기준으로 점수를 매깁니다.
이 상태와 점수는 문서와 함께 공개됩니다. 나중에 도트가 이 문서를 근거로 답할 때도, 이 정보를 보고 답을 얼마나 확신할지 정합니다.
틀리지 않게, 비싸지 않게
충돌하는 정책과 운영에만 있는 정책 다루기
서로 다른 저장소의 코드가 서로 다른 정책을 말하기도 합니다. 프런트엔드에서만 입력을 막고 API는 막지 않는다거나, 백오피스의 안내 문구가 실제 동작과 다른 경우입니다.
정책 문서를 생성하다 보면 이런 차이가 분명하게 드러납니다. 이때 LLM이 둘 중 그럴듯한 쪽을 골라 버리면, 팀은 그 차이를 알아챌 기회를 잃습니다. 그래서 CCP는 어느 층에서 어떤 차이가 있는지 문장으로 남기고 검토자에게 알립니다. 이 충돌은 검토자가 한쪽을 고를 때까지 문서에서 지워지지 않습니다.
반대로 코드에는 없는 정책도 있습니다. 운영상 꼭 문서에 담아야 하는 사실은 편성표에 ‘반드시 다룰 사실’로 넣습니다. 이 사실은 문서에서도 운영에서 정한 사실로 구분해 표시합니다. 코드가 그렇게 동작하는 것과 팀이 그렇게 정한 것을 독자가 구분할 수 있게 하기 위해서입니다.
지문: 코드가 바뀐 문서만 다시 쓰기
제품 코드는 매주 바뀝니다. 그렇다고 그때마다 모든 문서를 다시 쓰면 시간과 비용이 감당되지 않습니다.
그래서 문서마다 읽은 증거 묶음과 편성표, 용어 사전, 모델 설정을 묶어 고유한 지문을 만듭니다. 지문이 같으면 다시 생성하지 않고 이전 문서를 그대로 사용합니다. 다시 써야 할 때는 무엇이 바뀌어서 다시 쓰는지도 함께 기록해, 그 비용이 꼭 필요했는지 확인할 수 있게 했습니다.
스캐너가 어느 문서에도 속하지 않는 새 코드 영역을 찾으면, 새 문서로 만들지 기존 문서에 붙일지를 검토자에게 묻습니다. 정해지기 전까지 그 영역은 제안으로만 남습니다.
2. 실제 화면으로 사용설명서 만들기
화면이 설명서가 되기까지
소스 코드를 읽고, 설명할 범위를 정하고, 초안을 만들고, 검토자가 고친 내용을 반영한다는 점에서 사용설명서도 정책 문서와 같은 플랫폼 위에서 만들 수 있었습니다.
다만 고객이 직접 읽는 사용설명서에는 더 다듬어진 문장과 실제 제품 화면이 필요합니다. 캡처하고, 자르고, 문서에 붙였고, 제품이 바뀔 때마다 이 일을 다시 해야 했습니다. CCP는 이 과정까지 자동화했고, 그래서 몇 가지 단계가 더 들어갑니다.
첫 번째 질문이었던 ‘웹페이지 동기화하기’를 예로 들어 보겠습니다.
- 데이터 소스 목록에서 ‘업로드’를 클릭합니다.
- 업로드 방식 가운데 ‘개별 웹페이지 동기화’를 선택합니다.
- 웹페이지 이름과 URL을 입력하고 ‘동기화’를 클릭합니다.
세 번의 조작은 모두 다른 화면에서 일어납니다. 독자가 헷갈리지 않으려면, 각 단계의 설명 옆에 바로 그 순간의 화면이 붙어 있어야 합니다. 문장과 그림이 같은 순간을 가리키게 하려면, 글을 쓰기 전에 사용자가 할 일과 촬영할 장면부터 정해야 했습니다.
카탈로그: 제품 화면 분석하기
LLM에게 코드만 주고 사용설명서를 쓰게 하면, 화면을 보지 못하기 때문에 버튼 이름이나 클릭하는 순서처럼 화면을 봐야 알 수 있는 내용이 틀리기 쉽습니다.
그래서 사용설명서도 소스 코드 스캔에서 시작합니다. 스캐너는 라우트와 페이지 컴포넌트뿐 아니라 다음 내용까지 읽어 카탈로그를 만듭니다.
- 화면에 보이는 문구
- 버튼과 입력 같은 조작이 무엇을 하는지
- 그 화면에서 호출하는 API
- 코드에 적힌 한도
예시의 경우 ‘업로드’ 버튼을 클릭하면 창이 열리고, ‘개별 웹페이지 동기화’ 카드로 방식을 고른다는 사실이 카탈로그에 적힙니다. 이 카드가 ‘업로드’를 클릭해야 나타난다는 관계까지 함께 적힙니다. ‘동기화’ 버튼은 올바른 URL이 있어야 켜진다는 조건과 한 번에 100행까지 입력할 수 있다는 한도도 코드에서 뽑아 카탈로그에 담습니다.
원고의 문장은 LLM이 화면을 상상해서 쓴 것이 아니라, 이 카탈로그의 항목을 하나하나 문장으로 옮긴 것입니다.
카탈로그에서 설명서 후보가 나오면, 정책 문서와 마찬가지로 편성표가 무엇을 쓸지 정합니다. 어떤 설명서를 쓰고 뺄지, 어느 구획에 둘지, 반드시 다룰 내용이 무엇인지가 여기서 정해집니다.
시나리오: 촬영 방법 정하기
무엇을 쓸지 정해지면, 그 내용을 보여 줄 장면을 정합니다. 화면마다 촬영 시나리오가 있습니다. 어느 주소에서 시작해 무엇을 클릭하고 무엇이 보일 때까지 기다릴지, 그 화면이 부르는 API에 어떤 응답을 줄지를 적은 파일입니다.
처음 문서화하는 기능이나 새로 생긴 화면에는 아직 시나리오가 없습니다. 이런 화면은 LLM이 시나리오를 새로 쓰게 되는데, 코드만 읽어서는 어떤 API가 언제 불리는지 다 알 수 없습니다. 그래서 시나리오를 쓰기 전에 먼저 Playwright로 화면을 실제로 열어 보고, 어떤 API가 호출되고 화면에 무엇이 보이는지를 기록해 LLM에게 넘깁니다.
화면에 들어갈 데이터도 목적에 맞게 준비합니다. 예를 들어 데이터 소스 목록 화면은 파일, Q&A, 웹페이지, 유튜브처럼 다양한 종류의 항목이 있어야 그 역할이 한눈에 읽힙니다. 연결이 끝난 항목과 진행 중인 항목이 섞여 있어야 여러 상태 표시도 한 장면에 드러납니다. 응답의 모양은 제품 SDK의 응답 스키마로 맞추고, 그 안에 들어갈 값은 LLM이 화면에 맞게 채웁니다.
조작 단위로 장면 촬영하기
모든 화면은 실제 프런트엔드 코드를 실행해 촬영합니다. 시각과 언어, 테마를 고정하고, 촬영 직전에는 설명하려던 요소가 실제로 보이는지 확인합니다.
시나리오에 장면을 일일이 적지는 않습니다. 생성 파이프라인이 조작의 종류를 보고 촬영할 순간을 정합니다. 창을 여는 조작 앞에서는 그 버튼이 보이는 장면을, 방식을 고르는 조작 앞에서는 선택지가 보이는 장면을 남기는 식입니다.
준비하지 않은 API 요청이 나오면 빈 화면을 촬영하지 않고 멈춥니다. 빠진 응답을 채우거나 LLM이 시나리오를 고친 뒤, 그 화면만 다시 촬영합니다. 촬영이 막혀도 사람을 부르기 전에 스스로 고쳐 보는 것입니다.
문장과 장면 맞추기
촬영이 모두 끝나야 원고를 완성합니다. LLM은 카탈로그와 편성표, 촬영한 장면 목록을 받아 단계별 설명을 쓰고, 단계마다 어떤 장면을 붙일지 직접 고릅니다. 고른 장면이 실제로 있는지, 꼭 들어가야 할 장면이 빠지지 않았는지는 정책 문서의 게이트처럼 LLM 없이 검사 코드로 확인합니다.
설명서는 독자가 화면의 어디를 봐야 하는지도 짚어 줘야 합니다. 처음에는 강조할 대상을 LLM이 시나리오에 적어 주기를 기대했습니다. 그런데 LLM은 그 값을 대부분 비워 뒀고, 장면 대부분이 전체 화면 그대로 실렸습니다. 독자는 넓은 화면에서 문장이 안내하는 버튼 하나를 직접 찾아야 했습니다.
답은 시나리오에 이미 있었습니다. 시나리오에는 “무엇을 클릭할지”가 적혀 있습니다. 그래서 다음에 조작할 대상을 초점으로 삼아 강조 표시를 하고, 그 주변을 16:9로 잘라 보여 줍니다.
강조할 초점은 다음 순서로 고릅니다.
- 검토자나 LLM이 지정한 대상
- 다음 조작의 대상
- 그 장면을 만든 조작의 대상
- 장면을 촬영하기 위해 기다리던 요소
이렇게 만들어진 사용설명서는 다음과 같습니다.
같은 일을 두 번 하지 않게
바뀐 화면만 다시 촬영하기
제품이 바뀌면 어떤 화면을 다시 촬영할지 정해야 합니다. 정책 문서처럼 화면마다 그 화면이 의존하는 소스, 촬영 방법과 표시 값, 촬영 규칙, 강조 및 크롭 규칙을 비교합니다.
핵심은 화면의 픽셀을 바꾸는 입력과, 그 위에 얹는 강조만 바꾸는 입력을 나눈 것입니다. 강조 위치만 바뀌었다면 브라우저를 다시 띄워 촬영할 필요가 없습니다. 저장해 둔 원본 위에 강조만 다시 그리면 됩니다.
원고도 마찬가지입니다. 지문이 같으면 그대로 쓰고, 다시 써야 할 때는 이전 원고를 함께 넘겨 바뀐 부분만 고치게 합니다. 제품이 조금 바뀌었다고 설명서 전체의 말투와 구성이 흔들리면, 검토자가 다시 봐야 할 곳이 그만큼 늘어나기 때문입니다.
LLM이 한 번 고친 응답은 다른 화면도 함께 사용하기
한번은 제품이 업데이트되면서 관리자 화면의 공통 헤더가 새 API를 호출하기 시작한 적이 있습니다. 시나리오에는 그 API의 응답이 준비되어 있지 않았으니, 앞에서 본 것처럼 촬영이 중단되었습니다. 그런데 한두 개 화면이 아니라 관리자 화면 수십 개가 같은 이유로 멈췄습니다.
화면마다 LLM이 스스로 고치는 데는 성공했지만, 문제는 모두가 같은 응답을 각자 처음부터 고쳤다는 점입니다. 같은 수정과 재촬영이 화면 수만큼 반복되었고, 그만큼 시간과 비용이 들었습니다.
그래서 한 번의 생성 안에서 LLM이 고친 응답을 함께 공유하도록 했습니다. 처음 고친 응답이 촬영을 통과하면 해당 응답을 후보로 등록해 두고, 같은 API에서 멈추는 화면은 그 후보로 바로 채웁니다. 생성이 끝나면 여러 시나리오가 똑같이 쓴 응답을 공통 응답으로 올려, 다음 생성부터는 문제가 되지 않도록 합니다.
3. 검토하고 공개하기
정책 문서든 사용설명서든, 생성이 끝났다고 바로 공개되지는 않습니다. 검토자가 결과를 보고, 고치고, 승인한 버전만 고객과 도트에게 전달됩니다.
생성을 자동화해도 검토에 시간이 많이 들면 효율은 제자리입니다. 그래서 CCP는 검토자가 봐야 할 곳만 보고, 판단만 하면 되도록 검토 화면을 만들었습니다.
검토 목록: 판단이 필요한 곳만 모으기
생성 파이프라인이 남긴 확인할 점은 문서마다 검토 목록으로 모입니다. 정책이 충돌한 곳, 설명과 장면이 어긋나 보이는 단계처럼 LLM이 초안을 쓰면서 검토자의 판단이 필요하다고 남긴 곳을 한눈에 보여 줍니다.
검토는 실제로 배포될 모습 그대로의 미리보기 위에서 합니다. 지금 공개된 버전과 비교하며 바뀐 곳을 바로 고칠 수 있고, 언제든 LLM이 쓴 초안으로 되돌릴 수 있습니다.
병합: 다시 생성해도 검토자의 수정 지키기
문서를 다시 생성할 때마다 검토자가 고친 문장이 사라진다면, 검토자는 같은 곳을 매번 다시 고쳐야 합니다. 자동 생성이 오히려 일을 늘리는 셈입니다.
1장에서 본 것처럼 CCP는 문서를 필드 단위로 저장합니다. 그래서 검토자가 어느 필드를 고쳤는지 정확히 알고 있고, 다음 생성이 돌아오면 고친 필드마다 아래 세 경우 중 하나로 처리합니다.
- LLM의 새 초안이 예전과 같다면, 검토자가 고친 문장을 그대로 둡니다.
- 새 초안이 달라졌다면 제품이 바뀌었을 수 있으니, 검토자의 문장을 유지하되 새 초안을 함께 보여 줍니다.
- 고친 필드가 새 원고에서 사라졌다면, 조용히 버리지 않고 빠졌다고 알립니다.
어떤 경우에도 검토자의 수정이 모르는 사이에 바뀌거나 사라지지 않습니다.
새 초안을 함께 보여 줄 때는, 검토자가 판단만 하면 되도록 두 문장을 나란히 놓습니다. 달라진 낱말에만 색을 칠하고, ‘내 것 유지’나 ‘AI 제안으로’ 버튼 하나로 고르게 합니다. 내 것을 유지하면 같은 초안으로는 다시 묻지 않습니다.
도우미 에이전트: 원인과 고칠 자리 찾기
검토하다 보면 “이 단계에는 왜 그림이 없지?”, “이 문장은 왜 이렇게 썼지?” 같은 의문이 생깁니다. LLM이 여러 입력을 함께 참고해 결과를 만들기 때문에, 답을 찾으려면 편성표와 시나리오, 촬영 기록을 차례로 열어 봐야 합니다. 검토 시간의 가장 큰 몫은 고치는 일이 아니라 이 원인을 찾는 일이었습니다.
그래서 CCP에는 도우미 에이전트를 두었습니다. 검토자가 보고 있던 문서에서 “3단계에 왜 그림이 없어요?”라고 물으면, 도우미 에이전트가 그 문서의 근거 파일과 생성 기록, 초안과 사전을 읽어 원인을 설명합니다. 그리고 어디를 어떻게 고치면 되는지 제안합니다. 원인을 찾는 일은 도우미 에이전트가, 고칠지 말지는 검토자가 정합니다.
자동 생성: 제품이 배포되면 다시 만들기
검토가 끝나면 승인하고 공개할 수 있습니다. 승인은 그 시점의 원고를 봉인해 하나의 버전으로 만드는 일이고, 공개는 그 버전을 실제로 배포하는 일입니다.
공개는 ‘지금 버전’을 가리키는 포인터를 옮기는 일입니다. 그래서 롤백도 포인터를 예전 버전으로 돌리면 끝납니다. 포인터를 옮기면 사용설명서 사이트와 도트가 검색하는 색인이 함께 같은 버전으로 바뀝니다.
승인과 공개를 나눈 것은 자동 생성과도 맞닿아 있었습니다. 제품이 업데이트되면 문서도 따라 최신이 되도록, CCP는 제품의 운영 배포를 감지하면 스스로 생성을 시작합니다.
자동으로 만든 정책 문서는 승인해 버전으로만 남겨 둡니다. 이어서 사용설명서까지 만든 뒤, 검토가 필요하다고 사내 메신저로 알립니다. 검토자가 사용설명서를 승인하면, 정책 문서도 함께 공개됩니다.
반복되는 일은 최대한 자동화하되, 최종 결정은 사람이 내린다는 원칙을 지킨 것입니다.
4. 도트: 근거를 찾아 답하기
이제 처음의 질문으로 돌아가 보겠습니다. 지금까지는 문서를 만드는 이야기였다면, 여기부터는 그 문서로 답하는 이야기입니다.
도트는 질문을 받으면 먼저 어떤 근거가 필요한지 분류합니다. 사용법을 묻는 질문이면 사용설명서를, 규칙을 묻는 질문이면 정책 문서를 먼저 봅니다. 문서에 없는 지난 논의를 묻는 질문이면 사내 메신저 기록을 찾습니다.
동료는 더 이상 담당자를 찾아갈 필요가 없습니다. 사내 메신저에서 도트를 부르면 됩니다.
사용법과 규칙 질문에 답하기
동료가 사내 메신저에서 도트에게 “웹페이지를 데이터 소스에 어떻게 추가해요?”라고 묻습니다.
도트는 CCP가 만들고 검토자가 승인해 지금 공개된 문서에서 근거를 찾습니다. 앞에서 만든 ‘웹페이지 동기화하기’ 설명서의 단계를 근거로 답하고, 인용한 단계의 화면도 함께 보여 줍니다.
“동기화는 하루에 몇 번 진행되나요?”처럼 한도나 규칙을 묻는 질문에는 사용설명서의 제한 사항과 정책 문서를 근거로 답합니다. 이때 정책 문서의 상태와 품질 점수도 함께 참고합니다. 문서가 공개된 뒤 코드가 바뀌어 근거가 오래됐을 수 있다면, 답에 그렇게 밝힙니다.
문서만으로는 단정할 수 없는 질문도 있습니다. 이때는 문서로 아는 만큼 먼저 답하고, 코드를 직접 확인한 뒤 그 결과를 같은 스레드에 이어서 답합니다. 동료는 코드 확인이 끝날 때까지 기다리지 않아도 됩니다.
사내 메신저 에이전트: 문서에 없는 지난 결정 찾기
세 번째 질문 “웹페이지 동기화가 실패하면 고객사에 어떻게 안내하기로 했었죠?”는 정책 문서나 사용설명서로 답할 수 없습니다. 무엇이 규칙인지가 아니라, 누가 언제 무엇을 정했는지를 묻는 질문이기 때문입니다. 이런 질문은 사내 메신저를 조사하는 에이전트가 맡습니다.
도트는 질문을 받으면 먼저 제목을 붙여 접수하고, 조사하는 동안 진행 상황을 보여 줍니다. 처음에는 동의어와 결론을 나타내는 낱말을 섞어 넓게 검색합니다. 관련 있어 보이는 스레드를 읽다가 새로 드러난 용어로 범위를 좁혀 다시 찾습니다. 부족한 내용은 웹에서 찾기도 하고, 이렇게 모은 근거로 답을 씁니다.
LLM에게 출처까지 쓰게 하면, 있지도 않은 메시지의 링크를 그럴듯하게 만들어 낼 수도 있습니다. 그래서 도트는 조사하면서 실제로 본 메시지를 따로 기록해 두고, 답에 첨부하는 출처는 이 기록에서 만듭니다. 미처 확인하지 못한 내용 역시 함께 적습니다. 아무 말이 없으면 동료는 도트가 모든 채널을 확인했다고 오해하기 쉽기 때문입니다.
권한: 볼 수 없는 것은 답에 쓰지 않기
사내 메신저 에이전트를 만들면서 가장 조심한 건 권한입니다. 도트가 메시지를 읽을 수 있다는 것과, 그 내용을 답에 써도 된다는 것은 다른 문제이기 때문입니다.
도트는 질문한 사람의 권한과 답이 올라갈 채널을 보고, 어떤 메시지를 근거로 쓸지 판단합니다. 예를 들어 공개 채널에서 물었다면, 질문자가 볼 수 있는 비공개 채널의 내용이라도 답에 쓰지 않습니다. 그 답을 다른 사람도 읽기 때문입니다. 답에 쓸 수 없는 메시지는 조용히 빼고, 그런 메시지가 있었다는 사실도 말하지 않습니다.
5. 반복은 LLM에게, 판단은 사람에게
같은 질문 324개로 다시 비교하기
예전의 도트는 CCP 같은 플랫폼과 연결되어 있지 않았고, 사내 메신저를 검색할 수도 없었습니다. 개발자가 AI 코딩 에이전트로 만든 정책 문서를 벡터 DB에 넣어 두고, 최소한의 구현으로 RAG를 하는 정도였습니다.
도트를 지금 구조로 다시 만든 뒤, 예전 도트가 받았던 실제 질문 324개를 새 도트에 그대로 다시 물었습니다. 예전 도트가 답한 질문은 139개, 새 도트가 답한 질문은 208개였습니다. 되묻는 일은 크게 줄었고, 응답은 두 배 넘게 빨라졌습니다.
이 결과는 도트 혼자 만든 것이 아닙니다. 그사이 CCP가 생성한 문서가 연결되고 품질도 좋아진 덕분이기도 합니다. 문서를 만드는 일과 답하는 일이 연결되면서, 질문에 답을 얻는 데 드는 시간이 줄었습니다.
질문 하나에 쓰이던 두 사람의 시간 줄이기
예전에는 문서를 만드는 일이 한 사람의 시간을 통째로 쓰는 번거로운 작업이었습니다. 생성 스크립트를 돌리고, 결과 파일을 받아 고치고, 서버에 직접 올리고 색인했습니다. 제품이 배포되어도 무엇이 바뀌었는지 몰라 답할 근거를 찾지 못하기 일쑤였고, 만들어 둔 문서도 돌릴 때마다 내용이 크게 흔들렸습니다.
이제는 제품이 배포되면 정책 문서와 사용설명서가 자동으로 다시 만들어집니다. 검토자는 검토 목록과 결정 카드를 보며 판단이 필요한 곳만 확인하고 공개합니다. 동료는 사내 메신저에서 도트에게 물어 바로 답을 받습니다.
사람이 하던 일이 사라진 것은 아닙니다. 문서를 쓰고, 화면을 캡처하고, 같은 질문에 반복해서 답하던 시간이 꼭 필요한 판단을 내리는 시간으로 옮겨 갔습니다.
클라썸 팀에게 AX는 단순한 자동화가 아니었습니다.
반복되는 일은 LLM에게 맡기고, 사람은 판단에 집중하게 만드는 일이었습니다.
안녕하세요, 클라썸 Platform Engineering 팀의 Naco입니다.
제품 코드로 정책 문서와 사용설명서를 자동으로 만들고, 그 문서로 동료의 질문에 답하기까지 클라썸 팀이 사내 AX를 하며 겪은 문제와 풀어 간 방법을 공유합니다.
“웹페이지를 데이터 소스에 어떻게 추가해요?”
“동기화는 하루에 몇 번 진행되나요?”
“웹페이지 동기화가 실패하면 고객사에 어떻게 안내하기로 했었죠?”
클라썸 사내 메신저에는 이런 질문이 자주 올라옵니다. 내용을 아는 사람에게는 셋 다 쉬운 질문입니다. 하지만 정확하게 답하려면 생각보다 번거로운 과정을 거쳐야 합니다.
제품이 빠르게 업데이트되다 보니 사용설명서는 이미 배포된 제품과 달라져 있습니다. 메신저에서 논의했던 스레드는 한참 위로 밀려나 있습니다. 애써 찾아낸 정책 문서도 시간이 지나 틀려 있어서, 결국 실제 코드를 열어 봐야 답할 수 있습니다. 그러다 급한 마음에 가장 최근에 작업한 담당자를 찾아가게 됩니다.
질문 하나에 두 사람의 시간이 쓰이는 셈입니다. 묻는 사람은 답을 기다리고, 답하는 사람은 하던 일을 멈춥니다. 같은 질문이 다시 오면 이 과정이 처음부터 반복됩니다.
클라썸 팀이 풀고 싶었던 건 이 반복이었습니다. 문서를 대신 써 주는 AI를 만드는 게 아니라, 확인하고 정리하는 일은 자동화에 맡기고 동료들은 판단이 필요한 일에만 시간을 쓰게 하는 것. 사내 AX를 시작하며 세운 목표였습니다.
그래서 이 문제를 두 개의 시스템으로 나눠 풀었습니다.
- 클라썸 콘텐츠 플랫폼(이하 CCP)은 제품 코드를 바탕으로 정책 문서와 사용설명서를 자동으로 생성하고, 검토자가 그 결과를 검토, 수정, 공개하는 서비스입니다.
- 도트는 사내 메신저의 대화 내역과 CCP가 공개한 문서, 사내 위키, 필요하면 제품 코드까지 찾아 답하는 에이전트입니다.
CCP와 도트를 나눈 이유는 맡은 책임이 다르기 때문입니다. 도트가 질문을 받을 때마다 제품 코드를 처음부터 읽고 정책을 새로 판정할 수는 없습니다. 반대로 CCP가 동료들의 모든 질문을 미리 예상해 답을 만들어 둘 수도 없습니다.
그래서 문서를 만드는 쪽이 출처와 검토 상태, 공개할 버전을 책임지고, 답하는 쪽은 그 정보를 바탕으로 질문에 맞는 근거를 고르게 했습니다.
이 글은 CCP가 정책 문서와 사용설명서를 어떻게 만드는지, 검토자가 그 결과를 어떻게 확인해 공개하는지, 도트가 공개된 문서로 어떻게 답하는지를 차례로 따라간 뒤, 그 결과를 정리합니다.
1. 코드에서 정책 문서 만들기
코드가 문서가 되기까지
도메인: 기능을 나누는 기준
이 여정은 올해 3월의 한 회의에서 시작했습니다. 한 번 쓰고 방치되는 PRD나 그때그때 묻는 AI 에이전트에 기대는 대신, 언제나 최신 기능과 정책을 담고 있는 프로덕션 코드에서 답을 만들어 두자는 이야기였습니다. LLM이 코드를 읽고 자연어로 문서를 써 두면, 배포된 제품의 정책과 사용 방법을 바로 파악할 수 있다는 아이디어입니다.
끝없이 바뀌는 코드에서 일정한 품질의 문서를 안정적으로 만들려면 먼저 답해야 할 질문이 있었습니다. “제품을 어떻게 정적으로 나눌 수 있을까?”
출발점은 백엔드는 컨트롤러, 프런트엔드는 라우터를 기준으로 영역을 나누는 것이었습니다. 컨트롤러는 어떤 요청을 받는지, 라우터는 사용자가 어떤 경로로 들어오는지 알려 주는 입구입니다. 이 입구에서 서비스, 엔티티, 컴포넌트를 따라가며 한 기능을 이루는 코드의 범위를 좁혔습니다.
LLM에게 저장소 전체를 주고 매번 새로 분류하게 하는 대신, 코드에서 반복해서 찾을 수 있는 기준을 먼저 세웠습니다. 같은 코드에서는 항상 같은 묶음이 나와야, 바뀐 코드가 어느 문서에 영향을 주는지 자동으로 판단할 수 있기 때문입니다.
이렇게 묶은 단위를 도메인이라고 불렀습니다. 백엔드 코드는 누가 어떤 상태에서 요청할 수 있는지를 정하고, 프런트엔드 코드는 그 기능이 어디에 어떤 모습으로 드러나는지를 정합니다. 도메인은 이 두 쪽의 근거를 하나의 정책 아래 모으는 그릇입니다.
도메인은 세 층으로 설계했습니다.
- Domain Map: 한 도메인의 정책을 쓸 때 실제로 읽을 파일 목록
- Domain Tree: 도메인 사이의 관계를 나타내는 트리 구조
- Domain Dictionary: 코드의 이름과 서비스에서 보이는 이름의 연결
CCP에서는 검토자가 도메인을 더 쉽게 다룰 수 있도록 세 층을 역할에 맞게 나눴습니다.
Tree는 무엇을 어떤 순서로 문서화할지 정하는 편성표가 됐습니다. Dictionary는 코드의 도메인을 어느 문서가 맡는지 잇는 연결표와, 코드의 변수명을 서비스의 표현으로 바꾸는 용어 사전으로 나뉘었습니다.
- 편성표: 어떤 문서를 쓰고 뺄지, 어느 구획에 어떤 순서로 둘지 정의합니다.
- 연결표: 코드의 도메인을 어느 문서가 맡는지 잇습니다.
- 용어 사전: 코드의 변수명을 서비스의 표현으로 바꿉니다
증거 묶음: 코드에서 팩트 추출하기
이제 커넥트의 ‘데이터 소스 관리’ 정책 문서 한 편이 만들어지는 과정을 따라가 보겠습니다. 웹페이지와 유튜브 동기화, 파일 업로드처럼 데이터 소스에 관한 규칙을 모은 문서입니다.
정책 문서에서 가장 틀리기 쉬운 문장은 “최대 몇 개”, “며칠 이내” 같은 한도입니다. LLM에게 코드를 읽고 바로 쓰게 하면, 그 숫자가 정말 코드에서 온 것인지 확인할 방법이 없습니다.
그래서 첫 단계에는 LLM이 관여하지 않습니다. 스캐너가 Domain Map에 적힌 이 문서의 백엔드와 프런트엔드 코드를 읽고, 문서를 쓸 때 참고할 사실을 하나의 증거 묶음으로 만듭니다.
증거 묶음에는 API와 인증 방식, 저장 필드의 타입과 길이, 오류 코드, 알림, 그리고 코드에 적힌 상수가 들어갑니다.
상수는 100 * 1000 * 1000처럼 적힌 값도 미리 계산해 두고, 곱해진 수 하나하나도 후보로 남깁니다. 나중에 원고를 검사할 때 “100MB”의 100이 정말 코드에서 온 숫자인지 확인하기 위해서입니다.
초안 작성: LLM이 필드 채우기
다음으로 LLM이 증거 묶음과 원본 소스 코드를 함께 읽고 초안을 씁니다. 문서의 제목과 다룰 범위, 용어 사전, UX 라이팅 규칙도 함께 프롬프트로 받습니다.
그런데 LLM이 쓴 문장은 어떻게 검사할 수 있을까요? 줄글로 받으면 어느 문장이 어느 코드에서 왔는지, 숫자가 맞는지를 결국 사람이 처음부터 다시 읽어야 합니다.
그래서 초안을 읽기 좋은 문서가 아니라, 한 줄 요약과 주장(claim) 목록이 담긴 커다란 JSON으로 받습니다. 규칙, 한도, 오류 코드, 접근 권한 같은 정책 하나하나가 각각 하나의 주장이 되고, 주장마다 근거가 되는 코드 위치가 붙습니다. LLM이 근거 코드를 찾지 못한 내용은 지어내지 않고 ‘확인하지 못한 것’으로 따로 남깁니다.
이 JSON의 형식, 즉 스키마는 CCP가 미리 정해 둡니다. 한 줄 요약, 주장 목록, 확인하지 못한 것처럼 들어갈 필드가 정해져 있고, LLM은 그 필드를 채울 뿐입니다. 스키마를 정해 두면 좋은 점이 세 가지 있습니다.
- 검사할 수 있습니다. 주장마다 근거 코드가 붙어 있으니, 문장 하나하나를 코드와 대조할 수 있습니다.
- 검토자의 수정이 지켜집니다. 필드마다 따로 저장하므로, 검토자가 어느 필드를 고쳤는지 정확히 알 수 있습니다. 그래서 문서를 다시 생성해도 그 수정을 덮어쓰지 않습니다.
- 어느 문서든 같은 순서로 읽힙니다.
게이트 5종: 통과하지 못한 곳만 LLM이 다시 쓰기
초안은 완성되기 전에 다섯 가지 자동 검사를 통과해야 합니다. 이 검사들을 게이트라고 부릅니다.
- 근거 파일이 이 문서가 맡은 도메인 안에 있는가
- 한도의 숫자가 코드에서 뽑은 상수와 일치하는가
- 용어 사전에 따라 코드 변수명이 서비스 용어로 바뀌었는가
- UX 라이팅 규칙을 지켰는가
- 편성표가 반드시 다루라고 한 사실이 문서에 담겼는가
게이트는 LLM을 쓰지 않는 검사 코드입니다. 같은 원고를 넣으면 언제나 같은 결과가 나옵니다. 근거가 존재하고 그럴듯해 보여도, 원고가 증거 묶음과 어긋나면 통과하지 못합니다. 사람이 일일이 대조하던 일을 매번 같은 기준으로 자동화한 셈입니다.
게이트를 통과하지 못하면 문서를 다시 쓰게 합니다. 처음에는 매번 처음부터 새로 쓰게 하고, 위반이 가장 적은 시도를 골랐습니다. 그런데 다시 쓸수록 문서에서 사실이 줄어들었습니다. 게이트는 주장을 검사하니, 주장을 지울수록 위반도 줄어들었기 때문입니다.
위반이 적은 문서가 좋은 문서는 아니었습니다.
그래서 직전 시도의 산출물과 위반 내용을 함께 넘기고, 통과하지 못한 곳만 고치게 했습니다. 여러 시도 가운데 하나를 고를 때도 위반 수만 보지 않고, 사실을 얼마나 지켜 냈는지를 함께 봅니다.
세 번까지 시도해도 위반 사항이 남으면, 문서를 버리지 않고 일단 다음 단계로 넘깁니다. 대신 남은 위반을 검토자에게 보여 주고, 실제로 코드에 문제가 있는 건 아닌지 확인하게 합니다.
채점: 신뢰 상태와 품질 점수 남기기
CCP는 문서마다 상태를 남깁니다. 정책이 부족한 곳이 있는지, 근거를 확인하지 못한 주장이 있는지를 문서에 그대로 적어 둡니다.
게이트를 통과한 초안은 한 번 더 평가를 받습니다. 초안을 작성한 모델과는 다른 LLM 모델을 이용해 정확성, 빠진 내용, 용어, 흐름, 독자에게 맞는지를 기준으로 점수를 매깁니다.
이 상태와 점수는 문서와 함께 공개됩니다. 나중에 도트가 이 문서를 근거로 답할 때도, 이 정보를 보고 답을 얼마나 확신할지 정합니다.
틀리지 않게, 비싸지 않게
충돌하는 정책과 운영에만 있는 정책 다루기
서로 다른 저장소의 코드가 서로 다른 정책을 말하기도 합니다. 프런트엔드에서만 입력을 막고 API는 막지 않는다거나, 백오피스의 안내 문구가 실제 동작과 다른 경우입니다.
정책 문서를 생성하다 보면 이런 차이가 분명하게 드러납니다. 이때 LLM이 둘 중 그럴듯한 쪽을 골라 버리면, 팀은 그 차이를 알아챌 기회를 잃습니다. 그래서 CCP는 어느 층에서 어떤 차이가 있는지 문장으로 남기고 검토자에게 알립니다. 이 충돌은 검토자가 한쪽을 고를 때까지 문서에서 지워지지 않습니다.
반대로 코드에는 없는 정책도 있습니다. 운영상 꼭 문서에 담아야 하는 사실은 편성표에 ‘반드시 다룰 사실’로 넣습니다. 이 사실은 문서에서도 운영에서 정한 사실로 구분해 표시합니다. 코드가 그렇게 동작하는 것과 팀이 그렇게 정한 것을 독자가 구분할 수 있게 하기 위해서입니다.
지문: 코드가 바뀐 문서만 다시 쓰기
제품 코드는 매주 바뀝니다. 그렇다고 그때마다 모든 문서를 다시 쓰면 시간과 비용이 감당되지 않습니다.
그래서 문서마다 읽은 증거 묶음과 편성표, 용어 사전, 모델 설정을 묶어 고유한 지문을 만듭니다. 지문이 같으면 다시 생성하지 않고 이전 문서를 그대로 사용합니다. 다시 써야 할 때는 무엇이 바뀌어서 다시 쓰는지도 함께 기록해, 그 비용이 꼭 필요했는지 확인할 수 있게 했습니다.
스캐너가 어느 문서에도 속하지 않는 새 코드 영역을 찾으면, 새 문서로 만들지 기존 문서에 붙일지를 검토자에게 묻습니다. 정해지기 전까지 그 영역은 제안으로만 남습니다.
2. 실제 화면으로 사용설명서 만들기
화면이 설명서가 되기까지
소스 코드를 읽고, 설명할 범위를 정하고, 초안을 만들고, 검토자가 고친 내용을 반영한다는 점에서 사용설명서도 정책 문서와 같은 플랫폼 위에서 만들 수 있었습니다.
다만 고객이 직접 읽는 사용설명서에는 더 다듬어진 문장과 실제 제품 화면이 필요합니다. 캡처하고, 자르고, 문서에 붙였고, 제품이 바뀔 때마다 이 일을 다시 해야 했습니다. CCP는 이 과정까지 자동화했고, 그래서 몇 가지 단계가 더 들어갑니다.
첫 번째 질문이었던 ‘웹페이지 동기화하기’를 예로 들어 보겠습니다.
- 데이터 소스 목록에서 ‘업로드’를 클릭합니다.
- 업로드 방식 가운데 ‘개별 웹페이지 동기화’를 선택합니다.
- 웹페이지 이름과 URL을 입력하고 ‘동기화’를 클릭합니다.
세 번의 조작은 모두 다른 화면에서 일어납니다. 독자가 헷갈리지 않으려면, 각 단계의 설명 옆에 바로 그 순간의 화면이 붙어 있어야 합니다. 문장과 그림이 같은 순간을 가리키게 하려면, 글을 쓰기 전에 사용자가 할 일과 촬영할 장면부터 정해야 했습니다.
카탈로그: 제품 화면 분석하기
LLM에게 코드만 주고 사용설명서를 쓰게 하면, 화면을 보지 못하기 때문에 버튼 이름이나 클릭하는 순서처럼 화면을 봐야 알 수 있는 내용이 틀리기 쉽습니다.
그래서 사용설명서도 소스 코드 스캔에서 시작합니다. 스캐너는 라우트와 페이지 컴포넌트뿐 아니라 다음 내용까지 읽어 카탈로그를 만듭니다.
- 화면에 보이는 문구
- 버튼과 입력 같은 조작이 무엇을 하는지
- 그 화면에서 호출하는 API
- 코드에 적힌 한도
예시의 경우 ‘업로드’ 버튼을 클릭하면 창이 열리고, ‘개별 웹페이지 동기화’ 카드로 방식을 고른다는 사실이 카탈로그에 적힙니다. 이 카드가 ‘업로드’를 클릭해야 나타난다는 관계까지 함께 적힙니다. ‘동기화’ 버튼은 올바른 URL이 있어야 켜진다는 조건과 한 번에 100행까지 입력할 수 있다는 한도도 코드에서 뽑아 카탈로그에 담습니다.
원고의 문장은 LLM이 화면을 상상해서 쓴 것이 아니라, 이 카탈로그의 항목을 하나하나 문장으로 옮긴 것입니다.
카탈로그에서 설명서 후보가 나오면, 정책 문서와 마찬가지로 편성표가 무엇을 쓸지 정합니다. 어떤 설명서를 쓰고 뺄지, 어느 구획에 둘지, 반드시 다룰 내용이 무엇인지가 여기서 정해집니다.
시나리오: 촬영 방법 정하기
무엇을 쓸지 정해지면, 그 내용을 보여 줄 장면을 정합니다. 화면마다 촬영 시나리오가 있습니다. 어느 주소에서 시작해 무엇을 클릭하고 무엇이 보일 때까지 기다릴지, 그 화면이 부르는 API에 어떤 응답을 줄지를 적은 파일입니다.
처음 문서화하는 기능이나 새로 생긴 화면에는 아직 시나리오가 없습니다. 이런 화면은 LLM이 시나리오를 새로 쓰게 되는데, 코드만 읽어서는 어떤 API가 언제 불리는지 다 알 수 없습니다. 그래서 시나리오를 쓰기 전에 먼저 Playwright로 화면을 실제로 열어 보고, 어떤 API가 호출되고 화면에 무엇이 보이는지를 기록해 LLM에게 넘깁니다.
화면에 들어갈 데이터도 목적에 맞게 준비합니다. 예를 들어 데이터 소스 목록 화면은 파일, Q&A, 웹페이지, 유튜브처럼 다양한 종류의 항목이 있어야 그 역할이 한눈에 읽힙니다. 연결이 끝난 항목과 진행 중인 항목이 섞여 있어야 여러 상태 표시도 한 장면에 드러납니다. 응답의 모양은 제품 SDK의 응답 스키마로 맞추고, 그 안에 들어갈 값은 LLM이 화면에 맞게 채웁니다.
조작 단위로 장면 촬영하기
모든 화면은 실제 프런트엔드 코드를 실행해 촬영합니다. 시각과 언어, 테마를 고정하고, 촬영 직전에는 설명하려던 요소가 실제로 보이는지 확인합니다.
시나리오에 장면을 일일이 적지는 않습니다. 생성 파이프라인이 조작의 종류를 보고 촬영할 순간을 정합니다. 창을 여는 조작 앞에서는 그 버튼이 보이는 장면을, 방식을 고르는 조작 앞에서는 선택지가 보이는 장면을 남기는 식입니다.
준비하지 않은 API 요청이 나오면 빈 화면을 촬영하지 않고 멈춥니다. 빠진 응답을 채우거나 LLM이 시나리오를 고친 뒤, 그 화면만 다시 촬영합니다. 촬영이 막혀도 사람을 부르기 전에 스스로 고쳐 보는 것입니다.
문장과 장면 맞추기
촬영이 모두 끝나야 원고를 완성합니다. LLM은 카탈로그와 편성표, 촬영한 장면 목록을 받아 단계별 설명을 쓰고, 단계마다 어떤 장면을 붙일지 직접 고릅니다. 고른 장면이 실제로 있는지, 꼭 들어가야 할 장면이 빠지지 않았는지는 정책 문서의 게이트처럼 LLM 없이 검사 코드로 확인합니다.
설명서는 독자가 화면의 어디를 봐야 하는지도 짚어 줘야 합니다. 처음에는 강조할 대상을 LLM이 시나리오에 적어 주기를 기대했습니다. 그런데 LLM은 그 값을 대부분 비워 뒀고, 장면 대부분이 전체 화면 그대로 실렸습니다. 독자는 넓은 화면에서 문장이 안내하는 버튼 하나를 직접 찾아야 했습니다.
답은 시나리오에 이미 있었습니다. 시나리오에는 “무엇을 클릭할지”가 적혀 있습니다. 그래서 다음에 조작할 대상을 초점으로 삼아 강조 표시를 하고, 그 주변을 16:9로 잘라 보여 줍니다.
강조할 초점은 다음 순서로 고릅니다.
- 검토자나 LLM이 지정한 대상
- 다음 조작의 대상
- 그 장면을 만든 조작의 대상
- 장면을 촬영하기 위해 기다리던 요소
이렇게 만들어진 사용설명서는 다음과 같습니다.
같은 일을 두 번 하지 않게
바뀐 화면만 다시 촬영하기
제품이 바뀌면 어떤 화면을 다시 촬영할지 정해야 합니다. 정책 문서처럼 화면마다 그 화면이 의존하는 소스, 촬영 방법과 표시 값, 촬영 규칙, 강조 및 크롭 규칙을 비교합니다.
핵심은 화면의 픽셀을 바꾸는 입력과, 그 위에 얹는 강조만 바꾸는 입력을 나눈 것입니다. 강조 위치만 바뀌었다면 브라우저를 다시 띄워 촬영할 필요가 없습니다. 저장해 둔 원본 위에 강조만 다시 그리면 됩니다.
원고도 마찬가지입니다. 지문이 같으면 그대로 쓰고, 다시 써야 할 때는 이전 원고를 함께 넘겨 바뀐 부분만 고치게 합니다. 제품이 조금 바뀌었다고 설명서 전체의 말투와 구성이 흔들리면, 검토자가 다시 봐야 할 곳이 그만큼 늘어나기 때문입니다.
LLM이 한 번 고친 응답은 다른 화면도 함께 사용하기
한번은 제품이 업데이트되면서 관리자 화면의 공통 헤더가 새 API를 호출하기 시작한 적이 있습니다. 시나리오에는 그 API의 응답이 준비되어 있지 않았으니, 앞에서 본 것처럼 촬영이 중단되었습니다. 그런데 한두 개 화면이 아니라 관리자 화면 수십 개가 같은 이유로 멈췄습니다.
화면마다 LLM이 스스로 고치는 데는 성공했지만, 문제는 모두가 같은 응답을 각자 처음부터 고쳤다는 점입니다. 같은 수정과 재촬영이 화면 수만큼 반복되었고, 그만큼 시간과 비용이 들었습니다.
그래서 한 번의 생성 안에서 LLM이 고친 응답을 함께 공유하도록 했습니다. 처음 고친 응답이 촬영을 통과하면 해당 응답을 후보로 등록해 두고, 같은 API에서 멈추는 화면은 그 후보로 바로 채웁니다. 생성이 끝나면 여러 시나리오가 똑같이 쓴 응답을 공통 응답으로 올려, 다음 생성부터는 문제가 되지 않도록 합니다.
3. 검토하고 공개하기
정책 문서든 사용설명서든, 생성이 끝났다고 바로 공개되지는 않습니다. 검토자가 결과를 보고, 고치고, 승인한 버전만 고객과 도트에게 전달됩니다.
생성을 자동화해도 검토에 시간이 많이 들면 효율은 제자리입니다. 그래서 CCP는 검토자가 봐야 할 곳만 보고, 판단만 하면 되도록 검토 화면을 만들었습니다.
검토 목록: 판단이 필요한 곳만 모으기
생성 파이프라인이 남긴 확인할 점은 문서마다 검토 목록으로 모입니다. 정책이 충돌한 곳, 설명과 장면이 어긋나 보이는 단계처럼 LLM이 초안을 쓰면서 검토자의 판단이 필요하다고 남긴 곳을 한눈에 보여 줍니다.
검토는 실제로 배포될 모습 그대로의 미리보기 위에서 합니다. 지금 공개된 버전과 비교하며 바뀐 곳을 바로 고칠 수 있고, 언제든 LLM이 쓴 초안으로 되돌릴 수 있습니다.
병합: 다시 생성해도 검토자의 수정 지키기
문서를 다시 생성할 때마다 검토자가 고친 문장이 사라진다면, 검토자는 같은 곳을 매번 다시 고쳐야 합니다. 자동 생성이 오히려 일을 늘리는 셈입니다.
1장에서 본 것처럼 CCP는 문서를 필드 단위로 저장합니다. 그래서 검토자가 어느 필드를 고쳤는지 정확히 알고 있고, 다음 생성이 돌아오면 고친 필드마다 아래 세 경우 중 하나로 처리합니다.
- LLM의 새 초안이 예전과 같다면, 검토자가 고친 문장을 그대로 둡니다.
- 새 초안이 달라졌다면 제품이 바뀌었을 수 있으니, 검토자의 문장을 유지하되 새 초안을 함께 보여 줍니다.
- 고친 필드가 새 원고에서 사라졌다면, 조용히 버리지 않고 빠졌다고 알립니다.
어떤 경우에도 검토자의 수정이 모르는 사이에 바뀌거나 사라지지 않습니다.
새 초안을 함께 보여 줄 때는, 검토자가 판단만 하면 되도록 두 문장을 나란히 놓습니다. 달라진 낱말에만 색을 칠하고, ‘내 것 유지’나 ‘AI 제안으로’ 버튼 하나로 고르게 합니다. 내 것을 유지하면 같은 초안으로는 다시 묻지 않습니다.
도우미 에이전트: 원인과 고칠 자리 찾기
검토하다 보면 “이 단계에는 왜 그림이 없지?”, “이 문장은 왜 이렇게 썼지?” 같은 의문이 생깁니다. LLM이 여러 입력을 함께 참고해 결과를 만들기 때문에, 답을 찾으려면 편성표와 시나리오, 촬영 기록을 차례로 열어 봐야 합니다. 검토 시간의 가장 큰 몫은 고치는 일이 아니라 이 원인을 찾는 일이었습니다.
그래서 CCP에는 도우미 에이전트를 두었습니다. 검토자가 보고 있던 문서에서 “3단계에 왜 그림이 없어요?”라고 물으면, 도우미 에이전트가 그 문서의 근거 파일과 생성 기록, 초안과 사전을 읽어 원인을 설명합니다. 그리고 어디를 어떻게 고치면 되는지 제안합니다. 원인을 찾는 일은 도우미 에이전트가, 고칠지 말지는 검토자가 정합니다.
자동 생성: 제품이 배포되면 다시 만들기
검토가 끝나면 승인하고 공개할 수 있습니다. 승인은 그 시점의 원고를 봉인해 하나의 버전으로 만드는 일이고, 공개는 그 버전을 실제로 배포하는 일입니다.
공개는 ‘지금 버전’을 가리키는 포인터를 옮기는 일입니다. 그래서 롤백도 포인터를 예전 버전으로 돌리면 끝납니다. 포인터를 옮기면 사용설명서 사이트와 도트가 검색하는 색인이 함께 같은 버전으로 바뀝니다.
승인과 공개를 나눈 것은 자동 생성과도 맞닿아 있었습니다. 제품이 업데이트되면 문서도 따라 최신이 되도록, CCP는 제품의 운영 배포를 감지하면 스스로 생성을 시작합니다.
자동으로 만든 정책 문서는 승인해 버전으로만 남겨 둡니다. 이어서 사용설명서까지 만든 뒤, 검토가 필요하다고 사내 메신저로 알립니다. 검토자가 사용설명서를 승인하면, 정책 문서도 함께 공개됩니다.
반복되는 일은 최대한 자동화하되, 최종 결정은 사람이 내린다는 원칙을 지킨 것입니다.
4. 도트: 근거를 찾아 답하기
이제 처음의 질문으로 돌아가 보겠습니다. 지금까지는 문서를 만드는 이야기였다면, 여기부터는 그 문서로 답하는 이야기입니다.
도트는 질문을 받으면 먼저 어떤 근거가 필요한지 분류합니다. 사용법을 묻는 질문이면 사용설명서를, 규칙을 묻는 질문이면 정책 문서를 먼저 봅니다. 문서에 없는 지난 논의를 묻는 질문이면 사내 메신저 기록을 찾습니다.
동료는 더 이상 담당자를 찾아갈 필요가 없습니다. 사내 메신저에서 도트를 부르면 됩니다.
사용법과 규칙 질문에 답하기
동료가 사내 메신저에서 도트에게 “웹페이지를 데이터 소스에 어떻게 추가해요?”라고 묻습니다.
도트는 CCP가 만들고 검토자가 승인해 지금 공개된 문서에서 근거를 찾습니다. 앞에서 만든 ‘웹페이지 동기화하기’ 설명서의 단계를 근거로 답하고, 인용한 단계의 화면도 함께 보여 줍니다.
“동기화는 하루에 몇 번 진행되나요?”처럼 한도나 규칙을 묻는 질문에는 사용설명서의 제한 사항과 정책 문서를 근거로 답합니다. 이때 정책 문서의 상태와 품질 점수도 함께 참고합니다. 문서가 공개된 뒤 코드가 바뀌어 근거가 오래됐을 수 있다면, 답에 그렇게 밝힙니다.
문서만으로는 단정할 수 없는 질문도 있습니다. 이때는 문서로 아는 만큼 먼저 답하고, 코드를 직접 확인한 뒤 그 결과를 같은 스레드에 이어서 답합니다. 동료는 코드 확인이 끝날 때까지 기다리지 않아도 됩니다.
사내 메신저 에이전트: 문서에 없는 지난 결정 찾기
세 번째 질문 “웹페이지 동기화가 실패하면 고객사에 어떻게 안내하기로 했었죠?”는 정책 문서나 사용설명서로 답할 수 없습니다. 무엇이 규칙인지가 아니라, 누가 언제 무엇을 정했는지를 묻는 질문이기 때문입니다. 이런 질문은 사내 메신저를 조사하는 에이전트가 맡습니다.
도트는 질문을 받으면 먼저 제목을 붙여 접수하고, 조사하는 동안 진행 상황을 보여 줍니다. 처음에는 동의어와 결론을 나타내는 낱말을 섞어 넓게 검색합니다. 관련 있어 보이는 스레드를 읽다가 새로 드러난 용어로 범위를 좁혀 다시 찾습니다. 부족한 내용은 웹에서 찾기도 하고, 이렇게 모은 근거로 답을 씁니다.
LLM에게 출처까지 쓰게 하면, 있지도 않은 메시지의 링크를 그럴듯하게 만들어 낼 수도 있습니다. 그래서 도트는 조사하면서 실제로 본 메시지를 따로 기록해 두고, 답에 첨부하는 출처는 이 기록에서 만듭니다. 미처 확인하지 못한 내용 역시 함께 적습니다. 아무 말이 없으면 동료는 도트가 모든 채널을 확인했다고 오해하기 쉽기 때문입니다.
권한: 볼 수 없는 것은 답에 쓰지 않기
사내 메신저 에이전트를 만들면서 가장 조심한 건 권한입니다. 도트가 메시지를 읽을 수 있다는 것과, 그 내용을 답에 써도 된다는 것은 다른 문제이기 때문입니다.
도트는 질문한 사람의 권한과 답이 올라갈 채널을 보고, 어떤 메시지를 근거로 쓸지 판단합니다. 예를 들어 공개 채널에서 물었다면, 질문자가 볼 수 있는 비공개 채널의 내용이라도 답에 쓰지 않습니다. 그 답을 다른 사람도 읽기 때문입니다. 답에 쓸 수 없는 메시지는 조용히 빼고, 그런 메시지가 있었다는 사실도 말하지 않습니다.
5. 반복은 LLM에게, 판단은 사람에게
같은 질문 324개로 다시 비교하기
예전의 도트는 CCP 같은 플랫폼과 연결되어 있지 않았고, 사내 메신저를 검색할 수도 없었습니다. 개발자가 AI 코딩 에이전트로 만든 정책 문서를 벡터 DB에 넣어 두고, 최소한의 구현으로 RAG를 하는 정도였습니다.
도트를 지금 구조로 다시 만든 뒤, 예전 도트가 받았던 실제 질문 324개를 새 도트에 그대로 다시 물었습니다. 예전 도트가 답한 질문은 139개, 새 도트가 답한 질문은 208개였습니다. 되묻는 일은 크게 줄었고, 응답은 두 배 넘게 빨라졌습니다.
이 결과는 도트 혼자 만든 것이 아닙니다. 그사이 CCP가 생성한 문서가 연결되고 품질도 좋아진 덕분이기도 합니다. 문서를 만드는 일과 답하는 일이 연결되면서, 질문에 답을 얻는 데 드는 시간이 줄었습니다.
질문 하나에 쓰이던 두 사람의 시간 줄이기
예전에는 문서를 만드는 일이 한 사람의 시간을 통째로 쓰는 번거로운 작업이었습니다. 생성 스크립트를 돌리고, 결과 파일을 받아 고치고, 서버에 직접 올리고 색인했습니다. 제품이 배포되어도 무엇이 바뀌었는지 몰라 답할 근거를 찾지 못하기 일쑤였고, 만들어 둔 문서도 돌릴 때마다 내용이 크게 흔들렸습니다.
이제는 제품이 배포되면 정책 문서와 사용설명서가 자동으로 다시 만들어집니다. 검토자는 검토 목록과 결정 카드를 보며 판단이 필요한 곳만 확인하고 공개합니다. 동료는 사내 메신저에서 도트에게 물어 바로 답을 받습니다.
사람이 하던 일이 사라진 것은 아닙니다. 문서를 쓰고, 화면을 캡처하고, 같은 질문에 반복해서 답하던 시간이 꼭 필요한 판단을 내리는 시간으로 옮겨 갔습니다.
클라썸 팀에게 AX는 단순한 자동화가 아니었습니다.
반복되는 일은 LLM에게 맡기고, 사람은 판단에 집중하게 만드는 일이었습니다.
.svg){kind=icon}
.png)
