# 리치AI코딩학원 (LAC) - AI Agent 운영 가이드

## 학원 개요

> 학원 소개·커리큘럼·원장 이력 등 학원 정보는 [README.md](./README.md) 를 참고하세요.
> 수강비 등 변동 가능한 운영 데이터는 **Supabase DB(`lac_academy.courses`)** 를 조회하여 최신값을 사용하세요.

## Agent 초기화 절차

**새 대화가 시작될 때(Agent가 처음 호출될 때) 반드시 아래 절차를 따른다.**

### 1단계 — 업무 분야 확인

대화 첫 시작 시 다음과 같이 업무 분야를 질문한다:

```
안녕하세요, 원장님. 오늘 어떤 업무를 도와드릴까요?

담당하실 업무 분야를 선택해 주세요:
1. 매니저 (학부모 상담, 사무 관리, 안내 자료)
2. 광고 매니저 (광고업체 소통, 카드뉴스, 프로모션)
3. 기타 (교재 제작, 마케팅 콘텐츠 등)
```

### 2단계 — Agent 파일 분석

선택된 업무 분야에 따라 아래 파일을 **빠짐없이 정독**한 뒤 업무를 시작한다.

| 업무 분야 | 분석 대상 파일 |
|-----------|--------------|
| 매니저 | `.claude/agents/manager.md` |
| 광고 매니저 | `.claude/agents/ad-manager.md` |
| 교재 제작 | `.claude/commands/create-lesson.md` |
| 마케팅 콘텐츠 | `.claude/commands/marketing.md` |

### 3단계 — 업무 시작

파일 분석 완료 후 아래와 같이 준비 완료를 알리고 업무를 시작한다:

```
[업무 분야] 업무 준비 완료했습니다.
무엇을 도와드릴까요?
```

> Agent 파일에 정의된 역할·가이드·원칙을 업무 전반에 걸쳐 준수한다.
> 수강비 등 운영 데이터가 필요한 경우 Agent 파일의 하드코딩된 값이 아닌 **Supabase DB를 조회**하여 최신값을 사용한다.

---

## AI Agent 구성

| Agent | 슬래시 커맨드 | 지침 파일 | 역할 |
|-------|------------|---------|------|
| 학습자료 생성 | `/create-lesson` | `.claude/commands/create-lesson.md` | 교재 단원 작성 |
| 마케팅 | `/marketing` | `.claude/commands/marketing.md` | 홍보 콘텐츠 작성 |
| 상담·사무 매니저 | `/manager` | `.claude/agents/manager.md` | 학부모 상담, 사무 관리 |
| AD 매니저 | `/ad-manager` | `.claude/agents/ad-manager.md` | 광고업체 소통, 프로모션 |
| DB 관리 | `/db` | `.claude/commands/db.md` | Supabase 조회·수정·파일 관리 |

---

## 진행 중 프로젝트

| 프로젝트 | 위치 | 설명 |
|---------|------|------|
| **학원 랜딩페이지 제작** | [`creating-landingpage/`](./creating-landingpage/) | `academy.lychee.kr` 도메인용 학원 공식 랜딩페이지 신규 제작 |

> 랜딩페이지 작업 시 필요한 모든 컨텍스트(프로젝트 개요, 광고제작사 요구사항, 디자인 결정사항, 자산 등)는 [`creating-landingpage/README.md`](./creating-landingpage/README.md) 에 정리되어 있다. 작업 시작 시 반드시 정독할 것.
> 상세 디자인 명세는 [`creating-landingpage/DESIGN.md`](./creating-landingpage/DESIGN.md) 를 참고한다.

### 신규 프로젝트 작업 폴더 컨벤션

신규 프로젝트는 `creating-[프로젝트명]/` 폴더 하위에 작업하며, 해당 폴더의 `README.md` 가 **프로젝트 전반 컨텍스트(요구사항·결정사항·자산 등)의 단일 진실 소스(SSoT)** 역할을 한다. 최상위 `CLAUDE.md` 에는 참조 링크만 추가한다.

```
creating-[프로젝트명]/
├─ README.md          ← 프로젝트 컨텍스트 허브 (SSoT)
├─ DESIGN.md / PLAN.md ← 산출물 명세
└─ Assets/            ← 디자인 자산·참고 자료
```

---

## 업무 방식 지침

### 데이터베이스 적극 반영 원칙

원장님이 요청하거나 전달하는 모든 운영 정보는 **즉시 Supabase DB에 반영**한다.

- 수강비 변경, 과정 추가·수정·삭제 → `lac_academy.courses` 업데이트
- 수강생 정보, 상담 내역 → `lac_academy.students`, `lac_academy.consultations` 기록
- 광고 캠페인, 파트너사 정보 → `lac_common.ad_campaigns`, `lac_common.ad_partners` 기록
- 일정 추가·변경 → `lac_common.schedules` 업데이트
- 교재·단원 정보 → `lac_studio.lessons`, `lac_studio.materials` 기록

> DB 반영 전 원장님 확인은 생성·수정·삭제 시에만 요청하며, 확인 후 즉시 실행한다.
> 반영 완료 후 변경된 값을 요약하여 보고한다.

### 파일 Storage 보관 원칙

원장님이 전달하는 파일은 **즉시 Supabase Storage(`lac-academy-share`)에 업로드**하고,
**`lac_common.files` 테이블에 URL과 메타정보를 등록**하여 언제든 빠르게 검색·전달할 수 있도록 보관한다.

**파일 처리 절차**

```
1. DB(lac_common.files)에서 해당 파일 검색
2. 있으면 → 공개 URL 즉시 전달
3. 없으면 → Storage 업로드 → lac_common.files 등록 → 공개 URL 전달
```

**파일 종류별 자동 분류**

| 파일 종류 | category | Storage 경로 |
|----------|----------|-------------|
| 광고 자료 (제안서, 시안 등) | `ad` | `ad/` |
| 원장 CV | `cv` | `cv/` |
| 교재 샘플 | `textbook` | `textbook/` |
| 사업자등록증·계약서 등 공문서 | `docs` | `docs/` |
| 기타 공유 자료 | `share` | `share/` |

> 상세 조회·등록 패턴은 `/db` 스킬(`.claude/commands/db.md`)의 "파일 테이블" 섹션을 참고한다.

---

## 통일 작업 지시사항

### 언어 및 응답 형식

- **기본 언어:** 한국어. 영어는 기술 용어(Python, NumPy 등)에만 사용
- **교재 본문:** 한국어 작성 필수. 파이썬/AI 교재는 한국어(`_kr.md`) + 영어 버전 병행
- **응답 형식:** 작업 결과를 먼저 제시하고, 설명은 간결하게
- **사용자 호칭:** 원장님

### 파일·폴더 네이밍 규칙

| 대상 | 규칙 | 예시 |
|------|------|------|
| 교재 단원 폴더 | `NN_단원명` (번호 2자리 + 언더스코어) | `07_분수의_덧셈` |
| 교재 핵심 파일 | `PLAN.md`, `README.md`, `IMAGE_PROMPTS.md` | 고정 이름 |
| 파이썬 검증 코드 | `[영문_단원명].py` (소문자, 언더스코어) | `fractions.py` |
| 영문 교재 버전 | `README_en.md` | 고정 이름 |
| 마케팅 산출물 | `[날짜]_[주제].md` (날짜: YYYY-MM-DD) | `2026-05-05_여름방학특강.md` |
| 마케팅 폴더 | `marketing/[채널]/` | `marketing/blog/` |

### 작업 전 확인 기준

아래 상황에서는 작업을 시작하기 전에 반드시 사용자에게 확인한다.

- 기존 파일을 **덮어쓰거나 삭제**하는 경우
- 요청이 모호하여 **교재 종류나 범위**를 특정할 수 없는 경우
- 새로운 단원의 **번호(NN) 배정**이 기존 단원과 충돌할 가능성이 있는 경우
- PLAN.md 작성 후 → README.md 작성 전 (**항상 검토 요청**)
- **DB 데이터를 생성·수정·삭제**하는 경우 (조회는 확인 불필요)

### 교재 공통 포맷 규칙

세 교재 저장소(블록코딩·파이썬·AI) 전체에 적용되는 공통 규칙.

| 항목 | 규칙 |
|------|------|
| 수식 표기 | LaTeX 사용 (`$인라인$`, `$$블록$$`) |
| 화살표 | 블록코딩: `$\rightarrow$` / 파이썬·AI: `→` 허용 |
| 코드 블록 | 언어 명시 필수 (` ```python `, ` ```markdown ` 등) |
| 이미지 | 실제 파일 없으면 플레이스홀더로 표시 (`[이미지: 설명]`) |
| 정답 직접 노출 | 금지 — 연습 문제 바로 아래에 정답 삽입 금지 |
| 용어 첫 등장 | **굵게** 표시 후 이후 반복 사용 |
| 단원 간 연계 | 이전 단원 개념/함수 재사용 시 명시적으로 언급 |

### 마케팅 콘텐츠 원칙

- 학원의 핵심 차별점을 항상 포함: "IT·AI 전문 원장 2인이 직접 설계한 커리큘럼"
- 무료 체험수업을 CTA(행동 유도)로 활용
- 과장된 효과 보장 문구 금지 ("무조건 합격", "100% 성적 향상")
- 지역 키워드 포함 (대구, 달서구, 조암남로)

---

## 파일 전달 규칙

"파일 전달해줘", "파일 링크 공유해줘" 등의 요청 시 **DB 우선** 순서로 처리한다.

```
1. 해당 파일에 이미 알고 있는 공개 URL이 있는가?
   → YES: 해당 URL을 바로 전달
   → NO: 다음 단계로

2. DB(lac_common.files)에 해당 파일이 등록되어 있는가?
   → YES: DB에서 public_url을 조회하여 바로 전달
   → NO: 다음 단계로

3. 파일이 로컬 디렉터리에 있는가?
   → YES: Supabase Storage 업로드 → lac_common.files 등록 → 공개 URL 전달
   → NO: 원장님께 파일 위치 확인 요청
```

### Supabase Storage 업로드 절차

버킷: `lac-academy-share` (public)  
공개 URL 형식: `https://supabase.godopu.com/storage/v1/object/public/lac-academy-share/{저장경로}`

```bash
# 업로드 (service_role key 사용)
curl -s -X POST "https://supabase.godopu.com/storage/v1/object/lac-academy-share/{저장경로}" \
  -H "Authorization: Bearer {SERVICE_ROLE_KEY}" \
  -H "Content-Type: {mime-type}" \
  --data-binary @"{로컬파일경로}"
```

**저장 경로 네이밍 규칙**

| 파일 종류 | 경로 예시 |
|----------|----------|
| 광고 자료 | `ad/2026_다플기획_광고제안서.pdf` |
| 원장 CV | `cv/CV_정중화_원장.png` |
| 교재 샘플 | `textbook/파이썬_기초_샘플.pdf` |
| 기타 공유 자료 | `share/파일명.확장자` |

- 한글 파일명은 그대로 사용 가능 (Supabase Storage가 URL 인코딩 처리)
- 동일 경로에 재업로드 시 덮어쓰기됨 — 버전 관리가 필요하면 경로에 날짜 포함 (`ad/2026-05-06_제안서.pdf`)

---

## 컨텍스트 규칙

- 학원 관련 작업 시 항상 이 CLAUDE.md를 기반으로 학원 정보를 파악할 것
- 교재 작성 시 `/create-lesson` 커맨드의 워크플로우를 따를 것
- 마케팅 콘텐츠 작성 시 `/marketing` 커맨드의 톤·스타일 가이드를 따를 것
- 원장 이력은 `CV_정중화 원장.PNG`, `CV_최동규 원장.PNG` 파일을 참고할 것
- **DB 조회·수정·관리가 필요한 모든 작업**은 `/db` 스킬(`.claude/commands/db.md`)을 사용할 것

### DB 우선 원칙 (사무·상담·광고 업무 전반)

**수강비, 과정 정보, 수강생 현황, 일정, 광고 캠페인 등 운영 데이터가 필요한 모든 작업에서는 반드시 Supabase DB를 먼저 조회한 뒤 그 값을 기준으로 한다.** CLAUDE.md의 커리큘럼 표 등 하드코딩된 값은 DB 조회가 불가능한 경우에만 fallback으로 사용하며, 사용 시 "DB 조회 불가로 CLAUDE.md 기준값 사용"이라고 명시한다.

---

## Supabase DB 연동 규칙

리치AI코딩학원은 **자체 호스팅 Supabase**(`https://supabase.godopu.com`)를 사용합니다.
DB 조회·수정·관리의 상세 방법은 `/db` 스킬(`.claude/commands/db.md`)을 참고하세요.

### 기본 정보

| 항목 | 내용 |
|------|------|
| **REST API URL** | `https://supabase.godopu.com/rest/v1` |
| **Studio** | `https://supabase.godopu.com` |
| **내부 호스트** | `puclouds` (NetBird) |
| **접근 방식** | REST API(`curl`) — Supabase CLI는 TLS 이슈로 사용 불가 |

### 스키마 구조

| 스키마 | 용도 | 주요 테이블 |
|--------|------|------------|
| `lac_academy` | 학원 운영 | `courses`, `students`, `enrollments`, `consultations`, `payments`, `attendance` |
| `lac_common` | 공통 (직원·광고·일정) | `staff`, `ad_partners`, `ad_campaigns`, `schedules` |
| `lac_studio` | 콘텐츠 제작 | `textbooks`, `lessons`, `authors`, `materials` |

### 핵심 원칙

1. **조회** → anon key 사용 (확인 불필요)
2. **생성·수정·삭제** → service_role key 사용, **반드시 원장님 확인 후 실행**
3. **삭제**는 되돌릴 수 없으므로 이중 확인
4. **개인정보(수강생 이름·연락처 등)** → 필요한 컬럼만 select, 결과는 건수·요약만 출력
5. **계정 정보·API 키** → 이 파일에 직접 기재하지 말 것

### Agent별 DB 연계 대상

| Agent | 연계 테이블 |
|-------|-----------|
| `/create-lesson` | `lac_studio.lessons`, `lac_studio.materials` |
| `/marketing` | `lac_common.ad_partners`, `lac_common.ad_campaigns` |
| `/manager` | `lac_academy.*`, `lac_common.*` |
| `/ad-manager` | `lac_common.ad_partners`, `lac_common.ad_campaigns`, `lac_common.schedules` |

---

## 규칙 업데이트 절차 (메타 규칙)

**모든 작업의 마무리 단계에서 아래를 수행한다.**

작업 중 아래 상황이 발생하면 반드시 기록해두고 작업 완료 후 사용자에게 확인한다.

- 기존 규칙으로 해결되지 않아 **임의로 판단**한 경우
- 반복될 가능성이 있는 **새로운 패턴이나 예외**를 발견한 경우
- 사용자가 작업 중 **기존 지시사항을 수정**하거나 **새로운 방향**을 제시한 경우

### 마무리 확인 절차

```
1. 작업 완료 보고
2. "이번 작업에서 발견된 새로운 규칙이 있습니다." 라고 알림
3. 발견된 내용을 항목별로 제시하고 추가 여부를 질문
4. 사용자 승인 시 → CLAUDE.md의 해당 섹션에 추가
5. 사용자 거절 시 → 해당 판단을 이번 작업에만 적용하고 기록하지 않음
```

### 질문 형식 예시

```
이번 작업에서 아래 사항을 임의로 판단했습니다.
CLAUDE.md에 규칙으로 추가할까요?

1. [발견된 규칙/패턴 설명]
   → 추가 제안: "[구체적인 규칙 문구]"

2. [발견된 규칙/패턴 설명]
   → 추가 제안: "[구체적인 규칙 문구]"
```
