개발자의 시간을 벌어주는 두 가지 도구: 잘 쓴 테크 스펙, 그리고 AI

컬리 프로덕트 웹개발 팀의 테크 스펙 정착기와 AI 자동화 시도

한승희 게시 날짜: 2025.12.04.

• 1. 들어가며: 문서, 꼭 써야 하나요?
• 2. 테크 스펙이란 무엇인가요?
  • 1) 개요
  • 2) 작업 계획
  • 3) 구현
  • 4) 프로젝트 정보
• 3. 무엇이 좋아졌나요?
• 4. 실전 사례: 상품 쿠폰 프로젝트
  • ① 예상치 못한 이슈, 문서 위에서 해결하다
  • ② 플랫폼 환경까지 고려한 선제적 대응
  • ③ 감이 아닌 데이터로 산정하는 일정
• 5. AI로 자동화할 수 없을까?
  • 5.1. Input: 기획자가 건네준 PRD
  • 5.2. Output: AI가 작성한 테크 스펙 초안
    • [Tech Spec] 간단한 할 일 체크 페이지 개발
  • 5.3. 이것이 우리에게 가져다준 변화
• 6. 마치며: 기록이 만드는 성장의 선순환

안녕하세요. 컬리 프로덕트 웹개발 한승희입니다. 오늘은 컬리 상품 코어 프론트엔드 팀이 2023년 도입해 이제는 개발 문화의 핵심으로 자리 잡은 '테크 스펙(Tech Spec)'과 더불어, 최근 시도 중인 AI 자동화에 대해 이야기 해보려 합니다.

1. 들어가며: 문서, 꼭 써야 하나요?

개발자라면 누구나 한 번쯤 "문서, 꼭 써야 할까?"라는 생각을 해 보았을 것입니다. 그 시간에 코드를 한 줄이라도 더 짜는 게 효율적이지 않을까 고민하는 것이죠. 그렇지만 담당자가 바뀌거나 시간이 흐른 뒤 마주하는 레거시 코드 앞에서, 비로소 우리는 기록의 부재를 뼈저리게 실감하게 됩니다. 파편화된 문서들과 설명이 부족한 PR, 그리고 사라진 슬랙 메시지들에게서는 충분한 답을 얻기 어렵기 때문입니다.

팀에서도 비슷한 고민이 있었지만 '테크 스펙'을 도입하고 꾸준히 다듬어오면서 문서는 '짐'이 아닌 강력한 '무기'가 되었습니다. 이 문화를 통해 팀 내부적으로는 표준화된 양식 덕분에 누구나 부담 없이 문서를 작성하고 자연스럽게 지식을 공유하는 문화가 자리 잡았습니다. 더불어 팀 외부적으로는 구체적인 작업 계획과 기술적 근거를 제시함으로써 일정의 신뢰도를 높이고, 유관 부서와 투명하게 소통하는 창구가 되었습니다.

이제부터 저희가 어떻게 이 문화를 정착시켰는지, 실제 사례와 함께 소개해 드리겠습니다.

2. 테크 스펙이란 무엇인가요?

테크 스펙은 기술(Tech) + 설명서(Spec)입니다. 단순히 개발할 기능을 나열하는 것에서 더 나아가, 개발자의 관점에서 이것을 '어떻게' 구현할 지 설계하는 청사진입니다. 몇 번의 시행착오를 거친 끝에 팀에서 가장 효율적으로 사용하고 있는 구성입니다.

1) 개요

기획서 혹은 PRD를 개발자의 언어로 재해석하는 단계입니다. 단순하게 어떤 기능을 만든다를 넘어, 프로젝트의 맥락과 배경을 입체적으로 이해하기 위해 아래와 같이 두 관점을 모두 고려합니다.

• 비즈니스적 관점: 이 기능이 고객에게 어떤 가치를 주고 어떤 임팩트를 만들어 내는지 정의합니다. 기능을 개발하는 이유에 대한 답을 스스로 내림으로써, 개발자는 단순히 코더가 아니라 제품을 함께 만들어 가는 메이커로 몰입할 수 있습니다.

• 기술적 관점: 이번 작업을 통해 가지는 기술적인 의미를 정리합니다. 기존 레거시 코드를 리팩토링하거나, 혹은 향후 유지보수를 위해 어떻게 구조적인 개선을 할 수 있을지 고민합니다. 이를 통해 기술 부채를 해결하거나 확장성을 고려한 설계의 기회로 삼습니다.

2) 작업 계획

실제 개발에 들어가기 전, 작업의 단위를 쪼개고 설계하는 핵심 단계입니다.

• 작업 방향: 기획서를 바탕으로 개발자가 수행할 구체적인 태스크들을 나눕니다. 이 단계에서 도출한 작업 단위들은 그대로 Jira 업무 티켓이 되어, 체계적인 일정 관리와 업무 분배의 기준이 됩니다. 함께 프로젝트에 참여하는 사람들은 이 문서를 통해 누가 어떤 영역을 작업하고 있는지, 진행 상황은 어떤지 투명하게 파악할 수 있습니다.

• 이외 고려사항: 기술적 제약 사항이나 예외 케이스를 미리 검토합니다. 혹은 의도적으로 개발하지 않는 부분에 대해서 기록해 둡니다.

3) 구현

코드를 작성하기 전 핵심 로직을 설계하거나, 개발을 진행하며 마주한 트러블 슈팅 과정을 기록합니다. 복잡한 로직은 의사 코드(pseudo-code)나 다이어그램으로 미리 그려볼 수 있습니다. 또한 개발 도중 발생한 이슈와 해결 과정을 기록함으로써 추후 유사한 문제가 발생했을 때 참고할 수 있는 지식 자산으로 남깁니다.

4) 프로젝트 정보

프로젝트의 전체적인 흐름을 한눈에 조망합니다.

• 마일스톤: 프론트엔드 개발 일정뿐만 아니라, 디자인 가이드 전달, API 개발, QA 기간, 배포 일정 등 유관 부서의 스케줄까지 통합하여 관리합니다. 이를 통해 병목 구간을 미리 파악하고 협업 부서와 싱크를 맞춥니다.

• 관련 문서: 기획서, 디자인 시안, 연관 Jira 티켓 등 프로젝트와 관련된 링크를 찾기 쉽게 모아둡니다.

3. 무엇이 좋아졌나요?

테크 스펙 도입 후, 팀에는 크게 두 가지 긍정적인 변화가 있었습니다.

첫 번째는 코드 리뷰 효율의 상승입니다. 기존에는 PR을 올리면 어떤 맥락에서 수정했는지 설명하고 이해시키는 데 상당한 시간이 소요되었습니다. 리뷰어가 코드의 의도를 파악하고 피드백을 주기까지 길게는 1~2일이 걸리기도 했죠. 하지만 테크 스펙이 도입된 후에는 상황이 달라졌습니다. 문서에 이미 개발 배경과 의도가 명확히 기술되어 있어, 리뷰어는 코드를 보기 전에 어떤 맥락에서 코드를 이렇게 짰는지를 완벽하게 이해할 수 있게 되었습니다. 덕분에 리뷰 시간은 1~2시간 내외로 단축되었고, 단순한 문법 체크를 넘어선 깊이 있는 논의가 가능해졌습니다.

두 번째는 팀 전체의 생산성 향상입니다. 기획 단계에서 미처 발견하지 못한 이슈를 설계 단계에서 미리 찾아내고 해결함으로써, 개발 도중 발생하는 불필요한 커뮤니케이션 비용과 재작업이 현저히 줄어들었습니다. 결과적으로 팀은 더 빠르고 정확하게 제품을 만들어낼 수 있게 되었습니다.

4. 실전 사례: 상품 쿠폰 프로젝트

최근 진행했던 상품 상세 페이지 내 쿠폰 적용가 노출 및 다운로드 프로젝트를 통해 테크 스펙이 어떻게 활용되는지 보여드리겠습니다.

① 예상치 못한 이슈, 문서 위에서 해결하다

상품 쿠폰 프로젝트 개발이 한창 진행되던 중, 기획, 백엔드, 프론트엔드 모두 예상치 못한 이슈가 발생했습니다. 바로 '멀티 딜 상품의 중복 쿠폰 다운로드' 문제였습니다. 하나의 상품 페이지에 여러 옵션(딜1, 딜2)이 존재할 때, 동일한 ID를 가진 쿠폰이 얽혀 있어 버튼 하나를 누르면 모든 딜의 쿠폰이 한꺼번에 다운로드되는 현상이 발견된 것입니다.

이는 단순한 프론트엔드 버그가 아니라, 기획 단계에서 미처 고려되지 못했던 정책적 공백이자 백엔드 데이터 구조와 맞물린 복합적인 문제였습니다. 개발 중반부에 드러난 이슈라 자칫하면 로직을 크게 수정해야 할 수도 있는 상황이었지만, 당황하지 않고 테크 스펙의 '구현' 파트를 펼쳐 해결책을 모색했습니다.

기존 로직은 Coupon_ID만으로 상태를 관리하고 있어, 동일한 쿠폰 ID를 가진 서로 다른 딜 상품을 구분하지 못했습니다. 프론트엔드에서는 각 쿠폰의 상태를 개별적으로 관리하고, API 요청 시에도 동일한 ID의 쿠폰을 딜 상품별로 구분할 수 있도록 로직 변경이 필요했습니다. 이어 테크 스펙에 Coupon_ID와 Deal_Product_No를 조합하여 유일성을 보장하는 고유 키(Unique Key) 생성 함수를 설계했습니다.

// 테크 스펙에 작성한 의사 코드 예시 일부
const createCouponUniqueKey = (couponPublishId, dealProductNo) => {
  if (!dealProductNo) return null;
  return `${couponPublishId}-${dealProductNo}`;
};

이렇게 코드를 건드리기 전에 문서상에서 로직을 검증하고 유관 부서와 소통하며 시뮬레이션했습니다. 덕분에 기존 구조를 해치지 않으면서도 기획 변경 사항을 기민하게 반영하고, 일정 지연 없이 성공적으로 이슈를 해결할 수 있었습니다.

② 플랫폼 환경까지 고려한 선제적 대응

이번 프로젝트의 또 다른 기술적 의사결정 포인트는, '앱 내 쿠폰 다운로드 기능을 네이티브가 아닌 웹뷰(WebView)로 개발한다'는 것이었습니다. 단순히 웹뷰로 결정하고 끝난 것이 아니라, 테크 스펙 작성을 통해 왜 웹뷰로 개발해야 하는지에 대한 배경을 명확히 했습니다.

쿠폰 및 프로모션 정책은 빈번하게 변경될 수 있습니다. 네이티브로 개발할 경우에는 정책 변경 시마다 앱 심사와 업데이트 과정을 거쳐야 하지만, 웹뷰를 활용하면 배포 즉시 모든 사용자에게 최신 로직을 반영할 수 있어 운영 효율성이 극대화됩니다. 또한 향후 유사한 기능을 다른 서비스 영역으로 확장할 때에도 웹뷰 페이지는 URL만 연결하면 되므로 재사용성이 뛰어납니다.

이러한 전략적 판단 아래, 테크 스펙을 통해 웹뷰 환경에서 발생할 수 있는 잠재적 이슈들을 미리 검토했습니다. 네이티브 앱과 웹뷰 간에 데이터를 어떻게 주고받을지 통신 방식을 결정하고, 앱과 웹 사이의 로그인 세션이 끊기지 않도록 동기화 문제를 점검했습니다. 또한 앱 헤더의 유무에 따라 상단 여백이 달라질 수 있는 UI 문제까지 사전에 고려하여 대응책을 마련했습니다.

문서를 통해 이러한 이슈들을 미리 짚어보고 담당자와 해결 방안을 협의한 덕분에, 실제 개발 단계에서는 웹뷰 관련 이슈 없이 물 흐르듯 작업을 진행할 수 있었습니다.

③ 감이 아닌 데이터로 산정하는 일정

"이거 얼마나 걸려요?"라는 질문에 감으로 "일주일이요"라고 대답하면 신뢰를 얻기 어렵습니다. 테크 스펙의 '작업 계획' 단계는 근거 있는 일정 산정의 도구가 됩니다.

아래는 실제로 작성한 테크 스펙의 일부입니다.

단순히 '상품 쿠폰 다운로드 페이지 UI 개발'이라고 뭉뚱그려 이야기하기 보다는, 작업을 컴포넌트와 로직 단위로 아주 상세하게 쪼개고 공수를 산정합니다.

이렇게 구체적인 데이터를 제시하면, 굳이 왜 이만큼의 시간이 필요한지 길게 설명하지 않아도 됩니다. 함께 협업하는 다른 팀 동료들은 문서만 보고도 개발의 복잡도와 양을 직관적으로 이해할 수 있게 되죠. 이렇게 상세하게 쪼갠 태스크들을 모두 합산하여, 신뢰도 높은 전체 개발 일정이 도출되었습니다.

5. AI로 자동화할 수 없을까?

문서 작성이 좋다는 건 알지만, 매번 백지상태에서 시작하는 건 여전히 부담스러운 일입니다. 그래서 팀에서는 최근 PRD를 넣으면 테크 스펙의 틀을 만들어 주는 자동화를 실험하고 있습니다.

기획자로부터 아래와 같이 '간단한 할 일 체크 페이지' PRD를 전달받았다고 가정해 봅시다.

5.1. Input: 기획자가 건네준 PRD

[PRD]  간단한 할 일/메모 페이지

1. 목표: 사용자가 날짜별 할 일을 텍스트로 입력하고, 체크박스를 통해 상태를 관리

2. 핵심 기능:

• 텍스트 입력: 텍스트만 입력 가능 (Enter 시 저장 및 시간 자동 표기 [15:30])

• 상태 관리 (4단계): 체크박스를 클릭할 때마다 상태 순환 (Todo -> In Progress -> Done -> Canceled)

• 데이터 저장: '저장' 버튼 클릭 시 날짜별 최종 상태 저장 및 로드

• UI: 날짜 이동 네비게이션 및 반응형 디자인

5.2. Output: AI가 작성한 테크 스펙 초안

위 PRD를 Claude, Gemini 등의 AI에 입력하고, 저희 팀의 테크 스펙 양식에 맞춰 작성을 요청했습니다. 특히 태스크 분해 단계에서는 Taskmaster (GitHub Link)를 참고하여 구조적으로 업무를 쪼개도록 지시했습니다.

그 결과는 어땠을까요?

[Tech Spec] 간단한 할 일 체크 페이지 개발

1. 개요

• 비즈니스 배경: 사내 구성원들이 업무 효율성을 높이기 위해 가볍게 쓸 수 있는 데일리 태스크 관리 도구가 필요함. 복잡한 툴 대신 핵심 기능에 집중한 MVP 모델 개발.

• 기술적 목표: 리액트 기반 환경에서 공통 컴포넌트(4-State Checkbox)를 모듈화하여 향후 재사용성을 확보.

2. 프론트엔드 태스크 분해 & 일정 (with Taskmaster)

다음은 Taskmaster가 생성한 구체적인 작업 목록입니다. 각 작업은 우선순위와 의존성을 고려하여 체계적으로 정렬되었습니다.

4. 핵심 로직 의사 코드

저희 팀이 사용하는 코드 스타일에 맞춰 4단계 상태 순환 로직을 미리 구현해 보았습니다.

// 상태 순환 로직: Todo -> InProgress -> Done -> Canceled -> Todo -> ...
const NEXT_STATUS_MAP: Record<Status, Status> = {
  [Status.TODO]: Status.IN_PROGRESS,
  [Status.IN_PROGRESS]: Status.DONE,
  [Status.DONE]: Status.CANCELED,
  [Status.CANCELED]: Status.TODO,
};

const TodoItem = ({ item, onUpdate }) => {
  const handleToggle = () => {
    const nextStatus = NEXT_STATUS_MAP[item.status];
    onUpdate(item.id, { status: nextStatus });
  };

  return (
    <div className={`todo-item ${item.status.toLowerCase()}`}>
      <Checkbox status={item.status} onClick={handleToggle} />
      {/* ... */}
    </div>
  );
};

5.3. 이것이 우리에게 가져다준 변화

이 실험을 통해 저희는 AI를 단순한 글쓰기나 코딩 보조 도구가 아닌, 복잡한 업무를 구조화하고 설계를 돕는 파트너로 활용할 수 있음을 확인했습니다.

앞서 언급했던 것처럼 테크 스펙이 무기가 될 수 있었던 이유는 표준화된 양식 덕분에 누구나 부담 없이 문서를 작성하고 지식을 공유할 수 있었기 때문입니다. 문서를 어떻게 해석하고 써야하는지 고민하는 시간을 단축해 주어, 개발자는 AI가 잡아준 뼈대 위에 비즈니스 임팩트를 고려한 기술적 디테일과 엣지 케이스를 채워 넣는 데 집중할 수 있습니다. 결과적으로 단순한 작업은 AI에게 맡기고, 개발자는 기술적 난제 해결과 고도화라는 본질적인 업무에 더 집중하면서도 탄탄한 문서를 남길 수 있게 되었습니다.

더 나아가 이 접근법은 코드 리뷰의 효율성까지 높여줍니다. AI가 쪼개 준 태스크 단위가 곧 PR의 기준이 되기 때문에, 리뷰어는 각 PR이 어떤 맥락에서 어떤 작업을 수행하는지 문서만 보고도 쉽게 파악할 수 있습니다. 테크 스펙에 작성된 의사 코드와 실제 구현을 비교하며 리뷰하면 되니, 코드 리뷰가 빨라지고 팀 전체의 생산성이 올라갑니다.

또한 저희는 점진적으로 자동화의 범위를 넓혀가고 있습니다. 현재는 PRD에서 테크 스펙 초안을 생성하는 단계이지만, 향후에는 Jira 티켓 연동까지 가능할 것으로 기대하고 있습니다. 문서를 기반으로 태스크를 만들고, 각 태스크별로 의사 코드를 자동 생성하며, 이를 바탕으로 빠른 개발과 프로젝트 관리의 토대가 마련되는 것입니다. '문서로 먼저 설계하고, AI가 쪼개 준 태스크대로 개발한다'는 워크플로우가 자리 잡으면, 개발 과정에서 발생하는 변경 사항이나 트러블 슈팅도 다시 문서에 반영되어 지식이 선순환하게 됩니다.

6. 마치며: 기록이 만드는 성장의 선순환

지금까지 컬리 프로덕트 웹개발 팀이 테크 스펙을 통해 어떻게 일하는 방식을 변화시켰는지 소개해 드렸습니다.

다시 처음의 질문으로 돌아가 볼까요? "문서, 꼭 써야 하나요?" 저희 팀의 대답은 "네, 쓰면 확실히 좋습니다!"입니다. 테크 스펙은 단순한 기록을 넘어, 우리가 코드를 짜기 전에 글로 먼저 코딩하는 설계의 과정이자, 동료들과 더 나은 제품을 만들기 위해 치열하게 고민했던 소통의 흔적이기 때문입니다.

표준화된 양식으로 작성의 부담은 줄이고, AI 도구까지 활용하며 효율을 높인 덕분에 이제 기록은 개인의 성장을 넘어 팀 전체의 단단한 자산이 되었습니다. 히스토리가 투명하게 공유되는 즐거움, 기술적 의사결정이 논리적으로 이루어지는 명쾌함, 그리고 무엇보다 동료 간의 신뢰가 두터워지는 경험. 이것이 바로 저희가 문서를 사랑하게 된 이유입니다.

여러분의 팀에서도 작은 기록부터 시작해 보시는 건 어떨까요?