M9 · 주의할 점 페이지 쓰기

목표

• 직접 겪은 실수 하나를, 다음 사람이 증상만 보고도 알아볼 수 있게 씁니다.
• 그 메커니즘, 다른 원인과 구별하는 확인 방법, 해결 방법을 설명하고 각각을 출처로 뒷받침합니다.
• 영어·한국어·중국어로, 또는 한국어와 중국어 페이지를 보류(pending)로 표시한 채 사이트의 검사를 통과시킵니다.

시작하기 전에

• 주의할 점의 페이지들이 어떻게 쓰였는지 보고, 저장소의 docs/GOTCHA_TEMPLATE.md 템플릿을 읽습니다.
• PRIVACY_RULES.md를 읽습니다: 실제 프로젝트의 어떤 것도, 기관·장치·설치 장소의 이름도 쓰지 않습니다.

단계

1. 실수 고르기

직접 겪은 실수를 하나 고르고, 원인을 알기 전에 처음 본 모습으로 설명합니다. 그 실수가 일어난 프로젝트에 속한 것은 모두 걷어 냅니다. 페이지는 어떤 설계에도 맞는 내용이어야 합니다.

2. 재현하기

가능하면 사이트의 도구로 메커니즘을 보여 줍니다. 컨버터 수준의 실수는 전원의 전압을 고정해 버리는 고정 듀티 플라이백처럼 시뮬레이터로 보여 줄 수 있는 경우가 많습니다. 예를 들어 출력이 고정 전압에 연결된 벅의 시뮬레이터 프리셋은 끝내 자리 잡지 않는 인덕터 전류를 보여 줍니다.

▶ 시뮬레이터에서 열기: 벅
초기값을 가져온 예제 sim-buck-fixed

3. 페이지 쓰기

템플릿을 따릅니다: 태그, 그리고 증상, 원인, 확인 방법, 해결, 참고 자료. 모든 수치는 합성(synthetic) 예제(examples/synthetic/<name>.yaml, <Val>로 표시)에서 가져오거나, 같은 줄에 인용한 출처에서 가져옵니다. 식은 <EqRef>로 연결하고, 새 식은 먼저 equations.yaml에 넣습니다.

4. 모든 주장 뒷받침하기

장치나 방법에 대한 모든 서술에 references.bib의 출처를 인용합니다. 새 항목은 DOI나 URL을 열어 확인하기 전까지 VERIFY 표시를 유지하며, 그동안에는 공개 페이지에서 인용할 수 없습니다.

5. 검사 실행

python scripts/modulelint.py, python scripts/privacy_scan.py, python scripts/mathlint.py, python scripts/refcheck.py를 실행한 뒤 npm run build를 실행합니다. docs/STATUS.md에 페이지의 행을 추가하고, 한국어와 중국어 페이지를 쓰거나 그곳에 보류로 표시합니다(중국어는 중국어 표에 페이지의 행을 따로 둡니다). 사이트에 올리고 싶다면 풀 리퀘스트를 엽니다.

완료 기준

• 직접 겪은 실수를 처음 본 모습으로 설명하고, 그 일이 일어난 프로젝트의 것은 아무것도 담지 않습니다.
• 페이지가 템플릿을 따릅니다: 태그, 그리고 증상, 원인, 확인 방법, 해결, 참고 자료.
• 모든 수치가 <Val>로 표시한 합성 예제에서, 또는 같은 줄에 인용한 출처에서 옵니다.
• 장치나 방법에 대한 모든 주장이 references.bib의 검증된 항목을 인용합니다.
• modulelint, privacy_scan, mathlint, refcheck가 통과하고 사이트가 빌드됩니다.
• 한국어 페이지가 있거나, STATUS의 행이 한국어를 보류로 표시합니다.
• 중국어 페이지가 있거나, STATUS의 중국어 표에 있는 행이 중국어를 보류로 표시합니다.

이 미션 초기화

체크 표시는 이 브라우저에만 저장됩니다. 계정이 필요 없고 아무것도 전송되지 않습니다.

주의할 점

• 원인을 이미 염두에 두고 쓴 증상은 아직 원인을 찾지 못한 사람에게 도움이 되지 않습니다. 본 것을 그대로 씁니다.
• 작업하던 프로젝트의 수치는 반올림해도 쓸 수 없습니다. 같은 효과를 보이는 어림수로 합성 예제를 만듭니다.
• 확인 방법이 없는 해결은 추측일 뿐입니다. 해결이 효과가 있었는지 어떻게 아는지 씁니다.

더 알아보기

• 응용 노트 Impedance Measurement Handbook (5950-3000) — Keysight Technologies · 확인일 2026-09-24
  LCR 미터와 임피던스 분석기가 측정하는 원리, 부품의 측정값이 측정 주파수와 신호에 따라 달라지는 이유, 그리고 측정 지그(test fixture)의 연결과 보정 방법.
• 응용 노트 Low Level Measurements Handbook, 7th edition — Keithley Instruments (Tektronix) · 확인일 2026-09-24
  정밀 직류 측정. 그중에서도 테스트 리드의 저항을 측정값에서 빼 주는 4선식(켈빈) 저저항 측정법.

퀴즈

1. 주의할 점 페이지의 수치는 어디서 와야 합니까?

   1. 실수가 일어난 프로젝트에서, 반올림해서
   2. <Val>로 표시한 합성 예제에서, 또는 같은 줄에 인용한 출처에서
   3. 기억에서
   4. 아무 웹 페이지에서
   정답과 해설

   정답: B 개인정보 규칙은 출처가 있는 교과서·데이터시트 수치와 합성 예제 값만 허용합니다. 실제 프로젝트의 수치는 반올림해도 안 됩니다.

2. 독자가 보고 있는 것이 바로 이 주의할 점인지 확신하게 해 주는 섹션은 무엇입니까?

   1. 증상
   2. 원인
   3. 확인 방법
   4. 참고 자료
   정답과 해설

   정답: C 같은 증상에도 원인이 여럿일 수 있습니다. 확인 방법은 이 원인을 다른 것과 구별하는 측정이나 점검을 줍니다.

3. 새 참고 문헌에 아직 VERIFY 표시가 있습니다. 페이지에서 인용할 수 있습니까?

   1. 예, 제목이 맞아 보이면
   2. 아니요: DOI나 URL을 열어 확인하고 표시를 지우기 전까지 refcheck가 실패합니다
   3. 예, 한국어 페이지에서만
   4. 각주에서만
   정답과 해설

   정답: B 검증되지 않은 항목은 공개 페이지에서 인용할 수 없습니다. 아무도 확인하지 않은 것을 가리키는 인용이 없도록 하기 위해서입니다.

4. 한국어 페이지를 아직 쓰지 않았습니다. 사이트에는 무엇이 필요합니까?

   1. 아무것도 필요 없습니다
   2. 한국어 페이지를 보류로 표시한 docs/STATUS.md의 행
   3. 기계 번역
   4. 영어 페이지를 08-gotchas 밖으로 옮기기
   정답과 해설

   정답: B modulelint는 STATUS가 한국어 페이지를 보류로 표시할 때만 한국어 짝이 없는 영어 페이지를 받아들입니다.

5. 원인보다 증상을 먼저 쓰는 이유는 무엇입니까?

   1. 템플릿이 섹션을 알파벳 순으로 정렬하기 때문입니다
   2. 이 페이지가 필요한 독자는 아직 원인은 모르고 보이는 것만 알기 때문입니다
   3. 원인은 쓰기 어렵기 때문입니다
   4. 상관없습니다
   정답과 해설

   정답: B 주의할 점은 증상으로 찾습니다. 원인을 염두에 두고 쓰면 다음 사람이 벤치에서 보는 모습과 맞지 않습니다.