기술 문서 자동화, 정말 될까?

지난 AI야, 문서 좀 대신 써 줘 - 2. 쪽지 시험에서 최신 AI 모델들이 기술 문서를 얼마나 잘 이해하는지 실험해 봤어요. 결과는 꽤 괜찮았지만, 마음 한켠엔 아직 물음표가 남아 있었습니다.

왜냐하면 쪽지 시험에 사용한 문서는 테크니컬 라이터가 정성껏 작성한 완성형 문서였거든요. 그런데 실제 현업에서는 정리되지 않은 초안이나 회의 메모처럼 다듬어지지 않은 자료를 가지고 문서를 써야 해요. 과연 AI도 그런 자료로 잘 쓸 수 있을지 궁금해졌습니다.

그래서 이번에는 NotebookLM을 사용해 보기로 했습니다. 구글 랩스(Google Labs)에서 만든 AI 기반 문서 분석 도구인데요, 자료를 올리면 요약해주고, 질문에도 척척 답해줘요. 논문이나 기술 자료 읽을 때 아주 유용하죠! 그리고 NotebookLM은 업로드한 자료를 학습용으로 사용하지 않습니다.(참고)

아래는 NotebookLM으로 A Survey of AI Agent Protocols 논문을 읽으며 생성해 본 마인드맵이에요.

실제로 사내 개발자와 기획자가 정리한 문서 수십 장을 NotebookLM에 업로드해봤어요. 사람이 읽고 이해하려면 며칠 걸릴 양인데, NotebookLM은 금세 내용을 요약하고, 원문을 근거로 질문에 답해줬어요. 카카오의 기술 문서와 스타일 가이드 기반으로 기술 문서를 새로 쓰는 것도 물론 가능했습니다.

하지만 아쉽게도, TW 에이전트는 훨씬 더 다양한 제품과 기술을 다뤄야 하고, 누구나 쉽게 쓸 수 있어야 해요. NotebookLM만으로는 부족할 것 같아, 다시 원래대로 AI 모델이 직접 기술 문서를 작성하게 하는 방식으로 돌아왔습니다.

첫 번째 테스트

앞서 TW 에이전트에게 필요한 세 가지 능력 중, 기술 정보를 분석하고 분류하는 능력은 이미 확인했죠. 이제 두 번째 능력, 복잡한 기술 정보를 이해하고 명확하게 설명하는 능력을 검증해 볼 차례예요.

이번에는 구글 AI 스튜디오에서 TW 에이전트의 주인공, Gemini 2.5 Pro를 사용해 세 가지 케이스를 테스트했습니다.

카카오의 스타일 가이드에 맞춘 문서 재작성
카카오의 기술 문서 템플릿 구조에 맞춘 문서 재작성
템플릿과 스타일 가이드를 모두 준수한 문서 재작성

테스트용 원문은 Claude 3.7 Sonnet으로 생성했어요. 실제 사내에서 개발자와 기획자가 작성하는 기술 문서처럼 보이도록, 가상의 제품 기술 문서를 만들어 테스트에 활용했습니다.

기본 템플릿과 스타일 가이드는 카카오 내부에서 실제 사용하는 문서 기준을 그대로 사용했지만, AI가 이해하기 쉽도록 설명과 예시를 약간 보완했어요.

기술 문서 작성 지침과 스타일 가이드는 시스템 인트로덕션(System Introductions)에 입력했고, 기술 문서 템플릿과 테스트용 원문은 첨부 파일로 전달했습니다. 파라미터는 기본값 그대로 두었어요.

테스트 설계는 ChatGPT와 함께했고, 결과 평가는 Claude에게 맡겼어요. 든든한 팀이에요!

첫 번째 테스트 결과

첫 번째 테스트는 스타일 가이드에 맞지 않는 문장과 표현을 고치는 작업이었어요. Claude에게 “스타일 가이드 준수 여부를 평가해 달라”고 요청했더니, 변경된 내용과 부족한 부분을 시각적으로 정리한 보고서를 순식간에 만들어줬어요.

아래는 보고서 내용의 일부에요.

영역	원본 표현	개선된 표현
격식체 사용	“API키를 헤더에 넣으면 됨”	“API 키를 HTTP 요청 헤더에 포함하여 인증해야 합니다.”
종결어미 통일	“근데 레거시 시스템은 쿼리 파라미터로도 받음”	“레거시 시스템과의 호환성을 위해 쿼리 파라미터를 통한 인증도 지원합니다.”
구어체 제거	“이건 좀 복잡한데 분산 환경에서 동시성 제어할때 씀.”	“분산 환경에서 여러 프로세스나 서버 간의 동시 접근을 제어할 때 분산 락을 사용합니다.”
영어 용어 처리	“Redis랑 Memcached”	“Redis(레디스)와 Memcached(멤캐시드)”

두 번째 테스트는 AI가 기술 문서 템플릿에 맞춰 문서 구조를 재구성하고 작성하는 실험이었어요. 기대했던 대로 적절한 템플릿을 선택해 문서를 구성했고, 정보 누락도 없이 중요한 내용을 잘 포함했어요. AI가 기술 문서 작성 지침과 템플릿을 올바르게 이해한 것 같아요.

세 번째 테스트는 템플릿과 스타일 가이드를 모두 지키며 문서를 재작성하는 종합 테스트였어요. 사실상 TW 에이전트가 실제 업무에서 수행해야 하는 작업이기도 하죠. 테스트용 원문도 가장 복잡한 내용이었는데, 역시 AI는 몇 분 안에 멋지게 작업을 마쳤어요.

전반적으로 결과가 나쁘지 않았지만, 문서 길이가 다소 길고 군데군데 읽기 불편한 표현들이 남아 있었어요. 저도 직접 검토하면서 문서가 조금 부담스럽다고 느꼈어요.

두 번째 테스트

첫 번째 테스트를 통해 파악한 주요 개선 포인트는 아래와 같았어요.

AI가 일관된 용어를 사용하도록 가이드가 필요하다.
AI가 가독성을 중시해 문서를 쓰도록 해야 한다.
부족한 정보를 보완할 수 있는 장치가 있어야 한다.

그래서! 저부터 살기 위해(?) 가독성 개선에 집중해 보기로 했어요. 좀 더 읽기 쉬운 문서를 만들 수 있도록 기술 문서 작성 지침을 보완해 동일한 테스트를 다시 진행했습니다.

아래는 그때 추가한 가독성 개선을 위한 지침의 예시입니다.

## 4. 가독성 중심 작성
- **문장 작성 원칙**
    - 한 문장에 하나의 생각만
    - 주어와 동사를 가까이 배치
    - 문장 길이 최대 25단어
    - 불필요한 조사(의, 을, 를, 으로) 제거
- **표현 개선**
    - 어려운 한자어 → 쉬운 우리말
    - 수동태 → 능동태
    - 이중 부정 → 긍정
    - 중복 표현 제거
- **구조 최적화**
    - 단락당 3-5문장
    - 핵심 내용을 앞에 배치
    - 수식어구 최소화
...

두 번째 테스트 결과

가독성 개선 지침을 반영한 문서를 Claude에게 평가하게 했어요. 효과는 굉장했다! 문장은 더 짧고 간결해졌고, 중복 표현은 줄었으며, 정보의 품질도 한층 나아졌어요. Claude의 평가를 종합하면 약 30%의 가독성 개선 효과가 있었다고 하네요.

아래는 가독성 개선 평가 보고서의 일부에요.

역시 보기 좋은 문서가 읽기도 훨씬 편했어요. 하지만, 또 다른 문제가 있었습니다.

품질 vs. 비용

두 테스트의 토큰 사용량을 비교해보니, 두 번째 테스트의 출력 토큰이 거의 2배로 늘었어요. AI가 더 고민을 많이 한 만큼, 추론이 길어졌다는 뜻이겠죠?

문서의 길이는 짧아졌지만, 더 많은 비용이 들게 된 상황이네요. API 사용 요금은 출력이 몇 배로 비싸기 때문에, 출력 토큰을 줄이는 방법을 고민해봐야겠어요.

다음 편 예고

이번 테스트를 통해 최신 AI 모델이 템플릿과 스타일 가이드를 사용해 기술 문서를 작성하는 능력이 꽤 훌륭하다는 걸 알 수 있었어요. 이제 사용자를 위한 TW 에이전트의 인터페이스를 고민할 차례에요.

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

Directed by Yang.me
Written by Talysa.geist
Assisted by Gemini, ChatGPT and Claude

시리즈 모아보기

Vibe-Coding 관련 글 모아보기

AI야, 문서 좀 대신 써 줘 - 3. 짧고 간결하게!