테크 스펙이란 무엇일까??

정리 배경

현재 업무를 하다보니 문서화가 되어 있지 않은 코드를 보고 이해하는 것이 새로 들어온 동료들에게 그들의 리소스를 소비하게 만드는 것이라는 것을 느끼고 있습니다. 기존에 문서가 정리되어 있었다면 그들이 초기에 코드를 파악하는 시간을 줄여서 업무에 빨리 적응할 수 있도록 도울 수 있다고 생각했습니다.

 

그러면 이 문서화의 기준이 뭘까? 라고 고민하다가 테크 스펙을 찾게 되었습니다.

(이 글은 뱅크샐러드의 테크 스펙을 정리하고 하나의 예시를 통해 설명하고자 합니다)

테크 스펙엔 뭐가 들어갈까?

저는 간단한 하나의 예시를 들고 그에 맞춰 상황을 써보려고 합니다.

현재 배포된 화면에서 특정 텍스트가 미노출되었다는 상황을 가정하고 작성해보겠습니다.

 

1. 요약 (Summary)

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

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

04/03일 배포한 2.1버전에서 사용자가 A화면에 진입 시 B 기능에 대한 텍스트가 노출되지 않는 문제를 해결합니다. 또한 레거시 코드를 이와 연관된 Java에서 Kotlin으로 마이그레이션 하는 작업을 진행 합니다.

 

2. 배경 (Background)

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

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

이번 배포 때 기존에 A화면에서 노출되던 텍스트가 노출되지 않는 문제가 발생했습니다. 추가적으로 해당 문제를 해결하면서 연관된 레거시 코드이 남아있어 기술 부채가 존재하기에 이를 마이그레이션해서 해결하고자 합니다.

 

3. 목표 (Goals)

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

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

•  A 화면에서 텍스트가 다시 노출됩니다.

•  해당 기능과 연관된 레거시 코드를 Java에서 Kotlin으로 마이그레이션 합니다.

 

 

4. 목표가 아닌 것 (Non-Goals)

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

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

• A 화면에서 텍스트 미노출에 대한 이슈를 제외한 다른 기능들에 대한 변경

• 연관된 기능이 아닌 코드들에 대한 마이그레이션

 

5. 계획 (Plan)

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

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

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

 

생략

 

6. 이외 고려 사항들 (Other Considerations)

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

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

테스트 코드의 경우도 다시 Kotlin 버전으로 작성하고자 하였으나, 이번 스프린트 시간 분배의 문제로 구현하지 않기로 함.

 

7. 마일스톤 (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

 

04/04: A화면 텍스트 미노출 발견

04/05 ~ 04/07: 각 위치별 로그 체크 및 문제점 파악

04/08: 텍스트 미노출 해결

04/10 ~ 04/12: 연관된 코드 Java에서 Kotlin으로 Migration

04/13 ~ 04/14: 2.1.1 릴리즈 QA
04/15: 2.1.1 Rollout

 

<참고 자료>

https://blog.banksalad.com/tech/we-work-by-tech-spec/

https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/