k
korAI
🏆 AI Native 되기
고급· 18분업데이트 2026-04-18

일하는 환경 설계 — Harness

Claude Code·Cursor 내 셋업

🎯 이 레슨으로 얻는 것

AI 자체의 성능이 아니라, AI가 일하는 "작업 환경"(harness)을 설계하는 기술을 배웁니다. 같은 Claude여도 환경을 잘 짜면 결과가 10배 달라집니다.

🛠️ Harness가 뭐야?

AI가 일을 잘 하게 만드는 주변 장치 전체.

Anthropic 공식 용어로, 단순히 프롬프트만이 아니라:

  • AI가 볼 수 있는 파일·문서
  • AI가 쓸 수 있는 도구(tools)
  • 메모장 / 스크래치패드
  • 검증·재시도 루틴
  • 실행 권한의 범위

이 모든 "작업 환경"을 Harness라고 해요.

🏭 비유: 조립라인 vs 맨손

숙련된 장인도 맨손으로는 시계를 못 만듭니다. 도구·조명·부품 진열·검수 테이블이 있어야 가능하죠.

AI도 같아요. 프롬프트만 잘 쓴다고 결과 잘 나오는 게 아니라, 환경이 잘 세팅돼 있어야 진가가 나옵니다.

🧰 Harness의 5가지 구성 요소

1. Context — AI가 볼 자료

  • 관련 문서·파일·DB
  • 과거 대화 요약
  • 사용자 프로필·선호

나쁜 예: "이 코드 리뷰해줘" + 파일 달랑 1개 좋은 예: "이 코드 리뷰해줘" + CONTRIBUTING.md + 최근 리뷰 3개 + 코드 스타일 가이드

2. Tools — AI가 쓸 도구

  • 파일 읽기/쓰기
  • 웹 검색
  • 코드 실행
  • API 호출
  • 이미지 생성

Claude Code·Cursor·ChatGPT + Tools 가 이걸 제공. 에이전트 품질은 쓸 수 있는 도구가 많을수록 올라감.

3. Scratchpad — AI의 메모장

/scratchpad.md

## 현재 작업 중
- 사용자 인증 버그 수정
- 관련 파일: auth.py, middleware.py

## 지금까지 시도한 것
- [x] 토큰 만료 체크 추가
- [ ] Redis 세션 확인

## 다음 단계
...

복잡한 작업은 AI가 메모하면서 일할 때 품질이 확 올라갑니다.

4. Verifier — 검증 루프

AI가 한 작업을 AI 자신이 다시 검증:

# 1차: 코드 작성
# 2차: 작성한 코드 리뷰
# 3차: 테스트 실행
# 4차: 실패하면 수정 → 반복

5. Guardrails — 안전 장치

  • 실행할 수 있는 명령어 화이트리스트
  • 삭제·외부 전송 같은 위험 액션엔 사람 승인
  • 비용 상한선

🧪 실전 — Claude Code Harness 예시

CLAUDE.md 파일 하나로 프로젝트 전체의 Harness를 세팅:

# 프로젝트 Harness

## 너의 역할
너는 이 프로젝트의 시니어 풀스택 개발자야.

## 코드 스타일
- TypeScript strict mode
- 함수형 우선, class 지양
- 모든 외부 호출은 try/catch

## 일하는 방식
1. 수정 전에 관련 파일 3개 이상 읽기
2. 변경 계획을 `.plan.md`에 먼저 쓰기
3. 사용자 승인 후 실제 수정
4. 수정 후 `npm test` 실행해 검증

## 금지 사항
- `rm -rf`, `git push --force` 절대 금지
- `.env` 파일 읽기·쓰기 금지
- 새 npm 패키지 설치는 사용자 승인 후

이 파일 하나만 잘 쓰면 Claude Code가 팀원처럼 움직입니다.

🎨 Before / After

❌ Harness 없음

"이 파이썬 코드 리팩토링해줘"

→ AI가 혼자 상상으로 스타일 정함 → 테스트 안 돌림 → 멀쩡한 코드 망가뜨림 → 되돌리느라 1시간

✅ Harness 있음

같은 요청 + CLAUDE.md + 메모장 규칙

→ 관련 파일 먼저 읽음 → 계획을 .plan.md에 씀 → 사용자 확인 후 수정 → 자동 테스트로 검증 → 실패하면 스스로 롤백

📐 실전 체크리스트 (자기 Harness 세팅)

  • [ ] 프로젝트 루트에 README.md + CLAUDE.md 존재
  • [ ] 코드 스타일 / 금지 사항 / 워크플로 명시
  • [ ] 최근 변경 히스토리 요약 파일
  • [ ] AI가 쓸 수 있는 도구 목록 명시
  • [ ] 검증 명령어 (npm test, pytest 등) 명시
  • [ ] 민감 파일 (.env, secrets.*) 접근 차단

🛠️ 비개발자 Harness

개발자 아니어도 Harness 개념은 쓸 수 있어요.

Claude Projects 세팅

  1. Projects 생성
  2. Custom Instructions에 역할·톤·금지사항
  3. 파일에 자주 참고할 자료 업로드 (스타일 가이드, 브랜드 문서)
  4. 매 대화가 이 Harness 안에서 돌아감

결과물 일관성이 확 올라갑니다.

🧠 핵심 철학

"AI가 똑똑해지기만 기다리지 말고, AI가 일할 환경을 네가 설계해라."

Harness 엔지니어링은 2026년 에이전틱 시대의 가장 가치 있는 기술 중 하나예요. 모델은 자주 바뀌지만 좋은 Harness는 오래 갑니다.

🔗 다음에 뭘 볼까