01 / 21

하네스 엔지니어링

AI 에이전트를 말로 설득하는 것에서
시스템으로 제어하는 것으로

02 / 21

오늘의 핵심 질문

AI에게 규칙을 알려줬는데도
왜 같은 실수를 반복할까요?

긴 대화에서 맥락이 희미해집니다.
규칙은 기억해도 행동을 막지는 못합니다.
나쁜 코드가 남으면 다음 작업의 참고 자료가 됩니다.

03 / 21

한 줄 정의

하네스 엔지니어링은
AI 에이전트가 정해진 방향으로 움직이도록
구조, 제약, 피드백 루프를 설계하는 일입니다.

04 / 21

프롬프트와 하네스의 차이

구분	프롬프트 엔지니어링	하네스 엔지니어링
방식	AI에게 부탁한다	시스템으로 강제한다
제어 지점	요청과 설명	파일, 훅, 테스트, 권한
실패 가능성	잊거나 무시할 수 있음	실패하면 진행이 막힘

05 / 21

비유

프롬프트는 말에게
"천천히 가라"고 말하는 것입니다.

하네스는 속도 제한 장치와 울타리를 설치해
벗어날 수 없는 경로를 만드는 것입니다.

06 / 21

문제 1: Context Rot

대화가 길어질수록 AI는
초기 지시와 프로젝트 규칙을 놓치기 쉽습니다.

처음에는 TypeScript strict를 지킵니다.
시간이 지나면 JavaScript 코드를 제안합니다.
초반의 금지 사항이 뒤쪽 작업에서 약해집니다.

07 / 21

문제 2: 규칙은 행동을 막지 못한다

AI가 "알고 있다"는 것과
AI가 "못 하게 되어 있다"는 것은 다릅니다.

production DB 직접 수정
main 브랜치 강제 push
.env 같은 민감 파일 수정

프롬프트만으로는 이런 행동을 완전히 막기 어렵습니다.

08 / 21

하네스의 3개 기둥

Context Files
Automated Enforcement
Garbage Collection

이 세 가지가 함께 있어야
AI 에이전트의 품질이 안정됩니다.

09 / 21

기둥 1: Context Files

CLAUDE.md, agent.md 같은 문서는
AI가 매번 참조하는 작업 규칙입니다.

## 금지 규칙

- production DB 직접 쿼리 금지
- main 브랜치 직접 push 금지
- .env 파일 수정 금지

10 / 21

Context Files의 역할

좋은 컨텍스트 파일은
새 팀원에게 주는 온보딩 문서와 같습니다.

프로젝트의 약속을 고정합니다.
반복 설명을 줄입니다.
긴 대화에서도 기준점을 유지합니다.

11 / 21

기둥 2: Automated Enforcement

AI가 코드를 수정하거나 커밋하기 전에
시스템이 자동으로 검증합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npm run lint --fix"
      }
    ]
  }
}

12 / 21

좋은 하네스의 원칙

성공은 조용하게, 실패는 선명하게

문제가 없으면 흐름을 방해하지 않습니다.
문제가 있으면 즉시 멈춥니다.
가능하면 AI가 스스로 고치게 합니다.

13 / 21

기둥 3: Garbage Collection

AI는 기존 코드베이스를 보고 다음 코드를 만듭니다.

나쁜 패턴이 남아 있으면
AI는 그것을 "정상적인 예시"로 학습합니다.

14 / 21

나쁜 코드의 증식 경로

나쁜 코드 존재
→ AI가 참고
→ 비슷한 나쁜 코드 생성
→ 코드베이스 품질 하락
→ 더 많은 나쁜 코드 생성

정기적인 정리는
AI가 참고하는 환경 자체를 개선합니다.

15 / 21

사례: 테스트 없는 커밋 막기

프롬프트 방식:

코드를 작성한 뒤 반드시 테스트를 실행하고,
테스트가 통과한 경우에만 커밋하세요.

대화가 길어지면 잊을 수 있습니다.

16 / 21

하네스 방식

#!/bin/bash
npm test

if [ $? -ne 0 ]; then
  echo "테스트 실패: 커밋이 차단되었습니다."
  exit 1
fi

테스트가 실패하면
물리적으로 커밋이 불가능해집니다.

17 / 21

개발자의 역할 변화

Before	After
코드를 직접 작성	AI가 작성할 규칙을 설계
버그를 직접 수정	버그를 막는 시스템 구축
코드 리뷰	자동 검증 파이프라인 설계
기능 구현	AI 워크플로우 아키텍처 설계

18 / 21

개발자는 감독이 된다

중요한 역량은
코드 한 줄을 더 빨리 쓰는 능력만이 아닙니다.

AI가 안전하고 일관되게 일하도록
작업 환경을 설계하는 능력이 중요해집니다.

19 / 21

지금 바로 시작할 것

프로젝트 루트에 CLAUDE.md를 작성합니다.
pre-commit hook으로 테스트와 린트를 강제합니다.
민감 파일 수정 차단 규칙을 만듭니다.
AI가 반복하는 실수를 규칙으로 기록합니다.
나쁜 코드 패턴을 주기적으로 정리합니다.

20 / 21

결론

AI 에이전트 시대의 개발 생산성은
프롬프트만으로 결정되지 않습니다.

좋은 하네스가 좋은 AI 협업을 만듭니다.

21 / 21

토론 질문

여러분의 AI 에이전트에게는
어떤 "고삐"가 필요한가요?