diff --git a/.agents/skills/README.md b/.agents/skills/README.md new file mode 100644 index 000000000..2a99b9494 --- /dev/null +++ b/.agents/skills/README.md @@ -0,0 +1,88 @@ +# QueryPie 문서 저장소용 Agent Skills + +이 디렉토리는 QueryPie 문서 저장소에서 다양한 작업을 수행하는 데 도움이 되는 Agent skills를 포함합니다. + +표준 layout: + +```text +.agents/skills//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/` diff --git a/.claude/skills/code-review.md b/.agents/skills/code-review/SKILL.md similarity index 94% rename from .claude/skills/code-review.md rename to .agents/skills/code-review/SKILL.md index e898efb2c..6fdd12a4f 100644 --- a/.claude/skills/code-review.md +++ b/.agents/skills/code-review/SKILL.md @@ -24,7 +24,7 @@ QueryPie 문서 저장소의 변경 사항을 검토하기 위한 가이드라 - 모든 언어(en, ja, ko) 버전이 업데이트되었는지 확인 - 언어 간 동일한 구조 확인 -- 번역 품질 확인 — [translation.md](translation.md) 참조 +- 번역 품질 확인 — [translation.md](../translation/SKILL.md) 참조 ### 빌드 및 배포 diff --git a/.claude/skills/commit.md b/.agents/skills/commit/SKILL.md similarity index 100% rename from .claude/skills/commit.md rename to .agents/skills/commit/SKILL.md diff --git a/.claude/skills/confluence-mdx-testcase.md b/.agents/skills/confluence-mdx-testcase/SKILL.md similarity index 100% rename from .claude/skills/confluence-mdx-testcase.md rename to .agents/skills/confluence-mdx-testcase/SKILL.md diff --git a/.claude/skills/confluence-mdx.md b/.agents/skills/confluence-mdx/SKILL.md similarity index 100% rename from .claude/skills/confluence-mdx.md rename to .agents/skills/confluence-mdx/SKILL.md diff --git a/.claude/skills/confluence-pr-update.md b/.agents/skills/confluence-pr-update/SKILL.md similarity index 90% rename from .claude/skills/confluence-pr-update.md rename to .agents/skills/confluence-pr-update/SKILL.md index efb5613ef..af26f5397 100644 --- a/.claude/skills/confluence-pr-update.md +++ b/.agents/skills/confluence-pr-update/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,7 +177,7 @@ git status public/ ### Skeleton 불일치가 발생한 경우 -[mdx-skeleton-comparison.md](mdx-skeleton-comparison.md)의 "불일치 발견 시 처리 방법"을 참조하세요. +[mdx-skeleton-comparison.md](../mdx-skeleton-comparison/SKILL.md)의 "불일치 발견 시 처리 방법"을 참조하세요. ### 코드 블록 내 주석이 번역된 경우 @@ -185,7 +185,7 @@ git status public/ ## 관련 문서 -- **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) diff --git a/.claude/skills/mdx-skeleton-comparison.md b/.agents/skills/mdx-skeleton-comparison/SKILL.md similarity index 99% rename from .claude/skills/mdx-skeleton-comparison.md rename to .agents/skills/mdx-skeleton-comparison/SKILL.md index 3014022de..7c8a7c841 100644 --- a/.claude/skills/mdx-skeleton-comparison.md +++ b/.agents/skills/mdx-skeleton-comparison/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) diff --git a/.agents/skills/openspec-authoring/SKILL.md b/.agents/skills/openspec-authoring/SKILL.md new file mode 100644 index 000000000..6f6854d0f --- /dev/null +++ b/.agents/skills/openspec-authoring/SKILL.md @@ -0,0 +1,154 @@ +# OpenSpec Authoring + +QueryPie 문서 저장소에서 OpenSpec spec, proposal, design, tasks를 새로 작성하거나 크게 갱신할 때 사용합니다. +목표는 `openspec/`를 일회성 계획이 아니라 구현자가 따라야 하는 durable contract layer로 유지하는 것입니다. + +## 사용 시점 + +- 새 `openspec/specs//spec.md`를 작성할 때 +- 기존 OpenSpec spec의 Requirement 또는 Scenario를 크게 바꿀 때 +- 요구사항 변경을 `openspec/changes//` 아래 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//tasks.md`에 둡니다. +- 제품/기술/운영 의사결정은 필요한 경우 `openspec/changes//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 +# + +## Purpose + +## References + +## Requirements + +### Requirement: + +<한국어 계약 문장>(SHALL). + +#### Scenario: + +- 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//proposal.md`와 `tasks.md`부터 작성합니다. +3. decision, alternative, migration, risk가 있으면 `design.md`를 추가합니다. +4. 기존 accepted spec을 즉시 바꾸면 구현과 충돌할 수 있을 때는 `changes//specs//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 회귀를 놓치는 것 diff --git a/.agents/skills/openspec-doc-maintenance/SKILL.md b/.agents/skills/openspec-doc-maintenance/SKILL.md new file mode 100644 index 000000000..ee8b81df9 --- /dev/null +++ b/.agents/skills/openspec-doc-maintenance/SKILL.md @@ -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.md` + - proposed requirement change는 `openspec/changes//proposal.md` + - Decision, alternative, migration, risk는 `openspec/changes//design.md` + - 후속 구현과 검증 범위는 `openspec/changes//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를 불필요하게 막는 것 diff --git a/.agents/skills/openspec-task-execution/SKILL.md b/.agents/skills/openspec-task-execution/SKILL.md new file mode 100644 index 000000000..cb1de1b2d --- /dev/null +++ b/.agents/skills/openspec-task-execution/SKILL.md @@ -0,0 +1,170 @@ +# OpenSpec Task Execution + +QueryPie 문서 저장소에서 OpenSpec changes/specs에 남은 `tasks.md` 항목, 후속 구현, verification 보강, PR-sized 작업 수행을 요청받았을 때 사용합니다. +목표는 OpenSpec을 source of truth로 삼아 남은 작업을 우선순위와 PR-sized 단위로 나누고, 기존 Open PR과 구현 drift를 먼저 확인한 뒤, 준비된 작업은 PR로 만들고 막힌 작업은 blocker report로 모으는 것입니다. + +## 함께 읽을 skill + +- 작업 시작 시 `.agents/skills/README.md`, `openspec/README.md`, `openspec/project.md`를 읽습니다. +- OpenSpec 문서의 모순, 누락, stale Scenario, 구현과의 drift가 확인되면 `.agents/skills/openspec-doc-maintenance/SKILL.md`를 읽고 OpenSpec 수정 작업을 분리합니다. +- 새 spec, proposal, design, tasks를 작성하거나 큰 요구사항 변경을 기록해야 하면 `.agents/skills/openspec-authoring/SKILL.md`를 읽습니다. +- PR 생성 전에는 active runtime에 `create-pr` skill이 있으면 읽고, 없으면 `AGENTS.md`와 `docs/commit-pr-guide.md`를 따릅니다. + +## 사용 시점 + +- `openspec/changes//tasks.md`에 남은 항목을 실행해야 할 때 +- Accepted spec의 Scenario 또는 Requirement를 기준으로 구현 또는 검증 gap을 메워야 할 때 +- 특정 OpenSpec change, PR, branch 작업을 이어받아 task 완료 여부를 검증해야 할 때 +- OpenSpec은 존재하지만 현재 코드와 맞는지 확신이 없어 drift 검사부터 필요한 때 +- 준비된 작업과 blocker를 분리해 PR, PR 본문, GitHub Issue 또는 최종 보고로 남겨야 할 때 + +사용하지 않습니다: + +- OpenSpec 문서만 새로 작성하거나 정리하는 작업은 `openspec-authoring` 또는 `openspec-doc-maintenance`를 우선합니다. +- 단순 MDX 번역/교정 작업은 번역/교정 skill을 우선합니다. +- Confluence 변환 또는 reverse sync 작업은 관련 Confluence/reverse sync skill을 우선합니다. +- 단순 code review는 code-review workflow나 일반 review 지침을 우선합니다. + +## 우선순위 수행 규칙 + +OpenSpec task와 backlog 항목은 가능하면 `P1`, `P2`, `P3`, `Backlog` 네 단계 우선순위를 사용합니다. +명시 우선순위가 없는 과제는 기본 `P3`로 간주하되, 사용자의 최신 지시나 해당 OpenSpec change의 priority table이 있으면 그것을 우선합니다. + +수행 순서는 다음을 따릅니다. + +1. `P1` 과제를 먼저 수행합니다. +2. `P1` 과제 중 `blocked`와 `Backlog`가 아닌 과제를 모두 처리한 뒤 `P2`로 넘어갑니다. +3. `P2` 과제 중 `blocked`와 `Backlog`가 아닌 과제를 모두 처리한 뒤 `P3`로 넘어갑니다. +4. `P3` 과제 중 `blocked`와 `Backlog`가 아닌 과제를 모두 처리하면 남은 `Backlog`와 blocker를 보고합니다. + +우선순위 등급의 완료 범위는 `blocked`와 `Backlog`를 제외한 task만 포함합니다. +Product Owner 또는 stakeholder 결정, 외부 credential/session/production 권한, irreversible operation, acceptance criteria 부재, 사용자의 명시 승인 없이는 할 수 없는 PR approve/merge/close 같은 blocker로 막힌 task는 해당 등급의 완료 판단에서 제외합니다. + +한 우선순위 등급에서 다음 등급으로 넘어갈 수 있는 조건은 다음 중 하나입니다. + +- 해당 등급의 non-blocked task가 최신 `origin/main` 기준으로 이미 완료되어 있습니다. +- agent가 해당 task를 PR-sized 범위로 구현/문서화/검증하고 branch를 push했으며 PR 본문, focused verification, 필요한 GitHub check 상태를 보고했습니다. +- 이미 열린 PR이 해당 task를 실제 diff와 검증 evidence로 커버하고 있어 `already-covered-by-open-pr`로 분류됩니다. +- 남은 미처리 항목은 `blocked` 또는 `Backlog`로 분류되어 blocker report나 완료 보고에 기록되어 있습니다. + +열린 PR이 merge되지 않았다는 사실만으로 다음 우선순위 등급 진입을 막지 않습니다. +다만 그 PR이 conflict, failing required check, missing focused verification, 잘못된 base/head, 불명확한 coverage를 가진 경우에는 `already-covered-by-open-pr`로 보지 말고 현재 우선순위에서 repair 또는 follow-up을 먼저 수행합니다. + +`Backlog` 우선순위는 구현 대상이 아닙니다. +사용자의 명시적인 지시와 Product Owner/stakeholder 결정 또는 OpenSpec change를 통한 `P1`, `P2`, `P3` 승격이 모두 있어야 작업 대상으로 삼습니다. + +## 실행 절차 + +1. Open PR의 구현 내용을 먼저 파악합니다. + - `gh pr list --state open`으로 현재 열린 PR 목록을 확인합니다. + - 관련 후보 PR은 `gh pr view --json title,body,author,headRefName,baseRefName,files,commits,url`과 `gh pr diff ` 또는 `gh pr diff --name-only`로 구현 의도, 변경 파일, 실제 diff, 검증 흔적을 확인합니다. + - Open PR에서 이미 진행 중인 작업을 `in-flight work inventory`로 기록하고, OpenSpec 문서만 보고 새 작업을 먼저 시작하지 않습니다. +2. 기준 OpenSpec을 찾습니다. + - `openspec/changes//tasks.md`, `proposal.md`, `design.md`, `specs/**/spec.md`를 우선 확인합니다. + - 이미 archive된 change라면 현재 `openspec/specs/**/spec.md`와 관련 문서에서 active 계약을 확인합니다. + - 기준 change가 둘 이상이면 task와 PR을 change 단위로 분리합니다. +3. task inventory를 만들고 Open PR과 매핑합니다. + - unchecked task, follow-up task, Scenario, Requirement, affected code path, 필요한 검증 명령을 한 묶음으로 정리합니다. + - 각 task의 우선순위를 `P1`, `P2`, `P3`, `Backlog` 중 하나로 기록합니다. + - task에 우선순위가 명시되어 있지 않으면 `P3`로 기록합니다. + - `Backlog` task는 Product Owner/stakeholder 결정 또는 OpenSpec change로 승격되기 전까지 실행 inventory에서 제외하고 backlog/report inventory에만 기록합니다. + - task가 너무 크면 하나의 검증 가능한 사용자 가치 또는 OpenSpec requirement 단위로 쪼갭니다. + - 각 task마다 매핑되는 Open PR 번호, 매핑 근거, coverage 상태를 기록합니다. + - coverage 상태는 `covered`, `partially-covered`, `not-covered`, `unclear` 중 하나로 둡니다. + - Open PR이 해당 작업을 실제로 수행했는지 PR 제목이나 설명만으로 판단하지 말고 diff와 affected path를 확인합니다. + - 다른 사람 또는 다른 agent가 해당 작업에 적합한 Open PR을 이미 작성했다면 같은 작업을 새로 수행하지 않습니다. +4. 각 task를 분류합니다. + - `ready-implementation`: OpenSpec이 유효하고, 해당 작업에 적합한 Open PR이 없으며, 코드 구현이 부족합니다. + - `ready-openspec-maintenance`: 코드 또는 제품 결정은 명확하지만 OpenSpec이 stale이거나 누락되어 먼저 문서 PR이 필요합니다. + - `ready-verification`: 구현과 OpenSpec은 맞고 검증 증거만 보강하면 됩니다. + - `already-covered-by-open-pr`: 해당 task를 처리하기에 적합한 Open PR이 이미 있어 중복 수행하지 않고 PR 링크와 확인 결과만 보고합니다. + - `partially-covered-by-open-pr`: Open PR이 task 일부만 처리했으므로 남은 범위를 명시하고 별도 task 또는 follow-up으로 분리합니다. + - `blocked`: 의사결정, 추가 정보, 외부 권한, 상충 요구사항 때문에 작업을 안전하게 확정할 수 없습니다. +5. OpenSpec과 코드 구현의 drift를 판정합니다. + - OpenSpec이 현재 의도와 다르면 OpenSpec 수정 PR을 먼저 만듭니다. + - OpenSpec이 맞고 코드가 뒤처져 있으면 구현 PR을 만듭니다. + - OpenSpec과 코드가 모두 바뀌어야 하면 OpenSpec PR을 먼저 만들고, 구현 PR은 그 PR branch를 base로 둔 stacked PR로 분리합니다. + - Open PR의 구현 내용이 OpenSpec task에 매핑되는지 확인한 뒤, 매핑되지 않은 잔여 task만 새로 수행할 작업으로 판정합니다. + - drift 판정 결과와 Open PR 매핑 결과를 PR 본문 또는 blocker report에 남깁니다. +6. 과제 단위로 PR을 분리합니다. + - 서로 독립적인 OpenSpec task를 한 PR에 묶지 않습니다. + - spec-only, implementation, verification/docs evidence PR은 원자성이 없으면 분리합니다. + - 각 PR은 하나의 명확한 완료 조건과 검증 명령을 가져야 합니다. + - 구현 완료 후 focused local verification을 실행하고 commit/push/PR 생성 또는 업데이트를 먼저 완료합니다. + - 추가 GitHub checks, browser rendering 검증은 PR 생성 또는 업데이트 이후 bounded 방식으로 확인합니다. +7. blocker를 모아서 보고합니다. + - blocker는 chat에만 남기지 말고 PR 본문, 최종 보고, 또는 GitHub Issue에 모읍니다. + - GitHub Issue가 필요하고 인증이 가능하면 `gh issue create` 또는 `gh issue comment`를 사용합니다. + - issue는 자동 종료 keyword를 사용하지 않습니다. +8. 검증합니다. + - 문서 변경은 `git diff --check`와 관련 경로 검색으로 검증합니다. + - 코드 변경은 task에 직접 연결되는 테스트를 먼저 실행하고, 위험도에 따라 lint, typecheck, build, e2e를 추가합니다. + - GitHub check는 bounded 확인만 수행하고, 오래 걸리면 latest known state와 미확인 범위를 보고합니다. +9. 완료 보고를 작성합니다. + - 생성한 PR, task 출처, Open PR 구현 매핑 결과, 중복 방지 확인 결과, drift 판정, blocker report, 검증 결과, 남은 위험을 요약합니다. + - 우선순위 전환이 있었다면 해당 우선순위의 non-blocked task 처리 결과와 완료 범위에서 제외한 blocker 목록을 구분해 적습니다. + - 사용자의 명시적 승인 없이 PR approve, merge, close 또는 `main` 직접 push를 하지 않습니다. + +## Blocker 판정 기준 + +다음은 blocker로 분류합니다. + +- Product Owner 또는 stakeholder의 scope, UX, 용어, 우선순위, 정책 결정이 필요한 경우 +- OpenSpec Requirement 또는 Scenario끼리 충돌해 구현 기준을 하나로 고를 수 없는 경우 +- 외부 계정, credential, production 권한, 제3자 서비스 상태가 필요하고 agent가 안전하게 대체할 수 없는 경우 +- data migration, 삭제, irreversible operation처럼 안전 경계가 필요한 경우 +- acceptance criteria가 없어 선택지별 구현 결과가 사용자 행동이나 데이터 계약을 바꾸는 경우 +- agent가 PR branch를 push하고 필요한 검증을 보고했지만 사용자의 명시 승인 없이는 PR approve, merge, close, direct `main` push를 할 수 없는 경우 + +다음은 blocker로 분류하지 않습니다. + +- 일반적인 코드 검색, 영향 범위 조사, 테스트 실패 원인 분석 +- OpenSpec에서 합리적으로 추론 가능한 작은 구현 세부사항 +- 단순 lint, typecheck, formatting 실패 + +## Blocker report 템플릿 + +```md +## 요약 + +- 기준 OpenSpec: `` +- 실행하려던 작업 범위: `` +- 현재 진행 상태: `<완료, 진행 중, 중단된 항목 요약>` + +## Blocker 목록 + +| Task | 수행하려던 작업 | Blocker인 이유 | 고민 중인 선택지 | 필요한 의사결정 또는 정보 | 영향 범위 | 제안 next action | +| --- | --- | --- | --- | --- | --- | --- | +| `` | `<구체적 작업>` | `<왜 안전하게 진행할 수 없는지>` | `