5장. AI는 개발을 어떻게 도와주는가

AI는 코드를 대신 치는 도구가 아니라 일을 맡길 수 있는 동료다

처음 AI 코딩 도구를 접하면 흔히 이렇게 생각한다. "내가 코드를 몰라도 알아서 다 만들어주겠지?" 반은 맞고, 반은 틀리다. AI는 분명 놀라울 만큼 많은 일을 해준다. 프로젝트 구조를 만들고, 파일을 읽고, 코드를 고치고, 테스트를 돌리고, 에러를 설명하고, 문서까지 정리해준다. Claude Code는 실제 프로젝트 폴더를 읽고 수정하며, 자연어로 요청한 작업을 코드 변경까지 이어서 수행할 수 있다.¹ Codex 역시 기능 구현, 리팩터링, 코드 리뷰, 디버깅 같은 개발 작업 전반을 돕도록 설계되어 있다.²

하지만 AI가 잘 일하게 만드는 힘은 "마법의 한 방 프롬프트"에 있지 않다. 핵심은 일을 잘게 나누어 맡기는 능력에 있다. 다시 말해, AI를 잘 쓰는 사람은 코드를 전부 외운 사람이 아니라, 해야 할 일을 구조화해서 전달할 줄 아는 사람이다.

이 감각은 아주 중요하다. 개발을 처음 배우는 사람은 종종 "무엇을 먼저 해야 하지?"에서 막힌다. 반대로 숙련자는 문법보다 먼저 순서를 본다. 화면부터 만들지, 데이터부터 정하지, 로그인부터 붙일지, 검색은 나중에 할지 같은 흐름을 나눈다. AI와 협업할 때도 똑같다. 막연하게 "서비스 하나 만들어줘"라고 던지는 것보다, "회원가입 화면부터 만들자", "글 목록 API를 먼저 만들자", "에러 메시지를 친절하게 바꾸자"처럼 작게 나누는 편이 훨씬 잘된다.

AI가 도와줄 수 있는 일은 생각보다 넓다

많은 사람이 AI를 "코드 생성기" 정도로만 생각하지만, 실제로는 개발의 여러 단계에 걸쳐 도움을 받을 수 있다. 이 책에서 다루는 Claude Code와 Codex도 단순 자동완성기를 넘어, 작업을 읽고 판단하고 실행하는 쪽에 더 가깝다.¹²

개발에서 AI가 맡기 좋은 일은 크게 네 가지 흐름으로 볼 수 있다.

• 기획을 구조화하는 일

• 구현을 시작하고 연결하는 일

• 막힌 문제를 추적하고 고치는 일

• 결과를 설명하고 정리하는 일

이 네 가지는 각각 따로 떨어져 있지 않다. 실제 작업에서는 이어진다. 예를 들어 AI에게 "초보자용 독서 기록 서비스의 핵심 기능을 정리해줘"라고 시키면 기획이 시작된다. 이어서 "이 기능을 기준으로 화면 목록을 나눠줘"라고 하면 구조가 나온다. 그다음 "Next.js로 첫 화면을 만들어줘"라고 하면 구현으로 넘어간다. 이후 "로그인 후 글 저장이 안 되는 이유를 찾아줘"라고 하면 디버깅이 된다. 마지막으로 "지금까지 만든 기능을 README 초안으로 정리해줘"라고 하면 문서화가 된다.

즉, AI는 개발의 앞부분만 돕는 도구가 아니라, 시작부터 정리까지 함께 가는 작업 파트너다.

기획 단계에서 AI는 생각을 말로 바꾸는 데 강하다

초보자가 가장 자주 겪는 문제는 아이디어는 있는데 문장으로 정리가 안 된다는 점이다. 머릿속에는 "뭔가 일정 관리 비슷한 서비스"가 있는데, 막상 만들려고 하면 기능이 흐릿하다. 이럴 때 AI는 생각을 구체적인 문장으로 바꾸는 데 큰 도움이 된다.

예를 들어 AI에게 이렇게 요청할 수 있다.

"직장인을 위한 간단한 회고 서비스 아이디어를 한 줄 소개, 대상 사용자, 핵심 기능 3개, 첫 버전에 넣지 않을 기능으로 나눠 정리해줘."

이 요청의 좋은 점은 범위가 분명하다는 것이다. AI는 이런 구조화 작업에 강하다. 막연한 아이디어를 서비스 설명, 사용자, 화면, 데이터 항목 같은 단위로 바꾸어 준다. 초보자에게는 이것만으로도 큰 진전이다. 머릿속 안개가 문서가 되기 때문이다.

또 AI는 "빠르게 비교해보기"에도 유용하다. 같은 아이디어를 두고 "학생용 버전"과 "직장인용 버전"을 나눠 보게 하거나, "게시판형 서비스"와 "노트형 서비스"의 차이를 설명하게 할 수도 있다. 사람끼리 회의하면 한참 걸릴 수 있는 초안을 몇 분 안에 여러 방향으로 볼 수 있다.

물론 최종 결정은 사람이 해야 한다. 누구를 위한 서비스인지, 무엇을 빼야 하는지, 어떤 톤으로 만들지 같은 판단은 결국 사용자를 이해하는 사람이 하는 편이 좋다. AI는 좋은 정리자이지만, 진짜 책임자는 아니다.

구현 단계에서 AI는 첫 삽을 뜨는 속도를 확 끌어올린다

기획이 어느 정도 정리되면 이제 손을 움직여야 한다. 바로 이 지점에서 많은 초보자가 다시 멈춘다. 파일을 어떻게 시작해야 할지, 폴더를 어떻게 나눠야 할지, 어떤 순서로 만들지 감이 없기 때문이다.

Claude Code는 프로젝트 안에서 코드를 읽고, 변경하고, 간단한 작업을 자연어로 이어서 수행하도록 설계되어 있다. 예를 들어 프로젝트 구조를 파악한 뒤 파일을 고치고, Git 관련 작업이나 코드 변경까지 대화 흐름 안에서 이어갈 수 있다.¹ Codex도 기능 구현, 리팩터링, 리뷰 같은 작업을 가속하는 코딩 파트너로 소개된다.²

초보자 입장에서 이게 왜 좋을까. 첫째, 빈 화면 공포를 줄여준다. 아무것도 없는 폴더를 보고 멍해지는 대신, "회원가입 화면의 기본 레이아웃을 만들어줘", "글 목록 페이지의 뼈대를 잡아줘", "Supabase와 연결할 준비 코드를 만들어줘"처럼 시작점을 만들 수 있다. 둘째, 여러 파일을 같이 손대야 하는 작업에서 길을 잃지 않게 돕는다. 프론트엔드 한 파일만 고쳐서는 안 되고, 타입 파일과 API 호출부와 버튼 컴포넌트까지 함께 손봐야 할 때 AI가 전체 맥락을 묶어 주는 경우가 많다.

다만 여기서 중요한 원칙이 있다. AI에게 서비스 전체를 한 번에 만들라고 하기보다, 한 화면, 한 기능, 한 흐름씩 맡기는 편이 훨씬 낫다.

예를 들어 이런 식이 좋다.

"메인 화면에 서비스 소개 문구와 로그인 버튼만 먼저 만들어줘."

그다음에는 이렇게 간다.

"이제 로그인 성공 후 보일 글 목록 화면의 더미 UI를 만들어줘."

그다음에는 다시 좁힌다.

"목록에서 글 제목, 작성자, 작성일만 보이게 하고, 카드 형태로 정리해줘."

이렇게 하면 검토가 쉽다. 어디까지 됐는지 보이고, 틀린 방향도 빨리 잡을 수 있다. AI에게 일을 잘 맡긴다는 것은 거대한 요구를 잘게 쪼개어 검토 가능한 단위로 바꾸는 뜻이다.

디버깅 단계에서 AI는 '당황'을 '질문'으로 바꿔준다

개발 초보자에게 에러는 가장 무서운 순간이다. 화면은 하얗고, 콘솔에는 빨간 글씨가 쏟아진다. 무엇이 문제인지조차 모르겠고, 검색해도 남의 이야기 같다.

이때 AI의 가장 큰 장점은 에러를 번역해준다는 점이다. Codex는 코드에서 잠재적 버그나 논리 오류, 빠진 예외 처리를 찾아내는 리뷰와 디버깅 작업을 지원한다.³ 즉, 에러 메시지를 그대로 붙여 넣고 "무슨 뜻인지 초보자에게 설명해줘"라고만 해도 출발점이 생긴다.

더 좋은 방법은 에러를 세 단계로 나눠 묻는 것이다.

첫째, "이 에러 메시지가 무슨 뜻이야?"라고 묻는다. 그러면 상황을 이해할 수 있다.

둘째, "원인 후보를 3개만 좁혀줘"라고 묻는다. 그러면 무작정 뒤지지 않게 된다.

셋째, "가장 안전한 수정 순서를 제안해줘"라고 묻는다. 그러면 손대는 범위가 줄어든다.

이 과정이 중요한 이유는, 디버깅이 감정 싸움이 아니라 관찰 싸움이라는 걸 배우게 해주기 때문이다. AI는 초보자가 에러를 보고 얼어붙지 않게 만든다. "망했다"가 아니라 "좋아, 원인을 줄여보자"로 바뀌는 것이다.

또 디버깅에서 AI는 고치는 것만큼 "재발 방지"에도 도움을 준다. 예를 들어 "이 버그를 다시 막기 위한 테스트를 하나 추가해줘"라고 요청할 수 있다. 그러면 단순 봉합이 아니라, 다음 실수를 막는 쪽으로 한 걸음 더 나아간다.

문서화 단계에서 AI는 기억력 좋은 정리 담당자다

개발을 하다 보면 의외로 시간을 많이 잡아먹는 일이 있다. 바로 설명하는 일이다. README를 쓰고, 기능 설명을 정리하고, API 사용법을 적고, 지금까지 바뀐 내용을 요약하는 일 말이다. 재미는 덜하지만, 나중의 나를 위해 꼭 필요하다.

Codex는 코드 설명과 릴리스 전반의 작업을 도울 수 있는 도구로 소개되며, 문서화 역시 대표적인 활용처로 자주 언급된다.² 실제로 AI는 문서화에서 꽤 든든하다. 코드 자체를 읽고 "이 프로젝트가 무엇을 하는지", "어떻게 실행하는지", "어떤 환경변수가 필요한지", "어떤 파일이 핵심인지"를 초안 형태로 정리해줄 수 있기 때문이다.

초보자에게 문서화가 어려운 이유는 두 가지다. 하나는 뭘 써야 하는지 모르기 때문이고, 다른 하나는 다 아는 내용을 다시 쓰는 게 귀찮기 때문이다. AI는 이 두 문제를 동시에 줄여준다. 예를 들어 "이 프로젝트의 README 초안을 설치 방법, 실행 방법, 주요 기능, 폴더 구조로 나눠 작성해줘"라고 시키면 기본 뼈대를 빠르게 만들 수 있다.

다만 문서는 마지막 검토가 특히 중요하다. 실행 명령어 하나만 틀려도 문서는 금방 쓸모없어진다. AI가 초안을 만들고, 사람은 실제로 따라 해보며 고친다고 생각하면 좋다.

Claude Code와 Codex를 함께 쓰면 '한 명이 쓰고, 한 명이 검토하는' 흐름도 가능하다

흥미로운 점은 이 도구들이 서로 완전히 배타적인 관계만은 아니라는 것이다. Claude Code 안에서 Codex를 불러 코드 리뷰를 하거나, 특정 문제를 별도 작업으로 넘기는 플러그인도 제공된다. 이 플러그인은 읽기 전용 코드 리뷰, 더 비판적인 관점의 검토, 버그 조사나 수정 작업 위임 같은 흐름을 지원한다.⁴

이 말은 곧 이런 방식이 가능하다는 뜻이다. 먼저 Claude Code로 기능을 만든다. 그다음 Codex에게 "이 변경사항을 리뷰해줘"라고 시킨다. 또는 "이 구현에서 인증 처리의 위험 요소를 의심해봐"처럼 일부러 삐딱하게 검토하게 만들 수도 있다.⁴

초보자에게 이 흐름이 좋은 이유는 아주 단순하다. 사람도 혼자 만들면 자기 실수를 잘 못 본다. AI도 마찬가지다. 그래서 한 도구에게 만들게 하고, 다른 도구에게 검토하게 하면 생각보다 허점이 잘 보인다. 마치 발표 자료를 만든 뒤 친구에게 "오타 없는지 봐줘"라고 부탁하는 것과 비슷하다.

물론 도구가 두 개라고 해서 자동으로 품질이 보장되지는 않는다. 하지만 "작성"과 "검토"를 분리하는 습관 자체는 매우 건강하다. 앞으로 여러분이 사람과 협업하든, AI와 협업하든 오래 도움이 되는 방식이다.

AI에게 잘 맡기는 사람은 이렇게 말한다

이 장의 핵심 문장을 다시 꺼내보자. AI를 잘 쓰는 사람은 코드를 다 아는 사람이 아니라, 일을 잘 나눠 맡기는 사람이다.

그럼 실제로는 어떻게 맡겨야 할까. 좋은 요청은 대체로 공통점이 있다. 목표가 보이고, 범위가 있고, 결과물이 무엇인지 분명하다.

나쁜 요청은 이런 식이다.

"웹 서비스 하나 만들어줘."

이 요청은 너무 넓다. 어떤 사용자용인지, 무엇을 만들지, 어디까지가 이번 작업인지 아무것도 없다.

조금 나은 요청은 이렇다.

"독서 기록 서비스의 메인 페이지를 만들어줘. 상단에는 서비스 소개 문구, 중간에는 최근 기록 3개 예시 카드, 하단에는 회원가입 버튼이 보이게 해줘."

훨씬 낫지만, 아직도 구현 기준이 조금 흐릴 수 있다.

더 좋은 요청은 이렇게 된다.

"Next.js 기준으로 독서 기록 서비스의 메인 페이지 UI를 만들어줘. 아직 실제 데이터 연결은 하지 말고 더미 데이터로 보여줘. 모바일에서도 무너지지 않게 해줘. 작업 후 어떤 파일을 만들었는지 짧게 설명해줘."

이 요청이 좋은 이유는 작업 범위와 제외 범위가 함께 있기 때문이다. 실제 데이터 연결은 하지 말라고 했고, 어떤 결과를 기대하는지도 적었다. AI는 이런 요청을 훨씬 안정적으로 처리한다.

결국 좋은 협업은 좋은 질문에서 나온다. AI 시대가 와도, 질문하는 힘은 더 중요해진다.

그래도 AI를 무작정 믿으면 안 된다

여기까지 읽으면 AI가 거의 만능처럼 느껴질 수 있다. 하지만 중요한 브레이크를 하나 걸어야 한다. AI는 빠르고 유능하지만, 틀릴 수 있다. 그리고 꽤 그럴듯하게 틀릴 수 있다.

예를 들어 존재하지 않는 라이브러리 사용법을 자연스럽게 지어낼 수도 있고, 보안상 위험한 코드를 아무렇지 않게 제안할 수도 있다. 로그인, 권한 처리, 결제, 개인정보, 환경변수 같은 주제는 특히 조심해야 한다. 돌아간다고 끝이 아니라, 안전해야 하기 때문이다.

그래서 초보자일수록 다음 태도를 기억하면 좋다.

첫째, AI가 만든 코드는 바로 배포하지 않는다. 먼저 실행해보고, 직접 눌러보고, 이상한 점이 없는지 확인한다.

둘째, 중요한 기능은 "왜 이렇게 만들었는지 설명해줘"라고 꼭 되묻는다. 설명을 못 따라가겠다면, 아직 그냥 쓰면 안 된다.

셋째, 큰 변경은 한 번에 합치지 않는다. 작은 단위로 만들고 확인한 뒤 다음 단계로 간다.

AI는 운전대를 대신 잡는 존재가 아니라, 옆자리의 아주 빠른 조수라고 생각하면 좋다. 방향과 책임은 결국 사람에게 있다.

이 책에서의 AI 활용 원칙

앞으로 이 책에서는 Claude Code와 Codex를 단순한 "정답 생성기"로 쓰지 않을 것이다. 대신 다음과 같은 흐름으로 계속 활용할 것이다.

먼저 무엇을 만들지 짧고 분명하게 정리한다. 그다음 작업을 작은 단위로 나눈다. 그리고 AI에게 맡긴 뒤, 결과를 검토하고, 부족한 점을 다시 지시한다. 필요하면 다른 AI 도구로 검토를 한 번 더 받는다. 이 과정을 반복하면서 서비스가 조금씩 완성된다.

이 방식의 장점은 분명하다. 초보자도 전체 개발 흐름을 놓치지 않는다. 그냥 "코드 복붙"으로 끝나지 않고, 왜 이 순서로 가는지 이해하게 된다. 동시에 실제 결과물도 나온다. 배우면서 만드는 것이다.

개발은 원래 거대한 산처럼 보인다. 하지만 AI와 함께하면 그 산을 작은 계단으로 바꿀 수 있다. 한 번에 정상까지 점프하는 건 어렵지만, 한 칸씩 올라가는 건 가능하다. 그리고 그 한 칸을 잘 나누는 사람이, 결국 끝까지 간다.

참고

¹Quickstart - Claude Code Docs

²Codex  OpenAI의 AI 코딩 파트너

³Codex  OpenAI Developers

⁴GitHub - openai/codex-plugin-cc