업무에서 Claude Code를 매일같이 사용하고 있습니다.

코드 조사나 버그 원인 규명은 상당히 우수해서, 솔직히 이제 없어서는 안 될 존재입니다.

하지만 딱 한 가지 곤란한 점이 있었습니다.

돌아오는 설명이 어렵다.

전문 용어와 가타카나(외래어)가 나열된, 아마도 맞는 말을 하고 있는 문장.

하지만 이를 해석하는 데 시간이 걸려서, 결국 스스로 코드를 다시 쫓아가며 확인하게 됩니다. 그러면 무엇을 위해 물어봤는지 알 수 없습니다.

매번 "더 쉽게 설명해 줘"라고 부탁하는 것도 번거롭기 때문에, CLAUDE.md에 설명 방식에 대한 규칙을 적어두기로 했습니다.

Claude Code가 세션 시작 시 자동으로 읽어들이는 지시 파일입니다. "매번 말로 하는 부탁"을 두는 장소라고 생각하시면 됩니다.

이번 규칙은 "내가 읽기 편한가"라는 개인적인 취향의 문제이며, 프로젝트를 불문하고 적용되기를 바라기 때문에, 모든 프로젝트에 적용되는 ~/.claude/CLAUDE.md에 두고 있습니다.

# 설명 방식
- 가능한 한 평이한 언어로 설명한다. 전문 용어·가타카나(외래어)는 피하거나, 사용할 때는 한마디로 바꾸어 설명하는 내용을 덧붙인다.
- 결론을 먼저, 짧은 문장으로. 긴 서론이나 에둘러 표현하는 방식은 하지 않는다.
...

포인트는 "전문 용어를 금지하는 것"이 아니라 "사용한다면 바꾸어 설명하는 내용을 덧붙이게 하는 것"입니다.

완전히 금지해 버리면, 이번에는 에둘러 설명하게 되어 오히려 길어집니다.

용어 자체는 사용하게 하되, 처음 등장할 때 한마디 보충 설명을 해달라고 하는 정도가 딱 적당한 밸런스였습니다.

그냥 두면 "먼저 전제를 정리하겠습니다"부터 시작하기 쉽습니다.

알고 싶은 것은 결론이므로, 먼저 말하도록 합니다.

추상적인 구조 이야기는 친숙한 것에 비유해 달라고 하면 이해하기 쉬워집니다.

이 규칙이 없었다면, 이 시도는 실패했을 것이라고 생각합니다.

단순히 "쉽게 설명해 줘"라고만 적으면, Claude는 읽기 쉬움을 우선시하여 근거를 깎아내 버립니다.

파일명도 행 번호도 사라진, 분위기만 알 수 있는 설명이 돌아옵니다.

이래서는 사실 확인을 할 수 없고, 결국 코드를 다시 쫓아가게 됩니다.

그래서 역할을 나누었습니다.

본문… 이해하기 위한 것. 평이해도 좋다 -
비고… 검증하기 위한 것. 정확해야 한다

이해하기 쉬움과 정확성은 트레이드오프 (Trade-off) 관계가 되기 쉽지만, 장소를 나누면 양립할 수 있습니다.

본문에서 "무슨 일이 일어나고 있는지"를 파악한 다음, 비고에서 코드를 확인하러 갈 수 있습니다.

이 흐름이 된 이후로, 조사 속도가 눈에 띄게 변했습니다.

좋았던 점

• 해석하는 시간이 줄었다. 그대로 이해할 수 있어서 다시 읽을 필요가 없어졌다
• "이해한 것처럼 착각하고 있는 것"을 알아차리기 쉽다. 비고의 코드를 보고 납득할 수 없다면, 사실은 이해하지 못하고 있다는 뜻이다

주의할 점

비유는 정확하지 않습니다. 어디까지나 이해를 위한 입구로 사용하고, 최종적인 판단은 반드시 비고의 코드를 확인한 뒤에 수행한다는 전제를 깨뜨리지 않도록 하고 있습니다 -

• 규칙은 짧게 유지하는 것이 요령입니다. 공식 문서에서도 지시는 구체적이고 간결할수록 일관되게 지켜진다고 되어 있습니다. 이것저것 덧붙이면 지켜지기 어려워집니다
• 적용되지 않는다고 느껴지면, /memory 명령어로 어떤 파일이 읽히고 있는지 확인할 수 있습니다

만약을 위해 적어두자면, 이것은 "어려운 것을 이해하지 않아도 되게 만드는" 시도가 아닙니다.

오히려 반대로, 이해에 착수하기까지의 시간을 단축하기 위한 보조입니다.

평이한 설명은 어디까지나 입구이며, 최종적으로는 비고의 코드를 읽고, 용어의 의미를 스스로 찾아보며, 완전히 납득(腹落ち)할 필요가 있습니다.

비유만으로 납득하고 끝내 버리면, 다음에 비슷한 문제가 나왔을 때 아무것도 남지 않습니다.

실제로 비유를 통해 "알 것 같다"고 생각한 뒤에 비고를 읽고, 전혀 모르고 있었다는 것을 깨닫는 일도 흔히 있습니다.

그럼에도 불구하고, 입구가 낮다는 것에는 가치가 있다고 생각합니다.

짧은 규칙으로 매일의 해석 작업이 가벼워진다면, 시도해 볼 가치는 충분할 것입니다.