하네스 엔지니어링 - 이해의 폭을 넓히기 위해

처음 하네스 엔지니어링에 대한 개념을 알게 되었기 까지 얼마 되지 않았다. YouTube에서 최근 많은 사람들이 올리고 있는 영상들을 기차에서 찾아보다가 알게되었다.

그런데 이 개념을 알고나니 현재 세상이 알면 알수록 더욱 많은 것을 탐구, 조사하거나 생산할 수 있다는 점을 깨달았고, 특히나 AI가 컨텍스트 사용률을 낮추면서 더욱 높은 효율을 낼 수 있는 자동화 설계가 될 수 있다는 점이 메리트로 다가왔다.

 

그래서 하네스 엔지니어링에 대해 주구장창 찾아가며, AI와의 대화를 통해 추려낸 어느정도 Professional한 글을 작성해보고자 한다.

 

최근 하네스 엔지니어링이 뜨게 된 계기

왜 하네스가 뜨게 되었을까? 생각을 해보았을 때, 나는 Anthropic 해커톤에서 2월에 AgentShield 보안 스캐너가 개발되면서, 사용한 AI 사용 방식이 ECC 프로젝트로 넘어오면서 하네스 엔지니어링이 확산되었지 않았을까? 생각했다.

실은 그 이전 LLM등장 -> 문제 발생 -> 모델이 문제가 아니라, 모델을 어떻게 감싸느냐
이런 문제 제기를 하게 되면서, 에이전트 실험 붐이 2023~2024년 부터 유행하게 되었다.

이때의 결과 :
가능성은 보이지만, 안정성 / 재현성 / 보안 문제 심각💥

 

그래서 지속적인 연구를 통해 최근에 Anthropic 내부 해커톤에서 AgentShield(보안 스캐너) 같은 아이디어가 등장하며 아래로 관점의 변화가 생겨나게 되었다.

기존 관점
"AI 가 만든 코드가 안전한가?"
↓
AgentShield 관점
"AI 가 일하는 환경 자체가 안전한가?"

 

AgentShield 가 만든 변화

이전 사고방식                             이후 사고방식
- 출력 검증 중심                           - 실행 환경 검증
- 결과만 보고 판단                        - 권한 관리
                                                   - 프롬프트/훅/툴 까지 스캔

즉, AI를 "함수"가 아니라 "권한 가진 실행 주체"로 보기 시작
이게 하네스 개념의 핵심 전환점 중 하나이다.

 

왜 하네스 엔지니어링이 지금 뜰까?

1. 모델은 이미 충분하다.

ⓐ. GPT-4 이후 성능 차이보다 운영 방식 차이가 더 큼

2. 실제 서비스에서 문제 발생

ⓐ. AI가 망가뜨리는 코드

ⓑ. 테스트 안 돌림

ⓒ. 보안 사고 가능성

ⓓ. context collapse

즉, AI를 통제하는 시스템이 중요

3. 팀 단위로 확장

ⓐ. 개인 수준

    - 프롬프트 잘 치면 해결

ⓑ. 팀 수준

    - 사람마다 다르면 chaos

따라서, 규칙 + workflow + 검증 = 하네스

 

ECC (Everything Claude Code)

https://github.com/affaan-m/everything-claude-code

GitHub - affaan-m/everything-claude-code: The agent harness performance optimization system. Skills, instincts, memory, security

위 주소는 실제 해커톤에서 녹여낸 하네스 엔지니어링 기술 방법을 정리한 프로젝트이다. Star 수와 Fork 수만 봐도 얼마나 유명한지 알 수 있다.

 

ECC 프로젝트란?

Claude Code만 아니라, Codex, Cursor, OpenCode 등 여러 환경을 함께 다루는 크로스 하네스 생태계

에이전트(roles)
스킬(workflows)
명령어(commands)
훅(hooks)
규칙(rules)
보안 스캐너(AgentShield)
까지 포함한 에이전트 하네스 성능 최적화 시스템

 

 

1. 왜 이게 필요할까?

AI 코딩 도구를 그냥 쓰면 보통 아래와 같은 문제가 발생

• 세션마다 스타일이 흔들림
• 프로젝트 규칙을 자꾸 잊음
• 위험한 명령을 실행할 수 있음
• 긴 작업에서 컨텍스트가 쉽게 낭비됨
• 비슷한 작업을 반복할 때 매번 처음부터 지시해야 함

혼자 개발하더라도, AI에게 팀처럼 역할을 나누고 규칙을 주고 자동화를 붙이면 생산성을 높일 수 있다. ECC는 그것을 위한 큰 템플릿

 

글 이해를 돕기 위한 용어 풀이

1. Agent (에이전트)

역할이 정해진 AI 작업자

planner : 계획 세우는 담당
code-reviewer : 코드 리뷰 담당
security-reviewer : 보안 점검 담당
build-error-resolver : 빌드 에러 담당

 

즉, 에이전트는 "또 다른 모델"이 아니라, 같은 모델을 역할별로 포장한 작업 단위

 

2. Subagent(서브에이전트)

제한된 범위와 도구 권한을 가진 위임 프로세스

메인 AI가 전체 상황을 보고 있음
그중 일부 일을 전문 담당자에게 넘기는 구조

메인 에이전트 : "이번 기능 전부 구현해"
서브에이전트 A : 설계 검토
서브에이전트 B : 테스트 작성
서브에이전트 C : 보안 체크

 

즉, 한명의 만능 비서보다 작은 전문팀을 꾸리는 느낌

 

3. Skill(스킬)

반복 작업 절차를 재사용 가능한 작업 템플릿으로 만든 것

스킬의 예시
- 버그 재현 -> 원인 분석 -> 테스트 추가 -> 수정 -> 회귀테스트
- 새 기능 설계 -> 파일 탐색 -> 구현 -> 문서 업데이트
- PR 리뷰 -> 위험 포인트 체크 -> 성능 검토 -> 코멘트 작성

 

4. Command (커맨드)

사용자가 빠르게 호출하는 단축 명령
자주 쓰는 작업을 표준화하는 진입점

/plan : 계획 모드 시작
/tdd : 테스트 우선 개발 워크플로우 시작
/evolve : 학습된 패턴을 스킬로 승격

 

즉, command는 사용자 인터페이스, skill은 내부 작업 절차에 가까움

 

5. Hook(훅)

어떤 이벤트 전후에 자동으로 실행되는 연결지점

자동화 체크포인트
도구 실행 전 : 위험 명령인지 검사
도구 실행 후 : 로그 저장
세션 시작 시 : 프로젝트 규칙 로드
컨텍스트 압축 전 : 중요한 메모 백업

 

AI가 똑똑해도, 매번 사람이 "이제 이거 검사해", "끝났으면 로그 남겨" 라고 말하면 비효율적, 훅은 사람이 반복해서 말해야 하는 습관을 자동화

 

6. Rule(룰)

코딩 스타일, 테스팅, Git 워크플로우 같은 규칙 파일이 모듈별로 구성

TypeScript에선 any를 최소화
Python에선 pytest 기준으로 테스트 작성
보안 관련 파일은 직접 수정 전 리뷰 필수
PR 전엔 lint/test 필수

 

즉, 룰을 따로 둬 일관성 유지, 팀 규칙 반영, 프로젝트 품질 기준 강제가 편해짐

 

7. Frontmatter

---
name: planner
description: Expert planning specialist for complex features
tools: ["Read", "Grep", "Glob"]
model: opus
---

---로 감싼 YAML 영역이 나오는데, 이것은 문서 앞부분에 붙는 메타데이터 블록

 

쉽게 말하면,

• 이 파일 이름이 뭔지
• 무슨 역할인지
• 어떤 도구를 쓸 수 있는지
• 어떤 모델을 선호하는지

를 기계가 읽기 좋은 방식으로 적는 것

 

8. MCP (Model Context Protocol)

AI가 로컬 파일만 보지 않고, 외부 도구, 서버, 서비스와 연결되도록 해주는 인터페이스
MCP를 많이 쓸수록 좋다가 아니고, 필요한 만큼만 활성화하라는 관점이 중요

 

9. Context Window (컨텍스트 윈도우)

작업 기억 공간

- 프롬프트
- 코드 일부
- 규칙
- 도구 설명
- 이전 대화

 

원문이 MCP를 많이 켜면 실제 활용 가능한 컨텍스트가 줄어들 수 있다는 점도 이 작업 공간이 무한하지 않기 때문

 

10. Token Optimization (토큰 최적화)

AI에게 들어가는 텍스트 비용을 줄이면서, 필요한 정보는 유지하는 전략

길게 말해야 할 것은 짧게 정리하고
필요 없는 컨텍스트 줄이고
반복되는 절차는 구조화해서 재사용

 

즉, ECC가 에이전트/스킬/훅/툴을 나누는 이유도 결국은 토큰을 더 효율적으로 쓰기 위해

 

11. Continuous Learning / Instinct

ECC는 도구 사용 패턴을 훅으로 관찰하고, 이를 신뢰도 점수와 도메인 태그를 가진 Instinct로 저장

/evolve 명령어로 이런 패턴을 새로운 스킬/커맨드/에이전트로 발전시킬 수 있다고 설명
프로젝트 별 스코프를 두어 서로 오염되지 않도록 하는 것도 강조

정리하면,

AI가 자주 하는 좋은 작업 패턴을 관찰
그 패턴을 기억
나중엔 그걸 재사용 가능한 공식 절차로 바꿈

 

즉, 즉흥적인 잘한 행동을, 재사용 가능한 시스템으로 승격하는 개념

이걸 "학습"이라고 부르지만, 모델 자체를 재 훈련 하는 것이 아닌 "작업 패턴을 운영 레벨에서 축적하는 것"에 가까움

 

12. AgentShield

AI Agent 설정이 위험하지 않은지 검사하는 보안 점검기

ECC와 연결된 독립 npm 패키지
시크릿 탐지, 권한 감사, 훅 인젝션 분석, MCP 위험 분석, 설정 검토 등 5개 카테고리 스캔을 제공

AI는 단순 텍스트 생성기가 아니라 도구를 호출하고 파일을 읽고 명령을 실행할 수 있기 때문

위험 포인트
- 비밀 키 노출
- 위험한 도구 권한
- 악성 훅 삽입
- 외부 MCP 연결 취약점

 

즉, 예전엔 "앱 코드 보안"만 보안 되었다면, 이젠 에이전트 운영 설정 자체의 보안도 봐야 함

 

ECC / Toss Harness / About Harness Engineering

 

공통적인 메시지
AI의 성능 차이는 모델 자체보다, 그 모델을 어떤 규칙/도구/검증/문맥/워크플로우로 감싸는 가에서 크게 갈림

 

좋은 모델을 쓰는 것만으로는 부족
팀의 규칙, 문맥, 검증 루프, 저장 구조, 실행 환경이 함께 있어야 함
개인이 "프롬프트 잘 치는 법"을 아는 수준에서 끝나면 조직 생산성은 들쭉날쭉하다.
조직은 AI 사용법이 아닌 "AI가 일하게 되는 시스템"을 설계해야 한다.

 

1) 하네스(harness)란 무엇인가?

Harness는 원래 말에게 씌우는 '마구'이다. 아무리 힘이 좋아도 마구가 없으면 방향을 못 잡고, 힘도 원하는 곳에 전달하기가 힘들다.
<In AI>
모델 : 말
하네스 : 그 힘을 실제 일로 바꾸는 구조

 

2) 공통 핵심

개인의 센스에 맡기면 조직 생산성이 흔들림

- 같은 모델, 같은 IDE, 같은 저장소를 써도 누군간 10분 만에 끝내고, 누군가는 1시간 동안 수정 루프를 돔
- 잘하는 사람이 잘하는 이유를 개인 비법으로 남기지 않고
- 재사용 가능한 구조로 만들어 팀에 배포 해야 한다.

 

문서는 정적이지만, 하네스는 실행된다.

팀 브랜치 전략이 문서에만 있으면 안 지킬 수 도 있다.
하네스 훅에 들어가 있으면 AI가 main에서 커밋하려 할 때 feature 브랜치로 유도할 수 있다.

즉, 하네스는 "설명서"가 아니라 "행동 교정 장치"이다.

 

중요한 것은 더 많은 문맥이 아니라 더 좋은 문맥이다.

필요한 정보만 필요한 시점에 필요한 범위로 주입하는 것

 

도구를 많이 붙이는 게 능사가 아니다.

MCP나 각종 서버를 과도하게 연결하면 설명문 자체가 컨텍스트 예산을 잡아먹는다.

 

3) 따라서 실제 도입시 무엇을 설계하면 좋을까? [7가지]

①. 금지해야 할 실패는 무엇인가?

  - main 브랜치 직접 수정
  - 테스트 없이 완료 처리
  - 민감 정보 로그 출력
  - 프로젝트 규칙 위반
  - 디렉터리 구조 파괴
  - 레거시 핵심 파일 무단 변경

 

②. 반복해서 잘하고 싶은 것은 무엇인가?

  - 신규 기능 생성
  - 버그 수정
  - 코드 리뷰
  - 테스트 보강
  - 문서화
  - 릴리즈 전 점검

 

③. 어떤 검증을 자동화할 것인가?

  - lint
  - typecheck
  - unit test
  - integration test
  - e2e
  - security scan
  - format

 

④. 문맥을 어떻게 계층화할 것인가?

  - 글로벌 규칙
  - 도메인 규칙
  - 프로젝트 규칙
  - 현재 작업 상태

 

⑤. 어떤 것은 사람이 승인해야 하는가?

  - 데이터베이스 스키마 변경
  - 운영 배포
  - 보안 관련 설정 변경
  - 결제/정산 핵심 로직 수정

 

⑥. 세션 간 상태를 어디에 남길 것인가?

  - progress.md
  - task-log.md
  - decision-log.md
  - current-plan.md

 

⑦. 실패를 어떻게 학습 자산으로 승격할 것인가?

  - 동일 실패가 3번 나오면 Rule로 승격
  - 자주 반복되는 성공 작업은 Skill로 승격
  - 자주 쓰는 진입 흐름은 Command로 승격

 

4) 실전 도입 구조 : 예시

- 최소 단위

project/
├─ .ai/
│  ├─ rules/
│  │  ├─ global.md
│  │  └─ project.md
│  ├─ workflows/
│  │  └─ new-feature.md
│  ├─ hooks/
│  │  ├─ pre-commit-check.sh
│  │  └─ task-complete-check.sh
│  └─ state/
│     └─ progress.md
├─ src/
├─ tests/
└─ README.md

- 조금 더 성숙한 구조

project/
├─ .ai/
│  ├─ agents/
│  │  ├─ planner.md
│  │  ├─ implementer.md
│  │  ├─ reviewer.md
│  │  └─ security-reviewer.md
│  ├─ skills/
│  │  ├─ plan-feature.md
│  │  ├─ implement-with-tests.md
│  │  ├─ refactor-safely.md
│  │  └─ review-pr.md
│  ├─ commands/
│  │  ├─ new-feature.md
│  │  ├─ fix-bug.md
│  │  ├─ code-review.md
│  │  └─ release-check.md
│  ├─ rules/
│  │  ├─ 00-global-security.md
│  │  ├─ 01-global-style.md
│  │  ├─ 10-domain-payment.md
│  │  ├─ 10-domain-sql.md
│  │  └─ 20-local-project.md
│  ├─ hooks/
│  │  ├─ pre-tool-use.sh
│  │  ├─ post-tool-use.sh
│  │  ├─ on-session-start.sh
│  │  ├─ on-stop.sh
│  │  └─ task-complete.sh
│  ├─ state/
│  │  ├─ progress.md
│  │  ├─ current-plan.md
│  │  ├─ decision-log.md
│  │  └─ handoff.md
│  ├─ checks/
│  │  ├─ lint.sh
│  │  ├─ test.sh
│  │  ├─ e2e.sh
│  │  └─ security-scan.sh
│  └─ README.md
├─ docs/
│  ├─ architecture/
│  ├─ adr/
│  └─ domain/
├─ src/
├─ tests/
├─ scripts/
└─ README.md

 

 

추가적인 내용은 하네스 엔지니어링 - 이해의 폭을 넓히기 위해서 2로 더욱 더 재밌고 유익한 얘기로 돌아오도록  하겠습니다! 읽어주셔서 감사합니다!

 

Reference :

https://openai.com/ko-KR/index/harness-engineering/

하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기

https://wikidocs.net/blog/@jaehong/9481/

하네스 엔지니어링: AI 에이전트 시대, 경쟁력은 모델이 아니라 '마구'에서 나온다

https://goddaehee.tistory.com/575

"하네스 엔지니어링" - Everything Claude Code 리뷰 : 혼자서 팀처럼 개발하는 에이전트 셋업(ECC 하네스

https://toss.tech/article/harness-for-team-productivity

Software 3.0 시대, Harness를 통한 조직 생산성 저점 높이기