AI 보조 개발: 엔지니어를 위한 실무 가이드
요약
Claude CLI의 효율적인 사용을 위한 설정 시스템과 CLAUDE.md 활용법을 다룹니다. 프로젝트 컨텍스트를 유지하고 일관된 코딩 컨벤션을 적용하기 위한 파일 계층 구조와 권한 제어 방법을 설명합니다.
핵심 포인트
- 설정 시스템을 통해 AI에게 기술 스택과 컨벤션을 사전에 학습 가능
- 근접성 원칙에 따른 설정 우선순위(글로벌 < 프로젝트 < 하위 디렉토리) 이해
- CLAUDE.md를 활용한 프로젝트 온보딩 및 범위 지정 지침 작성
- settings.json을 통한 보안 경계 설정 및 작업 권한 제어
1. 설정 시스템(Configuration System)이 필요한 이유
대부분의 개발자는 Claude CLI를 사용할 때 동일한 방식으로 시작합니다. 터미널을 열고, 질문을 던지고, 답변을 얻습니다. 그러고 나서 매 세션마다 기술 스택(tech stack), 코딩 컨벤션(coding conventions), 프로젝트 구조를 다시 설명하는 과정을 반복합니다.
근본적인 원인은 컨텍스트(context)의 부재입니다. 설정 시스템의 핵심 가치는 단 하나의 메시지가 입력되기 전에 AI가 이미 당신의 프로젝트, 선호도, 그리고 허용된 작업 범위를 이해하도록 보장하는 것입니다.
잘 구조화된 설정은 다음과 같은 작업을 가능하게 합니다:
- AI에게 기술 스택과 컨벤션에 대한 영구적인 지식을 제공하여 재설명이 필요 없게 함
git push --force와 같은 위험한 작업 전에 명시적인 확인을 요구함- 파일 저장 시 포맷팅(formatting)과 같은 반복적인 작업을 자동화함
- 팀 전체에 걸쳐 일관된 AI 경험을 공유함
2. 파일 계층 구조 개요
Claude CLI 설정은 **근접성 원칙(proximity principle)**을 따릅니다. 프로젝트에 더 가까운 설정일수록 더 높은 우선순위를 가집니다. 개인 설정은 공유된 팀 설정에 절대 영향을 미치지 않습니다.
~/.claude/ # 글로벌 사용자 수준 설정
├── settings.json # 글로벌 권한, 모델, 동작
├── CLAUDE.md # 개인 글로벌 선호도 (커밋되지 않음)
...
설정 우선순위 (높음에서 낮음 순)
하위 디렉토리 CLAUDE.md
> 프로젝트 .claude/settings.local.json
> 프로젝트 .claude/settings.json
...
경험 법칙(Rule of thumb): 팀 컨벤션은 프로젝트 수준 설정에, 개인 선호도는 글로벌 설정에, 민감한 로컬 오버라이드(overrides)는 settings.local.json(.gitignore 처리됨)에 작성합니다.
3. CLAUDE.md: 프로젝트를 위한 AI 브리핑 문서
CLAUDE.md는 Claude CLI가 모든 대화를 시작할 때 자동으로 로드합니다. 이를 AI가 당신의 코드베이스를 건드리기 전에 읽는 온보딩(onboarding) 문서라고 생각하세요.
좋은 CLAUDE.md에 포함되는 내용
# 프로젝트 이름
## 기술 스택 (Tech Stack)
...
하위 디렉토리 CLAUDE.md
복잡한 프로젝트의 경우, 코드베이스의 특정 영역에 더 가까운 곳에 범위가 지정된 지침(scoped instructions)을 추가하세요:
# web/src/components/CLAUDE.md
## 컴포넌트 컨벤션 (Component Conventions)
...
⚠️ CLAUDE.md에 포함되어서는 안 되는 것
- 비밀 정보, 토큰 또는 비밀번호 — 개발 환경용이라 하더라도 포함 금지
- 대규모 코드 샘플 — 컨텍스트(Context)를 소모합니다. 어차피 AI는 소스 파일을 더 정확하게 읽습니다.
- 빈번하게 변경되는 정보 — 현재 버전 번호와 같이 자주 바뀌는 정보. 오래된 데이터는 AI를 오도할 수 있습니다.
4. settings.json: 동작 및 권한 제어
settings.json은 Claude CLI가 할 수 있는 일과 할 수 없는 일을 정의합니다. 이것이 여러분의 **보안 경계 (security boundary)**의 핵심입니다.
권한 모델 (The Permission Model)
Claude CLI는 허용 목록(allowlist) 모델을 사용합니다. 기본적으로 모든 작업은 확인이 필요하며, 명시적으로 허용된 작업만 자동으로 실행됩니다.
{
"permissions": {
"allow": [
...
도구 권한 구문 (Tool Permission Syntax)
ToolName(argument-match-pattern)
Bash(npm *)— 모든 npm 명령 허용Bash(npm run test)— 정확히 이 명령만 허용Read(**)— 모든 파일 읽기 허용 (**는 여러 경로 세그먼트와 일치)Write(src/**)—src/디렉토리 내부의 쓰기만 허용
모델 및 동작 설정 (Model and Behavior Configuration)
{
"model": "claude-opus-4-7",
"env": {
...
팀 설정(Team Config) vs 개인 설정(Personal Config)
| 파일 | git 커밋 여부 | 목적 |
|---|---|---|
.claude/settings.json | 예 | 공유된 팀 권한 기준선 |
| ... |
5. Hooks: 자동화된 워크플로우의 핵심
훅(Hooks)은 특정 이벤트가 발생할 때 자동으로 실행되도록 settings.json에 구성된 셸(shell) 명령입니다. 이는 AI 워크플로우를 자동화하기 위한 주요 메커니즘입니다.
사용 가능한 훅 이벤트 (Available Hook Events)
| 이벤트 | 발생 시점 | 일반적인 용도 |
|---|---|---|
PreToolUse | AI가 도구를 호출하기 전 | 위험한 작업 차단, 감사 로깅 (audit logging) |
| ... |
실무적인 훅 예시 (Practical Hook Examples)
1. AI가 파일을 수정한 후 자동 포맷팅
{
"hooks": {
"PostToolUse": [
...
2. 프로덕션 설정(Production Config)에 대한 쓰기 차단
{
"hooks": {
"PreToolUse": [
...
3. AI 작업 완료 시 데스크톱 알림
{
"hooks": {
"Stop": [
...
Hook 종료 코드 컨벤션 (Hook Exit Code Convention)
| 종료 코드 (Exit Code) | 의미 (Meaning) |
|---|---|
0 | 정상 진행 (Proceed normally) |
| ... |
6. MCP 서버: AI의 도달 범위 확장
MCP (Model Context Protocol)는 AI를 외부 시스템에 연결하기 위한 표준 프로토콜입니다. MCP 서버 (MCP Servers)를 통해 AI는 데이터베이스를 쿼리하고, 내부 API를 호출하며, 제3자 서비스와 상호작용할 수 있습니다.
MCP 서버 설정하기
settings.json에 선언합니다:
{
"mcpServers": {
"postgres": {
...
보안 원칙 (Security Principles)
- 민감한 토큰은 환경 변수(
${VAR_NAME})를 통해 참조하고, 절대 하드코딩하지 마세요. - 내부 MCP 서버는 기본적으로 읽기 전용(Read-only)이어야 합니다. 쓰기 작업은 권한 제어가 포함된 명시적인 도구(Tools)로 노출하세요.
- AI가 의도적으로 사용할 수 있도록 각 MCP 서버의 목적을
CLAUDE.md에 문서화하세요.
7. 스킬 (Skills): 재사용 가능한 AI 워크플로우 캡슐화
스킬 (Skills)은 .md 파일에 저장되며 /skill-name 명령어를 통해 트리거되는 구조화된 지침 세트입니다. 이는 팀 전체의 AI 워크플로우를 표준화하기 위한 주요 도구입니다.
스킬 파일 구조
# .claude/skills/create-feature.md
---
...
프로젝트 수준 vs 글로벌 스킬 (Project-Level vs Global Skills)
.claude/skills/ # 프로젝트 특정적; git에 커밋됨; 팀 공유
~/.claude/skills/ # 개인 글로벌; 모든 프로젝트에서 재사용 가능
스킬로 만들 가치가 있는 것들
- 고정된 출력 구조를 가진 코드 생성 (CRUD 모듈, API 엔드포인트)
- 다단계 조정 작업 (DB 마이그레이션 + 코드 생성 + 테스트)
- 팀의 명시적인 컨벤션이 있는 작업 (PR 설명, 리뷰 체크리스트)
- 반복적인 분석 작업 (의존성 보안 감사, 벤치마크 비교)
8. 에이전트 SDK (Agent SDK): 커스텀 AI 에이전트 구축
대화형 Claude CLI 모델만으로 충분하지 않을 때, Agent SDK를 사용하면 특정 목적에 맞게 설계된 에이전트(Agent)를 구축할 수 있습니다. 예를 들어, CI/CD 파이프라인에서의 자동화된 코드 리뷰(Code Review)나 모니터링 알림의 자동 분류(Triage) 등이 가능합니다.
핵심 개념: 에이전트 루프 (Agent Loop)
import anthropic
client = anthropic.Anthropic()
...
CI/CD 통합 예시
# .github/workflows/ai-review.yml
name: AI Code Review
...
에이전트 설계 원칙 (Agent Design Principles)
- 단일 책임 (Single responsibility): 각 에이전트는 한 가지 일만 수행해야 합니다. 복잡한 작업은 협력하는 여러 에이전트로 분리하세요.
- 멱등성 작업 (Idempotent operations): 실패한 에이전트 실행을 재시도하더라도 부작용(Side effects)이 발생해서는 안 됩니다.
- 감사 로그 (Audit logging): 디버깅을 위해 에이전트가 수행하는 모든 도구 호출(Tool call)을 기록하세요.
- 엄격한 제한 (Hard limits): 에이전트가 통제 불능 상태로 실행되는 것을 방지하기 위해
max_tokens와 루프 반복 횟수 제한을 설정하세요.
9. 개발 모범 사례 (Development Best Practices)
9.1 설정을 통한 컨텍스트 선제적 제공 (Front-Load Context Into Configuration)
반복적인 작업을 멈추세요. 반복되는 컨텍스트는 CLAUDE.md에 한 번만 작성해 두면 됩니다.
## Project-Specific Vocabulary
- "DTO" = Data Transfer Object, `internal/dto/`에 위치함
- "UC" = Use Case, `internal/usecase/`에 위치함
...
또한, 관련 없는 작업으로 전환할 때는 /clear를 사용하여 대화 컨텍스트를 초기화하세요. 세션이 길어지면 오래된 컨텍스트가 쌓여 출력 품질이 저하됩니다.
9.2 최소 권한 원칙 (Principle of Least Privilege)
편의를 위해 AI에게 광범위한 권한을 부여하고 싶은 유혹을 뿌리치세요.
// 나쁜 예: 위험할 정도로 광범위함
{ "allow": ["Bash(*)", "Write(**)"] }
...
9.3 단계적 자동화 (Progressive Automation)
리스크가 낮은 작업부터 자동화하기 시작하여 신뢰를 점진적으로 확장하세요.
1단계: 읽기 전용 자동화 (파일 읽기, 코드 검색, 테스트 실행)
↓
2단계: 로컬 쓰기 자동화 (파일 수정, 로컬 git 작업)
...
9.4 제약 조건이 있는 프롬프트 작성 (Write Constrained Prompts)
길이보다 구조가 더 중요합니다. AI에게 자유를 주기보다는 제약 조건을 부여하세요.
// 모호함 — 평범한 결과물을 생성함
"Optimize this code"
...
9.5 구조화된 코드 리뷰를 위한 AI 활용
AI에게 단순히 "코드를 봐줘"라고 요청하는 대신, 명시적인 리뷰 명령(review mandate)을 부여하세요:
internal/payment/calculator.go를 다음 항목에 대해 리뷰해줘:
1. 보안 (security) — SQL 인젝션 (SQL injection), 인증 우회 (auth bypass), 입력값 검증 (input validation)
2. 정확성 (correctness) — 경계 조건 (boundary conditions), 동시성 안전성 (concurrency safety), 에러 처리 (error handling)
...
9.6 팀 협업 컨벤션 (Team Collaboration Conventions)
## 커밋할 내용 (What to Commit)
항상 커밋할 것:
...
10. 일반적인 안티 패턴 (Common Anti-Patterns)
AI를 검색 엔진처럼 사용하기
// 안티 패턴: 결정론적인 답변이 있는 정보를 요청함
"고루틴 (goroutines)은 어떻게 작동하나요?"
...
AI 출력물을 맹목적으로 신뢰하기
AI는 매우 확신에 찬 어조로 잘못된 코드를 생성할 수 있습니다. 인증 (authentication), 결제 (payments), 데이터 마이그레이션 (data migrations)과 같은 핵심 경로 (critical paths)를 위해 AI가 생성한 코드는 머지 (merge)하기 전에 반드시 사람이 리뷰하고 테스트를 통해 검증해야 합니다. AI의 출력물은 완성된 제품이 아니라 초안 (draft)으로 취급하십시오.
단일 세션에 과도한 작업 몰아넣기
한 세션에서 너무 많은 일을 수행하면 컨텍스트 오염 (context pollution)이 발생합니다. 즉, 초기에 설정된 잘못된 가정이 이후의 출력물까지 오염시킵니다. 각각의 독립적인 작업에는 새로운 세션을 시작하세요.
AI가 의도를 추측하게 만들기
// 안티 패턴: 개방형 지시 (open-ended instruction)
"이 모듈에 테스트를 몇 개 추가해줘"
...
AI의 불확실성 신호 무시하기
AI가 "확실하지 않습니다" 또는 "이 부분을 확인하는 것이 좋을 것 같습니다"라고 말할 때, 그냥 지나치지 마세요. 이러한 신호는 대개 AI가 자신의 지식 경계에서 작업하고 있거나 컨텍스트 (context)가 부족함을 의미합니다. 이러한 순간에 사람이 개입하는 것이 AI가 추측하게 두는 것보다 훨씬 더 효율적입니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기