# AI에게 좋은 코드를 기대하지 않습니다

> **Summary:** AI가 코드를 쏟아내면서 검증 비용이 병목이 됐습니다. 흔한 해법은 리뷰 강화지만, 그건 부담을 다시 사람에게 떠넘기는 일입니다. Pivot Studio는 사내 코어 pivot-forge를 만들며 다른 길을 택했습니다. AI에게 좋은 코드를 기대하는 대신, 토큰·검증·권한 가드를 코드 구조로 미리 박아 '나쁜 코드를 짤 수 없는 틀'을 설계하는 방식입니다.

AI guardrails scaffold

AI 어시스턴트에게 한두 문장을 던지면 수십 줄의 코드가 순식간에 완성됩니다. 코드를 짜는 비용은 거의 0에 수렴했죠. 그런데 이상하게도 팀의 속도는 그만큼 빨라지지 않습니다. 쏟아지는 코드를 읽고, 검증하고, 안전하게 배포해도 되는지 판단하는 비용은 그대로이기 때문입니다.

여기서 대부분의 팀이 내리는 결론은 "그러니 리뷰를 강화하자"입니다. 하지만 이건 병목을 다시 사람에게 떠넘기는 일입니다. 생성은 기계가 하고 검증은 인간이 하는 구조에서는, 코드가 빨라질수록 리뷰어만 더 지칩니다. 우리는 다른 길을 택했습니다. 리뷰할 거리 자체를 줄이는 것. 그것도 잔소리나 지침이 아니라 **코드 구조로** 줄이는 것입니다.

이 글은 Pivot Studio가 클라이언트 사이트를 제작할 때 실제로 쓰는 코어 툴을 예로, "AI에게 좋은 코드를 기대하지 않고, 나쁜 코드를 짤 수 없는 틀을 먼저 짠다"는 접근을 정리한 것입니다.

## 왜 리뷰를 강화하는 것만으로는 부족할까요?

검증 비용의 본질이 인간의 인지 능력에 묶여 있기 때문입니다. 코드를 *쓰는* 능력과 *읽고 판단하는* 능력은 서로 다른 작업이고, 작성이 빨라진다고 판단이 빨라지지는 않습니다. AI가 하루에 수십 개의 변경을 만들어내는데 사람이 한 줄씩 다시 읽어야 한다면, 결국 "리뷰가 곧 고무도장"이 되거나 검증되지 않은 코드가 쌓이거나 둘 중 하나입니다.

그래서 질문을 바꿔야 합니다. "어떻게 더 잘 리뷰할까"가 아니라 **"애초에 리뷰할 것을 어떻게 줄일까"**입니다. AI가 자유롭게 생성하되, 벗어날 수 없는 운동장을 먼저 그려두면 됩니다. 틀린 길로 갈 *물리적 자리*가 없으면, 사람은 틀린 길을 검사할 필요도 없어집니다. 아래는 그 운동장을 이루는 네 개의 벽입니다.

## AI가 색과 간격을 제멋대로 쓰지 않게 하려면?

값을 직접 쓸 자리를 없애면 됩니다. 우리 코드베이스에는 임의의 색(raw hex)이나 임의의 px를 쓸 곳이 아예 없습니다. 색·간격·타이포는 전부 의미가 정해진 토큰 유틸리티로만 존재합니다. "여기 파란색 5만큼"이 아니라 "여기 브랜드 색, 여기 본문 크기"처럼, 숫자가 아니라 역할로만 지정하게 되어 있습니다.

토큰은 raw 팔레트 → semantic → surface 3계층으로 정리돼 있고, 브랜드 색과 다크모드는 토큰이 알아서 전환합니다. 그래서 AI가 "대충 파란 버튼"을 만들어도 그게 곧 브랜드 색이고, 다크모드에서도 자동으로 맞습니다. 일관성이 AI의 취향이나 주의력에서 나오는 게 아니라, **구조에서 강제로 나옵니다.** 디자이너가 토큰만 바꾸면 모든 화면이 한 번에 따라옵니다.

design token layers

## AI가 만든 폼에서 보안이 새지 않으려면?

검증을 "잘 짜주길" 기대하는 대신, 검증이 빠질 구조적 여지를 없앱니다. 우리는 데이터 스키마 하나로 클라이언트 검증·서버 검증·타입을 전부 파생시킵니다. AI가 새 폼을 만들 때 같은 스키마를 양쪽에서 쓰게 되어 있어서, "서버 재검증을 깜빡하는" 일이 일어나기 어렵습니다.

그리고 한 가지 원칙을 코드로 못 박아 둡니다. **클라이언트는 절대 믿지 않는다.** 공개 사용자가 보내는 값 중 권한이 필요한 필드는 서버가 강제로 덮어씁니다. 예를 들어 공개 글쓰기 폼에서 누군가 "이 글을 발행 상태로" "추천 글로" 같은 값을 몰래 끼워 보내도, 서버는 그걸 무시하고 항상 초안·비추천으로 저장합니다. 발행이나 추천 같은 권한은 관리자만 정할 수 있도록 경계가 코드에 박혀 있는 것이죠.

AI가 화면을 아무리 빨리 찍어내도, "무엇을 사용자가 정할 수 있는가" 같은 보안 경계는 사람이 짠 골격이 계속 쥐고 있습니다.

## AI가 새 기능을 추가하다 인증을 빠뜨리면요?

이게 핵심입니다. "조심해서 리뷰하자"가 아니라, **빠뜨리면 통과하지 못하게** 만들어 둡니다. 보호가 필요한 관리자 API는 첫 줄에서 권한을 확인하게 되어 있는데, AI가 새 관리자 라우트를 추가하면서 이 확인을 빼먹으면 테스트가 실패해 빌드가 빨간불을 켭니다. 모든 관리자 핸들러에 권한 검사가 들어 있는지를 자동으로 훑어보고, 하나라도 빠지면 배포를 막는 식입니다.

서버를 띄우는 무거운 테스트가 아니라, "이 불변식이 코드에 존재하는가"를 검사하는 가벼운 구조 가드입니다. 사람의 기억력 대신 자동 안전망이 1차 리뷰를 대신합니다. 빠른 생성과 안전한 배포가 충돌하지 않는 건, 이렇게 **테스트가 검증의 일부를 자동으로 떠맡기** 때문입니다. 사실 AI 협업과 무분별한 "바이브 코딩"을 가르는 진짜 분기점이 바로 이 지점입니다. 견고한 테스트가 있어야 에이전트가 통과할 때까지 스스로 반복하고, 없으면 깨진 코드 위에서 천연덕스럽게 "완료"를 선언합니다.

## 그래도 코드만으로는 못 막는 게 있지 않나요?

맞습니다. 그리고 여기서 정직해야 합니다. 틀이 막아주는 건 "기계적으로 틀릴 수 있는 것"까지입니다. 색을 잘못 쓰는 것, 검증을 빠뜨리는 것, 게이트를 누락하는 것 — 이런 건 구조로 봉합됩니다. 하지만 "이 기능이 이 비즈니스에 맞는가", "이 추상화가 지금 필요한가", "코드만 봐서는 알 수 없는 배포 함정" 같은 판단은 여전히 사람의 몫입니다.

오히려 그래서 우리는 미리 만들지 않는 걸 원칙으로 둡니다. 재사용할 구조는 상상으로 추상화하는 게 아니라, 실제 프로젝트 서너 개에서 반복되는 걸 *추출*해서 만듭니다(YAGNI). 인프라가 갈리는 부분(이메일·저장소·DB 드라이버 등)은 갈아끼울 자리만 비워두고, 실제로 필요해질 때 채웁니다. AI는 그 비워둔 자리를 메우는 데 강하지, 어디를 비워둘지 결정하는 데 강한 게 아닙니다. 운동장의 선을 긋는 일 — 그게 사람이 끝까지 쥐는 판단입니다.

## 그럼 지금 당장 무엇부터 만들면 될까요?

리뷰 프로세스를 강화하기 전에, **가드레일부터 까세요.** 순서가 중요합니다. 타입 검사, 린트, "any 금지" 같은 규칙을 먼저 깔고 그 위에서 AI에게 생성을 맡기면, "보기엔 그럴듯한 코드"가 "검증된 코드"로 바뀝니다. 반대로 가드레일 없이 생성부터 시키면, 어디서 무너지는지 추적이 안 됩니다.

그다음은 반복을 관찰하는 일입니다. 클라이언트 프로젝트 서너 개를 진행하다 보면 매번 똑같이 다시 짜는 부분이 보입니다. 그게 추출해서 틀에 넣을 후보입니다. 처음부터 완벽한 보일러플레이트를 설계하려 들지 말고, 같은 코드를 세 번째 다시 짤 때 비로소 틀로 올리세요. 틀은 한 번에 완성되는 게 아니라, 실전이 깎아내는 것입니다.

AI로 개발 속도를 높이는 건 이제 기본입니다. 진짜 경쟁력은 그 속도가 팀을 망가뜨리지 않도록, AI가 안전하게 뛸 운동장을 먼저 설계하는 능력에 있습니다. 빨리 짜는 기술이 아니라, 틀을 설계하는 판단 — 그게 다음 세대 개발 팀이 가져야 할 능력입니다. 지금 우리 팀의 코드베이스는, AI가 들어와도 길을 잃지 않을 만큼 잘 정돈돼 있나요?

---
*Source: [Pivot Studio](https://pivotstudio.co.kr/insights/ai-friendly-template-guardrails)*
*Published: 2026-06-15*