슬랙 100건의 쓰레드가 알려준 것들
- 급한 작업일수록 설계가 먼저였다
그 긴 이야기의 시작. 대충 그 긴거..
이번 주에 꽤 인상적인 경험을 했다. 한마디로 요약하면 "급한 작업일수록 설계를 먼저 해야 한다"는 것인데, 사실 이 문장은 누구나 알고 있고, 어디서든 한 번쯤은 들어봤을 이야기다. 그런데 막상 현장에서 촉박한 일정과 마주하면, 설계를 건너뛰고 코드부터 치는 자신을 발견하게 된다. 이번에 내가 딱 그랬고, 그 대가로 기획자와 나 사이에 슬랙 쓰레드 메세지 100건이 넘는 소통 괴물을 만나게 되었다.
그리고 그 쓰레드 괴물을 바라보면서 이 블로그 포스팅의 아이디어를 얻었다. 이건 기회야..! 글로 남겨야만해..!
이 글은 그 경험을 돌아보면서, 비슷한 상황에서 어떤 도구와 방법론이 도움이 될 수 있는지 정리한 글이다. 구체적으로는 요구사항 정리, 유비쿼터스 언어, 시퀀스 다이어그램, 클래스 다이어그램과 도메인 모델, ERD 설계, 그리고 이 모든 과정을 자동화할 수 있는 Claude Skills라는 도구에 대해 다루려고한다.
무슨 일이 있었는지
상황을 비유적으로 설명하면 이렇다. 식당의 메뉴판을 새로 만드는 작업이 있었다고 비유 해보려 한다. 기존 메뉴판에 적혀 있던 가격이 바뀌었고, 새 가격을 반영한 메뉴판을 내일까지 손님들에게 보여줘야 하는 상황이었다. 원래 이 메뉴판을 담당하던 동료가 업무가 많아서 나에게 도움을 요청했고, 나는 당일에 바로 작업을 시작해야 했다. 테스트 기간도 없었고, 추가 일정을 얻지도 못했다.
가격 정보라는 게 민감한 영역이다 보니, 디자인 시안에 최대한 충실하게 작업해서 전달했다. 그런데 다음 날 아침, 기획 담당자가 출근하자마자 디자인 변경과 화면 동작 수정을 요청했다. 처음에는 간단한 수정이라고 생각해서 몇 가지를 반영해드렸는데, 요청이 계속해서 이어졌다. 최초 작업 요청서에도 없던 내용이었고, 디자인을 확인해줄 담당자도 부재한 상태에서 발생한 추가 요청이었다.
이 과정에서 나는 계속 작업을 진행했고, 점심이 지나도록 마무리가 되지 않았다. 다행히 그 모습을 지켜보던 프론트엔드 동료분께서 도와주셔서 오후 1시쯤에 일단 반영을 마쳤지만, 기획 담당자는 여전히 디자인 세부 수정을 원했다. 나는 "현재 이전 가격이 계속 표시되고 있어서 고객에게 혼란을 줄 수 있으니, 가격 정보가 정확한지를 먼저 확인하고, 디자인 세부 조정은 이후에 디자이너 합류 후 하는 게 어떻겠느냐"고 제안했지만 받아들여지지 않았다. 결국 관리자가 개입해서 일단락되었다.
그런데 진짜 문제는 그 다음이었다.
반영된 가격 정보를 내가 직접 확인하는 과정에서, 실제 적용되어야 할 가격과 메뉴판에 표시된 가격이 다르다는 것을 발견했다. 정확한 가격 자료를 요청했더니, 전달받은 자료도 틀려 있었고, 디자인 시안의 가격도 달랐으며, 검수 자체가 제대로 이루어지지 않은 상태였다. 결국 최초 요청자, 그리고 기획 담당자, 결제 프로그램 담당자 그리고 그냥 나.. 내가 한 자리에 모여서 가격표를 처음부터 다시 정리해야 했다. 저녁 6시가 되어서야 올바른 가격 정보가 완성되었다.
100건의 쓰레드가 만들어진 진짜 이유
이 경험을 되돌아보면서, 슬랙 쓰레드가 100건을 넘긴 이유가 단순히 "요청이 많아서"가 아니라는 것을 깨달았다.
서로 요구사항에 대해 명확하게 합의하지 않은 상태에서 작업을 시작했기 때문에, 작업이 진행될수록 추가 사항이 계속 튀어나왔다. 명확하지 않은 요구사항과 구현 방향을 슬랙 메세지로 주고받으면서 정리하려 했으니, 대화가 끝없이 이어질 수밖에 없었다.
별도의 일정을 잡아서 한 자리에 모여 정리한 것이 아니라, "일단 최대한 빨리 전달하자"는 생각에만 집중한 결과였다. 그래서 100건이 넘는 슬랙 메세지 덩어리가 탄생했다.
이 쓰레드 괴물의 더 큰 문제는 "지금"이 아니라 "나중"에 있다고 생각한다. 이후에 이 개발 건에 대한 이슈가 발생하더라도, 당시 대화에 참여하지 않은 사람이라면 100건이 넘는 쓰레드를 처음부터 읽으면서 맥락을 파악해야 한다. 현실적으로 그렇게 할 사람은 거의 없다. 결국 히스토리가 사실상 소실되는 것과 다름없고, 이후에 같은 페이지를 수정해야 하는 상황이 오면 또다시 같은 혼란이 반복될 가능성이 높다.
이런 식의 의사소통과 작업 진행은 히스토리 관리가 되지 않을 뿐더러, 합의 없는 수정과 배포가 반복되는 구조를 만든다. 당장 시스템에 치명적인 장애를 일으키는 이슈가 아니라면, 작업을 시작하기 전에 요구사항을 정리하고 서로가 가진 도메인 지식의 수준을 맞추는 시간을 갖는 것이 훨씬 효율적이다.
동일한 이슈가 발생하지 않도록, 동료인 다른 개발자 분과 해당 페이지에 대한 개선 방향을 함께 논의하기로 했다. 그 자리를 위해 아래의 내용들을 준비하려 한다.
요구사항 정리 - 코드를 치기 전에 무엇을 만들 것인지 합의하기
요구사항 정리란, 개발을 시작하기 전에 "무엇을 만들어야 하는지"를 글로 명확하게 작성하는 과정이다. 언뜻 보면 당연한 이야기 같지만, 실제로 이 과정을 생략했을 때 어떤 일이 벌어지는지를 이번에 직접 경험했다.
이번 건에서 내가 준비하려는 요구사항 정리의 범위는 이렇다. 최초 요청자 사람이 전달한 원래 요청 사항에서 시작해서, 최종적으로모든 이해관계자(최초 요청자, 기획자, 결제 프로그램 담당자) 그리고 담당 작업자가 모여서 정리한 가격표의 이력까지를, 축약어 없이 상세하게 서술하는 것이다. "누가 언제 어떤 요청을 했고, 그 요청이 어떻게 변경되었으며, 최종적으로 무엇이 합의되었는지"를 한 장의 문서로 정리하면, 이 작업에 참여하지 않은 사람도 전체 맥락을 파악할 수 있게 된다.
요구사항 문서가 없으면 이런 일이 발생한다.
첫째, 기획자가 생각하는 완성 형태와 개발자가 이해한 완성 형태가 다르다. 구두로 전달받은 내용은 서로의 머릿속에서 다르게 해석된다. "가격표를 수정해주세요"라는 요청은 어떤 사람에게는 숫자만 바꾸는 것이고, 어떤 사람에게는 테이블 구조 전체를 재설계하는 것이다.
둘째, 작업 범위가 무한히 확장된다. 최초 요청에 없던 내용이 하나 둘 추가되기 시작하면, 어디까지가 이번 작업이고 어디부터가 다음 작업인지 판단하기 어려워진다. 이번에 내가 경험한 것이 정확히 이 상황이었다.
셋째, 검수 기준이 없다. 완성된 결과물을 봤을 때 "이게 맞는지 아닌지"를 판단할 기준이 없으니, 기획자의 주관적인 감각에 의존하게 된다. 그러면 수정 요청이 끝나지 않는다.
실제로 다른 프로젝트에서 사용하고 있는 요구사항 문서의 구조를 공유하면, 이런 형태다.
- 기능 명세: 어떤 경로로 어떤 요청을 보내면 어떤 응답이 오는지
- 비즈니스 규칙: 어떤 조건에서 어떤 동작이 이루어져야 하는지
- 구현 컴포넌트: 어떤 계층에서 어떤 역할을 담당하는지
- 구현 체크리스트: 단계별로 무엇을 만들어야 하는지
- 테스트 시나리오: 어떤 상황을 테스트해야 하는지
- 보안 고려사항: 어떤 부분에서 보안을 신경 써야 하는지
이렇게 정리된 문서가 있으면, 개발자는 "이 문서에 적힌 것을 만들면 된다"는 명확한 기준을 갖게 된다. 기획자도 "이 문서에 적힌 내용이 반영되었는지"를 기준으로 검수할 수 있다. 추가 요청이 들어오면 "이 부분은 최초 요구사항에 없던 내용이니, 별도 작업으로 분리하자"고 이야기할 수 있는 근거가 된다.
핵심은 이거다. 요구사항 문서는 개발자를 위한 것이 아니라, 기획자와 개발자 모두를 위한 합의문이다. 이번에 이 합의문 없이 작업을 시작한 것이 모든 혼란의 출발점이었다.
유비쿼터스 언어 - 같은 대상을 같은 이름으로 부르기
유비쿼터스 언어(Ubiquitous Language)는 에릭 에반스가 "도메인 주도 설계"에서 제안한 개념인데, 한마디로 말하면 "프로젝트에 참여하는 모든 사람이 같은 대상을 같은 이름으로 부르자"는 약속이다. 그래서 1루수가 누구야 금지..제발 금지..ㅠ
이 개념의 중요성을 체감한 것은 사실 이번이 처음이 아니다. 이전에 결제 관련 시스템을 개발할 때, 해당 기획자 분에게 "단가"라는 변수의 의미를 설명하는 과정에서 서로 이해가 맞지 않았던 경험이 있다. 나는 로직의 처리 순서를 따라가며 설명하려 했는데, 기획자 분께서 이해하는 "단가"의 의미와 내가 코드에서 사용하고 있는 "단가"의 의미가 달랐던 것이다. 당시에 서로의 도메인 지식 간극을 메우기 위해 상당한 감정 소모와 소통 비용이 발생했었다.
이번에도 비슷한 일이 반복되었다. "요금표"라는 단어 하나를 봐도, 기획자 분이 말하는 요금표와 내가 이해하는 요금표의 범위가 달랐다. 기획 쪽에서는 화면에 보이는 시각적 테이블 전체를 의미했고, 나는 데이터베이스에 저장된 가격 데이터를 의미했다. 이렇게 같은 단어가 다른 의미로 사용되면, 대화를 나눌수록 서로의 이해가 멀어진다.
그래서 이번에 같은 팀 개발자 분과 진행할 개선 회의에서는 모든 내용을 저맥락 커뮤니케이션 방식으로 정리하려 한다. 저맥락 커뮤니케이션이란, "상대방이 배경지식을 갖고 있다"고 가정하지 않고, 모든 개념을 풀어서 설명하는 소통 방식을 말한다. 구체적으로는 이런 목표를 세웠다.
- 모든 개념을 추상화한다: 기술 용어를 그대로 쓰지 않고, 그 용어가 무엇을 의미하는지를 함께 설명한다.
- 복잡도가 낮은 상세한 설명을 사용한다: 한 문장에 여러 개념을 담지 않고, 하나씩 풀어서 설명한다.
- 맥락을 하나씩 짚어나간다: 듣는 사람이 "왜 이 이야기를 하고 있는지"를 항상 알 수 있도록, 흐름을 끊지 않는다.
예를 들어 이런 차이다.
기술 중심 서술: "MemberService에서 BCrypt로 해싱된 비밀번호와 입력값을 비교하여 인증을 수행한다"
사용자 중심 서술: "사용자가 비밀번호 변경을 요청하면, 시스템은 현재 비밀번호가 맞는지 확인한 뒤 새 비밀번호로 변경한다"
두 번째 문장은 기획자도, 디자이너도, 사업팀도, 개발자도 동일하게 이해할 수 있다. 첫 번째 문장은 개발자만 이해할 수 있다. 슬랙 쓰레드가 100건이 넘어간 이유 중 하나는, 서로 다른 언어로 같은 대상에 대해 이야기하고 있었기 때문이다.
유비쿼터스 언어를 정리한다는 것은 거창한 게 아니다. 이 프로젝트에서 사용하는 핵심 용어를 목록으로 만들고, 각 용어의 정의를 한 문장으로 적어서 공유하는 것이다. "회원"이 뭔지, "주문"이 뭔지, "요금"이 뭔지, "단가"가 뭔지를 모두가 같은 의미로 사용하도록 합의하는 것만으로도 소통 비용이 크게 줄어든다.
시퀀스 다이어그램 - 그림으로 보면 기억에 남는다
시퀀스 다이어그램은 하나의 요청이 시스템 안에서 어떤 순서로 처리되는지를 시각적으로 표현한 그림이다. 사용자가 요청을 보내면, 어떤 구성 요소가 받고, 어떤 구성 요소가 처리하고, 어떤 구성 요소가 데이터를 조회하거나 저장하는지를 시간 순서대로 보여준다.
요구사항을 구두로 설명하거나 문서로만 전달하면, 듣는 사람의 도메인 지식 유무와 관계없이 머릿속에 오래 남지 않는다. 글로 적힌 열 줄의 설명보다, 흐름이 한눈에 보이는 한 장의 그림이 훨씬 기억에 잘 남는다. 그래서 이번 같은 팀 개발자와의 회의에서는 도식화된 그림을 기반으로 같은 자리에 모여 설명하는 방식을 취하려 한다.
여기서 중요하게 생각하는 원칙이 하나 있다. 시퀀스 다이어그램을 그릴 때 기술적인 개념을 최대한 덜어내는 것이다. 기획자나 사업팀 구성원이 봐도 전체 흐름을 머릿속에서 따라갈 수 있을 정도로 단순화한 표현을 사용할 예정이다. 목적은 "이 시스템이 기술적으로 어떻게 구현되어 있는지"를 보여주는 것이 아니라, "사용자의 요청이 어떤 단계를 거쳐 처리되는지"를 함께 이해하는 것이기 때문이다.
이번 작업에서 이런 다이어그램이 있었다면 무엇이 달라졌을까 생각해보면, 두 가지가 떠오른다.
첫째, "이 작업의 범위가 어디까지인지"가 명확해진다. 다이어그램에 그려진 흐름이 곧 작업 범위다. 새로운 요청이 들어왔을 때 "이 다이어그램에 없는 흐름이니 별도 작업으로 분리하자"고 판단할 수 있는 기준이 된다.
둘째, 예외 상황에서 어떤 일이 벌어지는지를 미리 합의할 수 있다. 이번에 겪은 문제 중 하나가 "가격 데이터가 틀렸을 때 어떻게 해야 하는지"에 대한 합의가 없었다는 점이다. 시퀀스 다이어그램에서는 정상 흐름뿐 아니라 예외 흐름도 함께 그리기 때문에, "이런 상황에서는 이렇게 동작한다"는 합의가 자연스럽게 이루어진다.
Mermaid라는 도구를 사용하면 텍스트 기반으로 시퀀스 다이어그램을 작성할 수 있고, 마크다운 문서 안에서 바로 렌더링된다. 별도의 다이어그램 도구를 사용하지 않아도 코드 저장소 안에서 버전 관리와 함께 유지할 수 있다는 장점이 있다.
클래스 다이어그램과 도메인 모델 - 유비쿼터스 언어를 구조로 만들기
클래스 다이어그램은 시스템을 구성하는 요소들이 어떤 속성과 동작을 가지고 있으며, 서로 어떤 관계로 연결되어 있는지를 그림으로 나타낸 것이다. 도메인 모델은 그중에서도 비즈니스 로직을 담고 있는 핵심 객체를 설계한 것을 말한다.
이번에 같은 팀 개발자분과의 회의에서 클래스 다이어그램을 그릴 때, 앞서 정리한 유비쿼터스 언어의 추상화된 개념을 기반으로 작성하려 한다. 유비쿼터스 언어 단계에서 이미 복잡성을 최대한 덜어냈기 때문에, 그 위에 만들어진 클래스 다이어그램과 도메인 모델은 자연스럽게 이해하기 쉬운 구조가 될 것으로 기대한다. 혹시 클래스 다이어그램만으로 이해가 어렵더라도, 앞서 정리한 유비쿼터스 언어 문서와 시퀀스 다이어그램을 함께 보면 전체 그림을 이해하는 데 도움이 될 것이다.
이번에 작업하면서 기존 코드가 하드코딩과 복잡한 구조로 작성되어 있었는데, 클래스 다이어그램이 사전에 정리되어 있었다면 "현재 구조가 어떻게 되어 있고, 어떤 부분을 어떻게 바꿔야 하는지"를 논의하는 시간이 훨씬 줄었을 것이다.
다른 프로젝트에서 사용하고 있는 구조를 예로 들면, 계층별로 역할이 나뉘어 있다.
- 인터페이스 계층: 외부 요청을 받고 응답을 돌려주는 역할을 한다. 컨트롤러와 요청/응답 객체가 여기에 속한다.
- 애플리케이션 계층: 여러 서비스를 조합하여 하나의 기능을 완성하는 역할을 한다.
- 도메인 계층: 비즈니스 규칙과 유효성 검증을 담당한다. 도메인 모델과 서비스가 여기에 속한다.
- 인프라스트럭처 계층: 실제 데이터베이스 접근이나 외부 시스템 연동을 담당한다.
여기서 특히 중요한 것이 도메인 모델이다. 도메인 모델은 단순히 데이터를 담는 그릇이 아니라, 비즈니스 로직을 스스로 수행할 수 있는 객체여야 한다. 예를 들어 "회원" 도메인 모델은 비밀번호 변경, 아이디 유효성 검증, 이름 유효성 검증 같은 동작을 직접 가지고 있다. 이렇게 설계하면 "이 규칙은 어디서 처리되는가?"라는 질문에 항상 명확한 답을 줄 수 있다.
이번에 겪은 가격 정보 불일치 문제도, 도메인 모델에 "가격 정보의 유효성을 검증하는 로직"이 명시적으로 존재했다면 더 빠르게 발견할 수 있었을 것이다. 검증 로직이 코드 곳곳에 흩어져 있거나 아예 없는 상태에서는, 잘못된 데이터가 그대로 화면에 노출되는 것을 막기 어렵다.
ERD 설계 - 테이블을 먼저 만들던 습관에서 벗어나기
ERD(Entity Relationship Diagram)는 데이터베이스의 테이블 구조와 테이블 간 관계를 시각적으로 표현한 다이어그램이다. 어떤 테이블에 어떤 컬럼이 있고, 테이블끼리 어떤 관계로 연결되어 있으며, 어떤 제약 조건이 걸려 있는지를 한눈에 파악할 수 있다.
이전까지의 작업 방식을 돌아보면, 데이터베이스 테이블을 먼저 만들고 그 위에 개발을 진행하는 순서였다. 테이블 구조가 곧 설계의 출발점이었다. 그런데 이번 이슈를 경험하면서, 이 순서가 뒤집혀야 한다는 것을 느꼈다. 이해관계자와의 소통을 기반으로 요구사항을 정리하고, 유비쿼터스 언어를 합의하고, 시퀀스 다이어그램으로 흐름을 그리고, 클래스 다이어그램으로 구조를 설계한 다음에, 그 결과물을 바탕으로 마지막에 ERD를 작성하는 것이 올바른 순서라는 것을 이번에 확실히 배웠다.
이 순서가 중요한 이유가 하나 더 있다. 현재 해당 서비스는 TypeScript와 Nest.js 기반으로 운영되고 있는데, 추후 Kotlin과 Spring Boot, JPA 기반으로 전환할 예정이다. 기술 스택이 바뀌면 데이터 접근 방식도 달라지기 때문에, 테이블 구조에서 출발하는 것보다 도메인 모델에서 출발하는 것이 전환 과정에서 훨씬 유리하다. 그래서 이번 같은 팀 개발자분과의 회의에서 ERD를 마지막 단계에 배치하고, 도메인 모델에서 ERD로 자연스럽게 이어지는 흐름을 연습해보려 한다.
이번 경험에서 ERD와 관련해 가장 뼈아팠던 부분은 "데이터의 정합성"이었다. 가격 정보가 여러 곳(데이터베이스, 디자인 시안, 기획 문서)에 분산되어 있었고, 어디가 원본인지도 불명확했다. ERD가 명확하게 정의되어 있었다면, "이 가격 데이터의 원본은 이 테이블의 이 컬럼이고, 화면에 표시되는 값은 여기서 가져온다"는 것이 분명했을 것이다.
ERD를 작성할 때 신경 쓰는 원칙들을 정리하면 이렇다.
- 참조 무결성: 테이블 간의 관계가 외래 키로 명시되어야 한다. 예를 들어 주문 테이블이 회원 테이블을 참조한다면, 존재하지 않는 회원의 주문이 생길 수 없도록 제약이 걸려 있어야 한다.
- 중복 방지: 고유 제약 조건을 통해 같은 데이터가 중복으로 들어가는 것을 막아야 한다.
- 삭제 정책: 데이터를 물리적으로 삭제할 것인지, 삭제 표시만 해둘 것인지를 미리 정해야 한다.
- 인덱스 설계: 자주 조회하는 조건에 맞는 인덱스를 미리 설계해야 한다.
특히 돈과 관련된 데이터를 다룰 때는, 원본 데이터(실제 설정된 가격)와 화면에 표시되는 데이터(스냅샷)의 관계가 명확해야 한다. 이번에 겪은 문제의 본질은, 원본 데이터와 표시 데이터 사이의 관계가 설계 단계에서 정의되지 않았기 때문에 발생한 것이었다.
Claude Skills - 설계 자동화와 안전한 코드 전환을 위한 도구
지금까지 이야기한 요구사항 정리, 시퀀스 다이어그램, 클래스 다이어그램, ERD 작성은 모두 중요하지만, 매번 수작업으로 하기에는 시간이 많이 든다. 특히 이번처럼 급한 작업에서는 "설계 문서 만들 시간이 없다"는 이유로 생략하기 쉽다.
이 문제를 해결하기 위해, 다른 프로젝트에서는 Claude Code의 커스텀 스킬(Custom Skills)을 만들어서 사용하고 있다. Claude Code는 명령줄에서 동작하는 인공지능 코딩 도우미인데, 여기에 프로젝트에 맞는 명령어를 직접 정의해서 사용할 수 있다.
현재 정의되어 있는 설계 문서 자동화 스킬은 네 가지다.
- /requirements: 기능 이름을 입력하면, 해당 기능의 요구사항 문서를 자동으로 생성한다. 기능 명세, 비즈니스 규칙, 구현 컴포넌트, 테스트 시나리오까지 포함된 문서가 나온다.
- /sequence-diagrams: 요구사항 문서를 기반으로, 각 기능의 정상 흐름과 예외 흐름을 시퀀스 다이어그램으로 생성한다.
- /class-diagram: 요구사항 문서를 기반으로, 계층별 클래스 다이어그램을 생성한다. 기존 코드의 네이밍 패턴을 분석해서 일관된 구조를 만들어준다.
- /erd: 요구사항 문서를 기반으로, ERD와 테이블 상세 명세를 생성한다. 기존 엔티티 구조를 분석해서 일관된 설계를 유지한다.
이 네 가지 스킬의 실행 순서도 정해져 있다. 요구사항 문서가 먼저 만들어지고, 그 문서를 기반으로 시퀀스 다이어그램이 만들어지며, 다시 그것을 기반으로 클래스 다이어그램과 ERD가 만들어진다. 각 단계가 이전 단계의 산출물을 참조하기 때문에, 문서 간의 일관성이 자연스럽게 유지된다. 각 스킬이 생성하는 문서에는 자체 검증 체크리스트가 포함되어 있어서, 생성 시점에 누락된 내용이 있는지 자동으로 확인해준다.
그런데 이번 경험을 통해, 설계 문서 자동화만으로는 충분하지 않다는 것도 느꼈다. 앞서 이야기했듯이, 해당 서비스는 추후 TypeScript와 Nest.js에서 Kotlin과 Spring Boot, JPA 기반으로 전환될 예정이다. 기술 스택을 전환한다는 것은 기존에 동작하던 로직을 새로운 언어와 프레임워크로 다시 작성한다는 뜻인데, 이 과정에서 기존 로직이 의도치 않게 변경되는 위험이 있다.
그래서 Claude Skills에 하나의 원칙을 더 추가하려 한다. 기존 로직에 영향을 주는 신규 로직을 구현할 때, 영향을 받는 기존 로직에 대한 테스트 코드를 먼저 작성한 뒤에 구현을 시작하도록 스킬을 구성하는 것이다. 이렇게 하면 기존에 동작하던 기능이 새로운 코드에 의해 깨지는 것을 사전에 감지할 수 있다. "먼저 테스트를 작성하고, 그 테스트가 통과하는 코드를 구현한다"는 테스트 주도 개발 방식을 스킬 자체에 내장하는 것이다.
이 도구가 이번 상황에 있었다면 어떻게 달라졌을지 상상해본다. 작업을 시작하기 전에 /requirements를 실행해서 요구사항 문서를 먼저 만들었다면, 해당 기획자 분과 "이 문서의 내용이 맞느냐"를 기준으로 대화할 수 있었을 것이다. 가격 데이터의 원본이 어디인지가 ERD에 명시되어 있었다면, 데이터 불일치를 훨씬 빠르게 발견했을 것이다. 슬랙 쓰레드 100건 대신, 문서 한 장을 공유하고 합의하는 것으로 끝났을 수 있다.
이 경험에서 배운 것들
정리하면 이렇다.
첫째, 급한 작업일수록 요구사항 정리가 필요하다. "시간이 없으니까 일단 코드부터 치자"는 판단이 결과적으로 더 많은 시간을 소모하게 만든다. 30분을 투자해서 요구사항을 정리하면, 3시간의 수정 요청과 100건의 슬랙 쓰레드를 줄일 수 있다.
둘째, 같은 단어를 같은 뜻으로 사용하는 것이 소통의 기본이다. "단가"가 무엇인지, "요금표"가 무엇인지를 명시적으로 합의하는 것만으로도 불필요한 감정 소모와 소통 비용을 크게 줄일 수 있다.
셋째, 시각적 다이어그램은 텍스트보다 기억에 남고 합의하기 쉽다. 슬랙에서 텍스트로 100건을 주고받는 것보다, 한 장의 그림을 놓고 같은 자리에서 10분 이야기하는 것이 훨씬 효율적이다.
넷째, 테이블을 먼저 만들고 개발하는 순서가 항상 맞는 것은 아니다. 요구사항 정리, 유비쿼터스 언어 합의, 시퀀스 다이어그램, 클래스 다이어그램을 거친 뒤에 ERD를 작성하는 것이 더 견고한 설계를 만든다.
다섯째, 도구를 활용해서 설계 과정의 비용을 줄일 수 있다. Claude Skills처럼 설계 문서를 자동으로 생성하고, 기존 로직에 대한 테스트를 먼저 작성하도록 유도하는 도구가 있으면, "설계에 시간을 들일 여유가 없다"는 핑계가 사라진다.
여섯째, 슬랙 쓰레드는 실시간 소통 도구이지, 히스토리 관리 도구가 아니다. 중요한 합의 내용은 반드시 별도의 문서로 정리해야, 나중에 참여하지 않은 사람도 맥락을 파악할 수 있다.
마치며
이번 경험은 꽤 고통스러웠지만, 그만큼 많은 것을 돌아보게 해주었다. 코드를 잘 치는 것도 중요하지만, 코드를 치기 전에 "무엇을 왜 만드는지"를 합의하는 과정이 더 중요하다는 것을 몸으로 느꼈다.
현재 해당 페이지의 하드코딩과 복잡한 설계로 작성된 기존 코드를 같은 팀 개발자 분과 함께 개선하는 작업을 앞두고 있다. 그 자리에서 이 글에서 다룬 내용들, 즉 요구사항을 먼저 정리하고, 유비쿼터스 언어로 용어를 합의하고, 시퀀스 다이어그램으로 흐름을 그리고, 클래스 다이어그램과 도메인 모델로 구조를 설계한 뒤에 ERD를 작성하는 과정을 함께 실습할 예정이다. 그리고 이 과정을 앞으로도 반복할 수 있도록 Claude Skills를 활용한 자동화 방안도 공유할 생각이다.
같은 상황을 겪고 있는 분들에게 이 글이 조금이나마 도움이 되면 좋겠다. 설계는 거창한 게 아니다. "우리가 만들 것이 무엇인지"를 한 장의 문서로 정리하는 것부터가 설계의 시작이다. 그리고 그 한 장의 문서가, 슬랙 쓰레드 100건을 막아줄 수 있다고 생각한다.
출처.
'Study for. > Engineering Culture' 카테고리의 다른 글
| Ktlint가 선명하게 코드를 핥고 있었다 (1) | 2026.02.06 |
|---|
