하네스 엔지니어링 - 클로드(CLAUDE) 기초 1. 에이전트 정의

CLAUDE 는 내부 Agent를 사용하며 현재 컨텍스트 창을 확장하는게 아니라 격리된 새 컨텍스트 창을 생성한다.

 

Agent는 격리된 새 컨텍스트에서 실행

[Claude의 메인 컨텍스트 기억]      [새로운 Agent의 컨텍스트]
  - 지금까지 대화 내용        ↔  - 빈 상태로 시작
  - 읽은 파일들                - 메인 컨텍스트의 지시만 파악
  - 내린 결정들                - 메인 컨텍스트의 기억은 모름

 

"확장" vs "격리" 차이

확장 (MCP 도구, Skills 등)

[Claude 컨텍스트의 기억]
  - 지금까지 대화 내용
  - 읽은 파일들
  - + 새 도구 추가됨  ← 같은 컨텍스트를 사용

팀장이 직접 새 능력을 얻는 것. 모든 맥락을 그대로 기억한 채로.

 

 

클로드에서 Agent 추가 방법

Claude Code를 사용하려면 Claude Pro ($20/월) 이상 플랜이 필요합니다. 무료 플랜은 지원되지 않습니다.

 

🍎 macOS
터미널을 열고 실행:
bashcurl -fsSL https://claude.ai/install.sh | sh

또는 Homebrew 사용:
bashbrew install claude-code

🐧 Linux
bashcurl -fsSL https://claude.ai/install.sh | sh

🪟 Windows
PowerShell (권장):
powershellirm https://claude.ai/install.ps1 | iex

CMD : 
curl -fsSL https://claude.ai/install.bat -o install.bat && install.bat

 

bash# 설치 확인
claude --version

# 문제 진단
claude doctor

# 프로젝트 경로로 이동
cd /home/myproject

# 로그인 (최초 1회) : claude를 실행할 폴더가 프로젝트 root가 됨
claude

 

 

Agent 파일 선언과 CLAUDE.md 정의 — 각각 역할이 다릅니다.

 

정확한 레이어 분리

파일담을 내용

CLAUDE.md	모든 에이전트가 공유하는 프로젝트 전체 규칙
.claude/agents/initializer.md	Initializer만의 책임과 행동 지침
.claude/agents/worker.md	Worker만의 책임과 행동 지침

 

---

1. CLAUDE.md에서 Initializer Agent 정의

CLAUDE.md는 모든 에이전트가 공유하는 프로젝트 룰이고, agent 정의 파일은 특정 역할의 범위를 좁히는 역할을 합니다. 이 두 레이어가 함께 작동합니다.

CLAUDE.md 예시 (관련 부분):

# Project Convention
 
## Agent 진입 조건
- `init.sh` 파일이 없으면 → **initializer** agent 실행
- `init.sh` 파일이 있으면 → **worker** agent 실행
---
 
## 공통 규칙 (모든 Agent 적용)
 
### Git
- 각 feature 완료 시 git commit 필수
- commit 메시지: `feat: <작업 내용>` 형식 사용
- 절대 `main` 브랜치에 직접 push 금지

### 코드 품질
- 테스트 없이 feature 완료 처리 금지
- 기존 테스트 파일 삭제 금지
- `package.json` 수정 시 반드시 명시적 승인 필요

### 프로젝트 구조
- `/src/api` — Express route handlers
- `/src/services` — Business logic
- `/src/db` — Database queries and migrations
- `/src/components` — React components
- `/src/lib` — Shared utilities

 

 

---

2. Initializer Agent 선언 — .claude/agents/ 파일

Agent는 .claude/agents/*.md 파일로 정의하며, 현재 컨텍스트 창을 확장하는 게 아니라 격리된 새 컨텍스트 창을 생성합니다.

your-project/
└── .claude/
    └── agents/
        ├── initializer.md   ← 최초 1회 실행
        └── worker.md        ← 이후 반복 실행

 

 

.claude/agents/initializer.md 예시:

---
name: initializer
description: 
  프로젝트 최초 실행 시 환경을 세팅하는 에이전트.
  init.sh가 없거나 claude-progress.txt가 없을 때 호출.
model: claude-opus-4-5
tools:
  - Read
  - Write
  - Bash
  - Glob
---
 
당신은 프로젝트 초기화 전담 에이전트입니다.
feature 코드는 절대 작성하지 않습니다. 환경 세팅만 담당합니다.
 
## 역할
이후 실행될 worker agent가 맥락 없이도 바로 작업을 시작할 수 있도록
아래 산출물을 생성하는 것이 유일한 목표입니다.
 
---
 
## 필수 산출물
 
### 1. `init.sh`
- 개발 서버 실행 명령 포함
- 기본 E2E 테스트 1개 이상 포함 (서버 기동 확인 수준)
- 실행 권한 부여: `chmod +x init.sh`
### 2. `features.md`
아래 형식으로 작성:
```
# Feature List
 
## 우선순위 높음
- [ ] feature-A: 설명
- [ ] feature-B: 설명
 
## 우선순위 낮음
- [ ] feature-C: 설명
```
 
### 3. `claude-progress.txt`
아래 형식으로 초기 구조 생성:
```
# Progress Log
 
## 완료된 작업
(없음)
 
## 다음 작업
features.md 참고
```
 
### 4. 초기 git commit
- 생성한 파일 전체를 포함
- 커밋 메시지: `chore: initialize agent environment`
---
 
## 완료 기준 체크리스트
- [ ] `bash init.sh` 실행 시 에러 없음
- [ ] `features.md` 존재, 우선순위 기재됨
- [ ] `claude-progress.txt` 존재
- [ ] `git log --oneline` 에 초기 커밋 확인

 

---

.claude/agents/worker.md — Worker 에이전트

---
name: worker
description: 기능을 점진적으로 구현하는 에이전트
model: claude-sonnet-4-5
---

## 세션 시작 루틴
1. pwd 확인
2. git log --oneline -10 읽기
3. claude-progress.txt 읽기
4. features.md에서 미완료 최우선 항목 선택

## 완료 기준
- 구현 → 테스트 → git commit → progress.txt 업데이트

 

3. 실행 흐름 요약

claude 실행
    │
    ├─ init.sh 없음? → initializer agent 호출
    │       └─ init.sh, features.md, progress.txt 생성 → git commit
    │
    └─ init.sh 있음? → worker agent 호출
            └─ progress.txt 읽기 → feature 선택 → 구현 → commit → 반복

 

 

핵심은 claude-progress.txt와 git 히스토리를 통해 새 컨텍스트 창에서 시작하는 에이전트가 빠르게 현재 상태를 파악할 수 있게 하는 것입니다. Anthropic Initializer는 딱 한 번, 그 이후는 Worker가 이 파일들을 읽고 이어받습니다.