토스테크

안녕하세요. 토스 Technical Writing Partner 김혜빈입니다.
이전 편에서 AI 시대에 문서화 방식이 어떻게 달라졌는지 간단히 소개했는데요. AI가 문서화 방식을 바꿨듯, 문서도 AI의 일에 영향을 줄 수 있어요. AI는 똑똑하지만 조직의 맥락을 모르면 제대로 동작하지 않는데, 그 맥락을 AI에게 전달하는 가장 쉬운 수단이 바로 문서이기 때문이에요. 그래서 토스 팀에서도 문서를 잘 관리하고 싶다는 요구가 빠르게 늘었어요.
문제는 규모예요. 토스 커뮤니티 전체 인원은 약 4천 명인데, Technical Writer(이하 TW)는 단 3명뿐이거든요. 팀원들이 문서를 하나씩만 만들어도 셋이서 수천 개를 리뷰해야 하는 셈이죠. 게다가 토스처럼 빠른 조직에서는 문서를 다 쓸 때쯤이면 어떤 기능은 이미 사라지고, 새로운 기능이 나와 있어요. TW가 일일이 변경 사항을 따라잡는 방식으로는 애초에 불가능한 일이에요.
그래서 우리 챕터는 토스에서 TW를 없애자는 목표를 세웠어요. 여기서 '없앤다'라는 건, TW가 직접 글을 쓰고 다듬는 일을 AI에게 넘기겠다는 거예요. 그 일이 자동화되면 TW가 없어도 조직 곳곳에서 문서가 잘 관리될 수 있으니까요.
이 글에서는 그 자동화의 여정을 소개할게요.
AI를 TW로 만들기
1. TW의 암묵지 알려주기
제가 토스 팀에 합류하고 나서 가장 처음으로 맡은 일은 지금까지 쌓아온 테크니컬 라이팅 리뷰 코멘트를 분석하는 것이었어요. 이걸 바탕으로 TW가 어떤 관점에서 글을 읽는지, 테크니컬 라이팅 원칙이 실제로 어떻게 적용되는지를 빠르게 습득할 수 있었어요.
예를 들면 이런 내용들이었어요.
제가 이런 리뷰 코멘트를 분석하면서 업무에 익숙해진 것처럼, AI를 새로 합류한 팀원이라 생각하고 TW가 생각하는 방식에 익숙해지도록 만들어 보기로 했어요. 
다행히 기준을 새로 만들 필요는 없었어요. 기존에 정리한 테크니컬 라이팅 가이드가 있었거든요. 가이드를 바탕으로 "한 페이지에서는 하나만 다루기", "가치를 먼저 제시하기"처럼 좋은 문서가 지켜야 할 기준에 따라 원칙을 추렸어요. 다만 사람이 보던 가이드를 그대로 주면 AI는 규칙을 기계적으로만 적용해요. 그래서 AI가 참고할 수 있도록, 원칙마다 잘못된 예시와 올바른 예시를 짝지어 보완했어요.
그리고 자주 쓰는 문서 유형을 정리한 뒤 그 문서에 반드시 들어가야 하는 내용을 템플릿으로 만들어 글쓰기 작업에 활용할 수 있도록 했어요. 예를 들어 결정 사항을 기록하는 ADR 문서는 아래와 같은 템플릿으로 정리했는데요. 템플릿에는 두 가지 장치를 넣었어요. 먼저 섹션마다 어떤 내용이 들어가야 하는지를 적어 뒀어요. 그래서 AI가 엉뚱한 내용을 작성하지 않고, 의도에 맞는 내용으로 채워 넣을 수 있어요. 그리고 결정의 근거처럼 빠지면 안 되는 섹션의 제목에는 ‘(required)’을 붙였어요. 이 문서에 반드시 포함되어야 할 정보를 건너뛰지 않도록 한 거예요.
이렇게 TW라면 반드시 알아야 하는 것들을 가르쳐 줬으니, 이제 일을 시킬 차례예요. 그동안 사람들이 TW에게 도움받던 부분은 다음 두 가지였어요.
새로운 글 쓰기
글 다듬기 
이 두 가지를 AI가 참고해서 작업할 수 있도록 Skill을 만들었어요.
2. 글 쓰는 방법 알려주기
TW가 팀원의 문서 작성을 도울 때는 보통 네 단계를 거쳐요. 
무엇을 위한 글인지 묻기: 어떤 문제를 해결하려는 글인지, 독자는 누구인지, 참고할 자료가 있는지 질문해요.
문서 구조 만들기: 모은 정보를 바탕으로 글의 목차와 핵심 메시지를 정해요.
내용 작성하기: 구조를 바탕으로 본문 채워 넣어요.
점검하기: 어색한 부분이나 빠진 부분이 없는지 확인해요.
이 단계를 그대로 옮겨서 문서 작성 Skill을 만들었어요. 다음은 실제 프롬프트의 일부를 발췌한 내용이에요.
Skill 사용법은 간단해요. 사용자는 AI가 물어보는 질문에 답만 하면 돼요. 아래 화면은 실제로 Skill을 사용하는 모습인데요. 실제 TW와 대화하듯 질문에 답하다 보면 어느새 문서 초안이 완성되어 있어요.
3. 글 다듬는 방법 알려주기
TW가 문서를 리뷰할 때는 글을 읽다가 "여기 뭔가 어색한데?" 하는 직감을 먼저 느낄 때도 많아요. 그 직감이 들면 왜 그렇게 느꼈는지 이유를 찾고, 개선점을 도출해요.
처음에는 앞서 분석해 둔 리뷰 코멘트를 그대로 체크리스트로 만들어, AI가 항목을 하나하나 확인하게 했어요. 그런데 오히려 정작 중요한 문제는 놓친 채, 굳이 달지 않아도 될 코멘트만 억지로 만들어 내는 거예요. 
그 원인은 리뷰와 작성의 차이 때문이었어요. 잘 쓰인 글의 조건은 정해져 있지만, 잘못 쓴 글은 매번 다른 문제가 있거든요. 어떤 글은 목적은 분명한데 논리 흐름이 어색하고, 어떤 글은 논리는 깔끔한데 가치가 빠져 있는 것처럼요. 그래서 이렇게 제각각인 포인트를 미리 정해 두는 방식은 효과적이지 않았어요.
그래서 AI가 테크니컬 라이팅 원칙을 참고해서 자율적으로 리뷰하는 워크플로를 만들었어요.
테크니컬 라이팅 원칙 확인하기: 리뷰에 참고할 테크니컬 라이팅 원칙 파일을 읽어요.
리뷰할 문서 읽기: AI가 스스로 테크니컬 라이팅 원칙에 맞지 않는 부분을 찾아내요.
코멘트 생성: 테크니컬 라이팅 원칙에 맞지 않는다고 판단한 이유와 수정 초안을 코멘트로 남겨요.
체크리스트 확인: 마지막에 원칙을 바탕으로 한 번 더 검토해요.
기존에 정리한 리뷰 코멘트는 체크리스트로 활용하는 대신, 원칙이 실제로 어떻게 적용되는지 보여주는 예시로 만들었어요. 워크플로 첫 순서에서 AI가 읽는 '테크니컬 라이팅 원칙 파일'이 바로 아래의 프롬프트예요. 원칙마다 잘못된 예시와 올바른 예시를 짝지어 두어서 AI가 규칙을 기계적으로 해석하지 않고 왜 이렇게 써야 하는지 이해하고 작업할 수 있어요.
하지만 아무도 쓰지 않았다
이렇게 두 가지 Skill을 만들고 나서, "이제 다들 좋은 문서를 쓰시겠지"라는 야심 찬 기대로 사내에 공개했어요. 그런데 생각보다 많이 사용하지 않으시더라고요.
왜일까 고민하다 보니 한 가지 결론에 도달했어요. 아직도 사용자가 직접 해야 할 일이 너무 많다는 점이었어요.
Skill은 사용자가 직접 다운로드 받아서 사용해야 하는데, 비개발자 팀원에게는 CLI로 Skill을 세팅하는 방식 자체가 낯설고 어려웠어요. Skill을 설치했더라도, 업무 중에 "아, 지금 문서를 써야겠다" 하고 매번 의식적으로 떠올려야 했고요. 게다가 문서를 쓰려면 필요한 자료를 사람이 일일이 찾아서 AI에게 건네줘야 했어요.
그래서 만들어둔 Skill을 더 발전시켰어요. 불편함과 번거로움을 낮춰주는 정도가 아니라, 아예 사용자가 해야 하는 일들을 전부 대신 해주는 쪽으로요.
1 팀원 1 TW 보급하기
각 팀에서 문서화 Skill을 더 쉽게 사용할 수 있도록 추가로 이런 작업을 했어요.
별도 설치나 업데이트 없이 사용하게 만들기
사용자가 매번 떠올리지 않아도, 일하던 흐름 속에서 쓸 수 있게 하기
문서 작성에 필요한 자료를 AI가 직접 찾기
이 세 가지를 한꺼번에 풀 방법은 하나였어요. Skill을 업무 프로세스에 딱 맞는 도구로 만들어서 제공하는 거예요. 글쓰기는 대화가 오가는 사내 메신저에서, 글 다듬기는 문서가 관리되는 GitHub에서 할 수 있도록요.
굳이 왜 사내 메신저와 GitHub에서 문서 작업이 이루어져야 했는지, 그리고 그곳에 어떻게 적용했는지를 소개할게요.
사내 메신저에서 글쓰기
먼저, 사내 메신저에서 글쓰기를 할 수 있도록 “토독이”라는 챗봇을 만들었어요. 앞서 만든 문서 작성 Skill 프롬프트를 그대로 적용해서 문서의 퀄리티도 마치 TW와 함께 쓴 것처럼 좋아요.
사내 메신저에서 문서를 써야 하는 이유는 간단해요. 좋은 문서에는 겉으로 드러난 내용뿐 아니라 암묵지가 함께 담겨야 하기 때문이에요. "왜 이렇게 하기로 했는지", "어떤 점을 고민했는지" 같은 건 막상 문서에 담기는 어렵지만, 글을 읽는 사람이 가장 궁금해할 부분인데요. 이런 암묵지는 주로 대화를 나누는 과정에서 자연스럽게 드러나요. 그리고 그 대화가 오가는 곳이 바로 사내 메신저고요. 그래서 대화하던 흐름을 끊지 않고 그대로 문서로 옮길 수 있도록, 메신저에서 문서를 쓸 수 있게 했어요.
사용법은 사내 메신저에 토독이를 태그해서 "이거 문서로 만들어줘"라고 하면 끝이에요. 그러면 토독이가 문서 작성에 필요한 자료를 사내 메신저와 토독에서 직접 찾아 모은 다음, 초안을 만들어요. 예전에는 사람이 자료를 일일이 찾아 건네줘야 했다면, 이제는 그 일까지 토독이가 대신하는 거예요.
GitHub에서 글 다듬기
다음으로, GitHub에서 글 다듬기가 자동으로 이루어지도록 리뷰 워크플로를 만들었어요. 앞서 만든 문서 리뷰 Skill을 GitHub Actions에 그대로 적용해서, TW가 직접 다는 것과 같은 기준의 코멘트를 받을 수 있어요.
GitHub에서 문서를 리뷰해야 하는 이유는 개발자들에게 가장 익숙한 환경이 GitHub이기 때문이에요. 토스의 정책 결정이 메신저에 남아 있다면, 개발 문서는 대부분 GitHub에서 관리되고 있거든요. 무엇보다 GitHub에는 리뷰가 시작되는 순간이 이미 정해져 있어요. 바로 PR(Pull Request)이 열리는 때예요.
그래서 문서가 포함된 PR이 열리면 자동으로 리뷰가 시작되도록 만들었어요. 사용자가 따로 할 일은 없어요. 평소처럼 PR을 열기만 하면, AI 봇이 테크니컬 라이팅 원칙에 따라 리뷰 코멘트를 달아줘요. 개발자가 코드 PR에서 받는 리뷰와 똑같은 방식이에요.
예전에는 "문서 다듬어야지” 하고 AI를 직접 호출해야 했다면, 이제는 그 일조차 할 필요가 없게 됐어요.
TW의 일은 아직 남아 있다
이 글을 시작하며 우리 챕터는 "토스의 TW를 없애겠다"라고 했어요. 그래서 직접 글을 쓰고 다듬던 일은 이렇게 AI에게 넘겼고요. 이제 토스 팀원들은 이제 TW가 없어도 빈 화면 앞에서 막막해하거나 TW와 문서 작성이나 리뷰 일정을 조율하지 않아도 돼요.
하지만 목표를 다 이룬 건 아니에요. 문서를 쉽게 쌓게 됐더니, 이제는 너무 많이 쌓여서 문제거든요. 같은 내용의 문서가 여러 곳에서 중복되고, 한 번 만든 문서는 금세 낡아요.
그래서 이제는 쌓인 지식이 스스로 순환하게 만들어야 해요. 지식이 생성되고, 검증되고, 갱신되고, 폐기되는 과정을 어떻게 설계하는지는 다음 편에서 자세히 이야기할게요. 그 과정까지 자동으로 돌아가는 날, 글을 쓰고 다듬던 TW는 정말 사라질 거예요.

5. Technical Writer, 사라질 결심

댓글