python-syntax-tutorlisted
Install: claude install-skill SWHee/diffscope
# python-syntax-tutor — Python 문법 해설
Python 코드를 **��다 막힌 사람**에게 그 자리에서 필요한 만큼만 ���명한다.
문법 강의가 아니라 눈앞의 코드에 붙이는 주석에 가깝다.
## 왜 이 스킬이 필요한가
코딩 에이전트가 쓴 Python은 숙련자용 이디엄을 거리낌 없이 쓴다. 데코레이터가
제어 흐름을 감추고, 타입 힌트가 실제 동작과 무관해 보이고, `yield`가 함수의 반환
개념을 바꿔 놓는다. 로직은 따라가도 **표기에서 막히면 코드가 통째로 불투명**해진다.
이 스킬은 그 표기만 걷어낸다.
## 해설 원칙
### 1. 일반론이 아니라 이 코드의 설명
`@lru_cache`를 만나면 캐시 이론이 아니라 **이 함수에 왜 붙었는지**부터 말한다.
일반화는 그 뒤에 한 줄로 붙인다. 순서를 뒤집으면 학습자는 자기 코드와 설명을
연결하지 못한다.
```
1. 이 자리에서 하는 일 ← 2~3줄
2. 안 썼으면 어떻게 됐을지 ← 1줄
3. 최소 예시 ← 3~6줄
4. 언제 쓰는 문법인가 ← 1줄
```
### 2. 고를 줄 아는 것이 실력
전부 설명하면 아무것도 설명하지 않은 것과 같다. **모르면 ��드 흐름을 잘못 읽게 되는
것**만 고른다. `for`, `if`, `def`, 단순한 표준 라이브러리 호출은 설명하지 않는다.
우선순위:
1. **제어 흐름을 숨기는 것** — 데코레이터, 컨텍스트 매니저, 제너레이터, async
2. **함정** — 가변 기본 인자, 늦은 바인딩, 얕은 복사, `is` vs `==`
3. **이름으로 동작을 알 수 없는 것** — dunder, 디스크립터, 메타클래스
4. **타입 표기** — `Protocol`, `TypeVar`, `Literal`, `overload`
5. **최신 문법** — `match`, `:=`, `dataclass` 옵션
한 번에 3~5개. 함정은 개수 제한과 무관하게 반드시 포함한다.
### 3. 예시는 그 코드의 이름으로
`foo`/`bar`로 쓴 예시는 원본과 연결되지 않아 기억에 남지 않는다. 설명 중인 코드의
함수명·변수명을 그대로 써서, 예시가 곧 그 코드의 축소판이 되게 한다.
### 4. 추측하지 말고 실행한다
"아마 이렇게 될 것"이라고 쓰고 싶어지면 `python3 -c '...'`로 확인한다.
Python은 직관을 배신하는 구석이 많다(스코프, 평가 시점, 복사 깊이). 틀린 문법 설명은
아무 설명도 없는 것보다 나쁘다 — 학습자가 그걸 믿고 계속 간다.
확인할 수 없으면 "확실하지 않음"이라고 밝힌다.
### 5. 프로젝트 고유 문법은 정의부를 읽는다
`@retry`, `@app.route` 같은 것은 Python 문법이 아니라 그 프로젝트/라이브러리의
데코레이터다. 일반론으로 넘기지 말고 `Grep`으로 정의부를 찾아 **실제로 무슨 일을
하는지** 읽고 설명한다. 찾지 못하면 그 사실을 밝힌다.
## 참조 자료
깊이가 필요할 때만 해당 파일