왜 잘 되다가 무너지는가

02이 차시를 마치면

• 1.바이브 코딩에서 반복적으로 나타나는 3대 실패 유형(맥락 유실·은근한 회귀·검증 없는 완료)을 예시와 함께 구별해 설명할 수 있다.
• 2.컨텍스트가 왜 무한한 자원이 아니라 예산처럼 유한한지 설명할 수 있다.
• 3.에이전틱 엔지니어링이 기존 바이브 코딩과 무엇이 다른지 자신의 말로 설명할 수 있다.
• 4.자신의 프로젝트에서 3대 실패 유형이 실제로 있었는지 점검해 진단 리포트를 작성할 수 있다.

03왜 필요한가

기본과정에서 만든 예약 접수 서비스를 두 달째 계속 고치고 있다고 해보자. 처음 몇 주는 AI에게 요청만 하면 척척 됐다. 그런데 최근엔 이상한 일이 반복된다. 지난주에 분명히 '이용자 이름은 한글만 허용해줘'라고 못박아뒀는데, 오늘 새 화면을 추가해달라고 하니 그 규칙을 까맣게 잊은 채 영문 이름도 통과되는 코드를 짜준다. 결제 화면을 새로 넣는 작업을 부탁했더니, 며칠 전엔 잘 되던 예약 취소 버튼이 어느새 눌러도 반응이 없다. 그리고 AI는 매번 '완료했습니다, 정상적으로 작동합니다'라고 자신 있게 말하지만 막상 브라우저를 열어보면 화면이 하얗게 비어 있다.

• ·규칙을 다시 설명하는 데 매번 시간을 쓰고, 그마저도 다음 세션에서 또 잊혀진다.
• ·새 기능을 넣을 때마다 예전에 되던 기능이 깨졌는지 일일이 확인해야 해서 속도가 오히려 느려진다.
• ·'완료했다'는 말을 믿고 넘어갔다가 나중에 더 큰 문제로 발견돼 원인 추적에 시간이 걸린다.
• ·문제가 반복되면 'AI가 못 미덥다'는 결론으로 넘어가 버려, 정작 고쳐야 할 나의 작업 방식(설계)은 그대로 남는다.

04개념 설명

05실습 가이드

1. 1. 진단 대상 프로젝트 열기

   • -기본과정에서 만든 프로젝트(또는 최근 두 달 이상 계속 고쳐온 아무 프로젝트)를 VS Code로 연다.
   • -Claude Code 사이드바 또는 통합 터미널을 열어 연결 상태를 확인한다.
   • -P1-1 프롬프트로 프로젝트 현재 상태(규칙 존재 여부, 최근 변경 이력, 구조)를 훑어보게 한다.

   예상 결과 — 프로젝트의 규칙 존재 여부, 최근 변경 이력, 구조에 대한 요약을 받는다.

   안 될 때 — 마땅한 프로젝트가 없다면, 기본과정 실습 중 하나(예: 04차시 자동화 스크립트)를 이어서 진단 대상으로 삼아도 된다.

2. 2. 맥락 유실 재현하기

   • -이전에 AI에게 명시적으로 요청했던 규칙 하나를 떠올린다(예: 디자인 색상, 이름 형식, 특정 라이브러리 금지 등).
   • -그 규칙을 다시 언급하지 않은 채 P1-2 프롬프트로 새 기능을 요청한다.
   • -받은 결과 코드에서 그 규칙이 지켜졌는지 눈으로 확인한다.

   예상 결과 — 규칙이 지켜지지 않은 사례를 최소 하나 확보하거나, 지켜졌다면 왜 지켜졌는지(예: README에 있었다)를 확인한다.

   안 될 때 — 규칙이 뚜렷하게 기억나지 않으면, 지금 임의로 규칙 하나를 정해 대화 초반에 알려준 뒤 대화를 충분히 길게 이어가다 같은 실험을 해본다.

3. 3. git 로그로 회귀 의심 지점 찾기

   • -터미널에서 git log --oneline으로 지금까지의 커밋 이력을 훑어본다.
   • -P1-3 프롬프트로 같은 파일·함수를 여러 번 건드린 커밋들을 짝지어 받는다.
   • -짝지어진 커밋 중 하나를 골라 git diff [커밋1] [커밋2]로 실제 변경 내용을 비교해본다.

   예상 결과 — 회귀 가능성이 있는 지점(중복 수정된 파일·함수) 목록과, 실제로 비교해본 diff 하나를 확보한다.

   안 될 때 — git 이력이 거의 없다면(커밋을 자주 안 했다면), 그 자체가 '커밋을 자주 하지 않았다'는 진단 결과가 된다 — 02차시에서 체크포인트 습관을 다룬다.

4. 4. 완료 보고된 기능 직접 확인하기

   • -P1-4 프롬프트로 지금까지 추가된 기능별 수동 테스트 체크리스트를 받는다.
   • -체크리스트를 하나씩 따라가며 실제로 클릭·입력해본다.
   • -기대와 다르게 동작하는 항목이 있으면 표시해둔다.

   예상 결과 — 기능별 체크리스트를 완주하고, 정상 동작·비정상 동작 여부가 항목별로 표시된다.

   안 될 때 — 체크리스트가 너무 길면 최근에 추가된 기능 5개만 골라 진행해도 된다.

5. 5. 이상 동작 원인 추정하기

   • -4단계에서 표시해둔 비정상 동작 중 하나를 골라 P1-5(복구 프롬프트)로 원인을 물어본다.
   • -AI가 짚어준 커밋을 git show로 직접 열어 실제 원인이 맞는지 확인한다.

   예상 결과 — 비정상 동작의 원인이 된 것으로 추정되는 커밋과 그 근거를 확보한다.

   안 될 때 — 원인이 명확히 안 잡히면 '원인 불명'으로 리포트에 남겨도 된다 — 원인을 완벽히 찾는 것이 아니라 이런 사고가 실제로 일어난다는 걸 확인하는 것이 이번 차시의 목적이다.

6. 6. 진단 리포트 작성하기

   • -2~5단계에서 확보한 사례들을 정리해 P1-6 프롬프트로 AI에게 리포트 작성을 요청한다.
   • -리포트 파일을 프로젝트 루트에 diagnosis-report.md 같은 이름으로 저장한다.
   • -리포트를 처음부터 끝까지 읽으며 실제 겪은 내용과 다르게 쓰인 부분이 없는지 확인한다.

   예상 결과 — 3대 실패 유형별 사례와 예방 문장이 담긴 마크다운 리포트 파일이 생성된다.

   안 될 때 — 세 유형 중 하나라도 사례를 못 찾았다면 '이번 프로젝트에서는 발견하지 못함'이라고 정직하게 적는다 — 없는 사례를 지어내지 않는다.

7. 7. 저장소에 기록해두기

   • -git add와 git commit으로 리포트 파일을 커밋한다.
   • -커밋 메시지에 '진단: 3대 실패 유형 점검'처럼 이번 실습의 목적이 드러나게 적는다.

   예상 결과 — 진단 리포트가 저장소 커밋 이력에 남는다.

   안 될 때 — 아직 Git 저장소가 아니라면 git init부터 진행한다. 이번 실습에서 '커밋이 안 돼 있었다'는 사실 자체도 진단 결과에 포함시킨다.

06실전 프롬프트

지금 이 프로젝트를 처음 보는 사람 입장에서 훑어봐줘.

1. README나 규칙 파일이 있는지, 있다면 뭐라고 적혀 있는지
2. 최근 커밋 로그를 보고 최근 두 달 동안 어떤 기능이 추가됐는지
3. 지금 폴더 구조에서 헷갈리는 부분이 있는지

진단이 목적이니까 고치지 말고, 관찰한 내용만 알려줘.

예전에(또는 방금) 너한테 [지켜야 할 규칙 하나, 예: 버튼 색은 항상 파란색만 쓴다]라고 말한 적이 있어.

지금 새로 [간단한 기능 하나]를 추가해줘. 이번 요청에는 그 규칙을 다시 안 알려줄 거야.

결과 코드에 그 규칙이 반영됐는지 내가 직접 확인해볼게.

최근 커밋 로그를 봐줘. 지난 [2개월] 동안 추가되거나 변경된 기능 목록을 뽑아줘.

그 중에서 서로 같은 파일이나 같은 함수를 건드린 커밋들이 있으면 짝지어서 알려줘.
같은 부분을 여러 번 건드렸다면, 나중 수정이 이전 기능을 깨뜨렸을 가능성이 있는 지점이니까 표시해줘.

지금까지 이 프로젝트에 추가된 기능들을 커밋 메시지 기준으로 목록화해줘.

각 기능마다 내가 직접 클릭하거나 값을 넣어서 확인해볼 수 있는 테스트 방법을 한 줄씩 적어줘.
나는 그 목록을 보면서 하나씩 직접 확인해볼 거야.

방금 확인해보니 이런 문제가 있어.

[관찰한 문제: 예 - 예전에 됐던 버튼이 안 눌린다]

이게 최근에(또는 언제부터) 이렇게 됐는지 커밋 이력에서 추정해줘.
원인이 될 만한 커밋을 짚어주고, 왜 그렇게 생각하는지도 설명해줘.

지금까지 확인한 내용을 정리해서 진단 리포트를 만들어줘.

- 맥락 유실 사례: [발견한 내용, 없으면 '없음'이라고 적어줘]
- 은근한 회귀 사례: [발견한 내용]
- 검증 없는 완료 사례: [발견한 내용]

각 사례마다 무슨 일이 있었는지 한 문단, 앞으로 어떻게 예방할지 한 문장씩 적어줘.
마크다운 문서 하나로 정리해줘.

07이것만은 주의

08자가 점검

09과제

이번 실습에서 다룬 프로젝트가 아니라, 자신이 관리하는 다른 프로젝트(또는 동료의 프로젝트)를 하나 더 골라 같은 3단계 진단(맥락 유실·은근한 회귀·검증 없는 완료)을 반복해보고, 두 프로젝트의 진단 결과를 비교해 공통적으로 반복되는 원인이 있는지 정리한다.

제출 형식 — 두 번째 프로젝트의 진단 리포트(.md)와, 두 리포트를 비교한 3~5문장 요약을 함께 제출한다.

10더 알아보기

• Claude Code 공식 문서 — 프로젝트 메모리(CLAUDE.md) — 다음 차시 실습 전에 훑어보면 좋다
• 자신의 git log — 가장 훌륭한 참고자료는 이미 자신의 프로젝트 안에 있다

에이전틱 엔지니어링(Agentic Engineering)

— AI가 반복해서 같은 품질로 일하도록 규칙·스펙·검증·체크포인트 같은 주변 장치를 설계하는 작업.

컨텍스트 윈도우(Context Window)

— AI가 한 번에 참고할 수 있는 대화·코드·문서의 최대 분량. 이 한도를 넘으면 오래된 내용부터 밀려난다.

회귀(Regression)

— 새로운 변경으로 인해 이전에 정상 동작하던 기능이 깨지는 현상.

다음 차시 예고 — 다음 차시(컨텍스트 엔지니어링)에서는 오늘 진단한 '맥락 유실' 문제를 실제로 해결한다. 규칙 파일을 계층적으로 구성하고, 그 규칙이 정말 지켜지는지 검증하는 법을 다룬다.