클린 코드를 넘어, ‘클린 컨텍스트’로

1. 코드에는 남지 않는 이유

VIP 고객에게는 왜 15%를 할인하는가. 특정 국가에서는 왜 쿠폰을 사용할 수 없는가. 임시로 넣었다던 조건은 왜 일 년째 남아 있는가.

변수명이 명확하고 함수가 깔끔하게 나뉘어 있어도, 이런 질문에 답할 수 없다면 코드를 바꾸기는 어렵다. 그리고 답을 찾으려는 순간, 우리는 코드 밖으로 나간다.

“그때 기획팀과 이야기한 내용인데요.”

“서버 제약 때문에 임시로 바꿨어요.”

“당시 담당자에게 물어봐야 할 것 같아요.”

코드 밖에서 답을 찾아 헤매는 사람은 개발자만이 아니다. 기획자는 정책의 근거를, 디자이너는 변경 이유를, PM은 일정의 선행 조건을 찾아다닌다. 고객과 합의한 일정이 실무자에게 전달되지 않거나, 정책이 바뀌었는데 어느 작업까지 반영됐는지 알 수 없는 일도 생긴다. 직군과 상관없이, 일을 시작하려면 먼저 사람을 찾아다니며 빠진 맥락부터 복원해야 한다.

우리는 코드의 변경 이력은 꼼꼼히 관리하면서, 그 코드를 바꾸게 만든 결정의 이력은 사람의 기억에 맡기곤 한다. 코드가 복잡하게 얽히는 것은 경계하면서도, 의사결정과 업무 흐름이 특정인의 기억에 의존하는 것은 관행으로 받아들인다.

이렇게 남겨진 빈칸은 기술 부채와 닮았다. 당장은 아무 비용도 들지 않는 것처럼 보이지만, 다음 사람이 같은 질문을 하고, 같은 기록을 뒤지고, 이미 내려진 결정을 재확인할 때마다 이자가 붙는다. 잘못 이해한 채 일을 진행했다면 재작업이라는 연체료까지 더해진다.

결정의 이유와 현재 상태를 확인하기 어려워 같은 맥락을 반복해서 복원해야 하는 상태. 나는 이것을 조직의 ‘맥락 부채’라고 부르고 싶다.

2. 유능함을 인정하는 것과 의존을 당연하게 여기는 것은 다르다

조직에 오래 있으면 감각이 생긴다. 누구에게 물어야 답이 빠른지, 어떤 문서가 실제로 유효한지, 기록되지 않은 예외가 무엇인지 알게 된다.

그 경험의 가치를 가볍게 볼 수는 없다. 문서에 없는 상황을 해석하고, 우선순위를 정하고, 서로 다른 이해관계를 조율하는 능력은 실제 전문성이다. 불완전한 정보 속에서 판단하고 결과를 만들어 내는 사람은 조직에 필요하다.

문제는 그 능력을 인정하는 데서 그치지 않고, 조직의 정보 공백까지 계속 그 능력으로 메우도록 요구할 때다.

“그 정도는 알아서 파악해야지.”

“일할 때는 센스가 있어야지.”

“우리도 원래 그렇게 배웠어.”

이 말이 반복되면 조직이 제공하지 않은 정보의 비용이 개인의 역량 문제로 넘어간다. 조직이 진 맥락 부채를 개인이 ‘센스’라는 이름으로 대신 갚는 셈이다. 기록되지 않은 결정을 찾아내지 못한 사람은 센스가 부족하다는 평가를 받고, 같은 혼선을 능숙하게 수습하는 사람은 유능하다는 평가를 받는다. 정작 그 혼선이 반복되는 이유와 이를 줄이는 일은 평가에서 빠진다.

여기서는 두 가지 일을 구분할 필요가 있다.

하나는 새로운 상황을 해석하고, 상충하는 목표와 위험 사이에서 판단하는 일이다. 다른 하나는 이미 내려진 결정이 무엇이었는지 매번 수소문해 복원하는 일이다.

현실에서는 두 일이 섞여 있고, 둘 다 경험과 능력을 요구한다. 그러나 이미 내려진 결정을 잘 복원하는 사람이 있다는 사실이, 조직이 계속 같은 비용을 치러야 할 이유는 되지 않는다.

판단을 서두르게 만드는 것이 목표는 아니다. 줄여야 할 것은 판단을 시작하기 위해 같은 사실을 다시 찾아내는 시간이다.

3. 클린 컨텍스트는 기록의 양으로 정해지지 않는다

여기서 필요한 것이 ‘클린 컨텍스트’다.

나는 클린 컨텍스트를 필요한 사람이 적절한 권한으로 결정의 이유와 현재 유효한 기준, 실제 업무에 반영된 상태를 확인하고 그 근거를 검증할 수 있도록 맥락을 관리하는 일이라고 정의하고 싶다.

이를 위해서는 적어도 두 가지 맥락이 연결돼야 한다.

첫째는 의사결정 맥락이다. 무엇을, 왜, 누가 결정했는지 남기는 것이다. 필요한 경우 검토한 대안과 당시의 제약도 포함한다. 그 결정이 어떤 조건에서 유효하고, 언제 바뀌었으며, 무엇으로 대체됐는지 확인할 수 있어야 한다.

개발자라면 여기서 ADR(Architecture Decision Record, 아키텍처 의사결정 기록)을 떠올릴 것이다. ADR은 결정의 배경·내용·상태·영향을 남기며, 기술적 조건뿐 아니라 사회적·프로젝트 맥락과 결정의 합의(accepted)·폐기(deprecated)·대체(superseded) 상태도 포함한다. 이 글에서 말하는 클린 컨텍스트는 이 발상을 정책·일정·고객 합의 등 업무 전반에 적용하고, 실제 업무 반영 상태도 함께 추적하려는 관점이다. 그래서 두 번째 맥락이 필요하다.

둘째는 업무 흐름 맥락이다. 누가 무엇을 언제까지 해야 하는지, 어떤 조건이 충족돼야 시작할 수 있는지, 무엇을 확인해야 완료로 볼 수 있는지를 연결하는 것이다. 결정이 내려졌다는 사실과 함께, 그 결정에 따른 일이 어디까지 진행됐는지도 드러나야 한다.

가상의 할인 정책을 예로 들어 보자. VIP 고객의 재구매를 유도하기 위해 15% 할인을 제공하기로 했다면, 할인율과 함께 결정의 목적과 적용 대상, 예외 조건, 책임자와 재검토 시점을 남길 수 있다.

이후 비용 부담을 고려해 다음 분기부터 할인율을 10%로 바꾸기로 했다면, 새 결정을 기록하는 것으로는 부족하다. 기존 15% 정책이 언제까지 유효한지 표시하고, 변경의 영향을 받는 화면과 서버 로직, 고객 안내와 검증 항목을 연결한다.

화면 수정은 끝났지만 서버 작업은 진행 중이라면 그 차이도 확인할 수 있어야 한다. 담당자가 “변경됐어요”라고 말했을 때, 그것이 정책의 확정을 뜻하는지 실제 서비스 반영의 완료를 뜻하는지 다시 물어야 한다면 아직 맥락이 충분히 연결된 것은 아니다.

현재 적용해야 할 기준과 실제로 반영된 상태는 서로 다를 수 있다. 클린 컨텍스트는 그 차이를 보이게 해야 한다.

문서가 많다고 이 일이 저절로 되지는 않는다. 현재 유효한 결정과 폐기된 결정을 구분할 수 없고, 정책이 바뀌어도 관련 작업에 반영되지 않는다면, 기록이 쌓여 있어도 여전히 사람에게 물어봐야 한다.

그래서 클린 컨텍스트는 문서화 위에 얹는 기준이다. 기록을 남기는 데 더해, 그 기록을 현재 업무에서 쓸 수 있는 상태로 유지하는 것까지가 그 범위다. 결국 중요한 질문은 이것이다. 다음 사람이 결정의 근거와 현재 상태를 확인하고, 변경의 영향을 따라갈 수 있는가.

4. 이자가 큰 부채부터 갚는다

그렇다고 모든 회의와 결정을 빠짐없이 기록하자는 이야기는 아니다.

기록을 작성하고, 관련 작업에 연결하고, 최신 상태로 유지하는 데도 비용이 든다. 아무도 찾지 않는 문서를 만들거나 이미 무효가 된 정보를 유효한 것처럼 남겨 두면, 부채를 갚으려고 만든 기록이 새로운 부채가 된다.

모든 부채를 한꺼번에 갚을 수 없듯, 맥락 부채에도 순서가 필요하다. 이자가 가장 큰 것부터다. 반복해서 묻는 결정, 잘못 이해하면 손해가 큰 조건, 자주 바뀌어 혼선을 만드는 정책이 여기에 해당한다.

시작은 반복되는 질문 하나면 충분하다. 답의 근거와 적용 조건, 책임자를 남기고, 다음 사람이 찾을 수 있도록 관련 작업에 연결한다.

기록을 남겼다면, 누가 언제 갱신할지도 정해야 한다. 정책을 바꾸는 업무 안에 관련 기록과 작업 상태를 갱신하는 절차가 포함돼야 한다. 누군가 나중에 알아서 정리할 일로 남겨 두면, 그 기록은 곧 다시 낡는다.

갱신한 기록이 정확한지, 실제 업무에도 반영됐는지는 검증해야 한다. 적용일이 입력됐는지, 필수 검토가 끝났는지, 변경된 정책과 연결된 작업 중 미완료 항목이 남아 있는지는 정해진 규칙으로 점검할 수 있다. 반면 어떤 위험을 감수할지, 상충하는 목표 중 무엇을 우선할지는 사람이 책임지고 판단해야 한다.

AI를 활용하더라도 이 구분은 달라지지 않는다. AI는 맥락 부채를 줄이는 도구가 될 수도, 키우는 도구가 될 수도 있다. 흩어진 기록을 정리하거나 문서 사이의 충돌을 검토하는 데 도움을 받을 수는 있지만, 요약 자체를 새로운 사실의 근거로 삼아서는 안 된다.

10% 정책의 적용일이 지났는데도 AI가 과거의 15% 할인 결정을 현재 정책처럼 정리한다면, 오래된 정보를 더 빠르게 퍼뜨린 셈이 된다. 검토 결과는 근거 원문과 대조할 수 있어야 하고, 결정의 유효 시점도 확인할 수 있어야 한다. 확인되지 않은 추정은 확정된 결정과 구분해야 한다.

도구가 무엇이든 검증 기준을 정하고 오류를 수정하는 책임은 사람에게 있다. 오류를 발견했다면 잘못된 기록까지 고치고, 영향을 받은 작업에도 반영해야 한다. 그 자리에서 답만 바로잡으면 같은 오류는 다음 사람에게 그대로 돌아간다. 확인한 결과가 다음 사람의 확인 비용까지 줄일 때, 비로소 부채가 줄어든다.

5. 다음 사람의 비용을 줄이는 것도 성과다

클린 컨텍스트의 효과는 문서 수나 AI 사용 횟수로 판단할 수 없다.

같은 질문이 덜 반복되는지, 결정의 근거를 찾는 시간이 줄었는지, 오래된 조건을 믿고 진행해서 생기는 재작업이 줄었는지를 봐야 한다. 예를 들어 특정 정책에 대한 메신저 문의가 한 달에 몇 번 오는지, 새로 합류한 사람이 담당자에게 묻지 않고 그 정책의 근거를 찾기까지 얼마나 걸리는지를 보면 된다. 기록을 작성하고 갱신하고 검증하는 데 드는 비용도 함께 살펴야 한다.

문서를 만들었는데 여전히 같은 설명을 반복해야 한다면, 문서가 있다는 사실만으로 개선됐다고 말하기는 어렵다. 설명이 부족한지, 찾기 어려운지, 이미 오래된 정보인지 살펴 고쳐야 한다. 반대로 거창한 시스템이 없어도 자주 묻던 정책 하나의 근거와 반영 상태를 쉽게 확인할 수 있게 됐다면 의미 있는 개선이다.

모든 개선이 업무 시간을 줄여야 하는 것도 아니다. 확인에 걸리는 시간은 같더라도 중요한 조건을 놓칠 위험이 줄었다면 가치가 있다. 시간을 줄였더라도 기록의 유지 비용이 지나치게 커졌다면 관리 범위와 방식을 다시 조정할 필요가 있다.

이 일을 개인의 선의에만 맡길 수는 없다.

개인에게는 반복되는 문제를 발견하고 개선할 책임이 있다. 조직에는 그 문제를 개선할 시간과 권한을 제공할 책임이 있다. 누가 기록을 갱신하고 누가 변경의 반영 여부를 확인할지 정하지 않은 채 “문서화도 잘하라”고 요구하면, 맥락을 관리하는 일마저 특정인의 보이지 않는 노동이 된다.

리더는 당장의 결과와 함께 다음 사람의 업무 비용을 줄인 성과도 평가해야 한다. 혼선을 능숙하게 수습한 사람의 기여를 인정하면서, 같은 혼선이 다시 생기지 않도록 바꾼 사람의 기여도 함께 인정해야 한다.

클린 코드가 코드를 이해하고 바꾸기 위한 규율이라면, 클린 컨텍스트는 조직의 일을 이해하고 개선하기 위한 규율이어야 한다.

경험을 조직의 자산으로 남긴다는 것은 과거의 판단을 정답으로 박제하는 일이 아니다. 다음 사람이 그 근거를 이해하고, 달라진 조건에서 다시 판단할 수 있게 하는 일이다.

개인의 센스가 필요한 순간은 앞으로도 있을 것이다. 하지만 이미 내려진 결정을 찾아 헤매는 일이 반복된다면, 그것은 개인의 센스가 아니라 조직의 책임으로 해결해야 한다.