CLAUDE.md / AGENTS.md 에 항상 추가하는 『철판 5줄』— AI 출력 품질을 높이는 실용 템플릿

최근 Zenn의 트렌드에서 "단 몇 줄로 코드 품질이 확 올라가는, CLAUDE.md / AGENTS.md 에 항상 추가하고 있는 것"이 화제가 되고 있었습니다.

우리 팀에서도 모든 프로젝트의 CLAUDE.md에 반드시 넣고 있는 철판 5줄이 있습니다.

이 5줄을 넣는 것만으로 Claude Code (또는 Codex)의 출력 품질이 체감상 30~50% 달라집니다.

이 기사에서는 그 5줄과 "왜 그것을 넣는지"에 대한 이유를 공유합니다.

## 철칙
- 실행하기 전에 「무엇을 하려고 하는지」를 1줄로 선언한 뒤 착수할 것
- 기존의 코드 규약·명명(Naming)·의존 관계를 반드시 먼저 확인한 뒤 작성할 것
...

이것을 CLAUDE.md의 서두나, 혹은 ## 철칙 섹션에 넣습니다.

각 줄의 의도를 차례대로 설명하겠습니다.

- 실행하기 전에 「무엇을 하려고 하는지」를 1줄로 선언한 뒤 착수할 것

목표: AI가 "생각나는 대로 구현을 시작하는 것"을 방지.

복잡한 태스크(Task)를 의뢰했을 때, AI가 절차를 정리하지 않고 갑자기 편집을 시작하면, 나중에 "어라, 무엇을 의도했었지?"라며 방향이 흔들립니다.

선언을 강제함으로써, 자신과 AI 모두 "이제부터 무엇을 할 것인가"에 대한 합의가 이루어진 뒤에 착수하는 흐름이 됩니다.

- 기존의 코드 규약·명명(Naming)·의존 관계를 반드시 먼저 확인한 뒤 작성할 것

목표: 새로운 명명 규칙이나 새로운 라이브러리를 멋대로 가져오는 것을 방지.

AI는 "베스트 프랙티스(Best Practice)"를 가져옵니다. 하지만 그것이 기존 코드와 일치하지 않는 경우가 많습니다.

"existing/auth.ts의 패턴에 맞춰줘"라고 매번 쓰는 것은 번거로우므로, CLAUDE.md에서 상시 규칙화합니다.

- 에러 핸들링 (Error Handling)을 작성할 수 없을 때는, 에러 발생 시 어떻게 할지 되물어볼 것

목표: AI가 "대충 try/catch로 에러를 뭉개버리는 것"을 방지.

에러 처리는 구현자의 의도를 모르면 작성할 수 없습니다. AI가 독단적으로 catch (e) { console.log(e) }를 하는 것을 방지하기 위해, **"모르면 물어봐"**라고 미리 알려둡니다.

이것만으로도 운영 환경의 장애로 이어지기 쉬운 에러 은폐가 극적으로 줄어듭니다.

- 완료되면 「한 일」 「변경한 파일」 「다음에 확인해야 할 사항」을 보고할 것

목표: AI가 "했습니다"라고만 보고하여 내용이 블랙박스가 되는 것을 방지.

매번 "한 일·변경 파일·다음 확인 사항"을 세트로 출력하게 하면, 리뷰 시에 무엇을 봐야 할지가 명확해집니다.

우리 팀에서는 이것을 철저히 함으로써 인간 리뷰 시간이 절반으로 줄었습니다.

- 불분명한 전제가 있다면, 추측해서 진행하지 말고 반드시 질문할 것

목표: AI가 "그럴듯한 추측으로 코드를 작성하는 것"을 방지.

이것이 가장 중요합니다.

AI는 추측으로 코드를 생성하는 능력이 높기 때문에, 본래 인간에게 확인해야 할 전제도 "아마 이럴 것이다"라며 진행해 버립니다.

"모르면 물어봐"를 명시해 두면, AI가 멈춰서 질문하게 되어 무의미한 구현이나 재작업이 급격히 줄어듭니다.

우리 팀에서 이 5줄을 넣은 후의 변화 (체감 기준):

항목	5줄 없음	5줄 있음
1 태스크당 리뷰 시간	30분	15분
...

숫자는 어디까지나 체감이지만, 가장 효과가 큰 투자 대비 효율이 높은 코드 품질 개선이라고 생각합니다.

이것은 Claude Code의 CLAUDE.md뿐만 아니라,

• Cursor의 .cursorrules
• Windsurf의 AGENTS.md
• GitHub Copilot의 .github/copilot-instructions.md

등 AI 도구 전반에서 동일한 사상으로 작성할 수 있습니다.

도구가 바뀌더라도, "AI가 움직여주길 바라는 철칙"을 5줄로 선언한다는 설계 사상은 재사용할 수 있습니다.

CLAUDE.md / AGENTS.md는 너무 길게 써도 효과가 옅어집니다.

가장 효과적인 이 철판 5줄:

• 착수 전 선언
• 기존 규약 우선 확인
• 에러 처리는 되묻기
• 완료 보고 포맷 고정
• 불분명한 전제는 질문

이것을 넣는 것만으로 AI 출력 품질이 체감상 30~50% 개선됩니다.

꼭 자신의 프로젝트 CLAUDE.md에도 추가해 보시기 바랍니다.

관련: 교재로 직접 실습하며 배우기

• 우선 무료로 체험하고 싶은 분: 교재 체험판을 GitHub 에서 배포 중 (git clone 하여 바로 실행 가능합니다) → https://github.com/ayies128/next-ai-camp-trial
• 전 20 세션 완전판 + 멘토링 → https://menta.work/plan/20251
• YouTube 채널 → https://www.youtube.com/channel/UC1rXVD9WYsQPQEWZyd-A1KA/