"AI 코딩 에이전트 길들이기 — Karpathy의 4원칙으로 Claude & Cursor 장악하기"

# 나만의 AI 코딩 가이드라인 만들기 — 원칙 확장과 팀 적용

Karpathy의 4원칙은 보편적인 출발점이다. 하지만 모든 프로젝트는 다르다. 백엔드 API 서버와 임베디드 펌웨어는 다른 원칙이 필요하다. 혼자 작업하는 것과 팀으로 작업하는 것도 다르다.

마지막 챕터에서는 4원칙을 베이스로, 내 상황에 맞는 가이드라인을 설계하는 방법을 다룬다.

---

## 1. AI 코딩 실패 패턴 직접 수집하기

좋은 가이드라인은 실제로 겪은 실패에서 나온다. 방법은 간단하다:

```markdown
# AI 코딩 실패 로그 (팀 내부 문서)

| 날짜 | 요청 내용 | 실제 결과 | 원인 분석 | 추가할 규칙 |
|------|----------|----------|----------|------------|
| 2026-01 | DB 쿼리 최적화 | 기존 인덱스 삭제됨 | Surgical Changes 미적용 | "인덱스·스키마 변경 시 명시적 확인" |
| 2026-02 | 에러 메시지 개선 | i18n 구조로 전면 리팩터링 | Simplicity First 미적용 | "i18n 없는 프로젝트에 i18n 추가 금지" |
| 2026-03 | 유틸 함수 추가 | 인터페이스 3개 생성 | Simplicity First 미적용 | "단일 사용처 코드에 추상화 금지" |
```

이런 로그가 쌓이면 CLAUDE.md에 추가할 프로젝트별 규칙이 명확해진다.

---

## 2. 도메인별 가이드라인 패턴

### API 백엔드 프로젝트

```markdown
## Project-Specific Guidelines (API Backend)

- DB 마이그레이션 파일은 수정하지 않음. 변경이 필요하면 새 마이그레이션 파일 생성
- 기존 API 응답 스키마 변경 시 반드시 확인 요청 (하위 호환성 깨질 수 있음)
- ORM 없이 raw SQL 사용 금지 (프로젝트 컨벤션)
- 새 라이브러리 추가 전 package.json 확인 후 제안만 할 것, 직접 설치하지 않음
```

### 임베디드 / 시스템 프로그래밍 (C/C++)

```markdown
## Project-Specific Guidelines (Embedded)

- 동적 메모리 할당 (malloc/new) 추가 시 명시적 확인 필요 (메모리 제약 환경)
- 인터럽트 핸들러 내 blocking 코드 절대 금지
- 타이밍 크리티컬 섹션에 불필요한 로직 추가 금지
- MISRA C 2012 규칙 준수 (프로젝트 `.misra-config` 참고)
- 전역 변수 추가 시 명시적 확인 요청
```

### 프론트엔드 (React/Vue)

```markdown
## Project-Specific Guidelines (Frontend)

- CSS 스타일 변경 시 디자인 시스템 tokens.ts 값만 사용, 하드코딩 금지
- 전역 상태 추가 시 먼저 로컬 상태로 해결 시도 후 제안
- 새 컴포넌트 생성 전 기존 컴포넌트 재사용 가능성 먼저 확인
- 비즈니스 로직을 View 컴포넌트에 직접 작성 금지, hook으로 분리
```

---

## 3. 팀 적용 패턴

개인 프로젝트와 팀 프로젝트는 `CLAUDE.md` 관리 방식이 다르다.

### 저장소에 커밋

```bash
# 팀 레포 루트에 커밋
git add CLAUDE.md
git commit -m "docs: add AI coding guidelines (Karpathy-based)"
```

팀원 모두가 같은 `CLAUDE.md`를 사용한다. AI 코딩 도구의 행동이 프로젝트 전체에서 일관해진다.

### PR 템플릿에 체크리스트 추가

```markdown
# .github/pull_request_template.md

## AI-Assisted Changes
해당되는 경우만 체크

- [ ] Think Before Coding: 모호한 가정 없이 구현됨
- [ ] Simplicity First: 불필요한 추상화 없음
- [ ] Surgical Changes: 요청 범위 밖 변경 없음
- [ ] Goal-Driven: 테스트/검증 기준 충족됨
```

---

## 4. 가이드라인 자체를 AI로 개선하기

흥미로운 피드백 루프가 가능하다.

```
1. AI 코딩 작업 진행
2. 문제 발생 (의도치 않은 변경, 과설계 등)
3. 원인 분석: "어떤 규칙이 있었으면 막을 수 있었나?"
4. CLAUDE.md에 규칙 추가
5. 다음 작업에서 해당 규칙이 적용되는지 확인
6. 반복
```

Claude에게 직접 물어볼 수도 있다:

```
"방금 작업에서 너는 요청하지 않은 추상화를 추가했어.
 이 문제를 예방하기 위해 CLAUDE.md에 어떤 규칙을 추가하면 좋을까?
 현재 CLAUDE.md 내용을 기반으로 제안해줘."
```

---

## 5. 최종 CLAUDE.md 템플릿

실전에서 바로 사용할 수 있는 완성 템플릿이다.

```markdown
# CLAUDE.md

## Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

- State assumptions explicitly. If uncertain, ask rather than guess
- Present multiple interpretations when ambiguity exists
- Push back when a simpler approach exists
- Stop and ask when confused about the task

## Simplicity First

Minimum code that solves the problem. Nothing speculative.

- No features beyond what was asked
- No abstractions for single-use code
- No unrequested "flexibility" or "configurability"
- If 200 lines could be 50, rewrite it

The test: Would a senior engineer say this is overcomplicated? If yes, simplify.

## Surgical Changes

Touch only what you must. Clean up only your own mess.

- Don't improve adjacent code, comments, or formatting
- Don't refactor things that aren't broken
- Match existing style, even if you'd do it differently
- Mention (don't delete) unrelated dead code you notice
- Remove only imports/variables YOUR changes made unused

The test: Every changed line should trace directly to the user's request.

## Goal-Driven Execution

Define success criteria. Loop until verified.

- Write tests first, then make them pass
- For multi-step tasks: define a verify step for each stage
- "Make it work" is not a success criterion

## Project-Specific Guidelines

```

---

## 6. 마무리 — CLAUDE.md는 살아있는 문서다

처음 설치할 때 완벽할 필요가 없다. 실제로 작업하면서 문제가 생길 때마다 규칙을 추가하면 된다.

좋은 `CLAUDE.md`의 특징:
- **짧고 명확하다** — 모호한 원칙은 모델도 해석이 갈린다
- **구체적 금지 사항이 있다** — "좋은 코드를 써라"보다 "single-use 추상화 금지"가 더 효과적이다
- **프로젝트 컨텍스트가 반영됐다** — 범용 원칙 + 도메인 특화 규칙의 조합

> 💡 **핵심**: Karpathy의 4원칙은 AI 코딩 가이드라인의 보편적 출발점이다. 실제로 겪는 실패 패턴을 로그로 쌓고, 도메인별 규칙을 추가하고, 팀과 공유하는 것이 완성이다. `CLAUDE.md`는 단순한 파일이지만, 올바르게 쓰면 AI 코딩 도구를 예측 가능하게 만드는 가장 강력한 도구다.

"나만의 AI 코딩 가이드라인 만들기 — 원칙 확장과 팀 적용"

// COMMENTS

ON THIS PAGE