d02 - 12. 바이브 코딩 도입과 빠른 재현

12교시 · 바이브 코딩 도입과 빠른 재현

2일차 14:00–15:00 · 이론/실습 선행: 1~11교시(손으로 전체 프로젝트 완성) 실습 환경: Windows 11 + PowerShell + VS Code

 

---

🎯 학습 목표

• GitHub Copilot을 설정하고, 워크스페이스 규칙서(copilot-instructions.md)와 재사용 프롬프트(*.prompt.md)를 만든다.
• 1~11교시에 손으로 익힌 클린 아키텍처·TDD 규칙을 Copilot이 자동으로 지키게 만든다.
• 핵심 한 줄기(CSV 적재 → 분석)를 바이브 코딩으로 처음부터 빠르게 재현하며 속도를 체감한다.

---

📖 개념 1 — 왜 "이제서야" 바이브 코딩인가

지금까지 11교시 동안 Copilot 없이 직접 손으로 전체 프로젝트를 만들었습니다. 그 이유가 이 교시에서 분명해집니다.

바이브 코딩의 전제 조건은 "AI가 짠 코드가 맞는지 사람이 판단할 수 있어야 한다"는 것입니다.

 

만약 클린 아키텍처도, TDD도 모른 채 처음부터 "매출 분석 앱 만들어 줘"라고 Copilot에 맡겼다면, 쏟아진 코드가 옳은지 그른지 판단할 근거가 없었을 것입니다. 하지만 여러분은 이미:

• 4계층과 의존성 규칙을 손으로 적용해 봤고,
• Red→Green→Refactor를 직접 돌려 봤으며,
• 포트/어댑터로 외부를 교체·테스트하는 법을 체득했습니다.

그래서 이제는 Copilot이 만든 코드를 보고 "이건 도메인에 pandas를 넣었으니 틀렸다", "이 테스트는 경계 케이스가 빠졌다" 를 즉시 짚어낼 수 있습니다. 판단할 수 있는 사람만이 위임할 수 있습니다. 바이브 코딩은 craft를 대체하는 것이 아니라, craft를 갖춘 사람을 가속하는 도구입니다.

📖 개념 2 — 두 종류의 지시: 상주 규칙 vs 작업 프롬프트

Copilot에게 우리 규칙을 알려 주는 방법은 두 가지이며, 역할이 다릅니다.

구분	copilot-instructions.md	*.prompt.md
성격	상주 규칙(항상 자동 적용)	작업 절차서(필요할 때 호출)
내용	"도메인엔 pandas 금지" 같은 불변 규칙	"테스트를 먼저 만들어라" 같은 단계별 절차
비유	회사 취업 규칙(헌장)	특정 업무의 작업 지시서

📝 용어 참고: GitHub Spec Kit 등 다른 도구에서는 이런 상주 규칙 문서를 "헌장(constitution)"이라 부르기도 합니다. 본 과정에서는 Copilot의 표준 파일명인 copilot-instructions.md를 그대로 사용합니다.

 

맥락 없는 AI는 "인터넷에서 가장 흔한 방식"(=한 파일에 다 섞는 안티패턴)으로 코드를 만듭니다. 규칙서로 맥락을 주면 우리 아키텍처를 따릅니다.

---

💻 실습 1 — Copilot 설정

1. signin 아이콘으로 GitHub에 로그인합니다.
2. Copilot Chat(Ctrl+Alt+I)을 열고 프로젝트 인식을 확인합니다.

이 워크스페이스의 폴더 구조를 한 줄씩 설명해 줘.

 

응답에 src/sales_agent/...와 tests가 등장하면 정상입니다.

---

💻 실습 2 — copilot-instructions.md 작성 (상주 규칙서)

.github 폴더를 만들고 규칙서를 작성합니다. 내용은 1~11교시에서 우리가 손으로 지켜 온 규칙을 그대로 문서화한 것입니다.

New-Item -ItemType Directory -Force -Path .github

 

VS Code에서 .github/copilot-instructions.md를 만들고 작성합니다.

# Copilot 지침 — sales-insight-agent

당신은 이 저장소에서 작업하는 시니어 파이썬 개발자입니다. 아래 규칙을 **항상** 따르세요.

## 프로젝트 개요
매출 CSV를 분석해 차트와 AI 인사이트 리포트를 생성하는 웹 기반 AI Agent.
클린 아키텍처 + TDD로 개발한다.

## 아키텍처 규칙 (가장 중요 — 맨 위에 둠)
- 4계층: domain → usecases → adapters → infra/UI.
- 의존성은 항상 바깥에서 안쪽으로만 향한다. 안쪽은 바깥을 import 하지 않는다.
- src/sales_agent/domain/ 코드는 표준 라이브러리만 사용한다.
  pandas, openai, streamlit, matplotlib를 절대 import 하지 않는다.
- src/sales_agent/usecases/ 코드는 domain과 usecases/ports.py(추상)에만 의존한다.
  구체 어댑터 클래스를 직접 import 하지 않는다.
- 외부(파일/네트워크/화면)와의 접점은 adapters와 infra에만 둔다.
- 안쪽이 바깥 기능을 써야 하면 usecases/ports.py에 Protocol을 정의하고
  어댑터가 이를 구현한다(의존성 역전).

## 개발 방식 (TDD)
- 기능을 만들 때는 테스트를 먼저 제안한다(Red), 그다음 최소 구현(Green).
- 테스트는 tests/ 아래 test_*.py에 둔다. pytest 스타일을 쓴다.
- 외부 의존(파일/LLM/네트워크)은 테스트에서 Fake(가짜) 구현으로 대체한다.
  테스트가 실제 네트워크를 호출하거나 과금되게 하지 않는다.
- 임시 파일·폴더는 pytest의 tmp_path를 사용한다.

## 코드 스타일
- Python 3.12. 모든 함수에 타입 힌트를 작성한다.
- 데이터 구조는 dataclass를 우선 사용한다. 값 객체는 frozen=True.
- 함수/변수명은 영어, 주석과 docstring은 한국어로 작성한다.
- 파생값(예: 매출액)은 저장하지 않고 property로 계산한다.

## 보안
- API 키·비밀값을 코드에 하드코딩하지 않는다. 환경 변수(.env)로만 읽는다.
- .env, 출력물, .venv는 .gitignore에 둔다.

## 금지
- 도메인/유스케이스에 print() 디버깅 출력을 남기지 않는다.
- 테스트 없이 핵심 로직을 구현하지 않는다.

 

🔍 관찰 포인트 — 규칙은 "추상"이 아니라 "구체적 금지/허용"으로 적습니다. "좋은 코드를 짜라" 같은 추상적 지시는 AI가 해석할 여지가 너무 넓어 잘 안 지켜집니다. 반면 "domain에 pandas import 금지" 처럼 검사 가능한 규칙은 잘 지켜집니다. 또 가장 중요한 아키텍처 규칙을 문서 맨 위에 둔 것도 의도적입니다 — AI는 앞부분을 더 비중 있게 반영합니다.

---

💻 실습 3 — *.prompt.md 작성 (재사용 프롬프트)

TDD의 세 단계를 그대로 프롬프트로 자산화합니다.

New-Item -ItemType Directory -Force -Path .github/prompts

 

.github/prompts/generate-test.prompt.md (Red 담당):

---
agent: agent
description: 기능에 대한 실패하는 테스트(Red)를 먼저 작성한다
---
# 역할
TDD의 Red 단계를 담당한다. **구현 코드는 작성하지 않는다.**

# 규칙
- tests/test_<기능>.py 에 작성한다.
- 정상 케이스 1개 이상 + 경계/오류 케이스를 포함한다.
- 외부 의존(파일/LLM/네트워크)은 Fake 클래스로 대체한다. 실제 호출 금지.
- 각 테스트에 한국어 docstring으로 "무엇을 검증하는지" 적는다.

 

.github/prompts/implement-feature.prompt.md (Green 담당):

---
agent: agent
description: 실패하는 테스트를 통과시키는 최소 구현(Green)을 작성한다
---
# 역할
TDD의 Green 단계를 담당한다.

# 규칙
- copilot-instructions.md의 아키텍처 규칙을 반드시 지킨다.
- 테스트를 통과시키는 데 필요한 코드만 쓴다(과잉 구현 금지).
- 도메인/유스케이스는 외부 라이브러리를 import 하지 않는다.
- 구현 후 `uv run pytest -v`로 통과를 확인하는 명령을 안내한다.

 

.github/prompts/refactor.prompt.md (Refactor 담당):

---
agent: agent
description: 테스트를 깨지 않으며 코드를 다듬는다(Refactor)
---
# 역할
TDD의 Refactor 단계를 담당한다.

# 규칙
- 기존 테스트를 단 하나도 깨지 않는다. 외부에서 본 동작은 동일하게 유지한다.
- 중복 제거, 의도가 드러나는 이름, 단일 책임으로 다듬는다.
- 변경 전후로 `uv run pytest`가 모두 통과해야 한다.

📝 파일 맨 위 --- ... ---(front matter)는 프롬프트의 모드·설명을 적는 메타데이터입니다.

---

💻 실습 4 — 핵심 줄기 빠른 재현 (speedrun)

이제 진짜 가속을 체감합니다. CSV 적재 → 분석 한 줄기를, 규칙·프롬프트의 힘을 빌려 처음부터 빠르게 재현해 봅니다. (이미 만든 프로젝트는 그대로 두고, 연습용으로 비교해 보는 것이 목적입니다.)

① 테스트 생성 (Red) — /generate-test

Copilot Chat에서:

/generate-test
대상 기능: AnalyzeSalesUseCase (매출 레코드 목록을 받아 총매출·상위상품·월별매출 집계)
입력은 SalesRepository 포트로 주입받는다. 테스트에서는 FakeSalesRepository를 쓴다.
정상 집계 + 빈 레코드 ValueError 케이스를 포함해.

 

🔍 관찰 포인트: 생성된 테스트가 FakeSalesRepository를 쓰고(파일 없이), 경계 케이스(빈 레코드) 까지 포함하는지 확인하세요. 규칙서·프롬프트가 작동하면 7교시에서 손으로 짠 것과 거의 같은 형태가 나옵니다. 여러분은 이미 정답을 알기 때문에 틀린 부분을 바로 짚을 수 있습니다.

uv run pytest tests/test_analyze_sales.py -v   # 🔴 실패(Red) 확인

② 구현 (Green) — /implement-feature

/implement-feature
위 테스트를 통과시키는 AnalyzeSalesUseCase를 구현해 줘.

 

🔍 관찰 포인트 — 규칙이 지켜지는지 검증하세요.

• 생성된 유스케이스가 import pandas를 하지 않는가? (도메인/유스케이스 규칙)
• SalesRepository(포트)를 주입받는 형태인가? (의존성 역전)
• 주석·docstring이 한국어인가? 규칙서가 없었다면 십중팔구 pandas로 시작했을 것입니다. 만약 규칙을 어긴 코드가 나오면, 받아들이지 말고 "도메인 규칙에 맞게 다시"라고 지시하세요.

uv run pytest tests/test_analyze_sales.py -v   # 🟢 통과(Green) 확인

③ 정리 (Refactor) — /refactor

/refactor
analyze_sales.py를 다듬어 줘. 단, 테스트가 모두 통과해야 한다.

uv run pytest -v   # 전체 회귀 확인

 

🔍 관찰 포인트 — 사람과 AI의 역할 분담. 이 루프에서 판단과 검증은 사람이, 반복 타이핑은 AI가 합니다. 손으로 만들 때와 순서·원칙은 똑같고, 타이핑만 빨라졌습니다. 이것이 바이브 코딩의 실체입니다 — AI에게 핸들을 맡기는 게 아니라, 사람이 운전하고 AI가 가속 페달을 밟는 구조입니다.

---

✏️ 미니 실습 — Copilot이 규칙을 지키는지 관찰

speedrun에서 /implement-feature로 생성된 코드를 받아들이기 전에 아래 5가지를 직접 점검하세요. AI가 규칙을 지켰는지 사람이 판단하는 연습입니다.

• [ ] 테스트가 FakeSalesRepository를 쓰는가(파일·네트워크 없이)?
• [ ] 테스트에 경계 케이스(빈 레코드 → ValueError 등)가 있는가?
• [ ] 구현이 import pandas를 하지 않는가?
• [ ] 유스케이스가 포트를 주입받는가?
• [ ] 주석·docstring이 한국어인가?

하나라도 어겼다면 받아들이지 말고 "도메인 규칙에 맞게 다시"라고 교정 지시합니다.

 

🔍 관찰 포인트: 1~11교시를 손으로 익혔기에 이 점검이 가능합니다. 판단할 수 있어야 위임할 수 있다 — 이것이 바이브 코딩의 전제입니다.

🔒 진행 게이트

• 제출물(기록): 5개 체크리스트 점검 결과(또는 규칙 위반 발견 시 교정 지시 1회).
• 이 결과가 있어야 다음 교시로 넘어갑니다.
• 정답·해설(별도 파일): solutions/미니실습정답_12.md

---

✅ 체크포인트

• [ ] Copilot이 프로젝트를 인식하고 응답한다
• [ ] .github/copilot-instructions.md가 있고, 아키텍처 규칙이 맨 위에 있다
• [ ] .github/prompts/에 generate-test, implement-feature, refactor가 있다
• [ ] /generate-test로 만든 테스트가 Fake·경계 케이스를 포함한다
• [ ] /implement-feature 결과가 규칙(도메인에 pandas 금지 등)을 지킨다
• [ ] 손으로 만들 때보다 빠르게 같은 결과에 도달함을 체감했다

---

🛠️ 트러블슈팅

증상	해결
규칙이 일부만 반영됨	가장 중요한 아키텍처 규칙을 문서 맨 위에. 핵심을 앞에
/프롬프트명 자동완성 안 됨	경로가 .github/prompts/<이름>.prompt.md인지 확인. 안 되면 내용을 Chat에 붙여넣기
도메인에 pandas가 들어옴	규칙 위반. "domain 규칙에 맞게 다시"라고 지시하고, 직접 고친다
영어 주석이 나옴	"주석·docstring 한국어" 규칙을 강조
Copilot이 규칙 무시	github.copilot.chat.codeGeneration.useInstructionFiles 설정이 켜져 있는지 확인

---

🔑 핵심 정리

• 바이브 코딩의 전제는 "AI 결과를 판단할 수 있는 craft" — 그래서 손으로 먼저 익혔다.
• copilot-instructions.md(상주 규칙)와 *.prompt.md(작업 절차)로 우리 규칙을 AI에 박제했다.
• 같은 TDD 루프를 타이핑만 빨라진 채 그대로 돌려, 핵심 줄기를 빠르게 재현했다.

다음 교시: 완성된 프로젝트에 새 기능을 바이브 코딩으로 빠르게 확장하며, 클린 아키텍처가 확장을 얼마나 안전하게 만드는지 확인합니다.