나의 Claude Code 품질 관리 워크플로
Claude Code 사용 시의 품질 관리 사례를 공유합니다. Hooks 자동화, 테스트 전략, AI Review, Pre-commit, GitHub 연동의 5가지 방어선
왜 AI 프로그래밍의 품질 관리에 주목해야 하는가?
Claude Code를 사용하여 AI 프로그래밍을 하는 과정에서 중요한 현상을 발견했습니다. Claude Code는 개발 속도를 2~3배 향상시킬 수 있지만, 이러한 AI 보조 프로그래밍의 효율 향상은 새로운 과제도 가져옵니다 -- AI가 생성한 코드에는 더 엄격한 품질 검사와 품질 관리가 필요합니다.
적절한 품질 검사 프로세스가 없으면, Claude Code의 작업 효율은 오히려 빈번한 디버깅과 리팩토링으로 인해 저하됩니다.
이를 통해 하나의 핵심 원칙을 깨달았습니다: AI의 출력은 검증이 필요하며, 맹목적으로 신뢰해서는 안 됩니다.
반년간의 실천과 최적화를 거쳐 포괄적인 품질 보증 체계를 구축했습니다. 이제 저의 품질 검사 프로세스를 공유하겠습니다. 이것은 자동화 검사에서 수동 리뷰까지의 계층적 품질 관리 프로세스입니다. 이 프로세스는 점진적입니다 -- 가장 기본적인 부분부터 시작하여 필요에 따라 점차 강화할 수 있습니다.
Claude Code의 기본 사용법에 아직 익숙하지 않은 분은 먼저 "Claude Code 10대 모범 사례"를 읽어 기본 워크플로를 이해해 주세요.
시작하기 전에: 검사를 원활하게 하는 두 가지 준비
구체적인 검사 프로세스에 들어가기 전에, 두 가지 준비 작업을 통해 이후의 품질 검사가 훨씬 효율적으로 진행됩니다.
기능별로 코드 구성하기
프로젝트 코드의 구성 방식에는 보통 두 가지 선택지가 있습니다: 기술 레이어별 분류(레이어드 아키텍처) 또는 비즈니스 기능별 분류(기능별 구성)입니다. AI 보조 프로그래밍 시나리오에서 저는 후자를 선택했습니다:
레이어드 아키텍처
src/
├── routers/ # 所有路由/API 端点
├── services/ # 所有业务逻辑
├── repositories/ # 所有数据访问
└── models/ # 所有数据模型기능별 구성 아키텍처
src/
├── user/
│ ├── __init__.py # Python 包标识
│ ├── router.py # FastAPI 路由定义
│ ├── service.py # 业务逻辑
│ ├── models.py # 数据库模型（SQLAlchemy）
│ ├── schemas.py # Pydantic 数据验证
│ └── CLAUDE.md # 模块特定规范
└── order/
├── __init__.py
├── router.py
├── service.py
├── models.py
└── schemas.py왜 기능별 구성이 AI에게 더 친화적인가?
예를 들어 보겠습니다. Claude에게 리뷰 기능을 수정하게 할 때, 레이어드 아키텍처에서는 routers/review.py, services/review_service.py, models/review_model.py, 그리고 schemas/review_schema.py까지 최소 4개의 서로 다른 디렉토리의 파일을 읽어야 합니다. 반면 기능별 구성에서는 관련 파일이 모두 src/review/ 디렉토리에 모여 있어 AI가 모듈 전체의 컨텍스트를 한 번에 파악할 수 있습니다.
또한 각 모듈에 자체 CLAUDE.md를 가질 수 있어, 해당 모듈 고유의 규칙과 제약을 정의할 수 있습니다. 이를 통해 AI가 서로 다른 모듈 간을 전환할 때 자동으로 다른 개발 규범에 적응할 수 있습니다.
Make 명령어로 통합 진입점 만들기
새 프로젝트를 시작할 때 가장 먼저 하는 일은 Makefile을 만드는 것입니다. 왜일까요?
AI가 코드를 작성할 때 프로젝트의 "규칙"을 알아야 합니다. 매번 Claude에게 "ruff check && mypy . && pytest를 실행해 주세요"라고 말하는 것보다, 간단히 "make check를 실행해"라고 하는 것이 훨씬 효율적입니다.
이것이 제 기본 Makefile 템플릿입니다:
.PHONY: help setup dev run stop format check test clean
help: ## 显示帮助信息
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf " %-15s %s\n", $$1, $$2}'
setup: ## 初始化开发环境（安装依赖 + git hooks）
@echo "📦 Installing dependencies..."
uv sync
@echo "🔧 Installing pre-commit hooks..."
uv run pre-commit install
dev: ## 本地开发模式（支持热重载）
@echo "🚀 Starting dev server with hot reload..."
uvicorn main:app --reload --host 0.0.0.0 --port 8000
run: ## 生产模式（多 worker）
@echo "🚀 Starting production server..."
uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000
stop: ## 停止后台运行的服务
@echo "🛑 Stopping server..."
# 停止服务的逻辑
format: ## 格式化代码
@echo "🎨 Formatting code..."
black .
ruff check --fix .
check: ## 代码检查 + 类型检查 + 测试
@echo "🔍 Checking code..."
ruff check .
mypy .
pytest
test: ## 运行测试
@echo "🧪 Running tests..."
pytest
clean: ## 清理缓存文件
@echo "🧹 Cleaning up..."
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true왜 이것이 효과적인가?
- 통합된 명령어 인터페이스: 프로젝트가 어떤 기술 스택을 사용하든,
make format,make test는 항상 유효합니다 - AI 친화적: Claude가 이러한 간결한 명령어를 더 쉽게 기억하고 사용할 수 있습니다
- 규범 강제: 팀 구성원(또는 미래의 자신)이 무엇을 실행해야 하는지 명확합니다
이 간단한 표준화로 반복적인 커뮤니케이션이 줄어들며, AI 보조 개발에서 특히 효과적입니다.
완전한 AI 프로그래밍 품질 검사 프로세스
제1 방어선: Hooks 자동 검사
Claude Code의 품질 검사 프로세스에서 가장 기본적인 요소는 자동화 검사입니다.
Claude가 코딩을 완료할 때마다, 설정된 Hook이 자동으로 포맷팅을 실행합니다:
{
"hooks": {
"Stop": [{
"hooks": [{
"type": "command",
"command": "make format",
"timeout": 60
}]
}]
}
}이를 통해 수동 개입 없이 코드 스타일의 일관성이 보장됩니다.
제2 방어선: 테스트 전략
Mock에 대해 제 방식은 많은 분들과 다를 수 있습니다: Mock을 쓰지 않아도 되면 쓰지 않는다는 입장입니다.
이유는 간단합니다. Mock 테스트가 통과해도 실제 환경에서 동작한다는 보장이 없습니다. 이런 경험이 여러 번 있었습니다: 유닛 테스트는 모두 그린인데, 배포하면 문제가 발생합니다. Mock이 실제 경계 조건을 숨기고 있었던 것입니다. AI가 생성하는 코드에서는 이 문제가 더 두드러집니다: AI는 테스트를 작성할 때 자신의 코드에 "맞추려는" 경향이 있어, 테스트를 통과시키기 위해 작성하지 진정으로 경계 조건을 검증하는 것이 아닙니다. 통합 테스트가 이런 종류의 문제를 더 효과적으로 발견할 수 있습니다.
물론 Mock이 필요한 시나리오도 있습니다: 유료 API 호출, 시간 관련 로직, 불안정한 서드파티 서비스 등입니다. 하지만 그 외에는 통합 테스트를 작성하는 것을 우선합니다.
커버리지에 대해서는 80%를 목표로 합니다 -- 핵심 로직을 커버하면 충분하며, 100%를 추구할 필요는 없습니다. 특정 모듈을 수정했을 때 pytest tests/user/를 실행하면 빠르게 검증할 수 있어 전체 테스트 완료를 기다릴 필요가 없습니다.
Claude에게 이 테스트 전략을 따르게 하기 위해 CLAUDE.md에 요구사항을 명확하게 기재합니다:
## 测试规范
- 实现新功能时，先写测试，确认测试失败，再写实现代码
- 每次修改后运行 `make test` 确保没有破坏现有功能
- 不要为了让测试通过而修改测试本身
- 外部 API、时间相关逻辑使用 Mock，其他场景优先使用真实依赖제3 방어선: 로컬 AI Review
큰 변경에 대해서는 Claude Code의 Commands를 사용하여 코드 리뷰를 수행합니다. 보통 특정 디렉토리의 변경을 리뷰하도록 Claude에게 요청합니다. 예를 들어 "src/order/의 이번 수정을 리뷰해 줘"와 같이 컨텍스트를 더 집중시킵니다.
# 使用专门的审查 Commands
/code-review:code-review언제 사용하는가?
- 필수: 아키텍처 변경, 신규 기능, 보안 관련
- 권장: 중요한 비즈니스 로직 수정
- 선택: 작은 버그 수정, 간단한 문구 수정
개인 개발자로서, 정기적으로 Claude에게 모듈 전체의 리뷰를 의뢰하기도 합니다. 팀 개발에서는 현실적이지 않습니다 -- 코드는 서로 다른 멤버가 작성하기 때문에 자유롭게 리팩토링하면 다른 사람의 영역을 침범할 수 있습니다. 하지만 개인 개발에서는 그런 걱정이 없어 문제를 발견하면 바로 조정할 수 있습니다.
제4 방어선: Pre-commit Hook
이것이 가장 중요한 단계입니다 -- 검사가 통과하지 않으면 코드를 아예 커밋할 수 없습니다.
제 방식은 pre-commit 프레임워크와 make check를 조합하는 것으로, 설정은 매우 간단합니다:
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: make-check
name: Run make check
entry: make check
language: system
pass_filenames: false모든 검사 로직은 Makefile에서 통합 관리하고, pre-commit은 커밋 시 트리거만 담당합니다.
그런 다음 Makefile에 setup 명령어를 추가합니다:
setup: ## 初始化开发环境
@uv sync
@uv run pre-commit installmake setup을 실행하면, 매번 git commit 시 자동으로 make check가 트리거됩니다.
개인 개발이라면 이 단계는 수동으로 수행할 수도 있습니다. 하지만 setup 명령어 설정을 권장합니다. 다른 컴퓨터로 전환하거나 프로젝트를 다시 클론할 때 make setup을 한 번 실행하기만 하면 개발 환경을 복원할 수 있어, 많은 절차를 기억하거나 다시 설정할 필요가 없습니다.
이러한 설정 작업 자체도 Claude Code에 맡길 수 있습니다 -- "pre-commit을 설정해서 커밋 시 make check를 실행하도록 해 줘"라고 전하면, 설정 파일을 생성하고 설치까지 해줍니다.
제5 방어선: GitHub 연동
Claude Code는 GitHub 연동 기능을 제공하며, Pull Request마다 자동으로 AI 코드 리뷰를 트리거할 수 있습니다.
Claude Code에서 /install-github-app을 실행하고 안내에 따라 인증 절차를 완료하면 됩니다.
설치가 완료되면, 프로젝트에 .github/workflows 디렉토리가 추가되어 있으며, Claude의 리뷰 워크플로 설정이 포함되어 있습니다.
이후 PR을 제출할 때마다 Claude가 자동으로 코드를 리뷰하고 PR에 코멘트를 남깁니다. 리뷰 스타일이나 주안점을 조정하고 싶다면, workflows 내의 prompt 설정을 직접 편집할 수 있습니다.
이것이 마지막 품질 게이트입니다 -- 코드는 병합 전에 한 번 더 AI 리뷰를 받아 놓친 문제가 없는지 확인합니다.
품질 검사 체계 전체 개요
이 5가지 방어선이 포괄적인 품질 보증 체계를 구성합니다:
| 방어선 | 검사 방식 | 트리거 타이밍 | 역할 |
|---|---|---|---|
| Hooks | 자동화 | 코딩 완료 후 | 코드 스타일의 일관성 보장 |
| 테스트 | 수동 + 자동 | 기능 구현 후 | 로직 문제 발견 |
| AI Review | AI 리뷰 | 큰 변경 시 | 즉각적 피드백 획득 |
| Pre-commit | 자동화 | 커밋 전 | 저품질 코드의 리포지토리 혼입 방지 |
| GitHub 연동 | AI 리뷰 | PR 시 | 최종 리뷰 관문 |
이 품질 검사 프로세스는 자동화에서 수동까지, 로컬에서 클라우드까지, Claude Code가 생성하는 코드의 품질을 보장합니다.
정리: AI 시대의 품질 관리 체계
AI 프로그래밍 시대는 이미 도래했지만, 품질 관리가 시대에 뒤떨어지는 일은 없을 것입니다.
이 포괄적인 Claude Code 품질 검사 프로세스는 5가지 품질 관리 단계를 연계하여 견고한 품질 보증 체계를 형성합니다. 어떤 AI 프로그래밍 도구를 사용하든, 이 품질 검사의 사고방식은 보편적으로 적용할 수 있습니다.
AI 프로그래밍에서의 품질 관리에 대한 상세한 경험 공유가 여러분 자신에게 맞는 품질 보증 체계를 구축하는 데 도움이 되기를 바랍니다. 질문이나 자신의 실천 경험을 공유하고 싶으시다면, 댓글로 알려주세요!
관련 글
- "Claude 시스템 아키텍처 완전 해설" -- Hooks, Skills 등 컴포넌트가 아키텍처에서 어떤 위치를 차지하는지 이해하기
- "Eclipse에서 Zed로: 한 개발자의 에디터 진화사" -- 에디터 경량화 + 터미널 중심의 워크플로 진화
- "GSD 심층 분석" -- 사양 기반 AI 프로그래밍 품질 보증 접근법