Claude code] 클로드 코드 오버엔지니어링 방지 부적, CLAUDE.md 문서

Claude Code 버전 업그레이드와 CLAUDE.md 글로벌 규칙 세팅

업그레이드 배경

유니티 MCP 연동 및 LSP MCP 우회연동 작업을 진행하면서 Claude Code 버전을 업그레이드했다. 기존 2.0.76에서 2.1.52로의 점프다.

2.1.X 대로 넘어오면서 체감한 변화는 다음과 같다.

긍정적 변화

• 크리티컬한 작업 미스가 줄어든 경향이 있다. 이전 버전에서 간헐적으로 발생하던 구조적 실수나 잘못된 파일 수정 같은 문제가 눈에 띄게 감소했다.
• MCP 관련 업데이트가 상당량 진행된 것으로 보인다. MCP 연동 작업이 주 목적이었기 때문에 이 부분의 개선은 업그레이드를 유지하기로 결정한 핵심 이유다.

부정적 변화

• 프롬프트에 대한 과한 가공이 여전하다. 요청하지 않은 리팩토링, 불필요한 추상화 추가, 과도한 에러 핸들링 삽입 등 오버엔지니어링 경향이 계속된다.
• 기본적인 토큰 사용량이 체감상 20~40% 증가했다. 같은 작업을 시켜도 응답이 길어지고 부연 설명이 많아졌다.

종합적으로 MCP 지원 강화와 작업 안정성 향상을 감안해 2.1.X 버전을 유지하기로 결정했다. 다만 과한 가공과 오버엔지니어링 문제는 별도로 대응이 필요했다.

CLAUDE.md에 글로벌 규칙 추가

Claude Code는 프로젝트 루트의 CLAUDE.md 파일을 통해 에이전트의 행동 규칙을 지정할 수 있다. 버전 업그레이드 후 체감한 문제들을 억제하기 위해 다음과 같은 글로벌 규칙을 추가했다.

# Global Rules

## Core Principles
- Perform the task as stated in the prompt. Do not do anything that is not requested.

## Prohibited Matters
- Do not add unsolicited refactoring, optimization, error handling, or comments.
- Do not create unnecessary abstractions, interfaces, or helper classes.
- Do not use #region or Reflection. Use asynchronous only after confirmation.
- Check before working if the scope of the change is unclear.

## How to Work
- Check and leverage existing code and fields first before adding new features.
- Briefly describe concepts changed after code work.
- During structural design and idea discussion, do not propose work before the user directs the work.

규칙의 의도를 항목별로 정리하면 다음과 같다.

Core Principles — 가장 근본적인 규칙이다. "시킨 것만 해라." Claude Code가 버전이 올라가면서 자체적으로 판단해서 추가 작업을 수행하는 빈도가 높아졌는데, 이를 원천적으로 차단하기 위한 선언이다.

Prohibited Matters — 구체적인 금지 항목이다. 요청하지 않은 리팩토링이나 최적화, 불필요한 추상화 생성을 명시적으로 금지했다. #region이나 Reflection 같은 개인적으로 사용하지 않는 기능도 여기서 차단한다. 비동기(async/await)는 유니티 환경에서 주의가 필요한 영역이므로 반드시 확인 후 사용하도록 제한했다. 변경 범위가 불명확할 때 먼저 확인하라는 항목은, 에이전트가 자의적으로 범위를 확장하는 것을 방지한다.

How to Work — 작업 방식에 대한 가이드다. 새 기능을 추가하기 전에 기존 코드와 필드를 먼저 확인하도록 했다. 코드 작업 후에는 변경된 개념을 간략히 설명하도록 하여 작업 맥락을 놓치지 않게 했다. 구조 설계나 아이디어 논의 단계에서는 사용자가 작업을 지시하기 전까지 선제적으로 작업을 제안하지 않도록 했다. 이는 토론 중 불필요한 코드 생성이나 구현 제안으로 흐름이 끊기는 것을 방지한다.