팀 위키의 문제 해결 기록을 정리하다가 같은 원인이 다섯 번 따로 적혀 있는 것을 봤다. 시기도 프로젝트도 달랐고 매번 처음 만난 것처럼 조사해서 같은 결론에 도달한 뒤 그 자리만 고쳤다.
Table of contents
Open Table of contents
상황 — 다섯 번의 같은 조치
Windows 에서 .ps1 배포 스크립트를 실행하는데 특정 프로젝트에서만 실패하는 문제였다. 원인은 매번 같아서 파일에 BOM 이 없어 Windows PowerShell 이 시스템 기본 코드 페이지로 읽었고 한글 주석이 깨지면서 구문까지 무너진 것이었다. PowerShell 공식 문서도 BOM 없는 UTF-8 스크립트를 Windows PowerShell 이 다른 인코딩으로 오독한다고 적고 있다.
다섯 번의 기록을 나란히 놓으니 증상 서술은 조금씩 다른데 조치가 전부 BOM 추가로 같았다. 그런데 다섯 번을 각각 몇 시간씩 조사했다.
원인 — 기록에 도달하지 못한 이유
기록은 남기고 있었지만 다음에 같은 것을 만났을 때 그 기록에 닿지 못했다. 이유가 셋이었다.
증상으로 검색하는데 기록에는 원인이 적혀 있어서 검색어가 안 맞았다. 프로젝트별로 기록이 흩어져 있어 다른 프로젝트에서 겪은 것은 안 보였고, 개별 조치만 적혀 있어서 다른 파일에서 만났을 때 연결이 되지 않았다.
주의 — 반복될수록 얕아진 조사
기록들 사이에 흥미로운 차이가 있었다. 세 번째 기록에는 같은 스크립트에서 Write-Host 출력이 파이프로 넘기는 결과를 오염시키는 다른 문제가 함께 적혀 있었다.
네 번째와 다섯 번째에는 그것이 없고 BOM 만 고치고 넘어갔다. 같은 증상을 반복해서 만나면 아는 것만 고치게 되고 그 자리에 있는 다른 문제는 안 보이므로 처음 만났을 때가 오히려 깊게 판다.
조치 — 바꾼 넷
두 가지 방법이 있었는데 다섯 번째 기록을 더 잘 써서 다음에 찾기 쉽게 하는 것과 발견하고 고치는 일 자체가 없어지게 규약과 검사를 두는 것이다. 뒤쪽을 골랐다. 이유는 앞의 네 기록도 각자는 충분히 잘 써 있었는데 닿지 못했기 때문이다. 대신 .editorconfig 와 검사 스크립트를 프로젝트마다 넣는 초기 비용을 감수했다. 그래서 넷을 바꿨다. .editorconfig 에 *.ps1 은 charset = utf-8-bom 으로 규약을 넣어 처음부터 그렇게 만들게 했다.
BOM 없는 .ps1 을 찾는 검사를 Jenkins 에서 자동으로 돌려 사람이 기억할 필요를 없앴다. 위키에는 그 증상으로 검색했을 때 나올 syntax error 같은 단어를 함께 적었고 같은 것을 몇 번 만났는지를 셌다. 반복 횟수가 곧 근본 대책의 우선순위이고 다섯 번 만난 것은 대책을 세울 만하다는 뜻이다.
다른 반복들
이것을 알고 기록을 다시 훑으니 반복이 더 있었다. NFC 와 NFD 정규화 차이로 비교가 전부 실패한 것이 네 번이었고 반환값을 안 보고 넘어가 실패가 조용히 삼켜진 것이 여러 번이었다.
상태값으로 사고 범위를 정해 무관한 과거 데이터까지 포함한 것이 세 번이고 인덱스 없는 컬럼으로 큰 테이블을 조회해 시간이 초과된 것이 다섯 번 이상이었다. 마지막 것은 AUTO_INCREMENT 키를 시간 대신 쓴다는 같은 결론이었는데 매번 다시 발견하고 있었다.
정리
- 같은 원인을 여러 번 만나면 조치가 아니라 규약이 필요하다
- 기록은 증상으로 찾게 되므로 원인만 적으면 도달하지 못한다
- 반복해서 만나면 조사가 얕아진다
- 아는 것만 고치고 그 자리의 다른 문제는 안 보인다
- 사람이 기억하는 대신 BOM 검사를 자동으로 돌린다
- 반복 횟수를 세면 그것이 근본 대책의 우선순위가 된다
- 프로젝트별로 흩어진 기록은 서로 안 보인다
- 개별 조치만 적으면 다음 사례와 연결되지 않는다