@qualisoft/ai-skills 1.0.0 → 1.3.0

package/skills/project-init/SKILL.md

@@ -45,6 +45,47 @@ node ~/.claude/skills/project-init/build.mjs selftest
 
 빌드한 HTML의 좌측 메뉴는 1~4단계 진행률을 자동 표시한다. 1단계는 인터뷰 기록, 2단계는 문서 상태(`draft` 25 / `review` 65 / `approved` 100 가중 평균), 3단계는 디자인 기록·스타일가이드·시안, 4단계는 `docs.config.json.stageProgress["4"]`를 기준으로 한다. 구현 스킬은 검증된 완료율만 4단계 값에 기록한다. 색은 0% 회색, 1~24% 빨강, 25~49% 노랑, 50~99% 주황, 100% 초록이다. 가이드·추적 메뉴는 회색, 홈처럼 주요 이동 항목만 파랑으로 분리한다.
 
+## 연동 서비스
+
+좌측에는 **`연동 서비스 관리` 한 줄만** 둔다(붙은 개수 배지 포함).
+서비스를 전부 나열하면 사이드바가 문서 메뉴보다 길어져 연동 목록판이 된다.
+목록은 `연동 서비스` 페이지가 맡고, 카드마다 **연동 방법 묻기 복사** 버튼이 있어
+AI에게 그대로 붙여넣을 문구를 클립보드에 담는다.
+
+**목록은 네 갈래에서 모은다. 아래일수록 약하다.**
+
+| 출처 | 어디서 | 딱지 |
+| --- | --- | --- |
+| **설정** | `Docs/docs.config.json` 의 `integrations` — 사람이 적은 것. **언제나 이긴다** | `설정` |
+| **자동 감지** | `git remote origin`(github.com이면 GitHub), 루트·`docs/`·`api/`·`openapi/` 의 `openapi\|swagger.(yaml\|yml\|json)` | `자동 감지` |
+| **기획** | **문서 본문에 서비스 이름이 있으면 연동 예정으로 본다.** 근거 문서를 카드에 적는다 | `기획` |
+| **추천** | 위 셋이 **하나도 없을 때만** 카탈로그 기본값으로 채운다 | `추천` |
+
+**기획에서 잡는 것이 이 체계의 요점이다.** 연동은 설정 파일보다 기획서에 먼저 적힌다 —
+“GCP 에 배포한다”, “카카오 알림톡을 쓴다”. 그걸 사람이 설정에 한 번 더 옮겨 적게 만들지 않는다.
+`기획` 딱지는 자동으로 올라온 것이라 **오탐일 수 있다.** 아니면 설정에서 빼면 된다.
+
+확정된 연동은 설정에 적는다. **설정이 항상 이긴다.**
+
+```json
+{
+  "integrations": {
+    "notion": { "url": "https://notion.so/...", "note": "회의록 DB" },
+    "figma":  { "status": "none" },
+    "sentry": { "name": "Sentry", "slug": "sentry", "color": "362D59", "what": "에러 추적", "url": "https://sentry.io/acme" }
+  }
+}
+```
+
+`status` 를 안 적으면 `url` 유무로 판정한다. 카탈로그에 없는 id도 쓸 수 있고,
+그때는 `name`·`slug`(simple-icons)·`color`(# 없는 HEX)를 같이 적는다.
+로고는 cdn.simpleicons.org 에서 받고, 막힌 환경에서는 브랜드색 이니셜로 떨어진다.
+연동을 새로 붙였으면 `integrations` 를 고치고 `build` 를 다시 돌린다.
+
+카탈로그에는 감지용 표기(`detect`)가 함께 들어 있다 — GitHub·Swagger·Notion·Figma·Slack·Jira(추천 기본값)와
+GCP·AWS·Vercel·Cloudflare·GA4·GTM·Sentry·카카오·네이버·Stripe·토스페이먼츠·Firebase·Supabase·SendGrid·GitHub Actions.
+새 서비스를 카탈로그에 넣을 때는 `detect` 를 같이 적는다. **없으면 기획에서 잡히지 않는다.**
+
 ## 작업 순서
 
 **새 프로젝트를 시작할 때**
@@ -368,6 +409,57 @@ npm view react versions --json  # 선택지가 필요하면
 > 그 도메인의 프로젝트를 실제로 해보기 전에는 채우지 않는다.
 > 겪지 않은 논점을 상상해서 적으면 다음 프로젝트가 틀린 지침을 물려받는다.
 
+## 파일 스크립트 — 산출물 생성 대본
+
+빌드한 HTML 의 각 문서 우측 상단에 **`파일 스크립트`** 버튼이 있다. 누르면 모달이
+열리고, 형식을 고르면 **AI 에게 줄 지시문(대본)** 이 나온다. 코드가 아니라 대본이다.
+복사해서 에이전트에 붙여 넣으면 그 형식으로 산출물을 만든다.
+
+형식은 PDF · Excel · PowerPoint · Word · CSV 다섯이다.
+
+**서식 규격이 대본 안에 박혀 있다.** 색 여섯 개, 글자 위계 네 단계, 표 스타일,
+하지 말 것 목록이 `_style.md` 에 고정되어 모든 대본에 들어간다. 그래서 착수 때
+만들든 중간에 만들든, 누가 어떤 도구로 만들든 **같은 모양이 나온다.** 이게 대본을
+쓰는 이유다 — 매번 "모던하게 만들어 줘" 라고 말하면 매번 다른 것이 나온다.
+
+**대본은 내용을 품지 않는다.** 원본 `.md` 경로만 가리키고 "이 파일을 먼저 읽어라"
+라고 지시한다. 그래서 문서를 고친 뒤 같은 대본을 다시 써도 최신 내용으로 만들어지고,
+HTML 크기가 문서 수와 무관하다.
+
+대본은 `templates/script/*.md` 에 있다. `_style.md` 가 공통 서식 규격이고 빌드할 때
+각 형식 대본의 `__STYLE__` 자리에 끼워진다. `__DOC_FILE__` · `__DOC_TITLE__` ·
+`__DOC_STEM__` 은 모달을 열 때 브라우저에서 치환된다.
+
+서식을 바꾸려면 **`templates/script/` 의 마크다운을 고친다.** `build.mjs` 는 파일을
+읽어 나르기만 한다.
+
+## 비활성 메뉴 — 안 쓴 메뉴를 죽여 둔다
+
+기획안을 근거로 메뉴는 만들어졌지만 끝까지 손대지 않는 문서가 생긴다. 그런 문서를
+"작성 중"으로 두면 진행률이 영원히 낮게 깔리고, **무엇이 남은 일이고 무엇이 애초에
+필요 없던 항목인지** 구분되지 않는다.
+
+한 번도 쓰이지 않은 문서는 좌측 메뉴에서 **검정 점**으로 바뀌고 이름이 흐려진다.
+판정은 `docUsed()` 가 한다.
+
+| 신호 | 판정 |
+| --- | --- |
+| 템플릿 골격을 뺀 실질 글자 수 ≥ 400 | 쓰임 |
+| `status` 가 `draft` 가 아님 (`log` 템플릿 제외) | 쓰임 |
+| 추적 ID 를 본문에 정의 (코드 블록 예시는 제외) | 쓰임 |
+| 위 어느 것도 아님 | **안 쓰임 — 검정 점** |
+
+임계값 400 은 실측으로 잡았다. 갓 만든 문서는 37~265, 한 번이라도 채운 문서는
+996 이상으로 갈라진다.
+
+> **상태나 링크를 주 신호로 쓰지 않는다.** `log` 템플릿은 `status` 가 `approved` 로
+> 시작하고, 모든 `spec` 템플릿은 리스크 대장으로 가는 링크를 자동으로 건다.
+> 그걸 근거로 삼으면 갓 만든 대장이 늘 '사용됨'이 된다.
+
+**사이드바 상단 `비활성 관리`** 를 켜면 메뉴마다 체크박스가 생긴다. 자동 판정을
+사람이 덮어쓸 수 있다. 덮어쓴 값은 문서 id 로 `localStorage` 에 남으므로 **다시
+빌드해도 유지된다.** 자동 판정과 같아지면 저장을 지워, 쓸데없는 기록을 남기지 않는다.
+
 ## 하지 말 것
 
 - `index.html`을 직접 고치기 — 다음 빌드에 덮어써진다.