기술 명세서
최근에 테크 스펙이라 부르면 기존 업계의 기술에 대한 명세와 업데이트 된 형태를 안내하던 제품 납기시 기술 명세서와는 달리 기술팀이 기술 기획 리뷰시 필요한 내용을 정리하는 것을 테크 스펙으로 부르는 것 같다. 설계 리뷰 문서를 위한 기술 명세서 간략화 버전이라고 생각한다.
충분히 리뷰를 받고 작업을 진행하기 위한 커뮤니케이션 용 문서해당 문서 자체가 설계에 기본이 되고, 참조 문서가 되며, 이후 PR 리뷰 등을 할때도 참조하여 충분히 검토할 수 있도록 하게 되는 문서
- 문서 안내 포멧
- 작성자
- 문서의 소속 팀
- 최근 수정일
- 프로덕트 스펙
- 지라 에픽 및 테스크
- 요약(Summary)
- 테크 스펙을 대략적으로 정리한다. 누가/ 무엇을 / 언제 / 어디서 / 왜 에 대해서 명확하게 작성한다
- 배경 (Background)
- 프로젝트의 컨텍스트에 대해서 작성한다.
- 만드는 이유, 동기, 어떤 사용자의 문제를 해결하기 위한 것인가?
- 이 문제를 해결하기 위해 이전에는 어떤 노력이 있었는가?
- 목표 (Goals)
- 의도하거나 의도하지 않았어도 발생 될 것으로 예상하는 모든 결과를 Bullet 으로 작성한다.
- 이 부분은 대규모 서비스, 코드 베이스에 기여할 때 가장 중요한 부분임
- 이 항목은 측정 가능한 기대하는 결과와 함께 프로젝트의 성공을 평가하는 기준이 된다.
- 목표가 아닌 것 (Non-Goals)
- 목표가 아닌 것이라는 말은 헷갈릴 수 있지만 이 문서를 읽는 검토자가 목표를 읽으며 산으로 가는 것을 막아줄 수 있기에 필요하다.
- 해당 프로젝트에 관련이 있지만 의도적으로 수행하지 않거나 해결하지 않으려는 것을 명세한다.
- 목표와 마찬가지로 Bullet 의 형태로 작성하여 리뷰어가 읽기에 간단 명료한 형태여야 한다.
- 목표가 아닌 것에 대해서 명확하게 작성하지 않으면 리뷰어가 프로젝트의 크기를 넓히려고 할 수 있다.
- 계획 (Plan)
- 가장 중요한 항목
- 구현을 위해 리서치하거나, 준비한 산출물에 대해서 상세히 작성합니다.
- 만약 구현 방법에 대해서 아직 결정을 하지 못한 경우라면, 어떤 방법들을 고려하고 있는 지 모두 목록화 하여 상세히 작성해야 합니다.
- 이를 통해 리뷰어들이 올바른 결정에 도움을 주게 됩니다.
- 얼마나 기술적으로 깊게 작성해야 할지는 스펙의 목적이나 독자들에 따라 정합니다.
- 생산적인 제안을 받을 수 있도록 충분히 상세히 작성해야 합니다.
- 여기는 어떻게 프로젝트가 다른 시스템들과 상호작용하는지 그림이나 다이어그램을 포함하기 좋은 지점입니다. 사용자와 시스템 간의 시퀀스 다이어그램, 서비스와 API 간의 데이터 흐름 다이어그램, 데이터베이스 ERD 등 모두 비주얼라이저 할 수 있으면 좋다. (기왕이면 누구나 문서와 첨부 파일을 수정 가능하도록 원본을 함께 포함하라)
- 구체적의 정도로는 예를 들어 테크 스펙이 로우 레벨까지 다뤄야 한다면 HTTP 응답 코드, JSON 요청 / 응답 포맷, 에러 명세 등까지 모두 다뤄져야 한다.
- 기대하는 결과
- 이 것으로 기술적으로나, 비즈니스적으로 기대하는 바에 대해서 작성한다.
- 예를 들면, 성능의 개선이나, 비즈니스적으로 기대하는 성과를 작성한다.
- 기능의 기획 의도에 포함되는 기대하는 것에 대해서 작성하고, 구현 이후에 실제로 기대하는 대로 되었는지 비교할 수 있는 기준이 될 수 있다.
- 보안 고려 사항 (보안, 개인정보, 리스크)
- 프로젝트가 외부에 노출되거나, 내부에 있더라도 지켜야 할 개인 정보 이슈가 있는 경우 발생할 수 있는 문제점들에 대해서 나열한다.
- 보안에 대해서는 최대한 부정적인 측면에 대해서 많이 나열하고, 그 문제를 리뷰어와 함께 소거해 나가는 것이 좋다.
- 이외 고려 사항 (Other Considerations)
- 목표가 아닌 것과 달리, 설계/계획 리서치나 구두로 대화했을 때 하지 않기로 한 내용들에 대해서 작성한다.
- 이전에 논의 된 주제를 다시 논의 않도록 할 수 있고 결정 사항에 대해서 리뷰어들이 다시 살펴볼 수 있도록 한다.
- 마일스톤 (Milestones)
- 프로젝트 완수 시간까지 필요한 대략적인 마일 스톤을 작성한다.
- 운영 이슈, 마이그레이션 이슈 등을 정리해서 어느정도의 작업량이 될 수 있을지 구체적이면 좋지만 대략적으로 작성을 하면 좋다.
- 질문 (Open Questions)
- 설계 중에 궁금했던 점, 절차상 고민이 되는 것들 과 같이 묻고 싶었던 것을 편하게 작성한다.
- 작성하면서 피드백을 받고 싶었던 부분이 있었다면 가감없이 작성한다.
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
https://eng.lyft.com/awesome-tech-specs-86eea8e45bb9
https://blog.banksalad.com/tech/we-work-by-tech-spec/
https://docs.google.com/document/d/1nhozeUvJYKytE_b_9-YP4Fyw0wtykl9haCG4Wwjb9Ws/edit#heading=h.c5rpsdy8g2ak