# docx

> 변경 내용 추적, 주석, 서식 보존, 텍스트 추출을 지원하는 포괄적인 문서 생성, 편집, 분석. Claude가 전문 문서(.docx 파일)를 다음과 같은 작업에 사용해야 할 때: (1) 새 문서 생성, (2) 내용 수정 또는 편집, (3) 변경 내용 추적 작업, (4) 주석 추가, 또는 기타 문서 작업

- Author: chspower1
- Repository: chspower1/skills
- Version: 20260126124047
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/chspower1/skills
- Web: https://mule.run/skillshub/@@chspower1/skills~docx:20260126124047

---

---
name: docx
description: "변경 내용 추적, 주석, 서식 보존, 텍스트 추출을 지원하는 포괄적인 문서 생성, 편집, 분석. Claude가 전문 문서(.docx 파일)를 다음과 같은 작업에 사용해야 할 때: (1) 새 문서 생성, (2) 내용 수정 또는 편집, (3) 변경 내용 추적 작업, (4) 주석 추가, 또는 기타 문서 작업"
license: 독점 라이선스. 전체 약관은 LICENSE.txt 참조
---

# DOCX 생성, 편집, 분석

## 개요

사용자가 .docx 파일을 생성, 편집, 분석하도록 요청할 수 있습니다. .docx 파일은 본질적으로 읽거나 편집할 수 있는 XML 파일과 기타 리소스가 포함된 ZIP 아카이브입니다. 작업에 따라 다양한 도구와 워크플로우를 사용할 수 있습니다.

## 워크플로우 의사 결정 트리

### 내용 읽기/분석
아래 "텍스트 추출" 또는 "원시 XML 접근" 섹션 사용

### 새 문서 생성
"새 Word 문서 생성" 워크플로우 사용

### 기존 문서 편집
- **본인의 문서 + 간단한 변경**
  "기본 OOXML 편집" 워크플로우 사용

- **타인의 문서**
  **"레드라인 워크플로우"** 사용 (권장 기본값)

- **법률, 학술, 비즈니스 또는 정부 문서**
  **"레드라인 워크플로우"** 사용 (필수)

## 내용 읽기 및 분석

### 텍스트 추출
문서의 텍스트 내용만 읽어야 한다면 pandoc을 사용하여 문서를 마크다운으로 변환하세요. Pandoc은 문서 구조 보존에 우수한 지원을 제공하며 변경 내용 추적을 표시할 수 있습니다:

```bash
# 변경 내용 추적과 함께 문서를 마크다운으로 변환
pandoc --track-changes=all path-to-file.docx -o output.md
# 옵션: --track-changes=accept/reject/all
```

### 원시 XML 접근
다음을 위해 원시 XML 접근이 필요합니다: 주석, 복잡한 서식, 문서 구조, 포함된 미디어, 메타데이터. 이러한 기능 중 하나라도 필요하면 문서를 풀고 원시 XML 내용을 읽어야 합니다.

#### 파일 풀기
`python ooxml/scripts/unpack.py <office_file> <output_directory>`

#### 주요 파일 구조
* `word/document.xml` - 주요 문서 내용
* `word/comments.xml` - document.xml에 참조된 주석
* `word/media/` - 포함된 이미지 및 미디어 파일
* 변경 내용 추적은 `<w:ins>` (삽입) 및 `<w:del>` (삭제) 태그 사용

## 새 Word 문서 생성

새 Word 문서를 처음부터 생성할 때는 JavaScript/TypeScript로 Word 문서를 생성할 수 있는 **docx-js**를 사용하세요.

### 워크플로우
1. **필수 - 전체 파일 읽기**: [`docx-js.md`](docx-js.md) (~500줄)를 처음부터 끝까지 완전히 읽으세요. **이 파일을 읽을 때 범위 제한을 설정하지 마세요.** 문서 생성을 진행하기 전에 상세한 구문, 중요한 서식 규칙, 모범 사례를 위해 전체 파일 내용을 읽으세요.
2. Document, Paragraph, TextRun 컴포넌트를 사용하여 JavaScript/TypeScript 파일 생성 (모든 의존성이 설치되어 있다고 가정하지만, 그렇지 않은 경우 아래 의존성 섹션 참조)
3. Packer.toBuffer()를 사용하여 .docx로 내보내기

## 기존 Word 문서 편집

기존 Word 문서를 편집할 때는 **Document 라이브러리** (OOXML 조작을 위한 Python 라이브러리)를 사용하세요. 이 라이브러리는 인프라 설정을 자동으로 처리하고 문서 조작을 위한 메서드를 제공합니다. 복잡한 시나리오의 경우 라이브러리를 통해 기본 DOM에 직접 접근할 수 있습니다.

### 워크플로우
1. **필수 - 전체 파일 읽기**: [`ooxml.md`](ooxml.md) (~600줄)를 처음부터 끝까지 완전히 읽으세요. **이 파일을 읽을 때 범위 제한을 설정하지 마세요.** Document 라이브러리 API와 문서 파일 직접 편집을 위한 XML 패턴을 위해 전체 파일 내용을 읽으세요.
2. 문서 풀기: `python ooxml/scripts/unpack.py <office_file> <output_directory>`
3. Document 라이브러리를 사용하여 Python 스크립트 생성 및 실행 (ooxml.md의 "Document Library" 섹션 참조)
4. 최종 문서 패킹: `python ooxml/scripts/pack.py <input_directory> <office_file>`

Document 라이브러리는 일반적인 작업을 위한 고수준 메서드와 복잡한 시나리오를 위한 직접 DOM 접근을 모두 제공합니다.

## 문서 검토를 위한 레드라인 워크플로우

이 워크플로우를 사용하면 OOXML에서 구현하기 전에 마크다운을 사용하여 포괄적인 변경 내용 추적을 계획할 수 있습니다. **중요**: 완전한 변경 내용 추적을 위해 모든 변경 사항을 체계적으로 구현해야 합니다.

**배치 전략**: 관련 변경 사항을 3-10개의 변경으로 그룹화하세요. 이렇게 하면 효율성을 유지하면서 디버깅을 관리할 수 있습니다. 다음으로 이동하기 전에 각 배치를 테스트하세요.

**원칙: 최소한의 정확한 편집**
변경 내용 추적을 구현할 때 실제로 변경된 텍스트만 표시하세요. 변경되지 않은 텍스트를 반복하면 편집 검토가 어려워지고 전문적이지 않게 보입니다. 대체를 다음으로 분해하세요: [변경되지 않은 텍스트] + [삭제] + [삽입] + [변경되지 않은 텍스트]. 원본의 `<w:r>` 요소를 추출하고 재사용하여 변경되지 않은 텍스트의 원래 run의 RSID를 보존하세요.

예시 - 문장에서 "30일"을 "60일"로 변경:
```python
# 나쁨 - 전체 문장 대체
'<w:del><w:r><w:delText>기간은 30일입니다.</w:delText></w:r></w:del><w:ins><w:r><w:t>기간은 60일입니다.</w:t></w:r></w:ins>'

# 좋음 - 변경된 부분만 표시, 변경되지 않은 텍스트는 원래 <w:r> 보존
'<w:r w:rsidR="00AB12CD"><w:t>기간은 </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t>일입니다.</w:t></w:r>'
```

### 변경 내용 추적 워크플로우

1. **마크다운 표현 가져오기**: 변경 내용 추적이 보존된 상태로 문서를 마크다운으로 변환:
   ```bash
   pandoc --track-changes=all path-to-file.docx -o current.md
   ```

2. **변경 사항 식별 및 그룹화**: 문서를 검토하고 필요한 모든 변경 사항을 식별하여 논리적 배치로 구성:

   **위치 찾기 방법** (XML에서 변경 사항 찾기용):
   - 섹션/제목 번호 (예: "섹션 3.2", "제4조")
   - 번호가 매겨진 경우 단락 식별자
   - 고유한 주변 텍스트가 있는 grep 패턴
   - 문서 구조 (예: "첫 번째 단락", "서명 블록")
   - **마크다운 줄 번호를 사용하지 마세요** - XML 구조에 매핑되지 않음

   **배치 구성** (배치당 3-10개의 관련 변경 그룹화):
   - 섹션별: "배치 1: 섹션 2 수정", "배치 2: 섹션 5 업데이트"
   - 유형별: "배치 1: 날짜 수정", "배치 2: 당사자 이름 변경"
   - 복잡도별: 간단한 텍스트 대체로 시작한 다음 복잡한 구조 변경 처리
   - 순차적: "배치 1: 1-3페이지", "배치 2: 4-6페이지"

3. **문서 읽기 및 풀기**:
   - **필수 - 전체 파일 읽기**: [`ooxml.md`](ooxml.md) (~600줄)를 처음부터 끝까지 완전히 읽으세요. **이 파일을 읽을 때 범위 제한을 설정하지 마세요.** "Document Library" 및 "Tracked Change Patterns" 섹션에 특히 주의하세요.
   - **문서 풀기**: `python ooxml/scripts/unpack.py <file.docx> <dir>`
   - **제안된 RSID 참고**: unpack 스크립트는 변경 내용 추적에 사용할 RSID를 제안합니다. 4b 단계에서 사용할 이 RSID를 복사하세요.

4. **배치로 변경 사항 구현**: 변경 사항을 논리적으로 그룹화하고(섹션별, 유형별 또는 근접성별) 단일 스크립트에서 함께 구현하세요. 이 접근 방식은:
   - 디버깅 용이 (더 작은 배치 = 오류 격리 용이)
   - 점진적 진행 가능
   - 효율성 유지 (3-10개 변경의 배치 크기가 적합)

   **권장 배치 그룹**:
   - 문서 섹션별 (예: "섹션 3 변경", "정의", "해지 조항")
   - 변경 유형별 (예: "날짜 변경", "당사자 이름 업데이트", "법률 용어 대체")
   - 근접성별 (예: "1-3페이지 변경", "문서 전반부 변경")

   각 관련 변경 배치에 대해:

   **a. 텍스트를 XML에 매핑**: `word/document.xml`에서 텍스트를 grep하여 텍스트가 `<w:r>` 요소에 어떻게 분할되어 있는지 확인.

   **b. 스크립트 생성 및 실행**: `get_node`를 사용하여 노드를 찾고, 변경 사항을 구현한 다음 `doc.save()`. ooxml.md의 **"Document Library"** 섹션에서 패턴 참조.

   **참고**: 스크립트를 작성하기 직전에 항상 `word/document.xml`을 grep하여 현재 줄 번호를 가져오고 텍스트 내용을 확인하세요. 각 스크립트 실행 후 줄 번호가 변경됩니다.

5. **문서 패킹**: 모든 배치가 완료되면 풀린 디렉토리를 다시 .docx로 변환:
   ```bash
   python ooxml/scripts/pack.py unpacked reviewed-document.docx
   ```

6. **최종 검증**: 전체 문서에 대한 포괄적인 검사 수행:
   - 최종 문서를 마크다운으로 변환:
     ```bash
     pandoc --track-changes=all reviewed-document.docx -o verification.md
     ```
   - 모든 변경 사항이 올바르게 적용되었는지 확인:
     ```bash
     grep "원래 문구" verification.md  # 찾으면 안 됨
     grep "대체 문구" verification.md  # 찾아야 함
     ```
   - 의도하지 않은 변경 사항이 도입되지 않았는지 확인


## 문서를 이미지로 변환

Word 문서를 시각적으로 분석하려면 두 단계 프로세스를 사용하여 이미지로 변환하세요:

1. **DOCX를 PDF로 변환**:
   ```bash
   soffice --headless --convert-to pdf document.docx
   ```

2. **PDF 페이지를 JPEG 이미지로 변환**:
   ```bash
   pdftoppm -jpeg -r 150 document.pdf page
   ```
   이렇게 하면 `page-1.jpg`, `page-2.jpg` 등의 파일이 생성됩니다.

옵션:
- `-r 150`: 해상도를 150 DPI로 설정 (품질/크기 균형 조정)
- `-jpeg`: JPEG 형식 출력 (선호하는 경우 PNG는 `-png` 사용)
- `-f N`: 변환할 첫 번째 페이지 (예: `-f 2`는 2페이지부터 시작)
- `-l N`: 변환할 마지막 페이지 (예: `-l 5`는 5페이지에서 중지)
- `page`: 출력 파일의 접두사

특정 범위 예시:
```bash
pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # 2-5페이지만 변환
```

## 코드 스타일 가이드라인
**중요**: DOCX 작업을 위한 코드 생성 시:
- 간결한 코드 작성
- 장황한 변수명과 중복 작업 피하기
- 불필요한 print 문 피하기

## 의존성

필수 의존성 (사용 불가능한 경우 설치):

- **pandoc**: `sudo apt-get install pandoc` (텍스트 추출용)
- **docx**: `npm install -g docx` (새 문서 생성용)
- **LibreOffice**: `sudo apt-get install libreoffice` (PDF 변환용)
- **Poppler**: `sudo apt-get install poppler-utils` (PDF를 이미지로 변환하는 pdftoppm용)
- **defusedxml**: `pip install defusedxml` (보안 XML 파싱용)