1주차-1장~4장 — 바이브 코딩 유지보수성: 책임·결합·캡슐화·Cynefin

AI 코딩(바이브 코딩)이 최초 구축에는 강하지만 반복 수정에 취약한 이유를 분석하고, 책임(변화율)·결합(영향력)·캡슐화·Cynefin 프레임워크로 수정에 강한 구조를 설계해 AI를 지도하는 방법을 학습한다.

0. 사전 필수 용어 (선행지식)

본 강의 이해에 필요한 4개 핵심 용어. 본문에서 반복적으로 등장하므로 사전에 숙지한다.

1. 바이브 코딩 (Vibe Coding / AI 코딩)
2. 정의: 대화형 AI(예: Claude·GPT·Gemini)에게 자연어 프롬프트로 코드를 생성·수정하도록 지시하는 개발 방식.
3. 비유: 사람과 짝 프로그래밍하듯 "분위기"로 의도만 전달하고 코드는 모델이 작성.
4. 본문 사용: 1·2·4장 전체 — 모든 논의의 전제.

5. 입문 자료 부족 시: Anthropic Claude Code 공식 가이드 또는 Aider 튜토리얼을 먼저 1회 실습 권장.

6. 도메인 (Domain)

7. 정의: 비즈니스 규칙·정책·관행이 모여 있는 영역 (예: "24세 이상만 가입 가능한 보험 상품").
8. 특징: 논리적·학문적이지 않다 — 김부장의 결정·정책 변경·외주 변경 등 비논리적 사유로 바뀜.

9. 본문 사용: §2·§6 에서 "책임=변화율"의 원천으로 설명.

10. 모듈(Module)·인터페이스(Interface)

11. 정의: 외부에 노출되는 진입점(공개 함수·API 시그니처)만 인터페이스. 내부 구현은 모듈 안에 숨김.
12. 비유: 자동판매기 — 동전 투입구·버튼만 보이고 내부 기계 구조는 가려짐.

13. 본문 사용: §3·§5 의 캡슐화 논의의 기반.

14. 스프린트·피봇(Pivot)

15. 정의: 짧은 주기 반복 개발(스프린트)을 통해 제품의 본질적 가치가 완전히 다른 방향으로 전환되는 패턴(피봇).
16. 비유: 자전거 → 전동킥보드 → 오토바이 → 자동차 — 같은 "탈것"이지만 본질이 다른 제품.
17. 본문 사용: §1 에서 "제품을 미리 정의할 수 없는 이유"의 근거.

📚 참고: 선행지식이 부족하면 Microsoft Learn 의 "Maintainability" 문서 또는 Robert C. Martin 의 SOLID 원칙 입문 자료를 먼저 학습한다.

1. 주제 정의

바이브 코딩의 유지보수성 이란, AI 가 생성한 코드를 지속적으로 수정·확장 가능한 구조로 유지하기 위한 설계 원칙과 지도 전략의 묶음이다.

강의는 "하네스(보편적 프롬프트 세트)로 모든 제품을 통제할 수 있다"는 환상을 해체한다. 핵심 메시지:

• AI 모델은 과업 완수(task completion) 에 최적화되어 학습됨. 첫 결과물은 그럴듯하지만 반복 수정에는 취약.
• 하네스로 묶는다고 해결되지 않는다 — 제품마다 책임과 변화율이 다르기 때문에 보편 하네스는 성립 불가능.
• 따라서 개발자가 책임·결합·캡슐화 개념을 알고 상황별로 AI 를 지도해야 한다.

⚠️ 주의: "AI 가 코딩하니까 개발자 지식이 필요 없다"는 발상은 위험. 오히려 AI 를 지도하기 위한 설계 지식이 더 중요해진다.

2. 풀려는 문제

2.1 최초 구축은 성공, 반복 수정에서 실패

• 70~80% 짜리 첫 결과물은 잘 나온다 — 최종 제품 대비 복잡성이 낮기 때문 (00:09:34, 00:10:07).
• 여기에 3% 추가하려고 하면 0% 부터 다시 뽑기가 시작됨 (00:10:21).
• 세션 5개까지는 훌륭해 보이지만, 세션 20개쯤 가면 거의 뽑기 수준으로 떨어짐 (00:11:00).

2.2 왜 그런가? — 모델 학습 특성

AI 모델은 "과업 완수" 위주로 학습됨. "수정 용이성"은 학습 시그널에 포함되지 않음.

• 결과: 코드가 단일 완성 에는 적합하지만, 증분 코드 관리에는 부적합.
• 인덕스 페이지가 3000줄짜리 한 파일로 만들어지는 등 책임 분리가 안 됨.

2.3 본질 문제

1. 제품 정의의 어려움 — 애자일·스프린트가 존재하는 이유 자체가 "처음에는 제품을 모른다" 이다. 피봇이 본질.
2. 반복 수정 약점 — AI 의 학습 구조적 한계.
3. 하네스의 환상 — 보편적 지시문으로 묶일 수 없음.

💡 실무 노하우: 첫 세션이 잘 됐다고 안심하지 말 것. 세션 5개 시점에 구조가 잡혔는지 검토하는 게이트를 만들어 두면 20세션 뽑기 단계로 가기 전에 개입할 수 있다.

3. 핵심 개념·구조

5개 핵심 개념. 각 개념은 서로 연결된다 (책임 → 격리 → 결합 관리 → 캡슐화 → Cynefin 전략).

3.1 책임 (Responsibility) = 변화율

• 정의: 해당 코드/기능이 수정되는 이유.
• 예시: 프로모션 정책·멤버십 정책·김부장 선호도·퇴사·도메인 변경·외주업체 변경.
• 변화율이 같은 코드끼리 묶고, 다른 코드는 격리해야 함.

3.2 결합 (Coupling) = 영향력

• 정의: 한 요소가 다른 요소에게 영향을 미치는 정도와 방식.
• 핵심: 의존성 ≠ 영향력. 변하지 않는 수학 함수에 의존해도 결합은 낮음.
• 영향력 발생의 3가지 원인: | 원인 | 의미 | |---|---| | 추종(트위킹) | 한 쪽이 바뀌면 따라 바뀌어야 함 | | 달성 목적 공유 | 같은 목표를 향해 함께 움직임 | | 자원 공유 | 같은 DB·파일·메모리 등 공유 |

3.3 격리 (Isolation)

• 정의: 책임·변화율에 따라 코드를 물리적으로 나누고 의존성을 최소화.
• 목표: 단방향 의존성 + 최소 관계.
• 양방향 의존성은 수정 시 연쇄적 여파를 일으켜 유지보수 불가.

3.4 캡슐화 (Encapsulation)

• 정의: 모듈의 내부 구조·구체적 구현 지식(Implementation Knowledge) 을 외부에 노출하지 않음.
• 위반 시: 구체 지식 결합(Implementation knowledge coupling) 발생 → 외부가 내부를 예상·오용.
• 대표 사례: 번역 API 의 부산물인 "언어 판별기"를 외부에서 직접 호출 → 번역 API 내부 변경 시 호출자 깨짐.

3.5 Cynefin (코네빈) 프레임워크

문제 이해도를 기준으로 5영역 분류 → 영역별 AI 코딩 전략:

4. 실습·구현 가이드 (Step 1~4)

코딩 실습은 없다. 대신 AI 지도 단계를 4 스텝으로 적용한다.

Step 1 — 변화율 식별

1. 최근 6개월 변경 커밋을 파일 단위로 집계.
2. 변경 원인을 분류: 정책·도메인·인물·외주·요청자별.
3. 같은 원인으로 함께 바뀐 파일을 한 묶음으로 묶음(=책임 단위 후보).

Step 2 — 격리

1. 책임 단위 후보별로 디렉터리 또는 모듈로 분리.
2. 다른 책임 단위와의 의존을 단방향으로 정리 (예: domain → infra 만 허용, 역방향 금지).
3. AI 에 지시: "이 디렉터리는 X 책임만 다룬다. 다른 책임 코드를 넣지 마라."

Step 3 — 캡슐화

1. 각 모듈의 공개 인터페이스 목록을 명시 (함수 시그니처만).
2. 내부 구현 지식이 인터페이스로 새는지 점검 (예: 반환 타입에 내부 클래스 노출 여부).
3. AI 에 지시: "이 모듈은 X 만 노출한다. 호출자가 내부 알고리즘을 알 필요가 없게 인터페이스를 좁혀라."

Step 4 — Cynefin 으로 AI 전략 선택

✅ 확인: 각 작업을 시작하기 전 "이건 Cynefin 어느 영역?"부터 자문하는 습관이 형성됐는가?

5. 사례·적용

5.1 사례 1 — 24세 보험 상품의 변화율

원 코드: if age >= 24: 로 가입 가능 여부 판정.

• 김부장이 22세로 변경 요청 → if age >= 22: 로 수정.
• 다음 달 사장님이 "왜 22세야?" 라며 다시 변경.
• 문제: 코드 곳곳에 24 가 박혀 있으면 변경마다 그레프 + 수정 + 회귀 테스트 비용 발생.
• 해결: 도메인 정책 상수로 분리 (MIN_AGE_FOR_PLAN_X = 22). 호출부는 상수 참조.

5.2 사례 2 — 번역 API 의 언어 판별기 오용

번역 API 내부에 부산물로 "입력 언어 판별" 로직이 있다.

• 호출자가 이를 발견하고 언어 판별 용도로 직접 사용.
• 번역 팀이 내부 알고리즘을 교체 → 호출자 모두 깨짐.
• 원인: 구체 지식 결합 — 캡슐화 실패로 내부 지식이 노출됐고, 외부가 그것에 의존.
• 교훈: 인터페이스를 좁혀 "번역 결과"만 노출하고, 언어 판별이 필요하면 별도 서비스로 분리.

5.3 사례 3 — 세션 20개 뽑기 현상

• 채팅창 5개까지: AI 가 훌륭히 따라옴.
• 채팅창 20개쯤: 수정마다 기존 기능 깨짐 → 깃 리셋 → 재생성 반복.
• 원인: 누적된 코드가 변화율 기준으로 분리되지 않아 한 수정이 전역적 영향.

💡 실무 노하우: 세션 5개 게이트에서 구조 리뷰. 책임별 분리가 안 되어 있으면 그 시점에 재구조화 — 20세션 뽑기 단계까지 가지 말 것.

6. 핵심 원리

6.1 도메인은 비논리적·비학문적

• 책임/변화율은 SOLID 같은 학문적 원칙이 아니라 비즈니스 현실 에서 출처.
• "24세 → 22세" 변경에 논리는 없음. 단지 누군가의 결정.

6.2 변화율 자체도 변한다

• 김부장이 매번 바꾸던 코드가 어느 날 상무님 호통 이후 안 바뀌게 됨.
• → 그 코드는 상수 영역으로 옮길 수 있음.
• 초반 설계의 변화율 판단을 계속 재조정 해야 한다.

6.3 의존성 ≠ 영향력

• 의존만으로는 결합 판단 불가. 변화가 함께 와야 진짜 결합.
• 안 변하는 수학 함수에 의존하는 코드는 결합 0 에 가까움.

6.4 인터페이스는 좁을수록 좋다

• 캡슐화의 핵심은 외부가 알 필요 없는 것을 안 알게 하는 것.
• 인터페이스로 내부 알고리즘이 추론 가능하다면 이미 캡슐화 실패.

7. 한계·트레이드오프

7.1 유지보수성 ↔ 유연성

• 유지보수성을 높이려면 책임별 격리·캡슐화 강화 → 인터페이스 좁아지고 유연성 감소.
• 유연성을 높이면 내부 노출 증가 → 결합 증가, 유지보수 어려워짐.
• 해법: 코드 재배치(rearrangement) 로 균형점 탐색. 정답 1개 없음.

7.2 보편 하네스의 불가능

• 누가 만든 프롬프트 세트가 본인 제품에서 잘 됐다고 자랑해도, 다른 제품엔 안 맞음.
• 관통하는 원리는 있지만 (예: "사람은 착하게 살아야 한다"), 상황별 적용은 다름.

7.3 비즈니스 모델 전환의 비용

• 강사 권고: 미래에는 "일회성 결과물로 돈 버는 비즈니스" 로 피봇하면 바이브 코딩 강점을 100% 활용.
• 그러나 레거시 비즈니스를 가진 회사는 당분간 유지보수도 해야 함 — 본 강의가 필요한 이유.

7.4 AI 자체의 한계

• AI 는 Clear·Complicated 까지는 잘 함.
• Complex·Chaotic 영역까지 코드를 생성하려 들지만 신뢰할 수 없다 — 개발자가 통제해야 함.

8. 다른 접근과 비교

8.1 AI 코딩 도구 OSS 와의 위치

본 강의의 교훈을 OSS 도구에서 직접 관찰 가능:

• anthropics/claude-code (https://github.com/anthropics/claude-code) — AGENTS.md / CLAUDE.md 같은 지시 파일로 책임 분리를 명시화하는 패턴. 강의의 "초반 지도 → 성숙 후 자동 적용" 과 정합.
• Aider-AI/aider (https://github.com/Aider-AI/aider) — repo map 으로 컨텍스트를 좁히는 방식. 강의의 "공개 인터페이스만 노출" 원칙과 유사한 동기.

📚 참고: 본 강의는 학문적 패러다임(SOLID·DDD)을 부정하지 않고, 도메인의 현실적 비논리성 을 출발점으로 삼아 재해석한다.

9. 메타인지 자기평가

9.1 체크리스트

• [ ] R(Remember): "책임" 의 강의 정의(= 수정되는 이유 = 변화율) 를 외워서 말할 수 있는가?
• [ ] U(Understand): "의존성 ≠ 영향력" 의 차이를 수학 함수 예시로 설명할 수 있는가?
• [ ] Ap(Apply): 자신의 코드에서 변화율이 다른 부분 3곳을 식별할 수 있는가?
• [ ] Ap: 단방향 의존성과 양방향 의존성을 본인 코드에서 구분해 그릴 수 있는가?
• [ ] An(Analyze): 최근 본인이 겪은 "수정 시 다른 곳이 깨진" 사건을 결합 발생 원인 3가지(추종/공유목적/공유자원)로 분류할 수 있는가?
• [ ] Ev(Evaluate): 본인 프로젝트가 Cynefin 어느 영역에 있는지 판단하고, 그에 맞는 AI 전략을 정할 수 있는가?
• [ ] C(Create): 본인 코드에 변화율 매트릭스를 한 페이지로 그릴 수 있는가?

9.2 자가 진단 질문

1. 마지막 AI 코딩 세션에서 세션 5개 게이트를 두었는가? 안 두었다면 다음 세션부터 도입.
2. AI 가 만든 코드 중 롤백 했어야 했는데 안 했던 것 이 있는가? 그것이 Complex 영역이었을 가능성.
3. 우리 팀이 "범용 하네스" 를 추구하고 있다면, 책임/변화율이 제품마다 다른 이유를 설명하고 방향을 바꿀 수 있는가?

✅ 확인: 7개 체크리스트 중 5개 이상 "예" 라면 강의 내용을 실무에 적용할 준비가 되었다고 본다.

본 학습 노트는 1주차-1장~4장 강의 자막·매뉴얼을 합성해 작성됨 (2026-05-27).