AI
Context Engineering
Cursor
MCP
Claude
Development Setup
Best Practices
Context Engineering 완전 정복 (3): 실전 - 프로젝트 셋업
Context Engineering 완전 정복 (3): 실전 - 프로젝트 셋업
"The best engineers stopped writing prompts in 2025. Context engineering means building dynamic systems that deliver the right information, right format, right time." — The Digital Speaker, 2025
들어가며
이전 글에서 Context Engineering의 이론적 기반을 다뤘습니다. 이제 실전입니다.
이 글을 읽고 나면:
- 프로젝트에 맥락 문서를 구축할 수 있습니다
- Cursor를 Context Engineering에 최적화할 수 있습니다
- MCP로 외부 지식을 AI에 연결할 수 있습니다
- 바로 사용할 수 있는 템플릿을 갖게 됩니다
Part 1: 맥락 문서 설계
1.1 CONTEXT.md 완전 가이드
파일 위치와 명명 규칙:
project-root/
├── CONTEXT.md # 프로젝트 전체 맥락
├── .cursorrules # Cursor 전용 규칙
├── agents.md # AI 에이전트 지시문 (선택)
├── src/
│ ├── auth/
│ │ └── CONTEXT.md # 모듈별 맥락 (선택)
│ └── ...
CONTEXT.md 전체 구조:
# Project Context
## Overview
[프로젝트가 무엇인지, 왜 존재하는지 2-3문장]
## Problem Statement
[해결하려는 핵심 문제]
## Architecture
[시스템 구조 개요]
## Tech Stack
[사용 기술 목록과 버전]
## Directory Structure
[주요 디렉토리 설명]
## Conventions
[코딩 컨벤션, 네이밍 규칙]
## Constraints
[기술적/비즈니스적 제약]
## Key Decisions
[주요 아키텍처 결정과 이유]
## History
[중요한 변경 이력]
## Lessons Learned
[과거 실패와 교훈]
## Glossary
[프로젝트 특화 용어]
## Current Focus
[현재 작업 중인 영역]
1.2 각 섹션 작성 가이드
Overview - 프로젝트 개요
## Overview
StoniStudio는 Next.js 14 기반의 기술 블로그 플랫폼입니다.
MDX를 사용하여 인터랙티브한 기술 콘텐츠를 작성하고,
다크 테마와 한/영 다국어를 지원합니다.
**핵심 가치:**
- 개발자 경험 우선
- 성능과 접근성
- 콘텐츠 중심 설계
Problem Statement - 문제 정의
## Problem Statement
기존 블로그 플랫폼의 문제:
1. 코드 하이라이팅이 부족하거나 커스터마이징 어려움
2. 인터랙티브 컴포넌트 삽입 불가
3. 다국어 지원 복잡
우리의 해결책:
- MDX로 React 컴포넌트를 콘텐츠에 직접 삽입
- 커스텀 코드 블록 컴포넌트
- 파일 기반 다국어 라우팅
Architecture - 아키텍처
## Architecture
┌─────────────────────────────────────────┐ │ Next.js │ ├─────────────┬─────────────┬─────────────┤ │ App Router│ MDX │ Tailwind │ ├─────────────┴─────────────┴─────────────┤ │ Content Layer │ │ (posts/ko, posts/en) │ ├─────────────────────────────────────────┤ │ Static Generation │ │ (AWS S3/CF) │ └─────────────────────────────────────────┘
**주요 데이터 흐름:**
1. MDX 파일 → gray-matter로 파싱 → 메타데이터 추출
2. MDX 컴파일 → React 컴포넌트로 변환
3. 정적 생성 → S3 배포
Tech Stack - 기술 스택
## Tech Stack
| 카테고리 | 기술 | 버전 | 비고 |
|---------|------|------|------|
| Framework | Next.js | 14.x | App Router |
| Language | TypeScript | 5.x | strict mode |
| Styling | Tailwind CSS | 3.x | |
| Content | MDX | 3.x | |
| Deploy | AWS SAM | | S3 + CloudFront |
**의존성 원칙:**
- 외부 의존성 최소화
- 번들 크기 모니터링
- 보안 업데이트 즉시 적용
Conventions - 컨벤션
## Conventions
### 파일 네이밍
- 컴포넌트: PascalCase (`PostCard.tsx`)
- 유틸리티: camelCase (`formatDate.ts`)
- 상수: SCREAMING_SNAKE_CASE
### 코드 스타일
- 함수: 화살표 함수 선호
- 컴포넌트: 함수형 컴포넌트만
- 타입: interface 선호 (type은 유니온/인터섹션에만)
### 커밋 메시지
<type>: <subject>
types: feat, fix, docs, style, refactor, test, chore
### 브랜치 전략
- main: 프로덕션
- develop: 개발
- feature/*: 기능 개발
Constraints - 제약 조건
## Constraints
### 기술적 제약
- Node.js 18+ 필수
- 정적 생성만 사용 (서버 컴포넌트 제한적)
- 클라이언트 사이드 데이터 페칭 최소화
### 성능 제약
- LCP < 2.5s
- 번들 크기 < 200KB (gzipped)
- 이미지는 반드시 최적화
### 비즈니스 제약
- 개인정보 수집 없음
- 광고 없음
- 오픈소스 라이선스 준수
Key Decisions - 주요 결정
## Key Decisions
### 1. App Router 선택 (2024-10)
**결정:** Pages Router 대신 App Router 사용
**이유:**
- 서버 컴포넌트로 번들 크기 감소
- 레이아웃 시스템 활용
- 미래 지향적 아키텍처
**트레이드오프:** 학습 곡선, 일부 라이브러리 호환성
### 2. MDX 직접 처리 (2024-10)
**결정:** Contentlayer 대신 직접 MDX 처리
**이유:**
- Contentlayer 유지보수 불확실
- 커스터마이징 유연성
- 의존성 감소
**트레이드오프:** 초기 구현 비용
Lessons Learned - 교훈
## Lessons Learned
### 실패 1: 과도한 클라이언트 상태
**문제:** 초기에 모든 상태를 클라이언트에서 관리
**결과:** 번들 크기 증가, 초기 로딩 느림
**교훈:** 서버에서 할 수 있는 것은 서버에서
### 실패 2: 이미지 최적화 누락
**문제:** 원본 이미지 직접 사용
**결과:** LCP 5초 이상
**교훈:** next/image 또는 외부 CDN 필수
1.3 agents.md / CLAUDE.md
AI 에이전트 전용 지시문 파일:
# AI Agent Instructions
## Persona
당신은 이 프로젝트의 시니어 개발자입니다.
코드 품질, 성능, 접근성을 중시합니다.
## Communication Style
- 한국어로 응답
- 코드 변경 시 이유 설명
- 불확실한 부분은 질문
## Priorities
1. 기존 코드 스타일 유지
2. 타입 안전성
3. 성능 최적화
4. 접근성
## Before Writing Code
1. 관련 기존 코드 확인
2. CONTEXT.md의 제약 조건 확인
3. 비슷한 구현이 있는지 확인
## Code Guidelines
- any 타입 사용 금지
- console.log 대신 적절한 로깅
- 매직 넘버 대신 상수
- 함수는 단일 책임
## Testing
- 새 기능에는 테스트 필수
- 엣지 케이스 고려
- 접근성 테스트 포함
## What NOT to Do
- 기존 API 시그니처 변경 (논의 없이)
- 새로운 의존성 추가 (승인 없이)
- 성능에 영향을 주는 변경 (벤치마크 없이)
1.4 디렉토리별 맥락 문서
대규모 프로젝트에서는 모듈별 맥락 문서가 유용합니다:
# src/auth/CONTEXT.md
## Module Overview
인증 관련 모든 로직을 담당하는 모듈
## Responsibilities
- JWT 토큰 생성/검증
- 세션 관리
- 권한 확인
## Key Files
- `middleware.ts`: 인증 미들웨어
- `jwt.ts`: JWT 유틸리티
- `types.ts`: 인증 관련 타입
## Dependencies
- jsonwebtoken: JWT 처리
- 내부: `@/lib/redis` (세션 저장)
## Security Considerations
- 토큰은 httpOnly 쿠키에 저장
- Refresh 토큰 로테이션 적용
- Rate limiting 필수
Part 2: Cursor 설정
2.1 .cursorrules 완전 가이드
Cursor는 프로젝트 루트의 .cursorrules 파일을 자동으로 읽습니다.
기본 구조:
# Project Rules for Cursor
## Project Context
[프로젝트 개요 - CONTEXT.md에서 핵심만]
## Tech Stack
[기술 스택 요약]
## Code Style
[코딩 컨벤션]
## File Patterns
[파일별 규칙]
## Common Patterns
[자주 사용하는 패턴 예시]
## Forbidden Patterns
[금지된 패턴]
2.2 프론트엔드 프로젝트 예시
# Cursor Rules - Next.js Blog
## Project Context
Next.js 14 App Router 기반 기술 블로그.
MDX로 콘텐츠 작성, Tailwind CSS 스타일링.
정적 생성으로 AWS S3/CloudFront 배포.
## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict)
- Tailwind CSS
- MDX
## Code Style
### TypeScript
- strict 모드 필수
- any 금지, unknown 사용
- interface 선호 (type은 유니온에만)
- 함수 반환 타입 명시
### React
- 함수형 컴포넌트만
- Props는 interface로 정의
- 커스텀 훅은 use 접두사
- memo는 성능 이슈 확인 후에만
### Tailwind
- 인라인 스타일 금지
- 커스텀 클래스는 @apply 사용
- 반응형: mobile-first
## File Patterns
### 컴포넌트 (components/*.tsx)
```tsx
interface ComponentNameProps {
// props
}
export default function ComponentName({ prop }: ComponentNameProps) {
return (
// JSX
);
}
페이지 (app/**/page.tsx)
export const metadata: Metadata = {
title: '',
description: '',
};
export default function PageName() {
return (
// JSX
);
}
유틸리티 (lib/*.ts)
/**
* 함수 설명
* @param param - 파라미터 설명
* @returns 반환값 설명
*/
export function utilityName(param: Type): ReturnType {
// implementation
}
Common Patterns
데이터 페칭
// 서버 컴포넌트에서
async function getData() {
const data = await fetchData();
return data;
}
export default async function Page() {
const data = await getData();
return <Component data={data} />;
}
에러 처리
// error.tsx
'use client';
export default function Error({
error,
reset,
}: {
error: Error;
reset: () => void;
}) {
return (
<div>
<h2>Something went wrong!</h2>
<button onClick={reset}>Try again</button>
</div>
);
}
Forbidden Patterns
❌ any 타입 ❌ console.log (logger 사용) ❌ 인라인 스타일 ❌ useEffect에서 데이터 페칭 (서버 컴포넌트 사용) ❌ 클래스 컴포넌트 ❌ default export 없는 컴포넌트
### 2.3 백엔드 프로젝트 예시
Cursor Rules - Express API
Project Context
Express.js 기반 REST API 서버. PostgreSQL + Prisma ORM. JWT 인증, Redis 세션.
Tech Stack
- Node.js 20
- Express.js 4
- TypeScript
- Prisma ORM
- PostgreSQL
- Redis
Code Style
에러 처리
- 커스텀 Error 클래스 사용
- 에러는 미들웨어에서 중앙 처리
- 절대 에러 삼키지 않기
비동기
- async/await 사용
- Promise.all 적극 활용
- 타임아웃 항상 설정
보안
- 입력 검증 필수 (zod)
- SQL 인젝션 방지 (Prisma 사용)
- Rate limiting 적용
File Patterns
컨트롤러 (controllers/*.ts)
export const getUser = async (
req: Request,
res: Response,
next: NextFunction
) => {
try {
const { id } = req.params;
const user = await userService.findById(id);
res.json({ data: user });
} catch (error) {
next(error);
}
};
서비스 (services/*.ts)
export const userService = {
async findById(id: string): Promise<User> {
const user = await prisma.user.findUnique({
where: { id },
});
if (!user) {
throw new NotFoundError('User not found');
}
return user;
},
};
Forbidden Patterns
❌ 동기 파일 I/O ❌ 하드코딩된 시크릿 ❌ try-catch 없는 async 함수 ❌ res.send() 후 추가 코드 ❌ 검증 없는 사용자 입력 사용
---
## Part 3: MCP (Model Context Protocol) 활용
### 3.1 MCP란 무엇인가
**Model Context Protocol (MCP)**는 LLM을 외부 맥락 소스에 연결하는 표준 프로토콜입니다.
Thoughtworks Technology Radar Vol. 33:
> "Every major technology vendor is building agent-awareness into their platforms, largely thanks to the Model Context Protocol (MCP)."
**MCP의 역할:**
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ LLM/AI │────▶│ MCP │────▶│ External │ │ Agent │◀────│ Server │◀────│ Sources │ └─────────────┘ └─────────────┘ └─────────────┘
- 파일 시스템
- 데이터베이스
- API
- 문서
### 3.2 주요 MCP 서버들
**1. Filesystem MCP**
- 로컬 파일 시스템 접근
- 코드베이스 탐색
**2. GitHub MCP**
- 레포지토리 정보
- 이슈, PR 접근
**3. Database MCP**
- PostgreSQL, MySQL 등
- 스키마 정보, 쿼리 실행
**4. Context7 MCP**
- 외부 문서 통합
- 라이브러리 문서 자동 로드
### 3.3 Claude Desktop에서 MCP 설정
**설정 파일 위치:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
**기본 설정 예시:**
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/projects"
]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
}
}
}
}
3.4 Context7 MCP 활용
Context7은 외부 라이브러리 문서를 자동으로 맥락에 포함시킵니다.
설정:
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@context7/mcp-server"]
}
}
}
사용 예:
"Next.js 14의 App Router에서 동적 라우팅을 구현하려고 해.
Context7으로 최신 Next.js 문서를 참조해서 알려줘."
AI가 자동으로 최신 Next.js 문서를 검색하여 맥락으로 활용합니다.
Part 4: 템플릿과 체크리스트
4.1 프로젝트 타입별 CONTEXT.md 템플릿
웹 프론트엔드:
# Project Context - Web Frontend
## Overview
[프로젝트 설명]
## Tech Stack
- Framework: [React/Vue/Next.js] [버전]
- Language: TypeScript [버전]
- Styling: [Tailwind/CSS Modules/Styled Components]
- State: [Redux/Zustand/React Query]
- Testing: [Jest/Vitest] + [RTL/Cypress]
## Architecture
[컴포넌트 구조, 상태 관리 전략]
## Performance Requirements
- LCP: < [목표]
- Bundle Size: < [목표]
- Lighthouse Score: > [목표]
## Browser Support
[지원 브라우저 목록]
## Accessibility
- WCAG [레벨] 준수
- 스크린 리더 테스트 필수
백엔드 API:
# Project Context - Backend API
## Overview
[프로젝트 설명]
## Tech Stack
- Runtime: Node.js [버전]
- Framework: [Express/Fastify/NestJS]
- Database: [PostgreSQL/MongoDB] + [ORM]
- Cache: [Redis]
- Queue: [Bull/SQS]
## API Design
- Style: REST / GraphQL
- Versioning: URL path (/v1/)
- Auth: JWT + Refresh Token
## Security Requirements
- OWASP Top 10 대응
- Rate Limiting: [설정]
- Input Validation: [라이브러리]
## Performance Requirements
- Response Time: p99 < [목표]
- Throughput: [목표] RPS
4.2 셋업 완료 체크리스트
## Context Engineering Setup Checklist
### 문서
- [ ] CONTEXT.md 생성
- [ ] Overview 섹션 작성
- [ ] Tech Stack 문서화
- [ ] Conventions 정의
- [ ] Key Decisions 기록
- [ ] Constraints 명시
### Cursor 설정
- [ ] .cursorrules 생성
- [ ] 코드 스타일 정의
- [ ] 파일 패턴 예시 추가
- [ ] Forbidden 패턴 명시
### MCP (선택)
- [ ] 필요한 MCP 서버 식별
- [ ] 설정 파일 구성
- [ ] 연결 테스트
### 팀 공유
- [ ] 팀원에게 문서 공유
- [ ] 피드백 수집
- [ ] 정기 업데이트 일정 수립
4.3 흔한 실수와 해결책
| 실수 | 문제 | 해결책 |
|---|---|---|
| 너무 긴 CONTEXT.md | AI가 핵심을 놓침 | 핵심만 유지, 상세는 별도 파일 |
| 업데이트 안 함 | 오래된 정보로 혼란 | 정기 리뷰 일정 수립 |
| 모호한 제약 | AI가 해석을 다르게 | 구체적 예시 포함 |
| 예시 부족 | 원하는 스타일 전달 안 됨 | 각 패턴에 코드 예시 |
| 팀 공유 안 함 | 일관성 없는 AI 활용 | 팀 온보딩에 포함 |
결론: 바로 시작하기
이 글에서 배운 것
-
CONTEXT.md 작성법
- 12개 섹션의 구조
- 각 섹션별 작성 가이드
- 실제 예시
-
Cursor 최적화
- .cursorrules 구조
- 프론트엔드/백엔드 예시
- 패턴과 안티패턴
-
MCP 활용
- MCP의 역할과 구조
- 주요 MCP 서버
- Context7 활용법
-
템플릿과 체크리스트
- 프로젝트 타입별 템플릿
- 셋업 체크리스트
- 흔한 실수 방지
다음 글 미리보기
Article 4: Context Engineering 실전 - 개발 워크플로우에서는:
- 맥락 우선 대화 패턴 20가지
- 4단계 워크플로우 상세 가이드
- Iteration에서 맥락 연속성 유지
- 실제 개발 시나리오 워크스루
오늘 할 일
-
CONTEXT.md 만들기 (30분)
- 이 글의 템플릿 복사
- 프로젝트에 맞게 수정
-
.cursorrules 만들기 (20분)
- 기본 구조 복사
- 프로젝트 컨벤션 추가
-
테스트하기 (10분)
- Cursor에서 간단한 작업 요청
- 맥락이 반영되는지 확인
References
- Thoughtworks. (2025, November). "Technology Radar Vol. 33." - MCP 관련
- Anthropic. "Model Context Protocol Documentation."
- Cursor. "Cursor Rules Documentation."
- Context7. "Context7 MCP Server Documentation."
다음 글에서는 일상 개발에서 Context Engineering을 적용하는 워크플로우를 다룹니다. 오늘 CONTEXT.md를 만들어보셨나요? 경험을 공유해주세요.
