Claude Code 팀 도입 — AI를 개인 습관에서 팀 표준으로

FSD와 함께, 입사 직후 제안한 또 하나가 Claude Code(.claude) 팀 표준화였다. 팀이 AI를 적극 쓰는데 "각자 알아서" 쓰면 결과도 보안도 제각각이 된다. 설정 파일을 까는 일 자체보다, 왜 필요한지를 제안서로 설득하는 일이 먼저였다.

"그냥 쓰는" AI 도구의 세 가지 비용

설정 없이 쓰면 개발자마다 프롬프트 습관·권한 승인·작업 순서가 다 다르다. 세 군데서 샜다.

• 보안 — .env·secrets를 AI가 읽거나 출력하는 게 가장 흔한 사고다. 매번 "허용?"을 누르다 보면 승인 피로로 무비판적 allow가 습관이 된다
• 일관성 — 개발자 A는 pages/+JS, B는 app/+TS. 같은 레포에 패턴이 혼재된다
• 온보딩 — "이 레포 어떻게 써요?"가 매번 슬랙·구두 설명·위키 찾기로 반복된다

우리 팀은 AI를 적극 쓰는 팀이라 이 비용이 빠르게 쌓일 참이었다. FSD를 고른 이유 중 하나도 "AI 컨텍스트 효율"이었으니, 둘은 한 세트였다 — 구조가 깔끔해야 AI도 정확했다.

팀 표준을 레포에 고정하다

① 보안: deny를 팀 레포에 커밋

.claude/settings.json의 deny로 위험 행위를 원천 차단하고, 안전한 명령만 allow에 등록해 승인 피로를 줄였다. 핵심은 계층 우선순위 — 팀이 deny한 건 개인이 local/global에서 allow해도 안 풀린다.

{
  "permissions": {
    "deny": ["Read(./.env*)", "Read(./secrets/**)", "Bash(curl *)"],
    "allow": ["Bash(pnpm lint)", "Bash(pnpm test *)", "Bash(pnpm build)"]
  }
}

deny를 팀 레포에 커밋하니 전원에게 자동 적용됐다. ".env 읽지 마"를 사람한테 부탁하는 대신 설정으로 막은 것이다.

② 일관성: CLAUDE.md에 스택·규칙을 명시

세션 시작 시 자동 로드되는 CLAUDE.md에 스택과 금지 규칙을 박았다.

## 스택
- Next.js 16 (App Router) · TS5 strict · TanStack Query · Zustand
## 규칙
- app/ 라우터만, 'use client' 최소화, API는 http 래퍼로

누가 "로그인 API 만들어줘"를 시켜도 같은 결과가 나온다.

③ 모듈화: 한 파일에 다 vs @import (트레이드오프)

규칙이 늘자 선택지가 갈렸다. 한 CLAUDE.md에 다 넣으면(500줄+) 컨텍스트 윈도우를 낭비하고 유지보수가 지옥이 된다. 그래서 루트는 ~40줄로 얇게 두고, 상세는 @.claude/rules/*로 분리하는 라우팅 허브로 갔다.

## 상세 규칙
@.claude/rules/architecture.md
@.claude/rules/coding-style.md
@.claude/rules/security.md

상위는 세션 시작 시 로드, 하위는 해당 파일 접근 시 온디맨드 로드 — 컨텍스트를 아끼면서 더 구체적인 지침이 우선하게 했다. 개인 선호는 gitignore되는 CLAUDE.local.md로 분리했다.

효과

설정이 없으면 AI가 "Zustand인지 Redux인지, fetch인지 axios인지"를 매번 탐색하며 토큰을 태운다. CLAUDE.md가 그 답을 미리 줘서, 탐색 대신 작업에 토큰을 쓰게 했다.

배운 점

• AI 도구도 "개인 습관"이 아니라 "팀 표준"으로 박아야 한다. 보안·일관성·온보딩은 부탁이 아니라 레포에 커밋된 설정으로 풀린다
• 이건 FSD와 한 세트였다 — 구조가 깔끔해야 AI 컨텍스트도 깔끔하고, 표준이 있어야 AI 결과가 일관된다
• 새 도구 도입도 결국 왜·트레이드오프를 문서로 설득하는 일이었다. 좋은 도구라고 그냥 깔면 안 쓰인다