AI 코딩 도구를 “더 똑똑하게”가 아니라 “더 안전하게” 쓰는 방법
AI 코딩 도구를 쓰다 보면 이런 경험을 하게 됩니다. 처음에는 빨라서 좋습니다.
기획이 애매해도 금방 코드를 뽑아내고, 화면도 만들고, 테스트도 써주는 것처럼 보입니다.
그런데 조금만 길게 써보면 문제가 드러납니다.
- 범위가 자꾸 넓어집니다.
- 아키텍처가 흔들립니다.
- 팀 규칙을 무시한 코드가 나옵니다.
- 테스트가 부족한 구현이 쌓입니다.
- 보안 기준이 빠진 채로 “일단 되는 코드”가 생깁니다.
이때 필요한 것이 바로 하네스(Harness) 프레임워크입니다.
하네스는 AI 코딩 도구를 억누르는 장치가 아닙니다. 오히려 반대입니다.
AI가 프로젝트의 규칙 안에서 움직이도록 길을 만들어 주는 구조화된 프레임워크입니다.
즉, Claude Code, Cursor, Codex 같은 도구가 이미 갖고 있는 내장 안전장치 위에,
내 프로젝트만의 규칙과 보안 기준, 개발 절차를 한 층 더 얹는 방식입니다.
하네스 프레임워크의 핵심 개념
하네스 프레임워크를 한 문장으로 정리하면 다음과 같습니다.
AI 코딩 도구가 프로젝트의 규칙을 따르도록 제어하는 구조화된 실행 프레임워크
이 개념은 단순한 자동화와 다릅니다.
일반적인 자동화는 “코드를 빠르게 생성”하는 데 초점이 있습니다.
반면 하네스는 다음 질문에 답합니다.
- 어떤 기능을 만들 것인가?
- 어떤 기능은 만들지 않을 것인가?
- 어떤 구조로 만들어야 하는가?
- 어떤 방식은 금지해야 하는가?
- 어떤 순서로 검증해야 하는가?
즉, 하네스는 AI 개발을 위한 정책 기반 통제 시스템입니다.
왜 필요한가
AI 코딩 도구는 매우 유능하지만, 기본적으로는 범용성을 목표로 합니다.
그래서 다음 같은 특성이 있습니다.
- 프로젝트의 세부 규칙을 원래는 모릅니다.
- 팀의 코딩 철학을 자동으로 이해하지 못합니다.
- 조직의 보안 규정과 아키텍처 원칙을 기억하지 못합니다.
- 맥락이 부족하면 “그럴듯한 코드”를 우선 생성합니다.
문제는 이 “그럴듯함”이 실제 운영 환경에서는 위험할 수 있다는 점입니다.
대표적인 문제 3가지
스코프 폭주
AI는 종종 사용자가 말하지 않은 기능까지 제안합니다.
“이 기능도 넣을까요?”가 계속 반복되면 MVP는 금세 커집니다.
그 결과 일정 지연, 복잡도 증가, 운영 리스크 증가가 발생합니다.
보안 규칙 위반
예를 들면 이런 것들입니다.
- API Key 하드코딩
- 입력값 검증 누락
- 인증/인가 처리 빠짐
- 외부 호출 timeout 미설정
- 위험한 셸 명령 생성
아키텍처 붕괴
AI는 종종 구조를 단순하게 만들려고 합니다.
그 과정에서 레이어 분리가 무너지고, 책임이 섞이고, 나중에 유지보수가 어려워집니다.
하네스는 이 세 가지 문제를 구조적으로 줄여줍니다.
하네스의 전체 구조
하네스는 보통 아래처럼 구성됩니다.
graph TB
A["프로젝트 전용 하네스"] --> B["AI 도구 내장 하네스"]
A --- C["CLAUDE.md / docs / hooks"]
B --- D["시스템 프롬프트 / 권한 / 기본 안전장치"]여기서 중요한 점은, 내장 하네스는 일반 안전장치이고, 프로젝트 하네스는 우리 팀의 규칙을 강제하는 층이라는 것입니다.
즉
- 내장 하네스 = 위험한 동작을 기본적으로 막음
- 프로젝트 하네스 = 우리 조직의 개발 방식과 보안 기준을 따르게 함
4개 레이어로 보는 하네스 프레임워크
하네스는 보통 다음 4개 레이어로 이해하면 쉽습니다.
Layer 1: docs/ — 프로젝트의 뇌
Layer 2: CLAUDE.md — 프로젝트의 헌법
Layer 3: 실행 엔진 — /harness와 execute.py
Layer 4: Hooks — 자동 검증 장치
각 레이어의 역할이 명확하면, AI는 훨씬 안정적으로 움직입니다.
Layer 1: docs/ — 프로젝트의 뇌
이 레이어는 AI에게 “무엇을 만들고, 왜 만들며, 어떤 방식으로 만들지”를 알려주는 핵심 문서입니다.
보통 3~4개의 문서만 잘 작성해도 효과가 큽니다.
PRD.md — 무엇을 만들 것인가
PRD(Product Requirements Document)는 제품의 핵심 요구사항을 정의합니다.
예시
# PRD: {프로젝트명}
## 목표
{한 줄 요약}
## 핵심 기능
1. {기능 1}
2. {기능 2}
3. {기능 3}
## MVP 제외 사항
- {안 만들 것 1}
- {안 만들 것 2}여기서 정말 중요한 것은 MVP 제외 사항입니다.
이 항목이 없으면 AI는 계속 기능을 확장하려고 합니다.
예를 들어
- 관리자 페이지는 2차 버전으로 미룬다
- 외부 API 연동은 이번 MVP에서 제외한다
- 사용자 간 협업 기능은 넣지 않는다
이렇게 “하지 않을 것”을 명확히 적는 것이 매우 중요합니다.
스코프를 통제하는 가장 효과적인 방법이기 때문입니다.
ARCHITECTURE.md — 어떻게 만들 것인가
아키텍처 문서는 프로젝트 구조와 구현 방식의 기준이 됩니다.
예시
# 아키텍처
## 디렉토리 구조
{폴더 트리}
## 패턴
{사용하는 디자인 패턴}
## 데이터 흐름
{데이터가 어떻게 흐르는지}이 문서가 있으면 AI가 임의로 구조를 바꾸는 일을 줄일 수 있습니다.
예를 들면 아래처럼 적을 수 있습니다.
## 패턴
- API 로직은 service layer에서만 처리한다
- DB 접근은 repository layer에서만 처리한다
- UI는 component 단위로만 분리한다
- 외부 API 호출은 별도 adapter를 통해서만 수행한다이렇게 하면 AI가 구조를 자꾸 섞는 것을 방지할 수 있습니다.
ADR.md — 왜 그렇게 만드는가
ADR(Architecture Decision Record)은 중요한 설계 결정을 기록하는 문서입니다.
예시
# Architecture Decision Records
### ADR-001: 인증 방식
**결정**: JWT 사용
**이유**: Stateless, 확장성 확보
**트레이드오프**: 토큰 탈취 위험이 있으므로 HTTPS와 만료 정책을 강제한다ADR의 장점은 매우 큽니다.
AI는 종종 “다른 방식으로 바꾸는 게 좋지 않을까요?”라는 제안을 합니다.
그런데 ADR이 있으면 이런 제안을 줄일 수 있습니다.
왜냐하면 이미 선택한 이유와 포기한 것이 문서화되어 있기 때문입니다.
즉, ADR은 단순한 기록이 아니라 재논쟁 방지 장치입니다.
UI_GUIDE.md — 어떻게 보여야 하는가
선택 문서이지만, UI 품질을 중요하게 생각한다면 사실상 필수에 가깝습니다.
예시 항목
- 색상 팔레트
- 여백 규칙
- 버튼 스타일
- 카드 디자인 패턴
- 금지할 UI 패턴
예를 들어 아래처럼 적을 수 있습니다.
## 금지 패턴
- glass morphism 남용 금지
- 과도한 그라데이션 텍스트 금지
- 네온 글로우 남용 금지
- 의미 없는 장식성 애니메이션 금지이 문서가 있으면 AI가 기본 스타일을 무작정 적용하는 것을 줄일 수 있습니다.
즉, 디자인 품질도 문서로 통제할 수 있습니다.
Layer 2: CLAUDE.md — 프로젝트의 헌법
CLAUDE.md는 AI가 가장 먼저 참고해야 하는 프로젝트 규칙 문서입니다.
이 문서는 하네스의 중심축입니다.
왜 중요한가
AI가 코딩할 때 가장 먼저 읽는 파일이라고 생각하면 됩니다.
여기에 들어가는 규칙은 가능한 한 짧고 강하게 써야 합니다.
특히 CRITICAL 키워드가 중요합니다.
이 키워드는 “이건 선택이 아니라 강제 규칙”이라는 신호로 쓰기 좋습니다.
좋은 CLAUDE.md 예시
# 프로젝트: {프로젝트명}
## 기술 스택
- Next.js
- TypeScript
- PostgreSQL
- Tailwind CSS
## 아키텍처 규칙
- CRITICAL: 모든 API 로직은 app/api/에서만 구현할 것
- CRITICAL: API Key와 Secret은 절대 코드에 하드코딩하지 말 것
- CRITICAL: 사용자 입력은 반드시 validation을 통과해야 함
- CRITICAL: DB 접근은 repository layer를 통해서만 수행할 것
## 개발 프로세스
- CRITICAL: 새 기능 구현 시 테스트를 먼저 작성할 것 (TDD)
- CRITICAL: 인증/인가 관련 변경 시 반드시 테스트를 포함할 것
- 커밋 메시지는 conventional commits 형식을 따를 것
## 명령어
- npm run dev
- npm run test
- npm run lint
- npm run build보안 관점에서 꼭 넣어야 할 규칙
보안팀 관점에서 보면 CLAUDE.md에는 다음과 같은 규칙이 유효합니다.
- CRITICAL: 인증/인가 없는 기능은 만들지 말 것
- CRITICAL: 민감 정보는 로그에 남기지 말 것
- CRITICAL: 외부 요청은 timeout과 retry 정책을 명시할 것
- CRITICAL: 위험한 셸 명령 생성 금지
- CRITICAL: 새로운 패키지 도입 시 보안 검토를 거칠 것이런 규칙은 단순한 코딩 스타일이 아니라 보안 정책입니다.
Layer 3: 실행 엔진 — /harness와 execute.py
이 레이어는 문서에 적힌 규칙을 실제 작업 흐름으로 바꾸는 부분입니다.
/harness의 역할
.claude/commands/harness.md 같은 형태로 정의된 실행 명령입니다.
사용자는 보통 /harness만 입력하면 됩니다.
그 안에서 수행되는 흐름은 대략 아래와 같습니다.
flowchart TD
A["/harness 실행"] --> B["docs/ 문서를 읽음"]
B --> C["사용자 요구를 구체화"]
C --> D["작업을 Phase로 분해"]
D --> E["phases/에 Phase 파일 생성"]
E --> F["execute.py 실행"]즉, /harness는 기획 → 분해 → 실행 → 검증을 한 번에 연결하는 원스톱 실행점입니다.
execute.py의 역할
execute.py는 Phase를 순차적으로 수행하는 자동화 엔진입니다.
작동 방식은 이런 식입니다.
phases/{task-name}/에서 다음 pending Phase를 찾습니다.- 해당 Phase의 지시서를 읽습니다.
- AI가 그 범위 안에서만 작업합니다.
- 결과를 검증합니다.
- 성공하면 다음 Phase로 넘어갑니다.
- 실패하면 상태를 기록하고 중단합니다.
예시 상태 흐름
| 상태 | 동작 |
|---|---|
| completed | 다음 Phase로 진행 |
| error | 에러 기록 후 중단 |
| blocked | 사용자 개입 요청 후 중단 |
이 구조의 장점은 명확합니다.
- 한 번에 너무 많은 일을 하지 않습니다.
- 작업 범위가 문서로 제한됩니다.
- 에러가 나면 어디서 멈췄는지 알 수 있습니다.
- 재실행이 쉽습니다.
왜 Phase가 중요한가
AI는 큰 작업을 한 번에 처리할 때 범위가 흐려질 수 있습니다.
그래서 큰 작업을 여러 개의 작은 단계로 나누는 것이 좋습니다.
예시
- 프로젝트 초기화
- 공통 타입과 유틸리티 작성
- API 라우트 구현
- UI 컴포넌트 작성
- 메인 화면 통합
이렇게 쪼개면 각 단계마다 검증이 가능해집니다.
즉, 품질을 높이면서도 실패 지점을 명확히 할 수 있습니다.
Layer 4: Hooks — 자동 검증 장치
Hooks는 AI가 잘못된 방향으로 가는 것을 자동으로 막는 장치입니다.
이 레이어는 사실상 보안 가드레일입니다.
TDD Guard
구현 파일을 수정하면서 테스트가 없으면 차단하는 방식입니다.
의미는 매우 큽니다.
- 테스트 없는 변경 방지
- 회귀 버그 감소
- 품질 관리 강화
보안 관점에서도 TDD는 중요합니다.
특히 인증/인가, 입력 검증, 권한 분기 로직은 테스트가 없으면 쉽게 무너집니다.
Dangerous Command Guard
다음 같은 위험 명령을 차단합니다.
rm -rfgit reset --hardgit push --force
AI는 때때로 운영에 위험한 명령을 생성할 수 있습니다.
이런 명령을 자동 차단하는 것은 매우 중요합니다.
특히 개발 환경과 운영 환경이 섞인 조직에서는 더 중요합니다.
Circuit Breaker
같은 에러가 짧은 시간에 반복되면 중단하는 장치입니다.
예를 들면
- 60초 안에 5번 같은 오류 발생
- 실행 중단
- 전략 변경 필요 경고
이 기능은 단순한 오류 처리처럼 보이지만, 실제로는 매우 유용합니다.
AI가 잘못된 루프에 빠졌을 때 불필요한 반복 실행을 멈출 수 있기 때문입니다.
즉, AI의 무한 삽질을 막는 장치라고 볼 수 있습니다.
하네스 프레임워크의 실제 작동 사례
이제 이 구조가 실제로 어떻게 품질을 바꾸는지 살펴보겠습니다.
사례 1: UI 품질이 낮았던 경우
문제는 UI 가이드가 없었던 것입니다.
AI는 기본 스타일을 그대로 가져오고, 결과물은 평범하거나 산만해집니다.
해결 방법은 간단합니다.
docs/UI_GUIDE.md추가- 금지할 스타일 명시
- 컴포넌트 간격과 색상 규칙 명시
- 반복 가능한 디자인 패턴 정의
결과적으로 같은 AI 도구를 써도 결과물이 달라집니다.
사례 2: API 파싱 에러가 반복된 경우
AI가 JSON 응답을 코드블록으로 감싸는 문제를 일으킬 수 있습니다.
이 경우 ADR에 다음과 같이 기록할 수 있습니다.
### ADR-009: 코드블록 처리 규칙
**결정**: JSON 응답은 코드블록을 제거한 뒤 파싱한다
**이유**: AI 응답 형식의 변동성을 흡수하기 위함
**트레이드오프**: 전처리 로직이 추가된다이런 식으로 문제가 해결되면, 이후 같은 문제가 반복될 가능성이 줄어듭니다.
사례 3: 기능이 계속 커지는 경우
처음에는 “댓글 수집 대시보드”였는데, 어느새 관리자 화면, 알림 시스템, 협업 기능까지 붙는 경우가 있습니다.
이럴 때는 PRD의 MVP 제외 사항이 중요합니다.
## MVP 제외 사항
- 관리자 기능
- 실시간 협업 기능
- 외부 API 자동 연동이 한 줄이 스코프 폭주를 막는 데 큰 역할을 합니다.
보안 관점에서의 하네스 활용법
사용자께서 보안 관점에 관심이 많으시므로, 이 부분은 특히 중요합니다.
하네스는 단순한 개발 편의 도구가 아니라 보안 정책을 개발 흐름에 녹여 넣는 장치로 볼 수 있습니다.
정책 강제
예를 들어 이런 규칙을 문서에 넣을 수 있습니다.
- CRITICAL: 인증/인가 검증 없는 API 생성 금지
- CRITICAL: 사용자 입력은 항상 validation 수행
- CRITICAL: 민감 정보는 로그 출력 금지
- CRITICAL: 외부 통신은 timeout 설정 필수
- CRITICAL: 의존성 추가 시 보안 승인 필요이렇게 하면 AI가 실수로 보안이 빠진 코드를 생성하는 것을 줄일 수 있습니다.
이상 동작 탐지
Hooks나 실행 로그를 SIEM/Wazuh 같은 시스템과 연동하면, AI 도구의 이상 행동도 탐지할 수 있습니다.
예시
- 위험 명령 차단 로그
- 반복 에러 발생 로그
- 검증 실패 로그
- 비정상적인 코드 생성 시도 로그
이런 로그는 내부 개발 환경에서도 유용합니다.
특히 AI 도구를 여러 개발자가 공통으로 쓸 때는 더 중요합니다.
공급망 위험 관리
하네스 환경에서 npm, pip 같은 패키지를 자동으로 추가할 수 있습니다.
그런데 이 부분은 공급망 보안 관점에서 주의가 필요합니다.
권장 규칙
- CRITICAL: 승인된 패키지만 사용
- CRITICAL: 신규 패키지 도입 시 보안 검토 필수
- CRITICAL: package-lock / lockfile 변경 시 리뷰 필수이런 규칙은 AI 시대에 매우 중요합니다.
AI는 편하게 패키지를 추천하지만, 실제 운영 환경에서는 그 편함이 위험으로 바뀔 수 있습니다.
구체적으로 어떻게 시작하면 되는가
실무에서 바로 시작하려면 다음 순서를 추천합니다.
Step 1. 프로젝트 목적 정의
먼저 “무엇을 만들지”를 한 문장으로 정리합니다.
예
- 댓글 수집 및 감성 분석 대시보드
- 내부 보안 점검 자동화 도구
- 운영 지표 시각화 페이지
Step 2. PRD 작성
핵심 기능과 MVP 제외 사항을 작성합니다.
Step 3. ARCHITECTURE 작성
디렉토리 구조, 책임 분리, 데이터 흐름을 정합니다.
Step 4. ADR 작성
중요한 기술 선택의 이유와 트레이드오프를 기록합니다.
Step 5. CLAUDE.md 작성
반드시 지켜야 할 규칙을 CRITICAL로 적습니다.
Step 6. Hooks 설정
테스트 누락, 위험 명령, 반복 에러를 자동 차단합니다.
Step 7. /harness 실행
AI가 문서를 읽고 Phase 기반으로 작업을 시작하게 합니다.
Step 8. 결과 검토 후 문서 보강
문제가 있으면 코드를 직접 고치기보다 문서를 보강하는 것이 더 좋습니다.
문서가 곧 AI의 행동 기준이기 때문입니다.
바로 쓸 수 있는 템플릿 예시
아래는 블로그 독자가 바로 참고할 수 있도록 만든 간단한 템플릿입니다.
PRD 템플릿
# PRD: 프로젝트명
## 목표
한 줄로 요약
## 핵심 기능
1. 기능 A
2. 기능 B
3. 기능 C
## MVP 제외 사항
- 제외 1
- 제외 2
- 제외 3ARCHITECTURE 템플릿
# Architecture
## 디렉토리 구조
- app/
- components/
- services/
- repository/
## 패턴
- service layer 분리
- repository pattern 사용
- 외부 API adapter 분리
## 데이터 흐름
UI → API → Service → Repository → DBADR 템플릿
# ADR
### ADR-001: 인증 방식
**결정**: JWT 사용
**이유**: stateless 구조에 적합
**트레이드오프**: 토큰 관리 정책 필요CLAUDE.md 템플릿
# 프로젝트 규칙
## CRITICAL 규칙
- CRITICAL: API Key 하드코딩 금지
- CRITICAL: 인증/인가 없는 API 금지
- CRITICAL: 테스트 먼저 작성
- CRITICAL: 위험 명령 사용 금지이 프레임워크가 특히 잘 맞는 경우
하네스는 모든 프로젝트에 무조건 같은 효과를 내는 것은 아닙니다.
하지만 다음 경우에는 특히 잘 맞습니다.
- AI 코딩 도구를 자주 쓰는 경우
- 팀 규칙이 중요한 경우
- 보안 기준이 중요한 경우
- 기능 범위가 자주 흔들리는 경우
- 장기적으로 유지보수해야 하는 서비스인 경우
- 비개발자와 개발자가 함께 기획하는 경우
특히 조직 내부에서 AI 코딩을 안전하게 도입하고 싶다면 매우 유용합니다.
흔한 오해
오해 1. 하네스는 AI를 느리게 만든다
처음에는 문서를 써야 하므로 시간이 조금 듭니다.
하지만 이후에는 오히려 빨라집니다.
재작업과 리뷰 비용이 줄어들기 때문입니다.
오해 2. 문서만 있으면 충분하다
문서만으로는 부족합니다.
Hooks와 실행 엔진이 함께 있어야 실제로 규칙이 강제됩니다.
오해 3. 테스트는 귀찮기만 하다
AI 코딩에서는 테스트가 특히 중요합니다.
AI가 만들어 놓은 코드의 안전장치가 되기 때문입니다.
결론
하네스 프레임워크는 단순한 개발 편의 도구가 아닙니다.
이것은 AI 코딩을 통제하기 위한 운영 체계에 가깝습니다.
정리하면 다음과 같습니다.
docs/는 AI에게 맥락을 제공합니다.CLAUDE.md는 반드시 지켜야 할 규칙을 강제합니다./harness와execute.py는 작업을 단계적으로 실행합니다.- Hooks는 실시간으로 잘못된 행동을 막습니다.
결국 핵심은 하나입니다.
AI가 코드를 잘 쓰게 만드는 것이 아니라, AI가 우리 팀의 규칙 안에서 코드 쓰게 만드는 것
이 방식이야말로 속도와 품질, 그리고 보안을 함께 잡는 현실적인 방법입니다.
댓글