AI 코딩은 요구사항 문서부터 써야 결과가 안정된다

• 목록
• 답변
• 글쓰기
• 옵션
  • 수정
  • 삭제

AI에게 “회원가입 페이지를 만들어 줘”라고 입력했는데 예상과 다른 화면이 나온 적이 있나요? 버튼 색이나 문구만 다른 정도라면 고치기 쉽지만, 인증 방식과 데이터 구조까지 어긋나면 생성된 코드를 상당 부분 다시 작성해야 합니다. 이런 문제는 프롬프트를 길게 쓰지 않아서가 아니라 AI가 판단할 기준을 문서로 주지 않았기 때문에 생깁니다.

처음 AI 코딩을 접하는 사람일수록 채팅창에 바로 요구사항을 입력하는 경향이 있습니다. 그러나 작은 프로젝트라도 목적, 사용자, 기능 범위, 완료 조건을 먼저 적어 두면 결과가 훨씬 안정됩니다. 개발 경험이 없어도 만들 수 있는 간단한 요구사항 문서부터 차근차근 살펴보겠습니다.

AI 코딩 요구사항은 프롬프트보다 오래 남습니다

채팅 지시와 요구사항 문서의 차이

프롬프트는 AI에게 지금 수행할 작업을 알려 주는 지시입니다. 반면 AI 코딩 요구사항은 프로젝트가 무엇을 해결하며 어떤 조건을 지켜야 하는지 기록한 기준입니다. “로그인 화면을 만들어 줘”는 프롬프트이고, “이메일과 비밀번호로 로그인하며 5회 실패하면 10분 동안 잠근다”는 요구사항에 가깝습니다.

한 번의 대화에서는 AI가 앞의 내용을 기억하는 것처럼 보여도 작업이 길어지면 세부 조건이 밀려날 수 있습니다. 새 대화를 시작하거나 다른 AI 코딩 도구로 옮기면 맥락은 더 쉽게 끊깁니다. 저장소 안에 문서가 있으면 매 작업마다 같은 기준을 다시 제공할 수 있고, 사람이 코드를 검토할 때도 무엇이 맞고 틀렸는지 판단하기 쉬워집니다.

• 프롬프트: 지금 생성하거나 수정할 작업을 구체적으로 지시합니다.
• 요구사항 문서: 프로젝트의 목적과 범위, 제약 조건을 지속적으로 보존합니다.
• 완료 조건: 작업이 끝났다고 판단할 수 있는 검증 기준을 제시합니다.
• 결정 기록: 왜 특정 기술이나 방식을 선택했는지 남깁니다.

예를 들어 할 일 관리 앱을 만든다면 “예쁜 투두 앱을 만들어 줘”보다 “개인 사용자를 대상으로 하며, 할 일 추가·완료·삭제를 지원하고, 새로고침 후에도 데이터가 남아야 한다”고 쓰는 편이 낫습니다. 여기에 모바일 화면 지원 여부와 로그인 제외 여부까지 적으면 AI가 불필요한 기능을 임의로 추가할 가능성도 줄어듭니다.

초보자 팁: 좋은 문서는 길이가 아니라 판단 가능성으로 평가합니다. AI가 구현 도중 선택해야 할 질문에 문서가 답할 수 있다면 충분히 유용합니다.

한 장짜리 문서는 다섯 항목이면 시작할 수 있습니다

목적부터 제외 범위까지 쓰는 순서

요구사항 문서를 처음부터 전문 기획서처럼 만들 필요는 없습니다. 저장소 최상단에 REQUIREMENTS.md 같은 파일을 만들고 프로젝트 목적, 대상 사용자, 핵심 기능, 제외 범위, 완료 조건을 적어 보세요. 각 항목을 두세 문장으로만 작성해도 구두 설명보다 명확한 기준이 됩니다.

가령 동네 모임 신청 페이지라면 목적은 “운영자가 신청자를 전화로 정리하는 시간을 줄이는 것”입니다. 대상 사용자는 모바일 이용이 많은 참가자와 신청 현황을 확인하는 운영자입니다. 여기서 결제와 소셜 로그인은 첫 버전에서 제외한다고 명시하면 AI가 보기 좋은 기능을 과도하게 붙이는 일을 막을 수 있습니다.

1. 목적: 이 프로그램이 해결할 문제를 한 문장으로 씁니다.
2. 사용자: 누가 어떤 환경에서 사용하는지 적습니다.
3. 핵심 기능: 반드시 작동해야 하는 기능을 우선순위 순으로 나열합니다.
4. 제외 범위: 이번 작업에서 만들지 않을 기능을 분명히 합니다.
5. 완료 조건: 사용자가 직접 확인할 수 있는 결과를 행동 형태로 씁니다.

모호한 표현을 행동과 숫자로 바꾸기

“빠르게”, “안전하게”, “사용하기 쉽게” 같은 말은 방향을 표현하지만 구현 기준으로는 부족합니다. “목록 화면은 일반적인 모바일 네트워크에서 2초 안에 표시한다”, “비밀번호는 화면과 로그에 평문으로 노출하지 않는다”, “주요 작업은 모바일에서 세 번 이내의 터치로 완료한다”처럼 관찰 가능한 문장으로 바꿔야 합니다.

보안 요구사항은 특히 생략하기 쉽습니다. 입력값 검증, 권한 확인, 비밀정보 저장 방식처럼 기본 원칙을 문서에 넣고 필요하면 코드 보안의 개념과 배경을 참고해 용어를 확인할 수 있습니다. 보안이라는 단어만 적는 데 그치지 말고 “다른 사용자의 주문 정보는 URL을 바꿔도 조회할 수 없어야 한다”처럼 서비스 상황에 맞는 조건을 함께 써야 합니다.

화면보다 사용자 행동을 먼저 적어야 합니다

사용자 시나리오가 구현 순서를 결정합니다

초보자는 첫 화면의 색상과 배치부터 정하기 쉽지만, AI 코딩에서는 사용자의 행동 흐름이 더 중요한 출발점입니다. 화면 모양만 설명하면 AI는 그럴듯한 정적 페이지를 만들 수 있지만, 입력한 데이터가 어디에 저장되고 다음 화면에서 어떻게 변하는지는 놓칠 수 있습니다. 사용자가 무엇을 하고 시스템이 어떻게 반응하는지를 먼저 적어야 기능이 연결됩니다.

시나리오는 “사용자는 이메일을 입력한다 → 인증 링크를 받는다 → 링크를 누르면 가입이 완료된다”처럼 단계별로 작성합니다. 실패 상황도 포함해야 합니다. 이미 가입한 이메일을 입력했을 때, 인증 링크가 만료됐을 때, 네트워크가 끊겼을 때 어떤 메시지와 선택지를 제공할지 정하면 AI가 성공 화면만 만드는 문제를 피할 수 있습니다.

• 사용자가 작업을 시작하는 위치와 조건을 적습니다.
• 입력해야 할 정보와 선택할 수 있는 행동을 구분합니다.
• 성공했을 때 바뀌는 데이터와 화면을 설명합니다.
• 실패, 빈 데이터, 중복 요청 같은 예외 상황을 최소 한 개 포함합니다.
• 관리자와 일반 사용자의 권한 차이를 별도로 표시합니다.

완료 조건은 테스트 가능한 문장으로 씁니다

각 시나리오 아래에는 “무엇을 확인하면 끝인가”를 붙이세요. 예를 들어 “사용자가 제목을 입력하고 저장을 누르면 목록 첫 줄에 새 항목이 나타나며, 페이지를 새로고침해도 유지된다”는 훌륭한 완료 조건입니다. 이 문장은 구현 지시이면서 사람이 수행할 수 있는 테스트 절차가 됩니다.

코드 보안도 같은 방식으로 검증할 수 있습니다. “권한을 확인한다”보다 “로그인하지 않은 사용자가 관리자 주소에 접근하면 로그인 화면으로 이동하고 관리자 데이터는 응답에 포함되지 않는다”가 명확합니다. 관련 개념을 더 살펴볼 때는 코드 보안 요약 자료처럼 정의가 분명한 출처를 곁들이되, 실제 프로젝트의 검증 문장은 직접 작성해야 합니다.

화면 캡처만으로 완료를 판정하지 마세요. 데이터 저장, 새로고침, 권한, 오류 복구까지 확인해야 작동하는 제품과 보기만 좋은 시안을 구분할 수 있습니다.

문서를 AI 작업 지시로 바꾸는 순서가 따로 있습니다

한 번에 전부 생성하지 않는 네 단계

요구사항 문서를 작성했다면 AI에게 전체 서비스를 한 번에 완성하라고 요청하지 않는 편이 좋습니다. 작업 범위가 커질수록 AI는 중요한 조건을 일부 생략하거나 여러 파일을 동시에 바꾸면서 오류를 만들기 쉽습니다. 먼저 문서를 읽고 질문하게 한 뒤, 계획을 세우고, 작은 단위로 구현하고, 완료 조건으로 검증하는 순서가 안정적입니다.

1. 문서 검토: “요구사항에서 모호하거나 충돌하는 부분만 질문해 달라”고 요청합니다.
2. 구현 계획: 수정할 파일, 데이터 흐름, 작업 순서를 제안하게 합니다.
3. 작은 구현: 회원가입, 로그인, 프로필처럼 사용자 흐름 하나씩 맡깁니다.
4. 검증: 완료 조건별 테스트 결과와 아직 확인하지 못한 항목을 보고하게 합니다.

실제 프롬프트는 복잡할 필요가 없습니다. “REQUIREMENTS.md를 기준으로 할 일 추가 기능만 구현해 줘. 먼저 관련 파일을 확인하고 변경 계획을 설명한 뒤 작업해 줘. 완료 후 요구사항의 완료 조건별로 검증 결과를 알려 줘” 정도면 충분합니다. 여기서 핵심은 문서 기준, 작업 범위, 선행 확인, 검증 보고를 한 문장 안에 넣는 것입니다.

AI의 제안과 확정된 요구를 분리하기

AI가 새로운 라이브러리나 구조를 제안했다고 해서 요구사항 문서에 곧바로 확정 사항처럼 넣어서는 안 됩니다. 먼저 왜 필요한지, 현재 기술로 해결할 수 없는지, 유지 비용은 얼마인지 질문하세요. 동의한 결정만 문서의 “기술 결정” 항목으로 옮기고 날짜와 이유를 짧게 남기면 나중에 선택을 되돌아보기 쉽습니다.

요구사항이 바뀌면 코드부터 고치는 대신 문서를 먼저 수정하는 습관도 중요합니다. 예를 들어 이메일 로그인에서 소셜 로그인으로 범위가 확대됐다면 사용자 시나리오, 개인정보 항목, 실패 조건이 함께 달라집니다. 문서를 먼저 갱신하고 영향받는 기능 목록을 AI에게 찾게 하면 일부 화면만 고친 채 서버 로직을 놓치는 실수를 줄일 수 있습니다.

• AI가 만든 계획에 요구사항 밖의 기능이 섞였는지 확인합니다.
• 패키지 추가 전 공식 문서, 라이선스, 최근 유지 상태를 확인합니다.
• 변경 파일이 예상보다 많다면 구현을 중단하고 이유를 묻습니다.
• 테스트를 실행하지 못했다면 성공으로 간주하지 않고 미검증으로 표시합니다.
• 문서와 코드가 다르면 어느 쪽을 기준으로 할지 사람이 결정합니다.

모델이 바뀌어도 문서의 검증 기준은 다시 확인해야 합니다

초보자가 실제로 묻는 운영 질문

Q. 개인용 미니 프로젝트에도 문서가 필요한가요?
기능이 하나뿐이고 하루 안에 버릴 실험이라면 짧은 메모로 충분합니다. 하지만 다음 주에도 수정할 프로젝트라면 목적, 핵심 기능, 제외 범위, 완료 조건만이라도 남겨 두세요. 열 줄 안팎의 문서가 대화를 다시 설명하는 시간을 크게 줄여 줍니다.

Q. 문서를 작성한 뒤에도 AI가 요구사항을 무시하면 어떻게 하나요?
전체 문서를 무작정 다시 붙여 넣기보다 위반한 완료 조건을 정확히 가리키세요. “저장 후 새로고침해도 항목이 유지되어야 한다는 조건을 충족하지 못했다. 원인을 조사하고 관련 부분만 수정한 뒤 해당 조건을 다시 테스트하라”처럼 관찰된 결과를 전달하면 수정 범위가 선명해집니다.

Q. 기획을 잘 모르면 AI에게 요구사항 문서를 작성시켜도 되나요?
초안 작성에는 유용하지만 확정은 사용자가 해야 합니다. AI에게 예상 사용자, 빠진 예외 상황, 결정이 필요한 질문을 제안하게 하고 답은 직접 선택하세요. AI가 가정한 결제 정책이나 개인정보 보관 기간을 확인 없이 채택하면 코드가 작동해도 실제 운영과 맞지 않을 수 있습니다.

• 매 기능 작업 전에 현재 문서 버전을 AI가 읽었는지 확인합니다.
• 월 1회 정도 구현된 기능과 문서의 차이를 점검합니다.
• 모델이나 코딩 도구를 바꿀 때 작은 기능으로 지시 이행 수준을 먼저 시험합니다.
• 가격, 지원 모델, 컨텍스트 길이, 데이터 보관 정책은 서비스 공식 안내에서 다시 확인합니다.
• 외부 API와 패키지 버전은 설치 시점의 공식 문서를 기준으로 검증합니다.

도구 변화와 프로젝트 기준을 혼동하지 않기

AI 모델의 성능과 제품 구성은 빠르게 달라집니다. AI 모델 출시 관련 보도에서 보듯 모델 명칭과 제공 일정도 계속 움직일 수 있으므로, 특정 모델 이름을 프로젝트의 영구 요구사항으로 박아 두는 방식은 피하는 편이 좋습니다. “이 모델을 사용한다”보다 “한국어 지시를 처리하고 지정된 테스트를 실행할 수 있는 도구를 사용한다”처럼 필요한 능력을 기준으로 적어 두세요.

구독 가격, 무료 사용량, 지원 언어, 데이터 처리 정책 역시 시간이 지나면 달라질 수 있습니다. 따라서 이런 항목에는 확인 날짜와 출처를 함께 기록하고 실제 도입 직전에 공식 페이지를 다시 살펴야 합니다. 반대로 사용자 시나리오와 완료 조건은 도구가 교체돼도 재사용할 수 있으므로 문서의 중심에 두는 것이 좋습니다. 변하는 제품 정보와 변하지 않아야 할 프로젝트 기준을 분리하는 것이 AI 코딩을 오래 안정적으로 활용하는 출발점입니다.