초보자를 위한 품질 커맨드(quality command) 1편: 한 번에 돌리는 코드 건강검진이란?

quality command image

1. “코드 돌아가긴 하는데… 진짜 괜찮은 걸까?” – 품질 커맨드(quality command) 생각 시작

비전공자로서 바이브코딩으로 개발하다 보면 이런 대화 한 번쯤 해보셨을 거예요.

“일단 실행은 됩니다.”
“근데… 스타일, 타입, 보안, 마이그레이션, 테스트는요…? 🤔”

코드가 “돌아가는 것”과
코드가 “안전하고, 읽기 좋고, 배포 가능한 상태”인 건 완전히 다른 이야기죠.

그래서 팀마다 이런 말을 자주 합니다.

  • “커밋하기 전에 꼭 이거 한 번 돌려요.”
  • “배포 전에 공통 체크리스트 돌렸나요?”

여기에 나오는 그 “한 번 돌리는 것”을
In this article, we'll use the 품질 커맨드라고 부를게요.

2. 품질 커맨드란 뭐냐면, 아주 간단하게…

quality command post image2

한 줄로 정의하면 이렇습니다.

여러 가지 코드 품질 체크를 한 번에 실행해 주는 대표 명령

예를 들어, Windows 기준으로는 이런 식의 배치 파일 하나가 있을 수 있어요.

  • quality_check.bat 를 더블클릭하거나
  • In the terminal, type quality_check 한 줄만 실행하면,

그 안에서 자동으로

  • Python 구문 에러 있는지 확인
  • Django 프로젝트 설정에 문제 없는지 검사
  • 마이그레이션이 꼬여 있지 않은지 체크
  • 보안 관련 기본 점검 수행
  • (원하면) 테스트까지 한 번에 실행

까지 해주는 거죠.

초보자 입장에서는
“도구 이름/옵션/명령어를 다 외우지 않아도,
품질 커맨드 한 번만 실행하면 된다”는 게 핵심입니다.

3. 왜 이렇게까지 품질 커맨드가 필요할까?

겉으로 보기엔 그냥 “명령 몇 개 묶어둔 배치 파일”처럼 보이는데,
실제로는 팀 생산성에 꽤 큰 차이를 만듭니다.

3-1. 사람마다 “다르게 체크하는 문제”를 없애 준다

  • 어떤 사람은 테스트만 돌리고,
  • 어떤 사람은 linter만 돌리고,
  • 어떤 사람은 Django 시스템 체크는 깜빡하고…

이러면 “누구는 통과, 누구는 실패” 상태가 섞여 버립니다.
품질 커맨드를 쓰면

“우리 팀은 커밋 전 / 배포 전에는 이 명령 한 번은 꼭 돌린다”

라는 공통 기준을 만들 수 있어요.

3-2. 초보자도 “숙련자처럼” 체크할 수 있게 해준다

quality command post image3
  • black, isort, flake8, mypy, bandit, coverage, Django 체크…
    이름만 들어도 벌써 머리가 아픈데요 😂

품질 커맨드에 한 번 세팅만 해두면,
입사 첫날인 주니어도 이렇게만 하면 됩니다.

“저는 커밋 전에 품질 커맨드 돌리고,
에러 없으면 커밋하고 있습니다!”

도구 사용법은 나중에 천천히 배워도 되고,
처음부터 “검사 안 하는” 상태를 막아주는 역할을 합니다.

3-3. 배포 사고를 미리 줄여 준다

  • 마이그레이션 충돌
  • settings 오타
  • 보안 관련 기본 설정 누락
  • 타입 불일치로 인한 런타임 에러

이런 것들은 “돌리기 전에 한 번만 제대로 검사해도 막을 수 있는 것들”이 많아요.

품질 커맨드는 그 “한 번만 제대로”를 강제해주는 안전장치입니다.

quality command post image4

4. 우리가 쓰게 될 품질 커맨드 구성 요소 한눈에 보기

이 시리즈에서는 대략 이런 구성으로 품질 커맨드를 이해할 겁니다.

(1) quality_check.bat – 통합 품질 체크 스크립트

  • Windows에서 더블클릭 또는 커맨드 한 줄로
    • Python 구문 검사
    • Django 시스템 체크
    • 마이그레이션 충돌 체크
    • 보안/배포 기본 점검
    • 테스트 실행(옵션)

까지 한 번에 묶어주는 메인 관제탑 같은 역할입니다.

(2) scripts/py_compile_all.py – Python 구문 검증기

  • 모든 .py 파일을 돌면서 실제로 컴파일이 되는지 확인합니다.
  • 아래는 자동으로 건너뛰게 만들 수 있습니다.
    • 가상환경 폴더
    • __pycache__
    • 마이그레이션 폴더 등

이게 있으면 “실행해 보기 전에 문법 에러부터 잡는” 느낌으로 쓸 수 있어요.

(3) requirements-dev.txt – 개발용 품질 도구 모음

예를 들어 이런 도구들을 한 번에 관리합니다.

  • black – 코드 포매터
  • isort – import 정렬
  • flake8 – 코드 스타일 체크
  • pylint – 조금 더 엄격한 정적 분석
  • mypy – 타입 힌트 검사
  • bandit – 보안 취약점 스캔
  • coverage – 테스트 커버리지 측정
  • pre-commit – git commit 전에 자동으로 검사 실행

“필요할 때마다 pip install”이 아니라,
개발용 품질 도구를 하나의 리스트로 관리for example.

(4) setup.cfg – 도구 공통 설정 파일

  • flake8 최대 라인 길이 (예: 120자)
  • 무시할 규칙 (예: E203, W503)
  • isort 설정 (예: Django 프로젝트에 맞는 그룹 정리)
  • coverage에서 제외할 경로(테스트 코드, 마이그레이션 등)

등을 한 군데에서 통일해 두는 역할입니다.

(5) .pre-commit-config.yaml – 커밋 전에 자동 검증

  • Git에서 커밋할 때마다
    • black
    • isort
    • flake8
    • bandit
      같은 검사들을 자동으로 돌려 주는 설정입니다.
  • “커밋하려는데 포매팅이 안 돼 있네요? 제가 고쳐둘게요”
    이런 느낌으로 동작하게 만들 수 있어요.

5. 초보자가 실제로는 어떻게 쓰게 될까? (사용 시나리오)

이 시리즈는 “커맨드를 하나하나 외우자”가 아니라,
“실제로 이렇게 쓰면 된다”에 초점을 맞추려고 해요.

예를 들어 초보자에게는 이렇게 설명할 수 있습니다.

  1. 코드를 수정한다.
  2. 터미널에서 프로젝트 폴더로 이동한다.
  3. 품질 커맨드를 실행한다. (예: quality_check.bat)
  4. 에러/경고가 나오면 해당 파일을 열어서 고친다.
  5. 다시 품질 커맨드를 돌려본다.
  6. 깨끗하게 통과하면 그때 Git 커밋 & 푸시를 한다.

That is,

“품질 커맨드 통과 = 이 코드는 최소한의 건강검진을 통과했습니다”

라는 하나의 기준을 팀에 만들 수 있는 거죠.

6. 앞으로의 시리즈 구성 (예상)

1편에서는 개념과 전체 그림에 집중했고,
이후에는 이런 순서로 하나씩 다뤄볼 수 있어요.

  • 2편: quality_check.bat 안에서는 실제로 어떤 순서로 무엇을 돌리는지
  • 3편: py_compile_all.py로 문법 체크 자동화하는 방법
  • 4편: requirements-dev.txt, setup.cfg로 품질 도구들을 통합 관리하는 법
  • 5편: .pre-commit-config.yaml로 “커밋 자동 검사” 세팅하기 (실전 Git 연동)

이렇게 가면 초보자도
“아, 팀에서 품질 커맨드를 이렇게 설계했구나”를 자연스럽게 이해할 수 있을 거예요.

7. 용어 정리 (초보자용)

마지막으로, 오늘 글에 나온 기본 용어를 한 번에 정리해둘게요.

  • 품질 커맨드
    여러 품질 관련 도구를 한 번에 실행해 주는 대표 명령어.
    보통 quality_check.bat 같은 스크립트로 만들어 둡니다.
  • 코드 품질 체크
    코드가 일정한 스타일을 지키고 있는지, 버그 가능성은 없는지,
    구조와 타입이 제대로 맞는지, 보안상 위험한 포인트는 없는지 자동으로 검사하는 작업 전체를 말합니다.
  • Python 품질 도구
    Python 코드를 분석하거나 정리해주는 도구들.
    예: black, isort, flake8, pylint, mypy, bandit 등.
  • black
    “코드 스타일을 일관되게 맞춰주는 자동 포매터”.
    사람이 스타일을 논쟁하는 대신, black에 맞춰버리는 철학을 가진 도구입니다.
  • isort
    import 문들을 깔끔하게 정렬해 주는 도구.
    표준 라이브러리 / 서드파티 / 로컬 모듈 순으로 정리하는 등 규칙을 자동으로 맞춰줍니다.
  • flake8
    문법/스타일을 검사해주는 도구.
    안 쓰는 변수, 들쑥날쑥한 스타일 등을 잡아줍니다.
  • pylint
    flake8보다 좀 더 엄격하게 코드 구조를 검사하는 정적 분석 도구.
  • mypy
    Python에 달아둔 타입 힌트(type hint)들이 실제 사용과 잘 맞는지 검사해주는 타입 체커.
  • bandit
    Python 코드에서 보안 취약점이 있을 만한 패턴을 찾아주는 도구.
    예: 하드코딩된 비밀번호, 위험한 함수 사용 등.
  • coverage
    테스트를 돌렸을 때, 코드의 어느 부분까지 실행됐는지(커버리지)를 측정해주는 도구.
  • pre-commit
    Git 커밋 전에 자동으로 실행되는 훅(hook)을 관리해주는 프레임워크.
    품질 커맨드 일부를 이 훅에 연결해두면, 사람이 깜빡해도 자동으로 검사합니다.

Similar Posts