프로젝트 맞춤 지침으로 상속 문서의 혼선 정리

이번엔 blindboxdex 프로젝트의 CLAUDE.md를 새로 작성했다. 그 전까지는 다른 프로젝트(vtuber 관련)의 지침 문서를 그대로 상속받고 있었는데, 프로젝트마다 도메인과 제약이 다르다 보니 팀원들이 "이 규칙이 우리 프로젝트에도 적용되는 거야?"라고 매번 판단해야 하는 불편함이 생겼다. 이번 작업으로 그 혼선을 명확하게 정리했다.

상속받은 문서의 함정

처음엔 상속 구조가 효율적이라 생각했다. 비슷한 프로젝트 구조니까 기존 지침을 그대로 가져다 쓸 수 있을 거라고. 하지만 시간이 지나면서 문제가 드러났다.

vtuber 관련 프로젝트와 blindboxdex는 도메인이 다르다. vtuber 프로젝트는 콘텐츠 진위 검증이나 이미지 정책처럼 특정 영역의 강한 제약이 CLAUDE.md에 깊게 박혀있었다. blindboxdex는 다른 흐름이다. 팀원이 코드를 보거나 PR을 리뷰할 때, "문서에는 이렇게 나와 있는데, 우리 프로젝트 현실은 다른 것 같은데?"라는 갈등이 생긴다. 누군가는 "지침에 있으니까" 하고 따르고, 누군가는 무시한다. 여러 버전의 "진실"이 떠다니는 것이다.

문서를 바꾸는 일의 무게

겉으로는 마크다운 파일 하나를 교체하는 작업이지만, 실제로는 "이 프로젝트의 단일진실은 여기서부터 시작한다"는 신호를 보내는 것이다. 팀원들이 blindboxdex에서 작업할 때 참고해야 할 지침, 제약, 관례가 명확하게 정의된다는 뜻이다.

우리 팀 지침에는 "적힌 것을 맹신하지 말고, 실측이 단일진실"이라는 문구가 있다. 그런데 그 말이 제대로 작동하려면, 문서가 충분히 정확하고 최신이어야 한다는 역설이 있다. 상속받은 문서가 stale 상태로 남으면, 팀원들은 자신의 경험이나 예전 지침을 신뢰하게 되고, 결국 혼란만 커진다.

회고: 작은 것들의 기술부채

side 프로젝트라는 이유로 문서화를 미루는 건 위험했다. 팀 규모가 작을수록, 또는 프로젝트가 새로울수록, 오히려 명확한 지침이 더 필요하다. 왜냐하면 팀원이 합류할 때 구두 설명에만 의존하면 안 되기 때문이다. 또 내가 다른 프로젝트에서 돌아와 blindboxdex를 다시 열 때도, "아, 여기는 이런 규칙이 있었지"를 빠르게 상기할 수 있어야 한다.

배운 점들:

• 상속받은 것도 정기적으로 감시해야 한다. inherited 구조는 처음엔 편하지만, 프로젝트가 진화하면서 문서와 현실이 벌어진다.
• "이건 우리 프로젝트 아니니까"는 더 빨리 결정해야 한다. 상속을 유지하는 비용이 교체하는 비용보다 크면, 망설이지 말고 새로 작성한다.
• 문서도 코드처럼 ownership이 필요하다. vtuber CLAUDE.md는 vtuber 팀이 관리하고, blindboxdex CLAUDE.md는 우리가 관리한다. 그래야 stale 문서가 발생하지 않는다.

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

• 사무의자 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

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