당신의 AI 설정 파일들이 서로 충돌하고 있습니다

이제 모든 AI 코딩 도구는 프로젝트에서 설정 파일(config file)을 읽어옵니다. Claude Code는 CLAUDE.md를 읽고, Codex는 AGENTS.md를 읽습니다. Cursor는 .cursor/rules/*.mdc를 읽습니다. 만약 당신이 대부분의 팀과 같다면, 각 파일은 서로 다른 시기에, 서로 다른 사람이, 서로 다른 형식으로 작성되었을 것입니다.

어떤 파일은 번호가 매겨진 단계(numbered steps)를 사용합니다. 다른 파일은 글머리 기호(bullet points)를 사용합니다. 세 번째 파일은 다른 파일들이 따르지 않는 패턴으로 표(tables)와 산문(prose)을 혼합하여 사용합니다.

이것이 단순히 외관상의 문제라고 생각할 수도 있습니다. 하지만 그렇지 않습니다.

파싱 비용 (The parsing tax)

LLM은 매 세션 시작 시 설정 파일을 파싱(parse)합니다. 파일 간에 형식 규약(format convention)이 바뀌면, 모델은 단순히 내용을 읽는 것에 그치지 않고 각 파일을 파싱하는 방법 자체를 다시 학습해야 합니다.

운전에 비유해 보겠습니다. 만약 당신이 사는 도시의 모든 거리에서 서로 다른 신호 체계를 사용한다면 — 예를 들어 Elm 거리에서는 빨간불이 정지를 의미하지만, Oak 거리에서는 초록불이 정지를 의미한다면 — 당신은 길을 찾는 대신 규칙을 해독하는 데 뇌 에너지를 소모하게 될 것입니다. CLAUDE.md는 - 글머리 기호를 사용하고, AGENTS.md는 1. 번호 매기기를 사용하며, .cursorrules는 표와 산문을 오갈 때도 똑같은 일이 발생합니다.

모델은 형식 전환(format switching)에 주의력(attention)을 낭비합니다. 실제 규칙을 따르는 데 쓰여야 할 주의력을 말입니다.

실제 수치

수개월에 걸쳐 축적된 4개의 파일로 구성된 우리의 설정 시스템은 6개 이상의 형식 스타일로 분산되어 있었습니다. 여기서는 글머리 목록, 저기서는 번호 목록, 글머리 기호가 적합한 곳에 표 사용, 일관성 없는 헤더 깊이(header depth) 등이 나타났습니다.

변경 전: 232행, 4개 파일에 걸쳐 6개 이상의 형식 스타일
변경 후: 168행, 3개 형식 스타일 (−28%)

행동 일관성(Behavior consistency)이 향상되었습니다. 규칙이 바뀌었기 때문이 아니라, LLM이 형식 파싱에 주의력을 쓰는 것을 멈추고 규칙을 따르는 데 주의력을 쓰기 시작했기 때문입니다.

세 가지 규칙

1. 모든 설정 파일에 하나의 기본 형식을 적용하세요. 글머리 기호나 번호 매기기 중 하나를 주된 형식으로 선택하고 둘 다 사용하지 마세요. 이를 CLAUDE.md, AGENTS.md, 기술 파일(skill files), 규칙 파일(rule files)에 모두 적용하세요.

2. 표는 비교 데이터용으로만 사용하세요. WMS vs WMTS vs WFS인가요? 그렇다면 표를 사용하세요. 코딩 컨벤션(coding conventions) 목록인가요? 그렇다면 글머리 기호를 사용하세요. 이들을 혼합하면 둘 다 희석되고 LLM에게 문맥 전환(context-switch)을 강요하게 됩니다.

3. 의존성 드리프트(dependency drift)처럼 포맷 드리프트(format drift)를 감사(Audit)하세요. 새로운 설정 섹션이 생겼나요? 확인하세요: 그 포맷이 나머지 부분과 일치하나요? 미리 고려하지 않았다면, 변환하세요.

여섯 번째 흔한 실수

DeployHQ의 가이드에서는 다섯 가지 실수를 나열합니다: 소설 쓰기, 도구 간 중복 작성, 자동 생성기 사용, 린터(linter)가 처리하는 규칙 포함, 업데이트 누락.

여기에 여섯 번째 실수가 있습니다: 설정 파일 전반에 걸쳐 서로 다른 포맷 스타일을 혼용하는 것입니다. 이는 다른 실수들보다 더 미묘합니다. 각 파일은 단독으로는 문제가 없어 보이기 때문입니다. 문제는 LLM이 이 파일들을 함께 읽을 때 발생하며, 매번 문맥 전환(context switch) 시마다 파싱 비용(parsing tax)을 지불하게 됩니다.

결론

코드베이스의 절반은 camelCase로, 나머지 절반은 snake_case로 작성하지는 않을 것입니다. AI 설정 파일에 대해서도 그렇게 하지 마세요. 포맷의 일관성은 미적인 문제가 아닙니다. 그것은 유일하게 중요한 독자인 LLM을 위한 성능 최적화(performance optimization)입니다.