From 4941bf520eebbc04065c4ec72fbdcd675e42dd6e Mon Sep 17 00:00:00 2001 From: JK Date: Thu, 25 Jun 2026 16:43:37 +0900 Subject: [PATCH] =?UTF-8?q?skill:=20Confluence=20Space=20sync=20=EC=9E=91?= =?UTF-8?q?=EC=97=85=20=EC=A0=88=EC=B0=A8=EB=A5=BC=20=EC=B6=94=EA=B0=80?= =?UTF-8?q?=ED=95=A9=EB=8B=88=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Confluence Space sync 기반 MDX 업데이트 작업을 재사용 가능한 skill 절차로 정리합니다. - branch 생성부터 Confluence fetch/convert, 한국어 PR 작성, en/ja 번역까지의 순서를 추가합니다. - 관련 skill과 CLI 문서 링크를 추가합니다. - Skeleton MDX 비교 검증 명령과 PR 갱신 단계를 명시합니다. - src/content 로컬 변경사항을 버리고 깨끗하게 재시작하는 문제해결 절차를 추가합니다. ## Test plan - [x] python3 /Users/jk/.codex-gpt15/skills/.system/skill-creator/scripts/quick_validate.py /Users/jk/workspace/querypie-docs/.agents/skills/confluence-mdx - [x] git diff --check -- ../.agents/skills/confluence-mdx/SKILL.md 🤖 Generated with Codex --- .agents/skills/confluence-mdx/SKILL.md | 115 ++++++++++++++++++++++++- 1 file changed, 114 insertions(+), 1 deletion(-) diff --git a/.agents/skills/confluence-mdx/SKILL.md b/.agents/skills/confluence-mdx/SKILL.md index 038e8f930..30c8ac09e 100644 --- a/.agents/skills/confluence-mdx/SKILL.md +++ b/.agents/skills/confluence-mdx/SKILL.md @@ -1,6 +1,6 @@ --- name: confluence-mdx -description: "Confluence 문서를 QueryPie MDX 콘텐츠로 변환하거나 변환 결과를 검증할 때 사용합니다." +description: "Confluence 문서를 QueryPie MDX 콘텐츠로 변환하거나 Confluence Space sync로 한국어 MDX를 갱신하고 영어/일본어 번역, Skeleton MDX 비교 검증, PR 갱신까지 수행할 때 사용합니다." --- # Confluence에서 MDX로 변환 가이드라인 @@ -11,6 +11,19 @@ description: "Confluence 문서를 QueryPie MDX 콘텐츠로 변환하거나 변 **상세 사용법**: [confluence-mdx/README.md](/confluence-mdx/README.md)를 반드시 참조하세요. +## 관련 Skill 및 CLI 문서 + +- **Confluence 자동 동기화 PR 보정**: [confluence-pr-update](../confluence-pr-update/SKILL.md) +- **번역 지침**: [translation](../translation/SKILL.md), [docs/translation.md](/docs/translation.md) +- **한국어 변경분의 en/ja 동기화**: [sync-ko-to-en-ja](../sync-ko-to-en-ja/SKILL.md) +- **Skeleton MDX 비교**: [mdx-skeleton-comparison](../mdx-skeleton-comparison/SKILL.md) +- **Commit 및 PR 작성**: [commit](../commit/SKILL.md), [docs/commit-pr-guide.md](/docs/commit-pr-guide.md) +- **Confluence 데이터 fetch CLI**: [bin/fetch_cli.py](/confluence-mdx/bin/fetch_cli.py) +- **전체 변환 CLI**: [bin/convert_all.py](/confluence-mdx/bin/convert_all.py) +- **Skeleton 비교 CLI**: [bin/skeleton/cli.py](/confluence-mdx/bin/skeleton/cli.py) +- **한국어 commit 동기화 CLI**: [bin/sync_ko_commit.py](/confluence-mdx/bin/sync_ko_commit.py) +- **이미지 alt 복원 CLI**: [bin/restore_alt_from_diff.py](/confluence-mdx/bin/restore_alt_from_diff.py) + ## 프로젝트 컨텍스트 - **변환 스크립트**: `confluence-mdx/bin/`에 위치 @@ -31,6 +44,73 @@ confluence-mdx/ ## 변환 워크플로우 개요 +### Confluence Space sync 기반 PR 작업 + +Confluence Space 전체 또는 최근 변경분을 동기화해 MDX 문서 PR을 만들 때는 다음 순서를 따른다. + +1. **branch 생성** + - worktree가 아니라 일반 git branch를 만든다. + - `confluence-mdx/var/` 아래 symlink와 변환 출력 경로가 정상 동작하려면 별도 worktree를 사용하지 않는다. + - 최신 `origin/main` HEAD를 기준으로 branch를 생성하고 checkout한다. + + ```bash + git fetch origin --prune + git switch -c docs/ origin/main + ``` + +2. **Confluence Space 데이터 fetch** + - 반드시 `confluence-mdx` 디렉토리에서 실행한다. + - 최근 변경된 Confluence 데이터와 attachment를 로컬 `var/` 아래로 내려받는다. + - 상세 옵션은 [bin/fetch_cli.py](/confluence-mdx/bin/fetch_cli.py) 및 [confluence-mdx/README.md](/confluence-mdx/README.md)의 `fetch_cli.py` 섹션을 확인한다. + + ```bash + cd confluence-mdx + source venv/bin/activate + bin/fetch_cli.py --recent --attachments + ``` + +3. **한국어 MDX 생성** + - `convert_all.py`로 한국어 MDX와 public asset 출력을 갱신한다. + - 상세 옵션은 [bin/convert_all.py](/confluence-mdx/bin/convert_all.py) 및 [confluence-mdx/README.md](/confluence-mdx/README.md)의 `convert_all.py` 섹션을 확인한다. + + ```bash + bin/convert_all.py + ``` + +4. **한국어 변경사항 PR 작성** + - `git status --short`와 diff를 확인한다. + - 변경된 한국어 MDX, attachment, 변환 metadata를 포함해 commit을 만든다. + - repository의 [commit](../commit/SKILL.md) 및 [PR 작성 지침](/docs/commit-pr-guide.md)을 따른다. + - 이 시점의 PR은 한국어 MDX 변환 결과를 먼저 리뷰 가능한 형태로 올리기 위한 중간 PR이다. + +5. **영어/일본어 번역 반영** + - 변경된 한국어 MDX 파일에 대응하는 `src/content/en/**`, `src/content/ja/**` 문서를 번역하거나 생성한다. + - 기존 문서가 있으면 구조와 frontmatter를 유지하며 갱신한다. + - 새 문서가 필요한 경우 한국어 문서와 대응되는 경로에 생성한다. + - 번역 작업은 [translation](../translation/SKILL.md) 및 [sync-ko-to-en-ja](../sync-ko-to-en-ja/SKILL.md) skill 지침을 함께 따른다. + - 한국어 commit을 기준으로 구조 변경을 먼저 반영할 때는 [bin/sync_ko_commit.py](/confluence-mdx/bin/sync_ko_commit.py)를 사용하고, 이미지 alt 복원은 [bin/restore_alt_from_diff.py](/confluence-mdx/bin/restore_alt_from_diff.py)를 확인한다. + +6. **Skeleton MDX 비교 검증** + - 변경된 한국어 문서와 대응 영어/일본어 문서를 Skeleton MDX 비교로 확인한다. + - Skeleton 비교 시 `src/content/{lang}/`가 아니라 `confluence-mdx/target/{lang}/` 경로를 사용한다. + - heading, list, table, admonition, code block, image, link 구조 차이를 확인하고 번역 MDX를 개선한다. + - 상세 사용법은 [mdx-skeleton-comparison](../mdx-skeleton-comparison/SKILL.md) 및 [bin/skeleton/cli.py](/confluence-mdx/bin/skeleton/cli.py)를 확인한다. + + ```bash + bin/skeleton/cli.py target/en/path/to/page.mdx + bin/skeleton/cli.py target/ja/path/to/page.mdx + ``` + +7. **PR에 번역 변경 포함 및 PR 갱신** + - 영어/일본어 변경사항을 commit하고 기존 PR에 push한다. + - PR title과 description을 최종 범위에 맞게 다시 작성한다. + - PR 본문에는 Confluence fetch/convert, 번역 반영, Skeleton 비교 검증 결과를 요약한다. + - 자동 동기화 PR 보정 흐름은 [confluence-pr-update](../confluence-pr-update/SKILL.md)를 함께 확인한다. + +8. **완료 확인** + - 최종 `git status --short`가 의도한 변경만 포함하는지 확인한다. + - 실행한 검증 명령과 남은 리스크를 작업 결과에 기록한다. + ### 빠른 시작 ```bash @@ -68,6 +148,39 @@ bin/converter/cli.py var//page.xhtml target/ko/path/to/page.mdx 2. `bin/convert_all.py --verify-translations`로 누락 여부 확인 3. `bin/convert_all.py` 재실행 +### `src/content/` 로컬 변경이 있는 상태에서 깨끗하게 다시 시작 + +Confluence Space 기준으로 MDX 생성/업데이트를 다시 수행해야 하고, 사용자가 `src/content/` 아래 로컬 변경사항은 모두 무시해도 된다고 명시한 경우에만 다음 절차를 따른다. + +1. `src/content/` 아래 tracked 로컬 변경사항을 reset한다. + + ```bash + git restore --source=HEAD -- src/content + ``` + +2. `src/content/` 아래 untracked 파일이 있으면 먼저 목록을 확인한 뒤, Confluence sync 작업 산출물로 버려도 되는 파일만 제거한다. + + ```bash + git status --short -- src/content + git clean -fd -- src/content + ``` + +3. 최신 `main` HEAD를 가져오고, 이 기준으로 새 local branch를 만든다. + + ```bash + git fetch origin --prune + git switch -c docs/ origin/main + ``` + +4. 새 branch에서 Confluence Space 기준 MDX 생성/업데이트 절차를 다시 수행한다. + + ```bash + cd confluence-mdx + source venv/bin/activate + bin/fetch_cli.py --recent --attachments + bin/convert_all.py + ``` + ## Python 환경 설정 ```bash