봉로그

AI 덕분에 설계 없이도 바로 코드를 구현할 수 있는 편리한 시대가 되었습니다.
하지만 무작정 코딩부터 시작하면 결국 ‘바이브 코딩(Vibe Coding) 숙취’라는 심각한 부작용을 겪게 됩니다.
코드 작성이 쉬워진 만큼, 오히려 시스템의 유지보수성과 완성도를 높이기 위한 ‘설계’가 무엇보다 중요해졌습니다.

AI는 어떻게(How) 구현할지는 잘 알지만, 무엇을(What) 만들어야 하는지는 모릅니다.
명확하지 않은 요구사항은 AI가 임의로 판단해 구현할 수밖에 없으며, 이는 결국 ‘Garbage In, Garbage Out(입력의 품질 = 출력의 품질)’으로 이어집니다.
과거에는 잘못된 입력을 넣으면 에러 메시지가 돌아왔지만, 지금의 AI는 어떤 입력이든 그럴듯한 오류(할루시네이션)를 만들어 내기 때문에 더욱 철저한 가이드라인이 필요합니다.

1. 성공적인 AI 협업을 위한 ‘설계’의 정의와 범위

AI에게 명확한 구현 컨텍스트를 제공하기 위해서는 기능별로 요구사항을 잘 정리해야 합니다.
효율적인 AI 개발 프로세스를 위한 설계는 크게 다음 4가지 단계로 나뉩니다.

• 요구사항 분석: 무엇을 만들 것인가? 핵심 기능과 비기능적 요구사항을 명확히 수립합니다.
• 아키텍처 결정: 어떤 기술과 구조로 만들 것인가? 구현부터 빌드/배포에 이르기까지 전 과정에 영향을 미치므로, Claude Code나 Gemini 같은 AI 에이전트의 도움을 받아 결정하는 것도 좋은 방법입니다.
• 인터페이스 정의: API 호출 방식이나 규격 등을 정의하여 데이터를 어떤 식으로 보여줄지, 시스템 간 호출은 어떻게 할지를 미리 작성합니다.
• 작은 단위로 쪼개기: 대규모 맥락으로 설계를 한 번에 진행하면 여러 AI 에이전트 간에 충돌이 일어날 수밖에 없으므로, 설계를 반드시 작은 단위로 분할해야 합니다.

2. 비용과 토큰을 아끼는 ‘다중 AI 에이전트’ 활용 워크플로

구현 단계로 넘어가기 전에 설계를 확정하면 AI 토큰 비용을 크게 절감할 수 있습니다.
무료 티어가 있는 Gemini와 고성능 Claude를 교차 검증하며 마크다운(MD) 파일로 설계 문서를 만드는 최적의 4단계 워크플로를 추천합니다.

• 1단계: 아이디어 정리 (Gemini – 무료)
  • 프롬프트 예시: “~~ 서비스 앱을 만들려고 해. 카카오, 구글 로그인이 필수로 있어야 해. 어떤 요소들을 고려해야 할까?”
• 2단계: 설계 문서 초안 작성 (Gemini – 무료)
  • 프롬프트 예시: “위 요구사항으로 REQUIREMENTS.md 초안을 만들어줘.”
• 3단계: 설계 검토 및 확정 (Claude – 최소 토큰)
  • 프롬프트 예시: “이 설계 문서를 검토해서 개발 스팩에 추가되어야 하거나 기능이 누락된 부분을 알려줘.”
• 4단계: 구현 (Claude Code)
  • 프롬프트 예시: “REQUIREMENTS.md에 따라 백엔드를 구현해줘.”

3. 핵심 프롬프트 원칙: “한 번에 하나의 작업만 요청하기”

AI에게 여러 가지 요구사항을 한꺼번에 요청하면 높은 확률로 반드시 문제가 발생합니다.

1. 기능 및 코드의 전반적인 품질 저하
2. 복합적인 에러 발생으로 인한 디버깅의 어려움
3. 서로 다른 기능 간(클래스, 함수, 파일 단위) 침범으로 인한 컨텍스트 혼란

따라서 기능을 잘게 쪼개고 AI에게 단일 작업만 요구해야 결과물이 명확해집니다.
검증과 피드백이 쉬워져 코드 품질과 제품 완성도가 함께 올라갑니다.
만약 내가 작성한 프롬프트에 “그리고”, “또한”, “추가로”와 같은 단어가 포함되어 있다면, 지금 즉시 작업을 분리해야 합니다.

잘못된 프롬프트 예시 ❌

“사용자 인증 시스템을 만들어줘. 회원가입, 로그인, 로그아웃, 비밀번호 변경, 그리고 이메일 인증과 소셜 로그인도 포함해서.”

올바른 프롬프트 예시 (단계별 단일 요청) ⭕

• 요청 1: “사용자 모델 스키마를 정의해줘 (User). 소셜 유형, 이메일, 비밀번호 해시, 생성일시, 수정일시, 마지막 로그인 일시 포함.”
  • 검증 단계: 스키마가 요구사항에 맞는지 확인  완료 후 다음 단계 진행 ➡️
• 요청 2: “회원가입 API 엔드포인트를 만들어줘. POST /api/auth 이메일, 비밀번호, 소셜 유형을 받음.”
  • 검증 단계: Postman으로 회원가입 테스트  완료 후 다음 단계 진행 ➡️
• 요청 3: “비밀번호 해싱 로직을 구현해줘. bcrypt 사용.”
  • 검증 단계: 저장된 비밀번호가 실제로 해시화되어 저장되는지 확인  완료 후 다음 단계 진행 ➡️
• 요청 4: …
• 요청 5: …

적절한 작업 크기를 결정하는 4가지 기준 💡

작업 크기를 너무 크게 잡으면 실패했을 때 대량의 토큰 손실(비용 낭비)을 입게 됩니다.
다음 가이드라인을 기억하세요.

• 단일 책임 원칙 적용: 하나의 요청은 오직 하나의 책임만 다루어야 합니다.
• 테스트 가능한 단위: 결과물을 독립적으로 테스트할 수 있어야 합니다.
• 10분 내 검증 가능한 크기: AI 출력을 받고, 코드를 훑어보고, 테스트를 돌려보는 총 시간이 10분을 넘는다면 작업을 더 잘게 쪼개야 합니다.
• 파일 혹은 기능 단위의 경계: 회원가입, 로그인, 로그아웃은 경계와 역할이 엄연히 다르므로 확실히 분리되어야 합니다. (Claude Code의 컨텍스트 윈도우 한계도 함께 고려해야 합니다.)

4. AI를 조종하는 명확한 지시의 기술 & 컨텍스트 제한

AI 툴을 사용할 때는 “무엇을 요청했는가”보다 “어떻게 요청했는가”가 훨씬 중요합니다.

• 모호한 지시: “상세 정보를 확인할 수 있는 화면을 구현해줘.” ❌
• 명확한 지시: “상세 정보에는 A, B, C 항목이 출력되어야 하고, D 항목은 마스킹 처리하여 출력되도록 해줘. E 항목은 출력되어선 안 돼.” ⭕

컨텍스트 제한의 5대 원칙 🎯

AI에게 필요한 정보만 정확하게 전달하기 위해 프롬프트에 다음 5가지 요소를 녹여내세요.

1. 목표(What): 무엇을 달성해야 하는가? → 작업의 방향 설정
2. 맥락(Context): 현재 상황과 배경은 무엇인가? → AI가 올바른 가정을 하도록 유도
3. 제약 조건(Constraints): 지켜야 할 규칙은 무엇인가? → 범위를 제한하여 일탈 방지
4. 완료 조건(Done Criteria): 성공을 어떻게 판단하는가? → 명확한 종료 지점 제시
5. 예시(Example): 기대하는 결과의 구체적인 모습은 무엇인가? → 모호함을 제거하여 AI가 적절한 예시를 생성하도록 유도

생산성을 높이는 추가 Tip

• 변경 이력 관리: 설계나 기능이 변경되면 CLAUDE.md, REQUIREMENTS.md 파일에 변경 이력(Change Log) 섹션을 두고 주요 사항을 기록해 두세요. 매번 새로 설정하지 않아도 AI가 이를 자동으로 참조합니다.
• 측정 가능한 완료 조건: “빠르게 동작해야 함”, “코드가 깔끔해야 함” 같은 모호한 조건은 피하세요. ”API 응답은 300ms 이내, 함수 당 30줄 이내, 중복 코드 없음”과 같이 검증 가능한 수치를 적어야 합니다.
• Plan 모드 활용: 본격적인 코드 생성 전, Plan 모드로 계획을 먼저 확인한 후 진행하는 것이 시행착오를 줄이고 토큰을 절약하는 데 유리합니다.

5. 선택이 아닌 필수, “매 단계 리뷰하기”

AI가 생성한 결과물을 코드 리뷰 없이 그대로 수용하면 버그, 보안 취약점, 아키텍처 일관성 깨짐 등의 문제가 코드베이스에 고스란히 쌓이게 됩니다.
AI 시대의 개발자에게 가장 필요한 핵심 역량은 바로 ‘생성된 코드를 정확하게 평가하고 검증하는 능력’입니다.

왜 매 단계마다 리뷰가 필요할까? 🤔

• 오류의 누적 방지: 잘못된 코드를 방치하면 AI는 그 코드를 컨텍스트(문맥)로 삼아 그 위에 또 다른 잘못된 코드를 쌓아 올립니다.
• 방향 수정 비용 최소화: 초기에 발생한 작은 문제가 후속 작업에 계속 영향을 미치기 때문에, 나중에는 처음부터 전체를 롤백(Rollback)해야 하는 불상사가 생길 수 있습니다.
• 학습 기회 제공: AI의 코드를 리뷰하면서 내가 미처 사용해보지 못한 새로운 라이브러리나 최신 지식, 유용한 문법을 배울 수 있습니다.

무엇을 집중적으로 리뷰해야 하는가? 🔍

1) 요구사항 충족 여부

• 요청한 기능이 빠짐없이 모두 포함되어 있는가?
• 요청하지 않은 기능이 추가되지는 않았는가? (AI는 종종 “이것도 필요할 것 같아서”라며 임의로 불필요한 기능을 덧붙이곤 합니다.)
• 엣지 케이스나 예외 상황이 적절히 처리되었는가?
• 입력과 출력의 형식이 예상과 일치하는가?

2) 코드 품질 및 보안

• 가독성, 일관성, 효율성, 안정성이 확보되었는가?
• AI는 특히 보안 측면에서 취약한 코드를 생성하는 경향이 있으므로 각별히 주의해야 합니다.

3) 의도치 않은 변경 사항 (★정말 중요)

AI가 뜬금없이 전혀 상관없는 파일이나 함수를 수정하는 경우가 있으므로 아래 항목들을 꼼꼼히 체크해야 합니다.

• 요청하지 않은 파일이 수정되었는지 확인
• 기존 테스트 코드가 임의로 삭제되거나 비활성화되었는지 확인 (가끔 테스트가 실패하면 AI가 테스트 자체를 무단으로 삭제해 버리는 경우가 있어 주의가 필요합니다)
• 설정 파일이나 환경 변수의 변경 여부
• 의존성(Dependency)의 추가 또는 삭제 여부
• 기존 함수의 시그니처(이름, 파라미터 등) 변경 여부

6. Claude Code 유용한 리뷰 커맨드 및 워크플로

Claude Code를 사용할 때 다음 CLI 커맨드를 적극적으로 활용하는 것도 좋습니다.

명령어	활용 시점	주요 역할
/review	커밋 및 PR(Pull Request) 전	최근 변경된 코드를 PR 리뷰 수준으로 꼼꼼하게 점검
/simplify	기능 구현 완료 및 버그 수정 후	코드 재사용성 향상 및 전반적인 품질 검토
/security-review	보안 민감 코드 작업 후, PR 전	변경 사항을 대상으로 보안 취약점 집중 분석

단계별 리뷰 습관과 되돌리기(Rollback) 전략 🔧

효과적인 리뷰 체계를 구축하기 위해 일관된 개발 워크플로를 유지하는 것이 좋습니다.

• 작은 작업 = 작은 리뷰: 중요한 로직일수록 작업을 작게 나누고, 각 작업이 끝날 때마다 즉시 리뷰합니다.
• 승인 전 실행 및 테스트: 코드를 최종 승인하기 전에 반드시 직접 실행해 보고, 가능하다면 테스트를 먼저 작성하고 실행(TDD)해 봅니다.
• 이해되지 않는 부분 질문하기: 리뷰 중 AI가 작성한 코드가 잘 이해되지 않는다면 AI에게 직접 원리와 설명을 요청하세요.
• Git을 활용한 되돌리기: AI의 작업 방향이 잘못되었을 때 언제든 원하는 안전한 지점으로 되돌아갈 수 있어야 합니다. 그러기 위해서는 커밋 메시지를 구체적이고 명확하게 작성하여 백업 포인트를 확실히 다져두어야 합니다.