하네스 엔지니어링 9단계 베스트 프랙티스 #1. 프로젝트 규칙 설정

시리즈 맥락 복기

이전 편 #0 업무 프로세스 매핑에서는 자동화할 프로세스를 한 장의 지도로 그리고, 사람이 하는 동작을 동사로 표시해 AI 개입 후보를 식별했습니다. 지도만으로는 부족합니다. 에이전트가 이 지도 위를 달릴 때 따라야 할 규칙이 없다면, 모델은 자기 판단으로 움직여 버립니다.

1. #0 업무 프로세스 매핑
2. #1 프로젝트 규칙 설정 ← 이번 편
3. #2 Code Wiki 작성
4. ... (#8 측정 + 회고까지 이어짐)

이 단계의 의미 — 하네스에서 Step 1이 차지하는 위치

Step 1은 말 그대로 말에게 채우는 고삐에 해당합니다. 모델이 아무 방향으로나 달리지 않도록, 사전에 "이 프로젝트에서는 반드시 이렇게 한다"라는 규약을 문서로 만들어 두는 작업입니다. Claude Code 계열 도구에서는 이 파일을 보통 CLAUDE.md라고 부르며, 에이전트가 세션 시작 시 자동으로 읽어들입니다.

해결하려는 문제

• AI가 '더 좋은 방법'을 제안하며 기존 제약을 무시하는 현상: 예컨대 "이건 X 라이브러리 쓰면 간단합니다"라며 함부로 새 의존성을 설치하는 경우.
• 매번 같은 지시를 반복해야 하는 비효율: "테스트부터 짜", "환경변수는 .env에", "커밋 메시지는 영어로" 같은 지시를 매 대화마다 다시 하지 않으려면 규칙을 파일로 고정해야 합니다.
• 멀티 프로젝트 간 규칙 충돌: 전역에서는 TDD가 필수지만, 특정 실험용 폴더에서는 예외를 두고 싶을 때, 이 예외를 어떻게 지역적으로만 허용할 것인가.

효과 — 어느 정도 임팩트가 있는가

개인 경험상, 잘 짜인 CLAUDE.md 하나가 프롬프트 엔지니어링 수십 번을 대체합니다. 매 세션마다 "GPU 쓸 때는 스케줄러 acquire 먼저"라고 타이핑할 필요가 없죠. 또한 새 프로젝트를 시작할 때 전역 규칙을 상속하는 한 줄만 넣으면 기본 방어선이 곧바로 확보됩니다.

베스트 프랙티스 1 — 계층형 CLAUDE.md로 규칙을 위임하라

핵심은 "전역 규칙은 한 곳에만, 프로젝트 고유 규칙은 해당 폴더에" 두는 계층 구조입니다.

프로젝트 CLAUDE.md는 다음처럼 상속 한 줄 + 고유 규칙만 둡니다.

# 개인 지식 저장소

홈 CLAUDE.md의 전체 정책(TDD, GPU, HITL 등)을 상속한다.

## 디렉토리 규칙
- work/: 영어 kebab-case
- life/: 한국어 파일명 허용

이렇게 하면 전역 규칙을 수정할 때 파일 하나만 고치면 되고, 프로젝트별 차이점은 해당 폴더의 CLAUDE.md만 봐도 파악됩니다.

베스트 프랙티스 2 — Constraint를 표로 명시하라

Constraint(제약 조건)는 코드 품질과는 별개로 "AI가 반드시 따라야 하는 환경 조건"을 말합니다. 이게 명시되지 않으면 AI는 "불필요해 보인다"며 우회합니다.

Constraint	이유	명시하지 않으면 생기는 사고
의존성 추가 금지	기존 패키지로 해결. 새 패키지는 보안/라이선스 검토 필요	"X 라이브러리 쓰면 간단합니다" → pip install 즉시 실행
특정 디렉토리 수정 금지	자동 생성 코드, 벤더링된 코드, 타 사용자 영역	generated/ 직접 수정
특정 API 사용 강제	로깅 표준, 에러 처리 컨벤션 등	표준 라이브러리 직접 호출로 래퍼 무시
브랜치 전략	main 직접 push 금지, PR 필수 등	기능 완료 후 바로 git push origin main
환경별 설정 분리	dev/staging/prod를 섞지 않는 정책	하드코딩된 localhost URL이 prod 코드에 삽입

베스트 프랙티스 3 — 지시보다 "이벤트-행동 표"로 적어라

"테스트를 먼저 짜라" 같은 추상적 지시는 잘 안 지켜집니다. 대신 이벤트별 구체적 행동을 표로 적으면 AI가 정확히 따릅니다.

## TDD 정책

| 이벤트 | 행동 |
|--------|------|
| 함수/클래스 추가 | 단위 테스트 작성 → 실행 |
| 기존 코드 수정 | 관련 테스트 실행 → 실패 시 수정 |
| 코드 삭제 | 관련 테스트 실행 → 불필요 테스트 정리 |
| 리팩토링 | 전체 테스트 스위트 실행 → 모두 통과 확인 |

이 형태가 "왜 잘 통하는가"는 단순합니다. AI는 상황 → 행동 매핑을 처리하는 데 특화되어 있기 때문입니다. 지시를 이 포맷에 맞추면 내부 해석 비용이 줄고, 결과적으로 실수도 줄어듭니다.

자주 빠지는 실수

• 전역 규칙을 프로젝트 CLAUDE.md에 복사해 붙여넣기: 전역이 바뀌면 모든 프로젝트를 다시 손봐야 합니다. 상속 한 줄로 해결하세요.
• 한 섹션에 여러 관심사를 섞기: 빌드 섹션에 코딩 스타일까지 넣으면 AI가 잘못 매칭합니다. 한 섹션 = 한 관심사 원칙을 지키세요.
• Constraint를 "가이드라인"처럼 부드럽게 쓰기: "~하면 좋습니다"는 쉽게 무시됩니다. "반드시", "금지", "필수" 같은 단정형 어조가 필요합니다.

다음 단계 예고 — Step 2 Code Wiki 작성

규칙(CLAUDE.md)은 "이렇게 행동하라"는 명령이라면, Step 2의 Code Wiki는 "이 코드가 왜 이런 구조인가"를 설명하는 맥락 파일입니다. 다음 편에서는 아키텍처, 도메인 용어, 의사결정 기록(ADR)으로 구성된 3종 세트를 소개합니다.

한 줄 요약: "규칙을 파일로 고정하지 않으면, 매 대화마다 같은 지시를 반복하게 된다."

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.