CLAUDE.md

• 항상 프로덕션 등급 (production grade)의 코드를 작성할 것.
• 절대 회귀 (regression)를 발생시키지 말 것.
  ...

세 가지 규칙.

그중 어느 것도 실행되지 않을 것입니다.

에이전트 (agent)가 게을러서가 아닙니다.

그것들은 명령 (instructions)이 아니기 때문입니다.

그것들은 규칙의 탈을 쓴 소망일 뿐입니다.

저는 방대한 규칙 라이브러리와 어떤 규칙이 실행되고 어떤 규칙이 장식처럼 놓여 있는지 확인할 수 있는 충분한 관측성 (observability)을 갖춘 환경에서 작업합니다.

그 간극은 매우 넓습니다.

대부분의 규칙은 열망처럼 읽힙니다.

몇몇은 물리 법칙처럼 읽힙니다.

많은 규칙이 유지되고 많은 규칙이 부패하는 것을 지켜본 결과, 실패는 다섯 가지 명확한 범주로 나뉩니다.

만약 당신의 에이전트가 당신의 명령을 계속 무시한다면, 당신의 규칙은 거의 확실히 이 중 하나일 것입니다.

1. 경계가 없는 열망 (Aspiration with no edge)

"철저하게 하세요." "품질 높은 코드를 작성하세요." "에러를 적절히 처리하세요."

그중 하나를 소리 내어 읽고 간단한 질문을 던져보세요.

그 규칙을 위반한다면 어떤 모습일까요?

만약 당신이 한 문장으로 대답할 수 없다면, 에이전트도 대답할 수 없습니다.

모델이 실패할 수 없는 규칙은 기분 (mood)에 불과합니다.

에이전트는 그 문장에 고개를 끄덕이고는 그냥 지나쳐 버립니다. 왜냐하면 준수해야 할 구체적인 것이 존재하지 않기 때문입니다.

이를 수정하려면 테스트 가능한 한 문장이 필요합니다. 디프 (diff)와 대조하여 예 또는 아니오로 답할 수 있는 한 줄의 문장 말입니다.

2. 트리거 부재 (No trigger)

이것은 준수하기에 충분히 구체적입니다. 하지만 여전히 실패합니다.

"새로운 인증 (auth) 패턴을 사용하세요."

언제 말입니까?

모든 파일에 적용합니까? 인증 파일에만 적용합니까? 새로운 코드에만 적용합니까? 로그인 기능을 건드릴 때만 적용합니까?

규칙의 어디에도 명시되어 있지 않으므로, 에이전트는 추측합니다.

때로는 맞게 추측하기도 하고, 때로는 그렇지 않기도 합니다.

당신은 그것을 에이전트가 신뢰할 수 없다고 읽게 됩니다.

하지만 그것은 규칙이 스스로의 발동 시점에 대해 침묵하고 있는 것입니다.

모든 실제 명령은 트리거 (trigger), 즉 그것을 깨우는 조건을 수반합니다.

그 트리거를 제거하면 규칙은 무작위로 실행되며, 이는 외부에서 보기에 규칙이 무시되는 것과 동일해 보입니다.

3. 강제성 부재 (No enforcement)

이제 당신의 규칙은 구체적이며 명확한 트리거를 가지고 있습니다.

긴 세션(long sessions)에서는 여전히 무너집니다.

오직 한 가지, 에이전트(agent)가 그것을 기억하느냐 하는 점만이 발목을 잡습니다.

세션 초기에는 규칙이 컨텍스트(context)에 신선하게 남아 있어 준수 상태가 완벽해 보입니다.

하지만 컨텍스트가 압축되고 재구축된 지 두 시간이 지나면, 그 규칙은 수백 개의 다른 정보와 경쟁하는 희미한 기억이 되어버립니다.

기억은 아무것도 강제하지 못합니다.

모델의 어텐션(attention) 속에만 존재하는 규칙은, 정작 가장 필요한 순간인 길고 지치며 중대한 결과가 걸린 세션에서 정확히 퇴화합니다.

지속 가능한 규칙에는 안전장치(backstop)가 있습니다. 실수를 감지하고 '아니오'라고 말해줄 모델 외부의 무언가가 필요합니다.

그 안전장치가 무엇인지보다는, 일단 존재한다는 사실 자체가 더 중요합니다.

4. 우선순위 없는 모순 (Contradiction with no precedence)

두 개의 규칙이 있습니다. 둘 다 옳습니다. 하지만 서로 충돌합니다.

하나는 빠르게 움직이고 변경 사항을 작게 유지하라고 합니다.

다른 하나는 모든 새로운 동작에 대해 테스트를 추가하라고 합니다.

한 줄짜리 수정 사항에서, 어느 쪽이 승리할까요?

만약 당신의 규칙에 명시되어 있지 않다면, 에이전트는 마지막으로 인지한 규칙을 따릅니다.

그것은 결정의 탈을 쓴, 불필요한 단계가 추가된 동전 던지기에 불과합니다.

모순은 괜찮습니다. 실제 시스템은 상충하는 목표를 안고 가기 마련입니다.

부족한 것은 우선순위(precedence)입니다. 커서에 어떤 규칙이 더 가깝게 위치했느냐에 따라 결정되는 것이 아니라, 매번 동일한 방식으로 결론이 나도록 명시된 순서가 필요합니다.

5. 오래된 참조 (Stale reference)

이것이 최악입니다. 왜냐하면 예전에는 작동했었기 때문입니다.

당신의 규칙은 특정 파일, 함수, 플래그, 또는 경로를 지칭합니다.

그러다 그 대상이 이동하거나, 이름이 바뀌거나, 삭제됩니다.

지침(instruction)은 그것과 함께 움직이지 않습니다.

이제 지침은 아무것도 가리키지 않거나, 더 나쁜 경우 이전 이름을 물려받은 다른 것을 가리키게 됩니다.

거짓을 말하는 규칙은 누락된 규칙보다 더 큰 피해를 줍니다.

누락된 규칙은 실패 시 개방(fail open)되어 당신이 알아차릴 수 있습니다.

하지만 오래된 규칙은 확신을 가지고 실패(fail confident)합니다. 그것은 에이전트에게 완전한 권한을 부여한 채 잘못된 대상을 향해 보내버리며, 초록색 로그는 이를 숨겨버립니다.

특정 아티팩트(artifact)를 지칭하는 모든 규칙은 작은 부채를 안고 있습니다. 해당 아티팩트가 이동할 때마다, 동일한 동작 내에서 무언가가 이를 업데이트해주지 않는 한 그 문장은 잘못된 정보로 변합니다.

이 다섯 가지를 관통하는 핵심

패턴을 날카롭게 다듬으면, 이 다섯 가지는 하나의 테스트로 수렴됩니다.

무엇이 이 규칙을 실행(fire)하게 만드는가, 그리고 실행되지 않았을 때 무엇이 이를 잡아내는가.

두 질문 모두에 답할 수 없는 규칙은 열망 (aspiration) 입니다. 이는 데모에서는 빛을 발하겠지만, 프로덕션 (production) 환경에서는 부패할 것입니다.

두 질문 모두에 답할 수 있는 규칙은 물리학 (physics) 에 더 가깝습니다. 세션이 길어지고 컨텍스트 (context) 가 부족해지며, 아무도 지켜보지 않는 상황에서도 유지됩니다.

내가 읽은 대부분의 CLAUDE.md 파일은 물리학의 탈을 쓴 90%의 열망입니다.

더 나은 문장을 만드는 것보다 정직함이 이 문제를 더 많이 해결합니다.

당신의 규칙 중 어떤 것이 실행될 수 있는지 명확히 하고, 나머지는 스스로를 위한 메모임을 인정하십시오.

스스로를 위한 메모는 괜찮습니다. 하지만 그것을 규칙이라고 부르는 순간, 무시되는 줄이 하나씩 늘어나며 파일은 서서히 아무런 의미도 갖지 못하게 됩니다.

당신의 차례

지금 바로 당신의 CLAUDE.md 또는 에이전트 규칙 (agent rules) 을 여십시오.

규칙 하나를 골라 두 가지 질문을 던져보십시오. 무엇이 그것을 실행하게 만드는가, 무엇이 실패를 잡아내는가.

그런 다음, 당신의 가장 취약한 규칙이 다섯 가지 중 어디에 해당하는지 말해 주십시오.

실제 환경에서 어떤 것이 가장 뼈아프게 다가오는지 궁금합니다. 제 라이브러리에서는 세 번째가 그렇기 때문입니다.