머리말
오랜만에 포스트를 적어봅니다. 노력하지만 별개로 최종 합격을 경험하지 못한 상태네요. 외부 상황이 좋지 않다느니 공급과 수요가 무너진 시장이라느니 부정적 소식은 들리지만 저는 꿈을 이뤄보고 싶어 취업의 문을 멈추지 않고 두드리는 중입니다. 그동안 선생님이자 서포터로써 저의 개발을 도와준 친구에 대해서 오늘은 적어볼까 합니다.
그 친구는 바로 Claude Code입니다.
지금까지 LLM을 코드 어시스턴트 에이전트용으로 GPT, Cursor, Claude를 사용해봤습니다. 현재는 Cursor와 Claude만 Pro 플랜을 구독하여 사용중이에요. 요즘의 프론트엔드 개발자 분들은 거의 이 조합으로 많이 사용하는 것으로 알고 있고, 실제로 구글의 Gemini나 OpenAI의 GPT보다 프론트엔드 개발에 있어서는 압도적으로 좋다고 느꼈습니다.
출처: https://huggingface.co/spaces/lmarena-ai/chatbot-arena
lmarena의 chatbot-arena에서는 Claude의 모델들이 1위를 포함하여 TOP 10에 총 7개의 모델이나 있네요.
Claude는 아무 세팅없이 요구를 해도 잘 수행하는 편이지만, 노베이스에서 질문이나 명령을 하는 것보다는 내가 원하는 것에 대한 단서와 정보를 Claude가 이해할 수 있는 맥락으로 제공하면, 의도하는 것을 거의 정확하게 결과로 만들어 줍니다. 이게 Claude의 핵심이라고 생각합니다. 그래서 맥락 기반 엔지니어링, ‘컨텍스트 엔지니어링’에 대해 제가 아는 대로 알려드리도록 하겠습니다. Cursor와 Claude를 둘 다 사용하지만, 일반적으로 요즘은 Claude Code로 대부분 개발을 진행하고 Cursor Agent는 Tab(코드 자동완성)과 간단한 퍼블리싱 활용을 위해서 서브로 사용하는 중이므로 포스트에서는 Claude Code만 다루겠습니다.
컨텍스트 엔지니어링
Claude Code를 좀 더 다양한 능력을 가진 에이전트로 보기 위해서는, 먼저 컨텍스트 엔지니어링라는 컨셉을 이해하면 좋을 것 같습니다.
컨텍스트 엔지니어링(Context Engineering)이란, LLM이 모든 사실, 규칙, 문서, 계획, 도구를 아우르는 전체적인 맥락 생태계를 가질 수 있도록 환경 전체를 설계하는 시스템 공학입니다.
참고: https://blog.langchain.com/context-engineering-for-agents/
지금은 에이전트가 기획 단계부터 배포, 코드 리뷰까지 모두 하는 시대입니다. 에이전트를 활용하는 능력조차 개발자가 가져야 하는 생존 역량이 된 거 같네요. 기업의 대규모 서비스나 개인 개발자도 에이전트 활용을 얼마나 잘 하느냐에 따라 투입한 리소스 대비 만들어내는 산출량이 좌우되기 때문이죠. 실제로 채용공고에서도 에이전트 활용 능력이 좋은 사람을 찾고 있는 곳이 늘고 있는 것 같습니다.
초기에 시간을 투자해서 에이전트가 코드 어시스트를 위한 맥락을 꼼꼼하게 구축하면, 밀도 높은 기획부터 정확하고 빠른 구현을 할 수 있게 되어 소중한 시간이 많이 절약됩니다. 절약한 시간은 개발자가 아키텍트 점진적 고도화, 코드 리뷰에 투자하여 코드 품질의 상향 평준화를 달성하는 결과를 만들어내는데에 사용하면 이것은 서비스의 성장과 안정과 연결되고, 다시 사용자의 증가와 재사용율과 연결되고, 궁극적으로는 매출로 이어질 수 있는 연결고리를 가진다고 생각합니다.
클로드 코드 기본 5개념
Claude Code는 Claude Desktop에 비해서 에이전틱 코딩에 특화되어 있는 CLI 버전의 Claude입니다.
터미널에서 프로젝트 경로에 접속하여 내 프로젝트의 파일과 코드를 읽고, 나의 요청(혹은 명령)을 수행하는 에이전트로 활동하기 위해 만들어진 친구죠. Claude Code로 컨텍스트 엔지니어링을 실현하기 위해서 알면되는 개념으로 5개만 확실히 알고 있으면 됩니다.
CLAUDE.md
프로젝트별 컨텍스트를 얻기 위해 자동으로 흡수하는 특별한 마크다운 파일입니다.
프로젝트의 핵심 정보를 Claude Code에게 미리 학습시켜 언제나 일관된 컨텍스트를 유지하며 코딩하게 할 수 있습니다.
저는 개인 프로젝트에서 사용하는 코드 패턴이 동일해서 제가 사용하는 코드 스타일을 기반으로 Claude Code가 코드를 생성하고 수정할 수 있게 최상단에 룰을 명시하는 편입니다.
예시
## MUST DO ALWAYS
- 항상 한국어로 대답합니다.
## 싱글라인 스코프 구현 패턴
**if, 화살표 함수의 스코프 내부 실행문이 싱글라인일 경우, {}를 절대 사용하지 않습니다.**
// if
if (!res.ok) return { success: false, message: '에러가 발생했습니다.'};
// arrow function
const yell = () => console.log('SIbal!!!');
## 선언적 프로그래밍
- SSR, PPR 페이지의 일괄적인 로딩 상태는 loading.tsx를 생성하여 핸들링합니다.
- 컴포넌트 단위 로딩 상태는 Suspense를 감싸서 핸들링합니다.
- 컴포넌트 단위 에러 핸들링은 컴포넌트 내부 처리 혹은 ErrorBoundary로 감싸서 처리합니다.
// ... 필요한 컨벤션은 추가 작성여러분도 자신만의 코드 규칙이나 팀의 규칙을 CLAUDE.md에 저장하여 추가 수정의 필요를 없애보세요.
유용한 특성
CLAUDE.md는 프로젝트 루트에 위치시켜두면 글로벌한 규칙으로 적용시킬 수 있는데, 각 디렉토리 별로 CLAUDE.md를 만들어두면 해당 경로와 하위의 경로들에만 적용되는 규칙을 별도로 적용시킬 수도 있습니다. 그래서 글로벌한 규칙은 루트에, 각 도메인별 디렉토리에는 해당 도메인에 맞는 규칙만 작성하여 위치시켜 규칙 관리를 좀 더 독립적으로 할 수 있게 만들어줍니다.
Commands, 슬래시 명령어
공식 개념
/ 로 시작하는 명령어를 사용하여, 프롬프트를 일일이 입력하지 않고 원하는 요청을 합니다.
슬래시 명령어는 기본 제공되는 명령어와 사용자 정의 명령어로 나뉘어져있습니다.
저는 주로 사용하는 기본 명령어를 정리해두고 사용하고 있습니다. 아래와 같습니다.
| 명령어 | 의미 |
|---|---|
/init | 전체 Context, docs/**를 읽고 CLAUDE.md 생성 |
/model | 모델 전환 |
/config | 세팅 값 변경 가능, Use todo list 활성화 |
/output-style:new - | 출력 템플릿을 원하는 스타일로 요구 |
/clear | 대화 비우기, 컨텍스트 초기화 |
/context | 컨텍스트 용량 상태 확인 |
/compact | 대화 비우기, 컨텍스트 요약 |
/resume | 생성된 세션들 중 선택해서 다시 대화 시작 |
/export | 대화 세션 전체를 클립보드로 복사 |
shift + Tab | 모드 전환 |
| `lsof -ti:3000 | xargs kill -9` |
/init 같은 경우에는 프로젝트를 만들고 나서 바로 사용하는 게 아니라, 어느정도 프로젝트 내에 맥락을 읽을 만큼의 코드가 있는 상황일 때 써야 Claude Code가 이를 분석해서 현재 프로젝트의 코드 패턴을 CLAUDE.md에 업데이트하기 때문에 개발이 30% 이상 이루어지고 나서부터 사용하면 좋을 것 같습니다.
사용자 정의 명령어는 프로젝트 명령어나 개인 명령어로 구분할 수 있습니다.
- 프로젝트 명령어: 해당 프로젝트에서만 사용할 수 있는 명령어입니다. 저장소에 저장됩니다.
.claude/commands/에OO.md이름으로 위치 시키기
- 개인 명령어: 모든 프로젝트에서 사용 가능한 명령어입니다. PC에 글로벌하게 저장됩니다.
~/.claude/commands/에OO.md이름으로 위치 시키기
Agents, 서브 에이전트
공식 개념
Claude Code에서 특화된 AI 서브에이전트를 생성하고 사용하여 작업별 워크플로우 및 개선된 컨텍스트 관리를 수행합니다.
- 특정 목적과 전문 분야를 가지고 있습니다
- 주 대화와 분리된 자체 컨텍스트 윈도우를 사용합니다
- 사용할 수 있는 특정 도구로 구성할 수 있습니다
- 동작을 안내하는 커스텀 시스템 프롬프트를 포함합니다
특징
| 특징 | 설명 |
|---|---|
| 컨텍스트 보존 | 각 서브에이전트는 자체 컨텍스트에서 작동하여 주 대화의 오염을 방지합니다. |
| 특화된 전문성 | 서브에이전트는 특정 도메인에 대한 상세한 지침으로 미세 조정될 수 있습니다. |
| 재사용성 | 한 번 생성되면, 서브에이전트는 다양한 프로젝트에서 사용될 수 있으며 팀과 공유하여 일관된 워크플로우를 구현할 수 있습니다. |
| 유연한 권한 | 각 서브에이전트는 다양한 도구 접근 수준을 가질 수 있습니다. ex) 특정 MCP 서버 사용 |
Agent Skills
Agent Skills는 프롬프트를 매번 복붙할 필요 없이 정해진 워크플로를 재사용 가능한 스킬로 만들어 두면, Claude Skills가 설명을 읽고 실행하는 거라고 생각하시면 됩니다. Agents, Commands는 사용자가 트리거하지만, Agent Skills는 Claude Code가 사용자의 요청을 분석해서 자율적으로 적절한 스킬의 사용 시기를 결정합니다.
사용법
.claude/skills/- 경로 아래에 반드시 SKILLS.md 파일을 위치시켜야 합니다.
여기서 description은 Claude가 적절한 Skill을 발견하는 데 가장 중요한 부분입니다.
- 무엇을 하는지 명확히 작성
- 언제 사용할지 구체적으로 명시
- 사용자가 언급할 핵심 키워드를 포함
파일은 YAML 프론트매터와 Markdown 콘텐츠가 포함되어있습니다. /skills에 존재하는 모든 스킬의 프론트매터는 항상 토큰을 차지하고 있습니다. 모든 스킬의 정보를 Claude Code가 미리 알고 있어야 적절하게 사용할 수 있기 때문입니다.
예시
.claude/skills/
├── SKILL.md
├── scripts/
│ ├── helper.py
│ └── process.sh
├── templates/
│ └── template.json
└── examples/
└── example-output.txt사용상의 이점
1. 워크 플로우 확장
- 특정 작업에 대한 Claude의 능력을 확장할 수 있습니다.
- 회사만의 특별한 프로세스도 Skills로 만들 수 있습니다.
2. 전문 지식 공유
- Git을 통해 팀 전체에서 노하우를 공유합니다.
- 시니어 개발자의 지식을 주니어도 바로 활용할 수 있습니다.
3. 프롬프팅 감소
- 매번 같은 설명을 반복할 필요가 없습니다. 계속 재사용할 수 있어요.
4. 복잡한 작업 수행
- 여러 Skills를 조합해서 복잡한 워크플로우를 자동화할 수 있습니다.
5. Deterministic(결정론적인)한 결과
- LLM은 Non-deterministic한 특성을 가지고 있지만, Deterministic한 결과를 나오게 합니다.
- Deterministic: input이 동일하면 항상 output이 동일
스킬 생성이 적절한 경우
- 반복성: 같은 형태의 작업을 주기적으로 해야 할 때 (주간 보고서, 월간 분석 등)
- 일관성: 결과물의 품질과 형식이 일관되어야 할 때
- 복잡성: 여러 단계를 거쳐야 하는 워크플로 (데이터 → 엑셀 → PPT → PDF)
- 전문성: 도메인 전문 지식이 필요한 작업 (재무 모델링, 생물정보학 분석 등)
스킬 생성을 하기에는 과한 경우
- 일회성 작업: 한 번만 할 작업이라면 스킬 만드는 게 오히려 비효율적
- 간단한 변환: "이 텍스트를 표로 만들어줘" 같은 단순 작업
- 창의적 작업: 브레인스토밍, 아이디어 발산 등 자유로운 사고가 필요한 작업
MCP
여러 MCP 서버를 연결해서 사용할 수 있습니다. 당연히 서브 에이전트가 특정 MCP 서버를 실행하게 만들거나, 커맨드에서 MCP를 사용하게 하거나, 스킬에도 MCP를 트리거시킬 수 있죠.
기본 명령어
# 설치를 위한 기본 명령어 템플릿
claude mcp add <이름> <명령어> [args...]
# 프로젝트 스코프로 설치
claude mcp add shared-server --scope project /path/to/server
# 연결된 모든 MCP 서버 조회
claude mcp list
# 서버 제거
claude mcp remove <서버 이름>.mcp.json
MCP 서버도 명령어처럼 범위를 선택해서 설치할 수 있습니다.
.mcp.json을 범위에 맞게 위치시키면 아래와 같은 과정을 거쳐 MCP 서버를 연결합니다.
- 자동 감지
- .mcp.json 파일을 프로젝트 루트에 배치하면 Claude Code가 자동으로 감지합니다.
- 별도의 설치 명령어 없이도 파일을 읽습니다.
- 승인 필요
- 서버가 자동으로 시작되기 전에 사용자 승인을 요청합니다.
- 처음 실행 시 각 서버에 대한 승인 프롬프트가 표시됩니다.
- 승인 후에는 자동으로 시작됩니다.
- 범위별 위치
- 프로젝트 범위: 프로젝트 루트의 .mcp.json (팀과 공유, 버전 관리에 포함)
- 로컬 범위: .claude/settings.local.json (개인용, 버전 관리에서 제외)
- 사용자 범위: ~/.claude/settings.json (모든 프로젝트에서 사용)
Agents vs Commands vs Skills
서브 에이전트, 커맨드, 스킬의 특징을 비교해보았습니다.
| 특징 / 요소 | Agents | Commands | Skills |
|---|---|---|---|
| 실행 방식 | Implicit | Explicit | Implicit |
| 단계적 공개 = 컨텍스트 소모 | Full | Full | Progressive |
| 실행 컨텍스트 | Subagent | Main Agent | Main Agent |
| 결정론적 | Non-deterministic | Non-deterministic | Deterministic |
각 요소를 언제 사용하면 좋을까요?
Agents
- 복잡하고 다단계 탐색이 필요할 때
- 여러 번 시도가 필요할 때
- 코드베이스 구조 파악, 오픈엔드 질문
- 독립적인 하위 작업을 병렬로 처리할 때
Commands
- 반복 가능한 워크플로를 실행할 때
- 단순하고 특정된 행위 하나를 요청하고 싶을 때
Skills
- 특정 파일 포맷 처리(PDF, XLSX 등)가 필요할 때
- 점진적으로 컨텍스트를 확장하며 작업하고 싶을 때
- 도메인 특화 작업이 반복될 때
실제 사용예시
CLAUDE.md
이전 챕터에서 보여드린 예시를 참고하시면 됩니다.
추가로 알려드리면, 아래의 명령어를 터미널에서 실행하면 Cursor Rules를 포인터로 CLAUDE.md에 업데이트 해주니 필요하시면 사용해보세요.
npm: npm dlx cursor2claude sync
pnpm: pnpm dlx cursor2claude sync
Commands
위에서 말했듯 개인 범위로는 ~/.claude/commands/, 프로젝트 범위로는 .claude/commands/에 마크 다운 파일을 위치시켜주면 됩니다.
make_plan.md
# OOO 아이디어 기획서 제작
**당신은 서비스 개발을 위해 아이디어 기획서를 제작하는 PM입니다.**
개발자로부터 다음의 질문에 대한 답변을 얻고, 답변에 기반하여 아래의 챕터에 맞춰 기획서를 작성하세요.
1. 만들고자 하는 서비스의 컨셉은 무엇인가요?
2. 서비스에서 제공할 핵심 기능에 대해서 설명해주세요.
3. 서비스에서 내고 싶은 분위기, 참고할 디자인에 대해서 설명해주세요.
---
## 📋 서비스 개요
### 🎯 서비스 미션
### 🎯 핵심 가치 제안
### 🎯 타겟 사용자
## 🏎️ 서비스 핵심 기능
## 📌 핵심 차별화 포인트
## 📅 기술 구현 전략
## 📈 시장 기회 & 경쟁사 분석
## 📏 비즈니스 모델 아이디어
## ✅ 예상 결과물
## 🔬 확장 전략
## 😊 기대 효과documentation.md
목표
특정 파일의 interface, 함수, 클래스의 JSDocs 주석 추가
# Document Code
Please add comprehensive documentation(TSDocs) to the code in the current file. $ARGUMENTS
For each interface, function and class:
- @description: 이 인터페이스, 함수, 클래스에 대한 명확하고 간단한 설명 문장
- @params: 파라미터 설명
- @types: 타입 설명
- @return: 반환 값 설명
- Please Create in Korean
Follow the project's existing documentation style.centralize-paths.md
목표
Paths Factory에 흩어져 하드코딩되어있는 내외부 URL들을 모두 모으기
# Centralization Paths
src: `@lib/api/paths.ts`
## 해야할 일
서버 액션, API 라우트 핸들러에서 비동기 요청을 위한 경로는 모두 중앙화하여 관리하고 참조하는 방식으로 사용합니다.
클라이언트 컴포넌트에서 라우트 핸들러를 요청하는 경로는 INTERNAL_PATHS, 서버 액션과 라우트 핸들러에서 외부 API로 요청하는 엔드포인트는 EXTERNAL_PATHS에 저장합니다.
서버 액션, 라우트 핸들러, 컴포넌트, 훅 등에서 하드코딩으로 경로를 명시하고 있다면 중앙화 후 참조하는 방식으로 변경하세요.Agents
e2e-refactoring-master.md
역할
테스트 코드 리팩토링
---
name: e2e-refactoring-master
description: E2E 테스트의 목적과 본질에 맞게 테스트 코드의 품질을 높이는 리팩토링 마스터 서브 에이전트입니다.
model: sonnet
color: red
---
# E2E 테스트 리팩토링 계획
당신은 QA 마스터입니다. 현재 작성된 E2E 테스트 코드를 분석하고, 아래의 조건을 반영하여 테스트 코드의 품질을 높이고
일관된 구조를 가진 테스트 코드로 개선시키는 것이 임무입니다.
## 🎯 로케이터 우선순위 적용
#### 1. getByRole()
#### 2. getByLabelText() / getByLabel()
#### 3. getByPlaceholderText()
#### 4. getByText()
#### 5. getByDisplayValue()
#### 6. getByAltText()
#### 7. getByTitle()
#### 8. getByTestId()
#### 9. locator()
## 🎯 describe(테스트 스위트) 범위 개선
- 기능 또는 컴포넌트 단위로 그룹화하세요.
- 사용자 시나리오 또는 특정 조건(Context)을 기반으로 그룹화하세요.
- beforeEach / afterEach 훅으로 페이지 이동 또는 기능 반복 줄이세요.
- 'OO 테스트'의 템플릿으로 테스트 스위트의 이름을 붙이세요.
## 🎯 test(테스트 케이스) 개선
- 하나의 테스트 케이스는 단일 책임을 가진 범위로 가볍게 만들어야 합니다.
- 페이지 전체, 그리고 상세한 UI 렌더 테스트는 하지 않습니다.
- 핵심 컨텐츠의 렌더링 확인과 요소의 개수를 확인하세요.
- 사용자 인터랙션 요소의 유효성 검증과 실행 후 결과 확인을 작성하세요.
- 테스트 내부에 동작별 설명 목적의 주석을 기입하세요.
## 🔌 테스트 지속 개선
### Playwright MCP를 사용
- mcp 서버를 실행하여 수정한 테스트가 올바르게 작동하는지 확인하세요.
- 실패하는 테스트 케이스가 있을 경우, 다시 개선하고 확인합니다.
- 모든 테스트 케이스가 통과할 때까지 수정하세요.
## ✅ 개선 결과 요약 생성
- 개선 결과에 대해서 코드 라인 감소, 구조, 유지보수 측면에서의 향상점을 위주로 성과 요약표를 .md 파일로 생성하세요.Skills
스킬은 제가 실제로 사용하지는 않아 모범 사례로 대체합니다.
- 개인 프로젝트가 모두 완성되어있는 상태이고 CLAUDE.md와 커맨드로 충분히 리팩토링할 수 있는 상태이므로, 추후에 필요하면 스킬을 구축해보려 합니다.
모범 사례 1. 단일 책임
하나의 Skill = 하나의 기능
- "PDF 양식 작성"
- "Excel 데이터 분석"
- "Git 커밋 메시지 생성"
모범 사례 2. 명확한 설명: 트리거 키워드 포함
**description**: "React 컴포넌트 생성. 'React', '컴포넌트', 'JSX'를 언급할 때 사용”모범 사례 3. 버전 릴리즈 노트
## 버전 기록
### v1.1.0 (2025-11-23)
- PDF 암호화 지원 추가
- 에러 처리 개선
### v1.0.0 (2025-11-01)
- 초기 릴리스
- 기본 PDF 양식 작성 기능MCP
제가 사용하고 있는 MCP 서버 목록이 담긴 json입니다.
“—your-token”이라고 되어있는 부분은 직접 토큰을 발급받아 대체하시면 됩니다.
.mcp.json
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--access-token",
"--your-token"
]
},
"context7": {
"command": "npx",
"args": [
"-y",
"@upstash/context7-mcp"
]
},
"playwright": {
"command": "npx",
"args": [
"-y",
"@executeautomation/playwright-mcp-server"
]
},
"shadcn-ui": {
"command": "npx",
"args": [
"@jpisnice/shadcn-ui-mcp-server",
"--github-api-key",
"--your-token"
]
},
"chrome-devtools": {
"command": "npx",
"args": [
"chrome-devtools-mcp@latest"
]
}
}
}Claude Code를 더 풍부하게 해주는 기타 도구
Super Claude
https://github.com/SuperClaude-Org/SuperClaude_Framework
Super Claude는 다음과 같은 특징을 가진 복잡한 업무를 실행하게 해주는 명령어 프레임워크입니다.
🛠️ 17개의 전문 명령어 - 일반적인 개발 작업을 위한 특화된 도구들
🎭 스마트 페르소나 - 다양한 도메인에 맞는 전문가가 자동으로 선택됩니다
🔧 MCP 서버 통합 - 문서, UI 컴포넌트, 브라우저 자동화 등
📋 작업 관리 - 진행 상황을 추적하고 관리
⚡ 토큰 최적화 - 더 긴 대화를 위한 효율적인 토큰 사용
바이브 코더들이 더 효율적인 Claude Code 활용을 위해 개발해낸 것 같습니다.
저는 예전에 사용했었는데, 기본 명령어와 제가 커스텀으로 만든 명령어 + 프롬프트로도 충분한 것 같아 사용하고 있지는 않습니다.
Claude Code Template
많은 개발자들이 서브 에이전트, 커맨드, 설정, 훅, MCP 서버 등을 템플릿으로 만들어두어 누구나 npx 명령어로 프로젝트에 바로 설치하여 사용할 수 있게 해뒀습니다. 사용해봐야지 하고 사용해 본 적은 없습니다.
마무리
Claude Opus 4.5 모델이 최근 출시하여 현재 LLM 모델에서 개발 성능은 압도적으로 1위를 하고 있네요. 내년에도 개발 분야에서의 1위는 Claude가 계속 장악하고 있을지 기대가 됩니다. 눈뜨면 새로운 LLM 모델과 기술의 출시, 신기능 추가와 새로운 패러다임의 등장... 신입 개발자의 자리는 점점 좁아지고 있는데 그만큼 혼자 개발하는 입장에서 더 많은 결과물을 시도해볼 수 있다는 아이러니까지... 참 정신없는 시대인거 같습니다. 아무튼 Claude Code와 함께 생산성 높은 개발하세요:)
