DocPilot 에이전트 문서·슬라이드 편집의 설계와 구현

배경과 평가 범위

DocPilot 은 HWP·HWPX·DOCX·PPTX·XLSX 등을 열고 편집하는 데스크톱 앱입니다. 오른쪽 에이전트 패널에서 Claude·Codex 같은 에이전트에 수정을 요청할 수 있습니다. 에이전트는 원본을 직접 수정하지 않고 변경안을 생성하며, 사용자가 원본·수정본·수정 목록을 한 화면에서 비교해 항목별로 적용 여부를 결정한 뒤 확정합니다. 이 방식이 문서와 슬라이드 편집에서 설계대로 동작하는지 확인해야 했습니다.

이 글은 DocPilot 개발에서 확인한 두 가지를 다룹니다. 하나는 에이전트 편집 동작을 어떤 구조로 설계했는지이고, 다른 하나는 DOCX 보고서 1건과 PPTX 발표자료 1건에서 과제 다섯 개를 수행했을 때 구현이 설계대로 동작했는지입니다. 결과는 수정 예시 캡처, 저장 파일 검증, 사용성 문제 9건과 심각도로 정리합니다.

평가의 성격. 이 글은 사용자 연구가 아니라 전문가 평가입니다. 평가자 1명이 앱 개발자 본인이고 시료는 2건, 과제당 반복은 1회입니다. 한계는 마지막 절에 따로 적었습니다.

편집 동작의 설계

에이전틱 편집(agentic editing)은 에이전트가 문서 전용 도구를 호출해 문서를 읽고 고치는 방식입니다. DocPilot 은 이 도구를 로컬 MCP 서버(docstudio-cli)로 제공하며, 설계는 세 가지 원칙으로 정리됩니다.

• 편집 단위는 문단입니다. 에이전트는 문단 id 로 문서를 읽고 문단 텍스트를 교체합니다. 문단 모양과 첫 글자 모양, 표·그림 같은 개체는 엔진이 보존하므로 에이전트가 서식 구조를 다루지 않습니다.
• 편집은 즉시 반영되지 않고 변경안으로 쌓입니다. 편집 모드에서 서버는 원본 파일이 아니라 변경안 파일에 편집을 기록합니다. 사용자가 확정하기 전까지 원본은 바뀌지 않습니다.
• 확정은 사람이 항목 단위로 합니다. 확정한 항목만 원본 형식 그대로 저장되고, 저장 전 첫 사본(.bak)이 남습니다.

동작 흐름

1. 요청. 사용자가 패널에 요청을 입력합니다. 문서 경로·형식·보는 위치·선택한 글·모드가 메시지마다 자동으로 함께 전달됩니다.
2. 도구 호출. 에이전트가 read_paragraphs 로 문서를 읽고 set_paragraph_text·replace_text 로 고친 뒤 save_document 로 변경안을 확정합니다.
3. 변경안 기록. 문단 id 별 수정 내용이 변경안 파일에 쌓입니다. 변경안에는 원본의 크기·수정 시각이 함께 기록되어, 다음 응답이 같은 원본에 이어질 때만 보류 편집을 이어받습니다.
4. 비교 화면 열림. 응답이 끝나면 원본, 수정본(변경 블록에 외곽선), 수정 목록(단어 단위 차이)이 한 화면에 나타납니다.
5. 항목별 선택. 체크 상자, 수정본의 변경 블록 클릭, 방향키와 Space 로 항목마다 적용·제외를 정합니다.
6. 확정. '수정 확인'을 누르면 고른 항목만 원본 바이트에 반영해 파일을 덮어씁니다. 첫 확정 때 .bak 사본을 만듭니다.

도구 구성

도구 구성은 아래 표와 같습니다(도구 설명 기준). 읽기 모드에서는 쓰기 도구가 도구 목록에서 빠지도록 구현되어 있고, 이 동작은 이번 평가에서 시험하지 않았습니다.

비교 화면의 구성

수정본은 원본에 변경안을 미리 적용해 보여 주고, 글이 달라진 문단만 수정 목록에 싣습니다. 글이 그대로인 편집(서식만 바뀌는 편집)은 목록에서 제외하고 원본 상태를 유지합니다. 차이는 단어·기호 단위로 계산해 삭제는 취소선, 삽입은 강조로 표시합니다. 원본과 수정본은 맨 위 문단 기준으로 스크롤을 맞춥니다. 문서는 쪽, 발표자료는 슬라이드를 단위로 위치를 표기합니다. 이번 평가에 쓴 엔진은 Claude(설치된 Claude Code CLI)와 Codex(앱 내장)이고, Gemini 와 Copilot 은 읽기 전용입니다.

평가 방법과 환경

• 시료 DOCX. 1쪽 보고서. 문단 15개와 4x4 표 1개. 구어체('~어요')와 어림 표현이 섞여 있고, 본문의 만족도 평균(4.3점)이 표의 월별 값 평균(4.1점)과 일치하지 않도록 의도적으로 구성했습니다.
• 시료 PPTX. 5장, 문단 20개. 제목에 감탄 부호·이모티콘, 본문에 '~함·~됨' 어미가 있습니다.
• 과제. D1 문체 통일 · D2 수치 정정 · D3 문서 위치 코멘트 2건 · S1 발표자료 전체 정리 · S2 4번 슬라이드 번호 붙이기
• 엔진. Claude(Sonnet 균형, 추론 낮음)로 다섯 과제 전부, Codex(GPT-6.1-Sol)로 D1·S1 을 같은 요청문으로 수행해 변경안 형식이 엔진에 관계없이 같은지 확인했습니다
• 조작. 입력·클릭은 앱 화면을 자동 조작하는 스크립트(WebView2 원격 디버깅)로 수행했습니다.
• 검증. 확정 뒤 저장 파일을 python-docx·python-pptx 로 원본과 대조(문단 텍스트, 글꼴·크기·굵기), XML 에서 텍스트 노드를 비운 구조 비교, 수치 비교
• 기준. Nielsen 의 사용성 휴리스틱 10개, 심각도 0~4(3 이상은 우선 수정 대상)
• 환경. DocPilot 0.1.0(2026-10-28 20:13 빌드), Windows 11, 창 2048x1232 최대화(화면 배율 125%)

구현 결과

과제마다 에이전트가 낸 변경안의 건수와 확정한 건수를 첫째 표에, 설계 결정이 구현에서 어떻게 확인되었는지를 둘째 표에 정리했습니다.

저장 파일 검증

• DOCX. 확정 뒤 바뀐 문단은 9개이고 나머지는 원문과 같았습니다. 글꼴·크기·굵기 변경 0건, 달라진 파일 부분은 word/document.xml 하나입니다. 텍스트 노드를 비운 XML 구조는 xml:space="preserve" 속성이 추가된 것을 제외하면 동일했습니다(Codex 저장본도 같은 결과).
• PPTX. 달라진 부분은 슬라이드 XML 5개이고, 텍스트 노드를 비운 XML 구조는 5개 모두 원본과 같았습니다. 도형 위치·크기·서식 변경은 없었습니다.
• 수치. Codex 의 D1 저장본은 누락되거나 추가된 수치가 0개였고, Claude 의 최종 DOCX 는 요청한 4.3 → 4.1 한 곳뿐이었으며, 최종 PPTX 는 S2 로 추가한 번호 '1.' '2.' '3.' 뿐이었습니다.
• 버리기. '변경안 버리기'를 누른 뒤 원본 파일이 바이트 단위로 동일함을 확인했습니다.

검증하지 못한 범위. 시료에서 고친 문단은 대부분 글자 모양이 하나입니다. 한 문단 안에 굵게·색이 섞인 경우의 보존, 표 셀·텍스트 상자 문단 편집은 검증하지 못했습니다. set_paragraph_text 는 도구 설명상 문단을 첫 글자 모양으로 통일하고, replace_text 는 글자 모양 조각 경계를 넘지 않도록 되어 있습니다.

문서 편집 예시

D1 문체 통일: 9건 제안과 항목별 적용·제외

요청문. 문서 전체를 보고서 문체로 바꿔 줘. '~어요·~해요·~같아요' 같은 구어체는 '~습니다' 체로 통일하고, '확 몰렸는데'·'쯤' 같은 어림 표현은 보고서에 맞게 정리해. 숫자와 표는 그대로 둬.

Claude 는 도구를 11회 호출(문서 읽기 1, 문단 고치기 9, 변경안 확정 1)해 9개 문단을 고쳤고 비교 화면이 자동으로 열렸습니다. 처음 실행한 폴더에서는 에이전트 실행 전에 폴더 신뢰 확인이 한 번 나타납니다.

에이전트는 응답에서 두 가지를 알렸습니다. 첫째는 본문의 만족도 평균 4.3점이 표의 월별 값 평균 약 4.1점과 맞지 않는다는 점이고, 둘째는 '10월 중순'이 작성 기준일(10월 28일)에 이미 지난 시점일 수 있다는 점입니다. 요청에서 숫자를 변경하지 않도록 지정했으므로 수치는 수정하지 않았습니다.

항목별 적용·제외와 저장 결과

이 선택은 조작을 시험하려고 한 것이며 문장의 품질 판단은 아닙니다. 확정 단추를 누르자 비교 화면이 닫히고 "수정 7건을 원본에 반영함"이 표시되었습니다. 저장 뒤 대조에서 제외한 두 문단은 원문 그대로였고 적용한 7개 문단만 바뀌었습니다.

D2 수치 정정: 변경 1건

요청문. 본문에 적힌 사용자 만족도 평균이 표의 월별 값과 맞는지 계산해서 확인하고, 틀렸으면 본문 문장의 수치만 표 기준으로 고쳐 줘. 표와 다른 문단은 건드리지 마.

변경안 1건이 생성되었습니다. 에이전트는 (4.1 + 3.9 + 4.3) ÷ 3 = 4.1 을 계산하고 replace_text 1회 호출로 본문 4.3 을 4.1 로 수정했습니다. 표와 다른 문단은 변경되지 않았습니다. 또한 같은 문장의 "높게 나타났습니다"가 5점 만점의 4.1점에 맞는지는 검토가 필요하다고 덧붙였습니다.

D3 문서 위치 코멘트로 한꺼번에 요청

문단을 선택하면 떠 있는 '코멘트' 단추가 나타납니다. 단추를 눌러 요청을 적으면 문서에 노란 강조와 번호가 붙고, 패널의 요청 목록에 쌓입니다. 두 곳에 코멘트를 단 뒤 '한꺼번에 요청'을 눌렀습니다.

2번 코멘트는 일정 문장을 단정적이지 않은 표현으로 수정해 달라는 요청이었습니다. 에이전트는 응답에서 "앞 문장은 그대로입니다"라고 보고했지만, 비교 화면에서는 앞 문장도 변경되어 있었습니다. 변경된 앞 문장은 D1 에서 제외한 9번 항목의 제안 문구와 같았습니다. 에이전트가 이전 응답에서 낸 제안이 이미 문서에 반영된 것으로 간주했기 때문으로 보입니다. 이러한 불일치를 감지한 것은 에이전트의 보고문이 아니라 비교 화면이었습니다.

수정 전후 문서

슬라이드 편집 예시

S1 발표자료 전체 정리: 14건 제안, 13건 적용

요청문. 발표자료 전체를 정리해 줘. 슬라이드 제목은 명사형으로 쓰고 감탄 부호·이모티콘은 없애. 본문 항목은 '~함·~됨' 같은 구어 어미 없이 한 줄 이내의 명사구로 간결하게 써. 숫자와 레이아웃은 그대로 둬.

Claude 는 슬라이드 5장의 문단 14개를 고쳤습니다. 비교 화면은 슬라이드를 세로로 이어 보여 주고, 수정 목록 항목마다 슬라이드 번호가 붙습니다.

항목 8(슬라이드 3 둘째 불릿)은 제외했습니다. 원문 "접속 오류 안내 문구가 불친절해서 사용자들이 많이 헷갈려 했음"이 "접속 오류 안내 문구의 불명확성"으로 축약되면서 사용자가 혼란을 겪었다는 정보가 누락되었기 때문입니다. 이 제외는 품질 판단에 따른 것입니다. 수정본의 변경 블록을 직접 클릭하여 전환했으며, 수정 목록의 해당 항목도 함께 '제외'로 변경되었습니다.

S2 범위를 지정한 수정: 4번 슬라이드 번호 붙이기

요청문. 슬라이드 4의 세 항목 앞에 '1.', '2.', '3.' 번호를 붙여 줘. 글은 그대로 두고, 다른 슬라이드는 건드리지 마.

변경안 3건이 생성되었으며 수정 목록 항목은 모두 슬라이드 4 에 속했습니다. 범위 지정은 지켜졌습니다. 다만 에이전트는 번호를 자동 번호 매기기 서식이 아니라 일반 텍스트로 입력했다고 보고했습니다. 그 결과 슬라이드에는 글머리표와 번호가 함께 표시됩니다(문제 P5).

수정 전후 슬라이드

슬라이드 3 의 둘째 불릿이 수정 후에도 원문 상태를 유지한 것은 항목 8을 제외했기 때문입니다. 수정 전후 이미지는 저장 파일을 앱의 렌더러로 다시 그린 결과입니다.

변경안 비교 화면의 사용성 문제

양호한 점

• 원본 보호. 확정 전에는 원본 파일이 바뀌지 않습니다. 변경안을 버린 뒤에도 원본이 바이트 단위로 같았습니다.
• 항목별 통제. 체크 상자, 블록 클릭, 방향키·Space 가 같은 결과를 내고, 제외한 항목은 저장본에서 원문 그대로였습니다.
• 서식 보존. DOCX·PPTX 저장본에서 서식 변경 0건, 글 외 구조 동일을 확인했습니다.
• 위치 대응. 같은 번호가 원본·수정본·목록에 붙고, 항목을 고르면 두 문서가 같은 위치로 이동합니다.
• 엔진 무관. Claude 와 Codex 의 변경안을 같은 화면에서 같은 방식으로 검토했습니다.

휴리스틱별 평가

발견한 문제 9건

심각도는 Nielsen 의 0~4 척도(4 치명, 3 중대, 2 경미, 1 미관상)입니다. 이번 평가에서 심각도 4에 해당하는 문제는 발견되지 않았습니다.

정리와 한계

• 설계한 편집 동작이 구현에서 그대로 확인되었습니다. 변경안 분리로 확정 전 원본이 바뀌지 않았고, 항목별 제외가 저장본에 반영되었으며, DOCX·PPTX 저장본에서 서식 변경 0건과 텍스트 외 구조 동일이 두 엔진에서 확인되었습니다.
• 편집 단위가 문단이라 텍스트 교체에는 효과적이나 서식·구조 편집 도구는 제공되지 않습니다. 번호 매기기 요청이 서식이 아닌 일반 텍스트 입력으로 처리되어 글머리표와 번호가 겹쳤습니다(P5).
• 신뢰를 떨어뜨리는 약점은 두 가지입니다. 숫자가 포함된 변경의 차이 표시(P1), 부분 적용 뒤 에이전트와 문서 상태의 불일치(P2)입니다. 이 둘을 먼저 해결하고, 되돌리기(P3)와 문장 재작성 표시(P4)를 이어서 다루는 순서를 제안합니다.
• 검토 기준은 에이전트 보고문이 아니라 비교 화면이어야 합니다. D3 에서 보고문과 실제 변경이 달랐고, 비교 화면만 이를 드러냈습니다.

한계

• 평가자가 앱 개발자 1명이고, 실제 사용자 과제 시험이 아닙니다. 판단과 심각도에 편향이 있을 수 있습니다.
• 시료는 한국어 DOCX 1건·PPTX 1건이고, 과제당 반복은 1회입니다. 모델 출력의 변동은 반영하지 못했습니다.
• 조작은 스크립트가 수행했으므로 사람이 검토할 때의 실수와 망설임은 관찰하지 못했습니다.
• Codex 로 확정까지 수행한 과제는 D1 뿐이며, S1 은 비교 화면까지만 확인한 뒤 변경안을 폐기했습니다.
• 혼합 글자 모양 문단, 표 셀·텍스트 상자 편집, HWPX·XLSX, 좁은 창, 읽기 모드 거절, 반영 실패 상황은 시험하지 않았습니다.

후속 작업

• P1·P2 수정 뒤 같은 과제로 재평가
• 혼합 글자 모양 문단과 표 셀·텍스트 상자 문단으로 서식 보존 시험 확대
• 사용자 3~5명에게 같은 과제를 시켜 차이 표시를 올바로 읽는지 확인

참고 자료

• Nielsen Norman Group, 10 Usability Heuristics for User Interface Design
• Nielsen Norman Group, Severity Ratings for Usability Problems