작업 목록에는 완료라고 쓰여 있는데, 코드 검토에서는 무엇이 끝났는지 다시 묻게 된다. 요청은 대화에 있고 수정은 저장소에 있으며, 확인 결과는 누군가의 기억에 남아 있는 상황이다. 작업을 Markdown 파일로 옮기는 선택은 이 거리를 줄일 수 있다. 다만 파일의 위치만 바꿔서는 완료의 의미까지 가까워지지 않는다.
Sebastian Schürmanns의 Tasks as Code는 2026년 10월 25일 공개된 글이다. 코드 가까이에서 작업을 계획하고 검토하는 방식을 제안한다. 여기서는 특정 제품으로 전체 업무를 옮기는 대신, 작은 변경 하나의 명세를 어떻게 남길지 생각해보려 한다.
요청을 관찰 가능한 장면으로 바꾸기
가상의 작업은 CSV 내보내기에서 제목 열이 빠지는 문제를 고치는 일이다. 처음 요청에는 내보내기를 제대로 해달라고만 적혀 있다고 하자. 이 문장으로 구현을 시작하면 열 순서를 바꾸거나 화면 필터를 추가하는 일까지 함께 들어올 수 있다. 제대로라는 말에 각자가 다른 결과를 넣기 때문이다.
작업 카드의 첫 문장을 조금 좁혀볼 수 있다. 현재 화면에 표시되는 세 항목을 같은 순서로 CSV에 내보내고, 첫 행에는 각 열의 제목을 넣는다. 이 정도라면 검토자는 출력 파일을 보고 요청과 비교할 수 있다. 어떤 라이브러리를 쓰라는 지시보다 먼저, 사람이 확인할 장면이 생긴다.
다음 문장에는 이번에 다루지 않는 것을 적는다. 파일 형식 추가, 검색 기능 변경, 대량 내보내기 성능 개선은 별도라고 남기는 식이다. 이는 일을 작게 보이게 만드는 문구가 아니다. 작업 도중 좋은 아이디어가 생겼을 때 지금의 완료 조건과 새 제안을 구분하기 위한 경계다.
명세에는 아직 모르는 조건도 들어갈 수 있다. 제목에 쉼표가 들어갈 때의 처리 방식이 정해지지 않았다면 미정이라고 쓴다. 구현자가 편한 방식으로 골라놓고 원래 요구였던 것처럼 설명하지 않는다. 결정이 필요한 질문은 계획과 나란히 두어야 코드를 읽는 사람도 멈춰야 할 곳을 알 수 있다.
검사 이름보다 남겨진 결과
완료 항목에 테스트 통과라고만 적으면 어떤 행동을 보았는지 알기 어렵다. 가상의 카드에는 빈 목록, 한 항목, 제목에 쉼표가 있는 항목을 구분해 적을 수 있다. 실제로 실행한 뒤에는 입력과 기대한 결과, 관찰한 결과를 붙인다. 실행하지 않았다면 준비한 검사라고 표시한다.
예를 들어 한 항목을 내보냈다는 사실과 제목 행까지 맞았다는 사실은 다르다. 파일이 만들어졌는지만 확인했다면 그 범위까지만 완료 증거가 된다. 검사의 수를 늘리기 전에 검토자가 같은 결과를 다시 확인할 수 있는지 물어보는 편이 낫다. 이 글의 CSV 장면은 설명용이며 실제 서비스에서 수행한 검사는 아니다.
검토가 끝난 시점의 코드 식별자와 확인한 파일을 연결해두면 이후 변경과도 구분할 수 있다. 오래된 검사 결과를 최신 코드의 증거로 읽는 일을 줄이기 위해서다. 기록은 길 필요가 없다. 무엇에 대해 어떤 결과를 보았는지가 빠지지 않으면 된다.
구현 중에 발견한 별도 문제는 같은 카드의 범위를 조용히 넓히기보다 연결된 후속 항목으로 남길 수 있다. 그렇다고 모든 작은 메모마다 파일을 만들 필요는 없다. 다시 검토할 이유가 있는 결정과 잠깐의 작업 메모를 같은 무게로 취급하면 명세 자체가 읽기 어려워진다.
코드와 가까운 기록에도 접근 경계가 필요하다
작업을 저장소로 옮기기 전에 누가 그 저장소를 읽는지 보아야 한다. 고객 정보나 내부 사고 기록이 포함된 요청을 공개 코드 옆에 그대로 붙일 수는 없다. 공개 가능한 요구만 요약하고 제한된 원문은 기존 접근 경계 안에 두는 선택이 필요할 수 있다.
계획과 실제 결과도 구분해서 남긴다. 계획에는 무엇을 할지, 결과에는 무엇을 했는지 적는다. 처음 예상한 방법이 바뀌었다면 이유를 짧게 붙인다. 처음 계획을 지워 최종 구현과 똑같이 만들면, 나중에는 어떤 판단이 바뀌었는지 보기 어렵다.
한 사람이 혼자 만드는 작은 도구라면 이 방식의 비용이 이익보다 클 수도 있다. 이미 짧은 이슈와 검토 기록으로 요청을 따라갈 수 있다면 새 형식을 더할 이유가 적다. 반대로 같은 질문을 반복해서 설명하고 있다면 그 질문 하나부터 코드 가까이에 남겨볼 만하다. 전체 관리 도구를 교체하는 결정은 그다음 일이다.
맞았는지 알아볼 방법을 먼저 정하는 일과도 이어진다. 여기서 추가하는 것은 거창한 설계 문서가 아니라, 그 방법을 현재 변경에 묶어두는 짧은 기록이다. 파일의 수가 늘었다는 사실은 작업이 명확해졌다는 증거가 아니다.
다음 변경을 시작한다면 카드 끝에 한 문장을 남겨볼 수 있다. 누가 어떤 출력을 보았을 때 이 일을 끝났다고 말할 수 있는가. 그 문장을 구현 전에 읽고, 구현 뒤에는 실제 결과로 채운다. Markdown의 장점은 그 두 시점을 같은 자리에서 비교할 수 있을 때 드러난다.
공개 원문을 참고해 AI의 도움으로 구성·작성한 글입니다. 가상 예시는 실제 수행 결과와 구분했으며, 표지는 Google Gemini로 만든 개념 일러스트입니다.
