웹 레이아웃 작업 경계 명확히 박기
목차
docs 폴더에 팀 가이드라인을 한 줄 추가했다. 웹 retention이나 레이아웃 개선 작업을 할 때, 인앱웹뷰·앱·API·어드민은 "영구 제외"라는 기준을 명시한 것. 언뜻 간단한 문서화 작업처럼 보이지만, 여기엔 꽤 많은 팀 리더십이 숨어 있다.
혼동이 많았던 작업들
이전까진 웹 관련 작업이 올라올 때마다 "이거 어디까지 담아야 하나?"라는 질문이 반복됐다. 모바일 앱의 웹뷰도 건드릴지, API 응답 포맷도 같이 고려할지, 어드민 화면은 어떻게 할지. 각자 다르게 해석하니까 PR 리뷰에서 "어? 여긴 왜 안 했어?" 같은 이야기가 나왔다. 특히 retention이나 레이아웃처럼 여러 팀이 영향받는 작업에서는 더 심했다.
개별 담당자 입장에선 합리적이었다. 인앱웹뷰도 결국 웹 기술이고, 앱 팀 요청이 들어오면 도와주는 게 맞다. API도 마찬가지. 하지만 "웹 작업"의 정의가 없으니까, 매 작업마다 경계를 다시 그었다. 그러다 보니 토론이 길어졌고, 온보딩할 때도 신입 개발자들이 헷갈렸다.
명시적 경계 그리기
이번엔 단순하게 가기로 했다. 웹 브라우저 환경이 기준이다. 인앱웹뷰도 웹뷰지만, 앱의 일부라고 봤다. API는 서버 영역이고, 어드민은 별도 도구. 이 네 영역은 웹 retention이나 레이아웃 같은 웹 직접 작업에서 제외한다는 걸 문서에 명시했다.
웹 작업 제외 범위:
- 인앱웹뷰 (앱 팀과 협력, 별도 스케줄)
- 앱 자체 레이아웃/UI (앱 팀 소관)
- API 응답/포맷 (서버 팀 소관)
- 어드민 화면 (운영 팀 소관)
단 네 줄이다. 하지만 이 네 줄이 팀 전체의 의사결정 속도를 바꾼다.
왜 이렇게 했나
문서화는 단순한 기록이 아니다. 그건 의사결정을 가속화하는 도구다.
첫째, 스코프 논쟁을 줄인다. 다음 번에 웹 작업이 올라올 때, "이건 어디까지?"라는 질문 대신 "가이드라인 봤어? 이 영역은 제외야"라고 바로 답할 수 있다. 특히 여럿이 관여한 작업에서 이 명시성이 엄청 중요하다.
둘째, 온보딩이 빨라진다. 새로 팀에 들어온 개발자가 첫 웹 작업을 할 때, 문서를 보고 "아, 여기까진 우리가 담당하고 여긴 다른 팀이네"라고 바로 이해할 수 있다.
셋째, 향후 리사이클링을 막는다. 6개월 뒤 누군가 "어, 인앱웹뷰도 좀 건드려야 하지 않나?"라고 제안할 수 있다. 그때 문서를 다시 읽고 조정하면 되는 것이지, 매번 같은 논쟁을 반복하지 않는다.
문서화 작업의 비용과 효과
이런 작업을 할 때 실수하기 쉬운 부분이 있다. 너무 상세하게 쓰다 보면 문서가 비대해지고, 유지보수 부담이 늘어난다. 또 너무 추상적으로 쓰면 실무자가 해석을 다르게 한다.
이번엔 "영구 제외"라는 표현을 썼는데, 여기가 핵심이다. "지금은 제외"라고 하면 언제든 다시 논의될 수 있다는 뉘앙스가 생긴다. "영구"라고 명시하면, 향후 변경을 원할 때 명확한 의도 하에 다시 정의할 수 있다. 이게 문서화의 묘미다.
또 하나, 변경 파일이 docs/hedvion-CLAUDE.md라는 점도 의미가 있다. 회사/팀 내부 정책과 기술 가이드라인이 모인 공간. 이 파일을 읽으면 "우리 팀은 이 문제를 어떻게 정의했나"를 바로 알 수 있다.
앞으로
이 기준이 영원히 유지될 필요는 없다. 팀의 구조가 바뀌고, 기술이 발전하고, 사업 방향이 틀어질 수 있다. 그때마다 다시 논의하고 문서를 업데이트하면 된다. 중요한 건, 지금 이 순간의 정의를 명확하게 남기는 것이다. 그것이 다음 6개월, 1년 동안 팀이 같은 방향으로 움직이게 하는 가장 싼 방법이다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.