# Comments — 기본은 무주석

- **주석은 원칙적으로 쓰지 않는다** (사용자 결정, 교정 3회 누적). 설명이 필요하면 주석이 아니라 이름·분리·타입으로 코드를 고치고, 재발성 함정·설계 지식은 하네스 문서(`.claude/rules/`·스킬·incidents)에 적는다 — 주석은 코드와 함께 낡아 거짓이 되고, 골든샘플의 주석은 복제되어 앱 전체로 퍼진다.
- **허용되는 주석은 도구가 요구하는 사유뿐**: `oxlint-disable -- 사유`(code-smell #6이 사유를 강제), `code-smell-ok(<이름>): 사유`, `@ts-expect-error -- 사유`, knip `/** @public 사유 */`, `TODO:` 자리 표식. 이 밖의 설명·의도·규칙 인용 주석은 전부 금지 — 게이트·rule이 이미 지키는 내용의 반복은 특히 금지.
- lint-disable과 룰이 자주 충돌하면 disable을 늘리지 말고 `.oxlintrc.json` 자체를 재검토하라 (disable 욕구는 설정 부채 신호).
- **정리도 작업이다**: 코드를 만질 때 눈에 띈 설명 주석은 같이 지운다. 단, 주석 삭제만을 위한 별도 커밋은 만들지 않는다(불필요한 churn).