이 글은 이런 분께
- “이미 한 번 고친 실수니까 다신 안 하겠지” 생각해본 분
- 문서화·기록이 재발 방지의 전부라고 믿는 분
Before — 몇 시간 전에 분명히 정리했는데
오늘 오전, Vercel 빌드 에러를 잡은 이야기를 사례글로 정리하면서 이렇게 적었다.
“summary: 같은 값에 큰따옴표를 쓰고 싶으면, 값 전체를 작은따옴표로 한 번 더 감싸야 한다.”
체크리스트에도 적었고, 재사용 자산으로 정리까지 했다. 그런데 몇 시간 뒤, 물결표 취소선 버그를 고친 이야기를 쓰면서 summary를 이렇게 썼다.
summary: "5~7개"라고 썼는데 화면엔 취소선이 그어졌다. ...
똑같은 패턴이었다. 큰따옴표로 시작하는데 전체를 안 감쌌다.
어떻게 — 로컬 빌드가 다시 잡아냈다
이번에도 커밋 전에 npm run build를 돌렸고, 똑같은 에러 메시지가 똑같은 형태로 떴다.
can not read a block mapping entry; a multiline key may not be an implicit key
Location: src/content/wiki/w3-case-tilde-strikethrough-bug.md:4:2
고치는 법도 이미 알고 있었으니 바로 고쳤다.
summary: '"5~7개"라고 썼는데 화면엔 취소선이 그어졌다. ...'
다시 빌드하니 정상적으로 끝났다.
After — 문서화만으론 재발을 못 막는다
| 알고 있었던 것 | 실제로 일어난 것 |
|---|---|
| ”summary가 큰따옴표로 시작하면 전체를 감싸야 한다”는 걸 사례글로 정리해뒀다 | 몇 시간 뒤 새 글을 쓰면서 똑같은 패턴으로 또 틀렸다 |
| 규칙을 안다 | 실제로 타이핑할 때는 그 규칙이 자동으로 안 떠오른다 |
이번엔 문제가 안 됐다. 왜냐하면 규칙을 외웠기 때문이 아니라, 커밋 전에 로컬 빌드를 항상 돌리는 습관(작업 규칙에 이미 박아둔 절차)이 대신 잡아줬기 때문이다.
배운 것 / 재사용 자산
기록(사례글·체크리스트)과 습관(항상 확인하는 절차)은 다른 층위다. 기록은 “이런 문제가 있었다”는 걸 나중에 다시 찾아볼 수 있게 해주지만, 타이핑하는 순간 그 규칙을 자동으로 떠올리게 해주진 않는다. 실수를 막아주는 건 결국 “매번 확인하는 절차” 쪽이다.
그래서: 반복되기 쉬운 실수는 “기억하려고 애쓰기”보다 “확인하는 절차를 만들기”로 대응하는 게 낫다. 이번 경우엔 이미 있던 “커밋 전 로컬 빌드” 습관이 그 절차 역할을 해줬다 — 규칙을 안 외워도 실수가 배포까지 새어나가지 않았다.