querypie · jk-kim0 · Jun 17, 2026 · Jun 17, 2026
@@ -0,0 +1,49 @@
+# OpenSpec
+
+이 디렉토리는 `querypie-docs`의 durable implementation contract를 기록합니다.
+
+OpenSpec spec은 일회성 plan이 아닙니다.
+현재와 미래의 documentation site, content workflow, Confluence conversion, reverse sync, deployment-facing behavior가 보존해야 하는 계약을 설명합니다.
+
+## 구조
+
+- `project.md` — 모든 spec에 적용되는 repository-wide context입니다.
+- `specs/` — accepted durable requirement를 둡니다.
+- `specs/<spec-id>/spec.md` — 하나의 platform, content workflow, data contract, 또는 user-facing capability를 설명합니다.
+- `changes/<change-id>/proposal.md` — 제안된 requirement 또는 contract change를 설명합니다.
+- `changes/<change-id>/design.md` — trade-off, alternative, migration, risk가 있는 변경의 decision record입니다.
+- `changes/<change-id>/tasks.md` — 해당 변경의 implementation 및 verification checklist입니다.
+- `changes/<change-id>/specs/<spec-id>/spec.md` — accepted spec을 즉시 수정하지 않아야 할 때 사용하는 change-local spec delta입니다.
+- `archive/<date>-<change-id>/` — change가 accepted 및 implemented 상태가 된 뒤 보존하는 완료 이력입니다.
+
+## 작성 규칙
+
+- OpenSpec Markdown 본문은 한국어로 작성합니다.
+- spec id, file name, `Requirement`와 `Scenario` 같은 heading, code identifier, route path, API name, modality token은 더 명확하거나 canonical한 경우 영어를 유지합니다.
+- Normative requirement에는 `SHALL`, `SHALL NOT`, `MAY`, `SHOULD`, `MUST`를 사용합니다.
+- 테스트 가능한 behavior는 `GIVEN` / `WHEN` / `THEN` / `AND` Scenario로 작성합니다.
+- Implementation reference는 maintainer가 source를 찾을 수 있을 만큼 구체적으로 쓰되, 큰 code block을 중복하지 않습니다.
+- 범위 제외는 금지가 아닙니다. 명시적으로 금지된 behavior가 아니면 `out of scope`, `future scope`, `backlog`로 구분합니다.
+- Implementation task checklist는 accepted `openspec/specs/**/spec.md`가 아니라 `openspec/changes/<change-id>/tasks.md`에 둡니다.
+- `docs/**`와 `openspec/**`에 같은 Requirement, Scenario, decision table, task checklist를 길게 중복하지 않습니다.
+
+## 작성 흐름
+
+1. 새 durable contract가 필요한지 판단합니다.
+   - 구현 PR이 따라야 할 요구사항, route behavior, content workflow, converter behavior, verification 기준이면 OpenSpec 대상입니다.
+   - 일회성 작업 메모, 단순 번역 요청, 임시 조사 결과는 OpenSpec 대상이 아닙니다.
+2. 기존 accepted spec이 있으면 `openspec/specs/**/spec.md`를 먼저 확인합니다.
+3. 새 요구사항 또는 기존 계약 변경이면 `openspec/changes/<change-id>/proposal.md`와 `tasks.md`를 먼저 작성합니다.
+4. decision, migration, risk, rejected alternative가 있으면 `design.md`를 추가합니다.
+5. 구현과 검증이 완료되면 accepted spec을 갱신하고 완료된 change를 `archive/<date>-<change-id>/`로 이동합니다.
+
+## 검증
+
+OpenSpec 문서만 변경한 경우 기본 검증은 다음입니다.
+
+```bash
+git diff --check
+rg -n "<핵심 requirement phrase>" openspec docs src confluence-mdx
+```
+
+코드 또는 콘텐츠 구현을 포함하는 PR은 해당 change의 `tasks.md`에 적은 focused verification을 추가로 실행합니다.
@@ -0,0 +1,23 @@
+# OpenSpec Archive
+
+이 디렉토리는 완료된 OpenSpec change 이력을 보관합니다.
+현재 archive된 change는 없습니다.
+
+## Archive 조건
+
+Change는 다음 조건을 만족한 뒤 archive합니다.
+
+- accepted spec이 필요한 경우 `openspec/specs/**/spec.md`에 반영되어 있습니다.
+- implementation task가 완료되었거나 남은 항목이 명시적인 follow-up으로 분리되어 있습니다.
+- verification 결과 또는 미검증 범위가 `tasks.md` 또는 PR body에 기록되어 있습니다.
+- `openspec/specs/README.md` inventory가 필요한 경우 갱신되어 있습니다.
+
+## 디렉토리 이름
+
+완료된 change는 다음 형식으로 이동합니다.
+
+```text
+openspec/archive/<YYYY-MM-DD>-<change-id>/
+```
+
+Archive는 완료 이력입니다. 새 요구사항 변경은 archive를 직접 수정하지 말고 새 `openspec/changes/<change-id>/`를 만듭니다.
@@ -0,0 +1,58 @@
+# OpenSpec Changes
+
+이 디렉토리는 proposed requirement 또는 contract change를 보관합니다.
+현재 active change는 없습니다.
+
+## Change 구조
+
+일반적인 change는 다음 구조를 사용합니다.
+
+```text
+openspec/changes/<change-id>/
+  proposal.md
+  design.md
+  tasks.md
+  specs/<spec-id>/spec.md
+```
+
+- `proposal.md`는 왜 변경이 필요한지와 어떤 capability가 바뀌는지 설명합니다.
+- `design.md`는 decision, rejected alternative, migration, risk가 있을 때 작성합니다.
+- `tasks.md`는 implementation, verification, drift check, cleanup checklist를 기록합니다.
+- `specs/<spec-id>/spec.md`는 accepted spec을 즉시 바꾸기 어려울 때 사용하는 change-local spec delta입니다.
+
+## Proposal 최소 형식
+
+```md
+## Why
+
+## What Changes
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+
+## Impact
+```
+
+## Tasks 최소 형식
+
+```md
+## 1. Contract
+
+## 2. Implementation
+
+## 3. Verification
+
+## 4. Spec / 구현 drift 확인
+
+## 5. OpenSpec Cleanup
+```
+
+## 운영 규칙
+
+- 하나의 change는 하나의 reviewable contract change를 다룹니다.
+- 서로 독립적인 product area 또는 workflow는 별도 change로 분리합니다.
+- Backlog 항목은 Product Owner 또는 reviewer가 우선순위를 명시하기 전까지 구현 task로 취급하지 않습니다.
+- 구현이 완료된 change는 accepted spec 정리 후 `openspec/archive/<date>-<change-id>/`로 이동합니다.
@@ -0,0 +1,83 @@
+# querypie-docs OpenSpec 프로젝트 Context
+
+OpenSpec은 future PR이 따라야 하는 durable implementation contract를 기록합니다.
+기존 `docs/**` 문서는 운영 가이드, 배경, 예시, 개발 절차를 설명하고, OpenSpec은 구현과 검증이 보존해야 하는 계약을 설명합니다.
+
+## Repository 역할
+
+`querypie-docs`는 QueryPie 제품 문서를 관리하고 배포하는 repository입니다.
+주요 surface는 다음과 같습니다.
+
+- Public documentation site: Next.js, Nextra, React, TypeScript 기반 문서 사이트
+- Product content: `src/content/{ko,en,ja}/` 아래 MDX 문서
+- Confluence import/conversion: `confluence-mdx/` 아래 Python 기반 변환 도구
+- Reverse sync: MDX 교정 결과를 Confluence XHTML로 되돌리는 도구와 테스트
+- API reference rendering: 저장된 specification JSON을 문서 사이트에서 렌더링하는 UI
+- Search index: build-time 문서 검색 인덱스와 `/mcp` endpoint가 사용하는 generated artifact
+- Deployment workflow: GitHub Actions와 Vercel preview/production deployment
+
+## Source of Truth
+
+- Public product documentation의 source of truth는 `src/content/{ko,en,ja}/`입니다.
+- `confluence-mdx/target/{ko,en,ja}/`는 `src/content/{ko,en,ja}/`를 가리키는 symlink로 취급합니다.
+- Confluence 변환 입력과 intermediate artifact는 `confluence-mdx/var/**`와 관련 tool 문서가 설명합니다.
+- Agent skill과 내부 repository 지침은 `.agents/skills/**`, `AGENTS.md`, `CLAUDE.md`, `docs/**`에 둡니다.
+- OpenSpec으로 승격된 durable contract는 `openspec/specs/**/spec.md`를 우선합니다.
+
+## Language 정책
+
+- OpenSpec 본문, internal repository guidance, skill 문서는 한국어로 작성합니다.
+- `src/content/en/**`와 `src/content/ja/**` 같은 localized public content는 target locale을 따릅니다.
+- 파일명, route path, API name, UI label, frontmatter key, code identifier, 외부 고유명사는 canonical language를 유지합니다.
+
+## Contract 우선순위
+
+동일한 behavior에 대해 문서가 충돌하면 다음 순서로 해석합니다.
+
+1. 사용자 또는 reviewer가 현재 PR에서 명시한 최신 요구사항
+2. `AGENTS.md`와 관련 repo-local skill
+3. `openspec/specs/**/spec.md` accepted spec
+4. active `openspec/changes/**` proposal, design, tasks
+5. `docs/**`, `README.md`, `CLAUDE.md`
+6. 현재 구현
+
+현재 구현이 accepted spec과 다르면 구현을 source of truth로 단정하지 않습니다.
+먼저 drift인지, 의도된 contract change인지, stale spec인지 분류합니다.
+
+## OpenSpec 대상
+
+다음 변경은 OpenSpec 작성 또는 갱신 후보입니다.
+
+- public route, navigation, sitemap, canonical, redirect behavior 변경
+- content source path, locale sync, skeleton comparison, translation consistency 계약 변경
+- Confluence import, MDX conversion, attachment path, reverse sync, XHTML patching behavior 변경
+- API reference rendering, stored specification loading, version routing 계약 변경
+- search index, MCP endpoint, generated artifact lifecycle 변경
+- deployment, preview, validation, CI check contract 변경
+- agent workflow, repository skill, durable authoring contract 변경
+
+다음 변경은 일반적으로 OpenSpec 대상이 아닙니다.
+
+- 단순 오탈자 수정
+- 기존 계약을 바꾸지 않는 localized copy 갱신
+- 일회성 조사 메모
+- 기존 accepted spec 또는 docs에 이미 명확히 정의된 작업의 단순 실행
+
+## PR 분리 원칙
+
+- OpenSpec-only 변경과 production implementation 변경은 가능하면 별도 PR로 분리합니다.
+- 같은 feature의 requirement와 implementation을 모두 바꿔야 하면 OpenSpec PR을 먼저 만들고, implementation PR은 OpenSpec PR branch를 base로 둔 stacked PR로 만듭니다.
+- unrelated OpenSpec drift는 현재 feature PR에 섞지 않습니다.
+- OpenSpec PR body에는 기준 spec/change path, 구현 PR과 분리한 이유, 후속 task, 검증 방식을 적습니다.
+
+## Initial Spec 후보
+
+아래 항목은 필요할 때 accepted spec으로 승격할 수 있는 후보입니다.
+
+- `contract-content-source-of-truth`: `src/content/{ko,en,ja}`와 `confluence-mdx/target/**` symlink 계약
+- `contract-locale-sync`: 한국어 원문 변경과 영어/일본어 동기화, skeleton comparison 계약
+- `contract-confluence-mdx-conversion`: Confluence XHTML에서 MDX로 변환하는 path, attachment, metadata 계약
+- `contract-reverse-sync`: MDX 교정 결과를 Confluence XHTML로 반영하는 안전장치와 patching 계약
+- `platform-docs-site-routing`: Nextra/Next.js route, metadata, sitemap, canonical 계약
+- `contract-api-reference-rendering`: stored API specification JSON loading 및 renderer 계약
+- `contract-agent-skill-authoring`: `.agents/skills` skill 작성과 trigger 계약
@@ -0,0 +1,39 @@
+# OpenSpec Specs Inventory
+
+이 디렉토리는 accepted durable requirement를 보관합니다.
+현재 repository에는 아직 accepted OpenSpec spec이 없습니다.
+
+## Inventory 규칙
+
+새 accepted spec을 추가할 때 이 파일에 다음 정보를 함께 기록합니다.
+
+| Spec | 책임 | 관련 surface | 상태 |
+| --- | --- | --- | --- |
+| `<spec-id>` | `<durable contract 책임>` | `<docs/src/confluence-mdx/tests 등>` | accepted |
+
+## Spec ID 규칙
+
+- 사용자-facing documentation workflow: `uc-*`
+- site foundation, authoring platform, reviewer/debugging capability: `platform-*`
+- data, loader, metadata, validation, route resolution, content workflow contract: `contract-*`
+- deployment, runtime, observability, operations: `infra-*`
+
+## Accepted Spec 작성 규칙
+
+- Accepted spec은 구현자가 보존해야 할 계약을 설명합니다.
+- Accepted spec에 task checklist를 넣지 않습니다.
+- 새 구현 순서, 검증 checklist, migration step은 `openspec/changes/<change-id>/tasks.md`에 둡니다.
+- Requirement는 `SHALL`, `SHALL NOT`, `MAY`, `SHOULD`, `MUST` 같은 modality token을 사용합니다.
+- Scenario는 `GIVEN`, `WHEN`, `THEN`, `AND`로 관찰 가능한 조건과 결과를 적습니다.
+
+## 후보 Backlog
+
+아래 후보는 필요할 때 별도 OpenSpec change로 승격합니다.
+
+- `contract-content-source-of-truth`
+- `contract-locale-sync`
+- `contract-confluence-mdx-conversion`
+- `contract-reverse-sync`
+- `platform-docs-site-routing`
+- `contract-api-reference-rendering`
+- `contract-agent-skill-authoring`