src layout으로 설치된 code만 검사한다

오늘의 질문

package를 src/ 아래 두고 test와 CLI가 repository root의 우연한 import가 아니라 설치된 wheel/module을 사용하도록 경계를 고정한다. 이를 생략하면 working directory에서는 import되지만 clean environment의 wheel에는 파일이 빠지거나 같은 이름의 local module이 가린다. 상황에서도 데모는 보일 수 있지만 제품·검증·운영 책임을 방어할 수 없습니다.

아직 답을 몰라도 괜찮아요. 아래 작은 예시를 보고 먼저 예상해 보세요.

01 · 가볍게 시작하기

정답을 보기 전에 먼저 골라볼까요?

눈으로만 보고 답 하나를 떠올려 보세요개발 checkout·CI artifact·사용자 설치 환경에서 같은 package를 실행의 축소된 product slice에서 src layout으로 설치된 code만 검사한다 release 판단을 수행한다.cp14 frozen synthetic fixture · fixed clock/UTC · outbound deny · secret-like sentinel · one independent mutant

1
먼저 골라보기
틀려도 괜찮아요. 지금 생각한 답 하나를 정해요.
2
그림으로 확인하기
움직이는 순서와 달라지는 곳만 천천히 찾아요.
3
내 말로 다시 말하기
한 문장으로 말해 보면 내가 이해한 곳을 확인할 수 있어요.

02 · 그림으로 보기

그림이 움직이는 순서를 직접 확인해요

01관찰src layout · import path · wheel content · shadowing
02추론package를 src/ 아래 두고 test와 CLI가 repository root의 우연한 import가 아니라 설치된 wheel/module을 사용하도록 경계를 고정한다. import origin·wheel file list·root-import negative test·clean install path receipt는 working directory에서는 import되지만 clean environment의 wheel에는 파일이 빠지거나 같은 이름의 local module이 가린다.를 포함한 정상·경계·실패 실행에서 독립적으로 다시 계산할 수 있어야 한다. src layout으로 설치된 code만 검사한다은 AI-off 기준선을 먼저 봉인하고 AI 제안 diff를 검토한 뒤, AI가 보지 못한 mutant로 재검증하고 사람이 승인·수정·거절한다. 개발 checkout·CI artifact·사용자 설치 환경에서 같은 package를 실행로 전이할 때 구현보다 contract·effect boundary·evidence owner·residual risk를 먼저 보존한다.
03검증src layout으로 설치된 code만 검사한다의 contract·owner·normal/boundary/failure outcome을 AI 없이 먼저 고정한다. working directory에서는 import되지만 clean environment의 wheel에는 파일이 빠지거나 같은 이름의 local module이 가린다.를 frozen synthetic fixture로 재현하고 최초 divergence와 expected verdict를 설명한다. AI 제안은 baseline과 diff로만 검토하고 독립 mutant에서 imported module path가 installed artifact 내부인지 검증하는 import-boundary probe를 구현한다.을 다시 실행한다. import origin·wheel file list·root-import negative test·clean install path receipt와 사람의 accept·refactor·reject 판정 및 residual risk를 함께 제출한다.

src layout으로 설치된 code만 검사한다의 contract·implementation·failure·evidence·human verdict를 한 화면에서 대조한다.package를 src/ 아래 두고 test와 CLI가 repository root의 우연한 import가 아니라 설치된 wheel/module을 사용하도록 경계를 고정한다.에서 working directory에서는 import되지만 clean environment의 wheel에는 파일이 빠지거나 같은 이름의 local module이 가린다.로 갈라지는 baseline·AI diff·independent mutant·human verdict 경로와 import origin·wheel file list·root-import negative test·clean install path receipt를 표시한다.현재 화면: 정적 요약 지도 · 읽는 방법: baseline·AI diff·mutant·verdict 단계를 선택하면 contract, first divergence, evidence와 residual risk가 동기화된다. · 모션 축소 설계: 자동 재생 없이 선택 결과를 즉시 표시하고 번호·문자 label·선 종류·pattern으로 색상 외 의미를 중복 제공한다.

처음 보는 말도 책 읽듯 풀어봐요

이 수업은 쉬운 뜻과 생활 예를 아직 함께 준비하지 못했어요. 설명 없는 정확한 이름은 먼저 보여 주지 않을게요.

그림에서 찾을 쉬운 규칙

01package를 src/ 아래 두고 test와 CLI가 repository root의 우연한 import가 아니라 설치된 wheel/module을 사용하도록 경계를 고정한다.
02import origin·wheel file list·root-import negative test·clean install path receipt는 working directory에서는 import되지만 clean environment의 wheel에는 파일이 빠지거나 같은 이름의 local module이 가린다.를 포함한 정상·경계·실패 실행에서 독립적으로 다시 계산할 수 있어야 한다.
03src layout으로 설치된 code만 검사한다은 AI-off 기준선을 먼저 봉인하고 AI 제안 diff를 검토한 뒤, AI가 보지 못한 mutant로 재검증하고 사람이 승인·수정·거절한다.
04개발 checkout·CI artifact·사용자 설치 환경에서 같은 package를 실행로 전이할 때 구현보다 contract·effect boundary·evidence owner·residual risk를 먼저 보존한다.

03 · 같이 풀어보기

한 단계씩 따라가면 어렵지 않아요

개발 checkout·CI artifact·사용자 설치 환경에서 같은 package를 실행의 축소된 product slice에서 src layout으로 설치된 code만 검사한다 release 판단을 수행한다.

함께 볼 작은 예시cp14 frozen synthetic fixture · fixed clock/UTC · outbound deny · secret-like sentinel · one independent mutant

04 · 이제 내가 해볼 차례

여기까지 오면 이런 일을 할 수 있어요

imported module path가 installed artifact 내부인지 검증하는 import-boundary probe를 구현한다.을 수행하고 import origin·wheel file list·root-import negative test·clean install path receipt로 package를 src/ 아래 두고 test와 CLI가 repository root의 우연한 import가 아니라 설치된 wheel/module을 사용하도록 경계를 고정한다.을 독립 검증한다.

src layout으로 설치된 code만 검사한다의 contract·owner·normal/boundary/failure outcome을 AI 없이 먼저 고정한다.
working directory에서는 import되지만 clean environment의 wheel에는 파일이 빠지거나 같은 이름의 local module이 가린다.를 frozen synthetic fixture로 재현하고 최초 divergence와 expected verdict를 설명한다.
AI 제안은 baseline과 diff로만 검토하고 독립 mutant에서 imported module path가 installed artifact 내부인지 검증하는 import-boundary probe를 구현한다.을 다시 실행한다.
import origin·wheel file list·root-import negative test·clean install path receipt와 사람의 accept·refactor·reject 판정 및 residual risk를 함께 제출한다.

05 · 자주 헷갈리는 지점

틀린 답도 이유를 알면 다음에는 맞힐 수 있어요

01repository에서 pytest가 통과하면 wheel에도 같은 code가 들어 있다.

한 번 더 생각해 볼 질문cp14 src layout으로 설치된 code만 검사한다에서 이 주장을 깨는 최소 반례와 관찰 가능한 판정값을 쓰세요.

이렇게 고쳐 생각해요package를 src/ 아래 두고 test와 CLI가 repository root의 우연한 import가 아니라 설치된 wheel/module을 사용하도록 경계를 고정한다.

02sys.path를 추가하면 packaging 문제를 해결한 것이다.

한 번 더 생각해 볼 질문cp14 src layout으로 설치된 code만 검사한다에서 이 주장을 깨는 최소 반례와 관찰 가능한 판정값을 쓰세요.

이렇게 고쳐 생각해요working directory에서는 import되지만 clean environment의 wheel에는 파일이 빠지거나 같은 이름의 local module이 가린다.는 성공 출력과 별도로 재현하고 최초 위반 지점에서 차단해야 한다.

03AI가 import error를 상대 경로로 고치면 clean install 검증은 필요 없다.

한 번 더 생각해 볼 질문cp14 src layout으로 설치된 code만 검사한다에서 이 주장을 깨는 최소 반례와 관찰 가능한 판정값을 쓰세요.

이렇게 고쳐 생각해요import origin·wheel file list·root-import negative test·clean install path receipt와 독립 mutant·human verdict가 함께 있어야 승인 범위를 설명할 수 있다.

06 · 더 궁금할 때만 보기

선생님과 검토자를 위한 믿을 만한 원문

원문과 어디까지 참고했는지 펼쳐 보기처음 배우는 동안에는 열지 않아도 괜찮아요.

Python Packaging Authority · 2026년 7월 28일에 확인했어요Writing your pyproject.toml

[build-system]·[project]·metadata·requires-python·dependency·entry point를 하나의 versioned package contract로 연결한다.

Python Packaging Authority · 2026년 7월 28일에 확인했어요src layout vs flat layout

working tree accidental import를 막고 설치된 wheel을 실제 test 대상으로 만드는 src-layout의 비용과 이점

Python Packaging Authority · 2026년 7월 28일에 확인했어요Tool recommendations

python -m build 기반 sdist/wheel과 Trusted Publishing 권고. deprecated direct setup.py command를 release recipe로 사용하지 않는다.