Docx-CLI: AI 에이전트가 Word 문서를 절반의 토큰으로 읽고 편집하는 CLI 도구

TL;DR Highlight

AI 에이전트(Claude, Codex)가 .docx 파일을 직접 XML로 다루는 대신 CLI 명령어로 편집할 수 있게 해주는 도구로, 토큰 사용량을 최대 2.6배 줄이고 문서 파손 없이 작업 성공률을 크게 높인다.

Who Should Read

AI 에이전트를 활용해 Word 문서를 자동으로 작성하거나 편집하는 작업을 구현하려는 개발자, 또는 LLM 에이전트의 토큰 비용과 실패율을 줄이고 싶은 엔지니어.

Core Mechanics

기존 방식대로 에이전트가 .docx를 직접 편집하려면 파일을 unzip해서 OOXML(Word 내부 XML 포맷)을 직접 수정해야 하는데, 이 방식은 토큰을 많이 소모하고 Word가 열 수 없는 손상된 파일을 자주 만들어낸다.
docx-cli는 에이전트에게 XML 대신 '주석이 달린 마크다운 읽기 뷰'와 단순한 CLI 명령어를 제공해서, 에이전트가 OOXML 구조를 직접 추론하지 않아도 된다. 내부적으로는 XML을 직접 수정하되 에이전트에게는 추상화된 인터페이스를 노출하는 방식이다.
텍스트 위치를 'p3:5-20' 같은 안정적인 로케이터(단락 번호 + 문자 오프셋)로 지정하기 때문에, 에이전트가 특정 위치를 정확히 타겟팅할 수 있고 사람은 Word에서 평소처럼 서식이 적용된 문서를 볼 수 있다.
커스텀 스타일, 테마 색상, 임베디드 객체 등 복잡한 서식 요소들이 모두 유지된다. 기존 OOXML 기반 접근법처럼 lossy하게 재생성하는 게 아니라 원본 XML을 in-place로 수정하기 때문이다.
트랙 변경(Track Changes) 모드로 수정 사항을 남기고 댓글을 달 수 있어서, 에이전트가 제안한 수정을 사람이 Word에서 수락/거절하는 워크플로우를 지원한다. 원래 TA 업무 자동화를 위해 시작된 프로젝트다.
A/B 실험 결과: NDA 작성, 인보이스 작성, 이력서 재스타일링, 계약서 레드라인 등 6가지 실제 문서 작업에서 Haiku 모델 기준 docx-cli는 4.3개 작업 성공 vs 기본 방식 0.7개, Sonnet 기준 6.0개 vs 4.0개로 작업 성공률이 크게 높았다.
토큰 사용량도 Haiku 기준 2.4M vs 6.1M(2.6배 절감), Sonnet 기준 1.6M vs 3.6M(2.2배 절감)으로 기본 방식 대비 절반 이하로 줄었다.
기본 방식에서는 Haiku 모델이 매 실행마다 평균 ~1개의 파일을 완전히 손상시켰는데, docx-cli를 사용하면 두 모델 모두 broken document가 0개였다.

Evidence

제작자는 교수인 아내를 위한 TA 에이전트 프로젝트로 시작했다고 밝혔다. 댓글을 달고, track changes 모드로만 편집하고, 문서 구조를 절대 망가뜨리지 않아야 한다는 요구사항에서 출발했으며 이후 테이블, 하이퍼링크, 각주 편집까지 확장됐다고 설명했다.
Claude Code와 Hermes에 바로 적용해봤더니 초기 테스트에서 잘 동작했다는 실사용 경험이 공유됐다. CLI 도구 방식이 실제 일상 사용에서 얼마나 효율적인지를 잘 보여주는 사례라는 평가도 함께 나왔다.
MCP(Model Context Protocol, AI 에이전트가 외부 도구를 사용하는 표준 방식)가 대세가 될 거라고 예상했는데 오히려 CLI 방식이 더 널리 쓰이는 방향으로 가는 것 같다는 의견이 나왔다. 같은 문제를 MCP 서버로 해결하고 있다는 다른 개발자도 댓글을 달았다(vespper.com).
비슷한 목적의 프로젝트들도 댓글에서 소개됐다: iOfficeAI/OfficeCLI, rcarmo/python-office-mcp-server, espressoplease/smalldocs. 이 프로젝트들 간의 토큰 사용량, 정확도, 기능 비교 벤치마크가 있으면 좋겠다는 요청도 있었다.
단순한 텍스트 치환 작업이라면 굳이 LLM이 필요한가, 배치 파일 치환을 안정적으로 해주는 인간 중심 CLI 도구만으로도 충분하지 않냐는 질문이 나왔다. 또한 임베디드 이미지를 XML 내에서 어떻게 처리하는지 묻는 댓글도 있었는데 이는 OOXML 파싱에서 공통적인 pain point라는 언급이 있었다.

How to Apply

AI 에이전트로 계약서, NDA, 인보이스 같은 Word 문서를 자동으로 작성하거나 수정하는 파이프라인을 만드는 경우, 직접 OOXML을 다루는 대신 docx-cli를 에이전트의 도구로 등록하면 토큰 비용을 2배 이상 줄이고 문서 손상 없이 작업을 완료할 수 있다.
Claude나 Codex 에이전트에 docx-cli를 연동할 때는 `.claude-plugin` 또는 `.codex-plugin` 설정 파일이 리포지토리에 포함되어 있으므로, 해당 설정 파일을 그대로 활용하면 별도의 프롬프트 엔지니어링 없이 바로 적용할 수 있다.
비용이 중요한 프로덕션 환경에서 약한 모델(Haiku 등 저렴한 모델)을 사용해야 할 때, 기본 방식으로는 Haiku가 6개 중 0.7개 작업만 성공하지만 docx-cli를 사용하면 4.3개로 성공률이 크게 오르므로, 강한 모델 대신 약한 모델 + docx-cli 조합으로 비용을 낮출 수 있다.
에이전트가 문서를 수정한 결과를 사람이 검토해야 하는 워크플로우라면, track changes 모드와 댓글 기능을 활용해서 에이전트 수정 사항을 Word에서 수락/거절하는 리뷰 프로세스를 그대로 유지할 수 있다.

Code Example

snippet

# 설치
curl -fsSL https://raw.githubusercontent.com/kklimuk/docx-cli/main/install.sh | bash

# 예시: 문서 읽기 (에이전트에게 마크다운 뷰 제공)
docx read document.docx

# 예시: 특정 위치 텍스트 편집 (p3:5-20 = 3번 단락의 5~20번 문자)
docx edit document.docx p3:5-20 "새로운 텍스트"

# 예시: 댓글 추가
docx comment document.docx p3:5-20 "이 부분을 검토해주세요"

Terminology

OOXMLOffice Open XML의 약자로 .docx 파일 내부에서 사용되는 XML 기반 포맷. .docx 파일을 unzip하면 나오는 수십 개의 XML 파일이 OOXML 구조로 이루어져 있다.

Track ChangesWord의 '변경 내용 추적' 기능. 누가 어떤 내용을 수정했는지 표시하고 나중에 수락/거절할 수 있게 해주는 기능이다.

character offset텍스트 내 특정 위치를 가리키는 방법으로, 문자열의 시작부터 몇 번째 문자인지를 숫자로 표현한 것. 예를 들어 'p3:5-20'은 3번 단락의 5번째~20번째 문자를 의미한다.

MCPModel Context Protocol의 약자. AI 에이전트가 외부 도구나 데이터 소스를 표준화된 방식으로 사용할 수 있게 해주는 Anthropic이 만든 프로토콜이다.

lossy데이터를 변환하거나 재생성하는 과정에서 원본 정보 일부가 손실되는 것. 문서에서는 서식, 스타일, 메타데이터 등이 사라지는 상황을 말한다.

redline계약서 등에서 수정 사항을 빨간색으로 표시하는 관행에서 온 용어. Word의 Track Changes 기능으로 구현되며, 제안된 변경 사항을 원본과 함께 보여준다.