바이브 코딩,
어디까지 만들면
완료인가

네 문을 한 묶음으로 확인하는 법

네 가지 기준은 서로 떨어진 체크 항목이 아니다. 핵심 작업이 정상 조건에서 끝나더라도 오류 뒤에 입력이 사라지면 사용자는 같은 일을 처음부터 반복해야 한다. 복원은 되지만 실행 방법과 설정이 남지 않으면 제작자 외에는 결과를 재현하기 어렵다. 따라서 완료 판단은 성공 장면 하나가 아니라 시작부터 실패·복구·재실행까지 이어지는 한 흐름을 본다.

가령 개인 독서 기록 앱이라면 책 한 권을 등록하는 장면만 확인하지 않는다. 빈 제목을 넣었을 때 수정할 곳이 보이고, 저장 뒤 같은 브라우저에서 새로고침해도 기록이 남으며, 다른 사람이 안내문을 따라 같은 버전을 열 수 있는지까지 살핀다. 공개 주소가 있다면 어떤 데이터가 기기에 남는지도 설명할 수 있어야 한다.

한 문이라도 막히면 기능을 더 얹기보다 현재 단계를 정확히 적는다. 학습용 데모라면 제한 조건을 밝히고 종료할 수 있다. 다른 사람이 반복해서 쓰는 도구로 공개하려면, 막힌 문을 고친 뒤 같은 핵심 작업 전체를 다시 확인하는 편이 맞다.

자료의 역할이 다르면 결론도 달라진다

공식 문서는 기술의 동작과 권고 범위를 설명하고, 공급사 사례는 특정 조직이 어떤 방식으로 도구를 사용했는지 보여 준다. KAAI의 직접 검증은 정해진 앱과 시험 조건에서 무엇이 재현됐는지를 말한다. 세 자료는 서로를 보완하지만, 어느 하나도 다른 환경의 성과를 대신 증명하지는 않는다.

예를 들어 공급사 사례의 시간 절감 수치는 그 사례의 비교 조건과 함께 읽어야 한다. 개인 프로젝트에 같은 수치를 옮기려면 업무 난도, 수정 횟수, 사람의 검토 시간까지 같은 기준으로 다시 측정해야 한다. 그런 기록이 없다면 '이런 작업 방식이 가능했다'고 참고할 수는 있어도 '내 프로젝트도 같은 폭으로 빨라진다'고 결론낼 수는 없다.

자료를 인용할 때는 문장마다 역할을 정한다. 기술 설명은 적용 조건을 확인하는 데, 사례는 시도할 가설을 세우는 데, 직접 시험은 현재 버전의 통과 범위를 기록하는 데 쓴다. 근거의 범위를 넘어서는 성과·안전성·시장 판단은 확인될 때까지 보류한다.

단계 이름은 약속의 범위를 정한다

단계 이름이 중요한 이유는 제작 수준을 자랑하기 위해서가 아니라, 사용자가 기대해도 되는 범위를 알려 주기 위해서다. 데모를 운영 서비스처럼 소개하면 정해진 장면 밖의 오류와 데이터 손실까지 사용자가 감수하게 된다. 반대로 학습 목적의 프로토타입을 정확히 표시하면 제한된 범위에서도 충분히 유용한 결과가 될 수 있다.

가령 행사 신청 화면이 샘플 정보로 한 번 작동하면 데모에 가깝다. 여러 입력을 반복해 보고 잘못된 값에서 회복하면 프로토타입 근거가 생긴다. 실제 신청을 받으려면 저장 위치, 접근 권한, 중복 제출, 삭제 요청, 장애 때의 연락과 복구까지 책임 범위에 들어온다.

다음 단계로 올릴 때는 새 기능 수가 아니라 새 약속을 감당할 증거가 있는지 본다. 사용 대상이나 데이터 범위가 넓어졌는데 시험과 책임이 그대로라면 승격을 보류하고, 현재 단계와 제한 조건을 공개 설명에 남긴다.

한 줄 계약이 기능 우선순위를 가른다

프로젝트 계약은 아이디어를 멋지게 요약하는 문구가 아니라, 기능을 넣거나 뺄 때 쓰는 판단 기준이다. 사용자와 핵심 작업이 정해지면 같은 화면에서도 반드시 필요한 입력과 나중으로 미룰 장식을 구분할 수 있다. 실패 뒤 돌아갈 지점까지 적는 이유는 정상 흐름만 보고 완료를 선언하지 않기 위해서다.

예를 들어 '개인이 지출 항목을 입력해 이번 달 목록을 보고, 잘못 입력한 항목을 수정한다'고 정했다면 첫 버전의 핵심은 입력·목록·수정이다. 통계 그래프나 추천 문구가 흥미롭더라도 이 세 동작이 불안정하면 우선순위가 아니다. 저장하지 않은 값이 사라지는지, 금액 형식이 틀렸을 때 어디서 고치는지도 같은 계약에서 시험할 수 있다.

계약 문장을 읽고도 완료 장면을 두 사람이 다르게 그린다면 제작을 잠시 멈추고 입력·결과·실패 조건을 더 좁힌다. 문장이 안정된 뒤에야 도구를 고르면, 플랫폼의 기능 목록이 프로젝트 범위를 대신 결정하는 일을 줄일 수 있다.

두 경로는 수준이 아니라 책임의 위치가 다르다

비개발 경로와 개발 경로는 쉬운 방식과 고급 방식의 순서가 아니다. 관리형 플랫폼을 쓰면 배포와 일부 운영을 플랫폼에 맡기는 대신, 내보내기·권한·요금·서비스 변경 조건을 확인해야 한다. 코드를 직접 관리하면 수정 범위는 넓어지지만 의존성, 환경 설정, 빌드와 되돌리기를 제작자가 설명해야 한다.

가령 같은 신청 폼을 만든다고 해 보자. 관리형 도구에서는 누가 응답을 볼 수 있는지, 원본을 어떤 형식으로 내보낼 수 있는지, 공개 링크를 끌 수 있는지가 핵심 기록이다. 코드로 만든다면 저장소의 실행 방법, 비밀값을 넣는 위치, 배포 실패 뒤 이전 버전으로 돌아가는 절차가 같은 역할을 한다. 화면이 같아도 책임이 놓이는 자리는 달라진다.

경로 선택은 필요한 통제와 감당할 운영 부담을 비교해 결정한다. 단순한 공개 페이지이고 플랫폼의 내보내기와 권한이 목적에 맞으면 비개발 경로로 충분할 수 있다. 반대로 외부 시스템 연동, 세밀한 권한 분리, 독자적인 복구 절차가 필요하지만 플랫폼이 이를 설명하거나 제공하지 못하면 코드 경로를 검토한다.

어느 경로에서도 확인할 수 없는 설정을 추정으로 메우지 않는다. 데이터 반출 방법이 불명확하거나, 필요한 되돌리기를 실제로 시험하지 못했다면 공개 범위를 줄이거나 배포를 보류한다. 완료의 공통 증거는 다른 사람이 같은 핵심 작업을 재현하고 실패 뒤 돌아올 수 있는지다.

선수 지식의 목표는 원인 위치를 좁히는 것

선수 모듈을 모두 전문적으로 다룰 필요는 없지만, 화면·브라우저·데이터·배포 중 어디에서 문제가 생겼는지는 나눌 수 있어야 한다. 이 구분이 없으면 표시 오류를 데이터 손실로 오해하거나, 저장 문제를 화면 디자인 수정으로 반복하게 된다. 최소 학습의 결과는 용어 암기가 아니라 다음 확인 지점을 고르는 능력이다.

가령 입력한 메모가 새로고침 뒤 사라졌다면 먼저 저장 버튼의 동작, 브라우저 저장소, 접속한 주소가 같은지 차례로 본다. 다른 기기에서도 보여야 하는 요구라면 기기 안 저장만으로는 부족하다는 점도 드러난다.

제작자는 각 모듈마다 하나의 통과 증거를 남기면 된다. 이전 버전 복원, 오류 위치 확인, 저장 위치 설명, 이용 조건 확인 중 현재 프로젝트에 필요한 항목을 실제로 수행한다. 그 증거가 없으면 관련 기능을 공개 범위에서 빼거나 도움을 받을 지점을 명시한다.

수정 뒤 정상 흐름까지 다시 봐야 한 번의 루프다

실패를 고친 직후에는 그 실패 사례만 통과하기 쉽다. 하지만 입력 검사를 추가하면서 정상 입력이 막히거나, 저장 방식을 바꾸면서 기존 기록을 불러오지 못할 수 있다. 그래서 재검증은 고친 오류와 원래의 핵심 작업을 함께 실행해야 끝난다.

빈 제목을 막는 검사를 추가했을 때도 수정의 영향은 그 입력란에 그치지 않는다. 빈 값의 안내를 확인한 다음, 정상 제목의 저장과 새로고침 뒤 복원까지 다시 본다. 수정 전후의 입력, 기대 결과, 실제 결과를 남기면 다음 변경에서 같은 실패가 돌아왔는지 비교할 수 있다.

배포는 생성 횟수나 수정 횟수가 아니라 이 반복의 증거를 기준으로 결정한다. 핵심 작업이 다시 깨졌거나 실패 원인을 설명할 수 없다면 새 기능을 이어 붙이지 않고 마지막으로 확인된 상태로 돌아가 원인을 좁힌다.

오류 문구는 다음 행동을 설계하는 화면이다

오류 화면의 역할은 실패 사실을 알리는 데서 끝나지 않는다. 사용자가 방금 한 일이 저장됐는지, 같은 요청을 다시 보내도 되는지, 어느 값을 고쳐야 하는지를 판단하게 해야 한다. 이 정보가 없으면 사용자는 중복 제출을 만들거나 작업을 포기할 수 있다.

가령 신청 버튼을 누른 뒤 연결이 끊겼다면 단순히 '오류가 발생했습니다'라고 쓰지 않는다. 제출 완료 여부를 확인할 방법이 있는지, 입력은 화면에 남아 있는지, 다시 시도하기 전에 무엇을 확인해야 하는지를 보여 준다. 실제로 완료 여부를 확인할 수 없다면 성공처럼 표시하지 않고 미확정 상태로 남긴다.

복구 경로는 제작자도 시험한다. 오류를 의도적으로 만들고 입력 보존, 안내 문구, 재시도, 이전 상태 복원을 차례로 확인한다. 외부 효과가 생겼는지 알 수 없거나 되돌릴 방법이 없다면 자동 재시도보다 중단과 확인을 먼저 둔다.

시험 항목은 실패의 크기와 발견 난도로 정한다

테스트 우선순위는 만들기 쉬운 항목이 아니라, 실패했을 때 사용자의 일을 얼마나 되돌리기 어려운지로 정한다. 핵심 결과가 틀리는 실패, 데이터가 사라지는 실패, 이미 끝난 일을 중복 실행하는 실패는 화면 간격 같은 문제와 따로 관리해야 한다. 평균 통과 개수로 중대한 한 건을 상쇄하지 않는 이유다.

가령 개인 일정 요청 도구를 시험한다면 먼저 날짜와 요청 내용이 한 번만 저장되는지 본다. 빈 날짜, 형식이 다른 날짜, 저장 중 새로고침, 같은 버튼 두 번 누르기, 작은 화면에서 수정하기를 이어서 시험한다. 각 항목에는 기대 결과를 먼저 적고 실제 화면이나 저장 상태를 남긴다.

수정 뒤에는 실패했던 입력만 다시 넣지 않는다. 정상 일정 한 건을 처음부터 등록하고, 새로고침해 확인한 뒤, 수정과 삭제가 원래 약속대로 되는지 회귀 시험을 한다. 테스트 기록에는 입력 조건, 기대 결과, 실제 결과, 사용한 버전이 있어야 다른 사람이 같은 판단을 재현할 수 있다.

인증·결제·개인정보처럼 영향 범위가 넓어지면 기존의 정적 앱 시험만으로 공개를 결정하지 않는다. 새 권한과 데이터 흐름, 실패 뒤 외부 영향을 다룰 시험을 먼저 추가한다. 시험할 환경이나 책임자가 준비되지 않았다면 해당 기능은 다음 버전으로 보류한다.

장애는 요청이 멈춘 층부터 찾는다

웹 주소가 열리지 않는다고 해서 모두 서버 장애인 것은 아니다. 주소가 올바른 위치를 가리키는지, 호스팅이 파일이나 응답을 내놓는지, 앱 코드가 화면을 만들었는지, 필요한 데이터를 읽었는지를 순서대로 나누면 확인 범위가 줄어든다. 층을 섞으면 도메인 설정 문제를 코드 수정으로 해결하려는 일이 생긴다.

첫 화면은 열리지만 저장한 목록만 보이지 않는다면 앱의 요청, 권한, 데이터 저장 상태를 먼저 살펴볼 수 있다. 반대로 주소 자체가 다른 곳을 가리킨다면 화면 코드를 고쳐도 요청은 해당 앱에 도달하지 않는다. 사용자가 마지막으로 정상 확인한 지점을 찾는 것이 진단의 출발점이다.

정적 페이지로 핵심 작업이 끝나면 서버와 데이터베이스를 억지로 추가하지 않는다. 여러 사용자가 상태를 공유하거나 비밀값을 브라우저 밖에서 처리해야 할 때처럼 요구가 생겼을 때만 구조를 넓힌다. 새 층을 추가하면 비용·권한·백업·복구의 책임도 함께 정한다.

공개 전에 한 건의 데이터가 지나가는 길을 그린다

개인정보와 비밀값을 줄이려면 먼저 입력부터 삭제까지의 경로를 알아야 한다. 사용자가 넣은 값이 브라우저, 외부 API, 로그, 데이터 저장소 중 어디를 지나고 어디에 남는지 적으면 불필요한 수집과 복사본이 드러난다. 목적을 설명할 수 없는 필드는 받지 않는 것이 가장 단순한 통제다.

가령 사용자가 자신의 문장을 넣어 요약을 받는 도구를 생각해 보자. 요약에 이름이 필요하지 않다면 이름 입력란을 만들 이유가 없다. 문장이 외부 서비스로 전달된다면 전송 사실과 범위를 사용자가 알 수 있어야 하고, 오류 로그에는 원문 전체 대신 문제를 재현하는 데 필요한 최소 정보만 남기는 방식을 검토한다.

API 키는 입력 데이터와 반대 방향으로도 살핀다. 브라우저에 키를 넣으면 사용자가 화면에서 보지 못하더라도 배포된 코드나 요청에서 노출될 수 있으므로, 원문의 권고처럼 백엔드와 비밀 저장소를 사용한다. 그 구조를 마련할 수 없다면 키가 필요한 기능을 공개 버전에서 빼는 편이 맞다.

공개 판단에는 수집 목적, 접근 가능한 사람, 보관과 삭제 방법, 잘못된 출력이 실행되기 전의 확인 지점을 함께 기록한다. 하나라도 답할 수 없으면 안내문으로 책임을 넘기기보다 데이터 범위를 줄이거나 기능을 보류한다. 실제 개인정보 처리의 적합성은 적용 환경과 별도 검토가 필요하다.

발견 준비와 실제 노출은 서로 다른 상태다

제목·설명·H1·본문이 같은 질문에 답하면 검색 시스템과 독자가 페이지의 주제를 파악하기 쉬워진다. 하지만 이 준비가 곧 수집·노출·클릭·인용을 뜻하지는 않는다. 공개 전에는 문서가 답할 질문과 근거를 정리하고, 공개 뒤에는 각 도구와 실제 검색 결과에서 별도로 확인해야 한다.

예를 들어 '개인 프로젝트 완료 기준'을 다룬 페이지라면 제목은 그 질문을 드러내고, 첫 문단은 완료의 조건을 짧게 답하며, 본문은 테스트와 한계를 근거 가까이에 둔다. 같은 표현을 모든 소제목에 반복하거나 내용이 같은 페이지를 여러 개 만드는 것은 독자에게 새 답을 주지 않는다.

게시 뒤 자료가 수집되지 않았다면 먼저 공개 설정, 대표 주소, 본문 접근 가능 여부를 확인한다. 수집됐지만 선택되지 않은 경우에도 특정 글자 수나 FAQ 개수로 결과를 보장하지 않는다. 노출과 인용은 관찰값으로 기록하고, 문안의 정확성과 기술 상태를 분리해 개선한다.

확장은 기술 이름이 아니라 막힌 지점에서 시작한다

RAG·Agent·Docker·Ollama는 기본 앱의 완성도를 대신하지 않는다. 각각 근거 검색, 여러 단계의 행동, 실행 환경 재현, 로컬 모델 실행이라는 다른 문제에 답한다. 현재 핵심 작업이 어느 지점에서 막혔는지 설명할 수 없으면 기술을 추가한 뒤에도 성공 기준을 세우기 어렵다.

가령 개인 문서에서 답을 찾는 도구가 출처를 자주 놓친다면 먼저 검색할 문서 범위와 정답 예시를 만든다. 그다음 RAG를 붙여 답과 출처가 함께 나오는지 비교할 수 있다. 검색 결과를 읽어 요약하는 것만 필요하다면 Agent의 외부 실행 권한까지 열 이유는 없다.

환경마다 실행 결과가 달라 재현이 깨질 때는 Docker가 후보가 될 수 있고, 외부 전송을 줄여야 하거나 로컬 실행 자체가 요구일 때는 지원 범위를 확인한 뒤 Ollama를 검토할 수 있다. 다만 컨테이너는 이미지·볼륨·비밀 관리가, 로컬 모델은 장비·모델·업데이트·품질 평가가 새 책임으로 들어온다. 문제 하나를 줄이면서 운영 부담을 더 크게 만들지는 않는지 비교한다.

확장은 한 번에 하나씩 적용하고 기존 핵심 작업과 새 실패 조건을 함께 재시험한다. 출처 정확도가 나아지지 않거나, 실행 권한을 안전하게 제한할 수 없거나, 다른 사람이 환경을 재현하지 못하면 그 확장을 보류하거나 제거한다. 작은 구조로 약속을 지킬 수 있다면 추가하지 않는 결정도 완료의 일부다.

공개 버전은 통과한 약속만 묶는다

완료 판정은 아이디어가 더 없다는 뜻이 아니라, 이번 버전이 지킬 약속을 잘라 내는 일이다. 통과한 핵심 작업과 시험 범위, 알려진 제한, 다음 버전으로 넘긴 항목을 함께 적으면 사용자는 현재 결과를 과장 없이 이해할 수 있다. 새 기능 후보는 공개 직전의 통과 범위를 흔들지 않도록 별도 목록에 둔다.

예를 들어 입력·판정·저장·복원이 확인된 정적 앱이라면 그 범위로 배포 후보를 만들 수 있다. 사용자 계정이나 결제를 붙이고 싶더라도 해당 권한과 실패 처리를 시험하지 않았다면 같은 완료 판정에 포함하지 않는다.

릴리스 직전에는 마지막으로 확인한 버전에서 핵심 작업과 공개 경계를 다시 실행하고, 다른 사람이 안내만으로 시작할 수 있는지 본다. 필수 시험이 깨졌다면 날짜를 맞추기 위해 통과로 바꾸지 않는다. 범위를 줄여 다시 판정하거나, 마지막 확인 버전을 유지하고 미통과 기능을 보류한다.