querypie · jk-kim0 · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026
@@ -0,0 +1,88 @@
+# QueryPie 문서 저장소용 Agent Skills
+
+이 디렉토리는 QueryPie 문서 저장소에서 다양한 작업을 수행하는 데 도움이 되는 Agent skills를 포함합니다.
+
+표준 layout:
+
+```text
+.agents/skills/<skill-name>/SKILL.md
+```
+
+## 사용 가능한 Skills
+
+### 번역/교정 Skills
+- **translation** - 다국어 번역 가이드라인 (ko → en, ja)
+- **proofread** - 문서 교정/교열 가이드
+- **sync-ko-to-en-ja** - 한국어 MDX 변경사항을 영어/일본어에 동기화
+- **mdx-skeleton-comparison** - 스켈레톤 비교를 통한 번역 일관성 검증
+
+### Confluence 워크플로우 Skills
+- **confluence-mdx** - Confluence에서 MDX로 변환 워크플로우
+- **confluence-pr-update** - Confluence MDX PR 수정 워크플로우
+- **confluence-mdx-testcase** - XHTML 변환 테스트케이스 추가 가이드
+
+### Reverse Sync / XHTML Skills
+- **reverse-sync** - Reverse Sync (MDX → Confluence XHTML 역반영) 사용 가이드
+- **reverse-sync-debugging** - Reverse Sync 디버깅 워크플로우 (verify 실패 원인 분석 및 수정)
+- **xhtml-beautify-diff** - XHTML Beautify-Diff Viewer 사용 가이드
+
+### 유틸리티 Skills
+- **sync-confluence-url** - ko→en/ja confluenceUrl frontmatter 동기화
+
+### 프로세스 Skills
+- **commit** - Commit 및 PR 작성 가이드
+- **code-review** - 코드 변경 사항 검토 가이드라인
+
+### OpenSpec Skills
+- **openspec-authoring** - OpenSpec spec, proposal, design, task 문서 작성
+- **openspec-doc-maintenance** - OpenSpec drift, 모순, stale scenario, contract 유지보수
+- **openspec-task-execution** - OpenSpec `tasks.md`의 남은 구현, 검증, PR-sized 후속 작업 수행
+
+## Skills과 참조 문서 관계
+
+각 skill은 핵심 원칙과 빠른 시작 가이드를 제공하며, 상세 내용은 프로젝트의 다른 문서를 참조합니다:
+
+| Skill | 참조 문서 |
+|-------|----------|
+| translation | [docs/translation.md](/docs/translation.md), [docs/api-naming-guide.md](/docs/api-naming-guide.md) |
+| confluence-mdx | [confluence-mdx/README.md](/confluence-mdx/README.md) |
+| confluence-pr-update | confluence-mdx, translation, mdx-skeleton-comparison |
+| confluence-mdx-testcase | [confluence-mdx/README.md](/confluence-mdx/README.md) |
+| sync-ko-to-en-ja | [docs/translation.md](/docs/translation.md) |
+| mdx-skeleton-comparison | [docs/translation.md](/docs/translation.md) |
+| reverse-sync | [confluence-mdx/bin/reverse_sync_cli.py](/confluence-mdx/bin/reverse_sync_cli.py) |
+| reverse-sync-debugging | reverse-sync, [confluence-mdx/bin/reverse_sync_cli.py](/confluence-mdx/bin/reverse_sync_cli.py) |
+| sync-confluence-url | [confluence-mdx/bin/sync_confluence_url.py](/confluence-mdx/bin/sync_confluence_url.py) |
+| xhtml-beautify-diff | [confluence-mdx/bin/xhtml_beautify_diff.py](/confluence-mdx/bin/xhtml_beautify_diff.py) |
+| commit | [docs/commit-pr-guide.md](/docs/commit-pr-guide.md) (Commit 및 PR 작성) |
+| proofread | [docs/api-naming-guide.md](/docs/api-naming-guide.md) |
+| openspec-authoring | [AGENTS.md](/AGENTS.md), `openspec/README.md` (OpenSpec 도입 후) |
+| openspec-doc-maintenance | [AGENTS.md](/AGENTS.md), `openspec/project.md` (OpenSpec 도입 후) |
+| openspec-task-execution | [AGENTS.md](/AGENTS.md), `openspec/changes/**/tasks.md` |
+
+## 사용법
+
+이 skills는 이 저장소에서 작업할 때 agent가 사용할 수 있습니다. 다음 작업에 대한 상황별 가이드를 제공합니다:
+
+- MDX 문서 작성 및 유지 관리
+- 다국어 콘텐츠 번역
+- Confluence 변환 스크립트 작업
+- 원문과 번역본 MDX 파일 간의 불일치 감지
+- OpenSpec 기반 요구사항, 구현 계약, 후속 task 관리
+- 코드 변경 사항 검토
+
+## 프로젝트 구조
+
+이 저장소는 다음을 사용합니다:
+- **Next.js 16** + **Nextra 4** - 문서 사이트
+- **TypeScript 5** - 타입 안전성
+- **React 19** - UI 컴포넌트
+- **MDX** - 콘텐츠 파일 형식
+- 다국어 지원: 영어 (en), 일본어 (ja), 한국어 (ko)
+
+## 콘텐츠 위치
+
+- 소스 콘텐츠: `src/content/{lang}/`
+- Confluence 변환 스크립트: `confluence-mdx/bin/`
+- 공용 자산: `public/`
+- 프로젝트 문서: `docs/`
@@ -24,7 +24,7 @@ QueryPie 문서 저장소의 변경 사항을 검토하기 위한 가이드라
 
 - 모든 언어(en, ja, ko) 버전이 업데이트되었는지 확인
 - 언어 간 동일한 구조 확인
-- 번역 품질 확인 — [translation.md](translation.md) 참조
+- 번역 품질 확인 — [translation.md](../translation/SKILL.md) 참조
 
 ### 빌드 및 배포
 

@@ -66,11 +66,11 @@ git status public/
 - 일본어: `src/content/ja/path/to/file.mdx`
 
 **번역 지침**:
-- [docs/translation.md](/docs/translation.md) 및 [translation.md](translation.md)의 번역 규칙 준수
+- [docs/translation.md](/docs/translation.md) 및 [translation.md](../translation/SKILL.md)의 번역 규칙 준수
 
 ### Step 5: Skeleton MDX 비교로 검증
 
-번역 후 구조 일치를 확인합니다. 사용법은 [mdx-skeleton-comparison.md](mdx-skeleton-comparison.md)를 참조하세요.
+번역 후 구조 일치를 확인합니다. 사용법은 [mdx-skeleton-comparison.md](../mdx-skeleton-comparison/SKILL.md)를 참조하세요.
 
 ```bash
 cd confluence-mdx
@@ -127,7 +127,7 @@ git push origin HEAD
 
 **PR title prefix 규칙**:
 - `mdx:` — MDX 콘텐츠 파일(`src/content/`)의 추가/수정/번역. Confluence 동기화, 번역, 교정/교열 등.
-- `docs:` — 저장소 내부 문서/지침(`docs/`, `.claude/skills/`, `README.md` 등)의 추가/수정. 콘텐츠가 아닌 개발/운영 문서.
+- `docs:` — 저장소 내부 문서/지침(`docs/`, `.agents/skills/`, `README.md` 등)의 추가/수정. 콘텐츠가 아닌 개발/운영 문서.
 - `feat:`, `fix:`, `chore:` 등 — 코드/인프라 변경에 대한 일반적인 conventional commit prefix.
 
 ```bash
@@ -177,15 +177,15 @@ git status public/
 
 ### Skeleton 불일치가 발생한 경우
 
-[mdx-skeleton-comparison.md](mdx-skeleton-comparison.md)의 "불일치 발견 시 처리 방법"을 참조하세요.
+[mdx-skeleton-comparison.md](../mdx-skeleton-comparison/SKILL.md)의 "불일치 발견 시 처리 방법"을 참조하세요.
 
 ### 코드 블록 내 주석이 번역된 경우
 
 코드 블록 내용을 한국어 원본(또는 영어 원본)과 동일하게 복원합니다.
 
 ## 관련 문서
 
-- **Confluence MDX 변환**: [confluence-mdx.md](confluence-mdx.md)
-- **Skeleton MDX 비교**: [mdx-skeleton-comparison.md](mdx-skeleton-comparison.md)
-- **번역 가이드라인**: [translation.md](translation.md)
-- **한국어→영어/일본어 동기화**: [sync-ko-to-en-ja.md](sync-ko-to-en-ja.md)
+- **Confluence MDX 변환**: [confluence-mdx.md](../confluence-mdx/SKILL.md)
+- **Skeleton MDX 비교**: [mdx-skeleton-comparison.md](../mdx-skeleton-comparison/SKILL.md)
+- **번역 가이드라인**: [translation.md](../translation/SKILL.md)
+- **한국어→영어/일본어 동기화**: [sync-ko-to-en-ja.md](../sync-ko-to-en-ja/SKILL.md)
@@ -245,4 +245,4 @@ python -m pytest tests/test_mdx_to_skeleton.py -v
 ## 상세 문서
 
 - **Skeleton MDX 개념**: [docs/translation.md](/docs/translation.md)
-- **번역 가이드라인**: [translation.md](translation.md)
+- **번역 가이드라인**: [translation.md](../translation/SKILL.md)
@@ -0,0 +1,154 @@
+# OpenSpec Authoring
+
+QueryPie 문서 저장소에서 OpenSpec spec, proposal, design, tasks를 새로 작성하거나 크게 갱신할 때 사용합니다.
+목표는 `openspec/`를 일회성 계획이 아니라 구현자가 따라야 하는 durable contract layer로 유지하는 것입니다.
+
+## 사용 시점
+
+- 새 `openspec/specs/<spec-id>/spec.md`를 작성할 때
+- 기존 OpenSpec spec의 Requirement 또는 Scenario를 크게 바꿀 때
+- 요구사항 변경을 `openspec/changes/<change-id>/` 아래 proposal, design, tasks, spec delta로 기록할 때
+- 기존 `docs/**`, 현재 구현, 테스트 evidence를 OpenSpec 계약으로 승격할 때
+- 구현 PR 전에 요구사항 또는 검증 범위를 먼저 확정해야 할 때
+
+사용하지 않습니다:
+
+- 구현 중 우연히 drift, 모순, stale Scenario를 발견한 경우에는 `openspec-doc-maintenance`를 우선 사용합니다.
+- 단순 MDX 번역/교정 작업은 `translation`, `proofread`, `sync-ko-to-en-ja`를 우선 사용합니다.
+- Confluence 변환 또는 reverse sync 작업은 관련 Confluence/reverse sync skill을 우선 사용합니다.
+
+## 사전 확인
+
+1. `AGENTS.md`와 `.agents/skills/README.md`를 읽고 현재 repository 규칙을 확인합니다.
+2. `openspec/`가 존재하는지 확인합니다.
+   - 존재하면 `openspec/README.md`, `openspec/project.md`, `openspec/specs/README.md`를 읽습니다.
+   - 존재하지 않으면 이번 요청이 OpenSpec 도입 또는 새 OpenSpec 작성 요청인지 확인하고, 필요한 경우 최소 scaffold를 먼저 작성합니다.
+3. 관련 active spec과 change 문서를 확인합니다.
+   - `openspec/specs/**/spec.md`
+   - `openspec/changes/**/{proposal.md,design.md,tasks.md}`
+4. 관련 repository 문서를 찾습니다.
+   - 프로젝트 개발 지침: `docs/DEVELOPMENT.md`
+   - 번역 지침: `docs/translation.md`
+   - API 명칭 지침: `docs/api-naming-guide.md`
+   - Confluence 변환 문서: `confluence-mdx/README.md`
+   - 기존 구현 계획: `docs/plans/**`, `docs/superpowers/**`
+5. 관련 구현 evidence를 찾습니다.
+   - 문서 콘텐츠: `src/content/**`
+   - 문서 UI와 렌더링: `src/app/**`, `src/components/**`
+   - Confluence 변환기: `confluence-mdx/bin/**`
+   - 테스트와 check: `tests/**`, `confluence-mdx/tests/**`, `src/**/*.test.*`, `scripts/**`
+
+## 작성 규칙
+
+- 내부 Markdown 본문은 한국어로 작성합니다.
+- 파일명, spec id, frontmatter key, route path, API name, code identifier, UI label, 외부 고유명사는 canonical language를 유지합니다.
+- Accepted spec은 구현 계약을 설명하고, task checklist를 포함하지 않습니다.
+- 후속 구현 순서와 검증 checklist는 `openspec/changes/<change-id>/tasks.md`에 둡니다.
+- 제품/기술/운영 의사결정은 필요한 경우 `openspec/changes/<change-id>/design.md`를 canonical decision record로 둡니다.
+- Requirement 문장은 가능한 한 `SHALL`, `SHALL NOT`, `MAY`, `SHOULD`, `MUST`를 명시합니다.
+- `SHALL NOT`과 `MUST NOT`은 실제 금지, safety guard, security guard, compatibility guard에만 사용합니다.
+- 단순 범위 제외는 금지가 아닙니다. `out of scope`, `future scope`, `backlog`로 구분합니다.
+- Scenario는 agent가 테스트나 smoke로 바꿀 수 있도록 `GIVEN`, `WHEN`, `THEN`, `AND`를 사용합니다.
+- `docs/**`와 OpenSpec에 같은 Requirement, Scenario, decision table, task checklist를 중복으로 길게 유지하지 않습니다.
+
+## 문서 형태
+
+Accepted spec 형식:
+
+```md
+# <spec-id>
+
+## Purpose
+
+## References
+
+## Requirements
+
+### Requirement: <name>
+
+<한국어 계약 문장>(SHALL).
+
+#### Scenario: <observable case>
+
+- GIVEN ...
+- WHEN ...
+- THEN ...(SHALL).
+```
+
+Proposal 형식:
+
+```md
+## Why
+
+## What Changes
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+
+## Impact
+```
+
+Design 형식:
+
+```md
+## Context
+
+## Goals / Non-Goals
+
+## Decisions
+
+### Decision: ...
+
+## Risks / Trade-offs
+
+## Migration Plan
+
+## Open Questions
+```
+
+Tasks 형식:
+
+```md
+## 1. Contract
+
+## 2. Implementation
+
+## 3. Verification
+
+## 4. Spec / 구현 drift 확인
+
+## 5. OpenSpec Cleanup
+```
+
+## 작성 절차
+
+1. 변경 대상이 accepted spec 수정인지, 새 change proposal인지 분류합니다.
+2. 넓은 요구사항 변경이면 `openspec/changes/<change-id>/proposal.md`와 `tasks.md`부터 작성합니다.
+3. decision, alternative, migration, risk가 있으면 `design.md`를 추가합니다.
+4. 기존 accepted spec을 즉시 바꾸면 구현과 충돌할 수 있을 때는 `changes/<change-id>/specs/<spec-id>/spec.md`에 delta를 둡니다.
+5. 새 spec id는 장기 책임을 기준으로 고릅니다.
+   - 사용자-facing workflow: `uc-*`
+   - app foundation 또는 reviewer/debugging capability: `platform-*`
+   - data, loader, metadata, validation, route resolution contract: `contract-*`
+   - deployment, runtime, observability, operations: `infra-*`
+6. 후속 구현 task에는 파일 후보, 영향받는 route/page/component/API/test surface, 검증 명령, browser smoke 필요 여부를 적습니다.
+7. Verification task는 구현 PR 범위보다 넓게 잡습니다. Cross-page UI, route, component, copy, content loader 계약은 같은 패턴을 쓰는 관련 surface를 source scan, regression test, browser smoke 중 하나 이상으로 확인하도록 적습니다.
+8. 새 OpenSpec이 기존 docs 내용을 대체하면 기존 docs는 짧은 bridge link로 축소하거나 중복 내용을 제거합니다.
+
+## 검증
+
+- `git diff --check`로 Markdown whitespace 문제를 확인합니다.
+- 핵심 Requirement 또는 decision phrase를 `rg`로 검색해 중복 canonical statement가 생기지 않았는지 확인합니다.
+- 새 파일과 수정 파일이 `openspec/README.md`의 layout과 writing rules를 따르는지 확인합니다.
+- 코드 변경이 없으면 build를 실행하지 않습니다. 문서 변경 검증과 scope check를 우선합니다.
+
+## 흔한 실수
+
+1. 현재 코드 동작을 제품 의도라고 단정해 stale implementation을 spec으로 고정하는 것
+2. accepted spec에 구현 task checklist를 넣어 contract와 실행 계획을 섞는 것
+3. `SHALL NOT`을 단순 out-of-scope 항목에 사용해 future scope를 영구 금지처럼 만드는 것
+4. `docs/**`와 `openspec/**`에 같은 Requirement를 길게 중복해 drift source를 늘리는 것
+5. 후속 구현 범위를 좁게 나눈 것을 이유로 verification 범위까지 좁혀 관련 route, component, locale, loader 회귀를 놓치는 것
@@ -0,0 +1,94 @@
+# OpenSpec 문서 유지보수
+
+QueryPie 문서 저장소에서 구현, 리뷰, 계획, 디버깅 중 OpenSpec 문서와 실제 계약 사이의 차이를 발견했을 때 사용합니다.
+OpenSpec 문제를 대화나 임시 메모에만 남기지 않고, repository의 durable contract로 정리하는 것이 목적입니다.
+
+## 사용 시점
+
+- `openspec/` 아래 문서를 추가, 수정, 정리, 보완할 때
+- 구현 또는 테스트에 필요한 Requirement나 Scenario가 OpenSpec에 없을 때
+- OpenSpec과 `docs/**`, 코드, 테스트, route behavior가 서로 다른 계약을 말할 때
+- stale Scenario, 오래된 route/API/content path, 잘못된 scope exclusion을 발견했을 때
+- 코드 구현 중 새 durable contract가 생겼고 `openspec/`에 기록해야 할 때
+- 요구사항 변경 또는 스펙 변경이 포함되어 구현 전에 OpenSpec 업데이트가 필요한 때
+
+사용하지 않습니다:
+
+- 처음부터 새 OpenSpec spec이나 change 문서를 작성하는 것이 주 작업이면 `openspec-authoring`을 우선 사용합니다.
+- 단순 코드 구현이고 OpenSpec drift 또는 contract 변경이 없으면 사용하지 않습니다.
+
+## 기본 원칙
+
+- 내부 Markdown 본문은 한국어로 작성합니다.
+- 파일명, spec id, code identifier, route path, API name, frontmatter key, modality token은 canonical language를 유지합니다.
+- OpenSpec은 구현 계약의 source of truth이고, `docs/**`는 workflow, 배경, 예시, 운영 가이드를 보조합니다.
+- 현재 사용자의 요청 자체가 OpenSpec 수정이면 같은 작업 PR 안에서 처리합니다.
+- 다른 구현/리뷰 작업 중 우연히 발견한 unrelated drift는 별도 OpenSpec PR로 분리합니다.
+- 요구사항 변경 또는 스펙 변경이 명확하면 코드 구현 전에 OpenSpec과 후속 task를 먼저 작성합니다.
+- 사용자가 명시적으로 implementation-only를 요구하지 않았다면, 새 contract를 코드에만 숨겨 두지 않습니다.
+
+## 유지보수 절차
+
+1. Drift 후보를 분류합니다.
+   - 모순: 두 spec 또는 spec과 docs/code가 서로 다른 요구를 말합니다.
+   - 오류: 현재 canonical docs나 구현 기준으로 명백히 잘못된 route, field, status, scope가 있습니다.
+   - 누락: 구현 또는 검증에 필요한 durable contract가 없습니다.
+   - stale: 과거 구현이나 preview-only 상태가 현재 계약처럼 남아 있습니다.
+2. 현재 작업 범위와 같은지 판단합니다.
+   - 같은 OpenSpec 요청이면 현재 branch에서 수정합니다.
+   - unrelated drift면 별도 branch와 PR로 분리합니다.
+   - 기존 open PR이 같은 범위를 다루면 새 PR보다 기존 branch 업데이트를 우선 검토합니다.
+3. 관련 source를 확인합니다.
+   - `AGENTS.md`
+   - `openspec/README.md`
+   - `openspec/project.md`
+   - 관련 `openspec/specs/**/spec.md`
+   - 관련 `openspec/changes/**/{proposal.md,design.md,tasks.md}`
+   - 관련 `docs/**`, `src/app/**`, `src/content/**`, `src/components/**`, `confluence-mdx/**`, `tests/**`
+4. 수정 위치를 고릅니다.
+   - accepted durable behavior는 `openspec/specs/<spec-id>/spec.md`
+   - proposed requirement change는 `openspec/changes/<change-id>/proposal.md`
+   - Decision, alternative, migration, risk는 `openspec/changes/<change-id>/design.md`
+   - 후속 구현과 검증 범위는 `openspec/changes/<change-id>/tasks.md`
+5. Requirement와 Scenario를 테스트 가능한 계약으로 고칩니다.
+   - Requirement는 의무, 금지, 허용, 권고를 modality token으로 표시합니다.
+   - Scenario는 `GIVEN`, `WHEN`, `THEN`, `AND`로 관찰 가능한 상태와 결과를 적습니다.
+6. 구현 drift 또는 후속 구현이 필요하면 task를 남깁니다.
+   - 변경 파일 후보
+   - 영향받는 route/page/component/API/content loader/test surface
+   - source-level test 또는 browser smoke 검증 방식
+   - spec과 implementation drift check 결과 기록 위치
+7. 중복 docs를 정리합니다.
+   - OpenSpec으로 승격된 Requirement, Scenario, decision table, task checklist는 `docs/**`에 full copy로 유지하지 않습니다.
+   - 필요한 docs는 OpenSpec 링크와 짧은 배경 설명으로 축소합니다.
+8. PR 설명에는 drift 원인, 수정한 OpenSpec path, 구현 PR과 분리한 이유, 후속 구현 task와 검증 기준을 적습니다.
+
+## PR 분리 기준
+
+별도 PR로 분리합니다:
+
+- 현재 feature 구현과 관계없는 OpenSpec drift
+- reviewer가 contract correction만 독립 검토해야 하는 변경
+- 코드 구현 전에 합의되어야 하는 요구사항 또는 스펙 변경
+
+같은 PR에 포함할 수 있습니다:
+
+- 사용자가 애초에 OpenSpec 문서 수정을 요청한 경우
+- 문서-only PR 자체가 OpenSpec change plan을 수행하는 경우
+- 구현 변경의 acceptance criteria를 정확히 반영하기 위해 같은 작은 spec/task 보정이 필요한 경우
+
+## 검증
+
+- `git diff --check`를 실행합니다.
+- 핵심 phrase를 `rg`로 검색해 중복 canonical statement가 남지 않았는지 확인합니다.
+- 변경한 OpenSpec path와 관련 docs path를 PR body에 적을 수 있을 만큼 scope를 확인합니다.
+- 코드 변경 없이 OpenSpec만 수정했다면 build보다 문서 diff, scope, 중복 검색을 우선 검증합니다.
+
+## 흔한 실수
+
+1. 구현 중 발견한 spec 문제를 대화에만 남기고 PR로 정리하지 않는 것
+2. unrelated OpenSpec correction을 feature PR에 섞는 것
+3. 새 Requirement를 만들고도 후속 implementation task와 verification 범위를 남기지 않는 것
+4. `docs/**`와 `openspec/**`에 같은 contract를 길게 중복하는 것
+5. 대표 화면 하나만 확인하고 shared route, component, locale, content loader 영향 범위를 검증 task에서 누락하는 것
+6. scope exclusion을 금지처럼 작성해 future work를 불필요하게 막는 것