# CTO로서의 역할에 대한 고찰 - v6: 코드 품질 및 기술 부채 관리

> 작성일: 2025-12-10
> 대상: 내부 팀원
> 시리즈: CTO 업무 정립 과정 6/10

## v5에서의 깨달음

보안은 시스템을 지키는 방패다. 하지만 방패만으로는 부족하다. 시스템 자체가 건강해야 한다. 그것이 **코드 품질**이다.

나쁜 코드는 느린 죽음이다. 처음엔 잘 돌아간다. 하지만 시간이 지날수록 버그가 늘고, 수정이 어려워지고, 결국 아무도 손대지 못하는 레거시가 된다.

## 코드 품질이란 무엇인가?

"좋은 코드"는 추상적이다. 측정할 수 없으면 개선할 수 없다.

### 좋은 코드의 조건
1. **읽기 쉽다**: 다른 사람이 이해할 수 있다
2. **수정하기 쉽다**: 변경의 영향 범위가 명확하다
3. **테스트 가능하다**: 검증할 수 있다
4. **일관성 있다**: 스타일이 통일되어 있다
5. **문서화되어 있다**: 의도가 명확하다

### 나쁜 코드의 징후
- 하나의 함수가 100줄 넘는다
- 변수명이 `a`, `tmp`, `data` 같은 것
- 중복 코드가 여기저기 있다
- 주석이 "왜"가 아니라 "무엇"을 설명한다
- 수정할 때마다 다른 곳이 깨진다

## 현재 우리의 코드 품질

솔직히 평가해보자:

### 잘하고 있는 것
- TypeScript 사용 (타입 안정성)
- ESLint 설정 (기본 규칙)
- Prettier 사용 (포매팅 자동화)

### 부족한 것
- 테스트 커버리지 10% 미만
- 코드 리뷰가 형식적
- 복잡도 관리 안 됨
- 중복 코드 많음
- 문서화 거의 없음

## 측정 가능한 지표

개선하려면 먼저 측정해야 한다.

### 1. 테스트 커버리지
```
현재: 10%
3개월 목표: 40%
6개월 목표: 70%
```

모든 코드를 테스트할 필요는 없다. 핵심 로직부터.

### 2. 코드 복잡도 (Cyclomatic Complexity)
- 목표: 함수당 10 이하
- 경고: 15 이상
- 금지: 20 이상

복잡도가 높으면 버그 가능성도 높다.

### 3. 중복 코드
- 목표: 5% 이하
- 현재: 측정 필요

같은 코드가 3곳 이상 있으면 함수로 만든다.

### 4. PR 크기
- 이상적: 200줄 이하
- 최대: 500줄
- 500줄 넘으면 분할

큰 PR은 리뷰가 형식적이 된다.

## 정적 분석 도구

사람이 다 보기 어렵다. 도구의 도움을 받자.

### 이미 사용 중
```json
{
  "eslint": "코드 스타일 및 잠재적 버그",
  "prettier": "포매팅",
  "typescript": "타입 체크"
}
```

### 추가 도입
```json
{
  "sonarqube": "코드 품질 종합 분석",
  "jest coverage": "테스트 커버리지",
  "eslint-plugin-complexity": "복잡도 체크",
  "jscpd": "중복 코드 감지"
}
```

### 통합 방법
```yaml
# GitHub Actions
name: Code Quality Check

on: [pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install
        run: npm install
      - name: Lint
        run: npm run lint
      - name: Test
        run: npm run test:coverage
      - name: SonarQube
        run: npm run sonar
```

PR 올리면 자동으로 체크. 기준 미달이면 머지 불가.

## 기술 부채 관리

기술 부채는 숨기는 게 아니라 관리하는 것이다.

### 기술 부채의 종류

**1. 의도적 부채** (나중에 고칠 거 알고 빠르게 구현)
- 예: MVP를 위한 임시 구현
- 관리: 이슈로 등록, 일정 계획

**2. 비의도적 부채** (몰라서 잘못 짠 것)
- 예: 초기 설계 실수
- 관리: 발견 즉시 이슈 등록

**3. 환경 부채** (외부 변화로 인한 것)
- 예: 라이브러리 deprecated
- 관리: 정기 점검으로 조기 발견

### 부채 등급 분류

**P0 (긴급)**: 보안 취약점, 서비스 장애 가능성
- 대응: 즉시 수정 (이번 스프린트)

**P1 (높음)**: 버그 유발, 확장성 문제
- 대응: 다음 스프린트

**P2 (중간)**: 유지보수성 저하
- 대응: 분기 내

**P3 (낮음)**: 개선하면 좋은 것
- 대응: 여유 있을 때

### 부채 추적

GitHub Issues로 관리:
```markdown
## [TECH-DEBT] Laravel 레거시 코드 마이그레이션

### 분류
- 등급: P1
- 타입: 의도적 부채
- 영향 범위: 인증 모듈

### 문제
- PHP Laravel 코드 유지보수 어려움
- 팀원 중 PHP 아는 사람 적음
- 보안 패치 업데이트 느림

### 제안 해결책
FastAPI로 재작성

### 예상 공수
2주 (1인)

### 우선순위 근거
- 보안 취약점 가능성
- 신규 기능 추가 어려움
```

## 리팩토링 전략

기술 부채를 갚는 것이 리팩토링이다.

### 언제 리팩토링하는가?

**하지 말아야 할 때**:
- 데드라인 직전
- 요구사항이 불명확할 때
- 테스트가 없을 때

**해야 할 때**:
- 같은 부분을 3번째 수정할 때
- 버그가 자주 나는 곳
- 새 기능 추가 전

### 안전한 리팩토링

```
1. 테스트 작성
   ↓
2. 리팩토링
   ↓
3. 테스트 통과 확인
   ↓
4. 코드 리뷰
   ↓
5. 배포
```

테스트 없이 리팩토링하는 건 안전벨트 없이 운전하는 것.

### 점진적 개선

한 번에 다 고치려 하지 말자:
- 매주 1개 기술 부채 해결
- "Boy Scout Rule": 캠핑장을 발견했을 때보다 깨끗하게

## 코드 리뷰 체크리스트 (품질 관점)

### 기능
- [ ] 요구사항을 충족하는가?
- [ ] 엣지 케이스를 고려했는가?
- [ ] 에러 핸들링이 적절한가?

### 설계
- [ ] 단일 책임 원칙을 따르는가?
- [ ] 중복 코드는 없는가?
- [ ] 확장 가능한 구조인가?

### 코드 품질
- [ ] 변수명이 명확한가?
- [ ] 함수가 너무 길지 않은가? (30줄 이하)
- [ ] 복잡도가 적절한가?
- [ ] 주석이 "왜"를 설명하는가?

### 테스트
- [ ] 테스트 코드가 있는가?
- [ ] 주요 경로를 커버하는가?
- [ ] 테스트가 실패하는 경우를 확인했는가?

### 보안
- [ ] 입력 검증이 있는가?
- [ ] 민감 정보가 노출되지 않는가?
- [ ] SQL Injection 등 취약점은 없는가?

## 팀 코딩 컨벤션

일관성이 품질이다.

### 네이밍
```typescript
// 좋음
const userAuthentication = ...
function calculateTotalPrice() { ... }
const isEmailValid = ...

// 나쁨
const ua = ...
function calc() { ... }
const check = ...
```

### 함수 크기
- 한 함수는 한 가지 일만
- 30줄 넘으면 분리 검토
- 화면 스크롤 없이 볼 수 있게

### 주석
```typescript
// 나쁨: 무엇을 하는지 설명
// 사용자 이름을 가져온다
const name = user.name;

// 좋음: 왜 하는지 설명
// 이메일 도메인 검증을 위해 소문자 변환 필요
const email = user.email.toLowerCase();
```

## 실행 계획

**이번 주**:
- SonarQube 설정
- GitHub Actions에 품질 체크 추가
- 기술 부채 이슈 10개 등록

**다음 주**:
- 코드 리뷰 체크리스트 적용
- 첫 리팩토링 대상 선정 및 시작

**이번 달**:
- 테스트 커버리지 20% 달성
- 코딩 컨벤션 문서화
- 분기별 리팩토링 계획 수립

## 다음 편 예고

v7에서는 **팀 성장 및 지식 공유 체계**를 다룬다:
- 온보딩 프로세스
- 기술 공유 문화
- 학습 지원 체계
- 멘토링 시스템

코드 품질은 팀 품질에서 나온다.

## 마치며

완벽한 코드는 없다. 하지만 나아지려는 노력은 있을 수 있다.

기술 부채를 0으로 만들 수는 없다. 하지만 관리할 수는 있다. 무엇이 있는지 알고, 언제 갚을지 계획하면 된다.

매주 조금씩, 지속적으로. 그것이 코드 품질을 유지하는 유일한 방법이다.

---

**글자 수**: 약 2,250자
**다음 편**: v7 - 팀 성장 및 지식 공유 체계