960개 대본 전체의 일관된 목소리를 위한 규약. LECTURE-TEMPLATE.md와 짝을 이룹니다.
강사 페르소나: 10년 차 풀스택/AI 엔지니어. 비개발자 친구에게 점심 먹으며 설명하는 톤. 현학적 X, 권위적 X, 안심·격려 중심.
청자 페르소나: 두 명을 동시에 상상한다.
- 비개발자(40대 마케터, 터미널 처음)
- 중급 개발자(2년 차, 새 영역 학습 중)
→ 본문은 비개발자 톤, 마지막 👨💻 개발자 노트 박스에서 중급 개발자 만족시킴.
| 항목 | 규칙 |
|---|---|
| 한 문장 길이 | 100자 이하 (예외 5% 허용) |
| 한 문단 길이 | 5 |
| 어미 | "~예요/이에요/합니다" 혼용 OK, 단 한 문단 안에서는 통일 |
| 1인칭 | "우리", "여러분과 같이", "저는" 사용 |
| 명령조 | "~하세요"는 ▶ 같이 쳐보기 박스에서만 |
- "같이 해봅시다", "한 번 보세요", "괜찮아요"
- "이걸 우리말로 풀면", "비유하자면"
- "안 되어도 돼요", "다시 해봐요"
- "여기까지 따라오시느라 수고하셨어요"
- "당연히", "쉽잖아요", "다들 아시겠지만", "상식적으로"
- "단순히", "그냥", "별거 아니에요" (실제로 별거임)
- "원래 그래요" (이유 설명으로 대체)
- 영어 약자 단독 사용 (
CRUD→ "C·R·U·D는 만들고·읽고·바꾸고·지우는 거예요")
{한국어 풀이} ({약자/영어}, "{한글 발음}")
예: "API (에이피아이)는 프로그램 사이의 약속 같은 거예요" 예: "OAuth (오어쓰)는 다른 사이트의 로그인을 빌려 쓰는 방법이에요"
> ▶ **같이 쳐보기** — {짧은 한 줄 설명, 무엇을 왜}
>
> ```bash
> {명령}
> ```- 본문 중 3개 이상 등장
- 명령은 1~5줄 권장 (긴 스크립트는 별도 파일 링크)
- 모든 명령은
chapters/NNN/start/또는finish/에서 동작 검증됨
## 👨💻 개발자 노트 (참고 — 비개발자는 그냥 넘기셔도 됩니다)
> - {정확한 파일 경로, 함수명, 트레이드오프 1}
> - {디자인 결정 이유 1}
> - {실무 베스트 프랙티스 1}
> - {디버깅 팁 1}
> - {참고 링크 / 다음 학습 1}- 5개 항목 이상
- 본문에서 일부러 단순화한 부분의 정확한 설명
- 파일 경로·함수명은 실제 코드와 일치 (relative link 권장)
> ⚠️ **흔한 실수**
> {실수} → {증상} → {해결}지난 시간(H{N-8})에서 우리가 {배운 것}을 봤죠.
오늘은 그걸 가지고 {오늘 할 일}을 해볼 거예요.
다음 챕터(Ch {N+1})에서는 {다음 주제} 를 할 거예요.
오늘 만든 {산출물}이 다음 시간에 {어떻게 쓰이는지} 보여드릴게요.
같은 개념은 항상 같은 비유로 부른다. 새 비유 도입 시 사전 등록.
| 개념 | 비유 |
|---|---|
| 터미널 | 카카오톡 채팅창 (컴퓨터와 채팅) |
| Docker 컨테이너 | 호텔 객실 / 사무실 칸막이 공방 |
| 데이터베이스 | 회사 캐비닛 |
| 인덱스 | 책 뒤의 색인 페이지 |
| API | 배달 앱 (요청 → 응답) |
| OAuth | 다른 회사 사원증으로 우리 카페 입장 |
| JWT | 위조 방지 도장 찍힌 출입증 |
| LLM | 책 백만 권 읽은 신입 비서 |
| Agent | 행동까지 하는 AI 비서 |
| MCP | AI 비서와 회사 도구를 잇는 표준 콘센트 |
| RAG | 책장에서 책 찾아 와서 답변 만들기 |
| 벡터DB | 의미가 비슷한 것끼리 모아둔 책꽂이 |
| AWS Region | 나라(한국 지점/도쿄 지점) |
| AWS AZ | 같은 도시 안 다른 건물 |
| IAM | 회사 출입증 + 권한 카드 |
| VPC | 우리 회사 빌딩 (외부와 분리된) |
| Auto Scaling | 손님 많을 때 직원 더 부르기 |
| CDN | 동네 편의점에 미리 갖다 둔 재고 |
| 멱등성 | 야무진 친구 (두 번 부탁해도 같은 결과) |
| Git commit | 게임 세이브 포인트 |
| Git branch | 평행우주 |
| CI/CD | 컨베이어 벨트 자동 검수+배송 |
→ 새 비유 추가 시 이 표 업데이트 PR.
- 비밀번호/토큰: 본문 코드 블록은 항상
<YOUR_TOKEN>형식 - API Key 노출 사고 사례 언급 시: 회사명 익명화
- AI 환각 가능성: "AI가 틀릴 수 있어요. 사람이 한 번 봐주세요" 안전 멘트 필수 (S7 챕터)
- Python: PEP 8, 타입힌트 권장 (S2 Ch 20 이후 챕터)
- TypeScript: strict 모드 가정
- Bash:
set -euo pipefail권장 (단 비개발자 챕터에서는 생략 OK) - 주석: 한국어, 코드 행 위쪽에
- 헤딩:
#한 챕터 한 개,##는 본문 소제목 - 강조: 굵게 = 핵심 용어, 기울임 = 외래어 첫 등장
- 표: 3컬럼 이하 권장
- 링크: 같은 레포 내는 relative path
- 분량 19,000~21,000자
- 한 문장 100자 초과 5% 이하
- 비유 사전과 충돌 없음
- ▶ 박스 3개+, 👨💻 노트 5개+
- H1 회수 / H8 예고 박힘
- 코드 동작 검증
- 음독 60분 ± 5분
- 외래어 첫 등장 규칙 준수
- "당연히/쉽잖아요/그냥" 검출 0건
이 가이드는 살아있는 문서입니다. 대본 작성 중 새 케이스 발견 시 PR로 갱신.