Claude Code를 제대로 쓰는 방법
Skills + Subagent + MCP + MSSQL 실전 구성
Claude Code를 단순한 코딩 챗봇으로 사용하는 단계를 넘어 프로젝트 규칙, 재사용 가능한 작업 지침, 전문 역할, MSSQL 도구를 연결하는 실무형 개발 환경을 구성하는 방법을 정리합니다.
검증 범위 : Anthropic Claude Code 관련 공식 자료, Microsoft SQL MCP/Data API builder 공식 문서, MCP GitHub 프로젝트 문서
대상 환경 : Windows 개발 PC · ASP.NET/C# · Microsoft SQL Server
중요 : 설치 명령과 MCP 서버 기능은 버전에 따라 변경될 수 있으므로 실제 적용 직전에 공식 문서와 저장소의 최신 내용을 다시 확인해야 합니다.
1. 먼저 결론부터
Claude Code를 잘 활용하는 핵심은 에이전트를 많이 만드는 것이 아닙니다. 프로젝트 규칙 → 반복 작업 지침 → 필요한 전문 역할 → 외부 도구를 필요한 만큼만 분리하는 것입니다.
CLAUDE.md
프로젝트에서 항상 지켜야 할 규칙과 맥락
Skills
특정 작업을 수행할 때 재사용하는 전문 지침
Subagents
보안·성능·리뷰처럼 별도 역할이 유용한 작업
MCP
DB와 같은 외부 도구·데이터 시스템 연결
처음부터 다중 에이전트 구조를 만들기보다 하나의 Claude Code 세션에서 작업을 시작하고, 반복되는 작업은 Skills로, 독립적인 전문 분석은 Subagent로, 외부 시스템 접근은 MCP로 분리하는 편이 구조를 이해하고 통제하기 쉽습니다.
2. Claude Code 설치 — Windows에서는 무엇을 확인해야 하나?
Claude Code의 설치 방법은 변경될 수 있으므로 설치 시점의 Anthropic 공식 설치 문서를 기준으로 확인해야 합니다. 이 글에서는 Windows에서 공식 설치 흐름을 확인한 뒤 설치 상태를 검증하는 것을 목표로 합니다.
설치 후 가장 먼저 확인할 명령
claude --version
claude doctor
claude --version으로 설치된 Claude Code 버전을 확인합니다.claude doctor로 설치 및 환경 관련 진단을 수행합니다.- 실제 설치 명령은 사용 중인 Claude Code 공식 문서의 현재 Windows 설치 방법을 우선합니다.
예전 npm 설치 방식만을 전제로 “Claude Code를 사용하려면 Node.js가 반드시 필요하다”고 설명하는 것은 현재 설치 구조를 정확하게 전달하지 못할 수 있습니다. 따라서 설치 방법과 Node.js 요구 조건은 사용한 설치 경로에 따라 구분해야 합니다.
3. CLAUDE.md — 프로젝트의 기본 규칙을 어디에 둘까?
CLAUDE.md는 Claude Code가 프로젝트를 작업할 때 참고해야 하는 프로젝트 수준의 지침과 맥락을 문서화하는 데 사용할 수 있습니다.
ASP.NET + MSSQL 프로젝트에서 넣을 수 있는 규칙 예시
- ASP.NET/C# 기존 아키텍처와 네이밍 규칙을 우선한다.
- SQL Server를 기준으로 SQL을 작성한다.
- Dapper 영역에 EF Core 패턴을 임의로 도입하지 않는다.
- 기존 API 계약과 데이터 모델을 임의로 변경하지 않는다.
- DB 변경 SQL은 실행 전에 사용자 승인을 받는다.
- 운영 DB를 개발 작업의 기본 대상으로 사용하지 않는다.
- 테스트하지 않은 코드를 테스트 완료라고 표현하지 않는다.
예시 구조
MyProject/
├─ CLAUDE.md
├─ .claude/
├─ .mcp.json
├─ src/
└─ tests/
중요한 점은 CLAUDE.md를 모든 작업의 세부 매뉴얼로 만들지 않는 것입니다. 특정 작업에서만 필요한 긴 절차는 Skills로 분리하는 편이 관리하기 쉽습니다.
4. Skills — 반복되는 전문 작업을 분리한다
Claude Code의 Skills는 특정 작업에 필요한 지침과 보조 파일을 재사용 가능한 단위로 구성하는 데 사용할 수 있습니다. Anthropic의 공식 Claude Code 관련 저장소에서도 Skill을 SKILL.md를 중심으로 디렉터리 단위로 구성하는 형태를 확인할 수 있습니다.
추천 구조
.claude/
└─ skills/
├─ sql-performance/
│ └─ SKILL.md
├─ code-review/
│ └─ SKILL.md
└─ api-review/
└─ SKILL.md
SQL 성능 분석 Skill 예시
---
name: sql-performance
description: Analyze SQL Server query performance and suggest safe optimization approaches.
---
# SQL Server Performance Review
## 분석 순서
1. 대상 SQL과 호출 경로를 확인한다.
2. 사용하는 테이블과 주요 컬럼을 확인한다.
3. WHERE, JOIN, GROUP BY, ORDER BY를 검토한다.
4. 인덱스와 통계 정보를 확인한다.
5. 실행 계획을 확인할 수 있다면 함께 분석한다.
6. 개선안을 제시한다.
7. 데이터 변경 작업은 실행하지 않는다.
## 결과 형식
1. 문제
2. 근거
3. 원인
4. 개선안
5. 개선 SQL
6. 인덱스 검토
7. 주의사항
프로젝트 전체에서 항상 적용되어야 하는 원칙은 CLAUDE.md에 두고, SQL 튜닝·코드 리뷰처럼 특정 작업을 수행할 때 필요한 절차와 참고 자료는 Skill로 분리하는 방식이 관리하기 좋습니다.
5. Subagent — 언제 별도 역할을 만들까?
Subagent는 특정 역할에 맞는 별도의 작업 단위로 활용할 수 있습니다. 예를 들어 보안 리뷰, 성능 분석, 코드 리뷰처럼 메인 작업과 분리했을 때 의미가 있는 작업에 적합합니다.
SQL Reviewer 예시
---
name: sql-reviewer
description: Review SQL Server queries for correctness, performance, indexing, and safety.
---
# SQL Reviewer
다음 항목을 순서대로 검토한다.
1. 논리적 오류
2. JOIN 구조
3. WHERE 조건
4. SARGability
5. 인덱스 활용
6. 실행 계획
7. 대량 데이터 처리
8. 잠금 및 동시성
9. SQL Injection 위험
10. 변경 작업 여부
데이터 변경 SQL은 실행하지 않는다.
결과:
- 문제
- 근거
- 원인
- 개선안
- 개선 SQL
- 주의사항
Subagent를 많이 만든다고 자동으로 성능이 좋아지는 것은 아닙니다. 역할 분리가 실제로 컨텍스트 관리나 전문 분석에 도움이 되는 경우에만 추가하는 것이 좋습니다.
6. Subagent와 MCP는 자동으로 완벽하게 결합된다고 가정하면 안 된다
여기서 기존 글의 표현을 바로잡을 필요가 있습니다. Claude Code의 Subagent에서 MCP 도구를 사용하는 방식은 Claude Code 버전과 구성에 따라 달라질 수 있습니다. MCP 도구 이름이나 전달 방식에 관한 실제 이슈가 GitHub에 보고되어 있으므로 “Subagent가 부모의 모든 MCP 도구를 항상 그대로 상속한다”고 단정해서는 안 됩니다.
- 먼저 메인 Claude Code 세션에서 MCP 서버가 정상 연결되는지 확인합니다.
- Subagent가 실제로 필요한 MCP 도구를 볼 수 있는지 확인합니다.
- Subagent의
tools설정 때문에 필요한 도구가 제한되지 않았는지 확인합니다. - 사용 중인 Claude Code 버전에서 해당 MCP/Subagent 조합이 정상 동작하는지 확인합니다.
따라서 이 글에서는 MCP와 Subagent의 결합을 “설정하면 무조건 된다”가 아니라 구성 후 실제 도구 노출 여부를 검증해야 하는 영역으로 다룹니다.
7. MCP란 무엇인가?
MCP(Model Context Protocol)는 AI 애플리케이션이 외부 도구와 데이터에 접근할 수 있도록 표준화된 방식으로 연결하는 프로토콜입니다. MCP 서버는 AI가 사용할 수 있는 도구 등을 제공하고, 클라이언트는 이를 발견하고 호출합니다.
MCP 클라이언트 측 역할
도구와 외부 시스템 접근 기능 제공
실제 데이터와 SQL 실행 대상
Microsoft도 Data API builder를 기반으로 SQL MCP Server를 제공하고 있습니다. 따라서 특정 오픈소스 MSSQL MCP 프로젝트와 Microsoft의 SQL MCP Server는 서로 다른 구현으로 구분해야 합니다.
8. MSSQL MCP 선택 — 두 가지를 구분해서 보자
| 구분 | codegiveness/mssql-mcp | Microsoft SQL MCP Server |
|---|---|---|
| 제공 주체 | 독립 오픈소스 프로젝트 | Microsoft |
| 기반 | C# / .NET 10 | Data API builder |
| 주요 접근 방식 | T-SQL 도구, 실행 계획, 인덱스 및 DB 상태 분석 등 | 엔터티 추상화와 RBAC를 기반으로 한 SQL MCP |
| 기본 동작 | Restricted 모드에서는 읽기 중심 | DAB 구성과 역할에 따라 노출 범위와 권한을 제어 |
이 글에서는 개발자가 실제 T-SQL과 실행 계획을 분석하는 시나리오에 맞추기 위해 codegiveness/mssql-mcp를 예제로 사용합니다. Microsoft SQL MCP Server는 별도의 공식 대안으로 소개합니다.
9. Windows에서 codegiveness/mssql-mcp 설치
2026년 9월 16일 확인한 해당 GitHub 저장소 README에서는 Windows에 .NET 10 Runtime이 필요하며 .NET Tool 설치 방법을 안내하고 있습니다.
dotnet tool install -g codegiveness.mssql-mcp
mssql-mcp --version
버전이 출력되면 실행 파일을 호출할 수 있는 상태입니다. 실제 DB 연결까지 확인하려면 다음 단계의
--validate 검증을 추가합니다.
$env:MSSQL_CONNECTION_STRING="Server=<server>;Database=<database>;User Id=<user>;Password=<password>;Encrypt=True;TrustServerCertificate=True;"
mssql-mcp --validate
위 명령은 예시입니다. 실제 비밀번호를 블로그 글이나 Git 저장소에 넣으면 안 됩니다. 개발 환경에서는 별도의 환경 변수 또는 안전한 Secret 관리 방식을 사용하는 것이 좋습니다.
10. Claude Code의 .mcp.json에 MSSQL MCP 연결
해당 MCP 프로젝트 README에서는 Claude Code의 프로젝트 수준 MCP 설정으로 프로젝트 루트의 .mcp.json을 사용할 수 있도록 예시를 제공합니다.
{
"mcpServers": {
"mssql-mcp": {
"command": "mssql-mcp",
"env": {
"MSSQL_CONNECTION_STRING": "Server=<server>;Database=<database>;User Id=<user>;Password=<password>;Encrypt=True;TrustServerCertificate=True;"
}
}
}
}
위 예시는 dotnet tool install -g codegiveness.mssql-mcp로 설치한 경우의 형태입니다. 해당 프로젝트 README에서는 npm 방식으로 실행할 때에는 npx와 해당 패키지 인수를 사용하는 별도 구성을 제공합니다.
.mcp.json에 실제 DB 비밀번호를 직접 넣은 뒤 Git 저장소에 커밋하지 마십시오. 예제에는 반드시 자리표시자를 사용하고 실제 비밀값은 안전한 환경 변수나 Secret 관리 방법으로 분리해야 합니다.
11. 연결 후 가장 먼저 해야 할 일
처음부터 복잡한 SQL 튜닝을 시키지 말고 MCP가 실제로 어떤 DB 정보를 제공하는지 단계적으로 확인합니다.
연결된 MCP 서버와 도구가 표시되는지 확인합니다.
DB 목록 또는 스키마를 조회해 연결 대상이 맞는지 확인합니다.
특정 테이블이나 프로시저의 구조를 조회합니다.
간단한 SELECT를 실행합니다.
연결·권한·도구가 모두 확인된 뒤에 실행 계획과 성능 분석으로 넘어갑니다.
12. codegiveness/mssql-mcp의 Restricted Mode
해당 프로젝트 README에 따르면 기본 Access Mode는 Restricted이며 읽기 전용 중심의 보호 장치를 사용합니다.
허용된 T-SQL 구조를 검사합니다.
Restricted 쿼리를 롤백하는 구조를 사용합니다.
Restricted 기본 쿼리 시간 제한이 있습니다.
과도하게 큰 결과가 에이전트 컨텍스트를 점유하지 않도록 제한합니다.
반대로 Unrestricted 모드는 DML/DDL 실행을 허용하는 용도로 제공됩니다. 따라서 이 모드를 단순히 “더 강력한 기본값”처럼 취급해서는 안 됩니다.
운영 환경에서는 AI가 변경 SQL을 자동 실행하도록 만들기보다 읽기 전용 계정과 Restricted 접근을 기본으로 하고, 변경이 꼭 필요한 경우에도 사람의 명시적 승인과 별도의 실행 절차를 두는 것을 권장합니다.
13. DB 계정 권한 — MCP보다 먼저 설계해야 한다
읽기 전용 MCP 서버를 사용하더라도 DB 계정에 과도한 권한을 주는 것은 좋은 설계가 아닙니다.
Claude Code → MCP Server → AI 전용 SQL 계정 → 필요한 DB/객체
- 가능하면 운영 DB가 아닌 개발·테스트 DB부터 사용합니다.
- AI 전용 계정을 별도로 구성합니다.
- 필요한 DB와 객체에 필요한 권한만 제공합니다.
- 실제 변경 권한이 필요하지 않다면 부여하지 않습니다.
- 비밀번호를 소스 코드와 Git 저장소에 넣지 않습니다.
db_datareader 같은 넓은 역할을 부여하는 것이 항상 최소 권한을 의미하는 것은 아닙니다. 실제 환경에서는 애플리케이션과 조직의 보안 정책에 맞춰 객체 수준 권한까지 검토해야 합니다.
14. 실제 SQL 개발에서는 이렇게 요청한다
좋지 않은 요청
프로젝트 목록 SQL 튜닝해줘.
이 요청만으로는 대상 DB, 프로시저, 테이블, 실행 계획, 데이터 규모를 알 수 없습니다. AI가 부족한 정보를 추정할 가능성을 줄이려면 먼저 조사 순서를 명확하게 지정하는 편이 좋습니다.
권장 요청 예시
현재 연결된 MSSQL 환경에서
usp_GetProjectList를 분석해줘.
1. 프로시저 정의를 먼저 확인한다.
2. 참조 테이블과 주요 컬럼을 확인한다.
3. 관련 인덱스를 확인한다.
4. WHERE / JOIN / ORDER BY를 분석한다.
5. 실행 계획을 확인할 수 있으면 함께 분석한다.
6. 병목 원인을 근거와 함께 설명한다.
7. 개선 SQL과 인덱스 검토안을 제시한다.
8. 예상되는 부작용을 설명한다.
9. UPDATE / DELETE / INSERT / DROP / ALTER / TRUNCATE는 실행하지 않는다.
10. 변경이 필요하다면 실행하지 말고 먼저 승인 요청을 한다.
실제 데이터 변경은 절대 실행하지 마.
AI에게 “튜닝해줘”라고만 하는 것이 아니라 조사 → 근거 → 원인 → 개선안 → 실행 여부의 순서를 명시하면 결과를 검토하기 쉬워집니다.
15. SQL Reviewer + MCP를 실제 업무에 적용하는 구조
| 역할 | 담당 | MCP 필요성 |
|---|---|---|
| Main Claude | 요구사항·구현·전체 작업 조정 | 작업에 따라 필요 |
| SQL Reviewer | SQL·스키마·실행 계획 분석 | 실제 DB 확인이 필요하면 필요 |
| Code Reviewer | C#·ASP.NET 코드 검토 | 대부분 불필요 |
| Explorer | 프로젝트 구조 탐색 | 필요한 경우에만 |
여기서 중요한 것은 역할의 숫자가 아니라 각 역할에 필요한 컨텍스트와 권한의 범위입니다. 특히 DB 접근 권한은 개발 편의를 위해 무조건 넓히지 않는 것이 중요합니다.
16. 전체 구조를 한 번에 보면
┌──────────────────────┐
│ Claude Code │
│ Main Session │
└──────────┬───────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌────────────┐ ┌─────────────┐
│ CLAUDE.md │ │ Skills │ │ Subagents │
│ 프로젝트 │ │ 반복 작업 │ │ 전문 역할 │
│ 기본 규칙 │ │ 전문 지침 │ │ │
└───────────┘ └────────────┘ └──────┬──────┘
│
▼
┌─────────────┐
│ SQL Review │
└──────┬──────┘
│
▼
┌─────────────┐
│ MCP Server │
└──────┬──────┘
│
▼
┌─────────────┐
│ SQL Server │
└─────────────┘
17. 추천 프로젝트 디렉터리
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.md
이 디렉터리 구조는 프로젝트에서 사용할 수 있는 하나의 예시입니다. 실제 Claude Code 버전에서 지원하는 구성 위치와 우선순위는 공식 문서를 기준으로 확인해야 합니다.
18. 처음부터 복잡하게 만들지 않는 구축 순서
설치하고 프로젝트를 정상적으로 읽고 수정할 수 있는지 확인합니다.
프로젝트 규칙과 금지사항을 먼저 문서화합니다.
반복되는 SQL 분석·코드 리뷰 절차를 재사용 가능한 단위로 만듭니다.
독립적인 전문 역할이 실제로 필요할 때만 분리합니다.
실제 DB와 같은 외부 시스템을 연결하고 먼저 읽기 작업을 검증합니다.
권한·승인·비밀정보·로그·실행 범위를 별도로 관리합니다.
19. 실무 CASE STUDY — 느린 MSSQL 프로시저 분석
상황
ASP.NET 시스템에서 프로젝트 목록을 반환하는 Stored Procedure의 응답 시간이 증가했다고 가정합니다. 아래는 가상 실무 적용 예시입니다.
기존 요청
프로시저가 느린데 튜닝해줘.
개선된 요청
usp_GetProjectList를 분석해줘.
1. 프로시저 정의 확인
2. 참조 테이블 확인
3. 주요 컬럼과 인덱스 확인
4. WHERE / JOIN / ORDER BY 분석
5. 실행 계획 확인
6. 병목 구간을 근거와 함께 설명
7. 인덱스 개선안 제시
8. SQL 개선안 제시
9. 변경 전후의 예상 영향 설명
10. 변경 SQL은 실행하지 말고 제시만 할 것
UPDATE, DELETE, INSERT, DROP, ALTER, TRUNCATE는
절대 실행하지 말 것.
분석 결과를 검토하는 순서
- AI가 실제 스키마를 확인했는지 확인합니다.
- 실행 계획을 실제로 확인한 것인지 추론한 것인지 구분합니다.
- 인덱스 제안이 기존 인덱스와 중복되는지 확인합니다.
- 개선 SQL이 결과 집합과 기존 계약을 유지하는지 확인합니다.
- 실제 변경 전에는 사람이 SQL과 대상 DB를 다시 확인합니다.
20. SQL 개발자라면 반드시 지켜야 할 체크리스트
- 운영 DB를 기본 연결 대상으로 사용하지 않는다.
- AI 전용 DB 계정을 사용한다.
- 최소 권한을 적용한다.
- 읽기 작업과 변경 작업을 구분한다.
- DELETE / UPDATE / INSERT를 자동 실행하지 않는다.
- DROP / TRUNCATE / ALTER는 특히 엄격하게 통제한다.
- 실제 DB 비밀번호를 Git에 저장하지 않는다.
- MCP 설정 파일에 Secret이 포함되어 있는지 확인한다.
- AI가 제안한 SQL과 실제 실행한 SQL을 구분한다.
- 실제 실행 결과와 AI가 예상한 결과를 구분한다.
21. 설치 후 최종 확인 체크리스트
22. 자주 묻는 질문
CLAUDE.md와 Skill을 하나로 만들어도 되나?
가능하지만 프로젝트 규칙과 특정 작업 절차가 계속 섞이면 관리가 어려워질 수 있습니다. 전체 프로젝트 규칙과 작업별 지침을 구분하면 유지보수하기 쉽습니다.
Subagent를 많이 만들수록 좋은가?
그렇지 않습니다. 역할이 명확하고 별도의 컨텍스트가 도움이 되는 작업만 분리하는 것이 좋습니다.
MCP를 연결하면 DB를 마음대로 수정할 수 있나?
MCP 서버의 구현과 DB 권한, Claude Code의 도구 권한, 접근 모드에 따라 달라집니다. 따라서 MCP 자체를 보안 경계로만 생각하지 말고 DB 권한과 서버 정책을 함께 설계해야 합니다.
codegiveness/mssql-mcp는 Microsoft 공식 제품인가?
아닙니다. 해당 프로젝트는 독립 오픈소스 프로젝트입니다. Microsoft는 별도로 Data API builder 기반의 SQL MCP Server를 제공합니다.
Subagent에서 MCP가 항상 보이나?
항상 그렇다고 단정하면 안 됩니다. Claude Code 버전, Subagent 설정, MCP 서버 범위와 도구 설정에 따라 실제 노출 여부를 확인해야 합니다.
SQL 변경 작업도 AI에게 맡길 수 있나?
기술적으로 가능한 구성과 운영 정책은 별개의 문제입니다. 특히 운영 환경에서는 사람이 최종 SQL과 대상, 영향 범위를 확인하고 승인한 뒤 실행하는 절차를 두는 것이 안전합니다.
23. 최종 정리
Claude Code를 실무 개발 환경에 제대로 적용한다는 것은 단순히 더 강한 모델을 선택하는 문제가 아닙니다.
CLAUDE.md에는 프로젝트의 기본 규칙과 맥락을 정리하고, Skills에는 반복되는 전문 작업을 정리하며, Subagent는 실제로 역할 분리가 필요한 작업에 사용하고, MCP는 DB와 같은 외부 시스템을 연결하는 통로로 사용하는 방식이 핵심입니다.
그리고 DB를 연결하는 순간부터는 AI의 코드 생성 능력보다 권한·승인·비밀정보·감사·실행 범위가 더 중요해집니다.
특히 MSSQL 개발 환경에서는 “AI가 SQL을 작성한다”보다 “AI가 실제 DB 정보를 근거로 분석하되 변경 작업은 사람이 통제한다”는 구조를 먼저 만드는 것이 중요합니다.
24. 공식 문서 및 검증 자료
- Anthropic Claude Code 공식 문서 — Setup
- Anthropic Claude Code 공식 문서
- Anthropic Claude Code 공식 GitHub 저장소
- Anthropic Claude Code GitHub — Skills/Plugin 관련 공식 자료
- codegiveness/mssql-mcp GitHub 저장소
- Microsoft Learn — SQL MCP Server
- Microsoft Learn — Data API builder
- Microsoft Learn — SQL MCP Server Overview
- Model Context Protocol 공식 사이트
Anthropic 자료는 Claude Code의 공식 제품·구성 정보를 확인하기 위한 자료입니다. Microsoft 자료는 Microsoft의 SQL MCP Server와 Data API builder 정보를 확인하기 위한 자료입니다. codegiveness/mssql-mcp 자료는 해당 독립 오픈소스 MCP 서버의 설치·기능·보안 동작을 확인하기 위한 프로젝트 문서입니다.
해시태그
#ClaudeCode #Claude #Anthropic #MCP #ModelContextProtocol #MSSQL #SQLServer #AI개발 #AI코딩 #Subagent #Skills #CSharp #ASPNet #개발자동화 #개발생산성
댓글
댓글 쓰기