From 261d4e1e3d51e25742074c151dd9dc544d8d57bb Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 30 Jan 2026 20:28:46 +0900 Subject: [PATCH 1/6] =?UTF-8?q?skill:=20Confluence=20MDX=20PR=20=EC=88=98?= =?UTF-8?q?=EC=A0=95=20=EA=B0=80=EC=9D=B4=EB=93=9C=EB=9D=BC=EC=9D=B8=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - generate-mdx-from-confluence.yml 워크플로우에서 생성된 PR 수정 절차를 문서화합니다. - 이미지 첨부, 영어/일본어 번역, Skeleton MDX 검증 절차를 포함합니다. - 코드 블록 일치 규칙 및 체크리스트를 제공합니다. Co-Authored-By: Claude Opus 4.5 --- .claude/skills/confluence-pr-update.md | 190 +++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 .claude/skills/confluence-pr-update.md diff --git a/.claude/skills/confluence-pr-update.md b/.claude/skills/confluence-pr-update.md new file mode 100644 index 00000000..345b6aa3 --- /dev/null +++ b/.claude/skills/confluence-pr-update.md @@ -0,0 +1,190 @@ +# Confluence MDX PR 수정 가이드라인 + +## 개요 + +이 skill은 `generate-mdx-from-confluence.yml` GitHub Actions 워크플로우에서 생성된 PR을 수정하는 작업 절차를 설명합니다. + +## 배경 + +- **워크플로우**: `.github/workflows/generate-mdx-from-confluence.yml` +- **목적**: Confluence에서 한국어 MDX 문서를 자동 동기화 +- **PR 브랜치 형식**: `mdx/confluence-updates-YYYYMMDD-HHMMSS` +- **추가 작업 필요**: 이미지 첨부 확인, 영어/일본어 번역 + +## 전체 워크플로우 + +### Step 1: PR 브랜치 체크아웃 + +```bash +# PR 브랜치 확인 및 체크아웃 +git fetch origin +git checkout mdx/confluence-updates-YYYYMMDD-HHMMSS +``` + +### Step 2: Confluence 동기화 재실행 (이미지 포함) + +워크플로우에서 `--recent` 옵션만 사용한 경우, 이미지를 포함하려면 로컬에서 재실행합니다: + +```bash +cd confluence-mdx +source venv/bin/activate + +# 이미지 첨부 포함하여 재실행 +python3 bin/pages_of_confluence.py --recent --attachments +``` + +**참고**: `--attachments` 옵션은 Confluence 페이지의 첨부 이미지를 `public/` 디렉토리에 복사합니다. + +### Step 3: 변경된 한국어 문서 확인 + +```bash +# 한국어 문서 변경 확인 +git diff src/content/ko/ + +# 새로 추가된 이미지 확인 +git status public/ +``` + +### Step 4: 영어/일본어 번역 수행 + +변경된 한국어 문서에 대응하는 영어/일본어 파일을 번역합니다. + +**파일 경로 규칙**: +- 한국어: `src/content/ko/path/to/file.mdx` +- 영어: `src/content/en/path/to/file.mdx` +- 일본어: `src/content/ja/path/to/file.mdx` + +**번역 지침**: +- [docs/translation.md](/docs/translation.md)의 번역 규칙 준수 +- [.claude/skills/translation.md](/.claude/skills/translation.md) 참조 + +### Step 5: Skeleton MDX 비교로 검증 + +번역 후 구조 일치를 확인합니다: + +```bash +cd confluence-mdx +source venv/bin/activate + +# 전체 비교 +python3 bin/mdx_to_skeleton.py --recursive --max-diff=10 + +# 특정 파일만 비교 +python3 bin/mdx_to_skeleton.py ../src/content/en/path/to/file.mdx +``` + +**상세**: [.claude/skills/mdx-skeleton-comparison.md](/.claude/skills/mdx-skeleton-comparison.md) + +### Step 6: 코드 블록 일치 확인 + +**중요**: 코드 블록 내용은 한국어/영어/일본어 문서에서 **동일**해야 합니다. + +```markdown +# 잘못된 예 - 코드 블록 내 주석을 번역함 +```bash +# クラスタアクセス確認 ← 일본어로 번역 (잘못됨) +kubectl get nodes +``` + +# 올바른 예 - 코드 블록 내용 동일 +```bash +# Verify cluster access ← 원본 그대로 유지 +kubectl get nodes +``` +``` + +코드 블록 내 주석은 번역하지 않고 원본(주로 영어) 그대로 유지합니다. + +### Step 7: 후행 공백 줄 제거 + +파일 끝에 불필요한 빈 줄이 있으면 제거합니다. 한국어 원본과 동일한 형식을 유지합니다. + +### Step 8: 변경사항 커밋 + +```bash +# 변경사항 확인 +git status +git diff + +# 스테이징 및 커밋 +git add src/content/en/ src/content/ja/ public/ +git commit -m "$(cat <<'EOF' +mdx: 영어/일본어 번역 추가 (한국어 문서 변경 대응) + +- 한국어 문서 변경에 대응하는 영어/일본어 번역을 추가합니다. +- Skeleton MDX 비교로 구조 일치를 확인합니다. + +Co-Authored-By: Claude Opus 4.5 +EOF +)" + +# 푸시 +git push origin HEAD +``` + +### Step 9: PR 제목/설명 업데이트 (필요 시) + +```bash +# PR 제목 업데이트 +gh pr edit --title "mdx: <변경 내용 요약>" + +# PR 설명 업데이트 +gh pr edit --body "$(cat <<'EOF' +## Summary +- Confluence에서 한국어 MDX 문서를 동기화합니다. +- 영어/일본어 번역을 추가합니다. + +## Changes +- `src/content/ko/path/to/file.mdx`: 변경 내용 +- `src/content/en/path/to/file.mdx`: 영어 번역 +- `src/content/ja/path/to/file.mdx`: 일본어 번역 + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +EOF +)" +``` + +## 체크리스트 + +- [ ] PR 브랜치 체크아웃 +- [ ] `--attachments` 옵션으로 이미지 포함 확인 +- [ ] 영어 번역 완료 +- [ ] 일본어 번역 완료 +- [ ] Skeleton MDX 비교 통과 +- [ ] 코드 블록 내용 일치 확인 +- [ ] 후행 공백 줄 제거 +- [ ] 커밋 및 푸시 +- [ ] PR 제목/설명 업데이트 + +## 일반적인 문제 해결 + +### 이미지가 누락된 경우 + +```bash +# 이미지 포함하여 재실행 +cd confluence-mdx +python3 bin/pages_of_confluence.py --recent --attachments + +# 새 이미지 확인 +git status public/ +``` + +### Skeleton 불일치가 발생한 경우 + +1. 불일치 내용 확인: + ```bash + python3 bin/mdx_to_skeleton.py ../src/content/en/path/to/file.mdx + ``` +2. 번역 파일의 구조를 한국어 원본과 동일하게 수정 +3. 공백, 줄 바꿈을 원본과 정확히 일치시킴 + +### 코드 블록 내 주석이 번역된 경우 + +코드 블록 내용을 한국어 원본(또는 영어 원본)과 동일하게 복원합니다. + +## 관련 문서 + +- **Confluence MDX 변환**: [.claude/skills/confluence-mdx.md](/.claude/skills/confluence-mdx.md) +- **Skeleton MDX 비교**: [.claude/skills/mdx-skeleton-comparison.md](/.claude/skills/mdx-skeleton-comparison.md) +- **번역 가이드라인**: [.claude/skills/translation.md](/.claude/skills/translation.md) +- **한국어→영어/일본어 동기화**: [.claude/skills/sync-ko-to-en-ja.md](/.claude/skills/sync-ko-to-en-ja.md) From bb49e95482e9136c47f53bdea3904eb264fc338c Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 30 Jan 2026 20:30:29 +0900 Subject: [PATCH 2/6] =?UTF-8?q?fix(.claude):=20=EC=B2=A8=EB=B6=80=ED=8C=8C?= =?UTF-8?q?=EC=9D=BC=20=EB=88=84=EB=9D=BD=20=EC=8B=9C=EC=97=90=EB=A7=8C=20?= =?UTF-8?q?=EB=8F=99=EA=B8=B0=ED=99=94=20=EC=9E=AC=EC=8B=A4=ED=96=89?= =?UTF-8?q?=ED=95=98=EB=8F=84=EB=A1=9D=20=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Step 2를 조건부 실행으로 변경합니다. - MDX에서 참조하는 첨부파일이 존재하지 않는 경우에만 동기화를 재실행합니다. Co-Authored-By: Claude Opus 4.5 --- .claude/skills/confluence-pr-update.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/.claude/skills/confluence-pr-update.md b/.claude/skills/confluence-pr-update.md index 345b6aa3..c56d38c6 100644 --- a/.claude/skills/confluence-pr-update.md +++ b/.claude/skills/confluence-pr-update.md @@ -21,9 +21,19 @@ git fetch origin git checkout mdx/confluence-updates-YYYYMMDD-HHMMSS ``` -### Step 2: Confluence 동기화 재실행 (이미지 포함) +### Step 2: 첨부파일 누락 확인 및 동기화 재실행 -워크플로우에서 `--recent` 옵션만 사용한 경우, 이미지를 포함하려면 로컬에서 재실행합니다: +MDX 파일에서 참조하는 이미지가 `public/` 디렉토리에 존재하는지 확인합니다. **첨부파일이 누락된 경우에만** 로컬에서 동기화를 재실행합니다. + +```bash +# 변경된 MDX 파일에서 참조하는 이미지 경로 확인 +# 예:
+ +# 해당 이미지가 public/ 디렉토리에 존재하는지 확인 +ls public/path/to/image.png +``` + +**첨부파일이 누락된 경우에만** 다음을 실행합니다: ```bash cd confluence-mdx @@ -33,7 +43,7 @@ source venv/bin/activate python3 bin/pages_of_confluence.py --recent --attachments ``` -**참고**: `--attachments` 옵션은 Confluence 페이지의 첨부 이미지를 `public/` 디렉토리에 복사합니다. +**참고**: `--attachments` 옵션은 Confluence 페이지의 첨부 이미지를 `public/` 디렉토리에 복사합니다. 이미 모든 첨부파일이 존재하면 이 단계를 건너뜁니다. ### Step 3: 변경된 한국어 문서 확인 @@ -147,7 +157,7 @@ EOF ## 체크리스트 - [ ] PR 브랜치 체크아웃 -- [ ] `--attachments` 옵션으로 이미지 포함 확인 +- [ ] 첨부파일 누락 시 `--attachments` 옵션으로 동기화 재실행 - [ ] 영어 번역 완료 - [ ] 일본어 번역 완료 - [ ] Skeleton MDX 비교 통과 From 71b77264439afb05775cf0020d5986b859786359 Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 30 Jan 2026 20:31:24 +0900 Subject: [PATCH 3/6] =?UTF-8?q?fix(.claude):=20=EC=BD=94=EB=93=9C=20?= =?UTF-8?q?=EB=B8=94=EB=A1=9D=20=EC=A4=91=EC=B2=A9=20=EB=A7=88=ED=81=AC?= =?UTF-8?q?=EB=8B=A4=EC=9A=B4=20=EC=98=A4=EB=A5=98=20=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 중첩된 코드 블록을 별도의 예시로 분리합니다. Co-Authored-By: Claude Opus 4.5 --- .claude/skills/confluence-pr-update.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/skills/confluence-pr-update.md b/.claude/skills/confluence-pr-update.md index c56d38c6..d9ff13bb 100644 --- a/.claude/skills/confluence-pr-update.md +++ b/.claude/skills/confluence-pr-update.md @@ -89,19 +89,19 @@ python3 bin/mdx_to_skeleton.py ../src/content/en/path/to/file.mdx **중요**: 코드 블록 내용은 한국어/영어/일본어 문서에서 **동일**해야 합니다. -```markdown -# 잘못된 예 - 코드 블록 내 주석을 번역함 +**잘못된 예** - 코드 블록 내 주석을 번역함: + ```bash # クラスタアクセス確認 ← 일본어로 번역 (잘못됨) kubectl get nodes ``` -# 올바른 예 - 코드 블록 내용 동일 +**올바른 예** - 코드 블록 내용 동일: + ```bash # Verify cluster access ← 원본 그대로 유지 kubectl get nodes ``` -``` 코드 블록 내 주석은 번역하지 않고 원본(주로 영어) 그대로 유지합니다. From a6883140d8739b0a4a998850b22c61639e20a2a0 Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 30 Jan 2026 20:32:39 +0900 Subject: [PATCH 4/6] =?UTF-8?q?fix(.claude):=20=EB=9D=BC=EC=9D=B8=20?= =?UTF-8?q?=EC=88=98=20=EB=B0=8F=20=EB=B9=88=20=EC=A4=84=20=EC=9C=84?= =?UTF-8?q?=EC=B9=98=20=EC=9D=BC=EC=B9=98=EB=A5=BC=20=ED=95=84=EC=88=98=20?= =?UTF-8?q?=EC=9A=94=EA=B1=B4=EC=9C=BC=EB=A1=9C=20=EB=AA=85=EC=8B=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 영어/일본어 번역 파일이 한국어 원본과 라인 수, 빈 줄 위치가 정확히 일치해야 함을 명시합니다. - 라인 수 비교 명령어 예시를 추가합니다. Co-Authored-By: Claude Opus 4.5 --- .claude/skills/confluence-pr-update.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/.claude/skills/confluence-pr-update.md b/.claude/skills/confluence-pr-update.md index d9ff13bb..e61bcb09 100644 --- a/.claude/skills/confluence-pr-update.md +++ b/.claude/skills/confluence-pr-update.md @@ -105,9 +105,22 @@ kubectl get nodes 코드 블록 내 주석은 번역하지 않고 원본(주로 영어) 그대로 유지합니다. -### Step 7: 후행 공백 줄 제거 +### Step 7: 라인 수 및 빈 줄 위치 일치 (필수) -파일 끝에 불필요한 빈 줄이 있으면 제거합니다. 한국어 원본과 동일한 형식을 유지합니다. +**필수 요건**: 영어/일본어 번역 파일은 한국어 원본과 **라인 수와 빈 줄 위치가 정확히 일치**해야 합니다. + +- 파일의 총 라인 수가 동일해야 합니다. +- 빈 줄의 위치가 동일해야 합니다. +- 파일 끝의 빈 줄 유무도 한국어 원본과 동일해야 합니다. + +```bash +# 라인 수 비교 +wc -l src/content/ko/path/to/file.mdx +wc -l src/content/en/path/to/file.mdx +wc -l src/content/ja/path/to/file.mdx +``` + +라인 수가 다르면 빈 줄을 추가하거나 제거하여 한국어 원본과 일치시킵니다. ### Step 8: 변경사항 커밋 From 569f86a09993f455ce3c58c8864936c12599e592 Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 30 Jan 2026 20:33:43 +0900 Subject: [PATCH 5/6] =?UTF-8?q?docs(.claude):=20README=EC=97=90=20?= =?UTF-8?q?=EB=88=84=EB=9D=BD=EB=90=9C=20Skill=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - confluence-pr-update.md: Confluence MDX PR 수정 워크플로우 - sync-ko-to-en-ja.md: 한국어 MDX 변경사항을 영어/일본어에 동기화 Co-Authored-By: Claude Opus 4.5 --- .claude/skills/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.claude/skills/README.md b/.claude/skills/README.md index 6fa64f5d..7b09e1c3 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -8,6 +8,8 @@ - **documentation.md** - MDX 문서 파일 작성 및 편집 가이드라인 - **translation.md** - 다국어 번역 가이드라인 (ko → en, ja) - **confluence-mdx.md** - Confluence에서 MDX로 변환 워크플로우 +- **confluence-pr-update.md** - Confluence MDX PR 수정 워크플로우 +- **sync-ko-to-en-ja.md** - 한국어 MDX 변경사항을 영어/일본어에 동기화 - **mdx-skeleton-comparison.md** - 스켈레톤 비교를 통한 번역 일관성 검증 ### 개발 Skills @@ -21,6 +23,8 @@ |-------|----------| | translation.md | [docs/translation.md](/docs/translation.md) | | confluence-mdx.md | [confluence-mdx/README.md](/confluence-mdx/README.md) | +| confluence-pr-update.md | confluence-mdx.md, translation.md, mdx-skeleton-comparison.md | +| sync-ko-to-en-ja.md | [docs/translation.md](/docs/translation.md) | | mdx-skeleton-comparison.md | [docs/translation.md](/docs/translation.md) | | documentation.md | [docs/DEVELOPMENT.md](/docs/DEVELOPMENT.md) | | commit.md (commands) | [docs/commit-pr-guide.md](/docs/commit-pr-guide.md) (Commit 및 PR 작성) | From 44860b0d33c6377484d165b756aa2fb598a703fb Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 30 Jan 2026 20:35:27 +0900 Subject: [PATCH 6/6] =?UTF-8?q?fix(.claude):=20=EB=B9=88=20=EC=A4=84=20?= =?UTF-8?q?=EA=B2=80=EC=A6=9D=EC=9D=84=20Skeleton=20MDX=20=EB=B9=84?= =?UTF-8?q?=EA=B5=90=20=EC=84=B9=EC=85=98=EC=9C=BC=EB=A1=9C=20=ED=86=B5?= =?UTF-8?q?=ED=95=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Step 7 (빈 줄 별도 섹션) 제거 - Step 5에서 Skeleton MDX 비교가 빈 줄 차이도 감지함을 명시 - 빈 줄 차이를 무시하지 말 것을 강조 - Step 번호 재정렬 (8→7, 9→8) Co-Authored-By: Claude Opus 4.5 --- .claude/skills/confluence-pr-update.md | 26 +++++--------------------- 1 file changed, 5 insertions(+), 21 deletions(-) diff --git a/.claude/skills/confluence-pr-update.md b/.claude/skills/confluence-pr-update.md index e61bcb09..aa7607a3 100644 --- a/.claude/skills/confluence-pr-update.md +++ b/.claude/skills/confluence-pr-update.md @@ -83,6 +83,8 @@ python3 bin/mdx_to_skeleton.py --recursive --max-diff=10 python3 bin/mdx_to_skeleton.py ../src/content/en/path/to/file.mdx ``` +**중요**: Skeleton MDX 비교는 빈 줄의 누락/추가 차이도 감지합니다. 영어/일본어 번역 파일은 한국어 원본과 **라인 수와 빈 줄 위치가 정확히 일치**해야 합니다. Skeleton 비교에서 발견된 빈 줄 차이를 무시하지 마세요. + **상세**: [.claude/skills/mdx-skeleton-comparison.md](/.claude/skills/mdx-skeleton-comparison.md) ### Step 6: 코드 블록 일치 확인 @@ -105,24 +107,7 @@ kubectl get nodes 코드 블록 내 주석은 번역하지 않고 원본(주로 영어) 그대로 유지합니다. -### Step 7: 라인 수 및 빈 줄 위치 일치 (필수) - -**필수 요건**: 영어/일본어 번역 파일은 한국어 원본과 **라인 수와 빈 줄 위치가 정확히 일치**해야 합니다. - -- 파일의 총 라인 수가 동일해야 합니다. -- 빈 줄의 위치가 동일해야 합니다. -- 파일 끝의 빈 줄 유무도 한국어 원본과 동일해야 합니다. - -```bash -# 라인 수 비교 -wc -l src/content/ko/path/to/file.mdx -wc -l src/content/en/path/to/file.mdx -wc -l src/content/ja/path/to/file.mdx -``` - -라인 수가 다르면 빈 줄을 추가하거나 제거하여 한국어 원본과 일치시킵니다. - -### Step 8: 변경사항 커밋 +### Step 7: 변경사항 커밋 ```bash # 변경사항 확인 @@ -145,7 +130,7 @@ EOF git push origin HEAD ``` -### Step 9: PR 제목/설명 업데이트 (필요 시) +### Step 8: PR 제목/설명 업데이트 (필요 시) ```bash # PR 제목 업데이트 @@ -173,9 +158,8 @@ EOF - [ ] 첨부파일 누락 시 `--attachments` 옵션으로 동기화 재실행 - [ ] 영어 번역 완료 - [ ] 일본어 번역 완료 -- [ ] Skeleton MDX 비교 통과 +- [ ] Skeleton MDX 비교 통과 (빈 줄 차이 포함) - [ ] 코드 블록 내용 일치 확인 -- [ ] 후행 공백 줄 제거 - [ ] 커밋 및 푸시 - [ ] PR 제목/설명 업데이트