Tailwind CSS 는 소스 파일을 언어로 파싱하지 않고 텍스트로 훑어, 클래스 이름이 될 만한 문자열을 모읍니다. 그래서 주석에 적힌 낱말도 CSS 규칙이 됩니다. 코드 주석 4만 5천여 개를 지운 커밋의 앞뒤로 앱 6개의 생성 CSS 를 비교해 보니, 앱별로 세어 유틸리티 30개가 빠져 있었습니다.

앞 글 「코드 주석은 다섯 종류만 남깁니다」에서, 주석을 지운 결과가 «주석 말고는 같다»는 것을 TypeScript 구문 트리(AST)로 비교하는 검증기를 만든 이야기를 적었습니다. 그 뒤 실제로 JS/TS 주석 45,042개를 지웠고, 검증기는 이번에도 제 몫을 했습니다. 그런데 그 증명이 원리적으로 닿지 않는 축이 하나 있었습니다. 이 글은 그 축에 대한 기록입니다. 어떤 원리가 무엇을 예측했고, 실제 결과가 어디서 어긋났고, 화면에 영향이 없다는 것을 무엇으로 확인했는지를 차례로 적었습니다.

먼저 밝혀 둘 것이 있습니다. 앱 6개는 모두 tailwindcss 3.4.17 을 쓰고, 아래의 비교는 2026년 11월 1일 이 글을 쓰며 다시 돌려 같은 30개를 재현한 결과입니다. Tailwind v4 를 쓰는 앱은 이번 비교에 넣지 않았습니다. 그리고 «화면 영향은 없었다»는 결론은 이번 30개를 하나씩 확인한 결과이지, 원리상 보장되는 것이 아닙니다. 삭제와 비교를 실제로 돌린 것은 코딩 에이전트였지만, 여기서 다룰 것은 그 방법과 결과입니다.

주석을 지워도 «동작이 같다»는 무엇으로 증명했나

주석을 지운 커밋의 증명은 두 겹이었습니다. 첫째는 검증기입니다. 변경 전후 파일을 각각 AST 로 파싱해, 주석과 의미 없는 차이를 정규화한 노드 열을 비교합니다. 2,683파일 중 2,666파일이 PASS 였고, FAIL 17파일은 모두 의도한 변경이었습니다. 둘째는 컴파일 산출물입니다. 백엔드를 tsc --removeComments 로 컴파일한 결과는 2,352파일 중 2,348파일이 바이트까지 같았고, 나머지 4파일은 공백·괄호·끝 쉼표만 달라서 정규화하면 같았습니다.

JS 런타임이 같다는 데에는 이것으로 충분하다고 생각했습니다. 그래서 PR 코멘트에 처음에는 «화면에 나가는 결과가 같다»고 적었습니다. 돌이켜 보면 증명의 범위를 한 칸 넓혀 읽은 문장이었습니다. 검증기가 본 것은 JS 의 구문입니다. 화면에 나가는 결과에는 JS 말고도 CSS 가 있고, 그 CSS 를 만드는 도구가 무엇을 입력으로 읽는지는 묻지 않았습니다.

머지 직전의 검증 단계는 기준과 헤드 두 시점에서 각 앱의 실제 Tailwind 설정으로 CSS 를 만들어 비교했습니다. 앱 6개가 모두 달랐습니다. PR 코멘트의 그 문장은 생성 CSS 에 대해서는 틀렸다고 정정했습니다.

Tailwind CSS 의 클래스 감지는 소스를 텍스트로 훑습니다

Tailwind v3 가 클래스를 감지하는 방식은 공식 문서에 설명되어 있습니다. 요지는 이렇습니다. Tailwind 는 설정의 content 글롭에 걸린 파일을 열되, 그 파일을 JS 나 HTML 로 파싱하지 않고 평범한 텍스트로 봅니다. 그리고 정규식으로 클래스 이름이 될 수 있는 문자열을 모두 뽑은 뒤, 그중 실제 유틸리티에 해당하는 것의 CSS 만 만듭니다. 문서가 함께 적어 두는 주의도 같은 원리에서 나옵니다. text-${color}-500 처럼 문자열을 조립해 만든 클래스는 소스에 완성된 모양으로 존재하지 않으므로 감지되지 않는다는 것입니다.

이 원리를 뒤집어 보면, 완성된 모양의 텍스트로 존재하기만 하면 어디에 있든 감지된다는 뜻이 됩니다. 문자열 리터럴이든 주석이든 산문이든 가리지 않습니다. 그래서 효과가 두 방향으로 생깁니다.

  • 주석에만 적힌 클래스도 CSS 가 생성됩니다.
  • 그 주석을 지우면 그 CSS 가 사라집니다.

AST 검증기는 주석을 «의미 없는 것»으로 빼고 비교합니다. JS 엔진에게는 맞는 말입니다. 하지만 Tailwind 에게 주석은 입력의 일부였습니다. 같은 파일을 두 도구가 서로 다른 문법으로 읽고 있었고, 검증기는 그중 한쪽의 문법으로만 «같다»를 증명했던 셈입니다.

Tailwind 생성 CSS 비교 — 앱 6개에서 앱별로 세어 30개가 빠졌습니다

비교 방법은 단순합니다. 주석 삭제 직전과 직후 두 커밋에서 앱 6개의 디렉터리만 git archive 로 꺼내고, 같은 node_modules 를 링크한 뒤 앱마다 Tailwind CLI 로 CSS 를 만들어 바이트로 비교합니다. 다르면 규칙 단위로 비교해 «기준에는 있고 헤드에는 없는 클래스»를 뽑습니다.

plaintext
# 앱 하나에 대해, 기준·헤드 두 커밋에서 각각
1. git archive <커밋> <앱 디렉터리> 로 트리를 임시 폴더에 꺼낸다
2. 같은 node_modules 를 링크한다 (의존성 차이를 없애기 위해)
3. tailwindcss -i <입력 css> -o <출력 css> --minify

# 그다음
4. 두 출력 CSS 를 바이트 비교한다
5. 다르면 규칙 단위로 비교해 빠진 클래스를 뽑는다

5단계의 규칙 비교는 PostCSS 로 선택자를 모으면 됩니다. 아래는 그 단계만 옮긴 최소한의 스크립트이고, 실제 비교에 쓴 도구 그대로는 아닙니다. 미디어 쿼리 안의 규칙은 같은 선택자라도 구간마다 따로 세도록 바깥 at-rule 을 키에 붙였습니다.

javascript
// rules-diff.mjs — 사용법: node rules-diff.mjs base.css head.css
import { readFileSync } from 'node:fs';
import postcss from 'postcss';

function ruleKeys(file) {
  const keys = new Set();
  postcss.parse(readFileSync(file, 'utf8')).walkRules((rule) => {
    const media =
      rule.parent?.type === 'atrule' ? `@${rule.parent.name} ${rule.parent.params} ` : '';
    keys.add(media + rule.selector);
  });
  return keys;
}

const [baseFile, headFile] = process.argv.slice(2);
const base = ruleKeys(baseFile);
const head = ruleKeys(headFile);

console.log(`base ${base.size} rules / head ${head.size} rules`);
[...base].filter((k) => !head.has(k)).forEach((k) => console.log(`- ${k}`));
[...head].filter((k) => !base.has(k)).forEach((k) => console.log(`+ ${k}`));

앱 이름 대신 A~F 로 적은 결과입니다.

앱기준 규칙헤드 규칙빠진 클래스
A1,3401,3382
B1,2141,2113
C7187121 (container — 규칙은 6개가 빠짐)
D5695681
E1,1381,11622
F1181171

가장 많이 빠진 앱(E)에서는 22개가 빠졌고, 그 앱의 CSS 파일은 minify 기준 68,470바이트에서 67,424바이트로 줄었습니다. C 앱은 빠진 클래스가 container 하나였지만, 규칙은 6개가 빠졌습니다.

빠진 클래스의 세 갈래

ring 은 두 앱에서 각각 빠져서, 앱별로 세면 30개이고 서로 다른 클래스로는 29종입니다. 빠진 클래스를 생김새로 나누면 세 갈래였습니다. 첫째는 주석 속의 평범한 영어 낱말이 유틸리티 이름과 같았던 경우입니다. 누군가 클래스를 쓰려던 것이 아니라, 문장을 쓰다 보니 그 낱말이 들어갔을 뿐입니다.

  • container, relative, grow, contents, ring, outline

둘째는 주석이 클래스 이름을 인용한 경우입니다. 코드를 설명하느라 주석에 적어 둔 클래스 이름이, 코드에서는 쓰이지 않는데도 규칙을 만들고 있었습니다.

  • outline-lilac-600, font-sans, z-skip-link, aspect-[4/5], backdrop-filter, hover:opacity-90, left-1
  • lg:inset-y-0, lg:pl-2, lg:right-[calc(5rem+22rem)], lg:grid-cols-[minmax(0,1fr)_minmax(0,22rem)]
  • max-w-6xl, mt-auto, py-8, py-[6px], right-20, right-[-60px], ring-offset-2, text-[12px], xl:right-20, z-editor-sticky

셋째가 가장 이상했습니다. 주석의 말줄임이 깨진 규칙을 만든 경우입니다. 기준 CSS 에 실제로 들어 있던 것은 이렇습니다.

css
.top-\[calc\(\.\.\.\)\] { top:calc(...) }
@media (min-width:1024px) { .lg\:grid-cols-\[\2026\] { grid-template-columns:… } }

\2026 은 말줄임표(…)를 CSS 선택자 안에서 이스케이프한 모양입니다. 원래 주석은 «띠의 sticky 산수(top-[calc(...)]·-mt-6·pt-8)는 손대지 않았다» 같은 산문이었습니다. 사람에게는 «긴 식을 줄여 적었다»는 뜻이었지만, Tailwind 에게는 arbitrary value 를 담은 클래스 하나였습니다. calc(...) 도 … 도 유효한 값이 아니니 브라우저는 이 선언을 무시합니다. 아무 일도 하지 않는 유효하지 않은 CSS 가 운영 번들에 실려 나가고 있었던 것입니다.

주석은 이미 알고 있었습니다

찾아 들어가 보니 조금 아이러니한 주석이 둘 있었습니다.

하나는 어떤 파일이 왜 유틸리티 폴더가 아니라 컴포넌트 폴더 아래에 있는지를 설명하는 주석이었습니다. 요약하면 이렇습니다. Tailwind 설정의 content 글롭은 컴포넌트와 앱 라우트 디렉터리만 가리킨다. 그러니 이 파일을 유틸리티 폴더에 두면 여기 적힌 arbitrary 클래스(lg:grid-cols-[…])의 CSS 가 아예 생성되지 않는다. 빌드·타입·린트가 전부 통과하고 화면만 조용히 1컬럼으로 무너지는 종류의 실패다. Tailwind 의 스캔 범위를 정확히 아는 주석이었습니다. 그런데 그 주석 자체가 lg:grid-cols-[…] 라는 깨진 규칙을 만들고 있었습니다.

다른 하나는 e2e 테스트의 주석이었고, 과거의 사고를 기록하고 있었습니다. 문서 주석만 16/9 로 고치고 실제 className 은 aspect-[4/5] 로 남긴 채 커밋된 적이 있는데, tsc·eslint·next build 가 모두 통과했다는 것입니다. 빌드 결과물에서 aspect-[4/5] 를 grep 해도 «Tailwind JIT 이 주석 안의 클래스명까지 발행해 여전히 잡힌다»고 적혀 있었습니다. 그래서 그 테스트는 클래스가 아니라 렌더된 상자의 크기를 잽니다.

이 현상을 저는 이미 한 번 겪었고, 기록까지 해 두었습니다. 그런데도 주석을 대량으로 지울 때의 검증 계획에는 들어가지 않았습니다.

빠진 클래스가 화면에 영향을 주는지 어떻게 확인했나

CSS 규칙이 빠졌다고 화면이 바뀌는 것은 아닙니다. 그 클래스를 실제로 쓰는 곳이 있을 때만 바뀝니다. 그래서 확인할 질문은 «빠진 30개를 지금 무엇이 쓰고 있는가»였습니다.

먼저 코드입니다. 헤드의 코드에서 빠진 클래스를 찾았습니다. Tailwind 의 스캔 대상 밖 파일, 공용 타입 패키지, 에디터 패키지까지 포함했습니다. 문자열 리터럴 안의 토큰으로만 센 엄격한 검색과 코드 어디서든 찾는 느슨한 검색을 따로 돌렸고, 사용처는 0건이었습니다. 동적으로 조립되는 클래스와도 겹치지 않았습니다.

다음은 DB 에 저장된 HTML 입니다. 블로그 글 본문처럼 DB 의 HTML 이 클래스를 쓸 수 있기 때문입니다. 블로그 두 곳의 글 HTML 에서는 0건이었습니다. 다른 두 앱은 운영 DB 를 읽기 전용 세션(transaction_read_only=1)으로 훑었습니다. 테이블 66개의 텍스트 열 358개, 301행이었고, 빠진 클래스는 느슨한 부분 일치로도 0건, class= 나 className 형태를 담은 행도 0건이었습니다.

0건이라는 결과는 검색이 실제로 작동할 때만 의미가 있습니다. 그래서 같은 경로로 반드시 있는 값(밑줄·대괄호·괄호)을 찾는 양성 대조(positive control)를 함께 돌렸고, 이쪽은 검출되었습니다. 그 두 앱에는 DB 값을 HTML 로 그리는 곳도 없었습니다.

확인하지 못한 것도 적어 둡니다. 서드파티 라이브러리가 실행 중에 붙이는 클래스는 확인하지 않았습니다. 이 경로만 미확인으로 남기고 화면 평가는 생략하기로 했는데, 그 판단은 제가 내리고 승인했습니다. 바이너리 열 2개도 훑지 않았습니다. 그래서 결론은 이렇습니다. 이번 30개는 모두 «주석에만 있던 것»이어서 화면 영향이 없었습니다. 다만 이것은 확인한 결과이지, 주석 삭제가 원리상 화면을 바꾸지 않는다는 보장은 아닙니다.

그 뒤 바꾼 것

레포의 주석 정책 문서에 한 문장을 더했습니다. 주석 삭제 검증기는 Tailwind 가 주석까지 훑는 점을 보지 못하니, Tailwind 를 쓰는 앱의 파일에서 주석을 지웠으면 그 앱의 생성 CSS 를 기준 커밋과 비교한다는 내용입니다.

그 뒤 주석을 코드로 옮기는 후속 작업들은 매번 앱 6개의 CSS 를 비교했습니다. 바이트까지 같았던 적이 한 번, E 앱의 규칙이 1,116개에서 1,116개로 같고 사라진 클래스가 0개였던 적이 한 번 있었고, 그 결과를 PR 에 남겼습니다. 비교 도구(트리 추출·CSS 생성·차이·사용처 찾기·DB 스캔)는 레포에 커밋하지 않고 작업 폴더에만 두었고, 다시 만드는 방법을 문서에 적었습니다.

Tailwind v4 를 쓰는 앱은 설정 파일 없이 동작하는 구성이라 이 비교 도구의 대상에서 빠져 있습니다. v4 에서도 같은 일이 일어나는지는 이번에 재 보지 않았습니다.

정리 — 주석을 입력으로 읽는 도구가 있는가

이번 일에서 가져갈 것을 적어 보면 이렇습니다.

  • «동작이 같다»의 증명은 그 도구가 보는 축에서만 유효합니다. JS AST 는 CSS 생성기의 입력을 보지 않습니다. 주석을 입력으로 쓰는 도구(Tailwind, 번들러의 매직 주석, 문서 생성기 등)가 있으면 그 산출물도 비교해야 합니다.
  • Tailwind 프로젝트에서 주석에 적은 클래스는 실제로 CSS 가 됩니다. 반대로 «주석에만 있어서 살아 있던» 스타일이 있을 수 있으니, 대량으로 주석을 정리하기 전에 생성 CSS 를 비교합니다.
  • 빌드 결과물을 grep 해서 «이 클래스가 적용됐나»를 보는 방식은 주석 때문에 거짓 양성이 날 수 있습니다. 계산된 스타일이나 상자의 크기처럼 렌더된 결과로 잽니다.
  • 큰 단위의 변경을 검증할 때는 «이 변경을 입력으로 읽는 다른 도구가 있는가»를 묻습니다.

돌이켜 보면 검증기는 틀리지 않았습니다. 검증기가 증명한 것을 제가 더 넓게 읽었을 뿐입니다. 주석은 실행되지 않는다는 말은 JS 엔진 앞에서만 참이었고, 같은 파일을 다른 문법으로 읽는 도구 앞에서는 주석도 코드였습니다. 증명을 하나 손에 쥐었을 때, 그것이 무엇에 대한 증명인지를 한 번 더 물어야겠다는 생각이 들었습니다.