배경

저번주 주말에 GDSC 2차 프로젝트 회의를 하면서 각자 생각해온 주제에 대해 말해보고, 대략적인 주제를 정한 후 서류 정리에 대해 고민하던 중에 팀원 중 한명이 '각자 테크 스펙에 대해 적어보자!' 라는 의견을 제시하여 테크스펙에 대해 알아보게 되었다.

테크 스펙?

🤔 테크 스펙이 뭔데?

뱅크샐러드의 테크스펙
설명하기에 앞서, 뱅크샐러드 블로그에서 작성한 테크스펙 글을 바탕으로 작성함을 밝힌다!
테크스펙은 이름 그대로 기술(Tech)와 설명서(Spec)을 합친 것이다. 프로젝트에 대해 설계를 진행할 때, 어떤 기능을 어떻게 구현할건지에 대해 기술적으로 풀어 설명하고, 다른 팀원들에게 제안하는 문서다. 보통은 기능에 대한 기획을 진행하고, 바로 개발에 들어가는 방식을 선택한다. 하지만 테크 스펙을 작성하게 될 경우 프로젝트에 사용될 기능에 대한 룰(rule)을 정해놓고, 룰을 조금 더 자세히 작성하여 개발 과정에서 발생하는 문제를 최소화 할 수 있다고 한다.

🗣️ 커뮤니케이션 비용 절감 도구

테크 스펙은 커뮤니케이션 비용 절감의 도구로도 쓰일 수 있다고 한다. 예를들어, 프로젝트 진행 시 기능개발을 위한 커뮤니케이션 채널이 오프라인, discord, Notion(문서) 3가지였다면, O($3^N$) 이었던 커뮤니케이션 복잡도를 N개의 테크스펙 위에서 커뮤니케이션 한다면 O(N)으로 줄일 수 있다고 한다.

뱅크샐러드 블로그에서는 아래와 같이 설명했다.

1. 작업 해야할 내용이 크다.
2. PR을 어떻게 쪼개야 할지 감이 안 온다.
3. 테크 스펙을 쓴다.
4. 마일스톤에 맞춰서 지라(JIRA) 보드에 하위 작업을 나열한다.
5. 큰 작업 다 쪼갰네!
6. PR 설명은 길게 쓸 필요 없다. 테크 스펙 링크로 대부분의 설명을 대체한다.

어떤 내용이 들어갈까?

요약 (Summary)

가장 먼저 테크 스펙을 세 줄 내외로 정리한다. 테크 스펙의 제안 전체에 대해 누가/무엇을/언제/어디서/왜를 간략하면서도 명확하게 적는다.

• Botton Navigation 영역(하단 탭)을 유저가 원하는 순서로 커스텀할 수 있게 한다.
• 서버 순서 정렬 및 저장 API를 요청할 수 없으므로, 순서를 로컬에 저장하고 불러온다.

배경 (Background)

프로젝트의 Context를 적는다. 왜 이 기능을 만드는지, 동기는 무엇인지, 어떤 사용자 문제를 해결하려 하는지, 이전에 이런 시도가 있었는지, 있었다면 해결이 되었는지 등을 포함한다.

• 다양한 탭을 사용하는 유저는 Segment에 따라 하단 탭의 노출 수와 사용 빈도가 다르다.
• 예를 들어, 20대와 30대의 추천 탭 노출 수 사이는 월 n만 정도이다.
• 이러한 유저의 Segment에 맞춰 하단 탭 순서를 유저가 직접 커스텀할 수 있다면 뱅크샐러드가 개인화되었다고 인지할 수 있을 것이다.

목표 (Goals)

예상 결과들을 Bullet Point 형태로 나열한다. 이 목표들과 측정 가능한 임팩트들을 이용해 추후 이 프로젝트의 성공 여부를 평가한다.

• Botton Navigation의 순서를 유저가 편집할 수 있게 한다.
• 앱을 껐다 켰을 시에도 유저가 편집한 순서대로 하단 탭을 보이게 한다.

목표가 아닌것 (Non-Goals)

목표가 아닌 것은 프로젝트와 연관되어 있으나 의도적으로 하지 않거나 해결하지 않으려 하는 것을 말한다.
목표가 아닌 것을 정하면 프로젝트 범위를 더 명확하게 할 수 있고, 이 기능도 붙이자, 저 기능도 붙이자 하는 것을 막을 수 있다.
목표처럼 목표가 아닌 것도 Bullet Point 형태로 읽기 쉽게 적어 독자가 직관적으로 이해할 수 있도록 한다.
목표가 아닌 것을 세부적으로 잘 적으면 프로젝트 범위를 넓게 보려 하는 독자들의 폭주를 막을 수 있다.

• 사용하지 않는 탭의 삭제 기능 등 '순서 편집' 외 하단 탭에 관련한 추가적인 기능 개발
• 순서 정렬 및 저장 API 개발

계획 (Plan)

테크 스펙에서 가장 긴 파트이다. 준비한 모든 리서치, 준비 내용들을 여기에 쓴다.
어떻게 기술적, 엔지니어링적으로 접근할지 상세히 묘사한다. 만약 어떤 부분을 어떻게 할지 확실히 결정하지 못한 상태라면 어떤 것들을 고려하고 있는지 목록화해서 적는다.
그렇게 하면 이 문서 리뷰어들이 올바른 결정을 내리도록 도움을 주게 된다.
얼마나 기술적으로 깊이 써야 하는지는 이 테크 스펙의 목적과 독자들에 따라 정한다.
작성자는 생산적인 제안을 받을 수 있도록 충분히 상세하게 계획을 적는다.

이 섹션은 프로젝트가 다른 시스템들과 어떻게 상호작용하는지 그림이나 다이어그램을 포함하기 좋은 지점이다.
사용자와 시스템 간의 시퀀스 다이어그램, 서비스와 API 간의 데이터 흐름 다이어그램, 데이터베이스 ERD 등을 포함하면 독자의 이해를 한층 높일 수 있다.

또한 이 테크 스펙이 로우 레벨 까지 다뤄야 한다면 HTTP 응답 코드, JSON 요청 / 응답 포맷, 에러 명세 등까지 모두 다뤄져야 한다.

이외 고려 사항들 (Other Considerations)

고려했었으나 하지 않기로 결정된 사항들을 적는다.
이렇게 함으로써 이전에 논의되었던 주제가 다시 나오지 않도록 할 수 있고, 이미 논의되었던 내용이더라도 리뷰어들이 다시 살표볼 수 있다.

앱 데이터 초기화 시에는 사용자가 커스텀했던 리스트를 모두 날리기로 했었으나, 기존 로직에서 앱 데이터 초기화 시에 로컬 관련 추가 핸들링이 없어 이 기능에서도 앱 데이터 초기화 때에 리스트를 날리는 등 추가적인 기능 구현을 하지 않기로 함.

마일스톤 (Milestones)

프로젝트를 제 시간에 맞추기 위해 테크 스펙의 내용을 바탕으로 추정한 마일스톤을 공유한다. 실험 계획, 배포 날짜를 포함해 최대한 자세히 적는다.

~ 9/25: BPL 컴포넌트 개발
9/28 ~ 9/29: 실험 변수 추가, 로컬 변수 추가
9/30 ~ 10/4: 추석 연휴!
10/5: 하단 탭 확장 가능한 구조로 리팩토링
10/6 ~ 10/8: 비즈니스 로직 구현
10/12 ~ 10/20: 사용자 이벤트 부착 및 미진한 내용 보충
10/20: 2.45.0 코드 프리즈 (이때까지 내부 기능 테스트, 이벤트 로깅 테스트)
10/21 ~ 10/23: 2.45.0 릴리즈 QA
11/4: 2.45.0 Rollout

참고자료

https://blog.banksalad.com/tech/we-work-by-tech-spec/
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/