techlist.io
KREN
toss

5. Technical Writer, 사라질 결심 (새 탭에서 열림)

aiprompt-engineeringtechnical-writingclidocumentation-automationadrmdx

AI 시대에 문서는 조직의 맥락을 AI에 전달하는 핵심 수단이므로, AI가 문서를 잘 만들고 관리하도록 문서화 원칙과 사례를 학습시켜야 한다. 토스는 소수의 Technical Writer(TW)만으로 수천 명의 문서를 관리할 수 없다는 문제를 해결하기 위해, TW의 역할을 AI Skill로 자동화하려 했다. 하지만 Skill을 만들어 공개하는 것만으로는 사용률이 높아지지 않았고, 사용자가 직접 설치·호출하고 자료를 준비해야 하는 불편함이 주요 장애물로 드러났다.

AI에게 TW의 암묵지 전달하기

  • 기존 TW의 리뷰 코멘트를 분석해 문서를 바라보는 관점과 테크니컬 라이팅 원칙을 추출했다.
  • 기존 가이드를 AI가 기계적으로 적용하지 않도록 각 원칙에 다음을 함께 제공했다.
    • 잘못된 예시
    • 올바른 예시
    • 왜 그렇게 작성해야 하는지에 대한 설명
  • 자주 작성하는 문서 유형별 템플릿을 만들었다.
  • ADR 템플릿에는 다음과 같은 필수 섹션을 명시했다.
    • 개요
    • 맥락
    • 고려한 선택지와 장단점
    • 최종 결정
    • 결정 근거
  • 반드시 들어가야 하는 섹션에는 (required)를 붙여 AI가 핵심 정보를 누락하지 않게 했다.
  • 문서 유형과 템플릿을 함께 제공해 AI가 구조와 작성 목적을 이해하도록 했다.

문서 작성 Skill 구축

TW가 문서 작성을 지원하는 과정을 네 단계로 분해해 AI Skill에 반영했다.

  • 목적과 배경 확인
    • 서비스·프로젝트명
    • 문서 목적
    • 대상 독자
    • 필요한 상세 수준
    • 참고 자료
    • 예상 문서 구조를 질문한다.
  • 문서 구조 결정
    • 템플릿이 없으면 개요, 핵심 내용, 부가 정보 순서로 기본 구조를 만든다.
    • 적합한 템플릿이 있으면 온보딩 가이드, 회의록, PRD 등 문서 유형별 템플릿을 참고한다.
  • 본문 작성
    • 테크니컬 라이팅 원칙과 MDX 규칙에 따라 내용을 채운다.
    • 템플릿은 문서의 목적과 유형에 맞을 때 보조적으로 사용한다.
  • 점검
    • 어색한 표현이나 누락된 정보를 확인한다.
    • 필수 정보가 부족하면 추측하지 않고 질문이나 주석으로 남긴다.
    • 선택 항목은 근거 자료가 없을 경우 빈 섹션으로 만들지 않는다.

사용자는 AI가 묻는 질문에 답하기만 하면 되므로, TW와 대화하듯 문서 초안을 완성할 수 있도록 설계했다.

문서 리뷰 Skill의 시행착오

처음에는 기존 리뷰 코멘트를 체크리스트로 바꿔 AI가 모든 항목을 점검하게 했다. 그러나 AI가 중요한 문제는 놓치고, 실제로 필요하지 않은 코멘트를 억지로 생성하는 문제가 발생했다.

  • 잘 작성된 문서의 기준은 어느 정도 정형화할 수 있다.
  • 반면 잘못된 문서의 문제는 문서마다 다르게 나타난다.
    • 목적은 명확하지만 논리 흐름이 어색한 경우
    • 논리는 자연스럽지만 독자에게 전달할 가치가 빠진 경우
  • 따라서 고정된 체크리스트만으로는 다양한 문서 문제를 효과적으로 찾기 어려웠다.

이를 해결하기 위해 AI가 원칙을 참고해 자율적으로 판단하는 리뷰 워크플로를 만들었다.

  • 테크니컬 라이팅 원칙 파일을 먼저 읽는다.
  • 문서를 원칙에 비추어 스스로 검토한다.
  • 문제라고 판단한 이유와 수정 초안을 코멘트로 작성한다.
  • 마지막에 체크리스트로 누락을 한 번 더 확인한다.

기존 리뷰 코멘트는 단순 점검 목록이 아니라, 원칙이 실제 문서에 어떻게 적용되는지 보여주는 예시로 활용했다. 예를 들어 date: string처럼 이름과 타입만 적는 대신, 의미·허용 형식·사용 예시까지 함께 작성하도록 가르쳤다.

Skill만 공개해서는 충분하지 않았다

두 가지 Skill을 만들어 사내에 공개했지만, 기대만큼 사용되지 않았다.

  • 사용자가 직접 Skill을 다운로드하고 설치해야 했다.
  • 비개발자에게 CLI 기반 설치 과정이 낯설고 어려웠다.
  • Skill을 설치한 뒤에도 문서를 작성할 때마다 사용자가 AI Skill을 떠올리고 직접 호출해야 했다.
  • 문서 작성에 필요한 코드, 기획서, 기존 문서, Slack 링크 등의 자료도 사용자가 직접 찾아 AI에게 전달해야 했다.
  • 결국 자동화된 기능이 있어도 실제 업무 흐름과 분리되어 있으면 사용자가 추가로 수행해야 하는 일이 많았다.

따라서 문서 자동화의 핵심은 좋은 프롬프트나 Skill을 만드는 데서 끝나지 않는다. 사용자가 별도로 설치하거나 기억하거나 자료를 수집하지 않아도, 실제 업무 과정에서 자연스럽게 AI가 문서 작성과 리뷰를 지원하도록 연결해야 한다.