AI가 발전하면 개발 규칙과 도구는 필요 없어질까요. 컴윗이 라이브러리와 화면 재현 환경까지 만드는 이유를 비개발자의 눈높이에서 설명합니다.
AI에게 서비스를 만들어달라고 했더니 화면이 나왔습니다. 버튼도 눌리고, 회원가입도 됩니다. 여기까지 보면 앞으로도 원하는 기능을 말로 설명하기만 하면 될 것 같아요.
그런데 휴대폰으로 열었더니 글자가 잘립니다. 기능 하나를 고쳤더니 다른 버튼이 안 눌립니다. AI는 다 고쳤다고 하는데, 다시 열어보면 그대로입니다.
“지금은 좀 부족해도, AI가 더 좋아지면 해결하겠죠.”
저도 더 좋아질 거라고 생각합니다. 다만 AI가 코드를 만들어준다는 말을, 개발에 필요한 준비까지 생략해도 된다는 뜻으로 받아들이면 곤란합니다.
모델에도 한계가 있습니다. 코드를 읽고 예상하는 것만으로 모든 문제를 알 수는 없어요. 줄바꿈이 어색한지 보려면 화면을 열어보고, 수정하다 다른 기능을 망가뜨렸는지 확인하려면 직접 실행해봅니다. AI도 그런 확인을 할 도구와 환경이 필요합니다.
모델이 발전하면 이 모든 게 필요 없어질까요. 그렇다면 다른 개발자가 만들어둔 도구나 코드도 가져다 쓰지 않고, AI가 처음부터 전부 만들면 되겠네요. 만들 수 있더라도 매번 새로 만들고 검사하는 게 좋은 방법인지는 따져볼 일입니다.
컴윗에서는 AI로 개발하면서 오히려 도구를 더 만들고 있습니다. 반복해서 실수하는 부분을 검사하고, 자주 쓰는 처리는 미리 만들어두고, AI가 실제 화면을 확인할 환경을 갖춥니다.
AI에게 더 많은 일을 맡기고 싶어서 하는 일입니다. “AI가 알아서 하겠지”라고 넘기기 쉬운 준비가 무엇인지, 저희가 만든 것으로 설명해볼게요.
최근 한 개발자의 AI 개발 경험담을 읽었습니다. AI로 만든 제품을 넘겨받았는데, 기능은 돌아가도 구조와 맥락을 파악하기 어려웠다는 경험이 나옵니다. 만든 사람이 AI와 나눈 대화를 다음 개발자가 전부 아는 건 아니니까요.
컴윗에서도 중요하게 보는 문제입니다. 처음 만든 화면만으로 서비스 개발이 끝나지는 않거든요. 상품에 옵션을 붙이고, 주문 취소 조건을 바꾸고, 관리자를 추가합니다. 만든 사람 대신 다른 개발자가 맡을 수도 있고, 다음 작업에서는 다른 AI를 쓸 수도 있어요.
예를 들어 주문 취소 기능을 고친다고 해볼게요. 취소 가능 여부를 한곳에서 정했다면 그 부분을 찾아 수정하면 됩니다. 그런데 주문 목록, 상세 화면, 관리자 화면이 각자 취소 조건을 계산한다면요. 한쪽을 고치고 다른 쪽을 놓칠 수 있습니다. 다음 사람이 보기에는 어느 쪽이 맞는지도 애매하고요.
AI에게 전부 찾아서 고쳐달라고 할 수는 있습니다. 다만 같은 판단을 여러 곳에 써놓을 때마다, AI도 그 관계를 다시 읽고 확인합니다. 이미 한 번 정리할 수 있는 일을 다음 수정 때마다 반복하는 셈이죠.
개발자가 코드 구조를 보는 데에는 이런 이유가 있습니다. 지금 화면이 뜨는지와 함께, 다음 기능을 어디에 어떻게 붙일지도 보는 겁니다.
저도 처음에는 AI에게 주의사항을 알려주는 방식으로 접근했습니다.
예전에 Zustand라는 상태 관리 도구를 쓸 때였어요. 상태는 로그인한 사용자나 현재 선택한 상품처럼 프로그램이 기억하는 값입니다. 여러 사람의 요청을 처리하는 서버에서 이런 값을 잘못 보관하면 문제가 생깁니다. 사용자마다 따로 다룰 값을 같은 곳에 넣어서, 서로 다른 요청이 같은 값을 읽거나 바꿀 수 있거든요.
그래서 요청별로 상태를 나누는 사용법과 제가 원하는 규칙을 AI에게 알려줬습니다. 그런데 여러 작업을 맡기다 보면 그 지침을 빠뜨리더라고요.
다음에는 린트 규칙을 만들었습니다. 린트는 코드에서 정해둔 규칙을 어긴 부분을 찾아주는 도구예요. 제가 금지한 사용법을 검사해서 오류로 알려주도록 했죠.
이제는 잘못 작성한 코드를 찾을 수 있었습니다. 그런데 쓰고, 검사에 걸리고, 다시 고치는 과정은 여전히 남았습니다. 그때마다 시간과 AI 사용량도 더 들었고요.
그래서 라이브러리까지 만들었습니다. 라이브러리는 여러 곳에서 가져다 쓰는 공통 코드입니다. 상태를 어디에 만들고 어떻게 접근할지, 그 사용법 자체에 제가 원하는 구조를 담으려 했습니다.
현재 Comwit State는 상태를 관리할 범위를 정해두고, 각 범위가 자기 값을 따로 보관하도록 구성했습니다. 화면도 그 범위에 연결해서 값을 읽고 바꿉니다. 이런 기본 동작을 AI가 기능마다 새로 작성하지 않도록 공통 도구에 넣은 거예요.
물론 이것만으로 모든 문제가 사라지지는 않습니다. 사용자를 바꾸면 이전 사용자의 값을 지우거나, 기기에 저장한 정보를 사용자별로 나누는 설정도 필요합니다. 다만 매번 상태 관리 방식부터 새로 짜고 같은 주의사항을 설명하는 일은 줄일 수 있습니다.
지침은 사용법을 설명하고, 검사는 위반을 찾고, 라이브러리는 반복할 처리를 구현합니다. 각 방법을 함께 씁니다.
AI가 일을 수행하고 결과를 확인할 수 있도록 지침과 도구, 실행 환경을 갖추는 일을 하네스 엔지니어링이라고 부릅니다. 저는 라이브러리를 만드는 일도 여기에 포함한다고 봅니다.
Anthropic도 장시간 작업하는 에이전트에 관한 실험에서 실행 환경, 진행 기록, 기능 목록, 브라우저 검증을 함께 구성했습니다. 모델에게 요청 한 번을 잘하는 것 외에도 손볼 부분이 있다는 이야기죠.
이 접근을 프로젝트 전체에 적용한 것이 Comwit Template입니다.
컴윗 템플릿 문서의 실제 화면. 화면 표시, 상태 관리, 서버 처리, 데이터 접근을 나눠 연결한 구조입니다.
폴더 몇 개와 예제 화면만 제공하면, AI는 다음 기능을 만들 때마다 어디에 무슨 코드를 놓을지 다시 정합니다. 컴윗에서는 화면을 그리는 코드, 상태를 바꾸는 코드, 서버에서 처리하는 코드, 데이터를 읽고 쓰는 코드를 나누고 서로 연결하는 방향을 정했습니다.
상품 목록을 고치는 상황으로 보면 이렇습니다.
| 준비한 것 | 다음 작업에서 쓰는 방법 |
|---|---|
| AI가 읽을 작업 지침 | 상품 화면과 데이터 처리 코드를 어디에 작성할지 알려줍니다. |
| 코드 구조를 확인하는 검사 도구 | 정해둔 구분을 무시하고 코드를 연결하면 오류를 냅니다. |
| 함께 쓰는 상태 관리 코드 | 상품 목록과 선택한 상품을 같은 사용법으로 관리합니다. |
| 화면을 재현하는 Storybook | 상품이 없거나 요청에 실패했을 때의 모습을 준비해 따로 열어봅니다. |
문서에 적힌 규칙과 프로그램이 검사하는 규칙은 역할이 다릅니다. 문서는 이유와 사용법을 설명합니다. 검사 도구는 자신이 확인할 수 있는 위반을 찾아냅니다. Storybook은 실제 페이지를 여러 상태로 열어볼 환경을 제공합니다. AI가 읽을 지침은 AGENTS.md 같은 파일에 넣고, 전체 구성은 작업 가이드에 정리해뒀습니다.
반복하는 처리도 공통 코드에 넣었습니다. 예를 들어 서버에서 문제가 생겼을 때, 사용자에게 보여주기로 정한 오류 메시지만 화면에 전달합니다. 그 외의 내부 오류는 기록해두고 자세한 내용을 화면에 그대로 내보내지 않습니다. 기능마다 AI에게 오류 전달 방식을 새로 작성시키지 않도록 공통 처리를 마련한 겁니다.
개발자가 이어서 작업할 때도 같은 구성을 봅니다. 어디에서 데이터를 읽는지, 어느 코드가 화면을 담당하는지, 무엇을 실행해서 확인하는지 출발점이 있죠. 다음 AI도 그 기준을 읽고 작업할 수 있고요.
비개발자가 이런 구조를 전부 직접 설계할 필요는 없습니다. 컴윗에서 미리 정리하려는 이유도 거기에 있습니다. 다만 AI가 검사 오류를 냈을 때, 빨리 끝내려고 검사부터 없애면 준비해둔 도구를 쓸 수 없겠죠.
“그냥 서비스를 켜놓고 AI가 보면서 고치면 되는 것 아닌가요?”
간단한 화면이라면 그렇게 할 수 있습니다. 그런데 주문 취소를 마친 뒤 뜨는 팝업의 디자인을 고치고 싶다면요. 글자 크기와 간격을 확인하려고 고객의 주문을 실제로 취소할 수는 없잖아요.
서비스에는 보기만 해도 되는 화면도 있지만, 결제나 삭제처럼 실제 처리를 해야 다음 화면을 보여주는 기능도 있습니다. AI에게 화면을 확인하라고 했다고 아무 버튼이나 누르게 둘 수는 없습니다.
“그러면 내 컴퓨터에서만 실행하면 되겠네요.”
그것만으로 해결하지는 못합니다. 내 컴퓨터에서 실행해도 실제 고객 정보를 보관한 곳이나 결제 서비스에 연결할 수 있으니까요. 테스트용으로 따로 연결했더라도 원하는 화면을 보려면 그에 맞는 데이터와 조건을 준비해야 합니다.
주문 목록을 예로 들어볼게요. 주문이 하나도 없을 때, 상품 이름이 길 때, 취소를 마쳤을 때, 요청에 실패했을 때는 서로 다른 모습을 보여줍니다. 빈 목록의 디자인을 보려고 저장해둔 주문을 전부 지울 수는 없겠죠. 오류 안내를 보려고 서버를 일부러 멈추기도 번거롭고요.
화면과 기능이 많을수록 이런 조건도 늘어납니다. 서비스를 실행할 수 있는 것과, 확인할 화면을 원하는 상태로 열 수 있는 것은 별개입니다. AI가 브라우저를 조작할 줄 알아도, 이 준비 없이 구석구석 확인하기는 어렵습니다.
그래서 컴윗 템플릿에는 페이지를 원하는 상태로 따로 열어보는 Storybook 환경을 넣었습니다. 버튼 하나만 확인하는 것도 부족합니다. 상단 메뉴와 본문, 팝업을 함께 봐야 실제 화면에서 줄바꿈이나 간격이 어색한지 확인할 수 있으니까요.
컴윗은 여기서 실제 서비스의 페이지와 화면 배치, 상태 처리 코드를 그대로 사용합니다.
화면이 서버에 주문 목록을 요청하고 취소 결과를 받는 통로를 API라고 합니다. Storybook에서는 실제 처리를 맡는 서버 대신, 확인에 필요한 응답을 돌려주는 코드를 연결합니다. 이런 방법을 모킹이라고 불러요.
빈 목록을 응답하게 하면 주문을 지우지 않고도 빈 화면을 확인할 수 있습니다. 취소 요청에 성공했다는 응답을 준비하면 실제 주문을 취소하지 않고도 그다음 팝업을 열어볼 수 있고요. 원래 서비스의 코드가 그 응답을 받아 화면을 보여줍니다.
그런데 Storybook을 설치한다고 실제 페이지를 그대로 띄울 수 있는 건 아닙니다. 페이지를 불러오는 순간 서버 코드와 데이터베이스 연결까지 함께 따라온다면, 브라우저에서 화면을 확인하는 Storybook에서는 그 페이지를 실행할 수 없습니다. 버튼 하나는 따로 띄울 수 있어도, 그 버튼이 들어간 실제 페이지 전체는 못 띄우는 거예요. 서버와 연결하는 부분을 교체할 수 있는 구조가 먼저 필요합니다.
이걸 피하려고 Storybook용 화면을 별도로 만들거나, “Storybook일 때는 이 코드를 실행하라”는 처리를 여기저기 넣을 수도 있습니다. 그러면 확인용 코드와 실제 서비스 코드가 달라집니다. 별도로 만든 화면의 디자인을 고쳐놓고, 실제 서비스에 또 옮겨야 하는 거죠. AI가 꼼꼼히 확인하고 고쳤어도 정작 고객이 보는 화면은 그대로일 수 있습니다. 실제 화면을 확인하려고 준비한 환경인데, 다른 화면을 고치고 있으면 무슨 의미가 있을까요. 이중으로 관리할 일만 늘어납니다.
컴윗에서는 API를 담당하는 부분의 연결만 바꾸도록 구조를 정했습니다. 화면, 상태 관리, 서버 처리를 나눠두었으니 교체할 위치가 분명합니다. 개발자가 이런 구분을 레이어라고 부릅니다.
각 페이지에 맞는 확인용 응답은 준비해야 합니다. 다만 그 응답을 연결하려고 원래 페이지 코드까지 고칠 필요는 없어요. 모킹을 빠뜨렸거나 서버 내부 코드를 직접 불러오면 Storybook 쪽에서 오류를 내도록 했습니다.
화면 코드는 함께 쓰고 API 연결을 교체합니다. 빈 목록이나 요청 실패 같은 상태는 각 페이지에 맞는 모킹 응답으로 준비합니다.
이렇게 준비한 페이지를 AI가 열어보고, 화면 폭을 줄여 줄바꿈을 확인하고, 수정한 뒤 같은 조건으로 다시 살펴볼 수 있습니다. 실제 데이터를 바꿔가며 원하는 상황을 만드는 수고도 줄고요.
실제 템플릿의 ‘내 계정’ 페이지입니다. 미리 작성한 확인 절차가 서로 다른 비밀번호를 입력하고 버튼을 눌러 오류를 재현합니다. 주변 메뉴도 서비스에서 쓰는 코드를 그대로 불러옵니다.
실제 인증과 저장, 결제까지 제대로 처리하는지는 별도의 테스트 환경에서 확인합니다. Storybook은 화면과 상호작용을 반복해서 살펴볼 환경입니다.
레이어를 나누자는 말이 코드 정리 취향처럼 들릴 수도 있습니다. 그런데 그 구조 덕분에 AI에게 실제 주문을 건드리지 않고도 취소 뒤의 화면을 확인하게 할 수 있습니다. 컴윗이 디자인을 꼼꼼히 확인할 도구와 코드 구조를 함께 준비하는 이유입니다.
“모델이 더 똑똑해지면, 이런 규칙도 알아서 생각해내지 않을까요?”
좋은 방법을 제안하는 능력은 더 좋아질 수 있습니다. 다만 그중 어떤 방법을 우리 서비스에 일관되게 적용할지는 또 다른 문제예요. 이 차이는 앞서 쓴 LLM이 전문가를 대체 못 하는 이유에서 자세히 다뤘습니다.
개발에는 목적에 따라 선택이 다른 문제도 많습니다. 하루 동안 아이디어만 확인할 팀이라면, 일단 화면을 빠르게 만드는 쪽을 택할 수 있습니다. 여러 사람이 오래 운영할 서비스라면, 처음에 시간을 더 써서 수정과 검사를 쉽게 할 구조를 준비할 수 있고요.
모델은 두 방법을 모두 알 수 있습니다. 하지만 “우리는 처음에 좀 더 준비하더라도 실제 페이지를 그대로 재현할 수 있게 만든다”는 건 컴윗이 택한 기준입니다. 모든 프로젝트에 똑같이 적용할 유일한 정답은 아니죠. 모델이 더 많은 개발 지식을 배웠다는 이유만으로 우리 기준을 매번 먼저 선택한다고 볼 수는 없습니다.
회사 안에만 있는 사정도 있습니다. 어떤 도구를 쓰다가 운영 중에 문제가 있었는지, 다음에 코드를 맡을 사람이 무엇에 익숙한지, 어떤 고객 정보는 테스트에도 사용하지 않기로 했는지요. 이런 내용을 알려주거나 찾아볼 수 있게 하지 않으면, 더 좋은 모델도 우리 회사가 어떤 결정을 했는지 정확히 알 수 없습니다.
경제적인 이유도 있습니다. 범용 모델을 만드는 회사는 서로 다른 요구를 가진 고객에게 같은 모델을 제공합니다. 특정 회사의 판단을 모든 고객의 기본값으로 삼기는 어렵고, 회사마다 다른 내부 경험을 모아 별도 모델을 계속 학습시키는 데에는 비용이 듭니다. 저는 이 때문에 각 회사의 기준을 모델 바깥의 지침과 도구에 담는 접근이 계속 필요하다고 봅니다.
이건 시간이 지나면 저절로 없어질 성능 부족과는 다릅니다. 회사마다 원하는 결과와 감수할 비용이 다르고, 그 기준도 계속 바뀝니다. 모델의 지능이 높아지는 것만으로는 서로 다른 기준을 하나로 정하거나, 전달하지 않은 내부 결정을 알아낼 수 없습니다.
AI에게 기록을 읽고 기준을 정리하게 하거나, 도구를 고르고 만드는 일까지 맡길 수는 있습니다. 그래도 읽을 기록과 사용할 도구를 실제로 연결하고, 그 기준대로 결과가 나오는지 확인하는 과정은 필요합니다. 전문가의 판단을 담은 도구가 일을 대신하는 것과, 범용 모델의 다음 버전을 기다리는 것은 여기서 차이가 납니다.
컴윗에서는 그 판단을 템플릿과 라이브러리에 담았습니다. 매번 AI에게 처음부터 같은 선택을 다시 시키지 않고, 이미 정한 구조와 공통 코드를 가져다 쓰도록 하는 거예요.
주문 취소 조건을 한곳에서 관리하면 수정할 곳을 줄일 수 있습니다. 수정한 뒤에는 연결된 각 화면도 확인합니다.
물론 기존 규칙을 전부 유지할 이유는 없습니다. 앞서 소개한 개발자의 경험담에도 빡빡한 검사가 새 기능 개발을 방해했고, 모델을 바꾼 뒤에는 작업 절차를 간소화했다는 이야기가 나옵니다. 모델이 이미 잘하는 일을 일일이 설명할 필요는 줄어들겠죠.
저희도 규칙마다 어떤 실수를 막는지, 반복 작업을 얼마나 줄이는지 따져보고 고칠 수 있습니다. 다만 “다음 모델이 알아서 하겠지”라는 기대만으로 우리 서비스의 기준까지 없애지는 않습니다.
솔직히 이 부분에서는 답답할 때가 있습니다. 조언을 구하러 오셨는데, 정작 코드에 문제가 있다고 말씀드리면 받아들이지 못하는 경우요.
기술 선택도 그렇습니다. 만들려는 기능에 비해 지나치게 복잡한 구성을 골랐거나, 서로 잘 맞지 않는 기술을 억지로 붙여놓은 경우가 있습니다. 이어받을 개발자도 유지하기 어렵고, 더 단순하게 만들 방법도 있어요. 그래서 왜 바꾸자는지 설명을 드립니다.
그런데 구조도 그대로, 기술도 그대로, 지금까지 만든 코드도 그대로 두고 해결할 방법을 원하십니다. AI는 가능하다고 했다면서요.
조언을 구하셨는데, 답은 이미 정해놓고 오신 거죠.
강형욱에게 반려견 훈련을, 백종원에게 가게 운영을 상담한다고 생각해볼게요. 문제를 고치려고 전문가를 불렀는데, 평소 하던 방식을 바꿔보자는 말에는 “그건 싫고요”라고 합니다. 그러면 도와줄 사람도 할 수 있는 일이 별로 없습니다.
개발도 마찬가지예요. 지금 선택을 유지해야 하는 사정이 있다면 같이 따져볼 수 있습니다. 이미 고객이 쓰고 있다거나, 바꾸는 데 쓸 시간이 부족하다거나요. 그런데 그런 조건을 검토하지도 않고, 내가 고른 방법이 맞다는 답만 듣고 싶다면 상담을 계속하기 어렵습니다.
“AI가 할 수 있다고 했어요”라는 말도 그 판단을 대신하지는 못합니다. 만드는 데 드는 시간, 오류를 찾는 과정, 다음 기능을 붙일 때의 비용까지 봐야 하니까요. AI가 가능하다고 설명한 것과, 우리 팀이 계속 운영할 만한 선택인지는 따로 확인합니다.
만들기는 내 방식대로 하고, 문제가 생겼을 때만 개발자가 해결해주길 바라면 같이 일하기 어렵습니다. 그 개발자도 AI를 씁니다. 그래도 바꾸자고 한다면, 왜 그런 말을 하는지는 한 번 들어봤으면 좋겠습니다.
여러분이 잘 만들어오면 개발자도 편합니다. 구조를 파악하고 고치는 데 쓸 시간을 다음 기능에 쓸 수 있으니까요. 나중에 우리가 이어받아 작업하기도 편했으면 하는 마음, 당연히 있습니다.
그래서 규칙을 알려드리고, 템플릿을 만들고, 라이브러리도 제공합니다. 비개발자가 처음부터 시행착오를 전부 겪을 필요는 없으니까요. 개발자가 겪었던 문제를 미리 피해서 만들면, 만드는 분도 덜 고생하고 도와주는 쪽도 덜 고생합니다.
개발자에게도 설명할 몫은 있습니다. “원래 이렇게 합니다”만으로는 부족하죠. 어떤 오류를 막는지, 지금 선택이 왜 유지하기 어려운지, 대안에는 무슨 비용이 있는지 설명할 수 있어야 합니다. 저희도 그 이유를 문서에 적고, 검사 도구와 라이브러리로 구현하려고 합니다.
그 설명까지 듣고 납득했다면, 그 방법을 실제 작업에도 적용해봤으면 좋겠습니다. 다음 AI가 “이 검사는 지워도 됩니다”라고 했다고 바로 지워버리면, 같은 문제를 또 만날 수 있으니까요.
AI로 직접 서비스를 만드는 사람은 앞으로도 많을 거라고 생각합니다. 저희도 더 많은 사람이 자기 아이디어를 만들어보길 바랍니다.
그래서 처음 만드는 일과 함께, 계속 고치는 일도 쉽게 만들고 싶습니다. 새 기능을 붙일 때 코드를 어디에 둘지 알 수 있고, 잘못 연결하면 검사에서 찾고, 수정한 화면을 다시 확인할 수 있도록요. 컴윗에서 템플릿과 라이브러리를 만드는 목적입니다.
지금 AI와 서비스를 만들고 있다면, 첫 화면을 띄운 뒤 작은 요구사항 하나를 바꿔보면 좋겠습니다. 그때도 기존 기능을 유지하며 고칠 수 있는지까지 보면, 지금 쓰는 개발 방식이 나에게 얼마나 도움이 되는지 더 구체적으로 알 수 있을 것 같아요.
첫 댓글을 남겨보세요.