yunchan/designpaca
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

designpaca 초기 구현 — 스킬 · 설치 CLI · 배포 파이프라인

Browse source 
웹 디자인 파이프라인 스킬과 이를 5개 에이전트에 설치하는 CLI 를 담은 모노레포.

스킬 (packages/skill)
- SKILL.md 261줄 + 참조 문서 16개 3,349줄. progressive disclosure 로
  본문은 절차와 인덱스만, 지식은 references/ 로 분리
- 0~6단계 파이프라인. 규모에 따라 전체·연장·국소 세 경로로 분기
- 하드 게이트 12개는 grep·카운트로 검증 가능한 것만. 취향 판단은 제외
- 미학 프리셋 5종, AI 슬롭 지문 목록, 한글 조판 규칙,
  SVG 필터·three.js·인터랙티브 모션·HTML-in-Canvas 실전 지침

설치 CLI (packages/cli, packages/core)
- npx designpaca 온보딩 TUI. Claude Code · Codex · Cursor · Windsurf · AGENTS.md
- 매니페스트에 설치 시점 해시를 기록해 사용자가 고친 파일은 update 가 건너뛴다
- 타깃별로 본문의 references/ 경로를 실제 설치 위치로 재작성
- AGENTS.md 는 항상 로드되므로 본문 대신 303자 포인터만 주입
- Windsurf 는 12,000자 상한 초과 시 설치를 차단

배포 (build/ci, .forgejo/workflows)
- 태그 v* → 검사·테스트·빌드 → npmjs 배포 + Forgejo 레지스트리 미러
  → draft 릴리스 → Cloudflare Pages. 재실행 멱등

근거 (research/)
- 약 250개 웹 소스 조사 결과와 도그푸딩 검증 2건. 스킬의 모든 수치는 여기서 나온다

테스트 22개 통과 (core 16 · cli 6)
This commit is contained in:
Yun Chan 2026-08-20 10:48:00 +09:00
commit 8808c672dc
135 changed files with 38838 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

750
research/skills/01-local-skill-teardown.md Normal file
View file

@ -0,0 +1,750 @@
# 01. 로컬 설치 스킬 전수 해부
작성일: 2026-08-20
조사 방법: 각 `SKILL.md` 파일을 실제로 읽고 분석. 빌트인 스킬은 Skill 도구로 로드해 본문을 직접 확인.
원문 인용은 모두 `>` 또는 따옴표로 표기하고 출처 경로를 병기한다.
---
## 0. 조사 범위와 확인 결과
### 실제로 읽은 파일
| 스킬 | 경로 | 바이트 | 줄 수 |
|---|---|---|---|
| design-taste-frontend | `C:\Users\encep\.agents\skills\design-taste-frontend\SKILL.md` | 88,459 | 1,206 |
| design-taste-frontend-v1 | `C:\Users\encep\.agents\skills\design-taste-frontend-v1\SKILL.md` | 21,421 | 226 |
| high-end-visual-design | `C:\Users\encep\.agents\skills\high-end-visual-design\SKILL.md` | 10,659 | - |
| minimalist-ui | `C:\Users\encep\.agents\skills\minimalist-ui\SKILL.md` | 7,986 | - |
| industrial-brutalist-ui | `C:\Users\encep\.agents\skills\industrial-brutalist-ui\SKILL.md` | 8,548 | - |
| gpt-taste | `C:\Users\encep\.agents\skills\gpt-taste\SKILL.md` | 7,931 | - |
| imagegen-frontend-web | `C:\Users\encep\.agents\skills\imagegen-frontend-web\SKILL.md` | 37,841 | 987 |
| imagegen-frontend-mobile | `C:\Users\encep\.agents\skills\imagegen-frontend-mobile\SKILL.md` | 41,791 | 1,465 |
| image-to-code | `C:\Users\encep\.agents\skills\image-to-code\SKILL.md` | 37,670 | 1,228 |
| redesign-existing-projects | `C:\Users\encep\.agents\skills\redesign-existing-projects\SKILL.md` | 15,238 | - |
| stitch-design-taste | `C:\Users\encep\.agents\skills\stitch-design-taste\SKILL.md` (+ `DESIGN.md` 12,174) | 12,035 | - |
| brandkit | `C:\Users\encep\.agents\skills\brandkit\SKILL.md` | 16,790 | 798 |
| full-output-enforcement | `C:\Users\encep\.agents\skills\full-output-enforcement\SKILL.md` | 2,641 | - |
| graphify | `C:\Users\encep\.claude\skills\graphify\SKILL.md` | 51,297 | 1,242 |
| frontend-design (공식) | `C:\Users\encep\.claude\plugins\marketplaces\anthropic-agent-skills\skills\frontend-design\SKILL.md` | - | - |
| skill-creator (공식) | `...\anthropic-agent-skills\skills\skill-creator\SKILL.md` | - | 486 |
| artifact-design (빌트인) | 파일 없음. Skill 도구로 본문 로드해 확인 | - | - |
| dataviz (빌트인) | SKILL.md 파일 없음. `references/`·`scripts/`만 디스크에 추출됨 | - | - |
### 확인 못한 것
- **`artifact-design` / `dataviz` / `artifact-diagramming` / `artifact-capabilities`의 SKILL.md 원본 파일**: Claude Code 바이너리에 임베드되어 있어 파일시스템에서 찾지 못했다. `find`로 전 사용자 디렉터리를 훑었으나 없음. 다만 **Skill 도구로 호출하면 본문이 컨텍스트에 로드되므로 내용은 직접 읽었다.** dataviz는 `C:\Users\encep\AppData\Local\Temp\claude\bundled-skills\2.1.235\a44f7fbb33676b5b8599b1fc53d4b74e\dataviz\` 아래에 `references/*.md` 7개와 `scripts/validate_palette.{js,py}`가 실제로 추출되어 있다.
- **`.agents/skills` 전체에서 `references/` 서브디렉터리를 가진 디자인 스킬은 0개.** 유일하게 `object-separation`(디자인 스킬 아님)만 `references/model-notes.md`를 가진다. 즉 **로컬에 설치된 커뮤니티 디자인 스킬은 전부 단일 파일 SKILL.md 구조**다. 이는 뒤에서 다룰 핵심 발견이다.
---
## 1. 프론트매터 구조 비교표
| 스킬 | `name` | `description` | 그 외 필드 | 설명 길이(문자) |
|---|---|---|---|---|
| design-taste-frontend | O | O | 없음 | 약 230 |
| design-taste-frontend-v1 | O | O | 없음 | 약 210 |
| high-end-visual-design | O | O | 없음 | 약 175 |
| minimalist-ui | O | O | 없음 | 약 125 |
| industrial-brutalist-ui | O | O | 없음 | 약 250 |
| gpt-taste | O | O | 없음 | 약 300 |
| imagegen-frontend-web | O | O | 없음 | 약 620 |
| imagegen-frontend-mobile | O | O | 없음 | 약 610 |
| image-to-code | O | O | 없음 | 약 500 |
| redesign-existing-projects | O | O | 없음 | 약 190 |
| stitch-design-taste | O | O | 없음 | 약 195 |
| brandkit | O | O | 없음 | 약 440 |
| full-output-enforcement | O | O | 없음 | 약 190 |
| graphify | O | O | **`trigger: /graphify`** | 약 200 |
| codex-image | O | O (한국어) | 없음 | 약 350 |
| frontend-design (공식) | O | O | **`license: Complete terms in LICENSE.txt`** | 약 175 |
| skill-creator (공식) | O | O | 없음 | 약 240 |
| canvas-design (공식) | O | O | `license` | 약 230 |
| algorithmic-art (공식) | O | O | `license` | 약 260 |
| web-artifacts-builder (공식) | O | O | `license` | 약 240 |
| discernment-nudge (공식) | O | O (YAML 블록 스칼라 `>`) | `license` | 매우 김 |
### 발견 1: 프론트매터는 사실상 `name` + `description` 2개뿐
**13개 커뮤니티 디자인 스킬 전부 `name`과 `description`만 쓴다.** `allowed-tools`, `disable-model-invocation`, `paths`, `metadata`, `context: fork` 같은 Claude Code 확장 필드를 쓰는 디자인 스킬은 한 개도 없었다. 이유는 명확하다. 이 스킬들은 Claude Code 전용이 아니라 Codex·Cursor 등에서도 돌아가야 하는 "휴대용" 스킬이고, Agent Skills 오픈 스펙이 허용하는 필드는 6개(`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`)뿐이기 때문이다.
### 발견 2: `trigger:` 는 스펙에 없는 필드다
`graphify`의 프론트매터:
```yaml
---
name: graphify
description: "any input (code, docs, papers, images, videos) to knowledge graph. Use when user asks any question about a codebase, documents, or project content - especially if graphify-out/ exists, treat the question as a /graphify query."
trigger: /graphify
---
```
출처: `C:\Users\encep\.claude\skills\graphify\SKILL.md`
`trigger`는 Agent Skills 스펙에도 Claude Code 프론트매터 레퍼런스에도 없다. Claude Code는 알 수 없는 키를 무시하지만, **claude.ai 업로드나 `package_skill.py` 패키징 시에는 하드 에러**가 난다. designpaca에서 절대 흉내내면 안 되는 패턴이다. (03-format-specs.md 참조)
### 발견 3: 디렉터리명이 곧 커맨드명
`.claude/skills/graphify/`에 있으면 `/graphify`, `.agents/skills/design-taste-frontend/`에 있으면 그 이름이 커맨드가 된다. 프론트매터 `name`은 개인/프로젝트 스킬에서는 **표시 라벨일 뿐이고 커맨드명을 바꾸지 못한다.** 플러그인 스킬에서만 `name`이 커맨드의 마지막 세그먼트를 결정한다.
---
## 2. description 작성 기법 분류
로컬 스킬들의 description을 4가지 패턴으로 분류할 수 있다.
### 패턴 A: 도메인 선언형 (짧음, 트리거 정확도 낮음)
> `description: Clean editorial-style interfaces. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.`
> — minimalist-ui
"무엇을 하는가"만 있고 "언제 쓰는가"가 없다. 사용자가 "미니멀한 랜딩 만들어줘"라고 해도 트리거될지 불확실하다. **Anthropic 공식 베스트 프랙티스가 명시적으로 지적하는 실패 유형이다.**
### 패턴 B: 용도 명시형 (권장)
> `description: Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check.`
> — design-taste-frontend
"landing pages, portfolios, and redesigns"라는 **구체적 용도 키워드**가 앞쪽에 있다. 이것이 매칭의 핵심이다.
### 패턴 C: 배제 조건 포함형 (가장 정교함)
> `description: ... Codex CLI 내장 image_gen 도구(gpt-image-2 = "imagegen2")를 ChatGPT 구독 인증으로 호출하며 OpenAI API 키가 필요 없다. **벡터/SVG/코드 네이티브 아이콘이나 로고 시스템 확장에는 쓰지 않는다.**`
> — codex-image (강조는 필자)
**"이럴 땐 쓰지 마라"를 description에 적는다.** 과잉 트리거를 막는 유일하게 검증된 방법. `refactor-governance`도 같은 기법을 쓴다:
> `Read-only lookup, investigation, explanation, or answering questions about the code is NOT a trigger — the gated workflow applies only when a file will be changed.`
### 패턴 D: 리터럴 발화 나열형 (한국어 스킬에서 특히 효과적)
> `"이미지 생성해", "이미지 만들어", "일러스트 만들어", "그림 그려줘", "이미지를 생성", "generate an image", "create an illustration", "Codex로 이미지 만들어" 같은 요청에 자동으로 트리거.`
> — codex-image
**사용자가 실제로 타이핑할 문장을 그대로 박아넣는다.** 다국어 환경에서 특히 중요하다. designpaca가 한국어 사용자용이라면 이 기법은 필수다.
### 패턴 E: description 안에 규칙을 넣는 반칙형
> `description: ... CRITICAL OUTPUT RULE — generate ONE separate horizontal image FOR EVERY section. A landing page with 8 sections produces 8 images. Never compress multiple sections into one image. ...`
> — imagegen-frontend-web (약 620자)
description에 **본문 규칙을 밀어넣는다.** 이유: description은 항상 컨텍스트에 있으므로 본문이 로드되기 전에도 모델이 그 규칙을 본다. 하지만 대가가 크다.
- Claude Code는 `description` + `when_to_use` 합쳐 **1,536자에서 잘라낸다.**
- 스킬 목록 전체가 예산(기본 컨텍스트 윈도의 1%)을 넘으면 **설명이 더 짧게 잘린다.**
- Agent Skills 스펙 상한은 1,024자.
620자짜리 description은 스킬이 몇 개 없을 때만 안전하다. designpaca는 이 사용자의 환경(스킬 20개 이상)에서 돌아야 하므로 **200~350자 범위가 현실적 상한**이다.
---
## 3. 본문 분량·구조 비교표
| 스킬 | 줄 수 | 섹션 수 | 구조 | 코드 예시 | references 분리 |
|---|---|---|---|---|---|
| design-taste-frontend | 1,206 | 15 + 부록 3 | 번호 섹션 + 표 + 체크리스트 + 부록 | 3개 캐노니컬 TSX 스켈레톤 | 없음 (부록으로 인라인) |
| design-taste-frontend-v1 | 226 | 10 | 번호 섹션 | 없음 (클래스명만) | 없음 |
| high-end-visual-design | ~200 | 8 | 번호 섹션 + 최종 체크리스트 | 없음 (Tailwind 클래스 인라인) | 없음 |
| minimalist-ui | ~120 | 8 | 번호 섹션 | 없음 (hex/CSS 값 인라인) | 없음 |
| industrial-brutalist-ui | ~130 | 8 | 번호 섹션 + 아키타입 분기 | CSS 스니펫 2개 | 없음 |
| gpt-taste | ~110 | 8 | 번호 섹션 + `<design_plan>` 게이트 | JSX 한 줄 예시 | 없음 |
| imagegen-frontend-web | 987 | 13+ | **HARD RULE 선두 배치** + 조합 엔진 | 없음 (이미지 스킬) | 없음 |
| imagegen-frontend-mobile | 1,465 | 37 | 번호 규칙 나열 + 카테고리 바이어스 | 없음 | 없음 |
| image-to-code | 1,228 | 38 | 번호 규칙 나열 + 예시 해석 | 없음 | 없음 |
| redesign-existing-projects | ~180 | 감사 카테고리 8 + 업그레이드 4 | **"문제 → 고치는 법" 페어 나열** | 없음 | 없음 |
| stitch-design-taste | ~300 | 9 + 출력 템플릿 | **메타 스킬** (DESIGN.md를 생성) | 출력 템플릿 마크다운 | `DESIGN.md` 동봉 |
| brandkit | 798 | 20+ | 시각 모드 8종 + 프롬프트 템플릿 | 프롬프트 템플릿 | 없음 |
| full-output-enforcement | ~60 | 5 | 금지 목록 + 프로세스 | 중단 마커 포맷 | 없음 |
| frontend-design (공식) | ~40 | 6 | **산문(prose)** | 없음 | 없음 |
| skill-creator (공식) | 486 | 20+ | 워크플로 + JSON 스키마 | JSON/bash | `references/schemas.md`, `agents/*.md`, `scripts/*.py` |
| dataviz (빌트인) | ~80 | 5 | **인덱스 + 절차 7단계** | 없음 | `references/` 7개 + `scripts/` 2개 |
### 발견 4: 커뮤니티 디자인 스킬은 전부 단일 파일, 공식 스킬만 분리
Anthropic 공식 스킬(skill-creator, dataviz, canvas-design, algorithmic-art)은 `references/`, `scripts/`, `assets/`를 쓴다. 커뮤니티 디자인 스킬 13개는 **하나도 안 쓴다.** design-taste-frontend는 88KB 단일 파일이다.
이게 왜 문제인가. Anthropic 공식 가이드는 이렇게 말한다:
> "Keep SKILL.md body under 500 lines for optimal performance"
> — Skill authoring best practices
> "Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer `SKILL.md` content into referenced files."
> — Agent Skills Specification
design-taste-frontend는 1,206줄. 발동되는 순간 **약 22,000토큰이 컨텍스트에 영구 상주한다.** Claude Code 문서:
> "When you or Claude invoke a skill, the rendered `SKILL.md` content enters the conversation as a single message and stays there for the rest of the session."
게다가 자동 컴팩션 시:
> "Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each."
즉 **88KB 스킬의 앞 5,000토큰만 살아남는다.** design-taste-frontend에서 5,000토큰이면 Section 0~4.2 정도까지다. **가장 중요한 Section 9 (AI TELLS)와 Section 14 (PRE-FLIGHT CHECK)는 컴팩션 후 사라진다.**
이것이 designpaca 설계에서 가장 중요한 구조적 교훈이다.
### 발견 5: 자기 자신의 구조를 명시하지만 구현은 없는 "계약" 섹션
design-taste-frontend Section 12는 블록 라이브러리 스키마를 정의해놓고:
> **Status:** schema defined here. Blocks will be added iteratively. Do not freelance new blocks without following this schema.
그리고 파일 위치를 `skills/taste-skill/blocks/hero/asymmetric-split.md` 등으로 지정하는데, **실제로 그 디렉터리는 존재하지 않는다.** 존재하지 않는 파일을 가리키는 것은 모델을 혼란시킨다. 좋은 아이디어(progressive disclosure로 가는 길)를 절반만 실행한 사례다.
---
## 4. 프롬프트 기법 상세 비교
### 4.1 금지 규칙 표현법
세 가지 계보가 뚜렷하게 갈린다.
#### 계보 A: 절대 금지형 (커뮤니티 디자인 스킬 대부분)
> **NO em-dash (`—`) as a design element OR anywhere else.** ... **Em-dash (`—`) is COMPLETELY banned.** It is the LLM's signature stylistic crutch and it is the #1 visual Tell in production tests. **There is no "limited use" allowance, no "natural language frequency" allowance, no "in body copy is fine" allowance. None.**
> ...
> This rule is non-negotiable. **The agent has historically ignored em-dash limits when phrased as "use sparingly." The phrasing here is binary: zero em-dashes.**
> — design-taste-frontend §9.G
이 마지막 문장이 핵심이다. **저자는 "sparingly"라는 표현이 실패했음을 관찰하고 이진 규칙으로 바꿨다.** 그리고 그 이유를 스킬 안에 기록해뒀다. 이것이 이 문서 전체에서 가장 잘 쓰인 문장이다.
#### 계보 B: 조건부 오버라이드형 (design-taste-frontend의 대부분 + 유일하게 v2에만 있음)
> **THE LILA RULE:** The "AI Purple / Blue glow" aesthetic is **discouraged as a default**. ...
> **Override:** if the brand or brief explicitly asks for purple / violet / lila, embrace it. But execute with intent: consistent palette, harmonised neutrals, restrained gradients. Not generic AI gradient slop.
> — design-taste-frontend §4.2
v1은 같은 규칙을 이렇게 썼다:
> **THE LILA BAN:** The "AI Purple/Blue" aesthetic is **strictly BANNED**.
> — design-taste-frontend-v1 §3 Rule 2
**v1 → v2에서 "BAN"이 "discouraged as a default + Override"로 바뀌었다.** v2 문서 최상단이 이 철학을 선언한다:
> Every rule below is **contextual**. None of it fires automatically. First read the brief, then pull only what fits.
이것이 v1과 v2의 근본적 차이이며, designpaca가 채택해야 할 방향이다.
#### 계보 C: 이유 설명형 (Anthropic 공식)
> Try hard to explain the **why** behind everything you're asking the model to do. Today's LLMs are *smart*. ... **If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag** — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.
> — skill-creator, "Improving the skill" §3
**공식 가이드와 커뮤니티 디자인 스킬이 정면으로 충돌한다.** 이 긴장은 실재하며, designpaca는 입장을 정해야 한다. 필자의 판단은 05-recommendations.md에 정리했다.
### 4.2 다이얼(Dial) 시스템
design-taste-frontend / v1 / image-to-code / imagegen-* 가 모두 공유하는 발명품.
```
* **`DESIGN_VARIANCE: 8`** - 1 = Perfect Symmetry, 10 = Artsy Chaos
* **`MOTION_INTENSITY: 6`** - 1 = Static, 10 = Cinematic / Physics
* **`VISUAL_DENSITY: 4`** - 1 = Art Gallery / Airy, 10 = Cockpit / Packed Data
```
핵심 3요소:
1. **레벨별 구체적 CSS 정의** (§7): `8-10 (Asymmetric): Masonry layouts, CSS Grid with fractional units (grid-template-columns: 2fr 1fr 1fr), massive empty zones (padding-left: 20vw)`
2. **브리프 → 다이얼 매핑 표** (§1.A): "minimalist / clean / calm / editorial / Linear-style" → VARIANCE 5-6, MOTION 3-4, DENSITY 2-3
3. **다이얼로 게이팅되는 규칙**: `Centered Hero sections are avoided when DESIGN_VARIANCE > 4`, `Use when MOTION_INTENSITY > 5`
그리고 자기 일관성 검증 규칙:
> **"Motion claimed, motion shown."** If `MOTION_INTENSITY > 4`, the page must actually move ... A static page that claims `MOTION_INTENSITY: 7` is broken. Conversely, if you cannot ship working motion in the available scope, drop the dial to 3 and ship a clean static page.
또한 별칭 금지:
> Cross-references throughout this document refer to these exact variable names - **never invent aliases like `LAYOUT_VARIANCE` or `ANIM_LEVEL`.**
image-to-code는 다이얼을 9개로 늘렸다: `DESIGN_VARIANCE, VISUAL_DENSITY, ART_DIRECTION, IMPLEMENTATION_CLARITY, IMAGE_USAGE_PRIORITY, SPACING_GENEROSITY, ANALYSIS_PRECISION, IMAGE_GENERATION_EAGERNESS, UI_SIMPLICITY_DISCIPLINE`. 9개는 과하다. 3개가 인지 부하 대비 효과가 가장 좋다.
### 4.3 게이트(Gate) 패턴
출력 전에 반드시 통과해야 하는 관문.
**gpt-taste — `<design_plan>` 강제 출력:**
> ## 8. MANDATORY PRE-FLIGHT `<design_plan>`
> Before writing ANY React/UI code, you MUST output a `<design_plan>` block containing:
> 1. **Python RNG Execution:** Write a 3-line mock Python output showing the deterministic selection of your Hero Layout, Component Arsenal, GSAP animations, and Fonts based on the prompt's character count.
> 2. **AIDA Check:** ...
> 3. **Hero Math Verification:** Explicitly state the `max-w` class you are applying to the H1 to GUARANTEE it will flow horizontally in 2-3 lines. ...
> 4. **Bento Density Verification:** Prove mathematically that your grid columns and rows leave zero empty spaces ...
> 5. **Label Sweep & Button Check:** ...
> Only output the UI code after this rigorous verification is complete.
**design-taste-frontend — Design Read 한 줄 선언:**
> ### 0.B Output a one-line "Design Read" before generating
> Before any code, state in one line: **"Reading this as: \<page kind> for \<audience>, with a \<vibe> language, leaning toward \<design system or aesthetic family>."**
**high-end-visual-design — 실행 순서 5단계:**
> 1. **[SILENT THOUGHT]** Roll the Variance Engine (Section 3). ...
> 2. **[SCAFFOLD]** ... 3. **[ARCHITECT]** ... 4. **[CHOREOGRAPH]** ... 5. **[OUTPUT]** ...
### 4.4 기계적으로 검증 가능한 규칙
가장 강력한 발명. **"세어서 확인할 수 있는" 규칙**을 만든다.
> * **EYEBROW RESTRAINT (mandatory, the #1 violated rule in production tests).** ... Hard rule:
> - **Maximum 1 eyebrow per 3 sections.** Hero counts as 1. So a page with 9 sections may use at most 3 eyebrows total.
> - If section A has an eyebrow, the next 2 sections cannot have one.
> - **Pre-Flight Check is mechanical:** count instances of `uppercase tracking` (or similar small-caps mono labels above headlines) across all section components. **If count > ceil(sectionCount / 3), the output fails.**
> — design-taste-frontend §4.7
다른 기계적 규칙들:
- `ZIGZAG ALTERNATION CAP`: "Max 2 sections in a row with this image+text-split pattern. The 3rd consecutive image+text split is a Pre-Flight Fail."
- `MARQUEE MAX-ONE-PER-PAGE`
- `BENTO CELL COUNT RULE`: "A bento grid has EXACTLY as many cells as you have content for. 3 items → 3 cells"
- `Section-Layout-Repetition Ban`: "A landing page with 8 sections must use at least 4 different layout families."
- `Hero MUST fit in the initial viewport`: "headline max 2 lines on desktop, subtext max **20 words** AND max 3-4 lines"
- `HERO STACK DISCIPLINE (max 4 text elements)`
- gpt-taste: "The H1 MUST NEVER exceed 2 to 3 lines. 4, 5, or 6 lines is a catastrophic failure."
**주관적 취향 판단("세련되게")을 세는 규칙으로 번역한 것.** 이게 anti-slop 스킬의 진짜 기술이다.
### 4.5 조건부 발동 ("contextual" 규칙)
> ## 5. CONTEXT-AWARE PROACTIVITY
> These are tools, not defaults. Use them when the design read calls for them. **None of these fire automatically.**
> * **Liquid Glass / Glassmorphism:** Appropriate for premium consumer, Apple-adjacent, luxury brand, or media-overlay vibes. **Inappropriate for dashboards, public-sector, or "boring B2B."**
> — design-taste-frontend §5
그리고 모션 정당화 요구:
> * **MOTION MUST BE MOTIVATED (mandatory).** Before adding any animation, ask: "what does this animation communicate?" Valid answers: hierarchy, storytelling, feedback, state transition. **Invalid answer: "it looked cool".** GSAP everywhere because GSAP is available is amateur. ... **If you cannot articulate the reason in one sentence, drop the animation.**
### 4.6 랜덤화 / 반복 회피 장치
같은 결과물이 반복되는 것을 막는 세 가지 접근.
**gpt-taste — 가짜 Python RNG:**
> ## 1. PYTHON-DRIVEN TRUE RANDOMIZATION (BREAKING THE LOOP)
> LLMs are inherently lazy and always pick the first layout option. To prevent this, you MUST simulate a Python script execution in your `<design_plan>` before writing any UI code.
> Use a deterministic seed (e.g., character count of the user prompt modulo math) to simulate `random.choice()` and strictly select: 1 Hero Architecture, 1 Typography Stack, 3 Unique Component Architectures, 2 Advanced GSAP Paradigms.
> **You are forbidden from defaulting to the same UI twice.**
**high-end-visual-design — Variance Engine:**
> ## 3. THE CREATIVE VARIANCE ENGINE
> Before writing code, silently "roll the dice" and select ONE combination from the following archetypes ...
> ### A. Vibe & Texture Archetypes (Pick 1) — Ethereal Glass / Editorial Luxury / Soft Structuralism
> ### B. Layout Archetypes (Pick 1) — The Asymmetrical Bento / The Z-Axis Cascade / The Editorial Split
**design-taste-frontend — 세션 간 회전 규칙 (파일 없이):**
> **Palette-rotation rule:** if the previous premium-consumer project you generated used the beige+brass family, this one MUST use a different family. Do not ship the same warm-craft palette twice in a row.
> **Serif discipline**: ... Different serif from your previous project?
**이 세 번째 방식은 작동하지 않는다.** 모델은 이전 세션을 기억하지 못한다. "이전 프로젝트와 다르게"는 상태 저장 없이는 실현 불가능한 지시다. (Hallmark가 `.hallmark/log.json`으로 이 문제를 푼 것과 대조된다 → 02-prompt-techniques.md 기법 12)
### 4.7 코드 스켈레톤 제공
design-taste-frontend만 실제 작동 코드를 담는다. §5.A/5.B/5.C에 GSAP Sticky-Stack, Horizontal-Pan, Motion whileInView 스켈레톤 3개. 각각 뒤에 "Critical points"를 한 줄로 요약:
> Critical points: `start: "top top"`, `pin: true`, every card except the last is pinned, the scale/opacity transform is driven by the NEXT card's scroll trigger (so previous card shrinks as next one arrives).
그리고 Pre-Flight에서 이를 참조:
> - [ ] **GSAP sticky-stack / horizontal-pan** implemented per Section 5.A / 5.B canonical skeleton (`start: "top top"`, `pin: true`, correct scrub)?
이건 잘한 설계다. **"이렇게 하라"가 아니라 "이 코드를 써라"**이므로 재현성이 높다.
---
## 5. AI 슬롭 방지 장치 원문 목록
designpaca가 참조해야 할 실제 금지 항목들. 출처를 정확히 표기한다.
### 5.1 design-taste-frontend §9.F "Production-Test Tells (banned outright)"
이 섹션 서문:
> These patterns came out of real LLM-generated landing-page tests. They are the signatures the model defaults to when it tries to "look designed."
**히어로/상단:**
- `NO version labels in the hero.` — `V0.6`, `v2.0`, `BETA`, `INVITE-ONLY PREVIEW`, `EARLY ACCESS`, `ALPHA`
- `NO "Brand · No. 01"-style sub-eyebrows.` — "Marrow · No. 01 · The 6-quart" 타입
**섹션 번호·마이크로 라벨:**
- `NO section-number eyebrows.` — `00 / INDEX`, `001 · Capabilities`, `002 · Featured commission`, `06 · how it works`, `05 · The honest table`
- `NO 01 / 4-style pagination on images or bento tiles.` — "If the user can count, they don't need the label."
- `NO "Index of Work, 2018 - 2026"-style range labels`
**구분자·점:**
- `The middle-dot (·) is rationed. Maximum 1 per line in metadata strips.`
- `NO decorative colored status dots on every list/nav/badge.`
**대시·타이포 장식:**
- `NO em-dash (—) as a design element OR anywhere else.`
- `NO <br>-broken-and-italicized headlines` — "for thirty\<br\>*years.*"
- `NO vertical rotated text` — "INDEX OF WORK, 2018 - 2026" 90도 회전
- `NO crosshair / hairline grid lines as decoration.`
**가짜 제품 프리뷰:**
- `NO div-based fake product UI in the hero` — "It is the #1 LLM-design Tell."
- `NO fake version footers` — "v0.6.2-rc.1", "last sync 4s ago · main"
**마케팅 카피 텔:**
- `NO "Quietly in use at" / "Quietly trusted by"`
- `NO "From the field" / "Field notes" / "Currently on the bench" / "On our desks" style poetic labels` — "Reads as performative-craftsman."
- `NO "We respect the French ones"-style mock-humble industry-references`
- `NO weather / locale strips` — "LIS 14:23 · 18°C"
- `NO micro-meta-sentences under eyebrows.` — 예: *"Each of these is a feature we ship today, not a roadmap promise. The list will stay short on purpose."*
- `NO generic step labels.` — "Stage 1 / Stage 2 / Stage 3", "Phase 01 / Phase 02 / Phase 03", "Pass One / Pass Two / Pass Three"
**필·라벨·버전 스탬프:**
- `NO pills/labels/tags overlaid on images.`
- `NO photo-credit captions as decoration.` — `Field study no. 12 · Ines Caetano`, `Plate 03 · House archive`, `Frame XII · 35mm`
- `NO version footers on marketing pages.` — `v1.4.2`, `Build 0048`
- `NO "Reservation 412 of 800"-style live-stock counters`
**장식 텍스트 스트립:**
- `NO decoration text strip at hero bottom.` — `BRAND. MOTION. SPATIAL.`, `TYPE / FORM / MOTION`, `DESIGN · BUILD · SHIP`, `ESTD. 2018 · LISBON · ...`
- `NO floating top-right sub-text in section headings.`
**리스트·구분선·스코어:**
- `NO border-t + border-b on every row of a long list / spec table.`
- `NO scoring/progress bars with filled background tracks as comparison visuals.`
**로케일·시간·스크롤 큐:**
- `Locale / city-name / time / weather strips are banned for 99% of briefs.`
- `Scroll cues are banned.` — `Scroll`, `↓ scroll`, `Scroll to explore`, 애니메이션 마우스휠 아이콘. 이유가 훌륭하다: *"If the user has not scrolled yet, they are looking at the hero. They know what scroll is. The bottom of the viewport does not need a label."*
- `ZERO decorative status dots by default.`
### 5.2 design-taste-frontend §4.2 프리미엄 소비재 팔레트 금지 (hex 단위)
> **PREMIUM-CONSUMER PALETTE BAN (mandatory, second-most-recurring AI-tell):**
> - Backgrounds: `#f5f1ea`, `#f7f5f1`, `#fbf8f1`, `#efeae0`, `#ece6db`, `#faf7f1`, `#e8dfcb` (all "warm paper / cream / chalk / bone")
> - Accents: `#b08947`, `#b6553a`, `#9a2436`, `#9c6e2a`, `#bc7c3a`, `#7d5621` (all "brass / clay / oxblood / ochre")
> - Text: `#1a1714`, `#1a1814`, `#1b1814` (all "espresso / warm near-black")
>
> This palette is BANNED as the default reach for premium-consumer briefs. **Every premium-consumer site you have ever shipped uses this exact palette. The brand becomes invisible.**
그리고 대안을 회전 목록으로 제공한다: Cold Luxury / Forest / Black and Tan / Cobalt + Cream / Terracotta + Slate / Olive + Brick + Paper / Pure monochrome + single saturated pop.
**hex 코드 단위로 금지한 것은 로컬 스킬 중 이것뿐이다.** 매우 구체적이고 검증 가능하다.
### 5.3 design-taste-frontend §4.1 세리프 금지
> * **SERIF DISCIPLINE (VERY DISCOURAGED AS DEFAULT):**
> * "It feels creative / premium / editorial" is NOT a reason to reach for serif. **The agent's default mental model that "creative brief = serif" is the single most-tested AI tell in production rounds.**
> * **Specifically BANNED as defaults:** `Fraunces` and `Instrument_Serif` (the two LLM-favorite display serifs).
> * **EMPHASIS RULE:** ... Do NOT inject a random serif word into a sans headline (or vice versa) just to add visual interest. **Mixed-family emphasis is amateur.**
### 5.4 image-to-code §29 ANTI-AI-SLOP RULES
카테고리 5개로 분류한 것이 특징:
> ### Layout slop
> - one giant unreadable collage / endless centered sections / identical card rows repeated section after section / cloned left-text/right-image blocks / fake complexity without hierarchy / decorative empty space with no purpose / **cards-inside-cards-inside-cards** / giant rounded wrapper sections around everything / overcompartmentalized dashboard framing
>
> ### Visual slop
> - default purple/blue AI gradients / too many glowing edges / floating blobs everywhere / glassmorphism stacked without reason / random futuristic details with no structure / over-rendered noise that hides the layout
>
> ### Typography slop
> - giant heading + weak tiny subcopy / too many font moods / awkward line breaks / lazy all-caps everywhere / generic gradient headline tricks
>
> ### Content slop
> Avoid generic filler vibes like: unleash / elevate / revolutionize / next-gen / seamless / transformative platform
> Avoid fake brand slop: Acme / Nexus / Flowbit / Quantumly / NovaCore
> Avoid fake complexity slop: pseudo-enterprise control labels / decorative system markers / filler status microcopy / **fake operator / runtime / orchestration jargon unless truly central to the brand**
>
> ### Density slop
> - over-packed sections / card overload / tiny spacing between major sections / visually exhausting walls of content
### 5.5 imagegen-frontend-mobile §21 MOBILE ANTI-AI-TELLS
모바일 특화 목록. 특히:
> ### Layout AI tells
> - fake chart dashboard spam / repeated stat cards with no product reason / **a homepage that looks like 12 widgets fighting for attention** / cloned screens in a flow / giant empty cards with weak content / **phone-shaped websites instead of app screens**
>
> ### UI clutter tells
> - too many pills / too many badges / too many tiny labels / fake system markers / meaningless avatar rows / random chart inserts / **decorative toggles with no product meaning**
### 5.6 minimalist-ui §2 Absolute Negative Constraints
> - DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces.
> - DO NOT use generic, thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons".
> - DO NOT use Tailwind's default heavy drop shadows (`shadow-md`, `shadow-lg`, `shadow-xl`).
> - DO NOT use primary colored backgrounds for large elements or sections.
> - DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
> - DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons.
> - DO NOT use emojis anywhere in code, markup, text content, headings, or alt text.
> - DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum".
> - DO NOT use AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve".
### 5.7 high-end-visual-design §2 "ABSOLUTE ZERO" DIRECTIVE
> If your generated code includes ANY of the following, **the design instantly fails**:
> - **Banned Fonts:** Inter, Roboto, Arial, Open Sans, Helvetica.
> - **Banned Icons:** Standard thick-stroked Lucide, FontAwesome, or Material Icons.
> - **Banned Borders & Shadows:** Generic 1px solid gray borders. Harsh, dark drop shadows (`shadow-md`, `rgba(0,0,0,0.3)`).
> - **Banned Layouts:** Edge-to-edge sticky navbars glued to the top. Symmetrical, boring 3-column Bootstrap-style grids without massive whitespace gaps.
> - **Banned Motion:** Standard `linear` or `ease-in-out` transitions. Instant state changes without interpolation.
### 5.8 stitch-design-taste §9 Anti-Patterns (AI Tells)
DESIGN.md 산출물에 넣을 목록으로 규정:
> - No emojis anywhere / No `Inter` font / No generic serif fonts / No pure black (`#000000`) / No neon/outer glow shadows / No oversaturated accents / No excessive gradient text on large headers / No custom mouse cursors / No overlapping elements / No 3-column equal card layouts / No generic names ("John Doe", "Acme", "Nexus") / **No fake round numbers (`99.99%`, `50%`)** / No AI copywriting clichés / **No filler UI text: "Scroll to explore", "Swipe down", scroll arrows, bouncing chevrons** / No broken Unsplash links / No centered Hero sections (for high-variance projects)
### 5.9 gpt-taste §7 The Meta-Label Ban
> **The Meta-Label Ban:** BANNED FOREVER are labels like "SECTION 01", "SECTION 04", "QUESTION 05", "ABOUT US". Remove them entirely. **They look cheap and unprofessional.**
### 5.10 frontend-design (Anthropic 공식) — 3대 기본값 지목
공식 스킬은 금지 목록 대신 "현재 AI 디자인이 수렴하는 세 가지 룩"을 이름 붙여 지목한다:
> AI-generated design right now clusters around three looks: (1) a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta accent; (2) a near-black background with a single bright acid-green or vermilion accent; (3) a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns. **All three are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject.** Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. **Where it leaves an axis free, don't spend that freedom on one of these defaults.**
artifact-design(빌트인)은 여기에 더 붙인다:
> a purple-to-blue gradient hero on white; Inter or Space Grotesk as the "safe" face; emoji as section markers; everything centered; `rounded-lg` everywhere; accent bar/rail on rounded cards.
**"Where it leaves an axis free, don't spend that freedom on one of these defaults."** 이 한 문장이 커뮤니티 스킬의 200줄짜리 금지 목록과 같은 일을 한다. 표현 밀도의 차이가 극적이다.
### 5.11 브랜드킷 — 이미지 도메인 anti-generic
> # ANTI-GENERIC RULES
> Never make: random floating icons / generic startup gradients / overdesigned logos / meaningless blobs / messy layout collages / fake tiny UI / inconsistent logo marks / too many colors / cheap neon / stock-template brand boards / corporate PowerPoint slides / soulless SaaS dashboards
>
> **Make the design quieter, sharper, and more intentional.**
레퍼런스 사용 규칙도 훌륭하다:
> Do not copy: exact logo / exact brand name / exact composition / exact slogan / unique visual asset
> **Use references as quality training, not as templates.**
---
## 6. 스킬별 강점·약점
### design-taste-frontend (v2)
**잘하는 것**
- **브리프 추론 우선(§0)**: 유일하게 "먼저 읽고 나중에 만들라"를 1번 섹션에 놓았다. 나머지 스킬은 전부 미학을 먼저 선언한다.
- **조건부 규칙 철학**: "Every rule below is contextual. None of it fires automatically."
- **기계적 검증 규칙**: eyebrow 카운트, zigzag 캡, bento 셀 카운트 등 세서 확인 가능
- **실제 디자인 시스템 매핑(§2.A)**: Fluent / Material / Carbon / Polaris / Atlaskit / Primer / GOV.UK / USWDS를 브리프 유형에 매핑하고 부록에 실제 설치 명령어와 공식 문서 링크를 담았다. **"AI가 CSS를 즉흥 발명하는 것"을 막는 가장 실용적인 장치.**
- **범위 밖 선언(§13)**: "This skill is NOT for: Dashboards / Data tables / Multi-step forms / Code editors / Native mobile / Realtime collab UIs" 그리고 "If the brief is one of the above, **say so explicitly**, point to the right tool"
- **리디자인 프로토콜(§11)**: 모드 감지 → 감사 → 보존 규칙 → 현대화 레버 우선순위 → 결정 트리. SEO 마이그레이션을 "#1 redesign risk"로 지목한 것이 실전적이다.
- **오버라이드 경로**: 거의 모든 금지 규칙에 명시적 탈출구가 있다
**못하는 것**
- **88KB / 1,206줄**: 공식 권고(500줄)의 2.4배. 발동 시 약 22K 토큰 상주, 컴팩션 시 앞 5K만 생존 → **가장 중요한 §9와 §14가 날아간다**
- **references/ 분리 0**: 부록 A/B/C(설치 명령, 공식 문서 링크, Liquid Glass 근사법)는 명백히 참조 파일로 뺐어야 한다
- **Pre-Flight 체크박스 60개**: 매번 60개를 전부 정직하게 체크하는 것은 비현실적이다. 순위나 티어가 없다
- **§12 블록 라이브러리가 유령**: 존재하지 않는 파일 경로를 지시한다
- **세션 간 회전 규칙이 작동 불가**: "different serif from your previous project"는 상태 저장 없이는 실행 불가
- **`gsap` 의존**: §5.A/5.B가 GSAP 전제. §3.A는 Motion(framer-motion)을 기본으로 선언 → 스택 이중화
- **Next.js/React/Tailwind 고정**: Vue, Svelte, Astro, 바닐라 HTML에 대한 언급이 §3.A에 없다
### design-taste-frontend-v1
**잘하는 것**: 226줄로 짧다. 다이얼 시스템의 원형. §9 "Motion-Engine Bento Paradigm"의 5-카드 아키타입은 구체적이고 재현 가능하다.
**못하는 것**: 브리프 추론이 없다. 모든 규칙이 무조건 발동한다. "LILA BAN", "strictly BANNED"만 있고 오버라이드가 없다. 히어로 규율, eyebrow 규율, 카피 자가 감사가 전부 없다. 실전 테스트에서 나온 텔 목록(§9.F)이 없다.
### high-end-visual-design
**잘하는 것**
- **Double-Bezel(Doppelrand) 기법**이 구체적이다: 외곽 셸 `p-1.5 rounded-[2rem] ring-1 ring-black/5` + 내부 코어 `rounded-[calc(2rem-0.375rem)]` + `shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]`. **동심원 반경 계산까지 지시한다.**
- **Button-in-Button 화살표 패턴**: 재현 가능한 시그니처
- 각 레이아웃 아키타입마다 **모바일 붕괴 규칙을 함께 적었다** ("Mobile Collapse: Remove all rotations and negative-margin overlaps below 768px. Overlapping elements cause touch-target conflicts on mobile.")
- 성능 가드레일(§6)이 이유와 함께 적혀 있다: "Never apply blur filters to scrolling containers or large content areas — this causes continuous GPU repaints and severe mobile frame drops."
**못하는 것**: 브리프 읽기 없음. Awwwards 미학 하나만 강제한다. B2B, 공공, 접근성 우선 브리프에 재앙적이다. `rounded-[2rem]` squircle과 glass가 모든 프로젝트에 강요된다.
### minimalist-ui / industrial-brutalist-ui
**잘하는 것**
- **미학 하나에 완전히 커밋한다.** 그래서 hex 값, 폰트명, border 값까지 구체적으로 지정할 수 있다 (`border: 1px solid #EAEAEA`, `#FDEBEC` / 텍스트 `#9F2F2D`)
- industrial-brutalist는 **모드 선택을 강제한다**: "Pick ONE per project and commit to it. **Do not alternate or mix both modes within the same interface.**" 그리고 팔레트도: "Choose ONE substrate palette per project... **Never mix light and dark substrates within the same interface.**"
- industrial-brutalist §8.1의 그리드 기법이 영리하다: "Utilize `display: grid; gap: 1px;` with contrasting parent/child background colors to generate mathematically perfect, razor-thin dividing lines without complex border declarations."
- 시맨틱 태그 지시: `<data>`, `<samp>`, `<kbd>`, `<output>`, `<dl>`
**못하는 것**: 스타일 스킬이지 디자인 스킬이 아니다. 브리프를 읽지 않는다. designpaca가 여러 미학을 다루려면 이건 "테마 파일"로 흡수되어야 할 형태다.
### gpt-taste
**잘하는 것**
- **모델의 실패를 이름 붙여 지목한다**: "Standard LLMs possess severe statistical biases: they generate massive 6-line wrapped headings **by using narrow containers**, leave ugly empty gaps in bento grids, use cheap meta-labels, output invisible button text, and endlessly repeat the same Left/Right layouts."
- **원인까지 짚는다**: 6줄 헤드라인의 원인이 "좁은 컨테이너"임을 지적하고 해법을 준다 ("You MUST use ultra-wide containers for the H1 (`max-w-5xl`, `max-w-6xl`, `w-full`)")
- `grid-flow-dense` 지시: bento 빈칸 문제의 실제 CSS 해법
- 버튼 대비 체크: "Dark background = white text. Light background = dark text. Invisible text is a failure."
**못하는 것**: "Python RNG 시뮬레이션"은 인지적 연극이다. 모델은 진짜 난수를 못 만든다. 프롬프트 문자 수 모듈로는 같은 프롬프트에 항상 같은 결과를 준다. 다만 **"선택했음을 명시적으로 출력하게 만드는" 효과**는 실재한다. GSAP 강제(§5)는 React 외 스택에서 무의미하다.
### imagegen-frontend-web / mobile
**잘하는 것**
- **HARD OUTPUT RULE을 파일 최상단에 배치**하고 그 자체로 별도 섹션을 만들었다. "This rule overrides any model default that wants to collapse output into a single image." 모델 기본 동작과 충돌하는 규칙임을 인지하고 명시적으로 이긴다고 선언한다.
- **조합 변형 엔진(Combinatorial Variation Engine)**: Theme Paradigm / Background Character / Typography Character / Hero Architecture / Section System / Signature Component Set / Motion-Implied Language / Composition Anchor / Background Mode / CTA Variation / Hero Scale / Narrative Spine / Second-Read Moment. **축별로 옵션을 나열하고 "섹션마다 하나씩 고르되 페이지 전체에서 최소 3개 앵커가 등장해야 한다"는 분산 규칙을 준다.**
- **가장 흔한 기본값을 명시적으로 강등**: "The default **left-text / right-image hero is the most overused AI pattern**. It is allowed, but **it should not be your first instinct**." 그리고 대안 10개를 나열한다.
- mobile §25 "NOT ALWAYS SIMPLE RULE": "Simplicity is not the goal by itself. **Cleanliness is the goal.** ... The rule is: not always simple, always clean." 미니멀리즘 과잉 편향을 교정한다.
- mobile §35 QUALITY CHECK 27문항이 자문 형식이다: "**Were too few screens generated out of laziness?**"
**못하는 것**: 987줄 / 1,465줄. 이미지 생성 도구 없는 환경에서는 대부분 무용지물. 규칙 번호가 37개까지 가면서 서로 중복된다.
### image-to-code
**잘하는 것**: "이미지 먼저, 코드는 번역 레이어"라는 강한 워크플로 선언 ("The image is the design source. The code is the translation layer."). §21~§25 추출 규칙(텍스트/타이포/스페이싱/컴포넌트/컬러)이 명확하다. §33 기본 섹션 팩(4/8/12) 제공.
**못하는 것**: 이미지 생성 도구 없으면 전체가 죽는다. 1,228줄. 다이얼 9개는 과하다.
### redesign-existing-projects
**잘하는 것**
- **구조가 다른 스킬과 완전히 다르다.** 미학 선언이 아니라 **"문제 → 고치는 법" 페어 나열**이다:
> - **Buttons not bottom-aligned in card groups.** When cards have different content lengths, CTAs end up at random heights. Pin buttons to the bottom of each card so they form a clean horizontal line regardless of content above.
- **"AI가 빼먹는 것" 섹션**이 독보적이다: 법적 링크, 뒤로가기, 404 페이지, 폼 검증, skip-to-content 링크, 쿠키 동의
- **광학적 정렬** 같은 미묘한 항목이 있다: "Mathematical alignment that looks optically wrong. Centering by the math doesn't always look centered to the eye. Icons next to text, play buttons in circles, or text in buttons often need 1-2px optical adjustments."
- **수정 우선순위**가 위험 대비 효과 순이다: "1. Font swap — biggest instant improvement, lowest risk"
- **스택 불가지론**: "Work with the existing tech stack. Do not migrate frameworks or styling libraries."
**못하는 것**: 감사 항목 100개 이상을 나열만 하고 우선순위 티어가 없다(우선순위는 마지막 7단계뿐). 다이얼이나 브리프 추론이 없다.
### stitch-design-taste
**잘하는 것**: **메타 스킬이다.** 자기가 디자인하지 않고 `DESIGN.md`를 생성해서 다른 도구(Google Stitch)가 읽게 한다. 출력 템플릿을 마크다운 코드블록으로 정확히 제시한다. Best Practices / Tips / Common Pitfalls 3단 구성이 좋다:
> - **Be Descriptive:** "Deep Charcoal Ink (#18181B)" — not just "dark text"
> - **Be Opinionated:** This is not a neutral template — it enforces a specific, premium aesthetic
> - Common Pitfall: "Using technical jargon without translation ("rounded-xl" instead of "generously rounded corners")"
**못하는 것**: Stitch 전용. 하지만 **"휴대용 design.md를 산출한다"는 아이디어 자체는 designpaca가 반드시 훔쳐야 한다.** (Superdesign의 `.superdesign/design-system.md`, Hallmark의 `design.md`도 같은 패턴)
### brandkit
**잘하는 것**: 로고 컨셉 방법론 5종(Monogram+Meaning / Product Action / Metaphor Fusion / Negative Space / Construction Geometry)을 구체적으로 나눈다. 시각 모드 8종에 각각 팔레트·타이포·이미지 방향이 붙는다. 텍스트 절제 규칙이 이미지 생성 맥락에서 정확하다("Text should be large enough and sparse enough to render well"). 태그라인 좋은 예/나쁜 예를 실제 문장으로 준다.
**못하는 것**: 웹 디자인 스킬이 아니다.
### full-output-enforcement
**잘하는 것**: 60줄로 한 가지 문제(잘림)만 판다. **금지 패턴을 문자열 단위로 나열한다**:
> **In code blocks:** `// ...`, `// rest of code`, `// implement here`, `// TODO`, `/* ... */`, `// similar to above`, `// continue pattern`, `// add more as needed`, bare `...`
> **In prose:** "Let me know if you want me to continue", "I can provide more details if needed", "for brevity", "the rest follows the same pattern", ...
그리고 **한계 도달 시의 행동을 정의한다**:
> `[PAUSED — X of Y complete. Send "continue" to resume from: next section name]`
> On "continue", pick up exactly where you stopped. No recap, no repetition.
**"Scope → Build → Cross-check"** 3단계에서 "Count how many distinct deliverables are expected. **Lock that number.**"가 핵심.
**못하는 것**: 디자인 스킬이 아니다. 하지만 designpaca가 여러 섹션을 한 번에 출력해야 할 때 이 기법을 흡수해야 한다.
### graphify
**잘하는 것**: 스킬이 아니라 **CLI 파이프라인 실행 매뉴얼**이다. Usage 블록에 커맨드 20여 개를 나열하고, Step 1~9를 순서대로 실행하게 한다. 각 스텝에 실제 Python/bash 코드가 있다. 그리고:
> ## Honesty Rules
> - Never invent an edge. If unsure, use AMBIGUOUS.
> - Never skip the corpus check warning.
> - Always show token cost in the report.
> - Never hide cohesion scores behind symbols - show the raw number.
> - Never run HTML viz on a graph with more than 5,000 nodes without warning the user.
**"Honesty Rules"라는 별도 섹션**은 좋은 패턴이다. designpaca에도 "이미지가 없으면 없다고 말하라", "가짜 지표를 만들지 말라" 류의 정직성 규칙 섹션이 필요하다.
**못하는 것**: `trigger:` 비표준 필드 사용. 1,242줄.
### frontend-design (Anthropic 공식)
**잘하는 것**
- **약 40줄. 산문. 금지 목록 거의 없음.** 그런데 효과가 있다.
- **역할 부여가 구체적이다**: "Approach this as the design lead at a small studio known for giving every client a visual identity that could not be mistaken for anyone else's. **This client has already rejected proposals that felt templated**, and is paying for a distinctive point of view"
- **주제에 뿌리내리기**: "The subject's own world, its materials, instruments, artifacts, and vernacular, is where distinctive choices come from."
- **2패스 프로세스**: 계획(토큰 시스템 4요소: Color 4-6 hex / Type 2+ roles / Layout ASCII 와이어프레임 / Signature) → **계획을 브리프에 대조 검토** → 코드
- **자기 검증 방법이 영리하다**: "if any part of it reads like the generic default you would produce for any similar page (**work through a similar prompt to see if you arrive somewhere similar**) rather than a choice made for this specific brief — revise that part, say what you changed and why."
- **절제의 원칙**: "**Spend your boldness in one place.** Let the signature element be the one memorable thing, keep everything around it quiet and disciplined... Consider Chanel's advice: before leaving the house, take a look in the mirror and **remove one accessory**."
- **위험 감수도 리스크임을 짚는다**: "Not taking a risk can be a risk itself!"
- **카피 작성 지침을 디자인의 일부로 다룬다**: "Words appear in a design for one reason: to make it easier to understand... They are design material, not decoration." / "A person manages notifications, not webhook config." / "An action keeps the same name through the whole flow, so the button that says 'Publish' produces a toast that says 'Published.'"
- **CSS 실무 함정 하나만 콕 집는다**: "It's easy to generate CSS classes that cancel each other out (especially with a type-based selector like `.section` and a element-based selector like `.cta`)"
**못하는 것**: 구체적 CSS 값, 폰트명 후보, 팔레트가 전혀 없다. 초보 모델이나 저사양 모델에서는 "무엇을 해야 할지" 감이 안 잡힐 수 있다. 검증 가능한 게이트가 없다.
### artifact-design (빌트인, Skill 도구로 확인)
**잘하는 것**
- **"디자인할지 말지"가 아니라 "어떤 트리트먼트인지"를 먼저 정하게 한다**: "Calibrate treatment, not whether to design. A doc deserves the same craft as a landing page — what changes is the treatment that craft is delivered in."
- **유틸리티 트리트먼트를 명시적으로 인정한다**: "Many requests call for a more utilitarian treatment: a plan, a memo, a demo. Make it polished... but avoid over-designing. **Most pages do not need a flashy, gigantic hero.**"
- **판단 기준 한 줄**: "When unsure: a well-composed page is never the wrong answer; an over-designed visual identity sometimes is."
- **우선순위 체인**: "Precedence is always: the user's own words, then the project's existing system, then your choices."
- **기존 시스템 존중을 1번에 놓았다**: "Look for an existing design system first — CLAUDE.md, a tokens or theme file, existing component styles."
- **뉴트럴 선택 원칙**: "A pure mid-grey reads as unconsidered; **a grey with a slight hue bias toward the page's accent reads as chosen.** ... the point is that the neutral was picked, not inherited."
- **다크모드를 3상태로 정확히 다룬다** (`data-theme` 스탬프 있음/없음 + `prefers-color-scheme`), 그리고 실패 모드를 이름 붙인다: "scan the stylesheet for any color declared only inside a media or `[data-theme]` block — **that is the classic unreadable-artifact bug.**"
- **레이아웃 스페이싱 원칙 한 줄**: "Lay out sibling groups with flex or grid and `gap`, not per-element margins that silently collapse or double."
- **"UI일 때는 다르다"를 분리**: "A dashboard or tool is scanned and operated, not read top-to-bottom, so the craft shifts from typography to information design. **Surface the summary before the detail; encode state in form as well as number.**"
**못하는 것**: Artifact 런타임 전용 제약(CSP, 폰트 호스트)이 섞여 있어 그대로 이식 불가.
### dataviz (빌트인)
**잘하는 것**
- **절차를 순서로 못 박고 이유를 준다**: "Color comes LAST. Most bad charts pick colors first."
- **"계산 가능한 것은 계산하라"**: "The single most important habit: **the color part is computable, so compute it.** Never eyeball whether a palette is colorblind-safe — run `scripts/validate_palette.js`."
- **실행 가능한 검증기를 번들한다** (`scripts/validate_palette.js`, `.py`) — 스킬이 취향 판단을 스크립트로 외주 주는 유일한 사례
- **디자인 시스템 불가지론**: "The method is invariant; only these parameters change per system." 그리고 파라미터 표를 준다 (Ramps / Categorical theme / Sequential hue / Diverging pair / Status palette / Texture fill / Surfaces / Filter controls)
- **완전한 progressive disclosure**: SKILL.md ~80줄 + `references/` 7개 + `scripts/` 2개. 본문은 **인덱스 + 절차**만 담고, 각 참조 파일이 무엇에 답하는지 표로 정리한다.
- **anti-patterns.md를 별도 파일로 두고 "모든 차트를 이것과 대조하라"고 지시**한다. 각 항목이 `❌ 무엇 / Why it misleads / ✅ Do instead` 3단이다. **실제 사례까지 적는다**: "Real example: an 'Adoption' chart plotting Users (0–30k) against Sessions (0–800k) — a reviewer flagged it as looking 'hallucinated.'"
- **마지막에 눈으로 확인하라고 한다**: "Render it and look at it. The validator checks color, not layout — open or screenshot the output and eyeball it for label collisions, geometry, and overflow before calling it done."
**못하는 것**: 차트 전용.
### skill-creator (Anthropic 공식)
designpaca 설계에 가장 직접적으로 적용되는 스킬. 핵심 인용:
> - **description**: ... Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please **make the skill descriptions a little bit "pushy"**.
> - Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next.
> - Prefer using the imperative form in instructions.
> - **Writing Style**: Try to explain to the model why things are important **in lieu of heavy-handed musty MUSTs**. Use theory of mind and try to make the skill general and not super-narrow to specific examples.
> - **Generalize from the feedback.** ... if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working.
> - **Keep the prompt lean.** Remove things that aren't pulling their weight.
> - **Look for repeated work across test cases.** ... that's a strong signal the skill should bundle that script.
> - **How skill triggering works**: Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly.
description 최적화 평가 쿼리 작성 가이드도 중요하다:
> Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"`
> Good: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage..."`
> The key thing to avoid: **don't make should-not-trigger queries obviously irrelevant.** "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. **The negative cases should be genuinely tricky.**
---
## 7. 종합 매트릭스
| 기법 | dtf(v2) | dtf-v1 | hevd | min-ui | ibu | gpt-taste | ig-web | i2c | redesign | stitch | frontend-design(공식) | artifact-design | dataviz |
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| 브리프 추론 우선 | O | X | X | X | X | X | 부분 | 부분 | 부분 | O | O | O | O |
| 다이얼 시스템 | O | O | X | X | X | X | O | O | X | O | X | X | X |
| 금지 목록(하드 밴) | O | O | O | O | O | O | O | O | O | O | X | 부분 | 부분 |
| 조건부 오버라이드 | O | X | X | X | 부분 | X | X | X | X | X | O | O | 부분 |
| 기계적 카운트 규칙 | O | X | X | X | X | O | O | X | X | X | X | X | O |
| 출력 전 게이트/체크리스트 | O | O | O | X | X | O | O | O | X | X | O | X | O |
| 랜덤/변형 엔진 | 부분 | X | O | X | X | O | O | O | X | X | X | X | X |
| 코드 스켈레톤 | O | X | X | X | 부분 | 부분 | X | X | X | X | X | X | X |
| references/ 분리 | X | X | X | X | X | X | X | X | X | 부분 | X | X | O |
| 범위 밖 선언 | O | X | X | X | X | X | X | X | X | X | X | 부분 | 부분 |
| 실행 가능 검증기 | X | X | X | X | X | X | X | X | X | X | X | X | O |
| 산출물로 design.md | X | X | X | X | X | X | X | X | X | O | X | X | X |
| 이유(why) 서술 | 부분 | X | 부분 | X | X | O | 부분 | X | O | X | O | O | O |
| 접근성 규칙 | O | X | X | X | X | 부분 | X | X | O | O | 부분 | O | O |
| 카피/문구 규율 | O | X | X | 부분 | X | O | 부분 | O | O | O | O | O | X |
| 500줄 이하 | X | O | O | O | O | O | X | X | O | O | O | O | O |
약어: dtf = design-taste-frontend, hevd = high-end-visual-design, min-ui = minimalist-ui, ibu = industrial-brutalist-ui, ig-web = imagegen-frontend-web, i2c = image-to-code
---
## 8. 로컬 조사에서 나온 핵심 결론 5가지
1. **커뮤니티 디자인 스킬은 전부 단일 파일이고, 이게 최대 약점이다.** 13개 중 references/ 를 쓴 스킬은 0개. 반면 Anthropic 공식 dataviz는 SKILL.md 80줄 + references 7개 + scripts 2개로 같은 밀도의 지식을 1/10 토큰으로 상주시킨다.
2. **"공식 스타일"과 "커뮤니티 스타일"은 정반대 방향이다.** 공식(frontend-design, artifact-design)은 40줄 산문에 이유 중심. 커뮤니티(design-taste-frontend)는 1,206줄에 금지 목록 중심. 둘 다 효과가 있고, 둘 다 결점이 있다. designpaca는 이 두 계보를 계층으로 분리해서 합쳐야 한다(공식 스타일을 SKILL.md 본문에, 커뮤니티 스타일을 references/에).
3. **가장 강력한 발명은 "기계적으로 셀 수 있는 규칙"이다.** eyebrow ≤ ceil(sections/3), zigzag ≤ 2연속, bento 셀 = 콘텐츠 개수, 히어로 헤드라인 ≤ 2줄, 서브텍스트 ≤ 20단어, 마퀴 ≤ 1개. 주관적 취향을 카운트로 번역하면 검증 가능해진다.
4. **세션 간 다양성 규칙은 상태 저장 없이는 실패한다.** design-taste-frontend의 "different serif from your previous project"는 실행 불가능한 지시다. designpaca는 프로젝트 루트에 로그 파일을 쓰는 방식으로 이 문제를 풀어야 한다.
5. **컨텍스트 수명 관리가 설계 제약이다.** 스킬은 발동 후 세션 내내 상주하고, 컴팩션 시 앞 5,000토큰만 재부착된다. 따라서 **가장 중요한 규칙은 파일 앞쪽에 있어야 한다.** design-taste-frontend는 이걸 정반대로 했다(AI Tells가 §9, Pre-Flight가 §14). imagegen-frontend-web이 HARD OUTPUT RULE을 6번째 줄에 놓은 것이 옳다.

1626
research/skills/02-prompt-techniques.md Normal file
View file

File diff suppressed because it is too large Load diff

632
research/skills/03-format-specs.md Normal file
View file

@ -0,0 +1,632 @@
# 03. 포맷 스펙과 변환 어댑터 설계
작성일: 2026-08-20
목적: designpaca를 Claude Code / Codex / Cursor(+ Windsurf, VS Code Copilot)에서 동일하게 동작시키기 위한 정확한 포맷 스펙과 변환 시 주의점.
**중요한 전제 변화**: 2026년 8월 현재, **Cursor와 Codex 모두 Agent Skills 표준을 네이티브 지원한다.** 따라서 "SKILL.md를 .mdc로 변환"하는 어댑터는 더 이상 1순위가 아니다. 1순위는 **하나의 SKILL.md를 세 도구가 모두 읽을 수 있는 위치에 두는 것**이다. 변환 어댑터는 레거시 경로(`.cursor/rules/*.mdc`, `AGENTS.md`) 지원용으로 남는다.
---
## 1. Agent Skills 오픈 표준 (모든 도구의 공통 분모)
출처: https://agentskills.io/specification (직접 fetch)
### 1.1 디렉터리 구조
```
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
```
### 1.2 프론트매터 — 허용 필드 6개 전부
| Field | Required | Constraints (원문) |
|---|---|---|
| `name` | Yes | "Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen." |
| `description` | Yes | "Max 1024 characters. Non-empty. Describes what the skill does and when to use it." |
| `license` | No | "License name or reference to a bundled license file." |
| `compatibility` | No | "Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.)." |
| `metadata` | No | "Arbitrary key-value mapping for additional metadata (a map from string keys to string values)." |
| `allowed-tools` | No | "Space-separated string of pre-approved tools the skill may use. **(Experimental)**" |
### 1.3 `name` 상세 규칙 (원문)
> * Must be 1-64 characters
> * May only contain unicode lowercase alphanumeric characters (`a-z`, `0-9`) and hyphens (`-`)
> * Must not start or end with a hyphen (`-`)
> * **Must not contain consecutive hyphens (`--`)**
> * **Must match the parent directory name**
무효 예시:
```yaml
name: PDF-Processing # uppercase not allowed
name: -pdf # cannot start with hyphen
name: pdf--processing # consecutive hyphens not allowed
```
Anthropic 플랫폼 문서는 여기에 두 가지를 더 추가한다:
> `name`: ... **Cannot contain XML tags. Cannot contain reserved words: "anthropic", "claude"**
> `description`: ... **Cannot contain XML tags**
> — platform.claude.com Skill authoring best practices
**→ designpaca 결론**: `name: designpaca`. 예약어 없음, 하이픈 없음, 소문자만. 디렉터리명도 `designpaca`여야 한다.
### 1.4 Progressive Disclosure 3계층 (원문)
> 1. **Metadata** (~100 tokens): The `name` and `description` fields are loaded at startup for all skills
> 2. **Instructions** (< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated
> 3. **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required
>
> **Keep your main `SKILL.md` under 500 lines.** Move detailed reference material to separate files.
### 1.5 파일 참조 규칙 (원문)
> When referencing other files in your skill, use **relative paths from the skill root**:
> ```markdown
> See [the reference guide](references/REFERENCE.md) for details.
> Run the extraction script: scripts/extract.py
> ```
> **Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.**
Anthropic이 이유를 설명한다:
> Claude may partially read files when they're referenced from other referenced files. When encountering nested references, **Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.**
그리고 100줄 초과 참조 파일에는 목차를 넣으라고 한다:
> For reference files longer than 100 lines, include a table of contents at the top. **This ensures Claude can see the full scope of available information even when previewing with partial reads.**
### 1.6 검증 도구
> Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
> ```bash
> skills-ref validate ./my-skill
> ```
**→ designpaca는 이 검증기를 CI에 걸어야 한다.**
---
## 2. Claude Code SKILL.md
출처: https://code.claude.com/docs/en/skills (직접 fetch)
### 2.1 설치 위치와 우선순위
| Location | Path | Applies to |
|---|---|---|
| Enterprise | managed settings 참조 | 조직 전체 |
| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | 모든 프로젝트 |
| Project | `.claude/skills/<skill-name>/SKILL.md` | 해당 프로젝트만 |
| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | 플러그인 활성 범위 |
이름 충돌 해소 순서 (원문):
> * Across levels, **enterprise overrides personal, and personal overrides project.**
> * A skill at any of these levels also overrides a bundled skill with the same name, **but not the bundled skill's aliases.**
> * Plugin skills use a `plugin-name:skill-name` namespace, so they can't conflict with other levels.
> * If you have files in `.claude/commands/`, ... **if a skill and a command share the same name, the skill takes precedence.**
**중첩 스킬** (모노레포용):
> Skills also load from nested `.claude/skills/` directories below your working directory. ... The nested one appears under a directory-qualified name, `apps/web:deploy`.
> **Skills in nested `.claude/skills/` directories below your starting directory aren't loaded at startup.** They load the first time Claude reads or edits a file inside that subdirectory.
**심링크 지원** (중요):
> A `<skill-name>` entry in the enterprise, personal, or project locations **can be a symlink to a directory elsewhere on disk.** Claude Code follows the symlink and reads `SKILL.md` from the target directory, and **if the same target is reachable from more than one location, Claude Code loads the skill once.**
→ 이 사용자의 환경이 이미 이 방식이다. `~/.claude/skills/design-taste-frontend` → `~/.agents/skills/design-taste-frontend`. **designpaca도 `~/.agents/skills/designpaca/`를 정본으로 두고 심링크하는 것이 옳다.**
### 2.2 프론트매터 전체 필드 (Claude Code 확장 포함)
> All fields are optional. Only `description` is recommended so Claude knows when to use the skill.
> Boolean fields accept `yes`, `no`, `on`, `off`, `1`, and `0` in any letter case, in addition to `true` and `false`.
| Field | 표준? | 설명 (요약) |
|---|:-:|---|
| `name` | O | 스킬 목록 표시명. **개인/프로젝트 스킬에서는 커맨드명을 바꾸지 못한다** (디렉터리명이 커맨드명). 플러그인 스킬에서만 마지막 세그먼트를 결정 |
| `description` | O | 무엇을 하고 언제 쓰는지. **"the combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing"** |
| `when_to_use` | X | description에 덧붙는 추가 트리거 문구. **1,536자 상한에 함께 포함됨** |
| `argument-hint` | X | 자동완성 힌트. 예: `[issue-number]` |
| `arguments` | X | `$name` 치환용 명명 위치 인자 |
| `disable-model-invocation` | X | `true`면 Claude가 자동 로드 못 함. **"Description not in context"** |
| `user-invocable` | X | `false`면 `/` 메뉴에서 숨김. Claude만 호출 |
| `allowed-tools` | O(실험) | 해당 턴 동안 승인 없이 쓸 도구. **"The grant clears when you send your next message"** |
| `disallowed-tools` | X | 스킬 활성 중 제거할 도구 |
| `model` | X | 스킬 활성 시 모델 오버라이드 |
| `effort` | X | `low`/`medium`/`high`/`xhigh`/`max` |
| `context` | X | `fork` → 포크된 서브에이전트에서 실행 |
| `agent` | X | `context: fork` 시 서브에이전트 타입 |
| `background` | X | `context: fork` 시 백그라운드 여부 (기본 `true`) |
| `hooks` | X | 스킬 호출 시 등록되는 훅 |
| `paths` | X | 글롭 패턴. **"Claude loads the skill automatically only when working with files matching the patterns"** |
| `shell` | X | `bash`(기본) 또는 `powershell` |
| `metadata` | O | 자유 형식 YAML 맵 |
| `license` | O | Claude Code는 받아들이지만 아무 동작 안 함 |
| `compatibility` | O | 최대 500자. Claude Code는 받아들이지만 아무 동작 안 함 |
### 2.3 도구 밖으로 나갈 때의 하드 에러 (가장 중요한 제약)
원문:
> Claude Code accepts every field in the table above. **Outside Claude Code, you can use only the fields in the Agent Skills spec:**
>
> | Distribution path | Frontmatter fields you can use |
> |---|---|
> | Claude Code skills at any level, including plugin skills | Every field in the table above |
> | claude.ai skill uploads, the Skills API, and packaging with `package_skill.py` | `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` |
>
> **If you include any field the spec doesn't allow, packaging or upload fails with a hard error instead of ignoring the field:**
> ```
> Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name
> ```
**→ designpaca 결정: 프론트매터는 `name` + `description`만 쓴다.** 크로스툴 휴대성이 목표이므로 확장 필드는 전부 배제. 이는 로컬 커뮤니티 스킬 13개가 이미 도달한 결론과 같다.
(참고: 로컬 `graphify`의 `trigger: /graphify`는 스펙에 없는 필드다. Claude Code는 무시하지만 claude.ai 업로드/패키징 시 위 에러가 난다. designpaca는 이 패턴을 복제하면 안 된다.)
### 2.4 커맨드명이 결정되는 규칙
| Skill location | Command name source | Example |
|---|---|---|
| `~/.claude/skills/` 또는 `.claude/skills/` 아래 디렉터리 | **디렉터리명** | `.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging` |
| 중첩 `.claude/skills/` (이름 충돌 시) | 작업 디렉터리 상대 경로 + 스킬 디렉터리명 | `apps/web/.claude/skills/deploy/` → `/apps/web:deploy` |
| `.claude/commands/` 아래 파일 | 확장자 뺀 파일명 | `.claude/commands/deploy.md` → `/deploy` |
| 플러그인 `skills/` 하위 | 프론트매터 `name` 또는 디렉터리명 + 플러그인 네임스페이스 | `my-plugin/skills/review/` → `/my-plugin:review` |
| 플러그인 루트 `SKILL.md` | 프론트매터 `name` (없으면 플러그인 디렉터리명) | `name: review` → `/my-plugin:review` |
### 2.5 컨텍스트 수명 (설계 제약)
원문 그대로:
> When you or Claude invoke a skill, the rendered `SKILL.md` content enters the conversation as a single message and **stays there for the rest of the session**. ... **Claude Code does not re-read the skill file on later turns.**
>
> When Claude re-invokes a skill whose rendered content is identical to the copy already in context, Claude Code adds a short note that the skill is already loaded rather than a second copy.
>
> Auto-compaction carries invoked skills forward within a token budget. When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill after the summary, **keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens.**
>
> **If a skill seems to stop influencing behavior after the first response, the content is usually still present and the model is choosing other tools or approaches.** Strengthen the skill's `description` and instructions so the model keeps preferring it, or use hooks to enforce behavior deterministically.
**→ 설계 결론 3개**
1. SKILL.md 본문은 **5,000토큰(약 500줄) 이내**여야 컴팩션 후에도 온전히 살아남는다.
2. **가장 중요한 규칙은 파일 앞부분**에 있어야 한다.
3. 여러 스킬을 쓰는 세션에서는 25,000토큰을 나눠 쓰므로, 큰 스킬은 다른 스킬을 밀어낸다.
### 2.6 스킬 목록 예산 (트리거 실패의 숨은 원인)
원문:
> Claude Code loads a listing of skill names and descriptions into context so Claude knows what's available. The listing always contains every skill name, but **if you have many skills, Claude Code shortens descriptions to fit the listing's character budget, which can strip the keywords Claude needs to match your request. The budget scales at 1% of the model's context window.**
>
> Run `/doctor` for an estimate of the listing's context cost and its biggest contributors.
> To raise the budget, set the `skillListingBudgetFraction` setting (e.g. `0.02` = 2%) or the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable.
**→ description을 짧게 유지해야 하는 진짜 이유.** 이 사용자 환경에는 스킬이 40개 이상 있다. 620자 description(imagegen-frontend-web)은 잘려나갈 위험이 크다. **200~350자를 권장.**
### 2.7 프론트매터 파싱 실패 시
> If the frontmatter YAML is malformed, Claude Code loads the skill body with empty metadata, so `/skill-name` still works but Claude has no `description` to match against. Run with `--debug` to see the parse error.
→ 조용히 실패한다. 검증기를 돌려야 하는 이유.
### 2.8 커스텀 커맨드와의 통합
> **Custom commands have been merged into skills.** A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work the same way.
> Files in `.claude/commands/` support the same frontmatter, **except `name` and `paths`, which Claude Code ignores in a command file.**
---
## 3. Codex (OpenAI) — 두 가지 경로
Codex는 **AGENTS.md**(항상 로드되는 컨텍스트)와 **Agent Skills**(온디맨드 로드) 둘 다 지원한다. 이 둘은 역할이 다르다.
### 3.1 Codex Agent Skills
출처: https://learn.chatgpt.com/docs/build-skills (developers.openai.com/codex/skills 에서 308 리다이렉트)
**스캔 위치 (우선순위 순, 원문 기반)**
| 범위 | 경로 |
|---|---|
| Repository | `.agents/skills` — 현재 작업 디렉터리와 상위 폴더들을 repo root까지 |
| User | `$HOME/.agents/skills` |
| Admin | `/etc/codex/skills` |
| System | OpenAI 번들 |
> "If two skills share the same `name`, Codex doesn't merge them; both can appear in skill selectors."
**프론트매터**
```yaml
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---
```
Codex 문서의 description 지침이 특히 명확하다: **"when this skill should and should not trigger"** — 배제 조건을 스펙 수준에서 요구한다.
**컨텍스트 예산**
> Skills use "progressive disclosure to manage context efficiently." The initial skills list uses at most **"2% of the model's context window, or 8,000 characters when the context window is unknown"**, though full `SKILL.md` instructions load when a skill is selected.
**→ 중대한 발견**: Codex의 스킬 스캔 경로가 `.agents/skills`와 `$HOME/.agents/skills`다. **이 사용자 머신의 `C:\Users\encep\.agents\skills\`가 정확히 그 경로다.** 즉 현재 설치된 디자인 스킬들은 Codex와 Cursor 양쪽에서 동시에 인식되도록 배치된 것이다.
### 3.2 Codex AGENTS.md
출처: https://agents.md/ (직접 fetch)
**포맷 (원문)**
> **No required fields.** "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide."
> **프론트매터를 쓰지 않는다.**
**중첩과 우선순위 (원문)**
> "The closest AGENTS.md to the edited file wins; **explicit user chat prompts override everything**."
Codex 구현의 3계층 (검색 결과 종합, 다수 소스 일치):
1. `~/.codex/AGENTS.override.md` (최고 우선순위 글로벌 오버라이드)
2. `~/.codex/AGENTS.md`
3. 프로젝트: git root부터 현재 디렉터리까지 걸어가며 각 디렉터리의 `AGENTS.override.md` 또는 `AGENTS.md`
- 병합 순서: root부터 아래로 연결(concatenate), 가까운 파일이 앞의 것을 오버라이드
- **기본 크기 상한 32 KiB에서 중단**
**권장 섹션 (원문)**
> Project overview / Build and test commands / Code style guidelines / Testing instructions / Security considerations / Commit message/PR guidelines / Deployment steps
**성격**
> "Think of AGENTS.md as a **README for agents**: a dedicated, predictable place to provide the context and instructions"
**지원 도구**: OpenAI Codex, Google Jules, Factory, Aider, Zed, VS Code, Devin, GitHub Copilot, Cursor, Gemini CLI 외 15개 이상. 6만 개 이상의 오픈소스 프로젝트에서 사용.
**→ AGENTS.md는 스킬이 아니다.** 항상 로드된다. designpaca 전체를 AGENTS.md에 넣으면 모든 대화에서 토큰을 먹는다. **AGENTS.md에는 포인터만 두고, 본체는 `.agents/skills/designpaca/`에 두는 것이 옳다.**
---
## 4. Cursor — 두 가지 경로
### 4.1 Cursor Agent Skills (신규, 권장)
출처: https://cursor.com/docs/context/skills (직접 fetch)
**로드 위치 4곳**
- 프로젝트: `.agents/skills/` 와 `.cursor/skills/`
- 사용자: `~/.agents/skills/` 와 `~/.cursor/skills/`
> Cursor "walks the skills root recursively and picks up any `SKILL.md` it finds."
**프론트매터**
필수:
- `name` — "Skill identifier. Lowercase letters, numbers, and hyphens only."
- `description` — "Describes what the skill does and when to use it."
선택 (Cursor 확장):
- `paths` — 글롭 패턴으로 스코프 제한
- `disable-model-invocation` — true면 `/skill-name`으로만 호출
- `icon` — "Icon shown on the badge when the skill is used as a Custom Mode"
- `color` — `default, green, cyan, blue, purple, magenta, orange, yellow, red, brand`
- `metadata`
> "Skills in nested project directories are automatically scoped to files inside that directory."
**→ `~/.agents/skills/designpaca/` 하나가 Cursor와 Codex 양쪽에서 인식된다.** 이것이 크로스툴 배포의 정답이다.
### 4.2 Cursor Rules (.mdc) — 레거시 경로
출처: https://cursor.com/docs/rules (직접 fetch)
**파일 위치**
```
.cursor/rules/
react-patterns.mdc
frontend/
components.mdc
```
**프론트매터 필드는 정확히 3개** (문서에 명시된 것 전부):
| Field | Type | 설명 (원문) |
|---|---|---|
| `alwaysApply` | boolean | "Apply to every chat session" |
| `description` | string | "Helps Agent decide relevance; omitting it restricts to manual @-mention only" |
| `globs` | string | "File pattern(s) for auto-attachment; supports comma-separated patterns" |
> "No other frontmatter fields are specified in the documentation."
**4가지 규칙 타입**
| Type | 조건 | 동작 |
|---|---|---|
| Always Apply | `alwaysApply: true` | 모든 채팅 세션에 적용 |
| Apply Intelligently | `description` 있음, `globs` 없음 | 에이전트가 관련성 판단 |
| Apply to Specific Files | `globs` 있음 | "Auto-attached when a matching file is in context" |
| Apply Manually | `description`·`globs` 둘 다 없음 | "@-mention in chat (e.g., `@my-rule`)" |
**공식 베스트 프랙티스 (원문)**
> - "Keep rules under 500 lines"
> - "Split large rules into multiple, composable rules"
> - Reference files via `@filename.ts` rather than copying content
> - Avoid duplicating style guides; use linters instead
**중요한 스코프 제약**
> Rules apply only to Agent (Chat), **not Cursor Tab or Inline Edit (Cmd/Ctrl+K).**
**Cursor의 AGENTS.md 지원**
> "`AGENTS.md` is a simple markdown file for defining agent instructions" without frontmatter. Supports nested placement: "You can place `AGENTS.md` files in any subdirectory" with hierarchical precedence.
---
## 5. Windsurf / Cascade Rules
출처: https://docs.windsurf.com/windsurf/cascade/memories → 307 리다이렉트 → https://docs.devin.ai/desktop/cascade/memories (직접 fetch)
**주의**: Windsurf 문서가 Devin 문서로 리다이렉트된다(Cognition의 Windsurf 인수 이후 통합). 아래는 리다이렉트된 최신 문서 기준이므로, `.windsurf/` 경로는 "legacy"로 표기되어 있다.
### 5.1 파일 위치 3계층
| 범위 | 경로 |
|---|---|
| Global | `~/.codeium/windsurf/memories/global_rules.md` (단일 파일, 항상 활성) |
| Workspace | `.devin/rules/*.md` (권장) 또는 `.windsurf/rules/*.md` (legacy), 그리고 legacy `.windsurfrules` |
| System (Enterprise) | macOS `/Library/Application Support/Devin/rules/`, Linux `/etc/devin/rules/`, Windows `C:\ProgramData\Devin\rules\` |
### 5.2 문자 수 제한 (하드)
> - Global rules: "Limited to **6,000 characters**"
> - Workspace rules: "Limited to **12,000 characters per file**"
**이것이 다른 어떤 포맷보다 강한 제약이다.** designpaca 본문이 12,000자를 넘으면 Windsurf에서는 반드시 분할해야 한다.
### 5.3 활성화 모드 (`trigger:` 필드)
| Mode | Trigger 값 | 동작 (원문) |
|---|---|---|
| Always On | `always_on` | "Full rule content is included in the system prompt on every message" |
| Model Decision | `model_decision` | "Description shown always; full content retrieved when Cascade deems relevant" |
| Glob | `glob` | "Applied when files matching specified patterns are accessed" |
| Manual | `manual` | "Activated only via `@rule-name` mention in input" |
### 5.4 프론트매터 예시 (원문)
```markdown
---
trigger: glob
globs: **/*.test.ts
---
All test files must use `describe`/`it` blocks and mock external API calls.
```
> Global and root-level files don't require frontmatter and remain perpetually active.
**주의**: Windsurf의 `trigger:`는 값이 `always_on`/`model_decision`/`glob`/`manual` 중 하나다. Claude Code SKILL.md의 슬래시 커맨드 이름을 넣는 필드가 아니다. (`graphify`의 `trigger: /graphify`와 혼동 금지 — 서로 다른 스펙의 같은 이름 필드다.)
---
## 6. VS Code / GitHub Copilot Agent Skills
출처: https://code.visualstudio.com/docs/copilot/customization/agent-skills (직접 fetch)
**로드 위치**
- 프로젝트: `.github/skills/`, `.claude/skills/`, `.agents/skills/`
- 개인: `~/.copilot/skills/`, `~/.claude/skills/`, `~/.agents/skills/`
- 추가 경로: `chat.agentSkillsLocations` 설정
**프론트매터**
- `name` (필수): "A unique identifier for the skill. Only lowercase letters, numbers, and hyphens are allowed"
- `description` (필수): "A description of what the skill does **and when to use it**"
- `argument-hint` (선택)
- `user-invocable` (선택)
- `disable-model-invocation` (선택)
- `context` (선택, 실험): `fork`
**custom instructions와의 차이 (원문)**
> skills are "task-specific, loaded on-demand" and work across multiple tools, while custom instructions are "Always applied (or via glob patterns)" and limited to "VS Code and GitHub.com only."
---
## 7. 포맷 비교 통합표
| 항목 | Claude Code SKILL.md | Agent Skills 표준 | Codex AGENTS.md | Cursor .mdc | Windsurf rules |
|---|---|---|---|---|---|
| **파일 위치** | `~/.claude/skills/<n>/SKILL.md`, `.claude/skills/<n>/SKILL.md` | `<n>/SKILL.md` | 리포 루트 + 각 하위 디렉터리 `AGENTS.md` | `.cursor/rules/*.mdc` | `~/.codeium/windsurf/memories/global_rules.md`, `.windsurf/rules/*.md` |
| **프론트매터** | YAML, 22개 필드 | YAML, 6개 필드 | **없음** | YAML, 3개 필드 | YAML, `trigger` + `globs` |
| **필수 필드** | 없음 (`description` 권장) | `name`, `description` | 없음 | 없음 | 없음 |
| **로드 시점** | 온디맨드 (description 매칭 or `/이름`) | 온디맨드 | **항상** | 4모드 (always/글롭/설명매칭/수동) | 4모드 (always_on/glob/model_decision/manual) |
| **크기 제한** | 본문 500줄 권장, 컴팩션 시 5K 토큰 생존 | 본문 500줄 / 5,000토큰 권장 | 32 KiB 병합 상한 | 500줄 권장 | **6,000자(글로벌) / 12,000자(워크스페이스) 하드** |
| **description 상한** | 1,536자(+`when_to_use` 합산), 목록 예산 1% | 1,024자 | N/A | 미명시 | 미명시 |
| **참조 파일** | O (`references/`, `scripts/`, `assets/`) | O | X (별도 AGENTS.md 중첩으로 대체) | `@filename` 참조 | X |
| **스크립트 실행** | O | O | X | X | X |
| **네임스페이스** | 플러그인 `plugin:skill`, 중첩 `dir:skill` | X | 경로 기반 | X | X |
| **심링크** | O (중복 로드 방지 포함) | 구현 의존 | N/A | 미명시 | 미명시 |
---
## 8. designpaca 배포 전략 (권장안)
### 8.1 단일 정본 + 심링크 (Tier 1)
**정본 위치**: `~/.agents/skills/designpaca/`
이 한 곳이 다음 세 도구에서 **변환 없이** 인식된다:
- **Cursor**: `~/.agents/skills/` 를 직접 스캔
- **Codex**: `$HOME/.agents/skills` 를 직접 스캔
- **VS Code Copilot**: `~/.agents/skills/` 를 직접 스캔
**Claude Code용 심링크**:
```bash
# Git Bash / WSL
ln -s ~/.agents/skills/designpaca ~/.claude/skills/designpaca
```
```powershell
# Windows PowerShell (관리자 또는 개발자 모드)
New-Item -ItemType SymbolicLink -Path "$HOME\.claude\skills\designpaca" -Target "$HOME\.agents\skills\designpaca"
```
Claude Code 문서가 이 방식을 명시적으로 지원한다:
> A `<skill-name>` entry ... can be a symlink to a directory elsewhere on disk. Claude Code follows the symlink and reads `SKILL.md` from the target directory.
**프로젝트 스코프**: 리포에 `.agents/skills/designpaca/`를 두면 Cursor·Codex·Copilot이 전부 읽는다. Claude Code용으로 `.claude/skills/designpaca` 심링크를 추가한다.
### 8.2 파일 구조 (권장)
```
designpaca/
├── SKILL.md # 400~480줄. 절차 + 인덱스 + 핵심 게이트
├── references/
│ ├── anti-patterns.md # AI 텔 카탈로그 (무엇/왜/대신)
│ ├── slop-gates.md # 출력 후 예/아니오 게이트 목록
│ ├── typography.md # 폰트 페어링, 스케일, 세리프 규율
│ ├── color.md # 팔레트 규칙, 금지 hex 패밀리, 대비
│ ├── layout.md # 매크로구조 인덱스 + 섹션 리듬
│ ├── motion.md # 이징, 스크롤, reduced-motion
│ ├── copy.md # 카피 규율 + 자가 감사 목록
│ ├── responsive.md # 브레이크포인트, 모바일 붕괴, 실무 버그
│ ├── design-systems.md # 공식 DS 매핑 + 설치 명령 + 문서 링크
│ ├── redesign.md # 리디자인 프로토콜 (감사/보존/레버)
│ └── design-md-template.md # 산출용 design.md 템플릿
├── assets/
│ └── themes/ # 테마별 개별 파일 (인덱스-후-선택)
└── scripts/
└── check_contrast.(js|py) # 대비/팔레트 검증기 (선택)
```
**모든 references 파일은 SKILL.md에서 1단계 링크로만 참조.** 참조 파일끼리 서로 링크하지 않는다.
### 8.3 프론트매터 (확정안)
```yaml
---
name: designpaca
description: <용도 + 트리거 문구 + 배제 조건. 200~350자. 3인칭.>
---
```
**확장 필드를 쓰지 않는 이유**:
1. claude.ai 업로드/패키징 시 하드 에러
2. Cursor·Codex·Copilot이 지원하는 필드 집합이 서로 다름
3. 로컬 커뮤니티 스킬 13개가 이미 같은 결론에 도달
### 8.4 레거시 어댑터 (Tier 2, 필요 시)
Agent Skills를 지원하지 않는 경로용 변환. **자동 생성 스크립트로 만들고 손으로 관리하지 않는다.**
#### (a) → Cursor `.mdc` 규칙
```
.cursor/rules/designpaca.mdc
```
```markdown
---
description: Use when building or reshaping web UI - landing pages, portfolios, marketing sites, product pages, or redesigns - and the visual result matters.
alwaysApply: false
---
<SKILL.md 본문>
<!-- references/ 는 @-참조로 대체 -->
See @.cursor/rules/designpaca-anti-patterns.mdc for the full anti-pattern catalogue.
```
**변환 시 주의점**
1. **`name` 필드를 제거한다.** `.mdc`는 `description`/`globs`/`alwaysApply` 3개만 인식. 다른 필드는 문서화되지 않았다.
2. **`alwaysApply: true`를 쓰지 마라.** Cursor 문서: "Use sparingly, this is your global config, not your per-feature config." 디자인 스킬은 항상 켜져 있으면 안 된다.
3. **`globs`를 쓸지 말지**: `**/*.{tsx,jsx,vue,svelte,astro,html,css}` 로 걸면 파일 컨텍스트 기반 자동 첨부가 되지만, "새 랜딩 만들어줘"처럼 파일이 아직 없는 경우 발동하지 않는다. **디자인 스킬은 `description`만 두는 "Apply Intelligently" 모드가 맞다.**
4. **참조 파일 링크를 `@경로`로 바꾼다.** `.mdc`는 `references/*.md` 상대 경로를 읽지 않는다.
5. **500줄 상한 준수.** 넘으면 여러 `.mdc`로 쪼개고 서로 `@`로 연결.
6. **Tab/Inline Edit에는 적용 안 됨**을 문서에 명시.
#### (b) → Windsurf 규칙
```
.windsurf/rules/designpaca.md (또는 .devin/rules/designpaca.md)
```
```markdown
---
trigger: model_decision
description: Use when building or reshaping web UI ...
---
<SKILL.md 본문 — 12,000자 이내로 압축>
```
**변환 시 주의점**
1. **12,000자 하드 상한.** SKILL.md가 이를 넘으면 반드시 분할. 파일 여러 개로 쪼개고 각각 `trigger: model_decision`.
2. **`trigger: model_decision`을 쓴다.** `always_on`은 6,000자 글로벌 규칙에만.
3. `references/` 개념이 없다. 핵심만 남기고 나머지는 버리거나 별도 규칙 파일로.
4. `name` 필드 없음.
#### (c) → AGENTS.md
**전체를 넣지 마라.** AGENTS.md는 항상 로드되므로 디자인 스킬 본문을 넣으면 모든 대화에서 비용이 든다. 포인터만 넣는다:
```markdown
## Design work
When building or changing UI in this repo, load the `designpaca` skill
(`.agents/skills/designpaca/SKILL.md`) before writing any markup or styles.
The project's locked design system lives at `design.md` at the repo root;
it overrides the skill's defaults.
```
**변환 시 주의점**
1. 프론트매터가 없다. YAML 블록을 넣으면 그냥 본문 텍스트로 읽힌다.
2. 32 KiB 병합 상한이 있으므로 짧게.
3. 중첩 시 가까운 파일이 이긴다. 모노레포에서 패키지별로 다른 디자인 지시를 줄 수 있다.
### 8.5 변환 시 절대 하면 안 되는 것
| 실수 | 결과 |
|---|---|
| SKILL.md에 `trigger: /designpaca` 넣기 | claude.ai 업로드/패키징 하드 에러. Windsurf `trigger`와 의미 충돌 |
| `.mdc`에 `name:` 남기기 | 문서화되지 않은 필드. 무시되거나 파싱 실패 |
| `.mdc`에서 `references/x.md` 상대 링크 유지 | Cursor가 읽지 못함. `@` 참조로 바꿔야 함 |
| Windsurf 규칙에 `alwaysApply` 넣기 | Cursor 필드다. Windsurf는 `trigger`를 쓴다 |
| AGENTS.md에 YAML 프론트매터 넣기 | 본문으로 렌더링됨 |
| SKILL.md `name`을 디렉터리명과 다르게 | 스펙 위반 ("Must match the parent directory name"). 개인/프로젝트 스킬에서는 어차피 디렉터리명이 커맨드가 되므로 혼란만 유발 |
| description에 XML 태그 | Anthropic 스펙 위반 |
| description 1,024자 초과 | Agent Skills 스펙 위반 (Claude Code는 1,536까지 받지만 표준은 1,024) |
| 참조 파일이 다른 참조 파일을 링크 | 부분 읽기(`head -100`)로 정보 유실 |
| 참조 파일 100줄 초과인데 목차 없음 | 부분 읽기 시 전체 범위를 모름 |
### 8.6 검증 체크리스트
배포 전 확인:
- [ ] `name`이 소문자+숫자+하이픈만, 64자 이내, 연속 하이픈 없음, 디렉터리명과 일치
- [ ] `description`이 1,024자 이내, 3인칭, 용도+트리거+배제 3요소
- [ ] 프론트매터에 표준 6필드 외 필드 없음
- [ ] SKILL.md 본문 500줄 이내
- [ ] 가장 중요한 규칙이 앞 100줄 안에 있음
- [ ] 모든 참조 파일이 SKILL.md에서 1단계로 링크됨
- [ ] 참조 파일 중 100줄 넘는 것에 목차 있음
- [ ] 파일 경로에 백슬래시 없음 (전부 `/`)
- [ ] `skills-ref validate ./designpaca` 통과
- [ ] Cursor `.mdc` 변환본이 500줄 이내
- [ ] Windsurf 변환본이 12,000자 이내
- [ ] Claude Code에서 `/doctor`로 스킬 목록 예산 확인
---
## 9. 확인 못한 것
- **Windsurf 공식 문서 원본**: `docs.windsurf.com`이 `docs.devin.ai`로 리다이렉트되어, 리다이렉트된 문서 기준으로 정리했다. `.windsurfrules` 단일 파일 레거시 포맷의 정확한 상한과 파싱 규칙은 리다이렉트 문서에 "legacy"로만 표기되어 있고 상세 스펙은 확인하지 못했다.
- **Cursor `.mdc`의 미문서화 필드**: 커뮤니티 문서들이 `alwaysApply`/`description`/`globs` 외 필드를 언급하기도 하지만, 공식 문서는 "No other frontmatter fields are specified"라고 한다. 미문서화 필드는 사용하지 않는 것이 안전하다.
- **`skills-ref` CLI의 실제 검증 항목 전체**: 저장소 URL만 확인했고 실행해보지 않았다.
- **Cursor Skills와 `.mdc` Rules가 동시에 있을 때의 우선순위**: 공식 문서에 명시되어 있지 않다.

190
research/skills/04-sources.md Normal file
View file

@ -0,0 +1,190 @@
# 04. 조사 소스 목록
작성일: 2026-08-20
표기 규칙
- **[직접]** = WebFetch로 본문을 직접 가져와 읽음. 인용문은 이 소스에서만 가져왔다.
- **[검색]** = WebSearch 결과 목록에서 확인. 제목과 요약만 봤고 본문은 읽지 않았다.
- **[로컬]** = 파일시스템에서 직접 읽음.
- **[스킬]** = Skill 도구로 로드해 본문을 직접 읽음.
---
## A. 공식 스펙 문서 (1~12)
| # | URL | 상태 | 설명 |
|---|---|---|---|
| 1 | https://agentskills.io/specification | [직접] | Agent Skills 오픈 표준 완전 스펙. 프론트매터 6필드, name 정규식, description 1024자 상한, progressive disclosure 3계층, 파일 참조 1단계 규칙 |
| 2 | https://agentskills.io/ | [직접] | 표준 개요와 지원 클라이언트 40개 이상 목록(Cursor, Codex, Gemini CLI, Copilot, Roo, Goose, Amp 등) |
| 3 | https://code.claude.com/docs/en/skills | [직접] | Claude Code 스킬 문서 전문. 프론트매터 22개 필드 표, 설치 위치·우선순위, 심링크, 컨텍스트 수명(5,000토큰 재부착), 스킬 목록 예산(컨텍스트 1%), 트러블슈팅 |
| 4 | https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices | [직접] | Anthropic 스킬 작성 베스트 프랙티스 전문. 3인칭 description 경고, degrees of freedom, progressive disclosure 패턴 3종, 워크플로/피드백 루프, 안티패턴, 최종 체크리스트 |
| 5 | https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview | [검색] | 스킬 개념 개요와 아키텍처 |
| 6 | https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills | [검색] | Anthropic 엔지니어링 블로그. progressive disclosure를 핵심 설계 원칙으로 소개 |
| 7 | https://cursor.com/docs/rules | [직접] | Cursor `.mdc` 규칙 공식 스펙. 프론트매터 3필드(`alwaysApply`/`description`/`globs`), 4가지 규칙 타입, 500줄 상한, Tab/Inline Edit 미적용 |
| 8 | https://cursor.com/docs/context/skills | [직접] | Cursor Agent Skills 지원. `.agents/skills`·`.cursor/skills` 4경로, 프론트매터(name/description 필수 + paths/icon/color/metadata) |
| 9 | https://agents.md/ | [직접] | AGENTS.md 오픈 표준. 프론트매터 없음, 중첩 시 가까운 파일 우선, 권장 섹션, 6만+ 프로젝트 채택 |
| 10 | https://learn.chatgpt.com/docs/build-skills | [직접] | Codex/ChatGPT 스킬 문서. 스캔 경로 4계층(`.agents/skills`, `$HOME/.agents/skills`, `/etc/codex/skills`, 시스템), 목록 예산 2%/8000자 |
| 11 | https://code.visualstudio.com/docs/copilot/customization/agent-skills | [직접] | VS Code/Copilot 스킬 지원. `.github/skills`·`.claude/skills`·`.agents/skills` 경로, custom instructions와의 차이 |
| 12 | https://docs.devin.ai/desktop/cascade/memories | [직접] | Windsurf/Cascade 규칙 스펙(docs.windsurf.com에서 307 리다이렉트). 6,000자/12,000자 상한, `trigger:` 4모드(always_on/model_decision/glob/manual) |
## B. 리다이렉트 원본·부속 (13~16)
| # | URL | 상태 | 설명 |
|---|---|---|---|
| 13 | https://docs.windsurf.com/windsurf/cascade/memories | [직접] | 307 리다이렉트 확인. Windsurf 문서가 Devin 문서로 통합됨 |
| 14 | https://developers.openai.com/codex/skills | [직접] | 308 리다이렉트 확인 → learn.chatgpt.com/docs/build-skills |
| 15 | https://code.claude.com/docs/en/llms.txt | [검색] | Claude Code 문서 인덱스 |
| 16 | https://github.com/agentskills/agentskills | [검색] | Agent Skills 표준 저장소. `skills-ref validate` CLI 포함 |
## C. Anthropic 공식 스킬 (17~24)
| # | URL / 경로 | 상태 | 설명 |
|---|---|---|---|
| 17 | `~/.claude/plugins/marketplaces/anthropic-agent-skills/skills/frontend-design/SKILL.md` | [로컬] | 공식 frontend-design 스킬. 약 40줄 산문. "AI 3대 기본값" 명명, "Spend your boldness in one place", 2패스 프로세스, 카피 지침 |
| 18 | `~/.claude/plugins/marketplaces/anthropic-agent-skills/skills/skill-creator/SKILL.md` | [로컬] | 공식 skill-creator 486줄. description 최적화 루프, eval 워크플로, "explain the why in lieu of musty MUSTs" |
| 19 | (빌트인) `artifact-design` | [스킬] | Artifact 디자인 가이드. 트리트먼트 보정, 다크모드 3상태, 우선순위 체인, `<title>` 명명 규칙 |
| 20 | (빌트인) `dataviz` + `.../bundled-skills/.../dataviz/references/*` | [스킬]+[로컬] | 차트 스킬. 절차 7단계, 색상은 마지막, 검증 스크립트 번들, references 7개 분리 구조 |
| 21 | https://github.com/anthropics/skills | [검색] | Anthropic 공식 스킬 저장소 |
| 22 | https://github.com/anthropics/skills/tree/main/skills/skill-creator | [검색] | skill-creator 소스 |
| 23 | https://claude.com/blog/skills-explained | [검색] | Anthropic 스킬 아키텍처·베스트 프랙티스 가이드 블로그 |
| 24 | https://anthropic.skilljar.com/introduction-to-agent-skills | [검색] | Anthropic 공식 Agent Skills 입문 코스 |
## D. Hallmark (anti-slop 디자인 스킬, 가장 참고 가치 높음) (25~30)
| # | URL | 상태 | 설명 |
|---|---|---|---|
| 25 | https://github.com/Nutlope/hallmark | [직접] | Together AI의 anti-AI-slop 디자인 스킬. 4개 verb, 21개 테마, 58 게이트. 파일 구조와 설치 경로(Claude Code/Cursor/Codex) 확인 |
| 26 | https://raw.githubusercontent.com/nikolanaidenko-eng/antislop/main/skills/hallmark/SKILL.md | [직접] | Hallmark SKILL.md 전문(포크 미러). Six Universal Disciplines, 인덱스-후-선택 로딩 규율, `.hallmark/log.json` 프로젝트 메모리, CSS 스탬프 |
| 27 | https://raw.githubusercontent.com/nikolanaidenko-eng/antislop/main/skills/hallmark/references/slop-test.md | [직접] | 58개 슬롭 테스트 게이트 전문 + 6축 사전 자기 채점(Philosophy/Hierarchy/Execution/Specificity/Restraint/Variety) |
| 28 | https://raw.githubusercontent.com/nikolanaidenko-eng/antislop/main/skills/hallmark/references/anti-patterns.md | [직접] | 명명된 AI 텔 카탈로그. Critical/Major/Microinteraction/Minor 4등급, 각 항목이 "무엇/왜 실패하는가/고치는 법" 3단 |
| 29 | https://github.com/Nutlope/hallmark/blob/main/SKILL.md | [검색] | 원본 저장소의 SKILL.md 경로(루트가 아닌 `skills/hallmark/`에 있음) |
| 30 | https://github.com/adeoyewole028/hallmark-design-skills | [검색] | Hallmark 포크 |
## E. Superdesign (design.md 산출 패턴) (31~35)
| # | URL | 상태 | 설명 |
|---|---|---|---|
| 31 | https://github.com/superdesigndev/superdesign-skill | [직접] | Claude Code/Cursor/Codex 공용 디자인 스킬. `.claude-plugin`/`.cursor-plugin`/`.codex-plugin` 3중 배포 구조, `.superdesign/design-system.md` 필수화 |
| 32 | https://raw.githubusercontent.com/superdesigndev/superdesign-skill/main/DESIGN.md | [직접] | "design.md는 디자인계의 AGENTS.md" 선언문. 왜 영속적 디자인 시스템 파일이 필요한지 가장 명료한 설명 |
| 33 | https://raw.githubusercontent.com/superdesigndev/superdesign-skill/main/skills/superdesign/SKILL.md | [직접] | Superdesign 스킬 본문. 환경 확인 우선, 리포 자동 분석 6파일 생성, `.superdesign/resume.json` 웜 리줌 |
| 34 | https://github.com/superdesigndev/superdesign | [검색] | Superdesign 본체 (IDE 내 디자인 에이전트) |
| 35 | https://github.com/jonthebeef/superdesign-mcp-claude-code | [검색] | Superdesign의 Claude Code MCP 통합 |
## F. 유출 시스템 프롬프트 (36~44)
| # | URL | 상태 | 설명 |
|---|---|---|---|
| 36 | https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools | [직접] | 33개 도구의 시스템 프롬프트 모음. 디렉터리 목록 확인(v0, Lovable, Same.dev, Cursor, Devin, Windsurf, Replit, Bolt, Cline, Codex CLI, Gemini CLI, RooCode 등) |
| 37 | `.../v0 Prompts and Tools/Prompt.txt` (raw) | [직접] | v0 디자인 규칙 원문. "exactly 3-5 colors total", "maximum 2 font families", "NEVER use purple or violet prominently", "Avoid gradients entirely", "NEVER generate abstract shapes like gradient circles, blurry squares, or decorative blobs", 디자인 토큰 강제 |
| 38 | `.../Lovable/Agent Prompt.txt` (raw) | [직접] | Lovable 디자인 규칙 원문. "The design system is everything", "USE SEMANTIC TOKENS FOR COLORS... DO NOT use direct colors like text-white", "NEVER use overrides. Make sure to not hold back on design" |
| 39 | `.../Same.dev/Prompt.txt` (raw) | [직접] | Same.dev 규칙 원문. "NEVER stay with default shadcn/ui components", "NEVER use emojis", "Avoid using purple, indigo, or blue colors unless specified", 클로닝 윤리 가드레일 |
| 40 | `.../Open Source prompts/Bolt/Prompt.txt` (raw) | [직접] | Bolt 프롬프트. **디자인 전용 섹션이 없음을 확인.** 코드 품질·모듈 분할 중심. 디자인 지시는 사실상 부재 |
| 41 | https://github.com/elder-plinius/CL4R1T4S | [검색] | 유출 시스템 프롬프트 대형 아카이브 (ChatGPT, Claude, Gemini, Grok, Cursor, Lovable, Replit) |
| 42 | https://github.com/YeeKal/leaked-system-prompts | [검색] | 유출 프롬프트 모음 (v0, Lovable, Cursor, Manus 포함) |
| 43 | https://simonwillison.net/2024/Nov/25/leaked-system-prompts-from-vercel-v0/ | [검색] | Simon Willison의 v0 유출 분석. Vercel CTO Malte Ubl의 "프롬프트만으론 가치 없다" 코멘트 |
| 44 | https://quasa.io/media/leaked-system-prompts-of-ai-vibe-coding-tools-a-deep-dive-into-cursor-bolt-lovable-and-manus | [검색] | Cursor/Bolt/Lovable/Manus 프롬프트 비교 분석 |
## G. 커뮤니티 디자인 스킬 목록·큐레이션 (45~54)
| # | URL | 상태 | 설명 |
|---|---|---|---|
| 45 | https://github.com/travisvn/awesome-claude-skills | [직접] | Claude Skills 큐레이션. 디자인 관련: frontend-design, web-artifacts-builder, canvas-design, algorithmic-art, frontend-slides, web-asset-generator, shadcn/ui |
| 46 | https://novitckii.com/resources/claude-design-skills/ | [직접] | 42개 디자인 스킬 전수 목록 + GitHub 저장소 URL. impeccable, animate, design-motion-principles, designer-skills, ai-design-skills 시리즈 등 |
| 47 | https://github.com/Koomook/claude-frontend-skills | [직접] | `distinctive-frontend` 스킬. 4축(타이포/컬러·테마/모션/배경) 접근, 극단적 웨이트 대비(100-200 vs 800-900), 문화적 미학 기반 팔레트 |
| 48 | https://github.com/jiji262/claude-design-skill | [직접] | Claude.ai 내부 Design 시스템 프롬프트를 스킬로 이식. 6단계 워크플로, Core Asset Protocol, Design Direction Advisor(3방향 제시), 스케일 하한(슬라이드 24px+, 히트타깃 44px+) |
| 49 | https://github.com/ComposioHQ/awesome-claude-skills | [검색] | 또 다른 Claude Skills 큐레이션 |
| 50 | https://github.com/wilwaldon/Claude-Code-Frontend-Design-Toolkit | [검색] | Claude Code 프론트엔드 디자인 개선 도구 모음(스킬·플러그인·MCP·CLAUDE.md 트릭) |
| 51 | https://pasqualepillitteri.it/en/news/576/claude-code-skills-design-uiux-guide | [검색] | UI/UX 디자인용 Claude Code 스킬 20선 |
| 52 | https://www.firecrawl.dev/blog/best-claude-code-skills | [검색] | 2026년 추천 Claude Code 스킬 |
| 53 | https://skills.rest/skill/anti-slop-design | [검색] | anti-slop-design 스킬 (비제네릭 웹 인터페이스) |
| 54 | https://ui.shadcn.com/docs/skills | [검색] | shadcn/ui 공식 스킬. 컴포넌트 컨텍스트와 디자인 패턴 강제 |
## H. AI 슬롭 분석 (55~61)
| # | URL | 상태 | 설명 |
|---|---|---|---|
| 55 | https://dev.to/rams901/hallmark-stop-ai-generated-ui-slop-in-one-command-in-2026-3p9n | [검색] | Hallmark 소개. "Pick a real direction (Swiss/editorial, brutalist, industrial-mono, organic, clean-product) and lock its tokens in a DESIGN.md at the project root" |
| 56 | https://www.925studios.co/blog/ai-slop-web-design-guide | [검색] | AI 슬롭 웹디자인 식별·수정 가이드 |
| 57 | https://vibecodekit.dev/ai-slop-design | [검색] | AI UI가 제네릭해지는 원인 분석. "LLMs predict the next token based on probability distributions... 'safe' design patterns that appear frequently in web training data get sampled at high probability" |
| 58 | https://saascity.io/blog/stunning-frontend-designs-vibe-coding-avoid-ai-slop | [검색] | 바이브 코딩에서 슬롭 회피 |
| 59 | https://www.mindstudio.ai/blog/claude-design-avoid-ai-slop-design-system | [검색] | Claude Design에서 디자인 시스템 접근으로 슬롭 회피 |
| 60 | https://ui-ux-pro-max-skill.com/blog/avoiding-ai-slop/ | 403 | 슬롭 회피 프롬프트 기법 7가지. **접근 실패(403). 내용 확인 못함** |
| 61 | https://www.coddykit.com/pages/blog-detail?id=512918 | [검색] | Hallmark 소개 기사 (4,600+ 스타 시점) |
## I. 스킬 작성 방법론 (62~69)
| # | URL | 상태 | 설명 |
|---|---|---|---|
| 62 | https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-skills/SKILL.md | [직접] | obra/superpowers 스킬 작성 규칙. "NO SKILL WITHOUT A FAILING TEST FIRST", description은 "Use when..." 시작 + 트리거 조건만, RED-GREEN-REFACTOR, 토큰 효율 목표치 |
| 63 | https://github.com/obra/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md | [검색] | superpowers가 정리한 Anthropic 베스트 프랙티스 요약 |
| 64 | https://generativeprogrammer.com/p/skill-authoring-patterns-from-anthropics | [검색] | Anthropic 베스트 프랙티스에서 도출한 작성 패턴 분석 |
| 65 | https://agentman.ai/blog/build-your-first-agent-skill-skillmd-anatomy | [검색] | SKILL.md 해부 가이드 |
| 66 | https://www.newsletter.swirlai.com/p/agent-skills-progressive-disclosure | [검색] | progressive disclosure를 시스템 설계 패턴으로 분석 |
| 67 | https://strapi.io/blog/what-are-agent-skills-and-how-to-use-them | [검색] | Agent Skills 개요. 3계층 로딩 토큰 수치(~30-50 토큰/스킬) |
| 68 | https://arxiv.org/html/2602.12430v3 | [검색] | 논문: Agent Skills for LLMs — 아키텍처, 획득, 보안 |
| 69 | https://www.deeplearning.ai/courses/agent-skills-with-anthropic | [검색] | DeepLearning.AI Agent Skills 코스 |
## J. 포맷 스펙 보조 자료 (70~79)
| # | URL | 상태 | 설명 |
|---|---|---|---|
| 70 | https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/cursor-rules-reference.md | [검색] | Cursor `.mdc` 레퍼런스와 예제 모음 |
| 71 | https://techsy.io/en/blog/cursor-rules-guide | [검색] | `.mdc` 프론트매터·globs·alwaysApply 해설 |
| 72 | https://www.vibecodingacademy.ai/blog/cursor-rules-complete-guide | [검색] | Cursor Rules 완전 가이드 + 15개 템플릿 |
| 73 | https://dev.to/vibestackdev/why-your-cursor-rules-are-being-silently-ignored-and-how-to-fix-it-4123 | [검색] | Cursor 규칙이 조용히 무시되는 원인과 해결 |
| 74 | https://medium.com/@ror.venkat/mastering-mdc-files-in-cursor-best-practices-f535e670f651 | [검색] | `.mdc` 베스트 프랙티스 |
| 75 | https://www.morphllm.com/agents-md-guide | [검색] | AGENTS.md vs CLAUDE.md vs .cursorrules 비교 |
| 76 | https://codex.danielvaughan.com/2026/03/26/agents-md-advanced-patterns/ | [검색] | AGENTS.md 중첩 계층·오버라이드 파일·폴백 패턴 |
| 77 | https://ralphable.com/blog/agents-md-scope-precedence-codex-2026-troubleshooting-guide | [검색] | Codex AGENTS.md 스코프·우선순위 3계층, 32 KiB 상한 |
| 78 | https://www.tembo.io/blog/agents-md | [검색] | AGENTS.md 작성법 |
| 79 | https://www.augmentcode.com/guides/how-to-build-agents-md | [검색] | AGENTS.md 구축 가이드 |
| 80 | https://blakecrosley.com/blog/agents-md-patterns | [검색] | 실제로 에이전트 행동을 바꾸는 AGENTS.md 패턴 |
| 81 | https://eastondev.com/blog/en/posts/ai/20260626-codex-agents-md-project-rules/ | [검색] | Codex용 AGENTS.md 규칙·로딩·템플릿 |
| 82 | https://prpm.dev/blog/agents-md-deep-dive | [검색] | AGENTS.md 오픈 표준 심층 |
## K. 로컬 파일 (조사 대상 원본) (83~99)
| # | 경로 | 상태 | 설명 |
|---|---|---|---|
| 83 | `C:\Users\encep\.agents\skills\design-taste-frontend\SKILL.md` | [로컬] | 88KB/1,206줄. 다이얼 3축, 브리프 추론, AI Tells 4계층, Pre-Flight 60항목, 디자인시스템 매핑 + 부록 3종 |
| 84 | `C:\Users\encep\.agents\skills\design-taste-frontend-v1\SKILL.md` | [로컬] | 226줄 v1 원형. 다이얼 최초 도입, Motion-Engine Bento 5-카드 아키타입 |
| 85 | `C:\Users\encep\.agents\skills\high-end-visual-design\SKILL.md` | [로컬] | Double-Bezel(Doppelrand), Button-in-Button, Variance Engine, 성능 가드레일 |
| 86 | `C:\Users\encep\.agents\skills\minimalist-ui\SKILL.md` | [로컬] | 웜 모노크롬 에디토리얼. hex 단위 팔레트, 절대 금지 9항목 |
| 87 | `C:\Users\encep\.agents\skills\industrial-brutalist-ui\SKILL.md` | [로컬] | 스위스 인쇄 × 군용 터미널. 모드/기판 단일 선택 강제, `gap:1px` 그리드 기법 |
| 88 | `C:\Users\encep\.agents\skills\gpt-taste\SKILL.md` | [로컬] | Python RNG 시뮬레이션, AIDA 구조, 2줄 헤드라인 철칙, `grid-flow-dense`, `<design_plan>` 게이트 |
| 89 | `C:\Users\encep\.agents\skills\imagegen-frontend-web\SKILL.md` | [로컬] | 987줄. HARD OUTPUT RULE 선두 배치, 조합 변형 엔진 13축, 서사 스파인, Second-Read Moment |
| 90 | `C:\Users\encep\.agents\skills\imagegen-frontend-mobile\SKILL.md` | [로컬] | 1,465줄. 모바일 AI 텔, "not always simple, always clean", 27문항 품질 체크 |
| 91 | `C:\Users\encep\.agents\skills\image-to-code\SKILL.md` | [로컬] | 1,228줄. 이미지 우선 워크플로, 다이얼 9축, 추출 규칙 5종, anti-slop 5분류 |
| 92 | `C:\Users\encep\.agents\skills\redesign-existing-projects\SKILL.md` | [로컬] | "문제→해법" 페어 100+개, "AI가 빼먹는 것" 섹션, 위험 대비 효과 순 수정 우선순위 |
| 93 | `C:\Users\encep\.agents\skills\stitch-design-taste\SKILL.md` + `DESIGN.md` | [로컬] | 메타 스킬. DESIGN.md 생성기. 출력 템플릿과 Best Practices/Pitfalls |
| 94 | `C:\Users\encep\.agents\skills\brandkit\SKILL.md` | [로컬] | 798줄. 로고 컨셉 5방법, 시각 모드 8종, 레퍼런스 사용 윤리 |
| 95 | `C:\Users\encep\.agents\skills\full-output-enforcement\SKILL.md` | [로컬] | 60줄. 잘림 방지. 금지 문자열 목록 + `[PAUSED — X of Y]` 중단 포맷 |
| 96 | `C:\Users\encep\.claude\skills\graphify\SKILL.md` | [로컬] | 1,242줄. `trigger:` 비표준 필드 사용 사례. Honesty Rules 섹션 |
| 97 | `C:\Users\encep\.claude\skills\codex-image\SKILL.md` | [로컬] | 한국어 description + 리터럴 발화 나열 + 배제 조건 조합의 모범 |
| 98 | `C:\Users\encep\.codex-litellm\skills\refactor-governance\SKILL.md` | [로컬] | description에 "NOT a trigger" 배제 조건을 넣은 사례 |
| 99 | `...\bundled-skills\2.1.235\...\dataviz\references\anti-patterns.md` 외 6개 | [로컬] | dataviz 참조 파일. `❌ / Why / ✅` 3단 구조, 실제 사례 인용 |
---
## 소스 통계
- 총 URL/경로: **99개**
- 본문 직접 확인(WebFetch): **22개**
- 로컬 파일 직접 읽음: **17개**
- Skill 도구로 본문 확인: **2개** (artifact-design, dataviz)
- 검색 결과 목록에서만 확인: **57개**
- 접근 실패: **1개** (#60, HTTP 403)
## 인용문의 출처 신뢰도
이 리서치의 모든 원문 인용은 위 목록에서 **[직접] / [로컬] / [스킬]** 표기된 41개 소스에서만 가져왔다. [검색] 표기 소스는 존재 확인과 맥락 파악에만 사용했고, 인용하지 않았다.
## 조사하려 했으나 실패하거나 확인 못한 것
1. **`artifact-design` / `dataviz` / `artifact-diagramming` / `artifact-capabilities`의 SKILL.md 원본 파일** — Claude Code 바이너리 임베드. 파일시스템 전수 검색에서 발견 못함. 단 Skill 도구 호출로 본문은 읽었다.
2. **Windsurf 공식 문서 원본** — `docs.windsurf.com`이 `docs.devin.ai`로 리다이렉트. 리다이렉트된 문서 기준으로 정리했다. `.windsurfrules` 단일 파일 레거시 포맷의 상세 스펙은 확인 못함.
3. **#60 ui-ux-pro-max-skill.com "7 prompt techniques"** — HTTP 403.
4. **Hallmark의 `references/macrostructures.md`, `component-cookbook.md`, `themes/*.md` 개별 파일** — 존재는 SKILL.md에서 확인했으나 파일 자체는 fetch하지 않았다. 21개 매크로구조와 20개 테마의 실제 이름 목록은 확인 못함(SKILL.md에 일부만 언급: Bento Grid, Long Document, Marquee Hero, Stat-Led, Workbench, Conversational FAQ, Manifesto, Photographic, Quote-Led, Specimen).
5. **`skills-ref` CLI 실제 검증 항목** — 저장소 URL만 확인, 실행 안 함.
6. **Cursor Skills와 `.mdc` Rules 동시 존재 시 우선순위** — 공식 문서에 명시 없음.
7. **Bolt.new의 디자인 관련 지시** — 프롬프트를 직접 읽었으나 디자인 전용 섹션이 없음을 확인. 추가 파일이 있을 수 있으나 `Prompt.txt` 하나만 확인했다.

722
research/skills/05-recommendations.md Normal file
View file

@ -0,0 +1,722 @@
# 05. designpaca 설계 원칙 10가지
작성일: 2026-08-20
근거: 01(로컬 스킬 해부), 02(기법 카탈로그), 03(포맷 스펙)에서 도출.
각 원칙은 **주장 / 근거 / designpaca에서의 구체 형태 / 반대 의견과 그에 대한 답** 4부로 쓴다.
---
## 원칙 1. SKILL.md 본문은 절차와 인덱스만 담는다. 지식은 references/로 뺀다.
### 주장
SKILL.md 본문은 **400~480줄, 5,000토큰 이내**로 유지한다. 미학 지식(anti-pattern 카탈로그, 타이포그래피, 컬러, 레이아웃, 모션, 반응형, 디자인 시스템 매핑)은 전부 `references/*.md`로 분리한다. 본문에는 (a) 절차, (b) 참조 파일 인덱스 표, (c) 필수 게이트만 남긴다.
### 근거
세 가지가 겹친다.
**첫째, 공식 권고 수치가 명확하다.**
> "Keep SKILL.md body under 500 lines for optimal performance"
> "**Instructions** (< 5000 tokens recommended)"
> — Anthropic best practices / Agent Skills spec
**둘째, 컨텍스트 수명이 하드 제약이다.**
> "the rendered `SKILL.md` content enters the conversation as a single message and **stays there for the rest of the session**"
> "Claude Code re-attaches the most recent invocation of each skill after the summary, **keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens.**"
> — Claude Code skills docs
design-taste-frontend는 1,206줄(약 22K 토큰)이다. 컴팩션 한 번이면 앞 5K만 남는다. **§9 AI Tells도 §14 Pre-Flight도 사라진다.** 그리고 25K 공유 예산을 혼자 다 먹어서 다른 스킬을 밀어낸다.
**셋째, 참조 파일은 읽기 전까지 0토큰이다.**
> "**No context penalty for large files:** Reference files, data, or documentation don't consume context tokens until actually read"
> — Anthropic best practices
**대조군이 있다.** dataviz는 SKILL.md 약 80줄 + `references/` 7개 + `scripts/` 2개다. 같은 밀도의 지식을 1/10 토큰으로 상주시킨다. Hallmark도 SKILL.md는 절차만 담고 지식은 전부 참조 파일이다.
### designpaca에서의 구체 형태
```
designpaca/
├── SKILL.md # 400~480줄
├── references/
│ ├── anti-patterns.md # AI 텔 카탈로그 (무엇/왜/대신)
│ ├── slop-gates.md # 출력 후 예/아니오 게이트
│ ├── typography.md
│ ├── color.md
│ ├── layout.md # 매크로구조 인덱스
│ ├── motion.md
│ ├── copy.md
│ ├── responsive.md # 실무 렌더링 버그 포함
│ ├── design-systems.md # 공식 DS 매핑 + 설치 명령
│ ├── redesign.md
│ └── design-md-template.md
├── assets/themes/ # 테마별 개별 파일
└── scripts/ # 선택
```
본문의 인덱스는 dataviz 형식을 따른다:
```markdown
| File | What it answers | When to load |
|------|-----------------|--------------|
| `references/anti-patterns.md` | 무엇이 AI처럼 보이는가 | 항상, 출력 직전 |
| `references/typography.md` | 폰트 페어링·스케일 | 타입 결정 시 |
| `references/design-systems.md` | 공식 DS를 써야 하나 | 브리프가 대시보드/엔터프라이즈일 때만 |
```
**규칙**: 참조 파일은 SKILL.md에서 1단계로만 링크. 참조 파일끼리 링크 금지. 100줄 넘는 참조 파일에는 목차.
### 반론과 답
**반론**: "참조 파일을 안 읽고 넘어가면 어쩌나."
**답**: 그래서 "언제 로드하는가"를 인덱스에 명시하고, 절차 단계에 "지금 X를 읽어라"를 박아넣는다. Hallmark가 그렇게 한다. 그리고 안 읽고 넘어가는 실패보다 **컴팩션으로 통째로 사라지는 실패가 훨씬 크다.**
---
## 원칙 2. 가장 중요한 규칙 3~5개를 파일 최상단에 별도 블록으로 둔다.
### 주장
프론트매터 바로 다음, 제목·역할 부여·개요보다 **먼저** 핵심 규칙 블록을 놓는다. 그 블록은 "이 규칙은 모델의 기본 동작을 이긴다"고 명시한다.
### 근거
**컴팩션 생존선이 앞 5,000토큰이다.** 물리적으로 앞에 있어야 살아남는다.
그리고 긴 문서에서 후반부 지시 준수율이 떨어진다는 것은 실무 관찰로 확인된다. design-taste-frontend가 §4.7에서 스스로 인정한다:
> **EYEBROW RESTRAINT (mandatory, the #1 violated rule in production tests).**
가장 많이 위반되는 규칙이 문서 중반에 있다.
imagegen-frontend-web은 반대로 했다. 파일 6번째 줄:
> # HARD OUTPUT RULE — READ FIRST
> **Generate one separate horizontal image PER section. Always. No exceptions.**
> ...
> **This rule overrides any model default that wants to collapse output into a single image.**
마지막 문장이 중요하다. **규칙이 모델 기본값과 싸운다는 사실을 명시**한다.
### designpaca에서의 구체 형태
프론트매터 직후:
```markdown
# READ FIRST — 이 5가지는 다른 모든 판단보다 먼저다
1. **프로젝트에 `design.md`가 있으면 그것이 최상위다.** 이 스킬의 모든 기본값을 덮어쓴다.
없으면 기존 코드에서 토큰(폰트/팔레트/스페이싱/반경)을 먼저 읽는다.
2. **코드를 쓰기 전에 Design Read 한 줄과 선택(구조·테마·다이얼)을 평문으로 출력한다.**
선언 없이 시작한 출력은 실패로 간주한다.
3. **트리트먼트를 먼저 정한다.** 메모·플랜·데모는 유틸리티, 랜딩·포트폴리오는 에디토리얼.
확신이 안 서면 유틸리티 쪽. 과잉 디자인이 과소 디자인보다 나쁘다.
4. **색·폰트는 반드시 명명 토큰을 경유한다.** 인라인 hex, 인라인 font-family, `text-white`
같은 직접 색 클래스는 금지. 토큰에 없으면 토큰을 먼저 추가한다.
5. **없는 것을 만들어내지 않는다.** 지표, 후기, 로고, 스크린샷. 없으면 라벨 붙은
플레이스홀더를 두고 사용자에게 요구한다. 숫자 모양의 구멍은 정직하고, 지어낸 숫자는 슬롭이다.
이 5가지는 모델의 기본 동작과 충돌한다. 충돌할 때 이 규칙이 이긴다.
```
### 반론과 답
**반론**: "역할 부여가 먼저 와야 톤이 잡히지 않나."
**답**: 역할 부여는 그 다음 20줄에 놓아도 효과가 유지된다. 규칙은 위치에 민감하지만 페르소나는 덜하다. 그리고 5개 규칙 자체가 이미 톤을 전달한다.
---
## 원칙 3. description은 3부 구성으로 200~350자. 확장 프론트매터는 쓰지 않는다.
### 주장
프론트매터는 `name`과 `description` **둘뿐**. description은 (1) 무엇을 하는가, (2) 어떤 요청에서 발동하는가(한국어·영어 리터럴 문구 포함), (3) 어떤 요청에서는 발동하지 않는가로 구성하고 **200~350자**를 지킨다.
### 근거
**확장 필드는 크로스툴 배포를 깬다.**
> "**If you include any field the spec doesn't allow, packaging or upload fails with a hard error** instead of ignoring the field: `Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name`"
> — Claude Code skills docs
로컬 커뮤니티 디자인 스킬 13개 전부가 이미 `name`+`description`만 쓴다. 이건 우연이 아니라 수렴이다.
**길이 상한은 두 겹이다.**
- 스펙 상한: 1,024자
- Claude Code 목록 상한: description + when_to_use 합쳐 1,536자
- **실효 상한: 스킬 목록 예산.** "The budget scales at 1% of the model's context window" — 이 사용자 환경에는 스킬이 40개 이상이라 긴 description은 잘린다.
imagegen-frontend-web의 620자 description은 이 환경에서 위험하다.
**배제 조건이 과잉 발동을 막는 유일한 방법이다.** Codex 문서가 스펙 수준에서 이걸 요구한다:
> `description: Explain exactly when this skill **should and should not** trigger.`
**한국어 리터럴이 필요하다.** 이 사용자는 한국어로 대화한다. `codex-image`가 한국어 발화를 나열한 이유가 그것이다.
### designpaca에서의 구체 형태
```yaml
---
name: designpaca
description: >-
웹 UI를 새로 만들거나 다시 디자인할 때 쓴다. 랜딩페이지, 포트폴리오,
마케팅·제품 페이지, 기존 사이트 리디자인이 대상이다. "랜딩 만들어줘",
"디자인 예쁘게", "이 페이지 다시 디자인", "UI 만들어줘", "design a landing page",
"make this look better", "redesign this page" 같은 요청에 발동한다.
브리프를 먼저 읽고 방향을 선언한 뒤, 템플릿처럼 보이지 않는 UI를 만든다.
대시보드·데이터테이블·차트·네이티브 모바일 앱, 그리고 버그 수정이나
기능 추가처럼 시각 결과가 목적이 아닌 작업에는 쓰지 않는다.
---
```
(약 300자. 3부 구성 충족. 3인칭. 한/영 리터럴 포함. 배제 조건 명시.)
### 반론과 답
**반론**: "`paths`로 `**/*.tsx`를 걸면 자동 발동이 정확해지지 않나."
**답**: 두 가지 문제가 있다. (1) `paths`는 Claude Code와 Cursor에만 있고 Codex에는 없다. (2) **새 페이지를 만들 때는 파일이 아직 없다.** 디자인 스킬의 가장 흔한 진입점("랜딩 만들어줘")에서 작동하지 않는다.
---
## 원칙 4. 모든 규칙은 조건부다. 하드 밴에는 반드시 오버라이드 경로를 붙인다.
### 주장
"절대 금지"를 기본 문법으로 쓰지 않는다. **"기본값으로는 지양 + 오버라이드 조건 + 설명 의무"** 3단이 표준 형태다. 예외는 원칙 5에서 정의하는 소수의 하드 게이트뿐이다.
### 근거
**design-taste-frontend v1 → v2가 이 방향으로 갔다.**
v1:
> **THE LILA BAN:** The "AI Purple/Blue" aesthetic is **strictly BANNED**.
v2:
> **THE LILA RULE:** ... is **discouraged as a default**. ...
> **Override:** if the brand or brief explicitly asks for purple / violet / lila, **embrace it.** But execute with intent.
v2 문서 최상단이 철학을 선언한다:
> Every rule below is **contextual**. None of it fires automatically. First read the brief, then pull only what fits.
**Anthropic 공식이 우선순위를 못 박는다.**
> **Where the brief pins down a visual direction, follow it exactly — the brief's own words always win**, including when it asks for one of these looks.
> — frontend-design
> **Precedence is always: the user's own words, then the project's existing system, then your choices.**
> — artifact-design
**탈출구 없는 금지는 두 방향으로 실패한다.** (1) 사용자가 명시적으로 보라색을 요청해도 모델이 거부한다. (2) 모델이 하나를 어기기 시작하면 규칙 체계 전체의 권위가 무너진다.
**"설명 의무"가 오버라이드 남용을 막는다.**
> Serif is only acceptable when ... the aesthetic family is genuinely editorial / luxury / publication **AND you can articulate why this specific serif fits this specific brand**
> **Default-reaching for it because "this is a cookware brief" is banned.**
> — design-taste-frontend §4.1, §4.2
설명할 수 없으면 그건 기본값 회귀라는 뜻이므로 자동으로 걸러진다.
### designpaca에서의 구체 형태
표준 규칙 템플릿:
```markdown
### <규칙 이름>
<무엇이 기본 지양 대상인가. 구체적으로.>
**왜.** <한 문장. 미학이 아니라 결과로 설명.>
**대신.** <실행 가능한 대안 2~3개.>
**해도 되는 경우.** <구체 조건> 이 경우 **왜 이 브리프에 이것이 맞는지 한 문장으로
설명하고 진행한다.** 설명할 수 없으면 기본값으로 회귀한 것이다.
```
우선순위 체인을 본문 상단에 명시:
```
사용자의 명시적 지시 > 프로젝트의 design.md > 프로젝트의 기존 코드 토큰 > 이 스킬의 기본값
```
### 반론과 답
**반론**: "오버라이드를 열어두면 모델이 다 빠져나간다."
**답**: 그래서 원칙 5(하드 게이트)와 짝을 이룬다. 그리고 "설명 의무"가 실질적 장벽이다. 실제로 design-taste-frontend v2가 v1보다 결과가 좋다는 것이 이 스킬이 v1을 "backward compatibility용"으로만 남긴 이유다.
---
## 원칙 5. 하드 게이트는 검증 가능한 것에만 건다. 세거나 grep 할 수 있어야 한다.
### 주장
오버라이드 없는 절대 규칙은 **기계적으로 검증 가능한 항목에만** 적용한다. 취향 판단에는 절대 규칙을 걸지 않는다. 게이트는 20~30개로 제한하고, 각각 예/아니오 질문 형태로 쓴다.
### 근거
**주관적 규칙에 하드 밴을 걸면 지켜지지 않는다.** design-taste-frontend가 그 증거를 문서에 남겼다:
> **The agent has historically ignored em-dash limits when phrased as "use sparingly." The phrasing here is binary: zero em-dashes.**
em-dash는 grep 가능하다. 그래서 이진 규칙이 작동한다.
**반면 카운트 규칙은 즉시 검증된다.**
> **Pre-Flight Check is mechanical:** count instances of `uppercase tracking` across all section components. **If count > ceil(sectionCount / 3), the output fails.**
**체크박스보다 질문형이 낫다.** Hallmark의 58 게이트는 전부 질문이고 정답이 전부 "아니오"다:
> 4. Is any card nested inside another card?
> 10. Is `transition-all` (or `transition: all`) used anywhere?
> 14. Are you animating `width`, `height`, `top`, `left`, `margin`, or `padding` anywhere?
> **If any answer is yes, fix it. Do not ship slop.**
체크박스("- [ ] X를 했는가")는 모델이 무비판적으로 전부 체크한다. 질문형은 실제 검사 행위를 요구한다.
**하지만 58개는 과하다.** design-taste-frontend의 60개 체크박스도 마찬가지다. 매번 정직하게 60개를 검사하는 것은 비현실적이고, 모델은 결국 전부 통과 표시를 한다. **20~30개가 실효 상한**이다.
### designpaca에서의 구체 형태
**본문에 하드 게이트 12개** (가장 자주 깨지고 가장 치명적인 것):
```markdown
## 출력 전 하드 게이트 — 전부 "아니오"여야 한다
1. 인라인 hex/rgb/oklch 색상값이나 인라인 font-family가 토큰 밖에 있는가?
2. 한 페이지에서 액센트 색이 2개 이상인가?
3. 코너 반경 체계가 문서화된 규칙 없이 섞여 있는가?
4. 페이지 중간에 테마(라이트/다크)가 뒤집히는가?
5. 320~1920px 사이 어느 폭에서든 가로 스크롤이 생기는가?
6. 버튼 라벨·내비 링크·CTA가 2줄로 접히는 폭이 있는가?
7. 버튼 텍스트가 버튼 배경과 대비 4.5:1 미만인가?
8. `transform`/`opacity` 외의 속성을 애니메이션하는가?
9. `h-screen`/`100vh`를 풀하이트 섹션에 썼는가? (`100dvh`여야 한다)
10. `window.addEventListener('scroll')`을 썼는가?
11. 사용자가 주지 않은 수치(지표·통계·후기·고객 수)가 페이지에 있는가?
12. `<div>`로 만든 가짜 스크린샷·가짜 브라우저바·가짜 폰 프레임이 있는가?
```
**나머지 게이트는 `references/slop-gates.md`로.** 출력 직전에 그 파일을 읽고 실행한다.
**카운트 규칙 5개**를 본문에:
```
- eyebrow(작은 대문자 라벨) 개수 ≤ ceil(섹션수 / 3), 히어로 포함
- 같은 image+text 스플릿 레이아웃 연속 ≤ 2회
- 마퀴 ≤ 1개
- 8섹션 페이지에 최소 4개의 서로 다른 레이아웃 패밀리
- 히어로: 헤드라인 ≤ 2줄, 서브텍스트 ≤ 20단어, 텍스트 요소 ≤ 4개
```
### 반론과 답
**반론**: "취향 문제야말로 강제해야 하는 것 아닌가."
**답**: 취향은 원칙 4의 조건부 규칙과 원칙 8의 자기 채점으로 다룬다. 하드 게이트에 취향을 넣으면 게이트 전체의 신뢰도가 떨어진다. 모델이 "12번은 지킬 수 없으니 대충 넘어가자"를 배우면 1~11번도 같이 무너진다.
---
## 원칙 6. 프로젝트 루트에 design.md를 쓰고, 다음 실행은 그것을 읽는다.
### 주장
designpaca는 UI만 만들고 끝나지 않는다. **프로젝트 루트에 `design.md`를 쓴다.** 그리고 실행할 때마다 **먼저 그 파일을 찾고, 있으면 스킬 기본값보다 우선한다.** 함께 `.designpaca/log.json`에 이번 실행의 선택(구조·테마·액센트 대역)을 append 한다.
### 근거
**세션 간 일관성 문제는 상태 없이 풀 수 없다.** design-taste-frontend는 이 지시를 세 군데에 넣었다:
> **Palette-rotation rule:** if the previous premium-consumer project you generated used the beige+brass family, this one MUST use a different family.
> - [ ] **Serif discipline**: ... Different serif from your previous project?
**전부 작동하지 않는다.** 모델은 이전 세션을 기억하지 못한다.
**세 개의 독립 프로젝트가 파일 기반 해법에 도달했다.**
- Superdesign: `.superdesign/design-system.md` (필수, 없으면 먼저 생성)
- Hallmark: `design.md` (locked system, "overrides everything") + `.hallmark/log.json` (최근 20개)
- stitch-design-taste: `DESIGN.md` 생성이 스킬의 전부
Superdesign의 DESIGN.md 문서가 이유를 가장 정확히 쓴다:
> Coding agents write great code and mediocre interfaces. One reason: **they have no persistent sense of *how this product is supposed to look*.** `AGENTS.md` and `CLAUDE.md` tell an agent how your code works. **A design system file does the same for how your product looks** ... so every UI the agent ships is consistent with the last one instead of reinventing a generic look each time.
>
> **Capture it once; every design after that is consistent, on-brand, and faster to ship.**
**그리고 이것이 "AI 슬롭"의 정의를 바꾼다.** Hallmark의 관점:
> **Repeating a macrostructure across outputs is the structural fingerprint of templating, which is the AI tell Hallmark exists to defeat.**
개별 페이지가 아무리 예뻐도, 프로젝트 안의 페이지 5개가 같은 구조면 그게 슬롭이다.
### designpaca에서의 구체 형태
**읽기 (Step 0):**
```markdown
## Step 0 — 무엇이 이미 있는지 먼저 읽는다 (질문하기 전에)
1. `design.md` (또는 `.designpaca/design.md`) — 있으면 이것이 최상위다. 스킬 기본값을 전부 덮는다.
2. 없으면 코드에서 추출: 폰트 스택(next/font, @font-face, tailwind config),
팔레트(`:root`의 hex/hsl/oklch, tokens.json), 스페이싱 스케일, 모션 라이브러리, 프레임워크
3. `.designpaca/log.json` — 최근 3~5개 항목을 읽는다
4. **발견한 것을 파일:줄 인용과 함께 한 번 출력한다.** 사용자가 검증할 수 있어야 한다.
```
**쓰기 (마지막 단계):**
```json
// .designpaca/log.json — 앞에 append, 최근 20개만 유지
{ "date": "2026-08-20", "structure": "<이름>", "theme": "<이름>",
"accent_band": "warm|cool|neutral|chromatic", "brief": "<한 줄>" }
```
```markdown
<!-- design.md — 사용자가 "시스템 고정"이라고 하면 생성 -->
# Design System: <프로젝트명>
## 1. 제품 맥락 (무엇을, 누구를 위해, 핵심 가치)
## 2. 컬러 (이름 + hex + 역할)
## 3. 타이포그래피 (역할별 폰트 + 스케일)
## 4. 스페이싱·반경·그림자
## 5. 모션 (이징 이름, 지속시간, reduced-motion)
## 6. 컴포넌트 패턴
## 7. 이 프로젝트에서 금지된 것
```
템플릿은 `references/design-md-template.md`에. 작성 규칙은 stitch-design-taste에서:
> - **Be Descriptive:** "Deep Charcoal Ink (#18181B)" — not just "dark text"
> - **Be Precise:** Include exact hex codes, rem values, pixel values
> - Pitfall: 기술 용어를 번역 없이 쓰기 ("rounded-xl" 대신 "generously rounded corners")
### 반론과 답
**반론**: "파일 쓰기 권한이 없는 환경에서는?"
**답**: 로그 쓰기 실패는 조용히 넘어가고, 그 세션 안에서는 명시적 선언(원칙 7)으로 다양성을 유지한다. `design.md`는 사용자가 요청할 때만 쓴다. 읽기는 어디서나 된다.
**반론**: "매번 파일을 읽으면 느리지 않나."
**답**: Hallmark가 답을 준다. `.hallmark/preflight.json`에 캐시하고 "re-scan only on user request or when package.json mtimes are newer".
---
## 원칙 7. 코드를 쓰기 전에 선택을 평문으로 선언한다.
### 주장
Design Read 한 줄 + 선택 프리뷰 블록을 **코드 이전에** 출력한다. 무엇을 골랐는지, 이전 실행과 어느 축에서 다른지, 다이얼 값이 얼마인지를 사용자가 읽을 수 있는 형태로 낸다.
### 근거
**LLM이 나쁜 디자인을 내는 1번 원인은 미학 지식 부족이 아니라 브리프를 안 읽는 것이다.**
> Most LLM design output is bad because **the model jumps to a default aesthetic instead of reading the room.**
> — design-taste-frontend §0
**선언은 세 가지를 동시에 한다.** (1) 선택 행위를 강제한다. (2) 이후 출력이 선언과 일관되게 나온다. (3) 코드 생성 전에 교정 지점을 만든다.
**gpt-taste의 "Python RNG"도 결국 이 효과를 노린 것이다.** 난수는 가짜지만 선언은 진짜다. 그렇다면 가짜 난수를 걷어내고 선언만 남기는 게 정직하다.
**Hallmark의 프리뷰 블록이 형태의 모범이다:**
```markdown
**Hallmark · v1.1.0**
- **Macrostructure** · <name>
- **Theme** · <name>
- **Sections** · <section names>
- **Motion** · <primitives, or "none">
- **Slop test** · <N / 58 pass/fail>
- **Diversification** · <axes that differ from prior run>
```
**단, 전부 보여주면 안 된다.** Anthropic 공식:
> Try to do a lot of this planning and iteration **in your thinking**, and only show ideas to the user when you have higher confidence it'll delight them.
브레인스토밍은 사고 안에서, **결론만** 프리뷰로.
### designpaca에서의 구체 형태
```markdown
## Step 2 — 방향을 선언한다 (코드 전)
먼저 사고 안에서: 후보 방향 2~3개를 만들고, 각각을 브리프에 대조해 가장 특정한 것을 고른다.
비슷한 프롬프트를 머릿속으로 돌려서 같은 곳에 도착하면 그건 기본값이다. 다시 고른다.
그 다음 사용자에게 **결론만** 이 형태로 출력한다:
**designpaca**
- **읽기** · <페이지 종류> for <청중>, <분위기> 언어
- **트리트먼트** · 유틸리티 | 에디토리얼
- **구조** · <매크로구조 이름>
- **타입** · <디스플레이> + <본문> (+ <유틸리티>)
- **컬러** · <액센트 이름 (hex)> / <중성 계열>
- **시그니처** · <이 페이지를 기억하게 만들 단 하나의 요소>
- **모션** · <목록 또는 "없음">
- **다이얼** · variance <n> / motion <n> / density <n>
- **직전과 다른 축** · <축 이름> (로그가 있을 때)
```
**"시그니처" 항목이 원칙 9(대담함은 한 곳에)와 연결된다.** 여기에 하나만 적을 수 있으므로 자동으로 절제가 강제된다.
### 반론과 답
**반론**: "사용자가 빨리 결과를 보고 싶어할 텐데 프리뷰가 방해되지 않나."
**답**: 프리뷰는 9줄이다. 잘못된 방향으로 400줄 HTML을 만드는 것보다 훨씬 빠르다. 그리고 사용자가 "그냥 해"라고 하면 다음 턴부터 생략할 수 있다.
---
## 원칙 8. 트리트먼트를 먼저 정한다. 기본기는 항상, 대담함은 조건부.
### 주장
"디자인할지 말지"가 아니라 **"어느 정도의 트리트먼트가 맞는지"**를 먼저 판단한다. 스킬을 2계층으로 나눈다: **모든 산출물에 적용되는 기본기**와 **에디토리얼 브리프에만 적용되는 대담함**.
### 근거
**디자인 스킬의 두 번째로 큰 실패는 과잉 디자인이다.** 메모에 거대한 히어로를 붙이고, B2B 대시보드에 Awwwards 미학을 씌우는 것. high-end-visual-design과 gpt-taste는 이 실패를 구조적으로 피할 수 없다. 트리트먼트 축이 없기 때문이다.
**artifact-design이 이 문제의 가장 정확한 처방을 담고 있다:**
> **Calibrate treatment, not whether to design.** A doc deserves the same craft as a landing page — **what changes is the treatment that craft is delivered in.**
>
> Many requests call for a more utilitarian treatment: a plan, a memo, a demo. Make it polished ... **but avoid over-designing. Most pages do not need a flashy, gigantic hero.**
>
> **When unsure: a well-composed page is never the wrong answer; an over-designed visual identity sometimes is.**
>
> Fundamentals below apply to everything. **The editorial process after that runs only when the read above says so.**
그리고 UI일 때 무엇이 달라지는지도 명시한다:
> A dashboard or tool is scanned and operated, not read top-to-bottom, so **the craft shifts from typography to information design.** Surface the summary before the detail; encode state in form as well as number.
**design-taste-frontend는 이걸 "범위 밖 선언"으로 처리한다:**
> This skill is NOT for: Dashboards / Data tables / Multi-step forms / Code editors / Native mobile / Realtime collab UIs.
> If the brief is one of the above, **say so explicitly**, point to the right tool.
두 접근을 합치는 게 낫다. **범위 밖은 거절하고, 범위 안에서는 트리트먼트를 보정한다.**
### designpaca에서의 구체 형태
**본문 구조:**
```markdown
## 트리트먼트 보정 (첫 판단)
**에디토리얼** — 랜딩페이지, 포트폴리오, 캠페인 페이지, 제품 소개, 사용자가 자랑할 물건.
→ 대담함 예산 1개. 시그니처 요소 하나. 나머지는 조용히.
**유틸리티** — 내부 도구, 문서 페이지, 관리 화면, 데모, 플랜/메모 페이지.
→ 진짜 타이포그래피 위계, 계산된 여백, 제대로 된 팔레트. 그것으로 충분하다.
거대한 히어로 없음. 스크롤 연출 없음. 장식 없음.
**정보 밀도형** — 대시보드, 데이터 테이블, 차트 화면.
→ 이 스킬의 미학 규칙 대부분이 적용되지 않는다. 위계는 타이포가 아니라 정보설계가 만든다.
요약을 먼저, 상세를 나중에. 상태는 숫자만이 아니라 형태로도 인코딩한다
(필, 칩, 심각도 스트라이프). 의미색(good/warning/critical)은 액센트와 별개다.
차트가 있으면 dataviz 스킬을 쓴다.
**범위 밖** — 네이티브 모바일(Apple HIG/Material), 코드 에디터(Monaco/CodeMirror),
실시간 협업 UI. → 그렇다고 말하고 올바른 도구를 알려준다.
확신이 안 서면 유틸리티 쪽으로 기운다.
**잘 구성된 페이지는 틀린 답이 된 적이 없다. 과잉 디자인된 비주얼 아이덴티티는 가끔 틀린 답이다.**
---
## 모든 트리트먼트에 적용되는 기본기
<타이포 위계 / 여백 / 토큰 / 대비 / 반응형 / 포커스 / reduced-motion / 카피>
## 에디토리얼일 때만
<시그니처 요소 / 히어로 논지 / 모션 연출 / 미학적 위험 1개>
```
### 반론과 답
**반론**: "사용자가 designpaca를 부른 건 화려한 걸 원해서 아닌가."
**답**: 아니다. 사용자가 원하는 건 **잘 만들어진 것**이다. artifact-design의 문장이 이 차이를 정확히 잡는다. 그리고 유틸리티 트리트먼트를 명시적으로 인정하지 않으면, 모델은 메모에도 히어로를 붙인다.
---
## 원칙 9. 대담함은 한 곳에만. 나머지는 조용히.
### 주장
"창의적으로 하라"를 지시로 쓰지 않는다. 대신 **시그니처 요소 정확히 하나**를 정하게 하고, 나머지 전부에 절제를 요구한다. 그리고 그 절제를 검증 가능한 수치로 만든다.
### 근거
**"창의적으로"는 모든 섹션에 장식을 붙이는 결과를 낳는다. 그게 슬롭이다.**
**Anthropic 공식이 이 문제의 가장 좋은 프레이밍을 갖고 있다:**
> **Spend your boldness in one place.** Let the signature element be the one memorable thing, keep everything around it quiet and disciplined, and **cut any decoration that does not serve the brief. Not taking a risk can be a risk itself!**
>
> **Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory.**
계획 단계에도 이 항목이 들어간다:
> **Signature:** the single unique element this page will be remembered by that embodies the brief.
**그런데 이것만으로는 검증이 안 된다.** 두 스킬이 이걸 수치로 만들었다:
Hallmark:
> 23. Does the accent colour cover more than ~5 % of any single viewport?
imagegen-frontend-web:
> ### Second-Read Moment
> **Pick exactly 1** unobvious but legible motif and place it deliberately, **once across the page**.
> **Avoid gimmick-for-gimmick: the moment must aid scan order or brand recall.**
**그리고 복잡도를 방향에 맞추는 규칙이 짝을 이룬다:**
> **Match complexity to the vision.** Maximalist directions need elaborate execution; **minimal directions need precision in spacing, type, and detail. Elegance is executing the chosen vision well.**
> — frontend-design
> **Simplicity is not the goal by itself. Cleanliness is the goal.** ... The rule is: **not always simple, always clean**
> — imagegen-frontend-mobile §25
### designpaca에서의 구체 형태
**프리뷰 블록에 "시그니처" 슬롯 1개** (원칙 7). 하나만 적을 수 있다.
**본문 규칙:**
```markdown
## 대담함 예산
이 페이지에서 기억될 요소는 **하나**다. 프리뷰의 "시그니처"에 적은 것.
그 하나에 모든 대담함을 쓰고, 나머지 전부는 조용하고 규율 있게 만든다.
검증:
- 액센트 색은 어느 뷰포트에서도 화면 면적의 5%를 넘지 않는다
- 시그니처 요소 외에 "이건 좀 특이하네" 소리를 들을 만한 것이 2개 이상이면 하나를 뺀다
- 브리프에 봉사하지 않는 장식은 전부 제거한다
위험을 안 지는 것도 위험이다. 시그니처가 "그냥 큰 헤드라인"이면 그건 시그니처가 아니다.
**복잡도는 방향에 맞춘다.** 맥시멀리즘은 정교한 실행을 요구하고, 미니멀리즘은
여백·타입·디테일의 정밀함을 요구한다. **미니멀은 요소를 지우는 게 아니라 남은 것을
정확하게 만드는 것이다.** 단순함이 목표가 아니라 깔끔함이 목표다.
```
### 반론과 답
**반론**: "그럼 결과가 밋밋해지지 않나."
**답**: 반대다. 대담함이 분산되면 아무것도 기억에 안 남는다. 한 곳에 집중되면 그 하나가 기억된다. 그리고 "Not taking a risk can be a risk itself"가 밋밋함에 대한 방어다.
---
## 원칙 10. 미학 규칙과 실무 버그 규칙을 분리한다. 버그 규칙은 협상 불가다.
### 주장
스킬의 규칙을 두 종류로 명확히 나눈다.
- **미학 규칙** — 조건부, 오버라이드 있음, 브리프가 이긴다
- **실무 규칙** — 접근성·성능·반응형·정직성. **오버라이드 없음.** 브리프가 요청해도 안 된다.
그리고 실무 규칙에는 "AI가 반복적으로 만드는 실제 렌더링 버그" 목록을 포함한다.
### 근거
**두 종류가 섞여 있으면 둘 다 약해진다.** "Inter를 쓰지 마라"와 "버튼 텍스트가 배경과 대비 4.5:1을 넘겨라"가 같은 목록에 있으면, 모델은 둘 다 취향 문제로 읽는다.
**여러 소스에서 같은 버그가 반복 등장한다.** 이건 실측 데이터에 가깝다:
`h-screen` → `100dvh`: design-taste-frontend, high-end-visual-design, stitch-design-taste, redesign-existing-projects **4개 스킬 공통**
`transform`/`opacity`만 애니메이션: **거의 모든 소스 공통**
토큰 경유 강제: design-taste-frontend, Hallmark, **v0, Lovable 4개 시스템이 독립적으로 도달**
> "DO NOT use direct colors like text-white, bg-white, bg-black, etc. Everything must be themed via design tokens" — v0
> "DO NOT use direct colors like text-white, text-black, bg-white, bg-black" — Lovable
> "Inline OKLCH/hex/rgb or font declarations are forbidden." — Hallmark
**그리고 미학과 무관한 순수 버그들이 있다:**
> 50. **Image-bearing grid track without `minmax(0, 1fr)`.** — Hallmark
> 51. **Display headers without long-word wrap** (`overflow-wrap: anywhere; min-width: 0`) — Hallmark
> 56. **Sticky element at `top: 0` below a sticky page-level nav.** Auto-fail. — Hallmark
> **NO 100vw widths.** Breaks on scrollbar-visible desktops. — Hallmark
> It's easy to generate CSS classes that cancel each other out (`.section` vs `.cta`) — frontend-design
> Lay out sibling groups with flex or grid and `gap`, **not per-element margins that silently collapse or double** — artifact-design
> **a color whose only definition sits behind `[data-theme]` never applies in the un-stamped state** — artifact-design
> `useState`로 연속값 추적 금지 — "collapses on mobile" — design-taste-frontend
> `loading="lazy"` on LCP — "p75 of 720 ms vs. 364 ms for preloaded" — Hallmark
**정직성도 실무 규칙이다.** 지어낸 지표는 취향 문제가 아니라 신뢰 문제다:
> A page that lies on its proof bar can't be trusted on its claims either ... **The number-shaped hole is honest; the fabricated number is slop.**
> — Hallmark
### designpaca에서의 구체 형태
**본문에 별도 섹션:**
```markdown
## 협상 불가 규칙
아래는 취향이 아니다. 브리프가 요청해도 예외를 두지 않는다.
미학 규칙(조건부)과 달리 이 목록에는 오버라이드 경로가 없다.
### 접근성
- 모든 텍스트와 UI 요소가 배경에 대해 WCAG AA (본문 4.5:1, 18px+ 대형 텍스트 3:1)
- 버튼 텍스트가 버튼 배경에 대해 대비 통과. 고스트 버튼이 사진 위에 있으면 스크림이나 스트로크
- 폼 입력·플레이스홀더·헬퍼·에러 텍스트 전부 대비 통과
- 모든 인터랙티브 요소에 보이는 `:focus-visible`. **포커스 링은 즉시 나타난다.
절대 페이드인시키지 않는다** (전환 중에는 키보드 사용자가 아무것도 못 본다)
- 터치 타깃 최소 44px
- 색만으로 정보를 전달하지 않는다
### 반응형
- 320~1920px 전 구간에서 가로 스크롤 없음
- 버튼 라벨·내비 링크·CTA는 어느 폭에서도 1줄. 안 되면 라벨을 줄인다 (기본 CTA는 3단어 이하)
- 풀하이트 섹션은 `min-h-[100dvh]`. `h-screen`/`100vh` 금지 (iOS Safari 주소창)
- `width: 100vw` 금지 (스크롤바 있는 데스크톱에서 깨진다). `width: 100%` + 컨테이너 패딩
- 이미지가 들어가는 그리드 트랙은 `minmax(0, 1fr)`. 맨 `1fr` 금지
- 디스플레이 사이즈 텍스트에 `overflow-wrap: anywhere; min-width: 0`
- 다단 레이아웃마다 768px 미만 붕괴 규칙을 같은 컴포넌트 안에 명시
- 페이지 레벨 sticky 아래에 또 다른 `top: 0` sticky 금지
### 성능
- `transform`과 `opacity`만 애니메이션. `top`/`left`/`width`/`height`/`margin`/`padding` 금지
- `window.addEventListener('scroll')` 금지. IntersectionObserver, 스크롤 구동 CSS
(`animation-timeline: view()`), 또는 라이브러리 훅을 쓴다
- 연속값(마우스 위치, 스크롤 진행률)을 React state로 추적 금지
- `backdrop-blur`는 fixed/sticky 요소에만. 스크롤 컨테이너나 큰 콘텐츠 영역에 금지
- 노이즈/그레인은 `position: fixed; pointer-events: none` 의사요소에만
- LCP 요소에 `loading="lazy"` 금지. `fetchpriority="high"`
- `prefers-reduced-motion: reduce`에서 모든 공간 이동이 150ms 이하 opacity 크로스페이드로 붕괴
- `useEffect` 애니메이션에 정리 함수
### 토큰 규율
- 모든 색과 폰트는 명명된 CSS 커스텀 프로퍼티를 경유한다
- 인라인 hex/rgb/oklch, 인라인 `font-family`, `text-white`/`bg-black` 같은 직접 색 클래스 금지
- 필요한 값이 토큰에 없으면 **토큰을 먼저 추가**하고 참조한다
- 한 페이지 = 하나의 액센트, 하나의 반경 체계, 하나의 테마
### 정직성
- 사용자가 주지 않은 지표·통계·후기·로고·고객 수를 만들지 않는다.
없으면 라벨 붙은 플레이스홀더(`— / 확인 필요`)를 두거나, 사용자에게 묻거나, 그 섹션을 뺀다
- `<div>`로 가짜 스크린샷·가짜 브라우저바·가짜 폰 프레임·가짜 IDE 크롬을 만들지 않는다
- 이미지 생성 도구가 없고 실제 이미지도 없으면, 라벨 붙은 플레이스홀더 슬롯을 두고
**응답 끝에 무엇이 필요한지 목록으로 말한다**
- 존재하지 않는 라이브러리를 import 하지 않는다. 쓰기 전에 의존성을 확인한다
### CSS 위생
- 셀렉터 특이성 충돌 주의. 타입 기반(`.section`)과 요소 기반(`.cta`) 셀렉터가
섹션 간 padding/margin을 두고 서로를 상쇄하는 일이 잦다
- 형제 그룹 간격은 flex/grid의 `gap`으로. 요소별 margin은 조용히 붕괴하거나 두 배가 된다
- 넓은 콘텐츠(테이블·코드·다이어그램)는 자기 컨테이너에 `overflow-x: auto`
- 다크모드는 3상태다. 색을 미디어 쿼리나 `[data-theme]` 블록 안에서만 정의하면
스탬프 없는 기본 상태에서 적용되지 않는다. `body`에 명시적 배경 토큰을 준다
```
### 반론과 답
**반론**: "이 목록이 길다. 원칙 1(500줄)과 충돌하지 않나."
**답**: 이 섹션은 약 50줄이다. 그리고 **이게 스킬이 실제로 값을 만드는 부분**이다. 미학 지식은 references로 뺄 수 있지만, 이 목록은 매번 적용되어야 하므로 본문에 있어야 한다.
**반론**: "브리프가 `100vh`를 원하면?"
**답**: `100dvh`가 같은 결과를 더 정확하게 낸다. 이건 취향 대립이 아니라 구식 API 대 신식 API다. 다른 항목들도 마찬가지다. 브리프가 "포커스 링 없애줘"라고 하면 그건 접근성 후퇴이므로 거절하고 대안(더 절제된 포커스 스타일)을 제시한다.
---
## 부록 A. 원칙 간 상호작용
| 원칙 | 지원하는 원칙 | 긴장 관계 |
|---|---|---|
| 1. references 분리 | 2(앞부분 배치), 5(게이트 분리) | 10(협상불가 목록은 본문에) |
| 2. 최상단 핵심 규칙 | 1, 4, 10 | - |
| 3. description 3부 | - | - |
| 4. 조건부 규칙 | 8(트리트먼트), 9(대담함) | 5(하드 게이트), 10(협상불가) |
| 5. 검증 가능 게이트 | 10 | 4 |
| 6. design.md + 로그 | 7(선언), 9(시그니처) | - |
| 7. 명시적 선언 | 6, 8, 9 | - |
| 8. 트리트먼트 보정 | 4, 9 | - |
| 9. 대담함 한 곳 | 7, 8 | - |
| 10. 실무 규칙 분리 | 2, 5 | 4 |
**4 vs 5·10의 긴장이 핵심이다.** 해소 방식: **규칙을 세 등급으로 명시적으로 나눈다.**
- **협상 불가** (원칙 10) — 접근성·성능·반응형·정직성·토큰. 오버라이드 없음
- **하드 게이트** (원칙 5) — 검증 가능한 슬롭 탐지. 오버라이드 없음, 단 검증 가능한 항목에만
- **조건부 미학** (원칙 4) — 나머지 전부. 브리프가 이긴다, 설명 의무 있음
스킬 본문에서 이 세 등급을 **시각적으로 구분**해야 한다. 같은 목록에 섞으면 등급이 무너진다.
---
## 부록 B. 명시적으로 채택하지 않는 것
| 항목 | 어디서 왔나 | 채택 안 하는 이유 |
|---|---|---|
| 가짜 Python RNG 시뮬레이션 | gpt-taste §1 | 난수가 생성되지 않는다. 같은 프롬프트 → 같은 결과. 원칙 7(명시적 선언)이 같은 효과를 정직하게 낸다 |
| "이전 프로젝트와 다른 세리프/팔레트" (파일 없이) | design-taste-frontend §4.1, §4.2, §14 | 상태 없이 실행 불가. 원칙 6(로그 파일)로 대체 |
| 다이얼 9축 | image-to-code §1 | 인지 부하 대비 효과 없음. 3축 유지 |
| Pre-Flight 체크박스 60개 | design-taste-frontend §14 | 정직한 검사가 불가능한 분량. 본문 12개 + references로 분리 |
| 슬롭 게이트 58개를 본문에 | Hallmark | 같은 이유. 본문 12개, 나머지는 `references/slop-gates.md` |
| 단일 미학 강제 | minimalist-ui, industrial-brutalist-ui, high-end-visual-design | designpaca는 여러 방향을 다뤄야 한다. 이들은 `assets/themes/` 아래 개별 테마 파일로 흡수 |
| `trigger:` 프론트매터 필드 | graphify | 스펙에 없다. claude.ai 업로드/패키징 하드 에러. Windsurf의 `trigger`와 의미도 다르다 |
| 존재하지 않는 파일 경로 지시 | design-taste-frontend §12 (blocks/) | 모델을 혼란시킨다. 만들 거면 만들고, 아니면 언급하지 않는다 |
| 특정 프레임워크 고정 (React/Next 전제) | design-taste-frontend §3.A, gpt-taste §5 | Vue, Svelte, Astro, 바닐라 HTML에서도 돌아야 한다. 스택은 사전 스캔(원칙 6 Step 0)에서 감지한다 |
| GSAP 강제 | gpt-taste §5, design-taste-frontend §5.A/5.B | 스택 의존. 모션 규칙은 라이브러리 불가지론으로 쓴다 |
| 형용사 나열형 페르소나 ("elite", "$150k agency") | high-end-visual-design, gpt-taste | 정보를 주지 않고, "화려하게 하라"로 오독된다. 원칙 8·9와 충돌 |
| 이미지 생성 도구 전제 워크플로 | image-to-code, imagegen-* | 환경 의존. 도구가 있으면 쓰고 없으면 정직한 플레이스홀더(원칙 10)로 분기한다 |
---
## 부록 C. 다음 단계 (설계 → 구현)
1. **description 초안 3~5개를 쓰고 트리거 평가를 돌린다.** skill-creator의 절차대로: should-trigger 8~10개, should-not-trigger 8~10개. 네거티브는 "genuinely tricky"해야 한다 (같은 키워드를 공유하지만 다른 걸 필요로 하는 near-miss).
2. **SKILL.md 본문 400~480줄 초안.** 순서: READ FIRST 5규칙 → 페르소나 3줄 → 트리트먼트 보정 → Step 0 사전 스캔 → Step 1 브리프 읽기 → Step 2 선언 → Step 3 참조 로드 인덱스 → Step 4 빌드 → Step 5 게이트 → Step 6 로그/design.md → 협상 불가 규칙.
3. **references 11개 작성.** 각각 100줄 넘으면 목차 포함. anti-patterns.md는 `무엇/왜 실패/대신` 3단 구조를 지킨다.
4. **테마 파일 작성.** minimalist-ui, industrial-brutalist-ui, high-end-visual-design의 내용을 `assets/themes/*.md`로 이식. 인덱스-후-선택 로딩.
5. **평가.** 최소 3개 시나리오 (새 랜딩 / 기존 페이지 리디자인 / 유틸리티 페이지). 스킬 없는 베이스라인과 비교.
6. **크로스툴 검증.** `skills-ref validate`, Claude Code `/doctor`, Cursor에서 발동 확인, Codex에서 발동 확인.
7. **레거시 어댑터 생성 스크립트.** SKILL.md → `.mdc` / Windsurf 규칙 / AGENTS.md 포인터. 03-format-specs.md §8.4의 주의점을 스크립트에 반영.

1306
research/skills/06-skill-audit.md Normal file
View file

File diff suppressed because it is too large Load diff