Claude Code 실무 팁 총정리 | hooks, 서브 에이전트, MCP 활용으로 달라진 개발 플로우

2026년 10월 현재, Claude Code를 업무의 메인 툴로 사용한 지 반년 이상 되었다. 처음에는 '채팅으로 코드를 작성하게 하는 도구' 정도라는 인식이었지만, CLAUDE.md, hooks, 서브 에이전트, MCP를 조합하니 단순한 코드 생성 도구를 넘어 '개발 플로우 자체를 운영하는 시스템'으로 변모했다.

최근 2주간 Qiita를 보면 'Security' 태그에 20개 이상의 스토리를 가진 글 6개가 올라왔고, 'AI 에이전트' 태그에도 4개의 글이 올라와 있다. Zenn의 일일 트렌드에서는 '나만의 AI 프로그래밍 방법론' 계열의 포스팅이 좋아요 환산 531이라는 높은 상승률을 보이고 있다. 즉, 현재 엔지니어 커뮤니티의 관심사는 'AI에게 코드를 작성하게 하는 것'에서 'AI와의 작업 절차를 어떻게 설계할 것인가'로 이동하고 있다. 본 글에서는 내가 실제로 사용하고 있는 Claude Code의 설정 및 명령어들을 그대로 적는다. 복사-붙여넣기로 작동하는 내용만 담았다.

처음에는 CLAUDE.md에 'TypeScript를 사용할 것', '테스트를 작성할 것' 정도만 적었다. 지금은 계층화하여 운영하고 있다.

project-root/
CLAUDE.md # 프로젝트 공통 규칙
RTK.md # 규칙 상세 (별 파일로 분리)

CLAUDE.md 내에서 @ 표기법을 사용하면 다른 파일을 불러올 수 있다.

@RTK.md
@docs/architecture.md

이를 통해 '전체 규칙은 간결하게', '상세 규칙은 별 파일로' 구성할 수 있다. 사용자 단위의 ~/.claude/CLAUDE.md와 프로젝트 단위의 CLAUDE.md는 모두 로드되므로, 개인적인 습관(커밋 메시지 작성 방식, 파괴적 작업 방지 등)은 ~/.claude/CLAUDE.md에, 프로젝트 고유 규칙(DB 사용 여부, 배포 위치 등)은 프로젝트 쪽에 두는 것이 사고가 가장 적다.

Qiita의 Security 태그가 성장하는 것은 우연이 아니다. AI 에이전트에게 실행 권한을 넘겨주는 기회가 늘어난 만큼, 사고 발생 확률도 높아졌다고 생각한다. 나는 Claude Code의 settings.json에 hooks를 설정하여 위험한 작업이 실행되기 전에 막고 있다.

{
"hooks": {
"PreToolUse": [
...

check-dangerous-command.sh 측에서는 rm -rf나 git push --force 같은 패턴을 문자열 매칭으로 감지하여, 해당할 경우 비제로 종료로 차단한다. 실제로 내 환경에서는 'force push를 하려다 일단 멈추는' 상황이 몇 번 있었고, 사고 미수로 끝난 적이 있다. /update-config 스킬을 사용하면 이러한 hook 설정을 대화 형식으로 구성해 주기 때문에, JSON을 직접 손으로 작성하는 것보다 빠르다.

AI 에이전트 태그의 글이 늘어나는 것도 체감과 일치한다. Claude Code에서는 .claude/agents/ 아래에 Markdown 파일을 두면 서브 에이전트를 정의할 수 있다.

---
name: security-reviewer
description: Merge 전에 보안 관점에서 diff를 리뷰하는 에이전트
...

이렇게 정의해 두면, 본체 Claude가 Agent 툴을 통해 호출할 수 있다. 내가 자주 사용하는 구분법은 다음과 같은 3가지 종류다.

• 탐색 전문 (Explore 상당): 파일이나 심볼의 위치를 찾는 것만 한다. 읽기 전용이라 안전하다.
• 조사 전문 (general-purpose 상당): 여러 파일을 가로질러 사양을 파악한다. 결과만 본체에 반환한다.
• 리뷰 전문: diff에 대해 보안 및 성능 관점에서 체크한다.

핵심은 '본체의 컨텍스트 윈도우를 오염시키지 않는 것'이다. 큰 로그나 검색 결과를 그대로 본체에게 읽히면, 이후의 판단력이 떨어지기 쉽다. 서브 에이전트에게 조사를 맡기고 요약만 받는 설계로 하면, 장시간 세션에서도 본체가 지능을 유지하기 쉽다.

Zenn에서 성장하는 '나만의 AI 프로그래밍 방법론' 계열 글을 읽어보면, 결국 모두가 도달하는 결론은 비슷하다. 'AI에게 자유롭게 작성하게 두지 않고, 처음에 계획을 작성하게 한 후 승인받고 실행시키는 것'. 나 역시 이것을 철저히 하고 있다.

Claude Code에는 Plan Mode가 있어 Shift+Tab으로 모드를 전환할 수 있다. 3단계 이상이 걸릴 것 같은 작업이나 아키텍처와 관련된 변경은 반드시 Plan Mode로 넣은 후에 던진다. 계획을 리뷰하고 OK를 줄 때까지 구현은 시작되지 않는다.

실무에서의 나의 루틴은 다음과 같다.

이러한 절차를 밟게 된 후로는 리뷰에서 지적되는 수준이 '로직 오류'에서 '설계의 선호도'로 바뀌었다. AI에게 모든 것을 맡기던 시절에는 근본적인 버그 지적이 많았다.

'데이터 분석'이라는 관점에서도 Claude Code는 은근히 강하다. MCP(Model Context Protocol) 서버를 연결하면 DB나 API에 직접 접근할 수 있다.

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres "postgresql://user:pass@localhost/mydb"

이것으로 DB에 직접 쿼리를 날릴 수 있게 되었다. 나는 매출이나 접근 로그의 집계를 SQL로 작성하게 하고, 주간 보고서를 자연어로 요약하도록 운영하고 있다. 주의할 점은 프로덕션 DB에 직접 쓰기 권한을 부여하지 않는 것이다. 읽기 전용 사용자(read-only user)로 연결하는 것이 철칙이다. 데이터 분석 관련 작업을 AI에게 맡길 경우, '집계까지는 맡기고, 의사결정은 인간이 한다'라는 경계를 명확히 해두면 사고가 적다.

나중에 다시 볼 수 있도록 표에 정리해 둔다.

이 표만 저장해 두면, 새로운 프로젝트를 시작할 때 초기 설정 체크에 사용할 수 있다.

SES에서 상주하게 되면 도구 선정 권한이 없고, 이런 설정을 자유롭게 시험해 볼 수 없는 환경도 많다. 'SES 그만두고 싶다'라고 느끼는 이유 중 하나는 바로 이 재량권의 부족이라고 생각한다. 반면, 개인 PC 환경이나 사이드 프로젝트에서 CLAUDE.md・hooks・서브에이전트 운영을 직접 구성해 놓으면, 그것 자체가 'AI 에이전트 운영 경험'이라는 형태로 시장 가치가 된다.

프리랜서로 전향하는 것을 생각한다면, 단가나 연봉 이야기를 하기 전에 '내가 어떤 공정은 AI에게 맡길 수 있고, 어떤 공정은 인간의 판단이 필수적인지'를 분리할 수 있는지가 평가되는 시대가 오고 있다. SES 프리랜서 전향을 고려하는 사람은, 먼저 상주처 업무 외에 작은 리포지토리를 하나 가져와 이 글의 설정을 한 번 쭉 시도해보는 것부터 시작하는 것이 현실적이라고 생각한다. 연봉 협상 자리에서도 'AI 에이전트 운영 설계가 가능하다'는 것은 단순히 'ChatGPT 쓸 수 있습니다'보다 설득력이 있다.

• CLAUDE.md는 계층화하고, @ 기호로 상세를 분리하는 것 - hooks로 위험 조작을 실행 전에 막는 장치를 넣는 것
• 서브에이전트로 본체의 컨텍스트를 오염시키지 않는 설계를 하는 것
• Plan Mode를 철저히 하여 계획 → 승인 → 실행의 단계를 무너뜨리지 않는 것
• MCP로 데이터 분석을 자동화하지만, 쓰기 권한은 주지 않는 것

이것들은 특별한 비법(裏技)이 아니라, Claude Code의 표준 기능을 조합했을 뿐이다. 화려한 자동화보다는 사고를 막는 장치를 쌓아 올리는 것이 결국 실무에서는 더 효과적이다.

• OpenClaw의 기억 × Claude Code의 실행으로 개발을 자율화하는 실천 기록
• 【2026년 최신】AI 코딩 툴 철저 비교 | Claude Code・Copilot・Cursor・Windsurf・Codeium 선택 방법
• 월 매출 250만, 직원 3명이 AI 경영 OS(CFO/COO/CMO)를 직접 만든 이야기

AI 구동塾 — AI를 사용한 스몰 비즈니스 만드는 법을 배운다

Claude Code, OpenClaw, AI 경영 OS의 실전 노하우를 매주 공개 중.

월액 ¥4,980으로 과거 기사 전체 무제한 열람 가능.

SES 해체 신서 프리랜서 DB에서는 고단가 건을 다수 게재하고 있습니다.

• ✅ 수수료율 공개로 투명한 거래
• ✅ AI/클라우드/웹 관련 엄선된 프로젝트
• ✅ 전담 코디네이터가 단가 협상을 지원