diff --git a/openspec/README.md b/openspec/README.md new file mode 100644 index 000000000..8a8a7924b --- /dev/null +++ b/openspec/README.md @@ -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.md` — 하나의 platform, content workflow, data contract, 또는 user-facing capability를 설명합니다. +- `changes//proposal.md` — 제안된 requirement 또는 contract change를 설명합니다. +- `changes//design.md` — trade-off, alternative, migration, risk가 있는 변경의 decision record입니다. +- `changes//tasks.md` — 해당 변경의 implementation 및 verification checklist입니다. +- `changes//specs//spec.md` — accepted spec을 즉시 수정하지 않아야 할 때 사용하는 change-local spec delta입니다. +- `archive/-/` — 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//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//proposal.md`와 `tasks.md`를 먼저 작성합니다. +4. decision, migration, risk, rejected alternative가 있으면 `design.md`를 추가합니다. +5. 구현과 검증이 완료되면 accepted spec을 갱신하고 완료된 change를 `archive/-/`로 이동합니다. + +## 검증 + +OpenSpec 문서만 변경한 경우 기본 검증은 다음입니다. + +```bash +git diff --check +rg -n "<핵심 requirement phrase>" openspec docs src confluence-mdx +``` + +코드 또는 콘텐츠 구현을 포함하는 PR은 해당 change의 `tasks.md`에 적은 focused verification을 추가로 실행합니다. diff --git a/openspec/archive/README.md b/openspec/archive/README.md new file mode 100644 index 000000000..37754400c --- /dev/null +++ b/openspec/archive/README.md @@ -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/-/ +``` + +Archive는 완료 이력입니다. 새 요구사항 변경은 archive를 직접 수정하지 말고 새 `openspec/changes//`를 만듭니다. diff --git a/openspec/changes/README.md b/openspec/changes/README.md new file mode 100644 index 000000000..481ae104a --- /dev/null +++ b/openspec/changes/README.md @@ -0,0 +1,58 @@ +# OpenSpec Changes + +이 디렉토리는 proposed requirement 또는 contract change를 보관합니다. +현재 active change는 없습니다. + +## Change 구조 + +일반적인 change는 다음 구조를 사용합니다. + +```text +openspec/changes// + proposal.md + design.md + tasks.md + specs//spec.md +``` + +- `proposal.md`는 왜 변경이 필요한지와 어떤 capability가 바뀌는지 설명합니다. +- `design.md`는 decision, rejected alternative, migration, risk가 있을 때 작성합니다. +- `tasks.md`는 implementation, verification, drift check, cleanup checklist를 기록합니다. +- `specs//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/-/`로 이동합니다. diff --git a/openspec/project.md b/openspec/project.md new file mode 100644 index 000000000..703163af1 --- /dev/null +++ b/openspec/project.md @@ -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 계약 diff --git a/openspec/specs/README.md b/openspec/specs/README.md new file mode 100644 index 000000000..37988b905 --- /dev/null +++ b/openspec/specs/README.md @@ -0,0 +1,39 @@ +# OpenSpec Specs Inventory + +이 디렉토리는 accepted durable requirement를 보관합니다. +현재 repository에는 아직 accepted OpenSpec spec이 없습니다. + +## Inventory 규칙 + +새 accepted spec을 추가할 때 이 파일에 다음 정보를 함께 기록합니다. + +| Spec | 책임 | 관련 surface | 상태 | +| --- | --- | --- | --- | +| `` | `` | `` | 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//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`