CLAUDE.md를 프로젝트 문서처럼 관리해야 하는 이유

AI를 사용하기 시작하면서 가장 놀랐던 것은 생각보다 코드를 잘 작성한다는 점이었다.

반대로 가장 아쉬웠던 것은 프로젝트를 잘 모른다는 점이었다.

당연한 이야기다.

AI는 일반적인 코드는 잘 작성하지만 지금 우리가 만들고 있는 서비스의 맥락은 알지 못한다.

프로젝트의 구조,
팀의 규칙,
도메인 지식,
과거의 의사결정 이유.

이런 정보는 직접 알려주지 않으면 알 수 없다.

그래서 자연스럽게 CLAUDE.md를 관리하기 시작했다.

처음에는 단순한 규칙 문서였다

처음에는 정말 간단했다.

- React Query 사용
- Server Component 우선 사용
- TypeScript strict mode 유지
- 절대 any 사용 금지

이 정도만 있어도 AI의 결과물이 꽤 좋아졌다.

하지만 프로젝트가 커질수록 한계가 보이기 시작했다.

AI는 규칙은 이해했지만 왜 그런 규칙을 사용하는지는 이해하지 못했다.

## 중요한 것은 규칙보다 맥락이었다

예를 들어 아래 두 문장은 비슷해 보인다.

```md
모든 API 호출은 React Query를 사용한다.
```

```md
우리 서비스는 네트워크 상태가 불안정한 환경에서 사용된다.
캐싱과 재시도 정책을 통일하기 위해 React Query를 사용한다.
```

첫 번째는 규칙이다.

두 번째는 의사결정의 배경이다.

실제로 AI는 두 번째 문장을 훨씬 잘 활용했다.

왜 이 기술을 사용하는지 이해하면 더 적절한 코드를 생성하기 때문이다.

그때부터 CLAUDE.md를 단순한 규칙 문서가 아니라 프로젝트 문서처럼 관리하기 시작했다.

## AI 시대에 문서의 역할이 달라지고 있다

예전에는 문서가 주로 사람을 위한 것이었다.

새로운 팀원이 들어왔을 때 읽고,
몇 달 뒤의 내가 다시 보기 위해 작성했다.

지금은 독자가 하나 더 늘어났다.

AI다.

AI는 문서를 읽고 프로젝트를 이해한다.

결국 문서 품질이 AI의 결과물 품질에도 영향을 준다.

코드베이스가 커질수록 이 차이는 더 크게 나타난다.

## 좋은 CLAUDE.md는 무엇이 다를까

최근에는 아래 내용들을 꾸준히 기록하고 있다.

### 프로젝트 구조

```md
app/
components/
features/
shared/
```

어떤 디렉토리에 무엇을 두는지 설명한다.

### 기술 선택 이유

```md
React Query 사용 이유
Server Component 사용 기준
상태 관리 전략
```

왜 사용하는지 적는다.

### 자주 발생하는 실수

```md
- Client Component 남용 금지
- 중복 API 호출 주의
- 날짜 처리 시 timezone 확인
```

사람도 실수하는 부분은 AI도 자주 실수한다.

### 코드 예시

AI는 설명보다 예시를 더 잘 이해한다.

실제 프로젝트 코드 패턴을 함께 기록해두는 것이 효과적이었다.

## 결국 중요한 것은 문제 정의다

최근 AI를 활용하면서 가장 많이 느끼는 점이 있다.

코드를 작성하는 능력보다

무엇을 만들 것인가

어떻게 만들 것인가

를 정의하는 능력이 더 중요해지고 있다는 것이다.

AI는 구현을 도와준다.

하지만 프로젝트의 방향과 기준은 여전히 사람이 정해야 한다.

CLAUDE.md는 그 기준을 기록하는 문서에 가깝다.

## 마무리

예전에는 좋은 코드베이스를 만들기 위해 문서를 작성했다.

지금은 좋은 AI 협업 환경을 만들기 위해서도 문서를 작성한다.

AI가 발전할수록 코드를 작성하는 시간은 줄어들 수 있다.

대신 프로젝트의 맥락과 의사결정을 정리하는 시간은 더 중요해질 것 같다.

최근에는 CLAUDE.md를 단순한 설정 파일이 아니라 프로젝트의 운영 문서라고 생각하며 관리하고 있다.

생각보다 효과가 꽤 좋다.