왜 스펙 문서가 아니라 '의사결정'을 남기는가

이 API 응답, Figma 디자인이랑 다르지 않나요?

릴리즈 직전 금요일. Slack에 올라온 개발자의 한마디에 팀 전체가 얼어붙습니다.

PM은 Jira 티켓을 꼼꼼히 업데이트하고 있었습니다. 디자이너는 Figma를 완벽하게 다듬고 있었습니다. 개발자는 GitHub에서 PR을 쏟아내고 있었습니다. 모두가 자기 영역에서 최선을 다하고 있었는데, 통합하는 순간 ‘인식의 차이’가 드러납니다.

금요일 저녁부터 시작되는 Slack 고고학. “그 스펙 어디서 결정된 거였지?” “이 API, 원래 티켓이랑 다른데 누가 바꿨어?” — 답은 아무도 모릅니다. 결정이 내려진 그 순간의 맥락이 어디에도 남아있지 않으니까요.

저희는 이 ‘아무도 잘못한 게 없는데 프로젝트가 타오르는 지옥’에 수없이 빠졌습니다. Beaket은 그 경험에서 태어난 도구입니다.

스펙 문서는 거짓말을 하게 되어 있다

스펙 문서가 나쁜 게 아닙니다. 구조가 문제입니다.

정보는 역할별로 다른 곳에 삽니다 — PM은 Jira에, 디자이너는 Figma에, 개발자는 GitHub에. 이건 자연스러운 일이고, 바꿀 필요도 없습니다. 각 도구가 해당 영역에서 최고니까요.

문제는 이렇게 흩어진 정보를 한 곳에 복사해서 ‘원본’으로 만들려는 시도입니다.

Notion이나 Wiki에 옮겨 적는 순간, 정보는 두 개가 됩니다. 한쪽이 업데이트되면 다른 쪽은 거짓이 됩니다. 관리가 멈춘 스펙 문서는 과거의 판단을 잃고, 실제 구현과 점점 멀어지는 유물이 되어갑니다.

이건 의지의 문제가 아니라 구조의 문제입니다. 복사본이 존재하는 한, 반드시 일어납니다.

그래서 저희는 ‘정보를 한 곳에 모은다’는 접근을 버렸습니다. 새로운 Wiki를 또 만들어봐야 결과는 같으니까요.

Beaket이 하는 일은 흩어진 정보 사이에 관계를 잇는 것입니다.

Figma나 GitHub의 정보를 Beaket에 복사할 필요가 없습니다. 각 도구가 원본으로 남습니다. Beaket은 그 원본들을 ‘왜 이런 판단을 했는가’라는 맥락으로 연결할 뿐입니다.

구체적으로, 세 가지 노드로 프로젝트의 판단을 구조화합니다.

이 세 가지가 엣지로 서로 연결되어 의사결정 그래프를 형성합니다. Beaket에 상세한 스펙을 쓰지 않습니다. 적는 건 ‘무엇을 결정했는가’, ‘왜’, ‘무엇과 연결되는가’ — 그것뿐입니다.

솔직히 말하면, 이 부분이 저희가 가장 많이 토론한 지점입니다.

“더 자세하게 쓸 수 있어야 하지 않나?” 당연히 그런 의견이 있었습니다. 하지만 상세하게 쓸 수 있게 하는 순간, 그건 새로운 Wiki가 됩니다. 그리고 Wiki는 반드시 썩습니다.

그래서 Beaket에는 ‘너무 많이 쓰지 않는다’는 제약을 의도적으로 넣었습니다.

기준은 단순합니다 — 6개월 후의 내가, 그 이유를 찾으러 올 것인가? 올 것 같으면 쓴다. 아니면 쓰지 않는다. 파라미터 목록이나 구현 절차는 GitHub에 맡깁니다. Beaket이 갖는 건 ‘왜 그렇게 됐는가’의 최소 단위뿐입니다.

이건 트레이드오프입니다. Beaket은 포괄적인 설계 문서 도구가 될 수 없습니다. 의도적으로 그렇게 만들었습니다.

한 가지 더, 저희가 만들어서 다행이라고 생각하는 메커니즘이 있습니다.

Spec이 작성된 후, 디자이너와 개발자가 각각 독립적으로 ‘Ready’ 플래그를 세웁니다. 디자이너는 “UI 관점에서 요구사항을 이해했다”, 개발자는 “기술적으로 이해했다”는 의미입니다. 양쪽 플래그가 모두 서야 그 Spec은 ‘Ready’가 됩니다.

이건 승인 워크플로우가 아닙니다. 악수입니다.

‘읽었습니다’가 아니라 ‘내 영역에서 봤을 때, 이걸로 진행할 수 있습니다’라는 선언. 애매한 상태로 구현이 시작되는 걸 구조적으로 막고 있습니다.

그리고 Ready 이후에 Spec이 변경되면, 영향 범위 — 연결된 Brief, ADR — 가 자동으로 표시됩니다. 더 이상 Slack 히스토리를 뒤질 필요가 없습니다.

Beaket은 변경 이력을 ‘누가, 언제, 무엇을 바꿨는가’뿐만 아니라, ‘왜 바꿨는가’까지 기록합니다.

텍스트를 선택하면 그 문구가 어느 시점에, 누구에 의해, 어떤 이유로 수정되었는지 추적할 수 있습니다. 저희는 이걸 Decision Trail이라고 부릅니다.

화려한 기능은 아닙니다. 하지만 6개월 후 “이 스펙, 왜 이렇게 된 거야?”라는 질문을 받았을 때, 답이 거기에 있습니다. 그것만으로도 팀의 의사결정 속도는 달라집니다.

Beaket이 모든 팀에 맞을 거라고 생각하지 않습니다.

같은 공간에서 일하며 컨텍스트가 자연스럽게 공유되는 소규모 팀에게는 과할 수 있습니다. 반대로 수백 명 규모의 조직에서는 아직 충분히 검증하지 못했습니다.

저희가 확신하는 건 딱 하나입니다. 판단의 배경이 사라지면, 반드시 비용이 발생한다. 그리고 그 비용은 팀이 커질수록, 시간이 지날수록 기하급수적으로 늘어납니다.

Beaket은 그 비용을 구조로 억제하기 위한 도구입니다. 만능 해결책이 아니라, 보험에 가깝습니다.

“이 설계, 왜 이렇게 된 건지 아무도 설명 못 해” — 만약 여러분의 팀에서도 이런 일이 일어나고 있다면, 하나의 결정을 연결하는 것부터 시작해 보세요.