AI 코딩 시대의 Python 품질 게이트를 만들어 보았다 ~ pyproject.toml · Makefile · AGENT.md로 품질을

최근에는 Codex나 Claude Code와 같은 AI 에이전트를 사용하여 Python 개발을 하는 기회가 늘어나고 있습니다.

실제로 사용해 보면, AI는 놀라울 정도로 빠르게 코드를 작성해 줍니다.

설계서를 읽히면 몇 분 만에 API를 구현하고, 테스트 코드까지 생성해 주는 일도 드물지 않습니다.

하지만 운용해 나가는 과정에서 다음과 같은 과제가 보이기 시작했습니다.

• 타입 힌트 (Type Hint)를 쓰는 것을 잊어버림
• Docstring을 작성하지 않음
• Repository Pattern을 무시함
• Prompt를 Python 코드에 직접 작성함
• API에서 SQL을 작성해 버림
• 설정 파일을 멋대로 추가함
• 테스트를 실행하지 않고 종료함

즉,

"동작하는 코드"는 만들 수 있지만, "팀의 규칙"은 지켜주지 않는다

라는 문제입니다.

그래서 이번에는, AI가 망설임 없이 품질을 지킬 수 있는 개발 표준을 작성했습니다.

현재는 다음 3가지를 중심으로 운용하고 있습니다.

파일	역할
pyproject.toml	Build · 의존성 관리 · 품질 도구 설정
Makefile	품질 체크 · 개발 커맨드(Command)의 표준화
AGENT.md	AI가 지켜야 할 설계 규칙

이번 구성은 다음과 같습니다.

포인트는,

품질 규칙 · 실행 방법 · 설계 사상

을 각각 독립시켜 놓은 것입니다.

가장 먼저 수행한 것은,

품질 도구를 모두 pyproject.toml에 집약하는 것

이었습니다.

이전에는

• requirements.txt
• setup.py
• setup.cfg
• pytest.ini
• mypy.ini
• .flake8

등 설정 파일이 흩어져 있었습니다.

AI는 설정 파일이 여러 개 있으면,

새로운 설정 파일을 만들거나, 다른 곳을 수정해 버립니다.

그래서

Single Source of Truth

로서 pyproject.toml만 이용하기로 했습니다.

[build-system]
requires = ["setuptools>=75", "wheel"]
build-backend = "setuptools.build_meta"
...

• PEP517 준수 Build를 이용한다
• Python 버전을 고정한다
• setup.py를 불필요하게 만든다

AI가 오래된 Build 방법을 작성하지 않도록 하고 있습니다.

[project.optional-dependencies]
dev = [
...
...

의존 라이브러리를

• Runtime
• Development
• Documentation

으로 분리하고 있습니다.

예를 들어

• pytest
• mypy
• black

은 운영 환경(Production)에서는 불필요하므로 dev에,

MkDocs는 docs에 추가하고 있습니다.

AI에게

"pytest를 추가해 주세요"

라고 의뢰해도, 적절한 위치에 추가할 수 있게 됩니다.

[tool.ruff]
line-length = 88
target-version = "py312"
...

Lint는 Ruff로 통일했습니다.

주요 규칙은

Rule	내용
B	Bugbear (버그가 발생하기 쉬운 코드)
...

Black과 책임을 분리함으로써

• Ruff = 품질
• Black = 포맷팅 (Formatting)

으로 나누었습니다.

[tool.black]
line-length = 88
target-version = ["py312"]

Black은 코드 포맷팅 전용입니다.

AI는 공백이나 줄 바꿈이 매번 바뀌기 때문에, 포맷팅을 완전히 자동화하고 있습니다.

[tool.mypy]
check_untyped_defs = true
disallow_untyped_defs = true
...

AI는

def create(data):

와 같은 코드를 작성하기 쉽습니다.

Mypy를 이용함으로써

• 타입 힌트 없음
• Any의 남용
• Optional의 암묵적 변환

을 방지하고 있습니다.

[tool.pytest.ini_options]

pytest.ini를 생성하지 않고, 설정을 pyproject.toml에 집약하고 있습니다.

AI가 설정 파일을 늘리지 않도록 하기 위해서입니다.

[tool.pydocstyle]
convention = "numpy"
[tool.interrogate]
...

Docstring은 NumPy 형식으로 통일하고 있습니다.

나아가 Docstring 기재율 95% 이상을 품질 게이트 (Quality Gate)로 설정했습니다.

AI는 구현을 우선시하기 때문에 Docstring 작성을 잊어버리는 경우가 많은데, 이 설정은 매우 효과적이었습니다.

[tool.coverage.report]
fail_under = 80

테스트 커버리지 (Test Coverage) 80% 이상을 유지합니다.

100%를 목표로 하기보다, 지속적으로 80% 이상을 유지하는 것이 더 현실적이라고 생각합니다.

품질 도구를 도입하더라도,

매번 명령어를 외우는 것은 번거로운 일입니다.

그래서

make check

만으로 품질 확인이 끝나도록 했습니다.

make up
make down
make rebuild

Docker 조작을 통일하고 있습니다.

개발자도 AI도 Docker Compose의 세세한 옵션을 기억할 필요가 없습니다.

make migrate
make revision name=create_users

Alembic Migration도 표준화하고 있습니다.

AI가 Migration 명령어를 매번 찾아볼 필요가 없습니다.

make ollama-health
make ollama-test

로컬 LLM (Local LLM)을 이용하고 있기 때문에, 통신 확인도 Makefile에 모아두었습니다.

품질 확인은 개별적으로도 실행할 수 있습니다.

make lint

Ruff

make format

Black

make typecheck

Mypy

make docstyle

Docstring

make coverage

Coverage

용도에 따라 개별 실행할 수 있습니다.

최종적으로는

check:
  lint
  format-check
  ...

만 실행합니다.

즉

make check

만으로

• Ruff
• Black
• Mypy
• Pytest
• Coverage
• Docstring
• MkDocs

까지 일괄적으로 품질 확인을 할 수 있습니다.

AI에 대한 지시도

구현 후에

make check를

실행해 주세요

라고만 하면 됩니다.

이번에 가장 효과가 있었던 것은

AGENT.md

입니다.

품질 도구로는 Repository Pattern이나 Service Layer 같은

아키텍처 (Architecture)

까지는 보장할 수 없습니다.

그래서 AI가 지켜야 할 규칙을 문장으로 정의했습니다.

예를 들어

・Type Hint
・NumPy 형식 Docstring
・Pydantic
...

AI가

• API에 SQL을 작성하는 것
• Prompt를 Python 코드에 작성하는 것
• HTTP 통신을 Service에 작성하는 것

등을 방지하고 있습니다.

반대로

API에서 SQL을 작성하지 말 것
Service에서 Session을 직접 조작하지 말 것
Prompt를 코드에 작성하지 말 것
...

도 정의하고 있습니다.

실제로 가장 효과가 있었던 것은 금지 사항이었습니다.

AI는 "무엇을 쓸 것인가"보다 "무엇을 써서는 안 되는가"를 명시했을 때,

설계 규칙을 더 잘 지키는 경향이 있었습니다.

실제로는 다음과 같은 흐름으로 개발하고 있습니다.

현재는

• Ruff
• Black
• Mypy
• Coverage
• Docstring

까지이지만,

앞으로는

• pre-commit
• Bandit
• pip-audit
• deptry
• import-linter
• vulture
• radon

등도 추가하고 싶습니다.

특히 import-linter를

이용하면

API
↓
Service
...

이외의 의존 관계를 금지할 수 있기 때문에, AI에 의한 아키텍처 붕괴를 더욱 방지할 수 있다고 생각합니다.

이번에 구축한 품질 게이트는

pyproject.toml: 품질 규칙 -
Makefile: 품질 체크의 표준화 -
AGENT.md: AI에게 지키게 할 설계 규칙

이라는 3층 구조로 되어 있습니다.

AI 코딩에서는 「어떤 AI를 사용하는가」 보다 **「AI가 망설이지 않도록 개발 표준을 마련하는 것」**이 장기적으로 코드 품질에 더 큰 영향을 미친다고 느끼고 있습니다.

아직 시행착오를 겪는 중이지만, 저와 마찬가지로 AI를 활용하여 Python 개발을 하고 계신 분들께 참고가 된다면 좋겠습니다.

만약 "이런 품질 게이트(Quality Gate)도 도입하는 것이 좋다"라거나 "우리 회사는 이런 방식으로 운영하고 있다"와 같은 의견이 있다면, 꼭 댓글로 알려주세요.