기능은 잘 작동하는데, 팀은 계속 같은 질문을 반복하는 경우가 있습니다.

“이 API는 왜 이렇게 호출하나요?”

“이 값은 숫자인가요, 문자열인가요?”

“이 상태가 되면 다음에는 무엇을 해야 하나요?”

문서가 없어서만 생기는 문제는 아닙니다. 

문서가 있어도 매번 해석해야 한다면, 팀은 계속 멈춰서 확인해야 합니다.

API를 단순한 기술 규약으로만 보면 설계의 중요한 목적을 놓치게 됩니다.

API는 시스템과 시스템 사이의 규칙이기 전에, 

팀과 팀 사이의 약속입니다.

좋은 API는 기준을 보여줘야 합니다.

좋은 약속은 모든 내용을 외우지 않아도 어느 정도 의도를 유추할 수 있게 합니다. 

이름을 정하는 방식과 요청·응답의 구조가 일정하면 

새로운 팀원이 합류해도 시스템을 이해하는 데 드는 시간이 줄어듭니다.

반대로 기준이 없는 API는 매번 새로운 해석을 요구합니다.

어떤 기능은 GET으로 조회하고 비슷한 기능은 POST로 조회합니다. 

어떤 리소스는 단수로 쓰고, 어떤 리소스는 복수로 씁니다. 상태값의 이름과 의미도 기능마다 다릅니다.

기능은 모두 동작할 수 있습니다. 하지만 사용하는 사람은 매번 만든 사람에게 물어봐야 합니다.

이런 질문이 쌓이면 개발 속도가 느려지는 것처럼 보입니다. 

실제로는 작성 속도보다 이해하고 확인하고 다시 설명하는 시간이 커진 것입니다.

예외도 적용될 기준을 남겨야합니다.

팀이 커질수록 모든 상황을 문서로 설명하기는 어렵습니다. 

그래서 중요한 것은 모든 예외를 없애는 일이 아니라, 예외를 판단하는 기준을 공유하는 일입니다.

API를 볼 때는 순서가 있습니다.

먼저 같은 대상을 같은 이름으로 부르는지 봅니다.

그다음 같은 행동을 비슷한 방식으로 표현하는지 확인합니다.

마지막으로 예외가 생겼을 때 왜 그렇게 결정했는지 설명할 수 있어야 합니다.

이 기준이 있으면 모든 사람이 매번 처음부터 논의할 필요가 없습니다.

반대로 약속이 없으면 작은 일도 회의의 안건이 됩니다. 

이름 하나를 정하는 데 시간이 걸리고, 상태 하나를 해석하는 데 담당자의 설명이 필요합니다. 

팀은 기능을 만드는 시간보다 기능을 이해시키는 데 더 많은 시간을 쓰게 됩니다.

일관성은 팀을 느리게 만드는 규칙이 아닙니다.

일관성은 설명 비용을 줄여서 팀이 다음 일을 시작할 수 있게 하는 장치입니다.

 이 약속을 업무 대화에도 적용해야합니다.

API가 팀 사이의 약속이라면, 업무 대화도 사람과 사람 사이의 인터페이스라고 볼 수 있습니다.

업무 메신저의 대화 안에는 배경, 결정, 담당자, 후속 액션, 진행 상태가 함께 들어옵니다.

 대화가 진행되는 동안에는 모두가 맥락을 이해하고 있는 것처럼 보입니다.

하지만 시간이 지나면 질문이 다시 생깁니다.

“그때 어떤 맥락에서 결정했죠?”

“이건 누가 맡기로 했죠?”

“다음 단계가 뭐였죠?”

결정은 기억나는데 왜 그렇게 결정했는지는 남지 않을 수 있습니다. 

담당자는 정해졌는데 언제까지 무엇을 해야 하는지는 흐려질 수 있습니다. 

대화 중에 나온 후속 액션이 별도의 업무로 이어지지 않을 수도 있고요.

만들고 있는 제품인 CROS Air가 출발한 이유도 여기에 있습니다.

업무 메신저의 대화를 단순히 쌓아두는 것이 아니라, 

대화 속에서 결정된 내용과 실행 항목이 이어지도록 업무 흐름으로 연결하는 일입니다.

하나의 Thread 안에서 맥락과 결정이 이어지고, 담당자와 다음 행동이 분명해지면

 대화는 기록으로만 남지 않습니다. 팀이 다시 움직일 수 있는 기준이 됩니다.

기술에서 좋은 인터페이스는 서로 다른 시스템이 같은 약속 아래에서 움직이게 합니다. 
업무에서 좋은 구조는 서로 다른 사람이 같은 맥락과 기준 아래에서 움직이게 합니다.

둘 다 핵심은 같습니다.

모든 것을 설명해야 하는 구조가 아니라, 

약속이 일관되어 설명하지 않아도 이해할 수 있는 구조를 만드는 것입니다.

좋은 API가 협업 비용을 줄이는 것처럼, 좋은 업무 구조도 반복되는 설명과 확인을 줄여야 합니다.

팀이 반복해서 설명하고 확인하는 내용부터 하나의 약속으로 정리해야 합니다.