AI가 틀린 게 아니라, 우리가 가이드를 안 줬던 거다
GitHub Copilot이 생성한 코드가 팀 컨벤션과 전혀 다른 구조로 나올 때, 흔히 '아직 AI가 부족해서'라고 생각한다. 하지만 진단을 바꿔볼 필요가 있다. AI 도구는 입력된 맥락을 기반으로 작동한다. 팀의 설계 철학이 코드베이스 어디에도 명시적으로 기술되지 않아 있다면, AI는 인터넷 평균을 답으로 돌려줄 수밖에 없다. 문제는 도구의 지능이 아니라 우리가 팀의 언어를 충분히 선언하지 않았다는 데 있다.
설계 철학을 코드로 선언하는 FSD
카카오페이 테크 블로그를 포함한 여러 FSD 도입기가 최근 주목받는 이유는 단순히 '폴더 구조를 잘 잡는 법'을 알려주기 때문이 아니다. FSD(Feature-Sliced Design)의 핵심 가치는 설계 의도를 코드 구조 자체에 인코딩한다는 점에 있다.
FSD는 레이어(Layer) → 슬라이스(Slice) → 세그먼트(Segment)의 3계층으로 코드를 조직한다. app > pages > widgets > features > entities > shared로 이어지는 단방향 의존성은 단순한 규칙이 아니라, '이 코드가 얼마나 넓은 범위에서 쓰이는가'라는 질문에 대한 구조적 답변이다. 같은 레이어 내 슬라이스 간 참조를 금지하는 규칙은 응집도를 높이고 결합도를 낮추는 원칙을 아키텍처 레벨에서 강제한다.
세그먼트 네이밍 규칙도 마찬가지다. components나 hooks처럼 기술적 성격이 아닌, ui, api, model처럼 목적을 기술하도록 강제한다. 어떤 개발자가 코드를 열더라도 '이게 뭐 하는 코드인지'를 폴더 이름만으로 즉시 파악할 수 있다.
실제 도입 과정에서는 '혜택 도메인 하나에만 목록·상세·등록·수정 페이지가 존재해 슬라이스가 폭발적으로 늘어난다'는 문제를 맞닥뜨리기도 한다. 이에 동일 도메인 데이터를 다루는 페이지를 슬라이스 그룹으로 묶는 방식을 팀 합의로 채택하고, 레이어 간 임포트 규칙은 그대로 유지하는 실용적 절충을 선택한 사례는 FSD가 경직된 규범이 아니라 팀의 맥락에 따라 조율 가능한 설계 언어임을 보여준다.
폼 검증의 단일 진실 공급원: React Hook Form + Zod
FSD 구조에서 Features 레이어의 model 세그먼트에는 검증 스키마와 내부 상태가 위치한다. 바로 이 지점에서 React Hook Form과 Zod의 조합이 빛난다.
전통적인 controlled input 방식은 폼이 커질수록 상태 관리 로직이 컴포넌트 전체에 흩어지고, 동일한 검증 규칙이 여러 곳에 복사·붙여넣기된다. React Hook Form은 uncontrolled input + ref 기반으로 작동해 불필요한 리렌더링을 제거하고, Zod는 검증 규칙을 스키마로 선언해 단일 진실 공급원(Single Source of Truth)을 만든다.
@hookform/resolvers의 zodResolver를 사용하면 Zod 스키마가 곧 폼 검증 로직이 된다. 이 스키마는 프론트엔드 폼에서만 쓰이는 것이 아니라 API 응답 런타임 검증, 백엔드 공유 타입에도 그대로 재사용할 수 있다. FSD의 Entities 레이어 model 세그먼트에 놓인 Zod 스키마 하나가 프론트엔드 폼과 API 통신 양쪽에서 데이터 신뢰성을 담보하는 구조다.
dev.to의 React Hook Form + Zod 가이드가 강조하는 것처럼, 검증은 단순히 UI에 에러를 표시하는 게 아니다. 잘못된 데이터가 시스템 안으로 유입되는 것을 차단하는 설계 행위다. 스키마가 코드베이스에 명시적으로 선언되어 있다는 사실은, AI 도구가 해당 도메인 코드를 생성할 때 참고할 수 있는 컨텍스트가 이미 존재한다는 의미이기도 하다.
Tone of Voice 파일: AI에게 팀의 언어를 가르치는 법
FSD로 아키텍처를 명시하고, Zod 스키마로 데이터 계약을 선언했다면, 마지막 퍼즐 조각은 AI 도구에게 팀의 코드 리뷰 기준을 알려주는 것이다.
dev.to의 'GitHub Copilot Is Too Nice. Fix It With a Tone of Voice File.' 아티클은 이 문제를 정면으로 다룬다. 기본 설정의 Copilot은 지나치게 정중하다. 애매한 가정을 그대로 수용하고, 잠재적 위험을 언급하지 않으며, 잘못된 결정을 부드럽게 포장한다. 그 결과물은 표면적으로 작동하는 것처럼 보이지만, 팀의 설계 원칙을 위반하거나 불필요한 복잡도를 포함하고 있는 경우가 많다.
해결책은 리포지토리 루트에 voice-instructions.md 파일을 두고 Copilot에게 직접적이고 비판적인 피드백을 요구하는 것이다. 잘못된 가정에 동조하지 않고, 문제가 있을 때 '무엇이 문제인지, 왜 문제인지, 어떻게 고쳐야 하는지'를 명확하게 짚도록 지시한다. FSD의 레이어 의존성 위반, Zod 스키마 없이 인라인 검증을 쓴 코드, 세그먼트 네이밍 컨벤션 위반—이런 패턴들을 팀이 합의한 기준으로 지적하도록 AI를 훈련할 수 있다.
이 접근법의 진짜 힘은 단순히 'AI를 더 엄격하게 만드는 것'이 아니다. 팀의 설계 철학을 AI가 읽을 수 있는 형태로 문서화하는 행위 자체가 온보딩 가이드이자 코드 리뷰 기준이 된다는 점이다.
세 가지를 묶으면 보이는 워크플로우
이 세 가지 접근을 하나의 흐름으로 연결하면 다음과 같은 팀 워크플로우가 완성된다.
- FSD로 아키텍처를 선언한다. 어떤 코드가 어느 레이어에 위치해야 하는지, 의존성 방향은 어떻게 되는지를 폴더 구조 자체로 명시한다. AI는 이 구조를 컨텍스트로 읽는다.
- Zod 스키마로 데이터 계약을 코드화한다. Entities와 Features의
model세그먼트에 스키마를 선언하면, AI가 해당 도메인 코드를 생성할 때 타입과 검증 규칙을 자동으로 참조한다. - Tone of Voice 파일로 AI의 리뷰 기준을 설정한다. 팀이 중요하게 여기는 설계 원칙—단방향 의존성 준수, 불필요한 복잡도 지양, 런타임 안전성 확보—을 AI에게 직접 알려준다.
이 구조가 자리잡히면 AI는 '인터넷 평균 코드'가 아닌 '우리 팀의 코드'를 생성하기 시작한다.
설계 철학을 외재화하는 것이 AI 시대의 경쟁력이다
FSD 도입의 단점으로 흔히 '모든 팀원이 아키텍처를 학습해야 한다'는 점이 꼽힌다. 역설적이게도 이 단점이 AI 시대에는 가장 큰 장점으로 전환된다. 팀이 합의한 설계 원칙이 코드 구조, 스키마, 지시 파일로 외재화되어 있을수록, AI 도구는 더 정확한 컨텍스트를 얻고 팀의 방식에 가까운 결과를 낸다.
빠른 프로토타이핑으로 검증하고 점진적으로 고도화하는 흐름을 중요하게 생각한다면, FSD의 점진적 도입 가능성과 Zod의 스키마 재사용성, Copilot의 커스터마이징 가능성은 함께 쓸 때 시너지가 극대화된다. AI를 더 잘 쓰기 위한 출발점은 더 좋은 프롬프트가 아니라, 팀의 언어를 더 명확하게 선언하는 것이다.