@qualisoft/ai-skills 1.0.0

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

@@ -0,0 +1,129 @@
+{
+  "name": "web",
+  "label": "웹 — IA · 콘텐츠 · 검색 노출",
+  "docs": [
+    {
+      "name": "information-architecture",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "IA — 정보 구조",
+      "summary": "사이트맵, URL 규칙, 내비게이션, 내부 링크 설계.",
+      "outline": [
+        [
+          "사이트맵",
+          null
+        ],
+        [
+          "URL 규칙",
+          "표기, 언어, 후행 슬래시, 최대 깊이, 변경 시 리다이렉트 정책"
+        ],
+        [
+          "전역 내비게이션",
+          "헤더·푸터 구성과 CTA"
+        ],
+        [
+          "페이지 구성 순서",
+          "섹션 순서와 그 근거(방문자 심리 흐름)"
+        ],
+        [
+          "내부 링크 설계",
+          "각 페이지에서 이어질 다음 행동. 막다른 페이지를 만들지 않는다"
+        ],
+        [
+          "빈 상태 처리",
+          "데이터 0건일 때 섹션을 렌더할지. 렌더하지 않으면 위아래 리듬이 깨지지 않아야 한다"
+        ],
+        [
+          "다국어 라우팅",
+          "언어별 URL 전략, 기본 언어, 미번역 콘텐츠 처리",
+          "i18n"
+        ]
+      ]
+    },
+    {
+      "name": "content-model",
+      "template": "spec",
+      "phase": "20. 설계",
+      "title": "콘텐츠 모델",
+      "summary": "콘텐츠 타입별 필드 정의. CMS 이관을 전제로 한 스키마.",
+      "outline": [
+        [
+          "원칙",
+          "콘텐츠와 레이아웃을 분리한다. UI는 데이터를 받기만 한다"
+        ],
+        [
+          "저장 위치",
+          "파일 기반 / CMS 이관 대상 구분"
+        ],
+        [
+          "스키마",
+          "타입별 필드와 필수 여부. 검증되지 않은 값을 넣지 말아야 할 필드를 명시"
+        ],
+        [
+          "빈 상태 규칙",
+          "선택 필드가 비면 화면에서 해당 블록이 사라져야 한다"
+        ],
+        [
+          "CMS 이관 시 고려",
+          "이관해도 컴포넌트는 바뀌지 않아야 한다",
+          "cms"
+        ]
+      ],
+      "minScale": "small"
+    },
+    {
+      "name": "seo-spec",
+      "template": "spec",
+      "phase": "50. 오픈 · 안정화",
+      "title": "검색 · AI 노출 정의서",
+      "summary": "메타데이터·구조화 데이터·URL 정책, 네이버 대응, 생성형 AI 노출(GEO).",
+      "outline": [
+        [
+          "페이지별 필수 메타데이터",
+          "title / description / canonical / Open Graph / Twitter Card. **페이지마다 고유해야 한다**",
+          "seo"
+        ],
+        [
+          "마크업 규칙",
+          "시맨틱 HTML, 페이지당 h1 하나, 의미 있는 alt, 그 자체로 읽히는 링크 텍스트",
+          "seo"
+        ],
+        [
+          "구조화 데이터 (JSON-LD)",
+          "Organization / WebSite / Article / BreadcrumbList / Service. **확인된 정보만 넣는다** — 허위 구조화 데이터는 검색 페널티 대상",
+          "seo"
+        ],
+        [
+          "URL 정책",
+          "읽기 쉬운 구조. 발행 후 변경 시 301",
+          "seo"
+        ],
+        [
+          "사이트맵 / robots",
+          "미발행 콘텐츠는 sitemap에서 제외",
+          "seo"
+        ],
+        [
+          "네이버 대응",
+          "서치어드바이저 소유확인 + 사이트맵 제출. 네이버는 자체 문서(블로그·카페·지식iN)를 우선하므로 기업 사이트는 **브랜드 검색 중심**으로 접근한다. OG 태그는 네이버 공유 카드에도 쓰인다",
+          "naver"
+        ],
+        [
+          "GEO — 생성형 AI 노출",
+          "① **AI 크롤러 허용 정책** (GPTBot / ClaudeBot / PerplexityBot / Google-Extended) — 차단하면 인용 자체가 불가능하므로 허용 여부를 명시적으로 결정한다 ② `llms.txt` 제공 여부 ③ 인용 가능한 문장 구조 — 한 문단에 하나의 사실, 명확한 주어 ④ **엔티티 일관성** — 회사명·서비스명·주소가 사이트와 외부(GitHub, 링크드인, 디렉터리)에서 동일해야 한다 ⑤ 구조화 데이터 재사용",
+          "geo"
+        ],
+        [
+          "GEO의 한계",
+          "`llms.txt`는 아직 확정된 표준이 아니다. GEO는 측정 도구도 없어서 주요 AI에 직접 질의해 언급 여부를 수동 확인하는 수준이다. **KPI로 잡으면 허수가 된다.** 효과를 단정해 쓰지 않는다",
+          "geo"
+        ],
+        [
+          "검색 노출 성과",
+          "서치콘솔 · 서치어드바이저 지표(노출수, 클릭률, 색인 상태)",
+          "seo"
+        ]
+      ]
+    }
+  ]
+}

package/skills/project-init/presets/ai-product.json

@@ -0,0 +1,12 @@
+{
+  "name": "ai-product",
+  "label": "AI 제품 / LLM 기능",
+  "description": "모델을 쓰는 제품. 평가 기준·실패 모드·비용·데이터 취급이 일반 소프트웨어와 다르다.",
+  "modules": [
+    "core",
+    "product",
+    "ai",
+    "design",
+    "ops"
+  ]
+}

package/skills/project-init/presets/internal-system.json

@@ -0,0 +1,15 @@
+{
+  "name": "internal-system",
+  "label": "사내 시스템 / 어드민",
+  "description": "업무 시스템. 권한·업무 프로세스·기존 시스템 연동·데이터 이관이 핵심이다.",
+  "modules": [
+    "core",
+    "process",
+    "product",
+    "ux",
+    "design",
+    "backend",
+    "engineering",
+    "ops"
+  ]
+}

package/skills/project-init/presets/mobile-app.json

@@ -0,0 +1,20 @@
+{
+  "name": "mobile-app",
+  "label": "모바일 앱",
+  "description": "iOS/Android 앱. 스토어 심사·권한·오프라인·푸시가 웹과 다른 축이다.",
+  "modules": [
+    "core",
+    "audience",
+    "product",
+    "ux",
+    "design",
+    "a11y",
+    "backend",
+    "mobile",
+    "engineering",
+    "ops"
+  ],
+  "exclude": [
+    "security-audit"
+  ]
+}

package/skills/project-init/presets/web-corporate.json

@@ -0,0 +1,116 @@
+{
+  "name": "web-corporate",
+  "label": "기업 웹사이트 / 코퍼릿 사이트",
+  "description": "마케팅 목적의 다중 페이지 웹사이트. 브랜드·콘텐츠·SEO 비중이 크다.",
+  "modules": [
+    "core",
+    "brand",
+    "audience",
+    "product",
+    "ux",
+    "design",
+    "a11y",
+    "web",
+    "engineering",
+    "ops"
+  ],
+  "options": [
+    {
+      "id": "seo",
+      "label": "SEO — 검색엔진 노출",
+      "default": true,
+      "detail": "메타데이터, 구조화 데이터, 사이트맵. 공개 웹사이트면 거의 항상 켠다."
+    },
+    {
+      "id": "naver",
+      "label": "네이버 대응",
+      "default": true,
+      "detail": "서치어드바이저 등록, 브랜드 검색 전략. 국내 대상이면 켠다."
+    },
+    {
+      "id": "geo",
+      "label": "GEO — 생성형 AI 노출",
+      "default": false,
+      "detail": "AI 크롤러 허용 정책, 엔티티 일관성. 측정 도구가 없어 효과 검증이 어렵다는 점을 알고 켠다."
+    },
+    {
+      "id": "analytics",
+      "label": "웹 애널리틱스 (GA4 등)",
+      "default": true,
+      "detail": "방문자 행동 측정. 쿠키를 쓰면 동의 배너 검토가 따라온다.",
+      "cost": "도구는 무료로 시작 가능. 운영 시 이벤트 설계·검수 시간이 든다."
+    },
+    {
+      "id": "tagmanager",
+      "label": "태그 관리 (GTM)",
+      "default": false,
+      "detail": "코드 수정 없이 태그를 관리한다. 스크립트가 늘어 성능 예산과 충돌할 수 있다.",
+      "cost": "도구 자체는 무료. 태그 운영·품질 관리 시간이 든다.",
+      "conflicts": [
+        "perfbudget"
+      ]
+    },
+    {
+      "id": "adtracking",
+      "label": "전환 추적 · 광고 픽셀",
+      "default": false,
+      "detail": "광고를 집행할 때만 필요. 개인정보 동의 대상이다.",
+      "requires": [
+        "consent"
+      ],
+      "cost": "매체 계정 비용 외에 동의·태그 운영 시간이 든다."
+    },
+    {
+      "id": "consent",
+      "label": "쿠키 · 개인정보 동의",
+      "default": false,
+      "detail": "법무 판단이 필요하다. 추적 도구를 쓰면 대체로 필요해진다.",
+      "cost": "동의 관리 도구를 쓰면 월 비용 또는 트래픽 기반 비용이 생길 수 있다."
+    },
+    {
+      "id": "a11y",
+      "label": "접근성 (WCAG AA)",
+      "default": true,
+      "detail": "끄지 않기를 권한다. 공공·금융은 사실상 필수."
+    },
+    {
+      "id": "perfbudget",
+      "label": "성능 예산 게이트",
+      "default": true,
+      "detail": "릴리즈를 막는 수치 기준을 둘지. 끄면 목표만 남고 강제력이 없다."
+    },
+    {
+      "id": "i18n",
+      "label": "다국어",
+      "default": false,
+      "detail": "켜면 IA·라우팅·콘텐츠 모델이 모두 바뀐다. 나중에 켜기 가장 비싼 항목이다.",
+      "cost": "번역·검수·콘텐츠 운영 비용이 언어 수에 따라 반복된다.",
+      "laterEnableCost": "high"
+    },
+    {
+      "id": "cms",
+      "label": "CMS 연동",
+      "default": false,
+      "detail": "지금 안 쓰더라도 CMS-ready 구조는 유지한다.",
+      "cost": "실제 CMS 도입 시 서비스 요금과 콘텐츠 모델 운영 부담이 생긴다."
+    },
+    {
+      "id": "contactform",
+      "label": "문의 폼",
+      "default": true,
+      "detail": "백엔드가 없으면 데모 상태임을 명시해야 한다.",
+      "modes": [
+        "external",
+        "custom-api",
+        "mailto"
+      ],
+      "cost": "외부 폼은 사용량 요금, custom-api는 서버·메일·스팸 대응 운영비가 들 수 있다."
+    },
+    {
+      "id": "darkmode",
+      "label": "다크 모드",
+      "default": false,
+      "detail": "토큰을 이중으로 유지하는 비용이 든다."
+    }
+  ]
+}

package/skills/project-init/schema.json

@@ -0,0 +1,80 @@
+{
+  "$comment": "기획 문서 표준. build.mjs check 가 이 파일을 근거로 빌드를 통과/차단한다.",
+
+  "frontmatter": {
+    "required": [
+      "id",
+      "title",
+      "phase",
+      "status",
+      "owner",
+      "summary",
+      "template",
+      "updated"
+    ],
+    "enums": {
+      "status": ["draft", "review", "approved"],
+      "template": ["spec", "register", "log", "reference", "readme"]
+    },
+    "patterns": {
+      "id": "^[0-9]{2}-[a-z0-9-]+$",
+      "phase": "^[0-9]{2}\\. .+$",
+      "updated": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "maxLength": {
+      "summary": 120
+    }
+  },
+
+  "$comment_sections": "문서 종류마다 성격이 달라 필수 섹션을 종류별로 둔다. 면제는 개별 예외가 아니라 '이 종류는 원래 필요 없다'는 타입 결정으로만 가능하다.",
+
+  "$comment_eli5": "'한 줄로 말하면'은 고객·현업이 읽을 수 있는 평문 요약이다. 지침으로 두면 지켜지지 않으므로 필수 섹션으로 강제한다. log(시간순 기록)와 reference(표 자체가 정의), readme(체계 설명)는 면제한다.",
+  "eli5": {
+    "section": "한 줄로 말하면",
+    "appliesTo": ["spec", "register"],
+    "maxSentenceChars": 60,
+    "rules": [
+      "왜 필요한지를 먼저 쓰고 무엇인지를 나중에 쓴다",
+      "약어는 첫 등장에 괄호로 풀어 쓴다 (예: UAT(고객이 직접 써보는 최종 검사))",
+      "비유를 한 개 넣는다",
+      "한 문장을 60자 이내로 끊는다"
+    ]
+  },
+  "sectionsByTemplate": {
+    "spec": {
+      "required": ["한 줄로 말하면", "미결정", "변경 이력"],
+      "note": "정의서. 결정된 것과 남은 것을 함께 적는다."
+    },
+    "register": {
+      "required": ["한 줄로 말하면", "변경 이력"],
+      "note": "대장(臺帳). 문서 전체가 열린 항목의 목록이라 미결정 섹션이 중복된다."
+    },
+    "log": {
+      "required": [],
+      "note": "기록. 확정된 항목만 시간순으로 쌓인다."
+    },
+    "reference": {
+      "required": ["변경 이력"],
+      "note": "참조표. 용어집처럼 조회용. 표 자체가 정의이므로 ELI5를 중복시키지 않는다."
+    },
+    "readme": {
+      "required": [],
+      "note": "문서 체계 자체를 설명하는 메타 문서. 문서당 1개."
+    }
+  },
+
+  "$comment_ids": "추적 대상 ID는 PREFIX-번호 형식만 인정한다. 하이픈 없는 형태(B2B 등)와 충돌하지 않기 위함이다.",
+  "traceability": {
+    "idPattern": "\\b([A-Z]{1,3}-\\d{1,3})\\b",
+    "blockerPrefix": "B",
+    "todoPattern": "TODO\\(([a-z]+)\\)"
+  },
+
+  "rules": {
+    "filenameMatchesId": true,
+    "uniqueIds": true,
+    "wikiLinksResolve": true,
+    "referencedIdsMustBeDefined": true,
+    "warnOnPlainDocReference": true
+  }
+}

package/skills/project-init/templates/log.md

@@ -0,0 +1,54 @@
+---
+id: {{id}}
+title: {{title}}
+phase: {{phase}}
+status: approved
+owner: TBD
+summary: {{summary}}
+template: log
+updated: {{updated}}
+---
+
+# {{title}}
+
+## 기록 규칙
+
+- 결정이 **바뀌었을 때**가 아니라 **내려졌을 때** 즉시 기록한다.
+- 새 의존성 추가, 스택 변경, 범위 변경은 반드시 기록한다.
+- 형식: 배경 → 선택지 → 결정 → 근거 → 영향.
+- 추적 ID는 `D-001` 형식으로 붙인다.
+
+---
+
+## {{updated}}
+
+### D-001. 제목
+
+| 일자 | AI | 계정 |
+| --- | --- | --- |
+| {{timestamp}} | {{ai}} | {{account}} |
+
+**배경**
+**선택지**
+**결정**
+**근거**
+**영향**
+
+---
+
+## 템플릿
+
+```
+## YYYY-MM-DD
+
+### D-00N. 제목
+
+| 일자 | AI | 계정 |
+| --- | --- | --- |
+| YYYY-MM-DD HH:mm | Claude Code / Codex / Cursor | 계정 이름 |
+**배경**
+**선택지**
+**결정**
+**근거**
+**영향**
+```

package/skills/project-init/templates/readme.md

@@ -0,0 +1,62 @@
+---
+id: {{id}}
+title: {{title}}
+phase: {{phase}}
+status: approved
+owner: TBD
+summary: {{summary}}
+template: readme
+updated: {{updated}}
+---
+
+# {{title}}
+
+이 폴더는 **구현 이전에 정립되어야 하는 모든 정의**를 담는다.
+코드가 아니라 합의를 저장하는 곳이다.
+
+## 원칙
+
+1. **하나의 문서 = 하나의 의사결정 영역.** 같은 내용을 두 문서에 쓰지 않는다.
+2. **모르는 것은 비워두고 표시한다.** 추측으로 채우지 않는다. 미정은 `TODO(주체)` 또는 리스크 대장으로 보낸다.
+3. **문서는 코드보다 먼저, 그러나 코드보다 짧게.** 읽히지 않는 문서는 없는 문서다.
+4. **결정이 바뀌면 문서를 고치고 의사결정 기록에 남긴다.**
+
+## 상태 값
+
+| status | 뜻 |
+| --- | --- |
+| `draft` | 초안. 내용이 비어 있거나 검증되지 않음 |
+| `review` | 검토 요청 상태 |
+| `approved` | 합의 완료. 변경 시 의사결정 기록 필요 |
+
+## 문서 종류
+
+| template | 필수 섹션 | 성격 |
+| --- | --- | --- |
+| `spec` | 미결정, 변경 이력 | 정의서 |
+| `register` | 변경 이력 | 대장 — 열린 항목 목록 |
+| `log` | 없음 | 기록 — 확정 항목 누적 |
+| `reference` | 변경 이력 | 참조표 |
+| `readme` | 없음 | 이 문서 |
+
+## 읽는 방법
+
+- **사람**: `index.html`을 브라우저로 연다.
+- **에이전트**: 개별 `.md`를 읽는다. 프론트매터 `summary`로 필요한 문서만 고른다.
+
+## 표기 규칙
+
+| 표기 | 뜻 |
+| --- | --- |
+| `[[문서-id]]` | 문서 간 링크. 깨지면 빌드가 실패한다 |
+| `TODO(client)` | 정보 제공 대기. `design` `copy` `legal` 등으로 주체를 밝힌다 |
+| `B-01` `F-01` `D-001` | 추적 ID. `PREFIX-번호` 형식만 매트릭스에 잡힌다 |
+
+## 검증과 빌드
+
+```bash
+node ~/.claude/skills/project-init/build.mjs check
+node ~/.claude/skills/project-init/build.mjs build
+```
+
+검증에 실패하면 빌드되지 않는다. 이것이 표준이 유지되는 유일한 이유다.

package/skills/project-init/templates/reference.md

@@ -0,0 +1,34 @@
+---
+id: {{id}}
+title: {{title}}
+phase: {{phase}}
+status: draft
+owner: TBD
+summary: {{summary}}
+template: reference
+updated: {{updated}}
+---
+
+# {{title}}
+
+## 분류 A
+
+| 항목 | 정의 |
+| --- | --- |
+| | |
+
+## 분류 B
+
+| 항목 | 정의 |
+| --- | --- |
+| | |
+
+## 변경 이력
+
+### {{updated}}
+
+| 일자 | AI | 계정 |
+| --- | --- | --- |
+| {{timestamp}} | {{ai}} | {{account}} |
+
+- 최초 작성

package/skills/project-init/templates/register.md

@@ -0,0 +1,63 @@
+---
+id: {{id}}
+title: {{title}}
+phase: {{phase}}
+status: draft
+owner: TBD
+summary: {{summary}}
+template: register
+updated: {{updated}}
+---
+
+# {{title}}
+
+## 한 줄로 말하면
+
+> TODO(owner) — 이 문서가 하는 일을 한 문장으로. 전문용어 없이, 60자 이내.
+
+**왜 필요한가** — 이게 없으면 무엇이 문제인가. 두 문장 이내.
+
+**비유하자면** — 익숙한 것에 견준다. 한 문장.
+
+**이 문서를 읽어야 하는 사람** — 역할 이름으로 적는다.
+
+## 등급
+
+| 등급 | 뜻 |
+| --- | --- |
+| `Blocker` | 해소 전 다음 단계 진입 불가 |
+| `High` | 늦어질수록 재작업 비용이 큼 |
+| `Medium` | 진행하며 병행 결정 가능 |
+
+## 항목
+
+> 추적 ID는 `PREFIX-번호` 형식으로 붙인다 (`B-01`, `H-01`, `M-01`).
+> 이 형식만 문서 간 추적 매트릭스에 잡힌다.
+
+아직 등록된 항목이 없다. 아래 형식을 복사해 추가한다.
+
+```
+### B-01. 항목 제목
+
+| | |
+| --- | --- |
+| **일자** | YYYY-MM-DD HH:mm |
+| **AI** | Claude Code / Codex / Cursor |
+| **계정** | 계정 이름 |
+| **차단 단계** | design / implementation / release |
+| **문제** | |
+| **영향** | |
+| **필요 결정** | |
+| **결정 주체** | |
+| **상태** | 미해소 |
+```
+
+## 변경 이력
+
+### {{updated}}
+
+| 일자 | AI | 계정 |
+| --- | --- | --- |
+| {{timestamp}} | {{ai}} | {{account}} |
+
+- 최초 작성

package/skills/project-init/templates/spec.md

@@ -0,0 +1,46 @@
+---
+id: {{id}}
+title: {{title}}
+phase: {{phase}}
+status: draft
+owner: TBD
+summary: {{summary}}
+template: spec
+updated: {{updated}}
+---
+
+# {{title}}
+
+## 한 줄로 말하면
+
+> TODO(owner) — 이 문서가 하는 일을 한 문장으로. 전문용어 없이, 60자 이내.
+
+**왜 필요한가** — 이게 없으면 무엇이 문제인가. 두 문장 이내.
+
+**비유하자면** — 익숙한 것에 견준다. 한 문장.
+
+**이 문서를 읽어야 하는 사람** — 역할 이름으로 적는다.
+
+## 목적
+
+이 문서가 답하는 질문은 무엇인가. 두세 문장.
+
+{{outline}}
+
+## 미결정
+
+| 항목 | 결정 주체 | 영향 |
+| --- | --- | --- |
+| | | |
+
+큰 항목은 [[{{riskDoc}}]]로 올린다.
+
+## 변경 이력
+
+### {{updated}}
+
+| 일자 | AI | 계정 |
+| --- | --- | --- |
+| {{timestamp}} | {{ai}} | {{account}} |
+
+- 최초 작성