개발자에게 글쓰기가 중요한 이유, 코드를 넘어 생각을 정리하는 습관

저는 개발을 시작하면 실력은 코드를 얼마나 많이 작성하느냐로 결정된다고 생각했습니다. 새로운 문법을 익히고, 어려운 문제를 빠르게 해결하고, 동료보다 더 복잡한 기능을 구현하면 좋은 개발자가 될 수 있다고 믿었죠. 그래서 한동안 작업 내용을 따로 기록하지 않았습니다. 머릿속에 모두 정리되어 있다고 착각했고, 설명하는 시간은 코딩을 방해하는 일처럼 느꼈습니다. 하지만 시간이 지나면서 제 생각이 자주 바뀌고, 같은 문제를 반복해서 해결하며, 다른 사람에게 제 의도를 설명하지 못하는 순간이 늘어났습니다. 그때부터 글쓰기는 부가적인 능력이 아니라 개발을 계속하기 위한 기본 도구라는 생각을 하게 됐습니다.

기록하지 않으면 같은 문제를 다시 만난다

첫 직장에서 한 기능의 속도를 개선하는 일을 맡은 적이 있습니다. 며칠 동안 여러 방법을 시도한 끝에 원인을 찾았지만, 당시에는 해결 과정과 수치를 적어두지 않았습니다. 결과만 반영하고 다음 업무로 넘어갔는데, 두 달 뒤 비슷한 현상이 다시 발생했습니다. 저는 처음부터 다시 자료를 찾고 실험을 반복해야 했습니다. 그때 간단하게라도 시도한 방법, 실패한 이유, 최종적으로 선택한 근거를 남겼다면 몇 시간을 아낄 수 있었을 겁니다. 이후에는 작업이 끝난 뒤 짧은 메모를 남겼습니다. 완벽한 문서가 아니어도 다음의 저에게는 꽤 정확한 안내서가 됐습니다.
처음 기록을 시작했을 때의 글은 읽기 어려웠습니다. 날짜와 숫자만 나열했고, 왜 그런 결정을 했는지는 빠져 있었습니다. 저는 나중에 그 메모를 다시 보면서 당시의 판단을 전혀 떠올리지 못했습니다. 결국 기록에는 결과뿐 아니라 맥락이 필요하다는 사실을 배웠습니다. 어떤 조건에서 문제가 생겼는지, 무엇을 의심했는지, 왜 다른 선택지를 버렸는지를 함께 적어야 시간이 지난 뒤에도 의미가 남습니다. 이 방식으로 작성한 문서는 단순한 업무 일지가 아니었습니다. 제 사고 과정을 다시 살펴보는 자료였고, 다음 문제를 만났을 때 출발점을 빠르게 찾도록 도와주는 지도였습니다.

글로 쓰면 애매한 생각이 드러난다

개발 중에는 해결 방법이 머릿속에서 그럴듯하게 보일 때가 많습니다. 저도 예전에는 ‘이 방향이면 될 것 같다’는 감으로 바로 작업을 시작했습니다. 그런데 동료에게 설명하기 위해 글로 정리하려고 하면 빈틈이 눈에 보였습니다. 입력값은 무엇인지, 예상 결과는 어떤 형태인지, 예외 상황은 어디까지 고려했는지 적는 과정에서 제가 실제로는 문제를 정확히 정의하지 못했다는 사실을 발견한 적이 여러 번 있습니다. 글쓰기는 생각을 예쁘게 포장하는 일이 아니라, 막연한 확신을 문장 단위로 검증하는 과정에 가까웠습니다. 문장 하나를 끝까지 완성하지 못한다면, 그 문제에 대한 이해도 아직 충분하지 않을 가능성이 큽니다.
한 번은 기능을 추가하기 전에 동작 과정을 글로 먼저 설명해 본 적이 있습니다. 당시에는 간단한 변경이라고 여겼지만, 단계별로 적어보니 사용자 상태에 따라 결과가 달라지는 경우가 네 가지나 나왔습니다. 저는 그전까지 가장 일반적인 상황 하나만 생각하고 있었습니다. 문서를 작성하지 않았다면 구현을 마친 뒤 예상하지 못한 수정 요청을 받았을 가능성이 높습니다. 글을 쓴 덕분에 시작 전에 질문을 정리할 수 있었고, 필요한 범위도 다시 조정했습니다. 물론 글을 쓴다고 모든 실수를 막을 수는 없습니다. 다만 적어도 제가 무엇을 알고 무엇을 모르는지는 훨씬 선명해졌습니다.

설명하는 능력은 협업의 속도를 바꾼다

개발자는 혼자 화면 앞에 앉아 있는 시간이 길지만, 실제 결과물은 여러 사람의 이해가 맞아야 완성됩니다. 기획자에게 변경 이유를 설명하고, 디자이너에게 가능한 범위를 전달하고, 운영 담당자에게 주의할 점을 알려야 합니다. 저는 예전 회의에서 말을 잘해야 한다는 부담 때문에 준비 없이 참여했다가 핵심을 제대로 전달하지 못한 적이 있습니다. 회의가 끝난 뒤 각자 다른 내용을 이해하고 있었고, 결국 작업을 다시 맞추느라 시간이 더 걸렸습니다. 그 뒤부터는 회의 전에 배경, 현재 문제, 선택지, 제가 원하는 결론을 짧은 글로 정리했습니다. 말로 설명할 때도 중심이 흔들리지 않았고, 상대방이 질문해야 할 지점도 자연스럽게 드러났습니다.
특히 기술적인 내용을 비개발자에게 전달할 때 글쓰기의 차이를 크게 느꼈습니다. 전문 용어를 많이 사용하면 제가 유능해 보일 것이라고 생각했지만, 실제로는 상대방이 판단하기 어려워졌습니다. 한 번은 작업의 위험 요소를 설명하면서 내부 구조와 구현 방식을 길게 늘어놓았고, 정작 일정에 어떤 영향을 주는지는 뒤늦게 말했습니다. 다음에는 ‘무엇이 바뀌고, 사용자에게 어떤 영향이 있으며, 지금 결정하지 않으면 어떤 문제가 생기는가’를 먼저 적었습니다. 그러자 대화가 훨씬 짧고 분명해졌습니다. 글쓰기는 지식을 과시하는 방법이 아니라 상대방이 필요한 정보를 순서대로 이해하도록 돕는 방법이어야 한다는 점을 그때 배웠습니다.

실패한 기록도 다음 선택의 근거가 된다

모든 글이 좋은 결과로 이어진 것은 아닙니다. 초기에는 업무 기록을 너무 자세히 남기려다가 작성 자체에 많은 시간을 썼습니다. 작은 수정에도 긴 문서를 만들었고, 정작 중요한 판단과 사소한 내용이 한데 섞였습니다. 며칠 뒤에는 아무도 그 문서를 다시 읽지 않았습니다. 저는 기록의 양이 많으면 도움이 될 것이라고 생각했지만, 핵심이 보이지 않는 문서는 없는 것과 비슷했습니다. 이후에는 작업의 크기에 따라 기록 수준을 다르게 정했습니다. 간단한 변경은 세 줄로 끝내고, 판단의 영향이 큰 일만 배경과 선택 이유를 자세히 적었습니다. 실패를 통해 좋은 글은 길이가 아니라 다시 읽었을 때 빠르게 이해되는 구조에서 나온다는 것을 알게 됐습니다.
개인적으로 글을 쓰며 가장 많이 달라진 부분은 질문하는 방식입니다. 예전에는 막히면 ‘왜 안 되지?’라는 말만 반복했고, 주변 사람에게도 막연하게 도움을 요청했습니다. 지금은 제가 확인한 조건과 시도한 방법, 예상과 달랐던 결과를 먼저 정리합니다. 그러면 질문이 ‘이 기능이 안 됩니다’에서 ‘이 조건에서는 정상인데 이 입력에서만 결과가 달라지는 이유를 어떻게 확인하면 좋을까요?’로 바뀝니다. 상대방은 훨씬 쉽게 답할 수 있고, 저 역시 답을 듣는 동안 문제의 구조를 더 잘 이해합니다. 글쓰기는 혼자 하는 활동처럼 보이지만, 사실은 다른 사람과 정확하게 협력하기 위한 가장 조용한 준비라고 느낍니다.

작은 기록이 긴 경력을 지탱한다

저는 이제 개발을 시작하기 전에 문제를 한 문장으로 적고, 작업이 끝난 뒤에는 무엇을 배웠는지 짧게 남기려고 합니다. 처음부터 멋진 기술 글을 쓰려는 마음은 내려놓았습니다. 오늘 확인한 사실 하나, 실패한 방법 하나, 다음에 다시 살펴볼 질문 하나만 적어도 충분하다고 생각합니다. 그런 기록이 쌓이면 나중에는 제 판단의 변화가 보이고, 자주 실수하는 지점도 발견됩니다. 무엇보다 다른 사람에게 설명하기 전에 제 자신이 먼저 이해했는지 확인할 수 있습니다. 개발 도구와 업무 방식은 계속 달라지지만, 생각을 정확한 문장으로 바꾸는 능력은 어떤 환경에서도 남는다고 믿습니다.
개발자에게 글쓰기는 작가처럼 표현하는 능력을 요구하지 않습니다. 어려운 문제를 쉬운 말로 풀고, 결정의 이유를 남기고, 실패를 다시 사용할 수 있는 지식으로 바꾸는 습관에 가깝습니다. 저 역시 아직 간결하고 정확하게 쓰는 일이 어렵고, 작성한 문장을 여러 번 고치는 편입니다. 그래도 기록하지 않던 시절보다 지금의 저는 문제를 더 천천히 바라보고, 동료와 더 정확하게 대화하며, 과거의 경험을 다시 활용합니다. 코드를 작성한 뒤 짧은 설명 한 줄을 남기는 것부터 시작해도 좋습니다. 그 한 줄이 언젠가 자신과 동료를 같은 실수에서 구해주는 가장 현실적인 도움으로 돌아올 수 있습니다.