강의 자료 생성 가이드라인

이 문서는 패스트캠퍼스 AI 에이전트 강의 시리즈의 강의 자료(Markdown 파일)를 작성할 때 따라야 할 표준 가이드라인입니다.

목적: Part1~3의 기존 강의 자료를 분석하여 도출한 공통 패턴과 구조를 체계화하여, 일관되고 고품질의 교육 콘텐츠를 생성할 수 있도록 합니다.

📁 파일 구조 및 명명 규칙

디렉토리 구조

PartN_주제명/
├── ChapterN_세부주제/
│   ├── README.md (선택)
│   ├── Clip1_제목.md
│   ├── Clip2_제목.md
│   └── ...

파일명 규칙

형식: ClipN_제목.md
- N: 1부터 시작하는 순차 번호
- 제목: 한글로 작성, 언더스코어(_)로 구분
예시:
- ✅ Clip1_Vector_Search_이해하기.md
- ✅ Clip3_PRD_프롬프트_만들기.md
- ❌ clip-1-vector-search.md (소문자, 하이픈 사용 X)

📄 문서 구조 템플릿

기본 구조

markdown

# Clip N: 제목

## 학습 목표
- 목표 1 (동사형으로 작성)
- 목표 2
- 목표 3

## 1. 개념/주제 섹션
내용...

## 2. 실습/예제 섹션
내용...

## 핵심 요약 (선택)
요약...

## 참고 자료
- 링크 1
- 링크 2

✍️ 작성 스타일 가이드

1. 제목 구조

문서 최상위 제목 (H1)

markdown

# Clip N: 제목

항상 Clip N:으로 시작
콜론(😃 뒤에 공백 한 칸
숫자는 아라비아 숫자 사용

주요 섹션 제목 (H2)

markdown

## 학습 목표
## 1. Vector Search란?
## 2. 핵심 구성 요소

이모지 사용 가능: ## 📋 학습 개요, ## 🗂️ STEP 1:
숫자 섹션: ## 1., ## 2. 형식 (점 포함)

하위 섹션 제목 (H3)

markdown

### 1.1 기본 개념
### 설치 방법 선택

2. 학습 목표 섹션 (필수)

형식 1: 기본 형식

markdown

## 학습 목표
- 개념을 이해할 수 있다
- 방법을 습득할 수 있다
- 차이점을 파악할 수 있다

형식 2: 이모지 활용

markdown

## 📋 학습 개요

### 🎯 학습 목표
- 목표 1
- 목표 2

작성 원칙:

2~5개의 명확한 학습 목표 제시
"~이해하기", "~습득하기", "~파악하기" 등 동사형 종결
불릿 포인트(-)로 나열
구체적이고 측정 가능하게 작성

3. 본문 작성 원칙

A. 개념 설명

명확한 정의 제공:

markdown

### RAG란 무엇인가?

**RAG(Retrieval Augmented Generation)**는 검색 시스템이 붙어 있는 Generation을 의미합니다.

더 근본적으로 표현하면:
> LLM이 정확하게 알지 못하는 정보를 제공하여 내가 원하는 대로 동작하게 시키는 것

작성 포인트:

첫 문장에서 정의를 명확히
굵은 글씨(text)로 핵심 용어 강조
인용구(>)로 중요 개념 강조

B. 비교 및 대조

표(Table) 활용:

markdown

| 구분 | 키워드 검색 | Vector Search |
|------|------------|---------------|
| 검색 방식 | 정확한 키워드 매칭 | 의미적 유사도 |
| 데이터 표현 | 텍스트 그대로 | 고차원 벡터 |

좋은 예/나쁜 예 구분:

markdown

**흔한 오해:**
- ❌ RAG = 벡터 검색을 반드시 해야 한다
- ❌ RAG는 항상 임베딩과 벡터 DB가 필요하다

**실제 RAG:**
- ✅ 벡터 검색 이외의 검색 시스템도 RAG입니다
- ✅ SQL 쿼리를 통한 검색 + Generation도 RAG입니다

4. 시각적 요소 활용

A. Mermaid 다이어그램 (적극 권장)

플로우차트:

markdown

```mermaid
graph LR
    A[사용자 질문] --> B[쿼리 임베딩]
    B --> C[Vector Store 검색]
    C --> D[관련 문서 추출]
    D --> E[LLM + 문서]
    E --> F[최종 답변]


**의사결정 플로우:**
```markdown
```mermaid
graph TD
    Start[프로젝트 시작] --> Q1{작업 단계를<br/>미리 정의할<br/>수 있는가?}
    Q1 -->|예| Q2{단계가<br/>항상 동일한<br/>순서인가?}
    Q1 -->|아니오| Agent[Agent 사용]


**다이어그램 작성 원칙:**
- 복잡한 개념이나 프로세스는 반드시 시각화
- 한글 레이블 사용
- 스타일링으로 가독성 향상 (`style A fill:#e1f5ff`)

#### B. 이모지 활용

**섹션 제목:**
- 📋 학습 개요
- 🎯 학습 목표
- 🗂️ STEP
- 📱 단계
- 💡 팁

**강조 표시:**
- ✅ 올바른 방법
- ❌ 잘못된 방법
- ⚠️ 주의사항
- 🚨 위험/중요
- 💬 대화/메시지
- 🔧 도구/툴 사용

---

### 5. 코드 예제 작성

#### Python 코드 블록
```markdown
```python
from openai import OpenAI

client = OpenAI()

def call_openai():
    """OpenAI API 호출 예시"""
    try:
        response = client.chat.completions.create(
            model="gpt-5-mini",
            messages=[
                {"role": "system", "content": "당신은 친절한 AI입니다."},
                {"role": "user", "content": "안녕하세요"}
            ]
        )
        return response.choices[0].message.content
    except Exception as error:
        print(f"오류: {error}")


**코드 작성 원칙:**
- 실행 가능한 완전한 코드 제공
- 주석으로 설명 추가
- 에러 핸들링 포함
- 변수명은 의미 있게 작성

#### 터미널 명령어
```markdown
```bash
# 설치
npm install -g @anthropic-ai/claude-code

# 실행
claude

# 설정 확인
claude --version


---

### 6. 실습 및 예제

#### 단계별 실습 구조
```markdown
## 실습: 여러 MCP를 동시에 활용해보기

### 1. 준비: 사용 가능한 MCP 확인

Claude Code를 실행하면...

### 2. 실제 동작 예시: YouTube + Linear + Slack

다음은 실제로...

```bash
User: "최대한 많은 MCP를 사용해봐"

Claude Code의 동작:
🔍 Step 1: 사용 가능한 MCP Tool 확인
✅ Result: ...


**실습 작성 원칙:**
- 명확한 단계 번호 부여
- 각 단계마다 예상 결과 표시
- 실제 터미널 출력 예시 제공
- 트러블슈팅 팁 포함 (선택)

---

### 7. 바이브코딩 프롬프트 섹션

**PRD 프롬프트 예시:**
```markdown
## PRD 작성 전략

### 2. PRD 프롬프트

스펙:

Python, uv 패키지 매니저
Neon PostgreSQL (pgvector, pg_search 확장)
OpenAI text-embedding-3-small

데이터베이스:

Neon MCP 사용
프로젝트: nonghyup-loan
테이블: loan_products

핵심 기능:

hybrid_search(): RRF로 vector, bm25 search 결합
- https://docs.paradedb.com/documentation/guides/hybrid 참고

CLI 동작: uv run python ... "의사 전용 대출"

작성 원칙:

실제 사용할 프롬프트를 코드 블록으로 제공
간결하지만 필요한 모든 정보 포함
참고 링크 명시
사용 방법과 예상 결과 함께 제시

8. 출처 및 참고 자료

문서 마지막에 배치:

markdown

## 참고 자료

### 공식 문서
- [Claude Code 개요](https://docs.claude.com/ko/docs/claude-code/overview)
- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)

### 관련 기술
- pgvector GitHub: https://github.com/pgvector/pgvector
- OpenAI Embeddings: https://platform.openai.com/docs/guides/embeddings

### 추가 학습
- [Elastic - 벡터 검색 가이드](https://www.elastic.co/kr/what-is/vector-search)

작성 원칙:

모든 외부 자료는 출처 명확히 표기
링크는 반드시 검증된 URL 사용
카테고리별로 분류 (공식 문서, 관련 기술, 추가 학습)
본문에서 참조한 자료는 반드시 포함

🎨 스타일 가이드

강조 및 서식

굵은 글씨 (Bold):

핵심 용어 첫 등장 시: **RAG(Retrieval Augmented Generation)**
중요 개념: **주의**: 이 작업은...

인용구 (Blockquote):

markdown

> "LLM 분야에서의 성공은 가장 정교한 시스템을 구축하는 것이 아닙니다."
> — Anthropic

코드 인라인:

명령어, 파일명, 함수명: `claude`, `pgvector`, `hybrid_search()`

리스트:

불릿 포인트: - 사용 (일관성)
순서 리스트: 1., 2. (점 포함)
중첩 시 2칸 들여쓰기

📝 작성 프로세스

1. 사전 준비

[ ] 강의 커리큘럼(lecture_prompt.md) 확인
[ ] 해당 Clip의 학습 목표 파악
[ ] 필요한 참고 자료 수집
[ ] 코드 예제 테스트

2. 초안 작성

[ ] 제목 및 학습 목표 작성
[ ] 본문 개념 설명 (이론)
[ ] 실습/예제 작성 (실전)
[ ] 다이어그램 추가
[ ] 코드 예제 검증

3. 검토 및 수정

[ ] 학습 목표와 내용 일치 여부 확인
[ ] 코드 예제 실행 가능 여부 테스트
[ ] 링크 유효성 검증
[ ] 한글 인코딩 확인 (깨짐 방지)
[ ] 마크다운 문법 검증

4. 최종 확인

[ ] 200줄 이하 권장 (필요시 초과 가능)
[ ] 시각적 요소 충분히 활용했는지
[ ] 바이브코딩 프롬프트 포함 여부
[ ] 참고 자료 출처 명시 확인

⚠️ 주의사항

필수 준수 사항

한글 인코딩: UTF-8 인코딩 사용, 파일 저장 후 깨짐 확인
코드는 요청 시에만: 강의 자료 작성 요청에 실제 코드 작성은 포함되지 않음
출처 명시: 웹에서 가져온 내용은 반드시 링크 포함
다음 클립 예고 금지: "다음 클립에서는..." 형태 문구 사용하지 않기
바이브코딩 프롬프트: 사람이 실제로 입력할 정도로 간결하게 작성

지양할 패턴

❌ 지나치게 긴 문서 (500줄 이상)
❌ 이론만 나열하고 예제 없음
❌ 검증되지 않은 코드 예제
❌ 깨진 링크 또는 출처 없는 인용
❌ 모호하거나 추상적인 설명

권장 패턴

✅ 개념 → 예제 → 실습 흐름
✅ 다이어그램으로 복잡한 개념 시각화
✅ 실행 가능한 완전한 코드 제공
✅ 바이브코딩 실습 포함
✅ 명확한 학습 목표와 요약

🔍 품질 체크리스트

작성 완료 후 다음 항목을 확인하세요:

구조

[ ] 제목 형식: # Clip N: 제목
[ ] 학습 목표 섹션 존재
[ ] 명확한 섹션 구분 (H2, H3)
[ ] 참고 자료 섹션 포함

내용

[ ] 핵심 개념 정의 명확
[ ] 실습/예제 포함
[ ] 바이브코딩 프롬프트 제공
[ ] 코드 예제 실행 가능

시각화

[ ] Mermaid 다이어그램 (복잡한 개념)
[ ] 표(Table) 활용 (비교/대조)
[ ] 이모지 적절히 사용
[ ] 코드 블록 문법 강조

품질

[ ] 한글 인코딩 정상
[ ] 링크 유효성 검증
[ ] 출처 명시 확인
[ ] 오타 및 문법 검토

📚 참고: 우수 사례

이론 설명 우수 사례

Part2/Chapter1/Clip1 - Agent vs Workflow:

명확한 정의와 비교표
의사결정 플로우차트
하이브리드 접근 방식 설명

실습 우수 사례

Part3/Chapter1/Clip3 - PRD 프롬프트 만들기:

실제 사용 가능한 PRD 프롬프트
명확한 스펙 정의
체크리스트 제공

시각화 우수 사례

Part3/Chapter2/Clip1 - RAG 개념 이해하기:

복잡한 워크플로우 다이어그램
상태 변화 시각화
단계별 State 예시

📞 문의 및 개선

이 가이드라인은 강의 자료의 품질과 일관성을 유지하기 위한 기준입니다.

새로운 패턴 발견 시: 가이드라인 업데이트 제안
불명확한 부분: .claude/lecture_prompt.md 참조
기술적 문의: Claude Code에게 질문

마지막 업데이트: 2025-10-16 버전: 1.0 기반 분석: Part1~3 총 9개 대표 클립 분석

농협 대출 상품 Hybrid Search

농협 대출 상담 Agent

Seoul Cultural Events MCP Server

.claude

commands

template

강의 커리큘럼

.claude

文档

part-4.-mcp-server

chapter-3.-db-mcp-server

Part1_AI_에이전트와_Claude_Code_기초

Part2_Agent_개념과_아키텍처

Part3_바이브코딩으로_Hybrid_Search_RAG_구현하기

Part4_바이브코딩으로_MCP_server_구현하기

Part6_바이브코딩과_AI_agent_best_practice

Part1_AI_에이전트와_Claude_Code_기초

Part2_Agent_개념과_아키텍처

Part3_바이브코딩으로_Hybrid_Search_RAG_구현하기

Part4_바이브코딩으로_MCP_server_구현하기

Part6_바이브코딩과_AI_agent_best_practice

Korea Data.go.kr MCP Servers

.claude

commands

subagents

文档

源码

NPS Business Enrollment MCP Server

template

강의 자료 생성 가이드라인 ​

📁 파일 구조 및 명명 규칙 ​

디렉토리 구조 ​

파일명 규칙 ​

📄 문서 구조 템플릿 ​

기본 구조 ​

✍️ 작성 스타일 가이드 ​

1. 제목 구조 ​

문서 최상위 제목 (H1) ​

주요 섹션 제목 (H2) ​

하위 섹션 제목 (H3) ​

2. 학습 목표 섹션 (필수) ​

3. 본문 작성 원칙 ​

A. 개념 설명 ​

B. 비교 및 대조 ​

4. 시각적 요소 활용 ​

A. Mermaid 다이어그램 (적극 권장) ​

8. 출처 및 참고 자료 ​

🎨 스타일 가이드 ​

강조 및 서식 ​

📝 작성 프로세스 ​

1. 사전 준비 ​

2. 초안 작성 ​

3. 검토 및 수정 ​

4. 최종 확인 ​

⚠️ 주의사항 ​

필수 준수 사항 ​

지양할 패턴 ​

권장 패턴 ​

🔍 품질 체크리스트 ​

구조 ​

내용 ​

시각화 ​

품질 ​

📚 참고: 우수 사례 ​

이론 설명 우수 사례 ​

실습 우수 사례 ​

시각화 우수 사례 ​

📞 문의 및 개선 ​

강의 자료 생성 가이드라인

📁 파일 구조 및 명명 규칙

디렉토리 구조

파일명 규칙

📄 문서 구조 템플릿

기본 구조

✍️ 작성 스타일 가이드

1. 제목 구조

문서 최상위 제목 (H1)

주요 섹션 제목 (H2)

하위 섹션 제목 (H3)

2. 학습 목표 섹션 (필수)

3. 본문 작성 원칙

A. 개념 설명

B. 비교 및 대조

4. 시각적 요소 활용

A. Mermaid 다이어그램 (적극 권장)

8. 출처 및 참고 자료

🎨 스타일 가이드

강조 및 서식

📝 작성 프로세스

1. 사전 준비

2. 초안 작성

3. 검토 및 수정

4. 최종 확인

⚠️ 주의사항

필수 준수 사항

지양할 패턴

권장 패턴

🔍 품질 체크리스트

구조

내용

시각화

품질

📚 참고: 우수 사례

이론 설명 우수 사례

실습 우수 사례

시각화 우수 사례

📞 문의 및 개선