Claude Code를 한 달간 사용하며 깨달은 「지시 개선만으로는 해결되지 않는 문제」

TL;DR

Claude Code를 깊게 사용하다 보면, 「프롬프트(Prompt)를 개선하는」 접근 방식에 한계를 느끼는 순간이 있다. 그 한계를 돌파하는 것이 「하네스 엔지니어링(Harness Engineering)」이라는 사고방식이다.

이 기사에서는 내가 실제로 경험한 한계와, 이를 해결한 구체적인 설정 방법을 소개한다.

같은 실수가 반복되는 문제

Claude Code를 사용하기 시작하며 처음 느낀 불만은 「같은 실수가 반복된다」는 것이었다.

예를 들어:

• 커밋 메시지(Commit message)를 매번 「[feat] 〜」 형식으로 부탁하는데, 가끔 영어로 커밋해 준다.
• 「.env는 커밋하지 마」라고 말했는데, git add 후에 .env가 포함되어 있었다.
• 이전 세션에서 「이 API의 사용법은 이렇다」라고 확인했는데, 다음 세션에서 또 틀린다.

이것들을 해결하려고 「프롬프트를 더 정중하게 작성하기」를 시도했다. 확실히 개선은 되지만, 완벽해지지는 않는다. 긴 프롬프트를 작성할수록 다른 중요한 지시사항이 희석된다.

해결책은 프롬프트가 아니라 파일

전환점은 「CLAUDE.md에 규칙을 작성한다」는 것을 발견했을 때다.

# CLAUDE.md
## 커밋 메시지
형식: [타입] 설명 (예: [feat] 로그인 기능 추가)
...

이것을 프로젝트 루트(Project root)에 두는 것만으로, Claude가 매번 자동으로 읽어들인다.

매번 설명할 필요가 없다. Claude가 「그런 환경」이라고 인식하고 움직인다.

5분 만에 설정할 수 있는 최소한의 CLAUDE.md

이하를 복사하여 ~/.claude/CLAUDE.md

(글로벌 설정)에 두는 것만으로 효과가 나타난다:

# Claude Code 글로벌 설정
## 응답 언어
일본어로 답변한다.
...

「이것을 삭제하면 Claude가 틀릴까?」

CLAUDE.md에 무엇을 쓸지 판단하는 심플한 기준이 있다.

「이 줄을 삭제하면 Claude가 틀릴까?」

답이 Yes라면 작성한다. 답이 No(Claude가 코드로부터 추측할 수 있음)라면 작성하지 않는다.

후보	삭제하면 틀리는가	작성해야 하는가
git push 금지	Yes (코드에서 추측 불가)	✅
TypeScript를 사용	No (기존 코드에서 명확함)	❌
.env를 git에 추가하지 않음	Yes (암묵적인 운용 규칙)	✅
함수명은 카멜 케이스(Camel case)	No (기존 코드를 따름)	❌

더 깊게 사용하고 싶은 분들에게

CLAUDE.md는 하네스 엔지니어링의 입구에 불과하다.

더 고도화된 설정으로서:

• hooks/: 세션 종료 시 자동으로 요약(Summary)을 생성한다.
• skills/: /git-management로 매번의 Git 조작을 자동화한다.
• agents/: Evaluator 에이전트로 코드의 버그를 CI보다 먼저 검출한다.

이것들을 체계적으로 해설한 유료 Book 「Claude Code 하네스 엔지니어링 실전 Playbook」을 Zenn에서 공개하고 있습니다.

→ [링크를 나중에 추가]

요약

• 「같은 실수가 반복되는」 문제는 프롬프트 개선으로 해결되지 않는다.
• CLAUDE.md에 규칙을 작성하면 매번 자동으로 읽힌다.
• 「이 줄을 삭제하면 Claude가 틀릴까?」가 작성할 내용을 판단하는 기준이다.
• 이것이 하네스 엔지니어링의 입구다.

좋아요나 댓글로 반응해 주시면 힘이 됩니다!