설계 결정 문서에서 "왜 이렇게 했나"를 영어로 쓸 때, 문장이 흐려지는 자리
스탠드업에서는 영어가 됩니다. "Yesterday I worked on the caching layer, today I'll pick up the flaky test." 짧고, 상대도 맥락을 알고, 틀려도 다음 문장으로 넘어가면 그만이죠.
그런데 같은 사람이 ADR(설계 결정 기록)이나 장애 보고서를 앉아서 쓰기 시작하면 문장이 갑자기 흐려집니다. 여기서는 "무엇을 했다"가 아니라 "왜 그렇게 판단했는지", 그리고 "무엇을 포기했는지"를 남겨야 하거든요. 반년 뒤에 이 문서를 읽는 사람은 결론보다 근거를 봅니다. 그 근거가 "it was better" 같은 문장으로 뭉개져 있으면, 결국 같은 논의를 처음부터 다시 하게 됩니다.
트레이드오프를 쓰는 건 어렵습니다. 한국어로도 어렵죠. 영어로 옮기면 "선택했다"와 "포기했다"가 같은 무게로 안 실리고, 근거가 의견처럼 읽히고, 장애 보고서에서는 사실과 추정이 뒤섞입니다. 오늘은 그 흐려지는 자리들을 하나씩 문장 단위로 짚어볼게요.
"더 나았다"로 끝내지 말고, 무엇과 비교해 나았는지 쓰기
설계 결정에서 가장 흔한 뭉개짐이 "better"입니다. 무엇보다 나은지, 어떤 축에서 나은지가 빠지면 판단이 아니라 취향처럼 읽혀요.
여기서 핵심은 over입니다. "A over B"는 "B를 검토했지만 A를 골랐다"는 비교 자체를 문장에 박아 넣어요. 그리고 because 뒤에는 형용사("better")가 아니라 사실("access patterns are relational")을 놓습니다. 형용사는 평가고, 명사구는 근거예요. 읽는 사람은 근거를 보고 스스로 "better"를 판단합니다. 결론을 대신 내려주면 오히려 신뢰가 떨어집니다.
포기한 것을 문장으로 남기기 — trade-off는 동사로 살아납니다
좋은 ADR은 선택한 것만큼 포기한 것을 분명히 씁니다. 그런데 여기서 be동사로 상태만 서술하면 "그냥 그런 단점이 있다" 정도로 약해져요.
"is faster but has downsides"는 상태 나열입니다. be동사와 have로만 이어지면 "빠르다, 단점이 있다" 두 사실이 나란히 놓일 뿐, 둘이 맞바꿈 관계라는 게 안 보여요. 반면 cut A at the cost of B는 동사 하나로 "무엇을 얻고 무엇을 내줬는지"를 한 문장에 묶습니다. 트레이드오프는 상태가 아니라 교환이니까, 상태 동사(be, have)보다 행위 동사(cut, gain, trade, sacrifice)로 써야 살아납니다. some downsides처럼 막연한 복수도 피하고, write amplification처럼 구체적인 대상을 지목하세요.
장애 보고서에서 사실과 추정을 시제와 조동사로 갈라내기
장애 보고서에서 제일 위험한 건 확인된 사실과 아직 추정인 것이 같은 톤으로 섞이는 겁니다. 영어에서는 시제와 조동사가 이 경계를 그어줍니다.
before는 두 문장 다 단정 과거("caused", "was")입니다. 읽는 사람은 둘 다 확정 사실로 받아들이는데, 실제로 캐시 부분은 아직 추정이라면 나중에 신뢰가 깨져요. after는 확인된 트리거만 단정 과거로 쓰고("triggered"), 추정은 likely와 함께 두고, 마지막에 have not confirmed로 불확실성의 범위까지 명시합니다. 장애 보고서에서 조동사와 부사(likely, appear to, presumably)는 겸손이 아니라 정확성입니다. 확정과 추정을 문장 형태로 구분해두면, 후속 조사가 방향을 잃지 않아요.
원인을 쓸 때 사람이 아니라 시스템을 주어로
포스트모템에서 "누가 잘못했나"로 읽히면 문서의 목적이 무너집니다. 영어에서 주어 선택이 이 인상을 크게 좌우해요.
before는 "The engineer forgot"으로 사람을 주어에 세웠습니다. 문법은 맞지만, 원인 분석이 아니라 책임 추궁처럼 읽혀요. after는 config를 주어로 두고 수동태(was not updated)로 씁니다. 여기서 수동태는 "누가"를 흐리려는 회피가 아니라, 시스템의 어떤 상태가 문제였는지에 초점을 맞추는 장치예요. 그리고 which left the service pointing으로 그 상태가 낳은 결과까지 인과로 이어줍니다. broke 같은 막연한 동사 대신 무엇이 어떻게 잘못됐는지(pointing at the old endpoint)를 구체적으로 쓰는 게 재발 방지에 훨씬 쓸모 있습니다.
제약과 가정을 조건절로 붙여 결정의 유효 범위를 남기기
모든 설계 결정에는 유효 기간이 있습니다. "이 전제가 유지되는 한"이라는 조건을 빼고 결론만 쓰면, 전제가 바뀐 뒤에도 옛 결정이 정답인 것처럼 남습니다.
before의 "It is fine"은 오늘 기준의 판단인데, 기한이 없어서 영원한 결론처럼 굳습니다. after는 세 가지를 더했어요. 첫째 not shard(안 함) 대신 defer(미룸)로 바꿔, 이건 포기가 아니라 유보임을 분명히 했습니다. 둘째 since 절로 그 유보가 성립하는 전제(under 500 rps)를 박았고요. 셋째 revisit ... if로 재검토 조건을 남겼습니다. if절의 이 조건이 나중에 문서를 "살아 있게" 만듭니다. 조건 없이 단정하면 문서는 빨리 낡고, 조건을 붙이면 언제 다시 펼쳐야 하는지가 스스로 말해줍니다.
정리하면, 설계 문서와 장애 보고서의 영어는 "무엇을 했다"의 영어와 다릅니다. 비교 대상을 데려오는 over, 교환을 표현하는 동사, 사실과 추정을 가르는 시제와 조동사, 사람 대신 시스템을 세우는 주어, 유효 범위를 남기는 조건절. 문법 포인트 자체는 새롭지 않지만, 판단과 근거를 남기는 자리에서는 이 선택 하나하나가 문서의 수명을 정합니다.
이런 문장은 회의처럼 즉석에서 만들어지지 않아서, 한 번 직접 써보고 왜 그렇게 쓰는지 짚어둔 문장만 다음에 다시 나옵니다. 오늘 쓴 ADR 한 줄을 그렇게 남겨두면, 반년 뒤 같은 결정을 마주했을 때 처음부터 다시 고민하지 않아도 됩니다.