팀 문화 구축 — Git·문서·품질 체계

배경

5명 이하 소규모 팀에서 개발 프로세스와 협업 표준이 부재했다. 코드 스타일이 개인마다 달라 리뷰 시 논쟁이 길어졌고, Git 사용법이 제각각이라 머지 충돌이 잦았으며, 시스템 아키텍처 문서가 없어 지식이 특정 개발자에게 편중되었다. 신규 팀원이 합류해도 시스템을 이해하기까지 시간이 오래 걸렸다.

시스템 구조

• Git·협업: Git Flow 전략과 PR 기반 리뷰 문화, Jira 이슈 트래킹 체계 도입.
• 문서화: 선별 시스템 백엔드 docs/{architecture, api, components, database} 세트 + DRF Swagger/OpenAPI 자동 문서화.
• 코드 품질: 백엔드 Pre-commit(Black·isort·Ruff), 프론트엔드 ESLint + Storybook + MSW 컴포넌트 개발 환경.

해결 과정

Git 워크플로우 정립. Git Flow 전략을 수립하고 팀원 교육을 진행했다. PR 기반 코드 리뷰 문화를 도입했을 때 처음에는 저항이 있었지만, 실제 리뷰에서 발견된 버그 사례를 팀에 공유하면서 인식이 바뀌었다. Jira로 이슈·릴리스를 추적하는 체계도 같이 정비했다.

아키텍처 문서 세트. 시스템 개요·Docker 서비스·서버 구조·컴포넌트·데이터베이스·API·PLC 통신 등 주제별 문서를 docs/architecture·docs/components·docs/database·docs/api로 나눠 작성했다. DRF Swagger/OpenAPI로 API 문서를 자동 생성하게 해서 별도 관리 없이 명세를 최신 상태로 유지할 수 있게 했다.

코드 품질 체계. 백엔드 Pre-commit 훅에 Black(포매팅)·isort(임포트 정렬)·Ruff(린팅)를 걸어 커밋 시점에 스타일이 자동 통일되게 했다. 프론트엔드는 ESLint(TypeScript + React Hooks) + Storybook + MSW로 컴포넌트 단위 개발·테스트 환경을 갖췄다.

성과

• Pre-commit + PR 리뷰로 팀 전체 코드 스타일 일관성 확보.
• 선별 시스템 백엔드 docs/{architecture, api, components, database} 문서 세트 + Swagger 자동 문서화로 지식 편중 해소.
• Storybook + MSW 기반 프론트엔드 컴포넌트 개발 환경으로 UI 개발·검증 주기 단축.
• Jira 이슈·릴리스 체계로 신규 인력 온보딩 시간 단축, 협업 프로세스 정착.