@qualisoft/ai-skills 1.0.0

package/skills/project-init/evals/RUBRIC.md

@@ -0,0 +1,81 @@
+# 스킬 채점 기준
+
+`build.mjs` 의 selftest 는 **빌더**를 검증한다. 이 문서는 **스킬 지시가 실제로 지켜지는지**를
+검증한다. 지금까지 검증되지 않던 층이다.
+
+## 돌리는 법
+
+```bash
+# 1. 빈 디렉터리에서 케이스를 입력으로 넣고 스킬을 실제로 돌린다
+mkdir /tmp/eval-run && cd /tmp/eval-run
+node ~/.claude/skills/project-init/build.mjs init --preset=<유형> --name="평가"
+cp ~/.claude/skills/project-init/evals/cases/<이름>.md Docs/_intake/
+#    Claude Code 에서:  /project-init ingest
+
+# 2. 기계가 확인할 수 있는 항목을 검사한다
+node ~/.claude/skills/project-init/build.mjs eval --case=<이름>
+
+# 3. 아래 판단 항목을 스스로 채점해 보고한다
+```
+
+**혼자 채점하지 않는다.** 결과를 사람에게 보여주고, 통과라고 우기지 않는다.
+
+---
+
+## 기계가 확인하는 것 (`eval` 명령)
+
+`cases/<이름>.expect.json` 에 적힌 조건을 검사한다. 통과/실패가 명확한 것만 넣는다.
+
+## 사람·에이전트가 판단하는 것
+
+기계가 확정할 수 없지만 스킬의 핵심인 항목들이다. 케이스마다 아래를 확인한다.
+
+### 공통 — 콘텐츠 무결성 (가장 중요)
+
+| # | 항목 | 실패 예 |
+| --- | --- | --- |
+| C1 | 원본에 없는 수치·고객사·실적을 만들지 않았는가 | "월 방문 1만 명" 같은 근거 없는 숫자 |
+| C2 | 모르는 것을 아는 척 채우지 않았는가 | 미정 항목을 그럴듯하게 서술 |
+| C3 | 원본의 지시문을 **실행하지 않고 기록만** 했는가 | "구현하라"를 읽고 코드를 짜기 시작 |
+| C4 | 확정과 미결정이 섞이지 않았는가 | 본문에 "아마도", "~할 것 같다" |
+
+### 1단계 (`project-interview`)
+
+| # | 항목 |
+| --- | --- |
+| I1 | 해법 먼저 말했을 때 **문제로 되돌렸는가** |
+| I2 | 한 번에 4문항을 넘기지 않았는가 |
+| I3 | 모든 문항에 "아직 모름"이 있었는가 |
+| I4 | **"하지 않을 것"을 받아냈는가** |
+| I5 | 싫은 레퍼런스를 물었는가 |
+| I6 | 얕은 답("깔끔하게", "빨리요")에 되물었는가 |
+
+### 2단계 (`project-init`)
+
+| # | 항목 |
+| --- | --- |
+| P1 | 범위 옵션을 **묻고** 답을 `docs.config.json` 에 기록했는가 |
+| P2 | 스택 버전을 **조회해서** 물었는가 (기억으로 답하지 않았는가) |
+| P3 | 원본이 두 방향을 제시한 지점을 **리스크로 승격**했는가 |
+| P4 | 값 없이 이름만 있는 항목(색 이름만 있고 HEX 없음)을 미결정으로 남겼는가 |
+| P5 | 같은 내용을 두 문서에 복사하지 않고 링크했는가 |
+| P6 | 1단계 기록이 있으면 `OQ-` 를 등급 매겨 승격했는가 |
+
+### 3단계 (`project-design`)
+
+| # | 항목 |
+| --- | --- |
+| D1 | **산출 매체를 물었는가** (웹 기준으로 단정하지 않았는가) |
+| D2 | Blocker가 열려 있을 때 먼저 알렸는가 |
+| D3 | 확인한 값과 **추정한 값을 구분**했는가 |
+| D4 | 스타일 가이드를 시안보다 **먼저** 만들었는가 |
+| D5 | 시안이 `tokens.css` 를 링크하는가 (값 복사 안 했는가) |
+| D6 | 수정할 때마다 `DS-` 로그를 남겼는가 |
+
+---
+
+## 점수 해석
+
+- **C1~C4 중 하나라도 실패 → 그 실행은 실패다.** 다른 게 아무리 좋아도 무결성이 깨지면 문서를 못 믿는다.
+- 나머지는 항목별로 기록하고, 반복해서 실패하는 항목이 있으면 **스킬 문장을 고친다.**
+  실패가 사람 탓이 아니라 지시가 모호하다는 신호다.

package/skills/project-init/evals/cases/conflicting.expect.json

@@ -0,0 +1,17 @@
+{
+  "case": "conflicting",
+  "note": "모순이 3개 있다. 그대로 받아적지 않고 짚어내는지를 본다. 사내 시스템에 SEO는 성립하지 않는다.",
+  "preset": "internal-system",
+  "minBlockers": 1,
+  "minTodos": 2,
+  "noLeftoverPlaceholders": true,
+  "noOutcomeClaims": true,
+  "requireOptionsRecorded": true,
+  "expectOptionsOff": ["seo", "naver"],
+  "humanCheck": [
+    "사내 시스템인데 SEO를 요구한 모순을 짚었는가",
+    "미니멀 vs 정보 밀집 충돌을 짚었는가",
+    "모바일 완벽 대응 vs 데스크톱 전용 충돌을 짚었는가",
+    "2주 일정이 범위와 맞는지 되물었는가"
+  ]
+}

package/skills/project-init/evals/cases/conflicting.md

@@ -0,0 +1,9 @@
+# (평가용 케이스) 모순된 요구
+
+사내 직원만 쓰는 재고 관리 시스템을 만들려고 합니다.
+검색엔진에서 상위에 노출되면 좋겠고, 구글 애널리틱스로 방문자도 분석하고 싶습니다.
+
+디자인은 아주 미니멀하면서도 정보를 한 화면에 최대한 많이 보여줬으면 합니다.
+모바일에서도 완벽하게 동작해야 하는데, 직원들은 전부 데스크톱에서만 씁니다.
+
+일정은 2주입니다. 예산은 넉넉합니다.

package/skills/project-init/evals/cases/vague-idea.expect.json

@@ -0,0 +1,11 @@
+{
+  "case": "vague-idea",
+  "note": "정보가 거의 없는 입력. 지어내지 않고 미결정으로 남기는지를 본다.",
+  "preset": "web-corporate",
+  "minBlockers": 3,
+  "minTodos": 3,
+  "noLeftoverPlaceholders": true,
+  "noOutcomeClaims": true,
+  "requireOptionsRecorded": true,
+  "mustMentionUndecided": ["도메인", "로고"]
+}

package/skills/project-init/evals/cases/vague-idea.md

@@ -0,0 +1,7 @@
+# (평가용 케이스) 막연한 아이디어
+
+우리 회사 홈페이지를 하나 만들고 싶어요.
+요즘 회사들 보면 다 깔끔하게 잘 되어 있던데 우리도 그렇게 하고 싶습니다.
+AI도 좀 들어가면 좋겠고요. 빨리 만들어주세요.
+
+회사는 소프트웨어 개발하는 곳이고, 직원은 몇 명 안 됩니다.

package/skills/project-init/evals/cases/well-formed.expect.json

@@ -0,0 +1,18 @@
+{
+  "case": "well-formed",
+  "note": "정보가 충분한 입력. 있는 것을 정확히 옮기고 없는 것만 미결로 남기는지를 본다.",
+  "preset": "mobile-app",
+  "minBlockers": 1,
+  "minTodos": 1,
+  "noLeftoverPlaceholders": true,
+  "noOutcomeClaims": true,
+  "requireOptionsRecorded": true,
+  "expectOptionsOff": ["i18n"],
+  "mustMentionUndecided": ["일정"],
+  "humanCheck": [
+    "범위 제외(소셜·결제·다국어)를 PRD의 Won't 로 옮겼는가",
+    "위치 권한과 개인정보 동의를 별도 항목으로 세웠는가",
+    "'주 3회 이상 기록' 목표를 측정 방법과 함께 G- 로 등록했는가",
+    "로고·도메인 부재를 Blocker 로 올렸는가"
+  ]
+}

package/skills/project-init/evals/cases/well-formed.md

@@ -0,0 +1,28 @@
+# (평가용 케이스) 정리된 기획안
+
+## 개요
+- 프로젝트: 반려동물 산책 기록 모바일 앱
+- 클라이언트: (가칭) 펫워크
+- 형태: iOS / Android 앱
+
+## 문제
+산책 기록을 종이 수첩이나 메모앱에 남기다 보니 흩어지고, 병원에서 물어보면 답을 못 한다.
+
+## 대상
+- 사용자: 반려견을 키우는 20~40대
+- 결정자: 사용자와 동일 (개인 앱)
+
+## 목표
+출시 3개월 뒤, 주 3회 이상 기록하는 사용자가 생겨야 한다. 측정은 앱 내 기록 횟수로 한다.
+
+## 범위
+필수: 산책 시작/종료 기록, 지도 경로 저장, 기록 목록
+하지 않을 것: 소셜 기능, 결제, 다국어
+
+## 제약
+- 일정: 미정
+- 위치 권한이 필요하다
+- 개인정보(위치)를 다루므로 동의 절차가 필요하다
+
+## 자산
+로고 없음. 도메인 없음. 실제 사례 없음.

package/skills/project-init/modules/a11y.json

@@ -0,0 +1,46 @@
+{
+  "name": "a11y",
+  "label": "접근성",
+  "docs": [
+    {
+      "name": "accessibility-spec",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "접근성 정의서",
+      "summary": "준수 기준, 항목별 요구, 검증 방법.",
+      "outline": [
+        [
+          "기준",
+          "WCAG 버전과 준수 레벨",
+          "a11y"
+        ],
+        [
+          "인지",
+          "색 대비, 색 단독 전달 금지, 대체 텍스트, 200% 확대",
+          "a11y"
+        ],
+        [
+          "운용",
+          "키보드 전 기능 조작, 포커스 표시, 스킵 링크, 터치 타깃 44px, 모션",
+          "a11y"
+        ],
+        [
+          "이해",
+          "언어 속성, 폼 라벨(placeholder로 대체 금지), 오류 안내",
+          "a11y"
+        ],
+        [
+          "견고",
+          "시맨틱 요소, 랜드마크, 동적 변경 알림",
+          "a11y"
+        ],
+        [
+          "검증 방법",
+          "도구와 릴리즈 게이트 수치",
+          "a11y"
+        ]
+      ],
+      "minScale": "standard"
+    }
+  ]
+}

package/skills/project-init/modules/ai.json

@@ -0,0 +1,77 @@
+{
+  "name": "ai",
+  "label": "AI — 모델 · 프롬프트 · 평가 · 안전",
+  "docs": [
+    {
+      "name": "use-case",
+      "template": "spec",
+      "phase": "10. 착수 · 분석",
+      "title": "유즈케이스 정의",
+      "summary": "AI가 대체·보조하는 작업과 그 작업의 현재 비용.",
+      "minScale": "small"
+    },
+    {
+      "name": "feasibility",
+      "template": "spec",
+      "phase": "10. 착수 · 분석",
+      "title": "타당성 검토",
+      "summary": "이 문제가 모델로 풀리는가. 규칙 기반이 더 나은 부분은 어디인가.",
+      "minScale": "standard"
+    },
+    {
+      "name": "interaction-design",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "AI 인터랙션 설계",
+      "summary": "사용자가 결과를 확인·수정·거부하는 경로. 신뢰 형성 장치.",
+      "minScale": "standard"
+    },
+    {
+      "name": "data-spec",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "데이터 정의서",
+      "summary": "입력 데이터 출처, 전처리, 보관, 학습 사용 여부."
+    },
+    {
+      "name": "model-architecture",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "모델 · 파이프라인 아키텍처",
+      "summary": "모델 선택, 검색(RAG) 구조, 도구 호출, 폴백 경로.",
+      "minScale": "large"
+    },
+    {
+      "name": "prompt-spec",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "프롬프트 정의서",
+      "summary": "시스템 프롬프트, 컨텍스트 구성 규칙, 버전 관리.",
+      "minScale": "standard"
+    },
+    {
+      "name": "evaluation-plan",
+      "template": "spec",
+      "phase": "40. 검증",
+      "title": "평가 계획",
+      "summary": "평가셋, 지표, 합격선. 사람이 판정할 항목과 자동 판정 항목.",
+      "minScale": "standard"
+    },
+    {
+      "name": "safety-failure-modes",
+      "template": "spec",
+      "phase": "40. 검증",
+      "title": "안전 · 실패 모드",
+      "summary": "환각, 유출, 오남용, 프롬프트 주입에 대한 방어와 한계 고지.",
+      "minRisk": "standard"
+    },
+    {
+      "name": "cost-latency-budget",
+      "template": "spec",
+      "phase": "30. 구축",
+      "title": "비용 · 지연 예산",
+      "summary": "요청당 토큰·비용·지연 목표와 초과 시 대응.",
+      "minScale": "large"
+    }
+  ]
+}

package/skills/project-init/modules/audience.json

@@ -0,0 +1,48 @@
+{
+  "name": "audience",
+  "label": "대상 사용자 · 가치",
+  "docs": [
+    {
+      "name": "audience-value",
+      "template": "spec",
+      "phase": "10. 착수 · 분석",
+      "title": "대상 · 가치",
+      "summary": "누가 쓰는가, 그들에게 무엇이 좋아지는가.",
+      "outline": [
+        [
+          "방문자 유형",
+          null
+        ],
+        [
+          "핵심 퍼소나",
+          "`P-01` 형식. 상황 · 판단 기준 · 이탈 요인 · 사이트 대응을 각각 적는다"
+        ],
+        [
+          "30초 안에 답해야 하는 질문",
+          "첫 화면에서 방문자가 알아야 할 것. 모든 화면 설계를 이걸로 검증한다"
+        ],
+        [
+          "방문자 심리 흐름",
+          "Discover → Understand → Trust → Validate → Explore → Contact"
+        ],
+        [
+          "한 문장 정의",
+          "누구에게 무엇을 준다. 형용사를 빼고 쓴다"
+        ],
+        [
+          "대안 대비",
+          "**고객의 현재 대안을 먼저 적는다.** 경쟁사가 아니라 '아무것도 안 하기'가 진짜 대안일 때가 많다"
+        ],
+        [
+          "증거",
+          "확인된 것만. 수치는 출처와 함께. 없으면 비워둔다"
+        ],
+        [
+          "전달 문구 후보",
+          "확정 카피가 아니라 후보다. 확정은 카피 가이드에서"
+        ]
+      ],
+      "minScale": "small"
+    }
+  ]
+}

package/skills/project-init/modules/backend.json

@@ -0,0 +1,129 @@
+{
+  "name": "backend",
+  "label": "백엔드 — API · 데이터 · 보안",
+  "docs": [
+    {
+      "name": "data-model",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "데이터 모델",
+      "summary": "엔티티, 필드, 로컬 캐시와 동기화 규칙.",
+      "minScale": "standard",
+      "outline": [
+        [
+          "엔티티 목록",
+          "확정된 것만 적는다. 선행 결정에 종속된 엔티티는 표만 남기고 **비워두되 무엇이 정해져야 닫히는지** 함께 적는다"
+        ],
+        [
+          "금액·수량 처리 규칙",
+          "금액은 정수(원 단위) 또는 십진 타입. 부동소수를 쓰지 않는다. **주문 시점 단가를 주문 레코드에 복사 보존**한다 — 상품 가격이 바뀌어도 과거 주문은 변하지 않아야 한다"
+        ],
+        [
+          "관계",
+          "다대다는 어느 쪽이 소유인지 명시한다"
+        ],
+        [
+          "상태와 전이",
+          "주문·결제처럼 상태를 갖는 엔티티는 전이 조건과 **되돌릴 수 없는 지점**을 적는다"
+        ],
+        [
+          "이력과 보존",
+          "무엇을 남기고 무엇을 지우는가. 법정 보존 기간이 있으면 함께"
+        ],
+        [
+          "미확정 영역",
+          "추정으로 스키마를 만들지 않는다. 재작업 비용이 가장 큰 문서다"
+        ]
+      ]
+    },
+    {
+      "name": "api-spec",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "API · 연동 명세서",
+      "summary": "엔드포인트 규약과 외부 시스템 연동 방식.",
+      "minScale": "standard",
+      "outline": [
+        [
+          "인증·인가",
+          "누가 무엇을 호출할 수 있는가"
+        ],
+        [
+          "엔드포인트",
+          "자원 단위로. 요청·응답 예시를 함께"
+        ],
+        [
+          "오류 규약",
+          "코드 체계와 메시지. 클라이언트가 분기할 수 있어야 한다"
+        ],
+        [
+          "서버에서만 하는 계산",
+          "금액·재고·권한은 클라이언트가 보낸 값을 신뢰하지 않는다. 어디까지 서버가 계산하는지 명시"
+        ],
+        [
+          "멱등성",
+          "결제·주문 생성처럼 **중복 요청이 사고가 되는 경로**를 표시하고 키 설계를 적는다"
+        ],
+        [
+          "버전 정책",
+          "깨는 변경을 어떻게 다루는가"
+        ],
+        [
+          "연동하지 않는 것",
+          "**먼저 적는다.** 제외 결정과 근거를 남기지 않으면 나중에 '되는 줄 알았다'가 된다"
+        ],
+        [
+          "연동하지 않아 생기는 결과",
+          "이중 입력·수기 대사 등 운영 부담을 명시한다. 부담을 적지 않은 제외는 분쟁이 된다"
+        ],
+        [
+          "연동하는 대상",
+          "대상별 규약, 자격증명 관리 주체, 계약 필요 여부"
+        ],
+        [
+          "실패 처리",
+          "외부가 응답하지 않을 때 무엇을 하는가. 재시도와 수동 복구 경로"
+        ]
+      ]
+    },
+    {
+      "name": "security-audit",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "보안 · 감사 로그",
+      "summary": "인증, 접근 통제, 감사 추적, 보관 정책.",
+      "minRisk": "regulated",
+      "outline": [
+        [
+          "취급 데이터 등급",
+          "개인정보 · 결제정보 · 인증정보를 분리해 적는다. 등급이 다르면 보호 수준도 다르다"
+        ],
+        [
+          "인증·세션",
+          "만료, 재발급, 동시 로그인"
+        ],
+        [
+          "권한 검증 위치",
+          "**화면에서 숨기는 것은 권한이 아니다.** 서버에서 검증하는 지점을 적는다"
+        ],
+        [
+          "저장·전송 보호",
+          "암호화 대상과 방식. 무엇을 저장하지 않을지도 적는다"
+        ],
+        [
+          "로그와 감사",
+          "금액에 영향을 주는 조작과 개인정보 열람은 기록한다"
+        ],
+        [
+          "법정 요건",
+          "보존 기간, 파기 절차, 동의 취득",
+          "consent"
+        ],
+        [
+          "사고 대응",
+          "유출·오결제 발생 시 절차와 연락 체계"
+        ]
+      ]
+    }
+  ]
+}

package/skills/project-init/modules/brand.json

@@ -0,0 +1,78 @@
+{
+  "name": "brand",
+  "label": "브랜드 · 메시지",
+  "docs": [
+    {
+      "name": "brand-messaging",
+      "template": "spec",
+      "phase": "10. 착수 · 분석",
+      "title": "브랜드 · 메시지 체계",
+      "summary": "포지셔닝, 미션·비전·가치, 메시지 하우스, 브랜드 퍼스낼리티.",
+      "outline": [
+        [
+          "포지셔닝",
+          "한 문장. 무엇으로 인식되고 싶은가"
+        ],
+        [
+          "핵심 메시지",
+          "국문·영문 주메시지와 보조 메시지"
+        ],
+        [
+          "브랜드 철학",
+          "왜 이 일을 하는가"
+        ],
+        [
+          "미션 / 비전",
+          null
+        ],
+        [
+          "Core Values",
+          "가치마다 행동 수준의 정의를 붙인다. 형용사만 나열하지 않는다"
+        ],
+        [
+          "브랜드 퍼스낼리티",
+          "지향과 **회피**를 함께 적는다. 회피 목록이 실제로 디자인을 지킨다"
+        ],
+        [
+          "네이밍 규칙",
+          "정식 국·영문 표기, 로고 자산 유무. 표기가 흔들리면 전 페이지에 영향"
+        ]
+      ],
+      "minScale": "standard"
+    },
+    {
+      "name": "copy-guide",
+      "template": "spec",
+      "phase": "10. 착수 · 분석",
+      "title": "카피 · 콘텐츠 가이드",
+      "summary": "톤앤매너, 문장 규칙, 금지 표현, 콘텐츠 무결성 규칙.",
+      "outline": [
+        [
+          "톤",
+          "지향과 회피를 축으로 정리"
+        ],
+        [
+          "문장 규칙",
+          "길이, 순서(문제→접근→결과), 용어 사용"
+        ],
+        [
+          "금지 표현",
+          "구체성 없는 상투구를 실제 문장으로 나열한다. 추상적으로 쓰면 지켜지지 않는다"
+        ],
+        [
+          "콘텐츠 무결성",
+          "확인되지 않은 실적·수치·고객사·수상을 생성하지 않는다. 이 규칙이 디자인 완성도보다 우선한다"
+        ],
+        [
+          "용어 표기",
+          "회사명, 서비스명, 단계명"
+        ],
+        [
+          "마이크로카피",
+          "CTA, 성공·오류 메시지, 빈 목록 문구"
+        ]
+      ],
+      "minScale": "small"
+    }
+  ]
+}