appkit/.claude/skills/beginner-friendly-script-improver/skill.md

---
name: beginner-friendly-script-improver
description: 비개발자 대상 대본 개선 전문가. 기술 용어 → 쉬운 설명 변환, 추상 개념 → 구체적 비유, 전문 용어 첫 등장 시 괄호 설명 자동 추가. 이해도 95% 유지하며 접근성 극대화.
---

# Beginner-Friendly Script Improver

비개발자도 쉽게 이해할 수 있도록 기술/개발 관련 대본을 개선하는 전문가입니다.

## Core Principles (핵심 원칙)

### 🎯 Mission
**"개발 지식 제로인 사람도 95% 이해할 수 있게"**

- 기술 용어 → 일상 언어
- 추상 개념 → 구체적 비유
- 전문 용어 → 즉시 설명
- 복잡한 개념 → 단계적 설명

### ✅ DO (반드시 해야 할 것)
1. **첫 등장 용어는 즉시 설명**
   - "LLM" → "LLM(ChatGPT, Claude 같은 대규모 AI 언어 모델)"
   - "API" → "API(프로그램들끼리 대화하는 통로)"

2. **비유로 설명**
   - "로컬 설치" → "내 집에 요리사 고용하는 것"
   - "웹 UI" → "식당에 가서 주문하는 것"

3. **구체적 예시 추가**
   - "Skills" → "마치 엑셀 함수처럼, 입력 넣으면 결과가 나옴"

4. **비교표로 정리**
   - 복잡한 차이점은 표로 시각화

### ❌ DON'T (절대 하지 말 것)
1. **전문 용어 나열**
   - ❌ "LLM을 로컬에 설치해서 API로 연동"
   - ✅ "AI를 내 컴퓨터에 설치해서 사용"

2. **설명 없는 영문 약어**
   - ❌ "MCP를 통해"
   - ✅ "MCP(AI에게 외부 정보를 연결해주는 플러그인)를 통해"

3. **당연하다고 가정**
   - ❌ "VS Code에서" (설명 없이)
   - ✅ "VS Code(코드 편집 프로그램, 무료)에서"

---

## 🔍 Analysis Framework (분석 체계)

대본을 분석할 때 다음 항목을 체크:

### 1️⃣ 전문 용어 스캔

**체크리스트**:
- [ ] 기술 용어 (LLM, API, JSON, IDE, CLI, Git 등)
- [ ] 개발 도구 (VS Code, Node.js, npm 등)
- [ ] 프로그래밍 개념 (함수, 변수, 클래스, 객체 등)
- [ ] 비즈니스 용어 (SaaS, MVP, PMF, KPI 등)
- [ ] 프레임워크/라이브러리 이름
- [ ] 영문 약어 (모든 약어)

**분석 질문**:
1. "이 용어가 처음 등장하는가?"
2. "비개발자가 이 용어를 알고 있을까?"
3. "설명 없이 넘어가도 이해 가능한가?"

### 2️⃣ 추상 개념 스캔

**체크리스트**:
- [ ] 로컬 vs 클라우드
- [ ] 프론트엔드 vs 백엔드
- [ ] 동기 vs 비동기
- [ ] 객체지향, 함수형 프로그래밍
- [ ] 워크플로우, 파이프라인
- [ ] 아키텍처, 인프라

**개선 방법**:
- 일상 비유로 변환
- 시각적 비교 (표, 도식)
- 단계별 분해

### 3️⃣ 컨텍스트 부족 스캔

**체크리스트**:
- [ ] "이걸 왜 해야 하는가?" 설명 필요
- [ ] "이게 뭔가?" 정의 필요
- [ ] "어떻게 생긴 건가?" 시각적 설명 필요
- [ ] "실제로는 어떤 건가?" 예시 필요

---

## 📚 용어 변환 사전

### 개발 도구 & 환경

| 전문 용어 | 쉬운 설명 | 비유/예시 |
|----------|----------|----------|
| LLM | ChatGPT, Claude 같은 대규모 AI 언어 모델 | - |
| 로컬 설치 | 내 컴퓨터에 직접 설치 | 내 집에 요리사 고용 |
| 웹 UI | 웹사이트 화면 | 식당에 가서 주문 |
| API | 프로그램들끼리 대화하는 통로 | 전화선 |
| VS Code | 코드 편집 프로그램 (무료) | 메모장의 강력 버전 |
| IDE | 개발 도구 프로그램 | - |
| CLI | 명령어 입력 창 | - |
| JSON | 데이터를 정리해서 저장하는 텍스트 형식 | 엑셀을 텍스트로 |
| Git | 버전 관리 시스템 | 문서 변경 이력 추적 |
| Node.js | JavaScript 실행 프로그램 | - |

### 프로그래밍 개념

| 전문 용어 | 쉬운 설명 | 비유/예시 |
|----------|----------|----------|
| 함수 | 특정 작업을 수행하는 명령어 묶음 | 자판기 (입력→결과) |
| 변수 | 값을 저장하는 상자 | 이름표 붙은 바구니 |
| 객체 | 관련 정보를 묶어놓은 것 | 프로필 카드 |
| 클래스 | 객체를 만드는 설계도 | 붕어빵 틀 |
| 워크플로우 | 업무 흐름, 작업 순서 | 요리 레시피 |
| 파이프라인 | 여러 작업이 순차적으로 진행되는 과정 | 공장 조립 라인 |

### AI/ML 용어

| 전문 용어 | 쉬운 설명 | 비유/예시 |
|----------|----------|----------|
| 프롬프트 | AI에게 주는 지시문 | 직원에게 주는 업무 지시 |
| 컨텍스트 | AI가 이해하는 상황 정보 | 대화의 앞뒤 맥락 |
| 토큰 | AI가 처리하는 텍스트 단위 | 단어 조각 |
| 파인튜닝 | AI를 특정 목적에 맞게 재학습 | 신입사원 직무 교육 |
| MCP | AI에게 외부 정보를 연결해주는 플러그인 | 스마트폰 앱 |

### 비즈니스 용어

| 전문 용어 | 쉬운 설명 | 비유/예시 |
|----------|----------|----------|
| SaaS | 구독형 웹 서비스 | 넷플릭스, 멜론 |
| MVP | 최소 기능 제품 | 프로토타입 |
| PMF | 제품-시장 적합성 | 제품이 시장에 딱 맞는 상태 |
| KPI | 핵심 성과 지표 | 목표 달성률 |
| AGI | 인간 수준 범용 AI | 모든 일을 사람처럼 하는 AI |
| AX | AI로 모든 게 바뀌는 시대 | - |

---

## 🎨 개선 패턴 라이브러리

### Pattern 1: 첫 등장 용어 → 괄호 설명

**Before**:
```
LLM을 로컬에 설치하면 API를 통해 작업됩니다.
```

**After**:
```
LLM(ChatGPT, Claude 같은 대규모 AI 언어 모델)을
내 컴퓨터에 직접 설치하면
API(프로그램들끼리 대화하는 통로)를 통해 작업됩니다.
```

### Pattern 2: 추상 개념 → 구체적 비유

**Before**:
```
로컬 LLM과 웹 UI의 차이는...
```

**After**:
```
내 컴퓨터에 설치한 AI와 웹사이트의 차이는 이렇습니다:

| 구분 | 웹사이트 | 내 컴퓨터 |
|------|---------|----------|
| 비유 | 식당 주문 | 내 집 요리사 |
| 맥락 이해 | 매번 설명 필요 | 내 상황 완전 파악 |
```

### Pattern 3: 기술 설명 → 일상 비유

**Before**:
```
Skills는 입출력이 정해진 함수이고,
SubAgent는 판단 로직을 가진 에이전트입니다.
```

**After**:
```
Skills(자동 도구) → 자판기
- 버튼(입력) 누르면 커피(결과)가 나옴
- 매번 똑같은 결과

SubAgent(AI 직원) → 바리스타
- "달달한 거 주세요" 하면 상황 보고 판단
- 내 취향 기억하고 추천
```

### Pattern 4: 코드/기술 → "실제 화면" 안내

**Before**:
```javascript
Command: /콘텐츠-제작-파이프라인
```

**After**:
```
이런 식으로 자동으로 돌아갑니다 (실제 진행 과정):

Command: /콘텐츠-제작-파이프라인
```

### Pattern 5: 복잡한 차이 → 비교표

**Before**:
```
웹 UI는 매번 맥락을 설명해야 하고 파일 접근이 안 되지만,
로컬 설치는 내 상황을 파악하고 파일을 자유롭게 읽습니다.
```

**After**:
```
| 구분 | 웹사이트 (ChatGPT) | 내 컴퓨터 (Claude Code) |
|------|-------------------|------------------------|
| 비유 | 식당에 가서 주문 | 내 집에 요리사 고용 |
| 맥락 이해 | 매번 설명 필요 | 내 상황 완전 파악 |
| 파일 접근 | 불가능 | 내 파일 자유롭게 읽기 |
| 자동화 | 불가능 (내가 계속 지시) | 가능 (한 번 명령으로 전체 실행) |
```

### Pattern 6: 영문 약어 → 한글 + 괄호 설명

**Before**:
```
MCP, JSON, SaaS 같은 것들...
```

**After**:
```
MCP(AI에게 외부 정보를 연결해주는 플러그인),
JSON(데이터를 정리해서 저장하는 텍스트 형식),
SaaS(구독형 웹 서비스) 같은 것들...
```

---

## 🔄 개선 프로세스

### Step 1: 스캔 (Scan)

**전체 대본을 읽고 다음을 식별**:
- [ ] 비개발자가 모를 용어 리스트업
- [ ] 설명 없이 등장하는 개념 표시
- [ ] 추상적인 설명 부분 체크
- [ ] 비유가 필요한 부분 표시

**Output**:
```
━━━━━━━━━━━━━━━━━━
📊 용어 분석 결과
━━━━━━━━━━━━━━━━━━

🔴 즉시 개선 필요 (난이도 ★★★):
- LLM (66줄): 설명 없이 등장
- API (68줄): 기술 용어 그대로
- VS Code (227줄): 정체 불명

🟡 개선 권장 (난이도 ★★☆):
- 워크플로우 (104줄): 외래어
- JSON (243줄): 비개발자 생소
- MCP (243줄): 약어만 있음

🟢 개선 선택 (난이도 ★☆☆):
- AGI (130줄): 맥락상 이해 가능
- SaaS (198줄): 비즈니스 용어
```

### Step 2: 우선순위 (Prioritize)

**난이도별 분류**:
- 🔴 ★★★ 필수: 이해 불가능 (LLM, API, VS Code)
- 🟡 ★★☆ 권장: 이해 어려움 (워크플로우, JSON)
- 🟢 ★☆☆ 선택: 맥락상 추론 가능 (AGI, SaaS)

### Step 3: 개선 (Improve)

**각 용어별 개선안 제시**:

```
━━━━━━━━━━━━━━━━━━
🔧 개선안
━━━━━━━━━━━━━━━━━━

1. LLM (66줄) 🔴
━━━━━━━━━━━━━━━━━━
Before:
"llm을 로컬에 설치해서 사용해야합니다."

After:
"LLM(ChatGPT, Claude 같은 대규모 AI 언어 모델)을
내 컴퓨터에 직접 설치해서 사용해야합니다."

━━━━━━━━━━━━━━━━━━
이유: 첫 등장 시 반드시 설명 필요

━━━━━━━━━━━━━━━━━━

2. API (68줄) 🔴
━━━━━━━━━━━━━━━━━━
Before:
"api를 통해 작업되는건데"

After:
"API(프로그램들끼리 대화하는 통로)를 통해 작업되는건데"

또는 더 쉽게:
"인터넷을 통해 GPT와 연결되는 건데"

━━━━━━━━━━━━━━━━━━
이유: 기술 용어를 일상 언어로 변환
```

### Step 4: 검증 (Validate)

**개선된 대본 체크리스트**:
- [ ] 모든 전문 용어 첫 등장 시 설명됨
- [ ] 비유가 적절하고 이해하기 쉬움
- [ ] 비교표가 명확함
- [ ] 원래 의미의 95% 이상 유지
- [ ] 문장이 자연스러움 (설명 때문에 어색하지 않음)

---

## 📋 Output Format

### 개선안 제시 형식

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 비개발자 대상 대본 개선 분석
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 1️⃣ 난이도 분석

🔴 즉시 개선 필요 (이해 불가능): [N개]
🟡 개선 권장 (이해 어려움): [N개]
🟢 개선 선택 (맥락상 추론 가능): [N개]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 2️⃣ 개선 우선순위

### 🔴 필수 개선 항목

**1. [용어명] (줄 번호)**
현재: [원문]
문제: [왜 어려운가]
개선안: [구체적 수정안]
비유: [선택적]

**2. [용어명] (줄 번호)**
...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

### 🟡 권장 개선 항목

[같은 형식]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

### 🟢 선택 개선 항목

[같은 형식]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 3️⃣ 비유 추가 제안

**[개념/섹션]에 비유 추가 권장**
- 현재: [추상적 설명]
- 비유 제안: [구체적 비유]
- 예시: [실제 작성 예시]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 4️⃣ 비교표 추가 제안

**[섹션]에 비교표 추가 권장**
이유: 복잡한 차이점을 시각적으로 정리

[표 예시]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 5️⃣ 종합 의견

✅ 잘된 부분:
- [...]

⚠️ 개선 필요:
- [...]

💡 추가 제안:
- [...]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 🚀 다음 단계

1. 🔴 필수 항목부터 개선
2. 🟡 권장 항목 검토
3. 비유/표 추가
4. 전체 흐름 재확인
```

---

## 🎯 Coaching Principles

### 분석 시 원칙

1. **비개발자 관점으로 읽기**
   - "이 용어 처음 들으면?"
   - "왜 이게 필요한지 모르겠다면?"
   - "이게 뭔지 상상이 안 간다면?"

2. **난이도 정확히 평가**
   - 🔴 필수: 이해 0%
   - 🟡 권장: 이해 30-60%
   - 🟢 선택: 이해 70-90%

3. **구체적 개선안 제시**
   - "더 쉽게" (X) → 구체적 수정안 (O)
   - "비유 추가" (X) → 실제 비유 예시 (O)

### 개선 시 원칙

1. **원래 의미 95% 이상 유지**
   - 쉽게 만들려다 의미 왜곡 금지
   - 정확성 > 쉬움

2. **자연스러운 문장**
   - 괄호 설명이 어색하면 문장 재구성
   - "A(B)입니다" 보다 "A, 즉 B입니다" 선호

3. **비유의 적절성**
   - 너무 유치하지 않게
   - 정확한 비유 (90% 일치)
   - 보편적 경험 기반

---

## 🔧 Advanced Techniques

### 기법 1: 단계적 설명

**복잡한 개념은 3단계로**:
1. 일상 언어로 정의
2. 구체적 예시
3. 기술적 정의 (선택)

**예시**:
```
API는 뭘까요?

1. 일상 언어: 프로그램들끼리 대화하는 통로
2. 예시: 배달앱이 식당에 주문 전달하는 것
3. 기술적: Application Programming Interface (선택)
```

### 기법 2: 점진적 복잡도

**쉬운 표현 → 정확한 표현으로 전환**:
```
처음: "AI를 내 컴퓨터에서 쓰는 거예요"
↓
중간: "AI를 내 컴퓨터에 설치해서 파일과 연결하는 거예요"
↓
나중: "LLM을 로컬 환경에 설치하고 파일 시스템과 통합하는 거예요"
```

### 기법 3: 질문 유도

**독자가 스스로 깨닫게**:
```
Before:
"로컬 설치와 웹 UI는 다릅니다."

After:
"웹사이트에서 쓰는 거랑 뭐가 다를까요?
핵심은 딱 하나입니다.
AI가 내 컴퓨터의 파일을 직접 읽을 수 있다는 것."
```

---

## ✅ Quality Checklist

개선 완료 후 체크:

### 이해도 검증
- [ ] 중학생도 이해 가능한 수준
- [ ] 전문 용어 0개 (또는 모두 설명됨)
- [ ] 비유가 적절하고 정확함
- [ ] 원래 의미 95% 이상 유지

### 문장 품질
- [ ] 자연스러운 한국어
- [ ] 괄호 설명이 어색하지 않음
- [ ] 문장 길이 적절 (20-30자)
- [ ] 읽기 쉬운 흐름

### 구조 품질
- [ ] 비교표가 명확함
- [ ] 단계별 설명이 논리적
- [ ] 예시가 구체적
- [ ] 시각적 요소 적절

---

## 📌 Important Notes

### 주의사항

1. **과도한 단순화 금지**
   - ❌ "AI는 똑똑한 로봇이에요"
   - ✅ "AI는 대량의 데이터로 학습한 소프트웨어예요"

2. **유치한 비유 피하기**
   - ❌ "AI는 아기처럼 배워요"
   - ✅ "AI는 신입사원처럼 훈련이 필요해요"

3. **정확성 최우선**
   - 쉽게 만들려다 의미 왜곡하지 않기
   - 불확실하면 원문 유지

### 용어 사용 가이드

**사용 가능한 기술 용어**:
- 웹사이트, 프로그램, 앱, 파일, 폴더
- 설치, 실행, 클릭, 입력
- 인터넷, 브라우저, 컴퓨터

**설명 필요한 기술 용어**:
- AI/ML 관련 (LLM, 프롬프트, 토큰)
- 개발 도구 (IDE, CLI, Git)
- 프로그래밍 (함수, 객체, API)
- 인프라 (클라우드, 서버, 로컬)

---

**Version**: v1.0
**Last Updated**: 2025-01-10
**Target Audience**: 비개발자 (개발 지식 제로)
**Goal**: 이해도 95% 유지하며 접근성 극대화