나의 CLAUDE.md를 믿었지만, WordPress.org는 방지하려고 했던 바로 그 점을 거절했다

나의 CLAUDE.md에는 그에 관한 규칙이 있었습니다. 하지만 생성된 코드는 어쨌든 그 규칙을 어겼습니다. 그리고 결국 이를 잡아낸 것은 나의 설정 파일(config file)이 아니었습니다. 바로 WordPress.org 플러그인 검토 팀의 거절이었습니다.

나는 긴 CLAUDE.md를 활용하여 플러그인을 제작해 왔습니다. 시간이 흐르면서 나는 두 개의 가이드 전체를 그 안에 통합했습니다. 하나는 내가 따르는 WordPress 일본어 번역 스타일 규칙이었고, 다른 하나는 당신이 구체적으로 하지 말아야 할 사항들을 포함한 나만의 플러그인 설계 관례(design conventions)였습니다. 파일은 길어졌습니다. 그리고 파일이 길어질수록 나는 더 안전하다고 느꼈습니다. 기록되어 있으니, 지켜질 것이라고 생각했습니다. 그것이 나의 가정이었습니다. 그리고 나는 단 한 번도 그 가정을 의심하지 않았습니다.

그러다 나는 유료 기능이 제한되는 방식과 관련하여 trialware(체험판 소프트웨어) 형태를 띤 코드가 포함된 플러그인을 출시했습니다. 이는 WordPress.org 디렉토리 가이드라인이 거부하는 유형이었고, 나의 설계 가이드가 에이전트(agent)에게 명시적으로 피하라고 지시했던 바로 그 종류였습니다. 규칙은 파일에 분명히 적혀 있었습니다. 하지만 생성된 코드는 어쨌든 그 규칙을 밟고 지나갔고, 나는 거절 통보가 돌아올 때까지 이를 알아차리지 못했습니다.

그 거절은 유용한 역할을 했습니다. 그것은 설정 파일에 대한 나의 신뢰를 뒤집어 놓았습니다. 규칙을 작성한 것은 나였습니다. 하지만 나는 그 규칙이 실제로 적용되고 있는지 확인한 적이 없었습니다. 그리고 나의 가이드가 제대로 작동하는지 최종적으로 채점한 것은 나의 가이드가 아니었습니다. 몇 주 후, 반대편에 있던 검토자였습니다.

기록된 것이 실행되는 것과 같지는 않다

여기 우리 대부분이 작동한다고 믿는 가정이 있습니다. 설정 파일은 작성한 뒤에 믿으면 되는 것이라는 생각입니다. '기록됨'은 곧 '준수됨'과 같다는 것이죠. 하지만 긴 지시 파일은 실제로 그렇게 작동하지 않습니다. 파일이 길어지는 순간부터 그 효과는 새기 시작합니다. 이에 대해 잘 쓰인 글이 최근에 나왔는데, 수천 줄에 달하는 거대한(monolithic) CLAUDE.md는 두 가지 문제를 동시에 일으킵니다. 에이전트는 작업 내용과 상관없이 그 모든 내용을 처리하며, 아무도 이를 완전히 책임지지 않기 때문에, 각 섹션에는 부채(debt)가 쌓이게 되고 결국 모두가 참조하지만 아무도 진정으로 신뢰하지 않는 파일이 되어버립니다. 나는 정확히 그 내용을 읽고 고개를 끄덕였지만, 그럼에도 계속해서 줄을 추가했습니다. 추가하는 것은 쉽고, 아무도 삭제하라고 말해주지 않기 때문입니다.

규칙이 준수되지 않게 되는 두 가지 방식, 둘 다 조용히 일어난다

설정 규칙 (config rule)이 무용지물이 되는 데에는 두 가지 방식이 있으며, 두 방식 모두 조용히 진행됩니다. 첫 번째는 길이입니다. 규칙은 그곳에 존재하고 읽히기도 하지만, 모델의 주의력 (attention)을 얻기 위해 수천 개의 다른 줄과 경쟁하는 단 한 줄에 불과하기 때문에 결과물에 영향을 미치지 못하게 됩니다. 두 번째는 드리프트 (drift)입니다. 당신의 컨벤션 (conventions)은 변화하지만, 파일은 여전히 에이전트 (agent)를 과거의 규칙으로 유도하여, 어제의 관행을 매우 확신에 차서 생성하게 만듭니다. 당신의 관점에서는 두 가지 모두 동일해 보입니다. 규칙은 작성되어 있고, 당신은 그것을 직접 가리킬 수도 있습니다. 하지만 그것은 아무런 역할도 하지 않고 있습니다.

그 부분이 제가 거꾸로 알고 있었던 지점이었습니다. 저는 충분히 세심하게 작성된 설정 파일 (config file)이라면 신뢰할 수 있는 것이라고 생각했습니다. 하지만 그럴 수 없습니다. 설정 파일은 스스로의 효과를 증명할 수 없기 때문입니다. 규칙이 살아있는지에 대한 증거는 결코 파일 자체에서 나오지 않습니다. 그것은 파일 외부에서 옵니다. 즉, 테스트 (test)나 누락된 것을 잡아내는 리뷰 (review)를 통해서입니다. 저의 CLAUDE.md는 trialware 규칙이 조용히 중요성을 잃었다는 사실을 제게 말해줄 수 없었습니다. 오직 거절 (rejection)만이 그 사실을 알려줄 수 있었습니다.

이제 신뢰하는 대신 내가 하는 일

그래서 저는 신뢰할 수 있는 설정 파일을 만들려고 노력하는 것을 멈추고, 대신 제가 가진 설정 파일이 여전히 유효한지 측정하려고 노력하기 시작했습니다.

실제로 이는 몇 가지 작은 변화를 의미합니다. 저는 설정 파일이 편안하게 느껴질 정도로 길어지지 않게 유지하며, 한 줄을 추가하는 것을 무료 안전망이 아닌 하나의 비용으로 취급합니다. 왜냐하면 제가 추가하는 모든 줄은 이미 주의를 끌기 위해 싸우고 있는 기존의 줄들을 희석시키기 때문입니다. 저는 파일 상단에 소유자와 마지막 검토 날짜와 같은 약간의 메타데이터 (metadata)를 넣습니다. 이는 에이전트 (agent)를 위한 것이라기보다, 특정 섹션이 오래되어 쓸모없게 되었는지 알아야 할 6개월 뒤의 저를 위한 것입니다. 그리고 거부당할 수도 있는 디렉토리 가이드라인 (directory guideline)처럼 실제로 중요한 사항에 대해 규칙에 의존하기 전에, 저는 새로운 세션 (session)을 열고 에이전트에게 현재 어떤 컨벤션 (conventions)이 유효하다고 생각하는지 묻습니다. 그런 다음 그 목록을 읽으며 사라진 것들을 찾아냅니다. 이 중 어떤 것도 파일에 대한 신뢰를 회복시켜 주지는 않습니다. 그저 계속해서 확인을 유지할 수 있는 방법을 제공할 뿐이며, 이것이 실제로 유일하게 효과가 있었던 방법임이 드러났습니다.

다음의 나에게 남기는 메모

설정 파일은 보기만큼 많은 정보를 담고 있지 않습니다. 당신을 안전하게 느끼게 만드는 길이는 당신이 의지하고 있는 단 하나의 규칙을 희석시키는 것과 같은 길이이며, 당신은 그것이 일어나는 것을 느끼지 못할 것입니다. 다음 줄을 추가하기 전에, 마지막 줄이 여전히 제 역할을 하고 있는지 확인하십시오.

설정 파일은 작성하고 나서 신뢰하는 대상이 아닙니다. 그것은 오직 당신의 마지막 확인만큼만 유효합니다. 저의 파일은 생각보다 가벼웠고, 낯선 이의 검토를 받고 나서야 그 사실을 알게 되었습니다.

단일 파일 문제 (monolithic-file problem), 컨텍스트 드리프트 (context drift), 그리고 설정 파일 메타데이터 (config-file metadata)에 관한 배경 지식: Packmind의 2026 컨텍스트 엔지니어링 (context-engineering) 가이드. 경험과 거절은 저 개인의 것입니다.