테크 스펙 작성 - 문서로 하는 코딩

카카오테크 부트캠프에서 프로젝트를 진행하면서 뱅크샐러드 류성두님의 "테크 스펙으로 모두가 함께 성장하는 내용" 발표를 보게 되었다. '문서로 하는 코딩'이라는 개념이 정말 신선했고, 실제로 우리 프로젝트에 적용해보고 싶었다.

 

참고한 유튜브 : https://www.youtube.com/watch?v=QHaVLYGqjvs

 

테크 스펙이란 무엇인가?

스펙 vs 테크 스펙

일반적인 스펙은 이런 거다:

"자산 화면에서 편집 버튼을 누르면 편집 화면이 나와야 된다"

 

테크 스펙은 같은 내용을 이렇게 쓴다:

"UIButton에다가 touchUpInside 입력을 받으면 EditViewController의 push라는 이벤트를 방출해야 됩니다"

 

즉, 스펙을 테크니컬하게 작성하는 것이 테크 스펙이다.

 

왜 테크 스펙이 필요한가?

모든 스펙은 생각보다 복잡하다. 세상에 간단한 스펙은 없다.

예를 들어 "은행 계좌 셀에는 금융사 로고, 상품 이름, 잔액을 표시해야 된다"는 단순해 보이지만, 실제 구현하려면:

• 은행 계좌 정보는 어디서 가져올까?
• 금융사 로고도 여러 버전이 있는데 어떤 걸 써야 할까?
• 상품 이름이 길 때는 어떻게 처리할까?
• 잔액이 마이너스일 때는 어떻게 표시할까?

이런 숨겨진 복잡성 때문에 일정 산정을 제대로 하지 못하고, 결국 무리한 일정 → 야근 → 버그 → 또 일정 어긋남의 악순환이 생긴다.

 

실제 적용 경험 - 개발 시간의 극적인 단축

 

한글 설계서로 코딩 시간 단축

테크 스펙을 도입한 가장 큰 효과는 개발 시간의 극적인 단축이었다.

 

기존 개발 방식:

• 30분 고민하고 → 10분 코딩하고 → 또 20분 고민하고 → 5분 코딩하고...
• "이 메서드 이름을 뭐로 할까?", "이 구조가 맞나?", "예외 처리는 어떻게 할까?"

테크 스펙 도입 후:

• 테크 스펙 보면서 → 바로 코딩 시작 → 막힘없이 쭉쭉 진행
• 마치 한글을 자바 코드로 번역하는 수준이다.

코딩 하면서 고민할 부분을 테크 스펙 작성 시간에 집중함으로써 빠른 개발이 가능한 것이다.

 

한글 설계서의 위력

테크 스펙에 복잡한 비즈니스 로직을 한글로 정리해뒀더니 코딩할 때 정말 쉬웠다.

예를 들어

[웹 소켓 연결 시 로직]

websocket이 클라이언트에서 들어오는 것을 afterConnectionEstablished 메서드에서 포착한다.

EC2Service 에서 privateIp를 알아낸다.

해당 유저 Id는 session에서 알아낸다.
**(HandshakeInterceptor에서 WebSocketSession Attributes에 UserId를 저장)**

해당 정보를 redis에 넣는다.

필드 userSessionMap에 사용자 id와 웹 소켓 세션 정보를 넣는다.

SessionMap에서 해당 user의 session 정보를 가져올 수 있는 메서드를 정의한다.

자료형은 HashMap으로 정의하며, get으로 가져오고 반환한다.

실제로 코딩할 때는 이 한글 설명을 그대로 자바 코드로 옮기기만 하면 됐다.

패키지 구조도 미리 정의할 수 있다.

├── domain
│   ├── chat
│   │   ├── config
│   │   │   └── WebSocketConfig
│   │   ├── handler
│   │   │   └── WebSocketHandler
│   │   ├── controller
│   │   │   ├── ChatRelayController
│   │   │   └── ChatQueryController
│   │   ├── service
│   │   │   ├── ChatQueryService
│   │   │   └── ChatEventSenderService
│   │   ├── repository
│   │   │   ├── ChatRepository
│   │   │   ├── ChatRepositoryCustom
│   │   │   └── ChatCursorPaginationRepository
│   │   └── dto
│   │       └── webresponse
│   │           ├── PostChatResponse
│   │           ├── GetChatWithCursorPaginationResponse
│   │           └── RelayChatResponse
│   ├── chatroom
│   │   ├── controller
│   │   │   └── ChatroomController
│   │   ├── service
│   │   │   └── ChatroomService
│   │   ├── repository
│   │   │   ├── ChatroomRepository
│   │   │   ├── ChatroomRepositoryCustom
│   │   │   └── ChatroomCursorPaginationRepository
│   │   └── dto
│   │       └── webresponse
│   │           └── GetChatroomWithCursorPaginationResponse
└── global
    ├── config
    │   └── RedisConfig
    └── util
        └── EC2Service

덕분에 "음.. 패키지 구조를 어찌 하는게 나을까" 같은 고민 없이 바로 구현할 수 있었다.

문서화 작업 중에 이것을 진행하여 코드가 아닌 한글, 그림으로 보기 때문에 빠르게 설계할 수 있었다.

 

시퀀스 다이어그램으로 아키텍처 완벽 이해

 

복잡한 API 플로우의 시각화

테크 스펙에 시퀀스 다이어그램을 추가한 것이 정말 큰 도움이 되었다. API 호출 시 전체 흐름이 한눈에 보였다.

스펙 등록 요청의 시퀀스 다이어그램:

Client → SpecController → SpecService → UserUtils → UserRepository
                       → FileStore (포트폴리오 업로드)
                       → AiService (스펙 분석)
                       → SpecRepository (저장)
                       → EducationRepository (서브 도메인 저장)
                       → WorkExperienceRepository
                       → ...

이 다이어그램 덕분에:

 

의존성 파악이 즉시 가능 했다. 어떤 Repository가 필요한지, 어떤 Service를 주입해야 하는지 바로 알 수 있었다

 

분산 시스템 아키텍처 이해도 향상

특히 복잡한 분산 채팅 시스템에서 시퀀스 다이어그램의 위력을 제대로 느꼈다:

User A → Main Server A → Kafka → Consumer Server → 
Redis (상대방 서버 확인) → Main Server B → User B

이런 복잡한 분산 처리 플로우도 다이어그램으로 보니까:

• "아, Kafka는 여기서 이런 역할을 하는구나"
• "Redis는 여기서 사용자 위치를 추적하는구나"

직관적으로 이해할 수 있었다.

 

스펙 수정에 관한 테크 스펙 일부분이다.

 

이 뒤에 위의 웹 소켓 연결 로직 예시 처럼 상세히 흐름도가 작성된다.

 

팀원과의 소통 효율성 극대화

팀원에게 복잡한 로직을 설명할 때도 시퀀스 다이어그램이 있으니까 정말 쉬웠다.

"여기서 AI 분석 요청을 보내고, 응답을 받아서 여기에 저장하고..." 이런 식으로 다이어그램을 가리키면서 설명하니까 빠른 설명이 가능했다. 텍스트로만 설명했다면 30분은 걸렸을 것이다.

 

네이밍 고민의 완전한 사전 처리

테크 스펙을 작성하면서 가장 많은 시간을 쓴 부분이 바로 변수명과 로직 설계였다. 류성두님 말씀처럼 "창의력이 필요한 문제들"이 대부분 해결되고 나서야 실제 코딩은 몇백 줄 안 된다는 걸 체감했다.

예를 들어:

• PostSpecRequest vs CreateSpecRequest vs SpecRegistrationRequest
• SpecService#createSpec() vs SpecService#registerSpec() vs SpecService#saveSpec()

이런 네이밍을 테크 스펙 단계에서 충분히 고민하고 결정해두니까, 실제 코딩할 때는 고민 없이 바로 써내려갈 수 있었다.

 

API 설계의 사전 검증

API 설계도 테크 스펙에서 미리 완료:

GET /api/specs?type=ranking&jobField=INTERNET_IT&cursor=encodedCursor&limit=10

Response:
{
  "isSuccess": true,
  "message": "랭킹 목록 조회 성공",
  "data": {
    "rankings": [...],
    "hasNext": true,
    "nextCursor": "..."
  }
}

미리 API 스펙을 검증 했기 때문에, 실제 구현할 때 "어? 이 필드도 필요한데?" 같은 일이 전혀 없었다.

또한 이 API가 호출되면서 거쳐야할 모든 검증, 호출할 클래스들을 정의하고 어느 패키지에 존재해야 되는지도 정의하였기 때문에

모든 로직 흐름도를 작성할 수 있었다.

만약 흐름도를 짤 수 없다면 추가 학습이 필요하다 생각하여 빠르게 학습하고 테크스펙을 작성하였다.

원래 였으면 코딩을 작성하면서 즉 Java 코드를 보면서 부족한 부분이 있으면 다시 학습하고 다시 코드를 짜는 불필요한 컨텍스트 스위칭이 발생하는데 이 모든 고민 부분을 테크 스펙 작성에 할애하는 것이다.

 

모두가 함께 성장하는 경험

 

팀원들에게 긍정적인 영향

테크 스펙을 공유하면서 팀원들로부터 정말 유용하다는 피드백을 받을 수 있었다:

• 부하 테스트 중에 오류가 발생해서 해당 시퀀스 다이어그램을 봤는데 에러 처리에 부하 테스트가 걸린 거 였어요 빠르게 파악이 가능했어요.
• AI Server와 S3 서버를 Mock으로 생성하는 방식은 정말 좋은 것 같습니다! 저도 나중에 사용해 봐야겠어요.

같은 피드백을 받았다.

 

다양한 사람들의 피드백

• 이 변수명이 의미 전달이 잘 안 되는 것 같아요. 혹시 이 변수명은 어떤가요?
• 혹시 Query 부분이랑 Command 부분을 따로 분리하면 클래스의 역할이 명확해 지지는 않을까요?

 

혼자서 할 수 있는 범위를 넘어서 성장하려면 결국 피드백을 받아야 한다.

테크 스펙을 통해 더 이른 시점에, 더 자주, 더 많은 사람들로부터 피드백을 받을 수 있었고, 이 과정에서 정말 많이 성장할 수 있었다.

 

결론

테크 스펙은 단순히 문서가 아니라 개발 생산성을 극대화하는 도구였다.

 

개발 시간 단축: 코딩하면서 고민해야 할 것들을 미리 한글로 정리해두니까 실제 개발할 때는 번역하는 수준으로 빠르게 진행할 수 있었다.

 

아키텍처 이해도 향상: 시퀀스 다이어그램으로 복잡한 API 플로우를 시각화해두니까 전체 시스템을 이해하고 최적화하기 쉬웠다.

 

팀 성장: 함께 설계를 검토하고 개선하는 과정에서 혼자서는 절대 도달할 수 없는 성장을 할 수 있다.

 

앞으로도 복잡한 기능을 개발할 때는 테크 스펙부터 작성하고 시작하는 습관을 유지해야겠다. 문서로 하는 코딩, 정말 강력한 도구 인 것 같다.