README 개편으로 신규 기능을 팀 전체가 제대로 쓰게 만든 법

README 0.9.0 버전 업데이트를 하며 느낀 게 많아서 기록해본다.

문서는 제품이다

README를 다시 쓸 때마다 드는 생각인데, 문서는 코드만큼 중요한 산출물이라는 거다. 특히 오픈소스나 내부 도구를 외부 팀에 노출할 때는 더 그렇다. 0.9.0 버전에서 Codex scan, admin accounts, Anthropic proxy 세 가지 주요 기능이 추가/변경되었는데, 이걸 README에 어떻게 설명할지가 생각보다 복잡했다.

단순히 "기능이 추가됐으니 써라" 식으로는 절대 안 된다. 누가 이 기능을 필요로 하는지, 어떤 문제를 푸는 건지, 어떻게 쓰는 건지를 명확히 해야 한다. 특히 admin accounts 같은 민감한 기능은 권한 체계와 위험성까지 함께 설명해야 팀원들이 오용하지 않는다.

기능별 설명 전략

Codex scan은 아마 핵심 기능일 테다. 기존 버전에서는 기본 스캔만 지원했다면, 이제는 더 깊은 분석이 가능해진 거 같다. README에는 "언제 써야 하는가"를 중심으로 작성했다. 예를 들어 정규 모니터링, 일회성 감사, 또는 보안 이슈 재점검 같은 구체적인 유스케이스를 먼저 제시하고, 그 다음에 설정 방법을 넣는 식.

Admin accounts는 권력 있는 기능이다. 이건 반드시 "주의" 섹션을 명확히 했다. 누가 admin이 될 수 있는지, 어떤 작업이 admin 권한이 필요한지, 감시 로깅을 어떻게 하는지. 우리 팀은 보통 문서에서 이런 걸 생략하는 경향이 있는데, 나중에 권한 정책 위반으로 문제가 되는 경우가 많더라.

Anthropic proxy는 기술 통합 부분이다. API 키 관리, 요청 포맷, 응답 핸들링, 레이트 리미팅 같은 기술 세부사항을 명확히 해야 다른 팀에서 쉽게 접근할 수 있다.

버전 변경의 문서화

0.9.0은 minor 버전 업이지만 breaking change가 있을 수도 있다. README를 쓰면서 "이전 버전과 호환되는가"를 항상 고민했다. 마이그레이션 노트가 필요한 부분이 있는지, 설정 파일 포맷이 바뀌었는지 체크해야 한다. 팀원들이 버전을 올렸을 때 "어? 왜 안 되지?" 하는 상황을 최대한 줄여야 한다.

코드리뷰와 문서 리뷰의 차이

코드 리뷰는 기술 정확성과 성능을 본다면, 문서 리뷰는 "이 설명이 진짜 누군가의 문제를 풀까?"를 본다. 문서가 너무 기술적이면 초급자는 겁먹고, 너무 단순하면 고급 사용자가 답답해한다. 0.9.0 README는 팀의 다양한 경험 수준을 고려해서 계층화된 설명 구조를 만들려고 했다. 빠른 시작 섹션, 일반적인 설정, 고급 옵션 이런 식으로.

번거롭지만 중요한 작업

솔직히 README 다시 쓰기는 "실제 기능 개발"보다 우선순위가 밀려들 수 있다. 버그 fix, 성능 개선이 더 급하니까. 하지만 문서가 없거나 낡으면 기능이 있어도 안 쓰는 것처럼 취급된다. 우리 팀에서도 작년에 내부 대시보드 기능을 3개월이나 남몰래 쓴 팀원이 있었는데, 이유가 README에 명확한 설명이 없어서였다.

0.9.0 릴리스는 기능만 정렬한 게 아니라, 그걸 팀 전체가 제대로 이해하고 활용하게 하는 다리를 놨다는 의미다. 다음 버전도 기능이 추가될 테니, 문서 유지 주기를 더 짧게 잡아야겠다.

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.