개발자들이 개발을 시작할 때의 모습은 제각각입니다. 일단 코드부터 두드리고 보는 행동파 개발자도 있고, 눈앞에 보이는 노트 위에 간단한 구조를 그려 보는 개발자도 있죠. 뱅크샐러드에서는 모두 같은 행동을 합니다. 우리는 테크 스펙을 써요.

😟 문서를 꼭 써야 돼?

코드 짜기도 바쁜 우리는 문서까지 작성할 시간이 없습니다. 대부분의 소통을 코드로 할 때가 많아 글로 소통하는 방법에 익숙하지 않기도 하고, 한 번 작성된 후 업데이트되지 않는 문서는 시간 들여 필요 없는 문서를 양산해버린 셈이 되니까요. 그럼에도 우리는 쉽게 문서화 라는 마법의 단어를 말하고는 합니다.

🤦 맨땅에 헤딩

🧑‍💻: 안녕하세요, 오늘 입사한 김뱅샐입니다. 전반적인 코드 구조를 살펴보았는데, 자산 연동 코드 구조가 왜 이런지(이따구인지) 모르겠습니다. 도움 주실 수 있을까요?
💀: 아… 그 코드 작성하신 분이 퇴사하셔서… 레거시 코드인데, 제가 생각할 때는 아마? 이런 식인? 것? 같네요? 아마도요? 해당 부분 PR 본문은 확인해 보셨나요?
🧑‍💻: 네. 자산 연동 기능을 추가한다 한 줄 적혀 있습니다.
💀: 아. ㅋㅋ 문서화가 놓쳐졌네요. 챙겨지면 좋을 것 같아요~
🧑‍💻: 아. ㅋㅋ 문서가 따로 없군요. 챙겨지면 좋을 것 같네요~

🤯 맨땅에 헤딩 N개월 후

🧑‍💻: 이따구의 코드를 작성해 보았습니다. PR 리뷰 부탁드립니다. @here
☠️: 전반적인 코드 구조가 잘 이해가 가지 않는데, 설명 부탁드립니다.
🧑‍💻: 오프라인으로 설명하는 시간 갖도록 하겠습니다.
2 months later…
🐣: 이따구 코드 구조가 복잡하네요. 설명 부탁드려도 될까요?
☠️: 코드 작성자 분께서 지금은 서버 개발자로 전향하셨습니다. PR에 따로 언급 없나요?
🐣: 오프라인으로 설명하는 시간을 가지셨대요! 코멘트에 그렇게 적혀 있어요!
☠️: 아. ㅋㅋ 문서는 따로 없군요. 챙겨지면 좋을 것 같아요~
🐣: 아. ㅋㅋ 문서화가 놓쳐졌나 보네요. 챙겨지면 좋을 것 같네요~

문서화, 해야 나중이 편하지만 하자고 말만 하게 되는 마법의 단어입니다. 일단 문서화해야겠네요 라는 말을 뱉고 나면 이미 문서를 대충 다 쓴 기분이 들기도 하지요. 규모가 작은 조직이라면 위와 같은 상황의 반복으로 급한 불은 끌 수 있을지 모릅니다. 하지만 성장하는 조직이라면 이야기가 달라집니다.

🤐 응, 문서 꼭 써야 돼

뱅크샐러드는 단기간에 급진적인 성장과 변화를 겪었습니다. 커지는 조직에 따라 복잡도는 증가했고 우리는 방황하기 시작했어요. 옹기종기 모여서 자신이 작업 중인 기능에 대해 구두로 설명하기에는 이미 10개가 넘는 PR이 Review Required 상태였고, 한 명씩 돌아가면서 자신의 코드에 대해 설명하는 시간을 한 시간씩만 써도 열 시간이 넘어 근무 시간을 초과하는 상황이 되었습니다. 우리는 하루에 천 번씩 배포하고, 기능은 갈수록 많아지고, 옆자리 팀원의 작업이 어떤 기능인지 모르기 시작하고, 요구 사항은 점점 더 많아졌습니다. 예컨대 이런 상황이 있죠.

🧚‍♀️: 기획서 여기 있습니다. 언제까지 개발 완료 가능하실까요?
👩‍💻: 흠… 다음 주 목요일까지 할 수 있을 것 같아요.
🧚‍♀️: 감사합니다. 기획서가 바뀌었습니다.
😇: 뱅샐 님 이전에 개발하셨던 부분에서 크래시 나는데 확인 좀 해 주시겠어요?
🤠: 뱅샐 님, 스크럼 하셔야죠! 회의 가셔야죠! 면접 보셔야죠! 슬랙 답장 좀 해 주세요! 리뷰 코멘트 반영했는데 봐 주세요! 제가 작업했던 부분에서 변경점이 생겼는데 확인 좀 해 주세요!
👩‍💻: (테스트 코드 포기하면 대충 일정은 맞출 수 있겠지 ㅎㅎ) 갈게요!
🧚‍♀️: 뱅샐 님, 개발 진척도 공유 부탁드립니다. 진행하고 계신 것 맞죠?
👩‍💻: (일정 망했지만 대충 모르는 척) 진행 중입니다. :)
🧚‍♀️: 그리고 기획에 이 정도 변경점이 생겼는데요. 어려운 부분이 아니라면 추가 부탁드립니다. :)
👩‍💻: 별로 어려운 부분은 아니네요. 추가해 볼게요~
🧚‍♀️: 네!
👩‍💻: 추가하다 보니 구조를 처음부터 다시 짜야 할 것 같은데요… 일단 엎어 볼게요…
🧚‍♀️: 네?
😅: 뱅샐 님, 작성하신 코드에서 꼬랑내가 나네요. 제 PR 머지되고 나서 컨플릭트도 장난 아니에요. PR 설명 좀 부탁드려요.
👩‍💻: 일정 딜레이될 것 같아서 그러는데 일단 머지하고 추후에 설명드리는 시간 가져도 될까요? 문제 없을 거예요. 믿음 메타로 갑시다.

복잡도가 증가한다는 것은 더 많은 함정을 만드는 일입니다. 그리고 개발자의 일은 이 복잡도를 제어하는 것이죠. 복잡도를 제어할 수 있는 가장 좋은 방법은 휘발성이 높은 Short Term Memory로부터 👉 의도와 목적을 조율할 수 있는 수단으로 나아가는 것입니다. 그래서 뱅크샐러드는 테크 스펙을 쓰기 시작했습니다.

테크 스펙을 쓴 뒤, 우리는 이렇게 일하기 시작했어요.

🧚‍♀️: 기획서 여기 있습니다. 언제까지 개발 완료 가능하실까요?
👩‍💻: 테크 스펙 적다 보니 생각보다 고려해야 할 점이 많네요. 테스트 코드 작성까지 다 하면 다다음 주까지 가능할 것 같습니다. 그리고 쓰다 보니 기획서의 이 부분은 변경되어야 할 것 같은데, 확인해 주시겠어요?
🧚‍♀️: 감사합니다. 제품 스펙도 업데이트되어야겠네요!
😇: 뱅샐 님 이전에 개발하셨던 부분에서 크래시 나는데 확인 좀 해 주시겠어요?
🤠: 뱅샐 님, 스크럼 하셔야죠! 회의 가셔야죠! 면접 보셔야죠! 슬랙 답장 좀 해 주세요! 리뷰 코멘트 반영했는데 봐 주세요! 제가 작업했던 부분에서 변경점이 생겼는데 확인 좀 해 주세요!
👩‍💻: (테크 스펙 적으면서 쪼갰던 작업 중 남은 작업을 보니 시간이 빡빡하다. 우선순위를 조정하고 빠질 수 있는 회의는 빠져야겠다.)
🧚‍♀️: 뱅샐 님, 개발 진척도 공유 부탁드립니다. 진행하고 계신 것 맞죠?
👩‍💻: 작성한 테크 스펙의 마일스톤 확인해주시면 됩니다. 더 디테일한 정보는 지라 보드를 확인해주시면 됩니다!
🧚‍♀️: 기획에 이 정도 변경점이 생겼는데요. 테크 스펙을 보니 이미 기한이 빡빡해 보이네요. 어려운 부분이 아니라면 다음 배포에 추가 부탁드립니다. :)
👩‍💻: 네, 다음 배포에 추가하겠습니다. 테크 스펙에도 업데이트할게요.

🤔 테크 스펙이 뭔데?

직독 직해하시면 됩니다. 기술(tech) 설명서(spec)를 말해요. 기능을 구현하기 전에 이 기능을 어떻게 구현할 것인지 기술적으로 풀어 설명하고, 제안하는 글이에요. 보통은 기능에 대한 기획적인 부분을 보고 바로 개발자가 작업하게 되지만, 테크 스펙은 실제 개발에 바로 들어갈 수 있을 것 처럼 자세하게 적어서 실제 플랫폼 코드가 포함되는 경우도 많아요.

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

테크 스펙은 일정 산정을 가능하게 하는 것은 물론이고, 커뮤니케이션 비용 절감의 도구로도 쓰일 수 있습니다. N개의 기능 개발을 위한 커뮤니케이션 채널이 오프라인, 슬랙, 문서 3가지였다면 O(3^N)이었던 커뮤니케이션 복잡도를 N 개의 테크스펙 위에서 커뮤니케이션한다면 O(N)로 줄일 수 있게 됩니다.

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

기능에 변경이 생겨 구체적인 논의가 필요한 경우, 더블 체크가 필요한 경우에도 문서가 있다면 보다 명확한 커뮤니케이션이 가능합니다. 예를 들면 이런 식으로 말이죠.

(이렇게 링크로 많은 커뮤니케이션을 생략하면 시간을 벌 수 있고, 그 시간으로 빠른 퇴근을 하거나 코딩 한 줄 더 하고 몸값을 올릴 수도 있겠죠. 😎)

👀 테크 스펙에 뭐 들어가?

테크 스펙의 필요성이 느껴지시나요? 이제 막 글 쓰고 싶으시다고요? 손이 간질거리신다고요? 그런데 좋은 테크 스펙을 쓰려면 어떤 내용이 들어가면 좋을지 모르겠다고요? 걱정하지 마세요. 뱅크샐러드 테크 스펙 템플릿 내용을 바탕으로 설명드리겠습니다.

요약 (Summary)

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

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

배경 (Background)

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

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

목표 (Goals)

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

• Bottom 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

위 내용은 lyft에서 공개된 tech spec 양식의 영향을 많이 받았습니다. 이와 같이 뱅크샐러드에서도 정리된 테크 스펙 템플릿을 공유합니다. 🙂 보다 많은 분들에게 도움 이 됐으면 좋겠네요. 잘 활용해 주세요! (링크)

😌 우리는 이렇게 문서를 써요

모든 테크 구성원에게 리뷰를

뱅크샐러드에서는 위 내용을 필수적으로 포함하여 Google Docs에 작성하고, 개발 착수 전에 공유합니다. 공유는 비단 자신이 속한 팀만이 아니라 전체 개발 구성원들에게 하여 보다 폭 넓은 피드백을 받도록 하고 있어요.

공통의 스펙, 다른 플랫폼이라면 한 개의 문서로

서로 다른 플랫폼에서 각각 문서를 작업하다 보면 아래와 같은 이슈가 생길 때도 있습니다.

😇: 투자 섹션 소수점 자릿수가 한 자리인데, 두 자리면 좋겠다는 유저 피드백이 들어왔습니다! Android OS 10 유저 분이십니다.
👽: 간단하네요. 제가 수정하겠습니다. iOS에서는 이슈 없나요? @ios
🍎: 엥? iOS에서는 두 자리로 보여 주고 있습니다.
👽: 엥? 한 자리 아니에요?
🍎: 엥? 두 자리로 이야기했을걸요? 슬랙 쓰레드에서 보고 iOS 문서는 고쳐 놓았습니다.
👽: 엥? 슬랙 어디요? 안드로이드에는 문서도 따로 없네요? 문서 쓸 시간까지는 없고, 일단 저는 코드를 고칠게요.

이런 이슈를 방지하기 위해 다른 플랫폼간 공통의 스펙을 작업한다면 한 개의 문서에서 소통하도록 합니다. 아래 이미지와 같이 특정 문장을 드래그한 뒤 댓글을 남기는 것으로 각 이해 관계자들은 쉽게 소통할 수 있습니다. 상이했던 동작을 캐치하고 별도 UI를 요청드리는 과정에 대한 기록도 남길 수 있었고, 이 기록은 나중에 쉽게 찾을 수도 있겠죠.

한 가지 플랫폼에 국한된 구현은 별도 문서로

다만, 두 개 다른 플랫폼의 기술적 특성까지 모두 한 문서에 작업하는 데에는 어려움이 있을 수 있습니다. 예를 들어, 안드로이드 코드에 대한 구조적인 설명 등 안드로이드 팀원들에게만 공유되어야 할 영역의 경우에는 별도 문서로 빼내어 작업하기도 합니다.

이렇게 목표가 아닌 것(Non-goals)에 상위 문서를 링크하는 것으로 기능 설명에 대한 것은 축소하고, 오로지 구현에 대한 설명만 담아 문서를 작성하기도 합니다. 혹은 참고하기 좋은 테크 스펙을 가장 상단에 링크해 둘 수도 있죠.

🥰 마치며

우리는 보통 문서화를 귀찮게 생각합니다. 문서화는 코딩과 별도의 일이라고 생각하기 때문이죠. 하지만 테크 스펙을 써 보면, 어떻게 만들 것인지 줄줄이 작성하면서 이미 웬만한 수준의 코딩이 들어가게 됩니다. 결과적으로 테크 스펙을 다 작성하고 나면 테크 스펙에서 작성했던 코드를 실제 프로덕트에 붙이는 것만으로 작업이 끝나기도 하죠. 즉, 문서화는 더이상 코딩과 별도의 일이 아니게 됩니다.

테크 스펙은 모든 과정을 투명하게 만듭니다. 베스트 프랙티스들로 문제를 해결하게 해 주고, 일정 산정에서 개발자에게 부담을 덜어주고, 설사 비즈니스 상황이 바뀌어 일정이 바뀐다고 하더라도 그건 상황이 바뀌었을 뿐 개발자의 실책이나 과오가 아닌게 명백히 보이기 때문에 개발자가 부담 없이 자유롭게 일할 수 있는 환경을 제공합니다.

코드 전에 문서로 일하는 뱅크샐러드는 조금 더 편하게 레거시를 기록하고, 덜 스트레스받으면서 커뮤니케이션하고, 더 완성도 있는 설계를 하고 있습니다. 저희의 협업 방식이 이 글을 읽으신 분들에게 도움이 되었으면 좋겠습니다. 읽어 주셔서 감사합니다!