pstack 의 주석 규칙 Comment Sicko 는 우리 코드의 의외성을 주석으로 설명하지 말라고 합니다. 그런 주석은 지우고, 산문 없이도 동작이 드러나도록 이름을 바꾸거나 뽑아내거나 타입으로 만들 심볼에 MUST KILL 을 표시하라는 것입니다. 이 규칙을 부르는 /no-comments 스킬은 제약 주석을 인코딩한 뒤에 지우는 순서(«encode then delete»)를 둡니다.

이 글은 그 규칙을 모노레포에 적용하며 MUST KILL 로 분류한 주석 929개를 무엇으로 옮길지 나눈, 2026년 10월 28일 기준 작업 도중의 기록입니다. JS/TS 주석 4만 9천여 개를 1차 판정해 보니 95% 가 지울 대상이었고, 이 레포는 할 일 대신 «언제, 어떤 계획에 따라, 왜 이렇게 했는지»를 주석에 적어 왔습니다.

주석이 이렇게 쌓인 원인 하나는 레포 안에 있었습니다. 코딩 에이전트에게 주는 지침 두 곳이 주석을 요구하고 있었습니다. 하나는 «테스트에 명확한 단계별 주석 포함 (리뷰 시 흐름을 이해할 수 있도록)», 다른 하나는 «any 사용 시 반드시 주석으로 사유 명시»입니다. 테스트 단계 서술로 보이는 주석이 정규식 근사치로 1,507개 있었습니다. Comment Sicko 식으로 보면 any 에 사유 주석을 다는 대신 any 를 없애야 하고, 외부 타입의 결함 때문에 정말 불가피할 때만 그 사유가 외부 제약으로 남습니다.

pstack 의 원칙 Encode Lessons in Structure 에는 이런 문장이 있습니다. «If the fix is structural, only use the structural fix. The instruction is the symptom.» 고칠 방법이 구조에 있다면 구조만 고치라는 것, 그리고 지시는 증상이라는 것입니다. 주석을 달라는 지시는 그 모양의 주석을 대량으로 만듭니다.

문서로 적은 규율이 네 번 실패해서 그 판단을 hook 으로 옮겼던 일을 «에이전트 126개가 떴습니다»에 쓴 적이 있는데, 같은 방향의 이야기입니다. 이 두 지침은 정책을 갱신하는 단계에서 바꿀 예정이고, 아직 바꾸지 않았습니다.

코드로 옮길 것 — MUST KILL 929개

MUST KILL 은 지금 주석이 지키고 있는 것을 코드가 지키도록 옮길 대상입니다. 종류별 개수와 예는 다음과 같습니다.

종류 (개수)주석이 하던 말옮길 방향
test (675)자르고 나서 escape 한다 — 순서를 바꾸면 escape 시퀀스가 중간에서 잘릴 수 있다순서를 테스트로 고정
type (82)여기 목록은 DTO 필드와 1:1 이어야 한다 — 타입이 안 지켜 준다손으로 옮겨 적기 제거
extract (79)보존일수 0 은 무기한이다이름 있는 가드로 추출
open-work (35)activeUsers 는 집계되지 않으므로 0구현 또는 필드 제거
rename (34)이 조회 호출이 안 읽음 표시를 정리한다getThreadAndMarkRead()
delete-dead (15)실제 가드 경로는 이 메서드를 거치지 않는다테스트만 부르는 메서드 삭제
handle-error (9)기록 1건 — 절대 던지지 않는다명시적 catch 와 경고 로그

가장 싼 것은 rename 입니다. 조회처럼 보이는 getThread() 에는, 이 호출 자체가 «운영자가 읽었다»로 취급되어 서버에서 안 읽음 표시를 정리하므로 성공한 뒤 목록과 배지 캐시를 반드시 무효화해야 한다는 주석이 붙어 있었습니다. 조회처럼 보이는 함수가 상태를 바꾸는 것입니다. 이름이 getThreadAndMarkRead() 라면 그 주석은 필요 없습니다.

같은 방식으로, 실은 저장 키 정규화기여서 . 을 - 로 바꿔 확장자를 뭉개는 sanitizeFilename() 은 sanitizeStorageKey() 로, 옆의 coverageRatio(0~1)와 단위가 다른 percentile(0~100)은 percentilePct 로 옮길 방향을 잡았습니다.

extract 는 매직 값과 조건에 이름을 붙이는 일입니다. 보존일수 0 은 «무기한 보존»을 뜻하는데, 이 0 을 보통 값처럼 흘리면 기준 시각이 «지금»이 되어 전부 지웁니다. 이것은 주석이 아니라 이름 있는 가드가 막아야 할 일입니다.

type 에는 실제로 한 번 빠뜨린 적이 있는 자리도 있었습니다. 컨트롤러가 DTO 필드를 서비스 입력으로 손으로 옮겨 적는 곳에, «옵션이 전부 선택이라 한 칸을 빼먹어도 컴파일이 통과하고, 요청은 204 로 성공하면서 그 옵션만 조용히 무시된다»는 주석이 있었습니다. 주석은 다음 사람에게 조심하라고 말할 수는 있지만, 빠뜨린 코드를 멈춰 세우지는 못합니다. 옮길 방향은 손으로 옮겨 적기를 없애거나, 빠뜨리면 컴파일이 멈추게 만드는 것입니다. 아직 옮기지 않았고, 아래는 방향을 보여 주는 예시입니다.

typescript
type AllKeys<T> = { [K in keyof Required<T>]: T[K] };

interface UpdateSettingsDto {
  theme?: 'light' | 'dark';
  language?: string;
  weeklyDigest?: boolean;
}

function toServiceInput(dto: UpdateSettingsDto): AllKeys<UpdateSettingsDto> {
  return {
    theme: dto.theme,
    language: dto.language,
  };
}

옵션은 여전히 선택이라 값은 undefined 일 수 있지만, 키는 하나도 빠질 수 없습니다. 위 코드는 weeklyDigest 를 빠뜨렸기 때문에 TypeScript 5.9 의 strict 설정에서 TS2741(«Property 'weeklyDigest' is missing…») 오류로 컴파일되지 않습니다. 주석이 사람에게 부탁하던 확인을 컴파일러가 대신하게 됩니다.

가장 많은 것은 test 였습니다. 929개 중 675개, 73% 입니다. «자르고 나서 escape 한다», «marketing 은 의도적으로 빠져 있다 — 선택 동의라 미동의로도 가입이 되어야 한다», «한 항목당 열린 행(effective_to IS NULL)은 최대 1개 — 이 테이블의 핵심 불변식» 같은 문장은 모두 «이렇게 동작해야 한다»는 불변식이고, 불변식은 테스트로 고정할 수 있습니다.

나머지는 주석이 문제를 고백하는 경우입니다. «백엔드 409 본문에 기계가 읽는 code 가 없어 서버 문구의 고정 조각으로 가른다»는 서버가 code 를 실으면 사라질 주석이고(handle-error), «단순화를 위해 LFU 는 LRU 로 폴백»은 옵션이 조용히 다른 동작으로 떨어진다는 고백입니다(open-work).

지우고 표시하는 대신, 옮기면서 지우기로 했습니다

원문의 Comment Sicko 는 주석을 지우고 심볼에 MUST KILL 을 표시합니다. 코드로 옮기는 일은 그다음입니다. 이번에는 MUST KILL 929개를 첫 단계에서 지우지 않았습니다. 그 주석이 설명하던 불변식은 코드로 옮겨지기 전까지 다른 어디에도 없습니다. 지우는 단계와 옮기는 단계 사이에 지식이 비는 구간이 생기는데, 레포 전체 규모에서는 그 구간이 길어질 수 있습니다. 그래서 «코드로 옮기는 커밋에서 그 주석을 함께 지운다»로 바꿨습니다. /no-comments 가 제약 주석에 두는 «인코딩한 뒤 지운다»는 순서를 MUST KILL 전체에 적용한 셈입니다.

test 종류 675개는 기존 테스트가 그 불변식을 이미 고정하고 있는지부터 찾습니다. 있으면 테스트를 새로 쓰지 않고 주석만 지운 뒤, 그 테스트의 이름을 근거로 남깁니다.

정리하면, 우리 코드의 의외성을 설명하던 주석은 지우는 것으로 끝나지 않고, 그 주석이 지키던 것을 이름·추출·타입·테스트가 지키도록 옮겨야 합니다. 이번 판정에서는 그 73% 가 테스트로 옮길 불변식이었고, 옮기기 전에 지우면 지식이 비는 구간이 생기므로 옮기는 커밋에서 함께 지우기로 했습니다. 남길 주석 다섯 종류의 기준과 1차 판정 결과, 남긴 외부 제약이 서로 반대를 말하던 mysql2 사례는 «코드 주석은 다섯 종류만 남깁니다»에 적었습니다.