테크니컬 가이드라인

9개 랩의 실제 개발 경험을 바탕으로, 테크포임팩트 커뮤니티 현직 개발자들의 검수를 거쳐 완성된 실무 가이드입니다.

HOW - 개발 실무를 위한 구체적 실행 가이드

이제 본격적으로 개발을 시작하시나요? 코드 리뷰나 배포에서 문제가 생겼나요? 이 가이드라인은 선택된 기술과 방향성을 바탕으로 어떻게 구체적으로 구현하고 협업할 것인지에 대한 실무 중심의 실행 가이드입니다. GitHub 관리부터 코드 품질, AI/ML 특화 개발 방식까지 실제 현장에서 검증된 방법들을 담았어요. 기술 선택의 기준이나 전략이 궁금하시다면 테크포임팩트 LAB 기획 및 운영 가이드라인 을, 테크포임팩트의 기본 철학은 테크포임팩트 LAB의 일하는 방식 을 참고해주세요.

0. 프로젝트를 시작하기 전

팀의 개발 문화 만들기

"다 다른 배경을 가진 전문가들이 함께 일하는 것"

우리는 서로 다른 회사, 다른 팀에서 일해온 전문가들입니다. 각자의 개발 방식과 코딩 스타일, 프로젝트 구조에 대한 선호가 다를 수 있어요. 성공적인 협업을 위한 첫 걸음은, 서로에게 따뜻한 호기심으로 접근하며 열린 마음으로 이해하는 것입니다. 또한 개발 리드나 랩장의 방향성을 따르는 리더십 존중이 필요합니다. "일단 해보고 개선하자"라는 실험적 태도도 중요하죠!

🎯 첫 번째 모임에서 꼭 나눠야 할 대화

• 각자의 개발 경험과 선호하는 방식 공유

• 이번 프로젝트에서 시도해보고 싶은 것들

• 소통 방식과 의사결정 프로세스 합의

저장소 전략 단계별 가이드

단계	가이드
시작 단계 (자유 선택)	개발 초기에는 랩이 가장 편한 방식으로 시작하세요 • 개인 GitHub 계정 • 펠로우 조직 GitHub • 테크포임팩트 GitHub
중간 점검 (PI1 종료 시점)	프로젝트 방향성이 보이면 최종 형태를 결정합니다 • 펠로우 역량: 개발팀 유무, 기술 수준 파악 • 지속성 계획: 누가 어떻게 유지보수할 것인지
최종 정리 (프로젝트 종료)	결정된 방향에 따라 적절한 곳으로 코드 정리 • 카카오임팩트 관리 → services-* 레포 • 펠로우 관리 → 펠로우 조직 이관 • 오픈소스 → oss-* 레포 별도 생성

1. 코드 품질

"6개월 후 다른 사람이 봐도 이해할 수 있는 코드"

• 가독성 우선: 영리한 코드보다 명확한 코드

• 일관성 유지: 팀 내에서 동일한 스타일 적용

  • 팀 내의 언어 별 코딩 컨벤션을 미리 두는 것도 필요함.

• 문서화 습관: 코드만으로 설명이 어려운 부분은 주석을 활용하기

• 테스트 가능성: 테스트하기 어려운 구조는 피하기

주석 vs 외부 문서 분리 기준

코드 내 주석 (최소화)

• 복잡한 알고리즘의 핵심 로직만

• 하드코딩된 상수의 이유

• TODO, FIXME 등 임시 해결책

외부 문서 (GitBook/Notion 권장)

• 전체 시스템 흐름 설명

• 컴포넌트별 역할과 관계

• 설계 의도와 제약사항

• 모델 선정 과정 및 실험 결과

프론트엔드 문서화 예시

• README.md: 기본 설치/실행

• GitBook: 컴포넌트 구조 + 데이터 플로우

실제 사례 참고

CaringNote LAB의 Java/Spring 사례

// 도메인별 패키지 분리 + 3-layer architecture
📦 com.springboot.api
├── counselcard/controller/service/repository
├── counselee/controller/service/repository
└── counselsession/controller/service/repository

• DDD 스타일의 명확한 패키지 구조

• 비즈니스 로직과 인프라 계층 분리

• QueryDSL 활용한 타입 안전한 쿼리

DVA LAB의 Python/FastAPI 사례

# 환경 변수와 설정 분리
@bentoml.service(
    resources={"gpu": 1, "memory": "18Gi"},
    workers=SERVICE_WORKERS,
    traffic={"timeout": 600, "max_concurrency": 8}
)

• 타입 힌트와 Pydantic 모델 활용

• 환경별 설정 파일 분리

• 모니터링과 로깅 통합

코드 품질 체크리스트

• 언어별 표준 린터/포매터 설정 (ESLint, Prettier, Black 등)

• Pre-commit Hook 설정 (Husky, lefthook 등)

• 에러 처리 및 로깅 전략 수립

2. 브랜치 전략

"협업이 쉽고, 배포가 안전한 브랜치 플로우"

• 단순함 추구: 복잡한 브랜치 구조보다 명확한 규칙

• 기능 단위: 하나의 브랜치는 하나의 완성된 기능

• 코드 리뷰 필수: 모든 변경사항은 동료의 검토 거치기

• 히스토리 관리: 의미 있는 커밋 메시지와 깔끔한 히스토리

실제 사례 참고

CaringNote LAB의 Git Flow

main (프로덕션) ← staging (검증) ← feature/fix/refactor 브랜치

브랜치 네이밍

• feature/사용자-관리-개선

• fix/로그인-버그-수정

• refactor/API-구조-개선

커밋 메시지 규칙

feat: 신규 기능 추가
fix: 버그 수정
refactor: 기능 개선
chore: 코드 정리

DVA LAB의 모델 개발 플로우

main ← develop ← feature/model-update
                ← feature/pipeline-optimization

• 모델 버전과 코드 버전의 분리 관리

• MLflow 스테이징을 통한 모델 검증 후 배포

누구나리포터 LAB의 노션 연동 플로우

누구나데이터 깃 플로우(Mermaid)

---
title: 누구나데이터 깃 플로우
---
gitGraph
	commit
	commit
	branch develop
	checkout develop
	commit
	commit
	branch "feature/DEV-27_CodeConvention"
	checkout "feature/DEV-27_CodeConvention" 
	commit id: "feat: biome code convention setting"
	commit id: "fix: loop code convetion bug fix"
	checkout develop
	merge "feature/DEV-27_CodeConvention"
	commit
	checkout main
	merge develop

main (프로덕션) ← develop (개발) ← feature/notionID_branchName ← fix/notionID_branchName

특징:

• 노션 작업 데이터베이스와 브랜치를 1:1 매핑

• 작업 추적성과 문서화의 완벽한 연동

• 팀 협업 시 작업 현황 실시간 파악 가능

브랜치 네이밍 예시

feature/a1b2c3d4_user-login-system fix/e5f6g7h8_signup-validation-error

커밋 메시지 규칙

feat: 기능 개발 docs: 문서 작성 fix: 버그 수정 chore: 사소한 작업(설정 변경 등)

브랜치 전략 체크리스트

• 브랜치 네이밍 규칙 팀 내 합의

• PR 템플릿 작성 (문제, 해결방법, 테스트 등)

• 코드 리뷰 가이드라인 수립

• 커밋 메시지 컨벤션 적용

• 브랜치 보호 규칙 설정 (main/staging)

3. 배포 및 릴리즈 프로세스

"실패해도 안전하고, 성공하면 확장 가능한 배포"

• 환경 분리: 개발/스테이징/프로덕션 환경 명확히 구분

• 점진적 배포: 한 번에 모든 것을 바꾸지 않는 단계적 접근

• 자동화 우선: 수동 작업으로 인한 휴먼 에러 최소화

• 롤백 준비: 언제든 이전 버전으로 돌아갈 수 있는 안전장치

실제 사례 참고

CaringNote LAB의 접근법

staging branch → 자동 배포 → 검증 → main branch → 프로덕션 배포

• GitHub Actions를 통한 완전 자동화 파이프라인

• DockerHub 중간 저장소 활용

• Kubernetes 환경에서의 무중단 배포

DVA LAB의 고도화 사례

MLflow → BentoML → Docker 컨테이너화 → 자동 스케일링

• 모델 버전 관리와 서비스 배포의 완전 분리

• 리소스 제한과 헬스체크를 통한 안정성 확보

• Prometheus/Grafana 모니터링 통합

배포 및 릴리즈 프로세스 체크리스트

• 환경별 설정 파일 분리 (.env.example 제공)

• Docker/Docker Compose 활용한 일관된 환경

• CI/CD 파이프라인 구축 (GitHub Actions 권장)

• 헬스체크 엔드포인트 구현

• 배포 실패 시 자동 롤백 전략 수립

---

4. GitHub 리포지토리

"처음 보는 사람도 5분 만에 프로젝트를 이해할 수 있는 구조"

• 직관적 구조: 파일과 폴더 이름만 봐도 역할을 알 수 있게

• 완전한 문서화: README부터 API 문서까지 빠짐없이

• 재현 가능성: 누구나 동일한 환경에서 실행할 수 있도록

• 기여 가능성: 외부 기여자도 쉽게 참여할 수 있는 구조

실제 사례 참고

CaringNote LAB의 프론트엔드 구조

caring-note-web/
├── src/
│   ├── api/          # OpenAPI 자동 생성
│   ├── app/          # Router, Keycloak 설정
│   ├── components/   # UI 컴포넌트
│   ├── pages/        # 도메인별 페이지
│   └── stores/       # Zustand 상태 관리
├── .github/
│   └── workflows/    # CI/CD 스크립트
├── package.json
├── README.md         # 상세한 설치/실행 가이드
└── lefthook.yml      # Git 훅 설정

DVA LAB의 MLOps 구조

dva-mlops/
├── bentoml/
│   ├── models/       # 모델별 서비스
│   ├── scripts/      # 자동화 스크립트
│   └── config/       # 환경 설정
├── pipeline/         # Celery + RabbitMQ
├── storage/          # MinIO 설정
├── docker-compose.yml
└── README.md         # 전체 시스템 가이드

Github Repository 체크리스트

필수 파일들

• README.md (프로젝트 소개, 설치, 실행, 기여 방법)

• LICENSE (MIT 또는 GPL 권장)

• .gitignore (언어/프레임워크별 표준)

• .env.example (환경 변수 템플릿) *보안 관리 가이드 참고

• SECURITY.md (실제 .env 파일 및 보안 민감 파일 관리 방법)

• CONTRIBUTING.md (기여 가이드라인)

AI/ML 프로젝트 추가 고려사항

• 모델 실험 결과 외부 문서 링크 (GitBook/Notion)

DVA LAB 사례

• 베이스 라인 모델 선정 : https://techforimpact-io.gitbook.io/diva/ai-parts/detection/3./3.1

• 고도화 실험 기록 : https://techforimpact-io.gitbook.io/diva/ai-parts/detection/3./3.2

• requirements.txt 버전 고정 (재현성 보장)

GitHub 설정

• Issue 템플릿 (Bug Report, Feature Request)

• PR 템플릿 (변경사항, 테스트, 리뷰 포인트)

• GitHub Actions Workflow

• 브랜치 보호 규칙

문서화

• API 문서 (Swagger/Postman)

• 설계 의도 및 제약사항 기록 (왜 이런 구조/기술을 선택했는지)

테크포임팩트 LAB 프로젝트에서는 종종 GPU 자원이 부족하거나, 서버리스 구조, 실시간 응답이 필요한 경우처럼 일반 서비스와 다른 제약 조건에서 개발을 하게 될 수 있습니다.

따라서 왜 이런 구조나 선택을 했는지에 대한 "설계 의도"를 코드나 문서에 담으면 더 좋습니다.

(예: 비용 문제로 A100 대신 T4 사용, 혹은 클라우드 일정 종료 예정이라 로컬 백업 전략 등)

• 아키텍처 다이어그램

• 배포 가이드

• 유지보수 인계를 위한 트러블슈팅 가이드

프로젝트가 종료된 후에도 기관 내부 인력이나 유지보수 파트너에게 인계되다 보니, 자주 발생하는 오류 대응법, GPU 변경 시 대응법, 백업 전략 등을 정리해두면 좋습니다.

• MLOps 인프라 구조와 리스크 대응 : https://techforimpact-io.gitbook.io/diva/service-parts/mlops/infrastructure

• 아키텍처 설명 :https://techforimpact-io.gitbook.io/diva/service-parts/mlops/architecture-overview#id-1.-architecture-overview

보안 관리 가이드 (SECURITY.md)

민감 정보 관리 전략

• Tech for Impact Google Drive 활용(*필요 시 사무국에 요청) + gdown으로 다운로드

• GitHub Secrets와 CI/CD 연동

• 팀 내 안전한 공유 프로토콜

예시

bash

`*# Google Drive에서 설정 파일 다운로드*
gdown --id [파일ID] --output .env

*# 또는 GitHub Secrets 활용*
echo "${{ secrets.ENV_FILE }}" > .env`

도움이 필요할 때

1단계: 이전 기수의 사례를 참고하세요!

• CaringNote LAB Github https://github.com/MediBird - 풀스택 웹 서비스 참고

• DVA LAB Github https://github.com/DVA-LAB - MLOps, AI 기반 서비스 참고

2단계: 테크포임팩트 커뮤니티를 활용하세요!

• 테크포임팩트 디스코드 채널에서 질문

• 다른 랩/이전 랩의 경험 공유 요청

3단계: 사무국 지원

• 기술적 검토 및 테크포임팩트 패컬티 자문 요청

• 인프라 설정 지원

🙏 Special Thanks

• DIVA LAB 한서우님: AI/ML 프로젝트 특화 가이드, 문서화 및 보안 가이드 기여