CLAUDE.md는 작성하고 있습니다. 하지만 .claude/ 디렉토리 전체를 「설정 아키텍처(Architecture of Settings)」로서 설계하고 있는 사람은 아직 적습니다.

이 기사에서는 .claude/ 디렉토리를 구성하는 CLAUDE.md・hooks・커스텀 명령어(Custom Commands)・settings를 연계하여, 솔로 개발부터 모노레포(Monorepo) 대규모 구성까지 대응하는 3가지 설계 패턴을 소개합니다. 다 읽을 때쯤에는 당신의 프로젝트에 최적화된 .claude/ 구성을 확인할 수 있을 것입니다.

Claude Code: 최신 버전 (CLI)
Node.js: 18 이상 (hooks 내에서 lint/type-check를 실행하는 경우)
OS: macOS / Linux (Windows에서도 대체로 동일)

• Claude Code의 프로젝트 루트에 .claude/ 디렉토리를 배치할 수 있는 상태

먼저, .claude/ 디렉토리에 배치할 수 있는 파일군과 그 역할을 정리합니다.

각 파일이 어느 페이즈(Phase)에 영향을 미치는지를 의식하여 배치하는 것이 설정 아키텍처의 첫걸음입니다.

혼자서 개발하는 프로젝트라면 최소한의 구성으로 충분합니다.

project-root/
├── CLAUDE.md
└── .claude/
...

# 프로젝트 개요
개인 블로그의 Next.js + TypeScript 프로젝트.
# 기술 스택
...

포인트: 솔로 개발에서는 「자신의 기억에 없는 것」만 적으면 충분합니다. 기술 스택과 파일 명명 규칙, 금지 사항을 3~5개 항목으로 압축하세요. 커스텀 명령어를 3개 정도 준비해 두면 일상적인 작업의 대부분을 커버할 수 있습니다.

팀 개발에서는 멤버 간에 암묵적 지식(Implicit Knowledge)이 되기 쉬운 규칙을 CLAUDE.md에 명문화하고, settings.json으로 위험한 조작을 방어합니다.

project-root/
├── CLAUDE.md
└── .claude/
...

# 프로젝트 개요
BtoB SaaS의 백엔드 API. 팀 4명이 개발 중.
# 기술 스택
...

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

settings.json에서 파괴적인 명령어(Destructive Commands)를 명시적으로 차단해 두면, Claude Code가 실수로 위험한 조작을 실행할 리스크를 줄일 수 있습니다.

모노레포에서는 서브 디렉토리마다 CLAUDE.md를 배치하여 기술 스택의 차이를 Claude Code에 정확하게 전달합니다.

monorepo-root/
├── CLAUDE.md # 공통 규칙
├── .claude/
...

자식 디렉토리의 CLAUDE.md는 루트의 CLAUDE.md에 추가되는 형태로 읽힙니다. 루트에는 모든 서브 프로젝트 공통 규칙 (Git 커밋 규약, CI 설정 등)을 쓰고, 각 서브 디렉토리에는 기술 스택 고유의 규칙만 작성하세요.

# 프론트엔드 고유 규칙
이 디렉토리는 Next.js App Router를 사용하는 프론트엔드 앱입니다.
# 기술 스택
...

Claude Code의 hooks 기능을 사용하면, 코드 편집 후에 자동으로 lint・type-check를 실행하고, 문제가 있다면 Claude Code에 피드백을 줄 수 있습니다.

hooks는 .claude/settings.json의 최상위 레벨(Top-level)에 설정합니다.

{
"hooks": {
"PostToolUse": [
...

#!/bin/bash
# .claude/hooks/lint-and-typecheck.sh
# PostToolUse (Write|Edit) 시 호출되는 스크립트
...

hooks의 stdout에 출력된 내용은 Claude Code에 피드백됩니다. 에러가 있으면 Claude Code가 자동으로 수정을 시도하므로, 「작성 → 체크 → 수정」 루프가 자동화됩니다.

.claude/commands/

디렉토리에 Markdown 파일을 배치하면, /project:

접두사(Prefix)가 붙은 커스텀 슬래시 명령어(Slash Command)로 사용할 수 있습니다.

.claude/commands/review.md

:

다음 파일의 코드 리뷰를 수행해 주세요.
## 리뷰 관점
1. **버그 리스크**: null/undefined 체크 누락, 경계값 처리, 에러 핸들링
...

사용법: /project:review src/services/user-service.ts

.claude/commands/test-gen.md

:

지정된 파일의 유닛 테스트 (Unit Test)를 생성해 주세요.
## 테스트 방침
- 테스트 프레임워크 (Test Framework): 이 프로젝트에서 사용되는 것을 자동 감지
...

.claude/commands/doc.md

:

지정된 대상의 문서를 생성해 주세요.
## 문서 종류 ($ARGUMENTS의 내용으로부터 판단)
- 파일 지정 → JSDoc/GoDoc 코멘트 추가
...

$ARGUMENTS

에는 슬래시 명령어를 실행할 때 이어서 입력한 텍스트가 전개됩니다.

CLAUDE.md는 강력하지만, 정보를 너무 많이 채워 넣으면 역효과가 납니다.

루트 CLAUDE.md: 100200행 이내 -
서브 디렉토리 CLAUDE.md: 3080행 이내 -
규칙의 수: 하나의 CLAUDE.md당 15개 항목 이내 -
판단 기준: "이 규칙이 없으면 Claude Code가 잘못된 판단을 하는가?"를 셀프 체크

망설여진다면 깎아내는 방향으로 조정하세요. Claude Code는 일반적인 베스트 프랙티스 (Best Practice)를 이미 알고 있습니다. 당신의 프로젝트에만 해당하는 "일반적이지 않은 규칙"만을 작성하는 것이 최적해입니다.

다음은 즉시 복사해서 사용할 수 있는 스타터 구성입니다. 프로젝트 규모에 따라 선택하세요.

.claude/
└── commands/
    ├── review.md # 코드 리뷰
    ...

.claude/
├── settings.json # 허용/거부 리스트
├── commands/
...

.claude/
├── settings.json
├── commands/
...

이러한 구성을 베이스로 하여, 자신의 프로젝트 워크플로우에 맞춰 커스터마이징하는 것을 추천합니다.

• CLAUDE.md 단독이 아니라, settings.json · commands · hooks를 조합하여 초기화부터 후처리까지 일관된 제어를 수행합시다.
• .claude/ 디렉토리를 "설정의 아키텍처"로서 설계합니다.
• 프로젝트 규모에 따라 3단계 구성 패턴을 선택합니다. 솔로 개발이라면 CLAUDE.md + 명령어 3개로 충분합니다. 팀 개발에서는 settings.json으로 안전장치를, 모노레포 (Monorepo)에서는 서브 디렉토리 CLAUDE.md로 문맥을 분할합시다.
• CLAUDE.md는 "뺄셈"으로 최적화합니다. 프로젝트 고유의 "일반적이지 않은 규칙"만을 작성합니다. 100~200행을 상한선 기준으로 삼아, 과도한 작성으로 인한 정확도 저하를 방지합시다.