처음부터 제대로 시작하기
Claude Code를 쓰다 보면 어느 순간 같은 설명을 반복하고 있는 자신을 발견하게 된다. 프로젝트 구조, 금지 규칙, 완료 기준. 매번 대화창에 길게 쓰는 대신, 파일로 한 번만 정의해두면 된다
이 글에서 소개하는 템플릿은 정답이 아니라 출발점이다. 그대로 쓰기보다 내 프로젝트에 맞게 고쳐 쓰는 뼈대로 활용하면 된다
세 파일의 역할부터 이해한다
Claude Code에서 가장 먼저 잡아야 할 파일은 세 개다. 비슷해 보이지만 다루는 층이 다르다
CLAUDE.md → 항상 읽히는 프로젝트 운영 계약서 .claude/rules/*.md → 경로별 세부 규칙 .claude/settings.json → 실제 허용·차단 잠금장치
CLAUDE.md가 “이 방에 들어가지 마세요”라는 안내문이라면, settings.json은 실제 자물쇠다. 안내문만 있고 자물쇠가 없으면 결국 들어간다
CLAUDE.md 템플릿
처음부터 완벽하게 채우려 하지 않아도 된다. 명령어 네 줄, 경계 몇 줄, 금지 규칙 몇 줄만 있어도 효과가 난다
# Project Contract ## Commands - install: `pnpm install` - dev: `pnpm dev` - test: `pnpm test` - lint: `pnpm lint` - build: `pnpm build` ## Boundaries - api: src/app/api/ - domain: src/features/ - ui: src/components/ ## Safety - never edit: .env, .env.* - always run: pnpm lint, pnpm test - ask before: deleting files, modifying schema ## Verification - unit: pnpm test -- [feature] - lint: pnpm lint
Safety 항목이 핵심이다. “Claude가 이 저장소에서 절대 놓치면 안 되는 것”을 먼저 적는 것이 목적이다
.claude/settings.json 템플릿
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Read",
"Edit",
"Write",
"Glob",
"Grep",
"Bash(pnpm lint)",
"Bash(pnpm test)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
}
}
권한 평가 순서는 deny → ask → allow다. 첫 번째로 매칭되는 규칙이 적용된다
주의할 점이 있다. Read(./.env)는 Claude의 파일 도구 읽기만 막는다. Bash(cat .env)까지 자동으로 막히지 않는다. 실제 민감 정보 차단은 permission rule과 sandbox 정책을 함께 봐야 한다
.claude/rules/ 템플릿
특정 경로에만 적용할 세부 규칙은 rules/ 폴더에 분리한다. paths를 지정하면 해당 파일을 다룰 때만 로드된다
--- paths: - "src/**/*.ts" --- # TypeScript Rules - avoid unused imports - keep functions small (under 30 lines) - add tests for behavior changes - prefer const over let
규칙 파일의 목적은 팀의 암묵지를 눈에 보이게 만드는 것이다. 사람마다 머릿속에 다른 “좋은 코드” 기준을 가지고 있을 때, 이 파일이 기준점 역할을 한다
Hook 템플릿: 편집 후 자동 린트
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "pnpm lint"
}
]
}
]
}
}
파일 편집이 일어날 때마다 자동으로 린트를 실행한다. “린트 돌려야지”를 기억하는 대신 환경이 알아서 검사하게 만드는 것이 핵심이다. 사람이 잊어버릴 것을 hook이 대신 잡아준다
실전 프롬프트 패턴
좋은 프롬프트는 세 가지를 함께 담는다
무엇을 해달라고 말하는가 (지시) 무엇을 먼저 읽게 할 것인가 (컨텍스트) 무엇을 통과해야 끝났다고 볼 것인가 (완료 기준)
이 셋 중 하나만 빠져도 결과가 흔들린다
버그 수정 프롬프트
CLAUDE.md, .claude/rules/testing.md, src/features/signup/, tests/signup.test.ts를 읽어라. 회원가입 폼 빈 값 제출 버그를 수정해줘. 단계별로 진행해줘: 1. 버그 원인 파악 2. 수정할 파일 범위 확인 3. 코드 수정 4. 테스트 실행 pnpm test -- signup과 pnpm lint를 모두 통과해야 완료다. 완료 후 handoff.md에 변경 내용과 남은 위험을 기록해줘.
코드 리뷰 프롬프트
이 diff를 리뷰해줘. 출력 형식: - correctness - regression risk - missing tests - security risk 각 항목별로 분리해서 작성해줘.
빠른 시작 카드: 버그 수정
처음 Claude Code를 쓸 때 막히는 지점이 “어디서 시작하지?”다. 아래 순서대로 따라가면 된다
CLAUDE.md .claude/settings.json .claude/rules/testing.md plan.md handoff.md
첫 프롬프트
CLAUDE.md, .claude/rules/testing.md, 관련 소스 파일을 읽어라. plan.md에 다음을 먼저 작성해줘: 1. 버그 원인 2. 수정 범위 3. 완료 기준 4. 회귀 위험 구현 후 pnpm test와 pnpm lint를 실행하고, 결과를 handoff.md에 남겨줘.
끝나는 기준: 코드 수정 내용, 테스트 결과, 남은 위험이 각각 분리되어 있어야 한다
파일명 규칙
좋은 파일명은 “나중의 나”와 “다음 세션의 Claude”가 둘 다 바로 이해할 수 있어야 한다
# 좋은 예 2026-03-23-weekly-brief-v1.md signup-empty-submit-plan.md api-auth-review-v2.md # 나쁜 예 최종.md 수정본2.md misc.md
날짜, 주제, 버전이 보이면 사람도 Claude도 훨씬 덜 헤맨다
자주 묻는 것
Skill은 많이 깔수록 좋을까?
아니다. Skill은 앱스토어 상품이 아니라 Claude가 읽어야 하는 추가 설명서다. 수가 많아지면 컨텍스트 비용이 커지고 어떤 Skill을 써야 할지 판단도 흐려진다. 팀이 매주 반복해서 쓰는 Skill 몇 개만 잘 다듬는 것이 훨씬 낫다
MCP는 많이 연결할수록 좋을까?
대체로 아니다. 연결이 많을수록 선택 비용과 컨텍스트 비용도 함께 올라간다. 프로젝트마다 실제로 필요한 것만 켜두고, 나머지는 꺼두는 편이 안정적이다
Prompt Engineering은 이제 필요 없을까?
여전히 중요하다. 다만 이제는 프롬프트만 잘 써서 해결하는 시대가 아니다. 파일 구조, 규칙, 권한, 검증이 약하면 긴 작업에서 흔들린다. Prompt Engineering의 비중이 Context Engineering과 Harness Engineering 안으로 재배치됐다고 이해하는 게 더 정확하다
출처 – Claude Code Claude Cowork 마스터 가이즈 – 제작자 CHOI