Claude Code를 제대로 쓰는 방법 -> Skills + Subagent + MCP + MSSQL 실전 구성
Claude Code를 제대로 쓰는 방법
Skills + Subagent + MCP + MSSQL 실전 구성
단순히 AI에게 코드를 작성시키는 단계에서 벗어나 프로젝트 규칙, 전문 역할, 데이터베이스 도구까지 연결하는 실무형 Claude Code 개발 환경을 구성하는 방법
검증 기준 : Claude Code 공식 문서 및 MSSQL MCP 프로젝트 공식 저장소
대상 환경 : Windows 개발 PC + ASP.NET/C# + Microsoft SQL Server
1. 먼저 결론부터
```Claude Code를 단순한 "코딩 챗봇"처럼 사용하는 것과 프로젝트 개발 환경의 일부로 사용하는 것은 큰 차이가 있습니다.
CLAUDE.md
프로젝트 전체의 기본 규칙과 개발 원칙
Skills
반복적으로 사용하는 전문 작업 절차
Subagents
SQL, 코드 리뷰, 테스트 등 전문 역할 분리
MCP
DB 등 외부 도구와 Claude 연결
처음부터 여러 Agent를 복잡하게 만드는 것보다 하나의 Claude Code + 명확한 규칙 + 필요한 도구부터 구축하는 것이 좋습니다. 복잡성이 실제 성능을 높여주는 경우에만 역할 분리와 다중 Agent 구조를 추가하는 방식이 안전합니다.
2. Claude Code 설치 — 2026년 현재 무엇을 설치해야 하나?
```현재 Claude Code 공식 설치 문서에서는 Native Install을 권장 방식으로 안내하고 있습니다. 예전처럼 Node.js와 npm 설치를 Claude Code의 필수 선행 조건으로 설명하면 정확하지 않습니다.
Native Install을 사용하는 경우 Node.js가 Claude Code 자체의 필수 조건은 아닙니다. npm 방식으로 설치할 경우에는 Node.js 18 이상이 필요합니다.
Windows PowerShell
irm https://claude.ai/install.ps1 | iex또는 WinGet
winget install Anthropic.ClaudeCode설치 확인
claude --version
```
claude doctornpm 방식도 현재 지원되지만, 새 Windows 환경을 구성한다면 공식 문서의 권장 방식인 Native Install부터 검토하는 것이 좋습니다.
3. CLAUDE.md는 무엇을 담당하는가?
```CLAUDE.md는 프로젝트 전체에 적용되는 기본적인 개발 규칙을 저장하는 곳으로 생각하면 이해하기 쉽습니다.
예를 들어
- ASP.NET MVC 5 프로젝트에서는 기존 패턴을 유지한다.
- SQL Server는 MSSQL 기준으로 작성한다.
- Dapper 사용 영역에서는 EF Core 패턴을 임의로 적용하지 않는다.
- DELETE, UPDATE, INSERT, DROP, TRUNCATE 등 데이터 변경 작업은 실행 전에 사용자 승인을 받는다.
- 기존 API 계약을 임의로 변경하지 않는다.
- 테스트가 필요한 경우 테스트 방법을 함께 제시한다.
다만 CLAUDE.md에 모든 절차를 계속 추가하다 보면 문서가 지나치게 커질 수 있습니다. 반복되는 전문 작업은 Skills로 분리하는 것이 더 적합합니다.
```4. Skills — 반복 작업을 전문 지식으로 분리하기
```Claude Code Skills는 반복해서 입력하는 지침이나 작업 절차를 재사용하기 위한 구조입니다.
프로젝트에서는 다음과 같은 형태로 구성할 수 있습니다.
.claude/
```
├─ skills/
│ ├─ sql-performance/
│ │ └─ SKILL.md
│ ├─ code-review/
│ │ └─ SKILL.md
│ └─ api-review/
│ └─ SKILL.md
├─ agents/
│ └─ sql-reviewer.md
└─ CLAUDE.mdSQL 성능 분석 Skill 예시
---
```
name: sql-performance
description: Analyze SQL Server query performance and suggest safe optimization approaches.
-------------------------------------------------------------------------------------------
# SQL Server Performance Review
## 기본 원칙
* 실행 계획을 먼저 확인한다.
* WHERE 조건과 JOIN 조건을 확인한다.
* 인덱스 사용 여부를 확인한다.
* SELECT * 사용 여부를 확인한다.
* 통계와 카디널리티 문제를 확인한다.
* 실제 데이터 변경은 수행하지 않는다.
## 결과 형식
1. 문제점
2. 원인
3. 개선 SQL
4. 인덱스 제안
5. 예상 효과
6. 주의사항CLAUDE.md는 프로젝트 전반에 적용할 기본 규칙에 적합하고, Skill은 SQL 튜닝, 코드 리뷰, API 설계처럼 특정 작업을 반복적으로 수행할 때 적합합니다.
5. Subagent — 역할을 분리하는 이유
```Subagent는 하나의 Claude Code 세션 안에서 특정 역할을 전문적으로 수행하도록 만든 별도의 작업 단위입니다. 각각 별도의 컨텍스트를 사용하기 때문에 메인 작업의 컨텍스트를 불필요한 분석으로 채우는 것을 줄일 수 있습니다.
예를 들어 SQL Reviewer를 만든다면
.claude/agents/sql-reviewer.md---
```
name: sql-reviewer
description: Reviews SQL Server queries for correctness, performance, indexing and safety.
model: sonnet
tools:
* Read
* Glob
* Grep
---
# SQL Reviewer
다음 기준으로 SQL을 검토한다.
1. 논리적 오류
2. JOIN 구조
3. WHERE 조건
4. 인덱스 활용
5. SARGability
6. 실행 계획 관점
7. 대량 데이터 처리
8. 트랜잭션 영향
9. 잠금 및 동시성
10. SQL Injection 가능성
데이터 변경 SQL은 실행하지 않는다.
결과는 다음 순서로 작성한다.
* 문제
* 원인
* 개선안
* 개선 SQL
* 주의사항model은 어떻게 지정할까?
| 모델 설정 | 실무 용도 |
|---|---|
inherit |
부모 Agent의 모델을 그대로 사용 |
opus |
복잡한 설계·추론이 중요한 작업 |
sonnet |
일반적인 개발·리뷰·분석 작업 |
haiku |
간단한 탐색·분류·보조 작업 |
Subagent가 항상 비용을 줄여준다고 단정하면 안 됩니다. Subagent의 중요한 장점은 전문 역할과 컨텍스트 분리이며, 실제 비용과 속도는 모델·작업량·호출 구조에 따라 달라집니다.
6. Subagent와 MCP를 함께 사용할 때 주의할 점
이 부분은 실무에서 특히 중요합니다.
Subagent는 기본적으로 부모 Agent의 도구를 상속할 수 있지만, tools를 명시적으로 제한하면 MCP 도구가 제외될 수 있습니다.
따라서 SQL Reviewer가 실제 MSSQL MCP 도구를 사용해야 하는 구조라면 단순히 Read, Grep, Glob 같은 도구만 허용하고 끝내서는 안 됩니다. MCP 서버의 범위를 의도적으로 구성해야 합니다.
- 이 Subagent가 DB를 실제로 조회해야 하는가?
- MCP 서버가 부모 Agent에서만 연결되어 있는 것은 아닌가?
- tools allowlist 때문에 MCP 도구가 빠지지 않았는가?
- 읽기 전용으로 제한되어 있는가?
- DB 계정 권한이 최소 권한인가?
7. MCP란 무엇인가?
MCP(Model Context Protocol)는 AI 애플리케이션과 외부 데이터 및 도구를 연결하기 위한 표준 프로토콜입니다.
따라서 MCP를 단순히 "외부 시스템 연결 플러그인"이라고만 이해하면 범위가 좁습니다. MCP 서버는 AI가 사용할 수 있는 도구와 리소스 등을 표준화된 방식으로 제공할 수 있습니다.
MCP Client 역할
외부 기능과 도구 제공
실제 데이터 저장소
8. Claude Code에 MSSQL MCP 연결하기
여기서는 예제로 codegiveness/mssql-mcp 프로젝트를 사용합니다.
이 프로젝트는 Microsoft가 공식적으로 제공하는 SQL MCP 서버가 아닙니다. 독립적인 오픈소스 프로젝트이며 C#/.NET 10으로 구현되어 있습니다. Microsoft 역시 별도의 MSSQL MCP Server를 MCP 서버 목록과 Data API builder 문서에서 제공하고 있으므로, 두 프로젝트를 같은 것으로 표현하면 안 됩니다.
Windows 설치
해당 프로젝트의 현재 README 기준 Windows 환경에서는 .NET 10 Runtime이 필요하며 다음과 같이 .NET Tool로 설치할 수 있습니다.
dotnet tool install -g codegiveness.mssql-mcp
mssql-mcp --version버전이 정상적으로 출력되면 MCP 서버 실행 파일을 사용할 수 있는 상태입니다.
```9. Claude Code의 .mcp.json 구성
```
Claude Code 프로젝트 수준의 MCP 설정은 프로젝트 루트의 .mcp.json으로 관리할 수 있습니다.
{
```
"mcpServers": {
"mssql-mcp": {
"command": "mssql-mcp",
"env": {
"MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
}
}
}
}
Windows에서 .NET Tool 방식으로 설치했기 때문에 여기서는 command를
mssql-mcp로 지정합니다.
DB 비밀번호가 들어간
.mcp.json을 Git 저장소에 그대로 커밋하지 마십시오.
특히 프로젝트 MCP 설정을 Git으로 공유할 경우 비밀정보 관리 방법을 별도로 설계해야 합니다.
10. MSSQL MCP에서 가장 중요한 보안 설정
```DB를 AI에 연결할 때 가장 먼저 생각해야 할 것은 "무엇을 할 수 있는가?"가 아니라 "무엇을 하지 못하게 할 것인가?"입니다.
1단계 — 읽기 전용 DB 계정
개발 DB라고 하더라도 AI용 계정에 운영자의 일반 계정 권한을 그대로 제공하지 않는 것을 권장합니다.
AI → MCP → 최소 권한 SQL Login → 필요한 DB/객체만 조회
단순히 db_datareader를 부여하는 것이 언제나 최소 권한이라는 의미는 아닙니다.
실제 운영환경에서는 필요한 데이터베이스와 객체에 필요한 권한만 제공하는 방향이 더 적절합니다.
2단계 — Restricted Mode 유지
codegiveness/mssql-mcp는 현재 기본 Access Mode가 Restricted입니다. 이 모드에서는 SQL AST 검증, 읽기 전용 트랜잭션, 명령 시간 제한 등의 보호 장치를 사용합니다.
반대로 Unrestricted Mode에서는 DML/DDL을 실행할 수 있으므로 운영 DB에서 기본값처럼 사용하는 방식은 피해야 합니다.
3단계 — 사용자가 최종 승인
가장 중요한 운영 원칙
SELECT가 아닌 INSERT / UPDATE / DELETE / DROP / TRUNCATE / ALTER 등의 데이터 변경 및 스키마 변경 작업은 AI가 자동 실행하지 않고 반드시 사용자의 명시적인 승인을 받은 후 실행하도록 구성한다.
11. 실제 SQL 개발에서는 어떻게 사용할까?
```나쁜 요청
프로젝트 목록 SQL 튜닝해줘.이 정도로 요청하면 AI가 실제 데이터 구조와 실행 계획을 충분히 알지 못한 상태에서 추측할 가능성이 있습니다.
좋은 요청
현재 연결된 MSSQL에서
```
usp_GetProjectList 프로시저를 분석해줘.
1. 프로시저 구조를 먼저 확인
2. 사용하는 테이블과 인덱스를 확인
3. 실행 계획을 분석
4. 병목이 예상되는 JOIN/WHERE를 확인
5. 개선안을 제시
6. 개선 SQL을 작성
7. 실제 UPDATE/DELETE/ALTER는 실행하지 말 것
8. 변경이 필요한 경우 먼저 나에게 승인 요청
실제 데이터 변경은 절대 실행하지 마.이렇게 요청하면 Claude가 단순히 SQL 문장을 수정하는 것이 아니라 스키마 → SQL → 실행 계획 → 인덱스 → 개선안의 순서로 접근할 수 있습니다.
```12. SQL Reviewer Subagent + MSSQL MCP 조합
```실무에서는 다음과 같은 역할 분리가 유용합니다.
| 역할 | 담당 | 권장 모델 방향 |
|---|---|---|
| Main Claude | 요구사항 분석·전체 구현 | 상황에 따라 Opus/Sonnet |
| SQL Reviewer | SQL·실행계획·인덱스 분석 | Sonnet 중심 |
| Code Reviewer | C#·ASP.NET 코드 리뷰 | Sonnet 중심 |
| Explorer | 프로젝트 구조 탐색 | 가벼운 모델 활용 가능 |
이것은 "무조건 Agent를 많이 만드는 구조"가 아닙니다. 한 Agent가 충분히 처리할 수 있는 업무는 한 Agent가 처리하고, SQL 분석처럼 명확한 전문성이 필요한 영역만 Subagent로 분리하는 것이 핵심입니다.
13. Claude Code + Skills + Subagent + MCP의 전체 구조
``` ┌──────────────────────┐
│ Claude Code │
│ Main Agent │
└──────────┬───────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌────────────┐ ┌─────────────┐
│ CLAUDE.md │ │ Skills │ │ Subagents │
│ 프로젝트 │ │ 전문 작업 │ │ 역할 분리 │
│ 기본 규칙 │ │ 절차 │ │ │
└───────────┘ └────────────┘ └──────┬──────┘
│
▼
┌─────────────┐
│ SQL Agent │
└──────┬──────┘
│
▼
┌─────────────┐
│ MCP │
│ MSSQL Server│
└──────┬──────┘
│
▼
┌─────────────┐
│ SQL Server │
│ Database │
└─────────────┘14. 추천 프로젝트 디렉터리
```MyProject/
```
│
├─ .claude/
│ │
│ ├─ agents/
│ │ ├─ sql-reviewer.md
│ │ ├─ code-reviewer.md
│ │ └─ api-reviewer.md
│ │
│ └─ skills/
│ ├─ sql-performance/
│ │ └─ SKILL.md
│ ├─ code-review/
│ │ └─ SKILL.md
│ └─ deployment-check/
│ └─ SKILL.md
│
├─ .mcp.json
├─ CLAUDE.md
│
├─ src/
├─ tests/
└─ README.md15. 처음부터 이렇게 만들지 말고 단계적으로 구축하자
```설치하고 프로젝트에서 정상적으로 코딩 가능한지 확인
프로젝트 규칙과 금지사항을 정리
반복되는 SQL 튜닝·코드 리뷰 절차를 분리
SQL Reviewer 등 전문 역할을 분리
실제 DB와 외부 시스템을 연결
권한·승인·로그·비밀정보·실행 범위를 관리
16. 특히 SQL 개발자는 이 원칙을 지키자
```AI에게 DB 권한을 주기 전에 확인할 것
- 운영 DB를 직접 연결하지 않는다.
- 가능하면 개발/테스트 DB를 사용한다.
- AI 전용 SQL 계정을 만든다.
- 최소 권한을 적용한다.
- 기본은 Read Only로 구성한다.
- DELETE / UPDATE / INSERT 실행을 자동화하지 않는다.
- DROP / TRUNCATE / ALTER는 특히 엄격하게 제한한다.
- 비밀번호를 Git에 저장하지 않는다.
- MCP 설정 파일을 저장소에 커밋할 때 Secret 포함 여부를 확인한다.
- AI가 제안한 SQL과 실제 실행한 SQL을 구분한다.
17. 실무 CASE STUDY — 느린 MSSQL 프로시저 분석
```상황
ASP.NET MVC 시스템에서 프로젝트 목록을 가져오는 Stored Procedure가 느려졌다고 가정합니다.
기존 방식
프로시저가 느린데 튜닝해줘.Claude Code + MCP 방식
usp_GetProjectList를 분석해줘.
```
1. 프로시저 정의 확인
2. 참조 테이블 확인
3. 주요 컬럼과 인덱스 확인
4. 실행 계획 분석
5. 예상되는 병목 구간 분석
6. 대량 데이터 처리 문제 확인
7. JOIN / WHERE / ORDER BY 검토
8. 인덱스 개선안 제시
9. SQL 개선안을 제시
10. 변경 SQL은 실행하지 말고 결과만 제시
UPDATE, DELETE, INSERT, DROP, ALTER, TRUNCATE는
절대 실행하지 말 것.결과
AI가 실제 DB 스키마와 실행 계획을 확인할 수 있다면 단순히 SQL 문법을 수정하는 수준을 넘어 데이터 구조와 실행 특성을 고려한 분석이 가능해집니다.
18. 설치 후 확인 체크리스트
```19. 자주 묻는 질문
```Node.js가 반드시 필요한가?
Claude Code Native Install 자체에는 Node.js가 필수라고 볼 수 없습니다. npm을 이용해 설치하는 경우 Node.js 18 이상이 필요합니다.
Subagent를 많이 만들수록 좋은가?
아닙니다. 전문 역할이 명확한 경우에만 분리하는 것이 좋습니다. 단순한 작업까지 Subagent로 분리하면 오히려 구조가 복잡해질 수 있습니다.
MCP를 연결하면 Claude가 DB를 마음대로 수정할 수 있는가?
MCP 서버의 구현과 권한 설정에 따라 달라집니다. 따라서 AI 전용 DB 계정의 최소 권한, MCP의 접근 모드, 도구 권한을 함께 제한해야 합니다.
MSSQL MCP는 Microsoft 공식 제품인가?
이 글에서 예제로 사용한 codegiveness/mssql-mcp는 Microsoft 공식 제품이 아니라 독립 오픈소스 프로젝트입니다. Microsoft 역시 별도의 MSSQL MCP Server와 SQL MCP 관련 문서를 제공하고 있으므로 구분해서 봐야 합니다.
SQL 변경 작업도 AI에게 맡겨도 되는가?
가능 여부와 별개로 운영 정책을 먼저 정하는 것이 중요합니다. 특히 DELETE, UPDATE, INSERT, DROP, TRUNCATE, ALTER와 같은 변경 작업은 사람이 최종 SQL과 대상을 확인하고 승인한 뒤 실행하도록 구성하는 것을 권장합니다.
20. 최종 정리
```Claude Code를 제대로 활용한다는 것은 단순히 더 좋은 모델을 선택하는 문제가 아닙니다.
프로젝트의 규칙을 CLAUDE.md로 정리하고, 반복 작업을 Skills로 만들며, 전문 작업을 Subagent로 분리하고, 실제 DB와 같은 외부 시스템은 MCP로 연결하는 구조가 핵심입니다.
그리고 데이터베이스를 연결하는 순간부터는 AI의 능력보다 권한·승인·보안·감사 정책이 더 중요해집니다.
특히 MSSQL 개발 환경에서는 "AI가 SQL을 작성할 수 있다"보다 "AI가 실제 DB를 조회하면서도 변경 작업은 사람이 통제한다"는 구조를 먼저 만드는 것이 중요합니다.
출처 및 공식 문서
```- Anthropic Claude Code 공식 설치 문서
- Anthropic Claude Code 공식 Subagents 문서
- Anthropic Claude Code 공식 Skills 문서
- Anthropic Claude Code 공식 MCP 문서
- codegiveness/mssql-mcp GitHub 저장소
- Microsoft MCP Server 저장소
- Microsoft SQL MCP / Data API builder 공식 문서
Claude Code, MCP 서버, 모델명, CLI 옵션 및 설치 방식은 계속 변경될 수 있습니다. 특히 MCP 서버는 프로젝트별 버전 차이가 있으므로 실제 설치 시 해당 프로젝트의 최신 README와 공식 문서를 다시 확인하는 것을 권장합니다.
해시태그
#ClaudeCode #Claude #Anthropic #MCP #ModelContextProtocol #MSSQL #SQLServer #AI개발 #AI코딩 #Subagent #Skills #CSharp #ASPNet #개발자동화 #개발생산성
대화 참여하기