대부분의 개발자들은 AI 코딩 도구를 더 똑똑한 자동 완성(autocomplete) 기능처럼 취급합니다. 주석을 입력하면 제안이 나오고, Tab 키를 눌러 수락하는 식이죠. 솔직히 말해서, 그것은 이 도구들이 실제로 할 수 있는 능력의 10% 정도에 불과합니다.

지난 몇 달 동안 저는 자동 완성을 훨씬 뛰어넘는 Claude Code 중심의 워크플로우를 구축해 왔습니다. 이는 세 가지 요소의 조합입니다: Claude에게 우리 팀의 아키텍처 패턴을 가르치는 커스텀 프로젝트 설정(custom project config), 다단계 엔지니어링 워크플로우를 처리하는 커스텀 슬래시 명령어(custom slash commands), 그리고 Claude를 우리가 매일 사용하는 인프라에 연결하는 MCP 통합(MCP integrations)입니다.

그 결과는 실질적이었습니다. 올바른 폴더 구조, Zod 스키마(Zod schemas), API 라우트(API routes), 훅(hooks), 그리고 테스트를 포함하여 새로운 기능을 스캐폴딩(scaffolding)하는 작업은 예전에 하루 중 약 2시간을 잡아먹곤 했습니다. 이제는 대략 5분 정도밖에 걸리지 않으며, 매번 우리의 컨벤션(conventions)을 완벽하게 따릅니다.

각 요소가 결합되는 방식:

┌───────────┐
│ Developer │
└─────┬─────┘
...

제가 이를 어떻게 설정했는지 정확히 알려드리겠습니다.

CLAUDE.md: Claude에게 당신의 아키텍처 가르치기

제가 작업하는 모든 프로젝트의 루트(root)에는 CLAUDE.md 파일이 생성됩니다. 저는 이것을 인간과 AI가 모두 실제로 읽게 될 문서라고 생각합니다. Claude Code가 세션을 시작할 때 이 파일을 로드하며, 이를 코드베이스 내부에서 어떻게 행동해야 하는지에 대한 지침으로 취급합니다.

다음은 제가 사용하는 파일의 단순화된 버전입니다:

# Project: Analytics Dashboard

## Architecture Overview
...

일반적인 문서처럼 보이지만, 그 효과는 기대 이상입니다. 명령어 하나로 이를 읽고 전체 기능을 생성합니다:

┌──────────────────────────┐
│ You type:                │
│   /scaffold-feature      │
...

제가 Claude에게 "사용자 유지(user retention)를 위한 새로운 분석 기능을 스캐폴딩해줘"라고 말하면, 다음과 같은 결과가 돌아옵니다:

1. components/features/retention/ 하위의 올바른 폴더 구조
2. 적절한 추론된 타입 (inferred types)을 포함한 types/retention.ts 내의 Zod 스키마 (Zod schemas)
3. queryFn 내에서 Zod 파싱 (Zod parsing)을 수행하는 hooks/useRetentionData.ts 내의 React Query 훅 (hook)
4. Zod 검증 (Zod validation)을 포함한 app/api/retention/route.ts 내의 API 라우트 (API route)
5. 동적 차트 임포트 (dynamic chart imports) 및 스켈레톤 로더 (skeleton loaders)를 포함한 컴포넌트들

이 모든 것은 우리의 컨벤션 (conventions)을 따르며, 저는 수동으로 다시 돌아가서 수정할 필요가 없습니다. 저에게 이것은 "코드를 작성하는 AI"와 "당신의 팀이 코드를 작성하는 방식대로 코드를 작성하는 AI"를 가르는 경계선입니다.

커스텀 슬래시 명령어 (Custom Slash Commands): 한 번의 명령어로 수행하는 다단계 워크플로우

슬래시 명령어 (Slash commands)는 입력하여 실행할 수 있는 재사용 가능한 프롬프트 (prompts)입니다. 각 명령어는 .claude/commands/ 내에 마크다운 (Markdown) 파일로 존재하므로, 해당 폴더가 리포지토리 (repo)에 커밋되면 팀 전체가 동일한 명령어를 사용할 수 있습니다. 저는 가장 자주 반복하는 각 워크플로우 (workflows)에 대해 명령어를 하나씩 작성했습니다.

명명 규칙에 대해 사람들이 혼동할 수 있는 부분을 짧게 언급하겠습니다. Claude Code에는 '스킬 (Skills)'이라는 별도의 기능도 있는데, 이는 Claude가 일치하는 작업을 발견하면 스스로 호출합니다. 유일한 실질적인 차이점은 누가 실행하느냐입니다. 스킬 (Skill)은 Claude가 관련이 있다고 판단할 때 자동으로 실행되는 반면, 슬래시 명령어 (slash command)는 사용자가 직접 입력할 때 실행됩니다. 아래의 워크플로우들에 대해서는 정확히 언제 실행될지에 대해 명시적이고 온디맨드 (on-demand) 방식의 제어를 원하기 때문에 슬래시 명령어 (slash commands)를 사용합니다. 만약 Claude가 이 중 하나를 스스로 호출하기를 원한다면, 동일한 마크다운 (Markdown)을 스킬 (Skill)로 패키징할 수도 있습니다.

명령어: 새로운 기능 스캐폴딩 (Scaffold a New Feature)

# /scaffold-feature

사용자가 "scaffold [feature-name]"이라고 말하면, 다음을 생성하세요:
...

따라서 제가 /scaffold-feature user-retention이라고 입력하면, Claude는 아키텍처적으로 올바르고, 적절한 패턴을 사용하며, 우리의 명명 규칙과 일치하는 5개의 파일을 생성합니다. 인접한 기능에서 복사-붙여넣기를 할 필요도 없고, 그 과정에서 아무도 Zod 검증 (Zod validation)을 잊어버리지 않습니다.

명령어: 성능 감사 (Performance Audit)

# /perf-audit

현재 페이지/컴포넌트의 성능 문제를 분석하세요:
...

명령어: PR 전 리뷰 (Pre-PR Review)

/pre-review

PR(Pull Request)을 생성하기 전에, 다음 사항을 기준으로 변경 사항을 검토하세요:
...

이는 린터(linter)가 절대 잡아낼 수 없는 종류의 문제들, 즉 아키텍처 드리프트(architectural drift), 상태 관리 계층(state management tiers)의 혼선, 그리고 시간이 흐르며 서서히 무너지는 컨벤션(conventions) 등을 포착해냅니다.

프로젝트 초기화: 전체 설정 (The Full Setup)

새로운 프로젝트를 시작할 때, 저는 전체 개발 환경을 구축해 주는 명령어를 사용합니다:

# /init-project

팀의 표준 설정으로 새로운 Next.js 프로젝트를 초기화하세요:
...

매번 보일러플레이트(boilerplate)를 작성하는 데 30분을 허비하는 대신, 명령어 하나를 실행하면 우리의 아키텍처 패턴, 검증 유틸리티(validation utilities), 폴더 컨벤션(folder conventions)이 이미 연결된 프로젝트를 얻을 수 있습니다.

MCP 서버: Claude를 인프라에 연결하기

MCP (Model Context Protocol) 서버를 통해 Claude는 외부 도구에 접근할 수 있습니다. 제가 가장 많이 의존하는 세 가지는 다음과 같습니다:

Figma MCP. Claude는 Figma 파일에서 디자인 명세(design specs)를 직접 읽을 수 있습니다. 새로운 컴포넌트를 만들 때 Figma 노드를 지정하면, 기존 UI 컴포넌트를 재사용하면서 디자인과 일치하는 코드를 생성합니다.

Slack MCP. Claude는 문맥 파악을 위해 채널 메시지를 가져올 수 있습니다. Slack 스레드에서 버그가 보고되었다면, Claude에게 해당 스레드를 전달하여 보고 내용, 주고받은 논의, 그리고 그 안에 묻혀 있는 모든 관련 문맥을 파악하게 할 수 있습니다.

GitHub MCP. Claude는 PR, 이슈(issues), 리뷰를 읽을 수 있습니다. 코드를 작성하기 전에 관련 이슈와 이전 PR을 스캔하여 이미 시도된 내용이 무엇인지 이해할 수 있습니다.

기저에 깔린 아이디어는 간단합니다. 팀이 매일 사용하는 거의 모든 도구가 Claude의 문맥(context)이 될 수 있으며, 문맥이 많아질수록 Claude의 결과물은 팀이 실제로 일하는 방식에 더 가까워집니다.

이것이 일상적인 개발을 어떻게 바꾸는가

현재 제가 진행하는 전형적인 기능 구현(feature session) 과정은 다음과 같습니다:

나: /scaffold-feature user-retention

Claude: [정확한 타입, API 라우트, 훅(hook), 컴포넌트, 배럴 익스포트(barrel export)를 포함한 5개 파일 생성]
...

이전에는 스캐폴딩(scaffolding), 와이어링(wiring), 그리고 수동 리뷰에 2시간 이상이 소요되었던 기능을 처리하는 데 이제는 약 15분 정도면 충분합니다.

이것이 시니어 엔지니어에게 의미하는 바

AI 증강 개발(AI-augmented development)이 아키텍처적 사고(architectural thinking)를 대체하는 것은 아닙니다. 오히려 그 반대로, 아키텍처적 사고에 더 크게 의존하게 됩니다.

시니어 엔지니어의 역할은 여전히 중요한 결정을 내리는 것입니다. 어떤 패턴을 사용할지, 경계(boundaries)를 어디에 설정할지, 어떤 트레이드오프(tradeoffs)가 가치가 있는지를 결정하는 일 말입니다. AI는 당신이 결정을 내린 후, 그 결정의 실행 속도를 높여줄 뿐입니다.

그렇기에 저는 당신이 만드는 명령어들이 기본적으로 당신의 아키텍처적 판단을 기록한 것이라고 주장합니다. 스캐폴딩(scaffolding) 명령어는 당신의 아키텍처 결정을 포착합니다. 사전 리뷰(pre-review) 명령어는 당신의 코드 리뷰 표준을 포착합니다. CLAUDE.md 파일은 팀의 컨벤션(conventions)을 포착합니다.

그리고 바로 그 지점에 진정한 레버리지(leverage)가 존재합니다. 당신은 한 번 결정을 내리고, 이를 명령어 또는 설정(config)으로 인코딩하며, 그 이후부터는 모든 기능에 일관되게 적용됩니다. 더 이상 "시니어가 그 PR을 검토할 시간이 없었다"라거나 "신입 개발자가 우리가 API 응답에 Zod를 사용한다는 사실을 몰랐다"와 같은 상황은 발생하지 않습니다.

시작하기

이 방식을 시도해보고 싶다면, 제가 권장하는 순서는 다음과 같습니다:

1. CLAUDE.md부터 시작하세요. 프로젝트의 아키텍처 개요, 폴더 컨벤션 (Folder conventions), 그리고 타협할 수 없는 규칙들을 작성하세요. 이 단계만으로도 Claude의 유용성이 눈에 띄게 향상됩니다.

2. 가장 반복적인 워크플로 (Workflow) 세 가지를 선정하세요. 매주 반복하고 있다고 느끼는 작업들입니다. 우선 그 각각에 대한 명령어를 작성하세요.

3. 각 명령어를 집중력 있게 유지하세요. 하나의 명령어에는 하나의 워크플로만 담으세요. 모든 것을 다 하려는 단일 메가 명령어 (Mega-command)를 만들고 싶은 유혹을 뿌리치세요. 한 가지 일을 잘 수행하는 작고 조합 가능한 (Composable) 명령어들이 여러분에게 더 큰 도움이 될 것입니다.

4. 반복하여 개선하세요 (Iterate). 첫 번째 CLAUDE.md에는 빈틈이 있을 것입니다. Claude가 여러분의 컨벤션을 놓친 결과물을 내놓을 때마다, 설정을 업데이트하세요. 시간이 지나면서 그 효과는 복리로 쌓입니다.

5. 팀원들과 공유하세요. CLAUDE.md와 명령어들은 리포지토리 (Repo)에 존재하므로, 모든 팀원이 동일한 컨벤션과 동일한 워크플로를 별도의 노력 없이 그대로 사용할 수 있습니다.

앞으로의 몇 년 동안 가장 큰 이득을 얻을 엔지니어는 타자가 가장 빠른 사람이 아닙니다. 이 도구들에게 자신의 표준을 가르치고, 자신의 판단력을 전체 코드베이스 (Codebase)로 확장할 수 있는 사람입니다.

CLAUDE.md부터 시작하세요. 나머지는 자연스럽게 따라올 것입니다.