반응형
CLAUDE.md란?
코딩 컨벤션 확인, 프로젝트 구조 파악, 사용 중인 기술 스택 이해와 같은 정보들을 규합한 지침서.
이를 통해 프로젝트마다 다른 규칙이나 맥락을 AI가 이해하며, 리뷰-테스트-문서화에서도 일관성을 유지한다.
1. CLAUDE.md
프로젝트 소개 파일
클로드 코드가 자동으로 읽어 들인다.
AI의 온보딩 가이드
필요한 이유?
코딩 스타일, 라이브러리, 파일 구조, 네이밍 룰 등 사용자 맞춤형을 위해 사용한다.
- 매번 반복하는 설명 생략
- 일관성 유지
- 프로젝트 이해도 향상
- 자동화
주요 특징
- 자동 컨텍스트 포함: 모든 대화에서 자동으로 프로젝트 맥락이 반영됨
- 프로젝트 특화: 팀의 코딩 스타일과 규칙을 저장
- 지속적 메모리: 세션이 끝나도 설정 유지
- 계층적 구조: 여러 CLAUDE.md 파일을 조합 가능
2. /init 명령어로 시작하기
첫번째 프로젝트 설정
> /init is analyzing your codebase…
⏺ I'll analyze this codebase and create a comprehensive CLAUDE.md file for future Claude Code instances working with this project.
⏺ Search(pattern: "**/*")
⎿ Found 1 file (ctrl+o to expand)
⏺ Read(package.json)
⎿ Read 13 lines (ctrl+o to expand)
⏺ Search(pattern: "**/*.md")
⎿ Found 0 files
⏺ Search(pattern: "**/*.js")
⎿ Found 0 files
⏺ Search(pattern: "**/*.ts")
⎿ Found 0 files
⏺ Search(pattern: "**/*.tsx")
⎿ Found 0 files
⏺ Search(pattern: "**/*.jsx")
⎿ Found 0 files
⏺ Search(pattern: "*")
⎿ Found 1 file (ctrl+o to expand)
⏺ Search(pattern: ".github/**/*")
⎿ Found 0 files
⏺ Search(pattern: ".cursor/**/*")
⎿ Found 0 files
⏺ Search(pattern: "src/**/*")
⎿ Found 0 files
⏺ Write(CLAUDE.md)
⎿ Wrote 26 lines to CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is a Node.js project in early development stage with minimal initial setup.
## Commands
… +16 lines (ctrl+o to expand)
⏺ Created CLAUDE.md for this minimal Node.js project. The file provides essential context about the project's current state and development commands that will
help future Claude Code instances understand and work with this codebase effectively.
<!-- 생성된 CLUADE.md 파일 -->
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is a Node.js project in early development stage with minimal initial setup.
## Commands
### Development
- **Install dependencies**: `npm install` (when dependencies are added to package.json)
- **Run tests**: Currently no test framework is configured. The test script will exit with an error.
## Project Structure
This is a basic Node.js project with:
- `package.json` - Node.js project configuration
- Entry point expected at `index.js` (currently not created)
## Next Steps for Development
When implementing features in this project:
1. Consider adding a proper test framework (Jest, Mocha, etc.)
2. Add build/development scripts as needed
3. Create the main entry point `index.js` or update `package.json` if using a different entry point
> 한글로 변경해줘
<!-- 변경된 md 파일 -->
# CLAUDE.md
이 파일은 Claude Code (claude.ai/code)가 이 저장소에서 작업할 때 참고할 가이드입니다.
## 프로젝트 개요
초기 개발 단계의 Node.js 프로젝트입니다. 최소한의 설정만 되어 있습니다.
## 명령어
### 개발
- **의존성 설치**: `npm install` (package.json에 의존성이 추가된 후)
- **테스트 실행**: 현재 테스트 프레임워크가 설정되지 않음. 테스트 스크립트는 에러와 함께 종료됨.
## 프로젝트 구조
기본적인 Node.js 프로젝트 구조:
- `package.json` - Node.js 프로젝트 설정 파일
- 진입점은 `index.js`로 예상 (현재 생성되지 않음)
## 개발 시 다음 단계
이 프로젝트에 기능을 구현할 때:
1. 적절한 테스트 프레임워크 추가 고려 (Jest, Mocha 등)
2. 필요에 따라 빌드/개발 스크립트 추가
3. 메인 진입점 `index.js` 생성 또는 다른 진입점 사용 시 `package.json` 수정단, 한글이 영어보다 1.5~2 토큰 정도 더 소비된다.
팀 구성원과 토큰 소비량을 고려하여 (영어, 한글, 하이브리드)선택이 필요하다.
3. 실제 프로젝트로 실습하기
실습 1:리엑트 프로젝트 생성 및 초기화
(base) mingeon@gimmingeon-ui-MacBookAir-2 Mon % npx create-react-app my-react-app
Need to install the following packages:
create-react-app@5.1.0
Ok to proceed? (y) y
npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
npm warn deprecated uid-number@0.0.6: This package is no longer supported.
npm warn deprecated rimraf@2.7.1: Rimraf versions prior to v4 are no longer supported
npm warn deprecated fstream-ignore@1.0.5: This package is no longer supported.
npm warn deprecated glob@7.2.3: Glob versions prior to v9 are no longer supported
npm warn deprecated fstream@1.0.12: This package is no longer supported.
npm warn deprecated tar@2.2.2: This version of tar is no longer supported, and will not receive security updates. Please upgrade asap.
create-react-app is deprecated.
You can find a list of up-to-date React frameworks on react.dev
For more info see:https://react.dev/link/cra
This error message will only be shown once per install.
Creating a new React app in /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-react-app.
Installing packages. This might take a couple of minutes.
Installing react, react-dom, and react-scripts with cra-template...
added 1325 packages in 31s
270 packages are looking for funding
run `npm fund` for details
Installing template dependencies using npm...
added 17 packages, and changed 1 package in 3s
270 packages are looking for funding
run `npm fund` for details
Removing template package using npm...
removed 1 package, and audited 1342 packages in 1s
270 packages are looking for funding
run `npm fund` for details
9 vulnerabilities (3 moderate, 6 high)
To address all issues (including breaking changes), run:
npm audit fix --force
Run `npm audit` for details.
Success! Created my-react-app at /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-react-app
Inside that directory, you can run several commands:
npm start
Starts the development server.
npm run build
Bundles the app into static files for production.
npm test
Starts the test runner.
npm run eject
Removes this tool and copies build dependencies, configuration files
and scripts into the app directory. If you do this, you can’t go back!
We suggest that you begin by typing:
cd my-react-app
npm start
Happy hacking!
(base) mingeon@gimmingeon-ui-MacBookAir-2 Mon % cd my-react-app
(base) mingeon@gimmingeon-ui-MacBookAir-2 my-react-app % claude
╭────────────────────────────────────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code! │
│ │
│ /help for help, /status for your current setup │
│ │
│ cwd: /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-react-app │
╰────────────────────────────────────────────────────────────────────────────────╯
> /init is analyzing your codebase…
⏺ I'll analyze the codebase and create a CLAUDE.md file with the essential information for future Claude
instances.
⏺ Read(package.json)
⎿ Read 40 lines (ctrl+o to expand)
⏺ Read(README.md)
⎿ Read 71 lines (ctrl+o to expand)
⏺ Search(pattern: "src/**/*.js")
⎿ Found 5 files (ctrl+o to expand)
⏺ Read(src/App.js)
⎿ Read 26 lines (ctrl+o to expand)
⏺ Read(src/index.js)
⎿ Read 18 lines (ctrl+o to expand)
⏺ Bash(ls -la)
⎿ total 1320
drwxr-xr-x@ 9 mingeon staff 288 9 22 23:15 .
drwxr-xr-x@ 7 mingeon staff 224 9 22 23:14 ..
… +7 lines (ctrl+o to expand)
⏺ Bash(ls -la .cursorrules .cursor/ 2>/dev/null || echo "No Cursor rules found")
⎿ No Cursor rules found
⏺ Bash(ls -la .github/copilot-instructions.md 2>/dev/null || echo "No Copilot instructions found")
⎿ No Copilot instructions found
⏺ Write(CLAUDE.md)
⎿ Wrote 56 lines to CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Common Development Commands
### Running the Application
```bash
# Start development server (http://localhost:3000)
npm start
… +46 lines (ctrl+o to expand)
⏺ Created CLAUDE.md with essential information for working with this React application. The file includes:
1. Common commands for development, testing, and building
2. Architecture overview highlighting the React 19 setup, CRA structure, and testing configuration
The file is concise and focused on actionable information specific to this codebase.생성된 CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Common Development Commands
### Running the Application
```bash
# Start development server (http://localhost:3000)
npm start
# Build for production
npm run build
# Run test suite in watch mode
npm test
# Run a single test file
npm test src/App.test.jsTesting Commands
# Run tests without watch mode (for CI)
CI=true npm test
# Run tests with coverage
npm test -- --coverage
# Run tests and update snapshots
npm test -- --updateSnapshotProject Architecture
This is a Create React App (CRA) project using React 19. The application follows a standard CRA structure with the following key aspects:
Entry Point
src/index.js- Application root that renders the App component into the DOM using React 19'screateRootAPI- Wrapped in
React.StrictModefor development warnings
Component Structure
src/App.js- Main application component- Components use functional components (no class components detected)
- Styles are imported as CSS modules alongside components
Testing Setup
- Uses React Testing Library (@testing-library/react)
- Jest configured through react-scripts
- Test files colocated with components using
.test.jssuffix src/setupTests.jsconfigures testing environment
Build System
- Uses react-scripts 5.0.1 (CRA's build tooling)
- No custom webpack configuration (not ejected)
- ESLint configured through react-app preset
초기화를 진행한뒤 요청은 리엑트 기반 코드 스타일과 CRA 구조에 맞는 답변을 생성한다.
/init → CLAUDE.md 는 AI와 프로젝트를 연결하는 출발점이자 반복 설명을 줄이는 도구다.
실습2: Express.js 프로젝트 초기화
클로드를 실행하며 /init을 호출했다.
(base) mingeon@gimmingeon-ui-MacBookAir-2 Mon % mkdir my-express-api
(base) mingeon@gimmingeon-ui-MacBookAir-2 Mon % cd my-express-api
(base) mingeon@gimmingeon-ui-MacBookAir-2 my-express-api % npm init -y
Wrote to /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-express-api/package.json:
{
"name": "my-express-api",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"type": "commonjs"
}
(base) mingeon@gimmingeon-ui-MacBookAir-2 my-express-api % npm install express
added 68 packages, and audited 69 packages in 2s
16 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
(base) mingeon@gimmingeon-ui-MacBookAir-2 my-express-api % touch app.js
(base) mingeon@gimmingeon-ui-MacBookAir-2 my-express-api % claude /init
╭──────────────────────────────────────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code! │
│ │
│ /help for help, /status for your current setup │
│ │
│ cwd: /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-express-api │
╰──────────────────────────────────────────────────────────────────────────────────╯
> /init is analyzing your codebase…
⏺ I'll analyze your Express API codebase and create a comprehensive CLAUDE.md file.
⏺ Read(package.json)
⎿ Read 17 lines (ctrl+o to expand)
⏺ Search(pattern: "**/*.js")
⎿ Found 100 files (ctrl+o to expand)
⏺ Search(pattern: "*.js")
⎿ Found 1 file (ctrl+o to expand)
⏺ Read(app.js)
⎿ Read 1 line (ctrl+o to expand)
⏺ Bash(ls -la /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-express-api/app.js)
⎿ -rw-r--r--@ 1 mingeon staff 0 9 22 23:36 /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/
my-express-api/app.js
⏺ Search(pattern: "*.md")
⎿ Found 0 files
⏺ Bash(ls -la /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-express-api/)
⎿ total 72
drwxr-xr-x@ 6 mingeon staff 192 9 22 23:36 .
drwxr-xr-x@ 7 mingeon staff 224 9 22 23:36 ..
… +4 lines (ctrl+o to expand)
⏺ Read(CLAUDE.md)
⎿ Error reading file
⏺ Bash(find /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-express-api -name "*.json" -path
"*/test/*" -o -name "*.json" -path "*/__tests__/*" 2>/dev/nul…)
⎿ (No content)
⏺ Bash(npm run 2>&1 | head -20)
⎿ Lifecycle scripts included in my-express-api@1.0.0:
test
echo "Error: no test specified" && exit 1
⏺ Write(CLAUDE.md)
⎿ Wrote 57 lines to CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is a minimal Express.js API project using Express v5.1.0. The project is currently in initial
setup phase with no implemented endpoints yet.
## Development Commands
… +47 lines (ctrl+o to expand)
⏺ I've created a CLAUDE.md file for your Express API project. The file provides essential guidance for
future Claude Code instances working with this repository, including:
1. Development commands for running and managing the application
2. Project structure highlighting that app.js is currently empty and needs implementation
3. Key technical notes about Express v5 breaking changes and the CommonJS module system being used
4. Implementation guidelines for setting up the Express server properly
The project appears to be a fresh Express v5.1.0 setup with no implemented code yet in app.js. The
CLAUDE.md file will help future instances understand the project context and provide guidance for
implementing the Express server.위 과정을 통해 Express 프로젝트에서도 자동으로 API 서버에 맞는 맥락을 반영한다.
의존성 설치, 개발 서버 실행 방법, 폴더 구조 등이 문서에 포함된다.
즉, 프론트엔드와 백엔드 모두에서 환경별 맥락에 맞는 답변을 제공한다.
4. CLAUDE.md 커스텀마이징
수동 편집하기
CLAUDE.md에 실제 프로젝트 맥락과 팀의 맥락 등 추가가 필요 하다면 직접 수정이 가능하다.
혹은 클로드 코드를 통해 작성할 수 있다.
> 이 프로젝트에 최적화된 CLAUDE.md 파일을 작성해
⏺ I'll analyze your Express API project and create an optimized CLAUDE.md file tailored specifically for
this codebase.
⏺ Read(app.js)
⎿ Read 1 line (ctrl+o to expand)
⏺ Bash(cat /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-express-api/app.js)
⎿ (No content)
⏺ Bash(find /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/my-express-api -type f -name "*.js" -not
-path "*/node_modules/*" | xargs ls -la 2>/dev/null)
⎿ -rw-r--r--@ 1 mingeon staff 0 9 22 23:36 /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/
my-express-api/app.js
⏺ Bash(ls -la /Users/mingeon/Desktop/vscode/_Book_Claude-Code/week2/Mon/)
⎿ total 8
drwxr-xr-x@ 7 mingeon staff 224 9 22 23:36 .
drwxr-xr-x@ 8 mingeon staff 256 9 21 22:06 ..
… +5 lines (ctrl+o to expand)
⏺ Read(~/Desktop/vscode/_Book_Claude-Code/week2/Mon/README.md)
⎿ Read 9 lines (ctrl+o to expand)
⏺ Update(CLAUDE.md)
⎿ Updated CLAUDE.md with 70 additions and 34 removals
2
3 This file provides guidance to Claude Code (claude.ai/code) when working with code in this
repository.
4
5 - ## Project Overview
5 + ## 프로젝트 개요
6
7 - This is a minimal Express.js API project using Express v5.1.0. The project is currently in
- initial setup phase with no implemented endpoints yet.
7 + Express.js v5.1.0 기반 RESTful API 백엔드 서비스 프로젝트입니다. 현재 초기 설정 단계입니다.
8
9 - ## Development Commands
9 + ## 개발 명령어
10
11 - ### Running the Application
11 + ### 애플리케이션 실행
12 ```bash
13 - # Start the application (once app.js is implemented)
13 + # 개발 서버 실행
14 node app.js
15 +
16 + # nodemon으로 개발 서버 실행 (설치 필요: npm install --save-dev nodemon)
17 + npx nodemon app.js
18 ```
19
20 - ### Dependencies
20 + ### 패키지 관리
21 ```bash
22 - # Install dependencies
22 + # 의존성 설치
23 npm install
24
25 - # Add new dependencies
26 - npm install <package-name>
27 -
28 - # Add development dependencies
25 + # 개발 의존성 추가
26 npm install --save-dev <package-name>
27 ```
28
29 - ## Project Structure
29 + ## 프로젝트 구조
30
31 - - **app.js**: Main application entry point (currently empty, needs Express server
- implementation)
32 - - **package.json**: Project configuration using CommonJS modules
33 - - **Express Version**: v5.1.0 (latest major version with breaking changes from v4)
31 + ```
32 + my-express-api/
33 + ├── app.js # 메인 진입점 (구현 필요)
34 + ├── package.json # CommonJS 모듈 시스템 사용
35 + └── node_modules/ # Express v5.1.0 및 의존성
36 + ```
37
38 - ## Key Technical Notes
38 + ## Express v5 주요 특징
39
40 - ### Express v5 Considerations
41 - - Express v5 has breaking changes from v4, notably:
42 - - Removed built-in middleware (body-parser, etc. must be installed separately)
43 - - Updated error handling patterns
44 - - Promise-based route handlers are automatically caught
40 + ### Breaking Changes (v4와의 차이점)
41 + - 내장 미들웨어 제거 (body-parser 등 별도 설치 필요)
42 + - Promise 기반 라우트 핸들러 자동 에러 캐치
43 + - `app.del()` → `app.delete()` 변경
44 + - `req.host` → `req.hostname` 권장
45
46 - ### Module System
47 - - Project uses CommonJS (`"type": "commonjs"` in package.json)
48 - - Use `require()` for imports and `module.exports` for exports
46 + ### 구현 시 필수 설정
47 + ```javascript
48 + // CommonJS 모듈 시스템 사용
49 + const express = require('express');
50 + const app = express();
51
52 - ## Implementation Guidelines
52 + // JSON 파싱 미들웨어 (Express v5에서는 별도 설정 필요)
53 + app.use(express.json());
54 + app.use(express.urlencoded({ extended: true }));
55
56 - When implementing the Express server:
57 - 1. Set up basic Express server configuration in app.js
58 - 2. Consider adding middleware for common needs:
59 - - `body-parser` or `express.json()` for JSON parsing
60 - - `cors` for CORS handling if building an API
61 - - `helmet` for security headers
62 - 3. Structure routes modularly (consider creating a `routes/` directory)
63 - 4. Add error handling middleware at the end of the middleware stack
64 - 5. Use environment variables for configuration (PORT, etc.)
56 \ No newline at end of file
57 + // 에러 핸들링 (맨 마지막에 추가)
58 + app.use((err, req, res, next) => {
59 + res.status(err.status || 500).json({ error: err.message });
60 + });
61 + ```
62 +
63 + ## API 구현 가이드라인
64 +
65 + ### 프로젝트 구조 권장사항
66 + ```
67 + my-express-api/
68 + ├── app.js # Express 앱 설정
69 + ├── server.js # 서버 시작 (선택적 분리)
70 + ├── routes/
71 + │ ├── index.js # 라우트 통합
72 + │ └── users.js # 엔드포인트별 분리
73 + ├── middleware/
74 + │ └── auth.js # 커스텀 미들웨어
75 + ├── controllers/
76 + │ └── userController.js # 비즈니스 로직
77 + └── .env # 환경 변수 (PORT, DB_URL 등)
78 + ```
79 +
80 + ### RESTful API 설계 원칙
81 + - GET: 리소스 조회
82 + - POST: 리소스 생성
83 + - PUT/PATCH: 리소스 수정
84 + - DELETE: 리소스 삭제
85 + - 적절한 HTTP 상태 코드 사용 (200, 201, 400, 404, 500 등)
86 +
87 + ### 필수 미들웨어 추천
88 + ```bash
89 + npm install cors helmet morgan dotenv
90 + ```
91 + - `cors`: Cross-Origin 요청 처리
92 + - `helmet`: 보안 헤더 설정
93 + - `morgan`: HTTP 요청 로깅
94 + - `dotenv`: 환경 변수 관리
95 \ No newline at end of file
Tip: Use # to memorize shortcut to quickly add to CLAUDE.md
⏺ Express API 프로젝트에 최적화된 CLAUDE.md 파일을 작성했습니다. 주요 특징:
1. 한국어로 작성: 프로젝트 컨텍스트에 맞게 한국어로 문서화
2. Express v5 특화: v4와의 주요 차이점과 breaking changes 명시
3. 실용적인 코드 예제: CommonJS 모듈 시스템과 필수 미들웨어 설정 코드 포함
4. 구조화된 프로젝트 가이드: RESTful API 구현을 위한 권장 디렉토리 구조
5. 개발 도구 추천: nodemon, cors, helmet 등 실무에서 자주 사용하는 패키지들
이 CLAUDE.md는 향후 Claude Code가 이 프로젝트에서 Express API를 구현할 때 필요한 모든 핵심 정보를 담고
있습니다.CLAUDE.md 메모리 스코프와 파일 위치
- CLAUDE.md는 프로젝트 전역에 걸친 규칙부터 개인 개발자의 선호까지 서로 다른 범위를 관리 할 수 있다. 덕분에 팀 규칙과 개인 습관이 깔끔히 분리되면서 함께 작동한다.
- 클로드 코드는 두가지 메모리 스코프를 통해 서로 다른 범위의 컨텍스트를 관리한다.
클로드 코드의 메모리 스코프
| 스코프 유형 | 파일 위치 및 이름 | 적용 영역 | 주요 용도 및 내용 |
|---|---|---|---|
| User scope | |||
| (사용자 범위) | ~/.claude/CLAUDE.md | 모든 프로젝트 | 개인 설정(코딩 스타일, 툴, 환경변수 등) |
| Project scope | |||
| (프로젝트 범위) | <프로젝트>/CLAUDE.md | 특정 프로젝트 | 프로젝트 공통 컨벤션, 구조, 협업 규칙 문서화 |
CLAUDE.local.md 는 deprecated된 개인용 메모리이다.
실제 활용 예시
User Scope 예시(~/.claude/CLAUDE.md)
# 개발자 개인 설정(전역 적용)
## 개발자 정보
- 이름: 홍길동
- 경력: 개발자 3년차
- 전문 분야: React + Node.js 풀스택
## 선호 도구
- 에디터: VS Code
- 운영 체제: macOS
- 패키지 매니저: npm
- 스타일링: Tailwind CSSProject Scope 예시(~/proj/cafe_reservation_service/CLAUDE.md)
# 카페 예약 시스템(팀 공유 설정)
## 프로젝트 정보
- 프로젝트, 3개월 일정
- 팀 구성: 개발자 2명, 디자이너 1명
## 기술 스택
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL클로드 코드는 두가지 스코프를 자동으로 조합하여 최적의 컨텍스트 제공한다.
- User Scope의 개인 설정이 기본 베이스가 된다.
- Project Scope의 프로젝트 규칙이 개인 설정을 덮어쓴다.
eg. 개인 선호 도구(User scope)에서 프로젝트 기술 스택을 가져와 종합적인 컨텍스트를 구성한다.
프롬포트 작성 팁
효과적인 대화를 위한 팁
- 구체적이고 명확한 요청: 모호한 요청보다는 구체적인 요구사항을 제시
- 컨텍스트 제공: 프로젝트 상황, 기술 스택, 제약사항 등을 명시
- 단계별 접근: 복잡한 작업은 작은 단위로 나누어 진행
CLAUDE.md 작성 베스트 프랙티스
CLAUDE.md는 AI 작업 설명서이므로, 간결하고 핵심을 빠짐없이 기입한다.
작성 원칙
- 간결성 우선: 장황한 설명보다는 짧고 명확한 표현
- 선언적 형태: 문장보다 점스타일 위주
- 토큰 효율성: 불필요한 서술 제거
- 실시간 업데이트: 프로젝트 진행에 따라 주기적으로 개선
필수 포함 요소
- 기술 스택(Tech Stack)
# Tech Stack
- Next.js 14
- TypeScript 5.2
- Tailwind CSS 3.4
- Prisma ORM
- PostgreSQL 15- 프로젝트 구조(Project Structure)
# Structure
- 'src/app': Next.js App Router pages
- 'src/components': Reusable React components
- 'src/lib': Utility functions
- 'src/types': TypeScript definitions- 핵심 명령어(Commands)
# Commands
- 'npm run dev': Start development server
- 'npm run build': Production build
- 'npm run test': Run Jest tests
- 'npm run db:migrate': Apply database migrations- 코딩 스타일(Code Style)
# Code Style
- Components: PascalCase
- Files: kebab-case
- Functions: camelCase
- Constants: UPPER_SNAKE_CASE
- Imports: Group external -> internal -> relative- 저장소 규칙(Repository Etiquette)
# Git Workflow
- Branchs: feature/description, fix/description
- Commites: "type: description" (feat, fix, docs, style)
- Merge: Squash commits on mainCLAUDE.md 활용 고급 팁
1. 계층적 CLAUDE.md 전략
project-root/
├── CLAUDE.md # 프로젝트 전체 컨텍스트
├── backend/
│ └── CLAUDE.md # 백엔드 전용 가이드
├── frontend/
│ └── CLAUDE.md # 프론트엔드 전용 가이드
└── docs/
└── CLAUDE.md # 문서화 가이드2. 동적 CLAUDE.md 관리
초기 단계:
# Status: Planning Phase(상태: 계획 단계)
# Focus: Architecture decisions, tech stack evaluation(포커스: 아키텍처 결정, 기술 스택 평가)개발 단계:
# Status: Active Development (Week 8/12)(상태: 개발 진행 중)
# Focus: Feature implementation, code review(포커스: 기능 구현, 코드 리뷰)
# Current Sprint: User authentication, reservation system(햔제 스프린트: 사용자 인증, 예약 시스템)배포 준비:
# Status: Pre-production(상태: 프리-프로덕션 상태)
# Focus: Performance optimization, security reveiw(포커스: 성능 최적화, 보안 검토)
# Deploy: Staging environment ready(배포: 스테이징 환경 준비 완료)3. 팀 협업을 위한 CLAUDE.md
# Team Context(팀 컨텍스트)
- Lead: Frontend specialist, 5+ years React(리드: 프론트엔드 전문가, 리액트 5년 이상)
- Junior: Backend learning, Node.js focus(주니어: 백엔드 학습 중, Node.js 중심)
- Designer: UI/UX, Figma handoffs(디자이너: UI/UX, 피그마 전달물 작업)
# Code Review Guidelines(코드 리뷰 가이드라인)
- Security: Required for auth/payment(보안: 인증/결제 기능에는 필수)
- Performance: Required for DB queries(성능: 데이터베이스 쿼리에는 필수)
- Accessibility: Required for all UI(접근성: 모든 UI에 필수)
# Documentation Standards(문서화 표준)
- API: OpenAPI spec in /docs/api.yaml(API: /docs/api.yaml에 OpenAPI 스펙 작성)
- Components: Storybook stories required(컴포넌트: Storybook 스토리 필수)
- Functions: JSDoc for utilities(함수: 유틸리티 함수에 JSDoc 필수)5. CLAUDE.md 활용 전략
프로젝트별 맞춤 설정
계약 프로젝트는 클라이언트의 상황과 일정 제약을, 개인 학습 프로젝트는 실험적 시도와 장기적인 품질 향상을 중심으로 작성한다.
프로젝트용:
# Project Context(프로젝트 컨텍스트)
- Type: Freelance contract (3months)(타입: 프리랜스 계약 3개월)
- Client: Non-technical cafe owner(클라이언트: 비전문가 카페 사장)
- Budget: Conservative, MVP focus(예산: 보수적, MVP 중심)
- Timeline: Tight, iterative delivery(일정: 촉박, 반복적 전달 방식)개인용:
# Project Context(프로젝트 컨텍스트)
- Type: Portfolio/Learning project(타입: 포트폴리오/학습 프로젝트)
- Goal: Skill development, experimentation(목표: 기술 역량 개발, 실험)
- Timeline: Flexible, quality over speed(일정: 유연함, 속도보다 품질 중시)팀 협업을 위한 CLAUDE.md
팀 협업은 역할, 코드 리뷰 규칙, 협업 기준이 중요하다.
# Team Context(팀 컨텍스트)
- Lead: Frontend specialist, 5+ years React(리드: 프런트엔드 전문가, 리엑트 5년 이상)
- Junior: Backend learning, Node.js focus(주니어: 백엔드 학습 중, Node.js 중심)
- Designer: UI/UX, Figma hands(디자이너: UI/UX, 피그마 전달물 작업)
# Code Review Guidelines(코드 리뷰 가이드라인)
- Security: Required for auth/payments(보안: 인증/결제 기능에 필수)
- Performance: Required for DB queries(성능: 데이터베이스 쿼리에 필수)
- Accessibility: Required for all UI(접근성: 모든 UI에 필수)토큰 효율성 최적화
Before
이 프로젝트는 React와 TypeScript를 사용하여 개발되고 있으며,
Tailwind CSS를 사용해서 스타일링을 하고 있습니다.
또한 백엔드는 Node.js와 Express를 사용하여 구축되어 있고,
데이터베이스로는 PostgreSQL을 사용하고 있습니다.After
# Tech
- React 18 + TypeScript
- Tailwind CSS
- Node.js + Express
- PostgreSQL자동 업데이트 워크플로
프로젝틑 시간에 따라 끊임없이 변하므로 CLAUDE.md를 지속적으로 업데이트 해야한다.
클로드에게 변경사항을 반영하도록 요청할 수 있다.
주간 CLAUDE.md 업데이트
> 이번 주 개발 진행 상황을 반영해서 CLAUDE.md를 업데이트해
기술 스택 변경 시
> 업그레이드한 패키지를 CLAUDE.md의 버전 정보에 반영해
새로운 팀원 합류시
> 새로운 팀원이 합류했어. 온보딩용 정보를 CLAUDE.md에 추가해6. 문제 해결 및 팁
- CLAUDE.md 가 너무 간단한 경우
- 파일 추가 후 /init 재실행
- 수동으로 보완 작성
- 클로드에게 작성 요청
- 팀 프로젝트에서의 관리는?
- 깃에 CLAUDE.md를 커밋하여 팀원들과 공유
- 팀 컨벤션 정의 후 CLAUDE.md에 명시
- 정기적으로 업데이트
- CLAUDE.md가 너무 길어서 토큰 소모가 큰 경우
- 핵심 정보만 남기고 상세 설명 제거
- 점스타일 형식으로 간결하게 작성
- 중복 정보 통합
- 별도 문서 파일로 분리
- 팀원마다 다른 설정을 사용하고 싶은 경우
- 개인별 설정 파일을 .gitignore에 등록 CLAUDE.md에서 참조하도록 작업
- 개인별 User scopedml CLAUDE.md(~/.claude/CLAUDE.md) 활용
현재 팀에서는 각자 클로드를 사용중이다.
컨벤션 룰에 대한 내용 및 코드 품질에 대한 내용을 팀 컨벤션으로 추가하여 반영하는 것을 고려한다.
반응형
'AI > Claude code' 카테고리의 다른 글
| [Claude code]5. 고양이 웹 페이지 만들고 공개하기 (0) | 2025.09.21 |
|---|---|
| [Claude code]4. 넘겨받은 디렉터리 분석 및 조치 (0) | 2025.09.21 |
| [Claude code]3. 인공지능으로 내 컴퓨터에만 있는 정보 분석하기 (0) | 2025.09.21 |
| [Claude code]2. 클로드 코드에서 제공하는 내장 명령어 (0) | 2025.09.16 |
| [Claude code]1. 클로드 코드 설치하기 (0) | 2025.09.16 |