@qualisoft/ai-skills 1.0.0

package/skills/project-build/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: project-build
+description: 2단계(project-init) 설계도와 3단계(project-design) 시안을 실제 코드로 구현한다. 스택은 기술 아키텍처 문서에서 읽고, 토큰은 tokens.css 하나를 그대로 물리며, 구현이 시안과 어긋나지 않는지 대조기로 판정한다. 구현 이력이 Docs/_build/ 에 쌓이고 2단계 HTML에서 함께 보인다. "구현 시작", "코드로 만들어줘", "개발 착수", "스캐폴딩", "시안대로 구현", "화면 만들어줘" 같은 요청에 해당한다.
+---
+
+# project-build
+
+**4단계 — 구현.** 설계도와 시안을 돌아가는 코드로 바꾼다.
+
+```
+[1] project-interview   아이디어 → 기획안
+[2] project-init        기획안   → 설계도
+[3] project-design      설계도   → 디자인 규칙 + 시안
+[4] project-build       설계도 + 시안 → 코드            ← 이 스킬
+```
+
+## 이 단계가 지켜야 하는 것
+
+앞 세 단계에서 배운 것이 있다. **문장으로 적힌 금지는 무시된다.**
+3단계에서 "이력 없이 스타일만 고치지 마"가 문서에 있었는데도 그대로 일어났고,
+그때부터 같은 규칙을 검증기로 옮겼다. 여기서도 같다 —
+**막아야 하는 것은 문장이 아니라 검사로 만든다.**
+
+그리고 **시안은 13회 다듬은 결과다.** 그 값을 코드로 옮기면서 흐트러뜨리면
+3단계를 통째로 버리는 것과 같다. 그래서 대조기가 있다.
+
+## 선행 조건
+
+| 문서 | 무엇을 가져오나 |
+| --- | --- |
+| 기술 아키텍처 (`*-tech-architecture`) | **스택·버전·폴더 구조·렌더링 전략.** 여기서 읽지 임의로 고르지 않는다 |
+| PRD (`*-prd`) | `F-01` 형식의 요구사항과 **수용 기준** — 완료 판정의 단일 출처 |
+| IA (`*-information-architecture`) | 사이트맵·URL 규칙·전역 내비 — Route Registry 의 원본 |
+| 화면 정의서 (`*-screen-spec`) | 화면별 섹션 구성·폼 필드·빈 상태 |
+| QA (`*-qa-test-plan`) | 릴리즈 체크리스트 — 배포 게이트 |
+| 접근성 · 성능 · SEO | 비기능 게이트 |
+| 3단계 `_design/` | `tokens.css`(정본) · `design-rules.md` · 시안 · `audit.html` |
+
+**시안이 없는 화면은 만들 수 있다.** 3단계는 방향 확인을 위해 1~3개만 만든다.
+나머지는 **`design-rules.md` 와 `tokens.css` 를 근거로** 4단계가 채운다.
+다만 시안이 있는 화면은 **반드시 그것을 따른다** — 대조기가 판정한다.
+
+**리스크 대장의 Blocker 를 먼저 확인한다.** 인증 방식·법적 표기처럼 미결인 채로 만들면
+다시 만들게 되는 것이 있다. 미결이면 `TODO(주체)` 로 두고 리스크에 올린다.
+
+## 산출물
+
+```
+src/                      구현 코드 (기술 아키텍처의 폴더 구조를 따른다)
+scripts/                  라우트 생성 · 프리렌더 · 사이트맵 · 빌드 검증
+Docs/_build/
+├── build-rules.md         구현 규칙과 근거 (id: build-rules)
+├── change-log.md          구현 이력 (id: build-change-log, BD-001 형식)
+├── parity.html            **시안 ↔ 구현 대조기**
+└── coverage.md            화면 정의서 대비 구현 커버리지
+```
+
+## 진행
+
+### 0. 스택을 문서에서 읽는다
+
+`docs.config.json` 의 `stack` 과 기술 아키텍처 문서가 정본이다.
+**버전을 임의로 올리거나 내리지 않는다.** 문서에 없는 의존성을 추가하려면
+그 이유를 `build-rules.md` 에 적고 사용자에게 알린다.
+
+문서가 미결로 남긴 것(API 프레임워크·프리렌더 도구·인증 방식 등)은
+**결정하지 말고 물어본다.** 답이 없으면 그 부분을 비워 두고 리스크에 올린다.
+
+### 0.5 토큰을 잇는다 — 변환하지 않는다
+
+`Docs/_design/tokens.css` 가 **정본이다.** 복사하지 않고 링크한다.
+
+Tailwind 4 는 CSS-first 라 그대로 물린다:
+
+```css
+/* src/styles/theme.css */
+@import "tailwindcss";
+@import "../../Docs/_design/tokens.css";   /* 정본을 그대로 읽는다 */
+
+@theme inline {
+  --color-ink: var(--ink);
+  --color-bg: var(--bg);
+  --radius-card: var(--radius-card);
+  /* … tokens.css 의 이름을 Tailwind 이름에 연결만 한다 */
+}
+```
+
+**값을 다시 적지 않는다.** 값을 옮겨 적는 순간 두 곳이 되고, 두 곳은 갈라진다.
+3단계에서 실제로 그렇게 갈라진 적이 있다(`DS-007`).
+
+### 1. 대조기를 먼저 놓는다
+
+`templates/parity.html` 을 `Docs/_build/parity.html` 로 복사한다.
+**시안을 코드로 옮기기 전에 놓는다.** 옮기고 나서 만들면 무엇이 흐트러졌는지
+비교 대상이 이미 사라진 뒤다.
+
+대조는 `data-parity="이름"` 표식으로 짝을 맞춘다.
+시안과 구현 양쪽에 같은 이름을 달면 대조기가 크기·색·타이포·형태를 비교한다.
+
+```html
+<!-- 시안 -->            <header class="site-header" data-parity="header">
+<!-- 구현 (Tailwind) -->  <header data-parity="header" className="fixed z-50 …">
+```
+
+**클래스 이름이 달라도 된다.** 그게 재작성을 허용하면서도 값을 지키는 방법이다.
+
+### 2. 뼈대를 만든다
+
+기술 아키텍처의 폴더 구조를 그대로 쓴다. **한 번만 쓰는 추상화는 만들지 않는다.**
+
+- Route Registry 한 곳이 라우터·프리렌더·사이트맵의 기준이 된다
+- IA 의 사이트맵을 Route Registry 로 옮긴다 — 경로를 두 곳에 적지 않는다
+- 공개 콘텐츠가 0건인 경로는 **목록을 숨기고 내비게이션에서도 함께 끈다** (IA 7항)
+
+### 3. 화면을 구현한다
+
+화면 정의서의 섹션 구성을 따른다. **정의서에 있는데 만들지 않은 섹션은 `coverage.md` 에 남긴다.**
+빠뜨린 것과 의도적으로 숨긴 것(콘텐츠 0건)은 다르다 — 구분해서 적는다.
+
+- 확정 카피는 그대로 쓴다. 없는 실적·고객사·수치를 만들지 않는다
+- 폼 필수 항목은 화면 정의서를 따른다. 임의로 줄이지 않는다
+- 상태(`idle`·`submitting`·`success`·`error`·빈 상태·404)를 전부 구현한다.
+  3단계 스타일 가이드에 그려둔 것이 있으면 그것을 따른다
+
+### 4. 판정한다
+
+| 도구 | 무엇을 보나 |
+| --- | --- |
+| `Docs/_build/parity.html` | **시안 ↔ 구현 어긋남** — 크기·색·타이포·형태 |
+| `Docs/_design/audit.html` | 대비·터치 타깃·이탈·상태 전환. **대상 URL 만 dev 서버로 바꾼다** |
+| `npm run build` + `validate-build` | 라우트·프리렌더·죽은 링크 |
+| QA 릴리즈 체크리스트 | 배포 게이트 |
+
+`audit.html` 은 3단계에서 이미 시안을 통과시킨 기준이다.
+**같은 기준을 구현도 통과해야 한다.** 새로 만들지 않고 대상만 바꾼다.
+
+### 5. 기록한다
+
+`change-log.md` 에 `BD-001` 형식으로 남긴다. 형식은 3단계와 같되 항목이 다르다.
+
+```
+## BD-001. 제목
+
+**일자**
+**근거**       어떤 문서·시안·수용 기준(F-xx)을 따랐는가
+**변경**       무엇을 만들었는가
+**대조**       parity.html 결과 — 어긋남 몇 건, 무엇
+**검수**       audit.html 필수 항목 결과 / 빌드 검증
+**확인 못 함**  못 본 것과 그 이유. 없으면 "없음"
+```
+
+## 완료 판정은 PRD 가 한다
+
+"다 됐다"는 느낌이 아니라 **수용 기준**으로 정한다.
+`F-01` 부터 하나씩 대고, 통과하지 못한 것은 통과하지 못했다고 적는다.
+QA 체크리스트의 마지막 줄은 **사용자 최종 승인**이다 — AI 가 대신 체크하지 않는다.
+
+## 하지 말 것
+
+- 문서에 없는 스택·의존성을 말없이 추가하기. **선택 의존성은 실제 요구가 생길 때만.**
+- `tokens.css` 의 값을 코드에 복사해 넣기. 링크한다.
+- 대조기 없이 시안을 재작성하기. 무엇이 흐트러졌는지 알 방법이 사라진다.
+- 시안이 있는 화면을 시안과 다르게 만들고 넘어가기.
+- 화면 정의서의 섹션을 조용히 빠뜨리기. `coverage.md` 에 적는다.
+- 폼 필수 항목을 임의로 줄이기.
+- 상태(빈 상태·오류·404)를 나중으로 미루기. 그 "나중"은 오지 않는다.
+- 백엔드가 없는데 성공 UI 를 띄우기. **서버 성공 응답 뒤에만 성공이다.**
+- 없는 실적·고객사·수치를 채워 넣기.
+- 미결 사항을 대신 결정하기. 물어보고, 답이 없으면 리스크에 올린다.
+- 검수하지 못한 것을 검수한 것처럼 보고하기.
+- 사용자 승인 없이 production 배포하기.

package/skills/project-build/templates/build-rules.md

@@ -0,0 +1,88 @@
+---
+id: build-rules
+title: 구현 규칙
+summary: 4단계에서 정한 구현 규칙과 그 근거.
+status: draft
+date: {{YYYY-MM-DD}}
+---
+
+# 구현 규칙
+
+> **4단계 기록이다.** 스택과 폴더 구조의 정본은 기술 아키텍처 문서다.
+> 여기에는 **그 문서가 정하지 않은 것**과 **구현하며 새로 정한 것**만 적는다.
+
+> **`status` 는 사람만 올린다.** `draft` → `review` → `approved`.
+> 4단계 진행률이 이 값을 읽는다. AI 가 임의로 `approved` 로 바꾸지 않는다.
+
+## 1. 스택 확인
+
+기술 아키텍처 문서에서 읽은 값을 그대로 옮긴다. **여기서 정하지 않는다.**
+
+| 영역 | 값 | 출처 |
+| --- | --- | --- |
+| | | `*-tech-architecture` N항 |
+
+**문서에 없는데 추가한 의존성** — 없으면 "없음"이라고 적는다.
+
+| 패키지 | 왜 필요했나 | 대안을 검토했나 |
+| --- | --- | --- |
+
+## 2. 토큰 연결
+
+`Docs/_design/tokens.css` 가 정본이다. **값을 복사하지 않고 링크한다.**
+
+```css
+/* src/styles/theme.css */
+@import "tailwindcss";
+@import "../../Docs/_design/tokens.css";
+
+@theme inline {
+  --color-ink: var(--ink);
+  /* … 이름만 잇는다 */
+}
+```
+
+값을 옮겨 적으면 두 곳이 되고, 두 곳은 반드시 갈라진다.
+`build.mjs check` 가 복사를 감지해 경고한다.
+
+## 3. 시안 대조 표식
+
+시안과 구현 양쪽에 `data-parity="이름"` 을 단다. 클래스 이름은 달라도 된다.
+
+| 표식 | 시안 | 구현 |
+| --- | --- | --- |
+| `header` | `.site-header` | |
+
+**시안에 없는 화면**은 표식 짝이 없다. 그건 정상이므로 여기에 "시안 없음"으로 적는다 —
+적지 않으면 빠뜨린 것과 구분되지 않는다.
+
+## 4. 문서가 미결로 남긴 것
+
+**대신 결정하지 않는다.** 물어보고, 답이 없으면 비워 두고 리스크에 올린다.
+
+| 항목 | 출처 | 상태 |
+| --- | --- | --- |
+
+## 5. 구현하며 새로 정한 것
+
+기술 아키텍처가 다루지 않은 판단이다. 이유를 함께 적는다.
+
+| 항목 | 결정 | 이유 |
+| --- | --- | --- |
+
+## 6. 기준 예외
+
+시안·설계도를 의도적으로 벗어난 곳. **여기 없는 차이는 버그다.**
+
+| 항목 | 원래 | 실제 | 범위 | 이유 | 보상 조치 |
+| --- | --- | --- | --- | --- | --- |
+
+## 7. 변경 이력
+
+### {{YYYY-MM-DD}}
+
+| 일자 | AI | 계정 |
+| --- | --- | --- |
+| {{YYYY-MM-DD}} | | |
+
+- 최초 작성

package/skills/project-build/templates/change-log.md

@@ -0,0 +1,29 @@
+---
+id: build-change-log
+title: 구현 이력
+summary: 무엇을 어떤 근거로 만들었고 어떻게 판정했는지의 기록.
+date: {{YYYY-MM-DD}}
+---
+
+# 구현 이력
+
+> **4단계 기록이다.** 3단계의 `DS-` 와 구분되는 `BD-` 를 쓴다.
+
+## 기록 규칙
+
+- **화면·기능 단위로** 항목을 추가한다. 몰아서 쓰지 않는다.
+- **근거에 수용 기준 ID(`F-01` 등)를 적는다.** 진행률이 이걸 세고,
+  한 번도 언급되지 않은 수용 기준은 `build.mjs check` 가 경고한다.
+- **대조와 검수 결과를 반드시 적는다.** 비워 두면 "다 봤다"로 읽힌다.
+- 통과하지 못한 것은 통과하지 못했다고 적는다.
+
+---
+
+## BD-001. 제목
+
+**일자** {{YYYY-MM-DD}}
+**근거** 어떤 문서·시안·수용 기준(`F-xx`)을 따랐는가
+**변경** 무엇을 만들었는가
+**대조** `parity.html` — 어긋남 몇 건, 무엇. 표식이 없으면 "표식 없음"
+**검수** `audit.html` 필수 항목 / 빌드 검증 / 릴리즈 체크리스트
+**확인 못 함** 못 본 것과 그 이유. 없으면 "없음"

package/skills/project-build/templates/coverage.md

@@ -0,0 +1,49 @@
+---
+id: build-coverage
+title: 구현 커버리지
+summary: 화면 정의서·IA 대비 실제로 무엇을 만들었는지.
+date: {{YYYY-MM-DD}}
+---
+
+# 구현 커버리지
+
+> **빠뜨린 것과 의도적으로 뺀 것은 다르다.** 그 둘을 구분해 적는 곳이다.
+> 3단계는 방향 확인을 위해 화면 1~3개만 만든다. 나머지를 채우는 것이 4단계이므로,
+> 무엇이 남았는지 여기서만 보이면 된다.
+
+## 상태 표기
+
+| 표기 | 뜻 |
+| --- | --- |
+| ✅ | 구현됨 |
+| 🟡 | 부분 — 무엇이 빠졌는지 적는다 |
+| ⭕ | **의도적으로 뺌** — 근거를 적는다 (예: 콘텐츠 0건 숨김 규칙) |
+| ❌ | 미구현 |
+
+## 1. 경로 (IA 사이트맵 대비)
+
+| 경로 | 상태 | 시안 | 비고 |
+| --- | --- | --- | --- |
+| `/` | | | |
+
+## 2. 화면별 섹션 (화면 정의서 대비)
+
+| 화면 | 섹션 | 상태 | 비고 |
+| --- | --- | --- | --- |
+
+## 3. 상태 화면
+
+| 상태 | 상태 | 비고 |
+| --- | --- | --- |
+| 빈 상태 | | |
+| 404 | | |
+| 폼 `idle` / `submitting` / `success` / `error` | | |
+
+## 4. 수용 기준
+
+| ID | 요구사항 | 상태 | 판정 근거 |
+| --- | --- | --- | --- |
+
+## 5. 남은 것
+
+여기가 비어야 4단계가 끝난다.