내 README에는 80개의 도구가 있다고 적혀 있었다. 내 코드에는 96개가 있었다. 몇 주 동안 아무도 눈치채지 못했다.
저는 오픈 소스 프로젝트를 운영하고 있습니다. 이 프로젝트는 AI 에이전트를 위한 브라우저 자동화 기술을 사용합니다.
제 README에는 프로젝트에 80개의 도구가 있다고 적혀 있었습니다. 저는 그 숫자를 태그라인, 네비게이션, 그리고 소셜 미디어 텍스트에 모두 기재했습니다.
지난주에 감사를 진행했습니다. 제 README와 실제 코드를 비교해 보았습니다.
코드는 96개의 도구를 등록하고 있었습니다.
한 파일 안에 세 가지 서로 다른 진실이 공존하고 있었습니다:
- 마케팅용 숫자: 80
- 문서화된 목록: 83
- 실제 코드: 96
13개의 도구는 전혀 문서화되어 있지 않았습니다. 사용자들은 그 도구들이 존재하는지조차 몰랐습니다.
가장 위험한 부분은 바로 그 격차였습니다. 문서화되지 않은 도구 중 4개는 고수준 시스템 도구였습니다. 이 도구들은 OS 레벨의 이벤트를 사용하여 키보드와 마우스를 제어했습니다. 이는 제 프로젝트에서 가장 강력하면서도 민감한 부분입니다.
이를 통해 문서화 드리프트(documentation drift)에 대한 뼈아픈 교훈을 얻었습니다.
드리프트는 무작위로 발생하지 않습니다. 편향되어 있습니다. 쉽고 지루한 것들은 문서화하지만, 급하게 출시하느라 새로 추가된 강력하거나 민감한 도구들은 문서화하는 것을 잊어버리곤 합니다.
프로젝트에서 가장 위험한 부분을 찾고 싶다면 문서를 읽지 마십시오. 문서와 코드 사이의 격차를 살펴보십시오.
저는 숫자를 수정하려고 했습니다. 그것은 실수였습니다. 숫자를 고치는 것은 증상만을 완화할 뿐입니다.
문제는 수동 유지보수입니다. 사람이 직접 사실을 입력하면, 그 사실은 결국 틀리게 됩니다.
유일하고 진정한 해결책은 숫자가 틀리는 것 자체를 불가능하게 만드는 것입니다.
반드시 신뢰할 수 있는 단일 원천(source of truth)으로부터 사실을 도출해야 합니다.
제 프로젝트에는 이미 한 가지 해결책이 있었습니다. 바로 스모크 테스트(smoke test)입니다. 이 테스트는 서버에 도구가 몇 개 있는지 물어보고 그 개수를 확인합니다. 하드코딩된 숫자를 사용하지 않습니다. 테스트는 정적인 숫자를 저장하지 않기 때문에 결코 드리프트가 발생할 수 없습니다.
글쓰기에 더 절제력을 갖추려고 노력하는 것을 멈추십시오. 절제력은 실패하기 마련입니다. 대신, 사실 관계를 자동화하십시오:
- 빌드 시점에 스크립트를 사용하여 개수를 생성하십시오.
- 코드 레지스트리에서 직접 도구 목록을 생성하십시오.
- 사람은 서술과 설명에만 활용하십시오.
도출 가능한 사실이라면 직접 타이핑하지 마십시오. 그것은 곧 발생할 드리프트일 뿐입니다.
오늘 여러분의 프로젝트에서도 이 감사를 실행해 보십시오:
- 코드에 있는 실제 항목의 개수를 세십시오.
- 문서가 주장하는 개수를 세십시오.
- 두 숫자가 다르다면, 그 격차 사이에 무엇이 있는지 찾아내십시오.
격차 사이에 있는 항목들이 대개 여러분 프로젝트에서 가장 중요한 부분입니다.
선택 사항 학습 커뮤니티: https://t.me/GyaanSetuAi