서론

Web 제작 현장에서 Claude Code를 일상적으로 사용하고 있습니다. 프로젝트는 Astro 기반의 기업 사이트부터 Next.js (App Router) 풀스택 개인 개발까지 폭넓지만, 프로젝트마다 「Claude Code를 위한 인수인계 사항」을 설계해 두면 매 세션마다 발생하는 재작업이 눈에 띄게 줄어듭니다.

이 기사에서는 실제로 운용 중인 두 가지 프로젝트(클라이언트의 기업 사이트 = Astro 5, 개인 개발 Next.js 앱)의 설정을 바탕으로 다음 내용을 소개합니다.

• CLAUDE.md에 「무엇을 쓰면 효과적인가」에 대한 실례
• settings.local.json의 permissions 키우는 법
• MCP 서버 설정의 3가지 스코프(Scope)와 활용법

참고로, Claude Code의 사양은 업데이트 속도가 빠르기 때문에, 본 기사의 사양에 관한 기술은 모두 집필 시점(2026년 7월)의 공식 문서를 확인한 후 작성되었습니다.

전제: Claude Code가 설정을 읽어들이는 메커니즘

먼저 공식 사양을 정리하겠습니다. CLAUDE.md는 세션 시작 시 매번 컨텍스트(Context)로 읽어들이는 지시 파일이며, 배치 위치에 따라 스코프(Scope)가 달라집니다 (공식: How Claude remembers your project).

파악해 두어야 할 공식 사양의 포인트:

• 1파일당 200행 이하 권장. 길수록 컨텍스트를 소비하며 준수율이 떨어짐
• 현재 디렉토리에서 상위 디렉토리로 거슬러 올라가며 모두 읽어 들여 연결됨 (덮어쓰기가 아님)
• 서브 디렉토리의 CLAUDE.md는 Claude가 해당 디렉토리 내의 파일을 읽을 때 지연 로딩(Lazy loading)됨
• @path/to/file 구문을 통해 다른 파일을 임포트(Import) 가능 (최대 4계층)
• CLAUDE.md는 강제력 있는 설정이 아니라 어디까지나 컨텍스트임. 확실하게 차단하고 싶은 조작은 hooks나 permissions로 제어해야 함

마지막 점이 실무에서는 특히 중요합니다. 「~하지 마라」라고 CLAUDE.md에 써도 따르지 않을 수 있습니다. 금지 사항은 후술할 permissions.deny에 적는 것이 정답입니다.

실례 1: Astro 기업 사이트의 CLAUDE.md

클라이언트의 기업 사이트 (Astro 5 · SSG 구성)에서 사용 중인 CLAUDE.md의 구성입니다. 82행 이내로 맞추었습니다. 효과가 컸던 순서대로 소개합니다.

커맨드(Command) 목록은 최우선으로 작성

## 커맨드
npm run dev # 개발 서버 기동 (Astro)
npm run build # 프로덕션 빌드 (dist/로 출력)
...

이것이 없으면 Claude는 npx prettier 등 프로젝트에서 사용하지 않는 도구를 추측해서 실행하기 쉽습니다. Biome 채택 (탭 인덴트 · 더블 쿼트)이라는 점도 명시해 두면, 생성되는 코드의 스타일이 처음부터 일치하게 됩니다.

프로젝트 고유의 추상화는 사용 예시와 함께 작성

이 사이트에는 「이미지는 src/assets/images/에 두지만, 참조는 public/img/ 경로로 통일한다」라는 독자적인 헬퍼(Helper) 계층이 있습니다. 이런 리포지토리(Repository)를 읽는 것만으로는 의도가 전달되지 않는 규약이야말로 CLAUDE.md에 쓸 가치가 있습니다.

### 이미지 관리
이미지는 `src/assets/images/`에 배치하고, `public/img/` 경로로 참조한다.
// 래스터 이미지의 메타데이터 취득
...

이를 작성하기 전에는 Claude가 astro:assets의 Image를 직접 import 하는 구현을 제안하여 매번 수정해야 했습니다. 작성한 후에는 한 번도 발생하지 않았습니다. 「같은 수정 지시를 2번 입력하면 CLAUDE.md행」이라는 공식 권장 기준 (When to add to CLAUDE.md)은 체감상으로도 옳습니다.

레이아웃의 props와 데이터 집약 파일

레이아웃

• BaseLayout.astro — 모든 페이지 공통. title, description, ogImage, canonical, noindex 등을 props로 받음
  ...

새로운 페이지 추가를 요청했을 때, 기존 페이지와 동일한 방식으로 BaseLayout과 네비게이션 데이터를 사용하게 됩니다. "어디에 무엇이 집약되어 있는가"를 나타내는 인덱스로서의 CLAUDE.md입니다.

커밋 메시지 언어 지정

### 커밋 메시지
일본어 커밋 메시지가 필수.

단 한 줄이지만 효과는 매우 큽니다. 지정하지 않으면 영어로 커밋됩니다.

실례 2: permissions의 육성 방법

.claude/settings.local.json의 permissions.allow는, 처음부터 설계하는 것이 아니라 운영하면서 키워나가는 것이라고 생각합니다.

Claude Code는 허가되지 않은 명령어를 실행하기 전에 확인을 요청합니다. 이때 "항상 허가"를 선택하면 이 파일에 추가되므로, 몇 주간 사용하면 프로젝트의 작업 내용이 그대로 반영된 리스트가 됩니다. Astro 사이트 측의 실제 모습은 이 정도의 단순함입니다.

{
"permissions": {
"allow": [
...

반면, Next.js 풀스택 앱 측은 drizzle-kit의 마이그레이션(migration), gh CLI를 통한 배포 확인, vercel env pull까지 80행 이상으로 늘어났습니다. 여기서 얻은 운영상의 배움은 두 가지입니다.

1. 와일드카드(Wildcard)의 입도를 의식할 것

Bash(git -C:*)와 같이 넓게 허가할지, Bash(git commit:*)와 같이 서브 커맨드(subcommand) 단위로 허가할지는 판단이 필요합니다. 저는 파괴적일 수 있는 것(git push, drizzle-kit push 등)은 매번 확인하도록 남겨두고, 읽기 계열이나 빌드 계열은 넓게 허가하고 있습니다.

2. 팀과 공유한다면 settings.json, 개인용은 settings.local.json

공식 설정의 우선순위는 "로컬 설정 → 프로젝트 공유 설정 → 사용자 설정" 순으로 적용됩니다. 수탁 프로젝트에서 리포지토리(repository)를 공유할 경우, 빌드·린트(lint) 계열의 허가는 .claude/settings.json에 넣어 커밋하고, 개인적인 실험적 허가는 settings.local.json으로 분리하면 팀원의 첫 경험이 좋아집니다.

또한, .env와 같은 기밀 파일에 대한 액세스는 permissions.deny로 차단할 수 있습니다. CLAUDE.md에 ".env를 읽지 마라"라고 쓰는 것보다 확실합니다.

{
"permissions": {
"deny": [
...

실례 3: MCP 서버의 스코프(Scope) 설계

MCP 서버 설정에는 세 가지 스코프가 있습니다 (공식: MCP installation scopes).

저의 구분 방식은 다음과 같습니다.

• User: Figma, Notion 등 프로젝트를 넘나들며 사용하는 도구
• Project: 해당 프로젝트 고유의 문서 MCP 등. 예를 들어 Better Auth를 사용하는 앱에서는 공식 문서 MCP를 프로젝트 스코프로 추가하고 있습니다.

claude mcp add --transport http better-auth https://mcp.inkeep.com/better-auth/mcp

라이브러리 공식 문서 MCP를 연결해 두면, 구현 시 Claude가 최신 API 사양을 참조할 수 있기 때문에, 학습 데이터가 오래되어 발생하는 "그럴듯하지만 동작하지 않는 코드"가 줄어듭니다. Better Auth나 Drizzle처럼 업데이트가 빠른 라이브러리에서는 특히 유효했습니다.

.mcp.json은 환경 변수 확장(${VAR} / ${VAR:-default}...

）를 지원하기 때문에, API 키를 직접 작성하지 않고도 팀과 공유할 수 있습니다.

{
"mcpServers": {
"api-server": {
...

또한, 프로젝트 스코프(Project scope)의 .mcp.json은 보안상 첫 실행 시 승인 다이얼로그가 나타납니다. settings.local.json의 enableAllProjectMcpServers: true를 통해 일괄 승인할 수도 있지만, 타인의 리포지토리(Repository)에서는 개별 승인(enabledMcpjsonServers)을 하는 것이 안전합니다.

운용에 사용하는 커맨드(Command)와 팁(Tips)

** /init으로 초안 만들기**: 기존 프로젝트라면 /init을 통해 코드베이스를 분석한 CLAUDE.md를 자동으로 생성할 수 있습니다. .cursorrules 등 다른 도구의 설정 파일도 읽어와서 반영됩니다. 생성된 결과는 어디까지나 초안이므로, 앞서 언급한 '독자 규약'은 직접 추가해야 합니다.

** /memory로 읽기 상태 확인하기**: "CLAUDE.md에 적었는데도 따르지 않는다"라고 느껴질 때는, 먼저 /memory를 통해 해당 파일이 실제로 읽히고 있는지 확인합니다. 리스트에 없다면 배치 위치의 문제입니다.

HTML 주석은 컨텍스트(Context)에 포함되지 않음: CLAUDE.md 내의 <!-- 주석 -->은 읽어들일 때 제거됩니다 (공식 사양). 인간 유지보수자를 위한 메모를 토큰 소비 없이 남길 수 있습니다.

AGENTS.md와의 공존: Claude Code가 읽는 것은 CLAUDE.md입니다. 다른 코딩 에이전트(Coding agent)와 AGENTS.md를 공유하고 싶다면, CLAUDE.md의 맨 앞에 @AGENTS.md라고 적어 임포트(Import)하면 이중 관리를 피할 수 있습니다.

요약

• CLAUDE.md에는 "리포지토리를 읽는 것만으로는 알 수 없는 독자 규약"을 200행 이내로 작성합니다. 커맨드 목록, 독자적인 추상화, 커밋 규약이 비용 대비 효과가 높은 3가지 요소입니다.
• 금지 사항은 CLAUDE.md가 아니라 permissions.deny로 설정합니다. CLAUDE.md는 강제성이 없는 컨텍스트이며, permissions는 운용하면서 키워나갑니다. 팀 공유분은 settings.json, 개인분은 settings.local.json을 사용합니다.
• 문서 MCP(Document MCP)의 프로젝트 스코프 추가는 업데이트가 빠른 라이브러리에서의 구현 정밀도를 높여줍니다.

설정은 한 번 만들고 끝내는 것이 아니라, "같은 지적을 두 번 하면 추가한다"는 루프를 돌림으로써 프로젝트마다 최적화되어 갑니다.

참고 (1차 정보)

Discussion