CLAUDE.md 설계에서 발견한 함정 — 「쓰면 따른다」는 착각이었다

서론

Claude Code를 사용하여 개인 개발을 하다 보면, 이런 경험을 한 적이 없으신가요?

「CLAUDE.md에 제대로 적어 두었는데도, 세션을 시작할 때마다 똑같은 말을 듣는다」

처음에는 제 작성 방식이 잘못된 것인가 생각했습니다. 그다음에는 버그인가 의심했습니다. 한동안 원인을 잘 모르는 채로 「뭐, 괜찮겠지」라며 계속 넘겨왔습니다.

이 기사는 그 「뭔가 이상한데」라는 느낌에 제대로 마주한 기록입니다.

자신의 프로젝트에 대하여

Flutter로 오프라인 AI 메모 앱을 개인 개발하고 있습니다. 특징은 AI를 모두 온디바이스 (On-device)로 구동한다는 점이며, flutter_gemma라는 패키지를 사용하여 Gemma 3 1B를 로컬 실행하고 있습니다.

Claude Code를 통한 개발 관리에는 CLAUDE.md와 TASKS.md 두 파일을 사용하고 있습니다. CLAUDE.md에 프로젝트의 규칙이나 제약을 적고, TASKS.md에서 6개의 페이즈로 나눈 태스크를 관리하는 구성입니다.

나름대로 제대로 설계했다고 생각했습니다. 그럼에도 문제는 발생했습니다.

무슨 일이 일어나고 있었나

문제의 제약은 이것입니다.

태스크를 병행하여 진행하지 말 것

CLAUDE.md에 이렇게 적어 두면, Claude가 순서대로 태스크를 수행해 줄 것이라고 생각했습니다. 그런데 실제로는 세션을 시작할 때마다 확인하는 듯한 문구가 나옵니다.

병행하여 태스크를 진행하지 않도록 지시받았습니다만, 확인해도 괜찮습니까?

오토 모드 (Auto mode)로 동작하고 있기 때문에 작업 자체가 멈추지는 않습니다. 다만, 매번 이런 문구가 경고처럼 표시되다 보니 점점 신경이 쓰이기 시작했습니다. 「이거, 제대로 기능하고 있는 건가?」 「내 작성 방식이 잘못된 건가?」 하는 불안감이 생기는 것입니다. 버그인지 사양인지 한동안 판단할 수 없는 상태였습니다.

원인 고찰

조사해 나가는 과정에서 어느 정도 원인이 보이기 시작했습니다. 단, 아래 내용은 추측을 포함합니다.

CLAUDE.md의 지시가 모두 따르는 것은 아니다

Claude Code의 거동을 분석한 HumanLayer의 리포트에 따르면, Claude Code는 세션 시작 시 CLAUDE.md의 지시 위에 다음과 같은 내부 리마인더 (Internal reminder)를 자동으로 삽입한다고 합니다.

"This context may or may not be relevant to your tasks."

(이 컨텍스트는 태스크와 관련이 있을 수도 있고 없을 수도 있습니다)

즉, CLAUDE.md에 적은 내용은 「절대로 따라야 하는 커맨드 (Command)」가 아니라, 「참고해야 할 컨텍스트 (Context)」로 취급되고 있습니다. Claude는 매번 그 지시가 현재의 태스크와 관련이 있는지 스스로 판단하고 있는 것입니다.

공식 문서에서는 프로젝트 병행 처리를 권장하고 있다

더 조사해 보니, Claude Code의 공식 문서 (Best Practices)에서는 프로젝트의 병행 처리가 명확하게 권장되는 기능임을 알 수 있었습니다.

"Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows."

즉, 제가 CLAUDE.md에 「병행하여 진행하지 말 것」이라고 적은 제약은 Claude Code 본래의 설계 사상과 정면으로 충돌했을 가능성이 있습니다. 충돌하는 제약이기 때문에 매번 「정말로 괜찮습니까?」라고 확인해 왔던 것이 아닐까 생각합니다.

깨달은 판단 기준

여기서 한 번 멈춰서 생각했습니다.

애초에 이 제약, 정말로 필요했던 걸까?

선택지는 두 가지였다고 생각합니다.

① 프로젝트 병행을 허용한다

Claude가 병행 처리에 능숙하다면, 그것을 제한했던 것은 저의 착각이었을지도 모릅니다. 개인 개발에서 컨플릭트 (Conflict) 리스크가 낮은 상황이라면, 병행 처리를 허용하는 편이 오히려 개발 속도가 빨라질 가능성이 있습니다.

② 완전 금지한다

금지하려면 어중간한 방식이 가장 좋지 않습니다. 예를 들어 다음과 같이 강한 문구로 명시할 필요가 있었다고 생각합니다.

## 반드시 지킬 것
- 태스크는 반드시 하나씩 순서대로 진행할 것
- 여러 태스크의 동시 실행은 금지
...

다만 이 방식에서도 확인 문구가 사라질지는 아직 테스트해보지 않았습니다. HumanLayer의 분석이 맞다면, 내부 리마인더(Internal Reminder)가 존재하는 한 Claude는 여전히 "이 지시가 현재 태스크와 정말 관련이 있는가?"를 계속해서 판단할 것이며, 근본적인 해결책이 되지 않을 가능성도 있습니다. 이 부분은 향후 검증할 예정입니다.

이번 실패는 금지하고 싶은 것인지 허용하고 싶은 것인지 스스로 모호한 상태에서, 막연하게 제약 사항을 작성했다는 점에 있었습니다.

"막연하게 작성한 제약"이 가장 기능하지 않는다.

이것이 이번 경험을 통해 얻은 가장 큰 깨달음입니다. CLAUDE.md는 쓰기만 하면 무조건 따르게 되는 파일이 아니라, Claude가 매번 "관련이 있는가?"를 판단한 뒤에 참조하는 파일입니다. 설계 의도가 명확하지 않으면 판단도 모호해집니다.

현상태의 구성과 운용

이 경험을 바탕으로 CLAUDE.md에 적을 것과 적지 않을 것을 정리했습니다.

CLAUDE.md에 적는 것

• 기술 스택 (Flutter, flutter_gemma, Gemma 3 1B 등)
• 디렉토리 구조와 각 폴더의 역할
• 반드시 지켜주길 바라는 규칙 (강한 어조로, 1행 1규칙)
• 개발 환경의 전제 조건

CLAUDE.md에 적지 않는 것

• 모호한 제약이나 "가급적 이렇게 해주었으면 좋겠다" 수준의 희망 사항
• 태스크 진행 방식의 세부 절차 (이는 TASKS.md의 역할)

TASKS.md의 역할

태스크 진행 관리는 TASKS.md로 완전히 분리했습니다. 6개의 페이즈(Phase)로 나누어 각 페이즈의 태스크와 진행 상태를 관리하고 있습니다. CLAUDE.md는 프로젝트의 "헌법", TASKS.md는 "작업 지시서"라는 위치를 가집니다.

이러한 분리를 통해 CLAUDE.md가 깔끔해졌고, Claude가 망설이는 상황이 줄어들었습니다.

요약

문제의 근본 원인은 아직 해결되지 않았습니다. 강한 어조로 바꾸면 확인 문구가 사라질지도 아직 테스트하지 않은 단계입니다. 다만, 이 경험을 통해 명확해진 점이 있습니다.

• CLAUDE.md의 지시가 모두 따르는 것은 아니다. Claude가 매번 "관련이 있는가?"를 판단하고 있다.
• Claude Code의 설계 사상과 충돌하는 제약일수록 확인이나 경고가 나타나기 쉽다.
• 모호한 제약을 적을 바에는, 허용할 것인지 완전 금지할 것인지를 명확히 결정한다.
• 역할이 다른 파일은 분리한다 (CLAUDE.md = 규칙, TASKS.md = 태스크 관리).

비슷한 경험을 하신 분이 있다면 꼭 댓글로 알려주세요.

Discussion