proven-python: AI 에이전트가 작업을 완료하기 전에 Python 코드를 증명하게 하세요

문제점

AI 에이전트가 작성하는 대부분의 코드는 그럴싸해 보입니다. 컴파일도 되고, 읽기도 좋으며, 아마도 작동할 것입니다. 문제는 바로 그 "아마도"입니다. 에이전트는 작업이 완료된 것처럼 보이면 멈추는데, "완료된 것처럼 보이는 것"은 "증명된 완료"인 경우가 드뭅니다. 당신은 나중에 아무도 테스트하지 않은 상황에서, 즉 운영 환경(production)에서 그 격차를 발견하게 됩니다.

proven-python

proven-python은 AI 코딩 에이전트가 숙련된 엔지니어가 실제로 Python 작업을 수행하는 방식에 따르도록 강제하는 Claude Code 스킬입니다:

• 실패하는 테스트를 먼저 작성한 다음, 이를 통과시키는 코드를 작성합니다.
• 모든 시그니처(signature)를 입력하고, 설명되지 않은 무시(ignores) 없이 mypy --strict를 통과합니다.
• 함수를 작게 유지하고 정직한 이름을 붙입니다.
• 버그 수정은 수정 없이는 실패하는 회귀 테스트(regression test)와 함께 배포됩니다.
• ruff, mypy, pytest가 모두 통과(green)될 때까지 아무것도 "완료"된 것이 아닙니다.

이것은 모델 호출(model-invoked) 방식입니다. 에이전트가 Python을 작성, 변경, 디버깅, 테스트 또는 리뷰하기 직전에 이를 로드하며, 아무도 실행해보지 않은 그럴싸해 보이는 코드를 생성하는 대신 이 절차를 따릅니다.

당신의 방해가 되지 않습니다

에이전트와 싸우는 규율 스킬은 스킬이 없는 것보다 더 나쁩니다. proven-python은 "판단력을 동반한 적용(apply with judgment)" 규칙을 가지고 있습니다. 즉, 코드에 따라 엄격함을 조절하고(일회성 스크립트는 전체 게이트가 아닌 그 정신만을 따름), 당신의 지시와 코드베이스의 컨벤션(conventions)을 존중하며, 한 줄짜리 차이(diff)에 대해서는 형식적인 절차를 건너뜁니다. 이는 Anthropic의 자체 Claude Code 베스트 프랙티스를 무시하는 것이 아니라, 그에 맞추어 설계되었습니다.

구축 방식

• 절차는 짧게 유지됩니다. 깊이(테스트, 타이핑, 설계, 문서, 리뷰, 사람이 읽을 수 있는 출력)는 필요할 때 로드되는 참조 파일에 존재하므로 컨텍스트(context)를 팽창시키지 않습니다.
• 복사해서 붙여넣을 수 있는 pyproject, pre-commit, CI 템플릿을 제공합니다. 모델에게 행동을 요구하는 한 단락의 글보다 빌드를 실패하게 만드는 명령어가 더 효과적이기 때문입니다.
• 에이전트 불문(agent-agnostic) 방식입니다: 일반 Markdown 형식이므로 Codex, Cursor 또는 스킬이나 지침 파일을 읽는 모든 에이전트에 바로 적용할 수 있습니다.
• 리포지토리(repo) 자체의 코드도 동일한 기준을 유지합니다: 검증 스크립트는 타입이 지정되어 있고, 테스트되었으며, CI에 의해 제어됩니다.

설치

/plugin marketplace add shanwije/proven-python
/plugin install proven-python

또는 skills/proven-python을 프로젝트의 .claude/skills 디렉토리로 복사하세요.

오픈 소스 (Open source)

MIT 라이선스이며, 표준 Python 및 엔지니어링 문헌에서 추출한 원칙을 따릅니다. 모든 출처와 라이선스는 리포지토리(repo)에 나열되어 있습니다. 피드백과 PR(Pull Request)을 환영하며, 특히 규칙이 너무 엄격하거나 방해가 되는 부분에 대한 의견을 기다립니다.

https://github.com/shanwije/proven-python