UX 개발 / Claude Code

Claude Code 프로젝트 시작법: 재사용 가능한 하네스와 환경설정

Claude Code하네스 엔지니어링CLAUDE.md프로젝트 설정플러그인AI 코딩
Claude Code 프로젝트 시작법: 재사용 가능한 하네스와 환경설정

새 프로젝트에서 Claude Code 공식 웹사이트를 열자마자 플러그인과 긴 지침부터 채울 필요는 없다. 먼저 프로젝트가 무엇을 만드는지, 실제 실행·검증 명령이 무엇인지, 어디까지 바꿔도 되는지를 Claude와 사람이 함께 확인할 수 있게 만들면 된다. 그 위에 반복해서 드러나는 문제만 자동화한다.

이 글은 2026년 10월 13일 기준 공식 빠른 시작, 모범 사례, 확장 기능 안내를 바탕으로 작성했다. 끝에는 다른 저장소에 복사해 수정할 수 있는 시작 템플릿 ZIP도 제공한다.

핵심 원칙: 작은 하네스를 먼저 만든다

여기서 하네스 엔지니어링은 AI에게 긴 프롬프트를 주는 일이 아니다. 프로젝트 설명, 도구 접근, 작업 경계, 테스트와 리뷰를 연결해 변경 사항을 다시 확인할 수 있게 만드는 실무 방식이다. Anthropic의 장기 실행 에이전트 하네스 연구는 작은 작업 단위와 진행 기록, 실제 동작 검증의 중요성을 보여 준다. 다만 그 연구는 Agent SDK 실험이므로, 아래 구성은 그것을 Claude Code 프로젝트에 가볍게 적용한 이 글의 제안이다.

질문시작 구성 → 필요할 때 확장
무엇을 만들고 누구를 위한 것인가?README.md, docs/project-brief.md → 상세 기획 문서
매 세션 어떤 사실을 알아야 하나?짧은 CLAUDE.md 또는 AGENTS.md → 경로별 .claude/rules/
어떻게 성공을 확인하나?실제 테스트·빌드 명령과 완료 기준 → hook, CI, 독립 리뷰
반복 절차가 생겼나?요청에 명시 → 프로젝트 skill
외부 시스템이 필요한가?기본 연결 없음 → 최소 권한 MCP
여러 프로젝트에 같은 기능을 배포하나?개별 설정 → plugin

Claude Code 공식 확장 개요에서 CLAUDE.md, Skills, MCP와 Subagents의 역할을 설명하는 화면

Anthropic의 Claude Code 확장 기능 공식 문서 공개 화면. 상시 지침에서 시작해 필요한 확장만 추가하는 구조를 보여 준다. (2026-10-13 캡처)

공식 문서도 처음에는 CLAUDE.md로 관례를 기록하고, 특정 필요가 생길 때 확장하라고 안내한다. 플러그인 수가 많거나 CLAUDE.md가 길다고 프로젝트 이해도가 자동으로 높아지지는 않는다.

1. 설치하고 저장소 루트에서 시작하기

macOS·Linux·WSL에서는 공식 문서의 권장 네이티브 설치 명령을 사용한다. 설치 스크립트를 실행하기 전에 도메인이 공식 claude.ai인지 확인하고, 팀 보안 정책이 있으면 그 배포 방법을 따른다. Windows나 Homebrew를 쓰는 경우에는 운영체제별 공식 설치 방법을 참고한다.

curl -fsSL https://claude.ai/install.sh | bash
claude --version
cd /path/to/your/project
claude

첫 실행에서는 계정 로그인 안내가 나온다. Claude 구독, Console/API 계정 또는 지원되는 클라우드 제공자 접근 권한이 필요하다. 세션 안에서 /help로 사용 가능한 명령을 확인한다.

기존 코드가 있다면 먼저 이렇게 요청한다.

파일을 수정하지 말고 이 저장소의 목적, 진입점, 실제 실행·테스트·빌드 명령,
주요 디렉터리, 현재 실패하는 검사와 모르는 점을 찾아 요약해 줘.
추측한 내용과 파일에서 확인한 내용을 구분해 줘.

그 다음 /init으로 프로젝트 지침 초안을 만든다. 이미 CLAUDE.md가 있으면 덮어쓰는 대신 개선안을 제시한다. 생성된 명령은 직접 실행해 맞는지 확인하고, /context의 Memory files에서 실제 로드 여부를 살핀다. 새 저장소라서 아직 테스트가 없다면 테스트 명령을 지어내지 말고, 첫 번째 작은 기능과 함께 통과·실패가 구분되는 최소 검사를 만든다.

2. 프로젝트 내용을 어디에 담을까?

아래 구조는 Claude Code가 강제하는 표준이 아니라, 사람과 에이전트가 함께 쓰기 좋은 이식 가능한 출발점이다.

your-project/
├── README.md                   # 사람이 읽는 제품·실행 개요
├── CLAUDE.md                   # 매 세션 필요한 짧은 규칙
├── docs/
│   ├── project-brief.md        # 사용자, 문제, 범위, 성공 기준
│   └── architecture.md         # 모듈 경계와 중요한 결정
└── .claude/
    ├── settings.json           # 필요할 때만 팀 공용 권한·hook 설정
    └── skills/                 # 반복 절차가 생길 때 추가

README.md에는 사람이 프로젝트를 실행하고 이해하는 데 필요한 개요를, project-brief.md에는 제품 목적과 이번에 만들지 않을 것을 쓴다. CLAUDE.md는 Claude가 매 세션 알아야 할 짧은 운영 규칙만 둔다. 상세 API 명세나 긴 작업 절차를 그대로 옮기지 않는다.

공식 Claude Code 문서의 CLAUDE.md와 자동 메모리 비교표

Anthropic의 프로젝트 기억 공식 문서 공개 화면. 사람이 작성하는 CLAUDE.md와 Claude가 축적하는 자동 메모리의 역할을 구분한다. (2026-10-13 캡처)

공식 문서는 CLAUDE.md를 200줄 미만을 목표로 짧고 구체적으로 유지하라고 권한다. @docs/... import는 파일을 나누는 데는 유용하지만, 시작 시 내용을 함께 읽으므로 컨텍스트를 절약하지 않는다. 긴 문서는 평소에는 경로만 알려 주고 해당 작업에서 읽게 한다. 여러 코딩 도구가 공통으로 쓰는 AGENTS.md가 이미 있다면 최근 Claude Code는 직접 읽을 수 있다. 다만 프로젝트나 상위 디렉터리에 CLAUDE.md 또는 CLAUDE.local.md가 있으면 기본 설정에서는 AGENTS.md 대신 그것을 읽는다. 둘을 함께 유지할 때는 CLAUDE.md에서 @AGENTS.md를 가져오거나 /config의 Project instructions 설정을 확인한다.

3. 바로 복사할 수 있는 두 문서

먼저 docs/project-brief.md에 제품의 내용을 적는다. 아래 대괄호는 프로젝트에 맞게 바꾸고, 모르면 미정이라고 쓴다. 모호한 부분을 그럴듯하게 채우는 것보다 확인할 질문으로 남기는 편이 낫다.

# Project brief

## 목적
- 대상 사용자: [누가 사용하나]
- 해결할 문제: [현재 어떤 불편이 있나]
- 성공한 상태: [사용자가 무엇을 할 수 있나]

## 범위
- 이번에 포함: [핵심 흐름 1~3개]
- 이번에 제외: [명시적인 비목표]

## 제약
- 기술/운영 제약: [스택, 지원 환경, 일정 등]
- 민감 정보: [실제 값이 아닌 환경변수 이름과 보관 위치만]

## 첫 완료 기준
- 동작 확인: [재현 가능한 시나리오]
- 자동 검사: [실제로 실행되는 테스트/빌드 명령]
- 사람 검토: [결정이 필요한 항목]

다음은 루트 CLAUDE.md의 최소 예시다. 명령과 경로가 실제 저장소와 일치하도록 고친 뒤 사용한다.

# Project operating guide

## Purpose
- Build: [one-sentence product goal]
- Read `docs/project-brief.md` when product scope is relevant.
- Read `docs/architecture.md` when changing module boundaries.

## Verified commands
- Dev: [actual command]
- Targeted test: [actual command]
- Build or typecheck: [actual command]

## Boundaries
- Follow existing patterns; avoid unrelated refactors.
- Do not add dependencies or change public APIs without explaining why.
- Do not put secrets or real customer data in files or output.
- Keep generated files and deployment settings untouched unless the task needs them.

## Done means
- Run the smallest relevant check, then the required broader checks.
- Report changed files, commands run, results, and remaining risks.
- Show the diff for review before commit or deployment.

여기서 Read docs/...는 경로를 언급한 것이지 전체 파일을 자동 import하는 지시가 아니다. 프로젝트 규모가 커지면 파일 종류별 규칙을 .claude/rules/의 paths: frontmatter로 분리하고, 여러 단계의 반복 작업은 .claude/skills/<name>/SKILL.md로 옮긴다. 처음부터 빈 skill 파일을 여러 개 만들 필요는 없다.

4. 설정과 권한은 팀 공용·개인을 나누기

공식 설정 범위 안내에 따르면 ~/.claude/settings.json은 개인 공통, .claude/settings.json은 저장소에 공유할 팀 설정, .claude/settings.local.json은 현재 프로젝트의 개인 설정이다. 로컬 파일을 직접 만들었다면 Git 제외 규칙을 확인한다. 프로젝트별 개인 지침은 CLAUDE.local.md에 둘 수 있지만 이것도 Git에서 제외한다.

팀 설정은 필요한 항목만 넣는다. 예를 들어 다음은 Claude의 직접 파일 읽기 도구가 루트 .env 파일을 여는 것을 차단하는 출발 예시다.

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

이 규칙을 운영체제 수준의 비밀 보호로 오해하면 안 된다. 다른 명령이나 스크립트를 통한 간접 접근까지 막는 샌드박스는 아니므로, 실무 비밀은 저장소에 넣지 않고 별도 보관·최소 권한·격리 환경을 병행한다. bypassPermissions를 편의상 켜 두는 방식도 피한다. 승인 정책과 실행 환경은 프로젝트의 위험도에 맞춰 공식 권한 문서에서 확인한다.

5. 첫 번째 작업은 탐색 → 작은 변경 → 검증

새 기능을 한 번에 크게 맡기기보다 파일, 성공 조건, 제외 범위와 검사 방법을 한 작업 단위로 묶는다. 아래 텍스트를 첫 작업 요청의 틀로 재사용할 수 있다.

@docs/project-brief.md를 읽고 이번 작업과 관련된 코드만 먼저 찾아 줘.

목표: [사용자가 얻게 될 결과]
현재 상태: [버그 증상 또는 빈 기능]
성공 조건: [입력/출력 또는 화면에서 확인할 결과]
범위: [수정 가능한 모듈·파일]
제외: [이번에 하지 않을 변경]
검증: [실제 테스트/빌드/스크린샷 명령]

먼저 확인한 사실과 모르는 점을 알려 줘. 복잡한 변경이면 계획을 보여 준 뒤,
가장 작은 단위로 구현하고 검증 결과와 남은 위험을 보고해 줘.

Anthropic의 모범 사례는 실행 가능한 테스트·빌드·스크린샷을 Claude에게 주고, 복잡한 작업에는 탐색→계획→구현을 분리하라고 권한다. 단순한 오탈자 수정까지 계획 모드를 강제할 필요는 없다. 변경 후에는 내장 /verify나 해당 프로젝트의 실제 테스트를 실행하고, 중요한 변경은 다른 관점의 리뷰와 사람의 diff 검토까지 거친다. 테스트가 없으면 “통과”라고 쓰지 말고 검증하지 못한 범위를 보고한다.

작업 중에 다음 세션도 알아야 할 사실을 발견했다면, 명령·경로·예외 조건만 짧게 CLAUDE.md 또는 해당 문서에 반영한다. 한 번의 대화 기록을 통째로 붙이지 않는다. 장기 작업은 미완 항목과 마지막 검증 결과를 작업 문서나 이슈에 남겨 새 세션에서도 이어갈 수 있게 한다.

6. 플러그인은 어떤 순서로 고를까?

Claude Code에는 기본 도구와 내장 skill이 있다. 먼저 /help에서 /run, /verify, /code-review 등 현재 설치본에 제공되는 기능을 확인한다. 그 후 반복되는 문제에 맞는 공식 플러그인을 하나씩 더한다. 아래 이름은 Anthropic 공식 플러그인 저장소에서 확인할 수 있다.

플러그인알맞은 때와 확인할 점
claude-md-management구조 변경 후 CLAUDE.md를 감사할 때. 제안된 diff는 사람이 승인한다.
frontend-designUI 구현이 반복될 때. 기존 디자인 시스템과 충돌하는지 확인한다.
typescript-lspTS/JS 탐색과 진단이 많을 때. 별도 언어 서버 설치가 필요하다.
code-reviewPR 전 독립 검토가 필요할 때. 지적 사항을 실제 코드·테스트로 재확인한다.
security-guidance인증·민감 정보 작업이 잦을 때. 보안 검토나 CI를 대체하지 않는다.
feature-dev기존 코드베이스의 복잡한 기능 개발. 빈 프로젝트나 작은 수정에는 과하다.

공식 마켓플레이스 claude-plugins-official은 보통 첫 대화형 실행 시 등록된다. 세션 안에서 /plugin으로 먼저 탐색하거나, 예를 들어 다음 명령으로 상세 화면을 열어 설치 범위와 구성을 검토한다.

/plugin install frontend-design@claude-plugins-official

Claude Code 공식 문서에서 플러그인 이름과 마켓플레이스를 지정해 설치 상세를 여는 방법

Anthropic의 플러그인 설치 공식 문서 공개 화면. /plugin install 이름@마켓플레이스가 상세·범위 선택 화면을 여는 과정을 보여 준다. (2026-10-13 캡처)

공식 마켓플레이스가 없다면 /plugin marketplace add anthropics/claude-plugins-official을 먼저 실행한다. 플러그인은 skill뿐 아니라 hook이나 MCP 서버를 포함할 수 있으므로 설치 전에 내용을 읽고 필요한 범위에만 활성화한다. CLAUDE.md 관리 플러그인의 상세 사용법은 별도 실전 가이드에 정리했다.

다른 프로젝트에 옮기는 방법

시작 템플릿 ZIP 다운로드에는 CLAUDE.md, docs/project-brief.md, docs/architecture.md, 선택적으로 적용할 settings.example.json과 안내문이 들어 있다. 기존 프로젝트에 바로 압축을 풀어 같은 이름의 파일을 덮어쓰지 말고, 별도 폴더에서 열어 필요한 부분만 복사한다. 템플릿의 대괄호·TODO·예시 명령을 실제 정보로 바꾸고, 첫 세션에서 /context와 실제 테스트 명령으로 확인한다.

마지막으로 다음 다섯 가지만 점검하면 충분하다.

  1. 목적·사용자·포함/제외 범위가 project-brief.md에 있다.
  2. CLAUDE.md의 명령과 경로가 실제로 존재하고 짧다.
  3. 가장 작은 성공/실패 검사가 한 번 실행됐다.
  4. 비밀 값이 Git과 지침 파일에 없고, 권한 범위가 검토됐다.
  5. 첫 변경은 diff·테스트 결과·남은 위험을 보고한 뒤 사람이 검토한다.

하네스는 한 번에 완성하는 설정 모음이 아니라, 반복되는 실수를 발견할 때 정확한 층에 한 가지씩 더하는 과정이다. 더 넓은 설계 원칙은 Claude Code 하네스 엔지니어링 글에서 이어서 볼 수 있다.

Related