AI 하네스 엔지니어링

JAMEe_·2026년 6월 29일

AI툴

목록 보기

3/3

AI 하네스 엔지니어링 정리

코드를 직접 잘 짜는 일에서, AI가 알아서 잘 일하도록 하네스를 설계하는 일로 무게중심이 넘어온 느낌

1. 컨텍스트랑 토큰 아끼기

매번 시키는 반복 작업은 미리 스크립트로 만들어두는 게 효율 — json→csv 변환을 매번 부탁하는 것보다, 변환 스크립트 깔아두고 파일만 던져서 실행시키는 방식
MCP는 무겁고 컨텍스트를 잡아먹으니 평소엔 꺼두고 필요할 때만 켜는 방식
외부 연결도 무거운 MCP보단 CLI로 불러쓰는 걸 선호
무거운 작업은 subagent한테 넘기고 메인 컨텍스트엔 요약본만 남기기

CLAUDE.md는 매 요청마다 컨텍스트로 들어가니까 최대한 가볍게

큰 파일은 한 번 read해서 캐시에 박기
CLAUDE.md는 정돈해서 항상 상단에 — 위에 둬야 다른 프리픽스 때문에 캐시미스 나는 걸 방지
내 input만 가는 게 아니라 system prompt랑 CLAUDE.md 내용까지 전부 긴 스트림으로 붙어서 감 — 일치하는 데까지만 캐시되고 어긋나는 지점부터는 캐시 안 됨
컨텍스트 50% 넘어가면 새 섹션 파서 작업
진행 중인 섹션에서 모델이나 CLAUDE.md 건드리면 캐시 다 날아가고 내부적으로 꼬임 — 바꿀 거면 새 섹션 파고 새로 질문
엔트로픽 CLI로 프로젝트 범위 섹션 로그 들여다보면서 어디를 최적화할지 잡기
중요한 최적화는 훅으로 강제 (/compact는 40% 넘으면 자동으로 돌게)

root CLAUDE.md에서 다른 md 참조할 때 @~.md는 항상 로드, @ 없으면 필요할 때만 읽는 차이

2. 자동화 훅 알아보기

종류	성격	예시
Hook	이벤트 기반, 보장이 필요한 작업	커밋 전 린트/빌드/테스트
`/loop`	세션 안에서 도는 자동화, 기본 7일 후 만료	커밋·히스토리 주기적 체크
`/routine`	엔트로픽 클라우드 실행, 로컬 꺼져도 돎, 기본 영구	주간 요약, 정기 PR 리뷰

훅 타입

PreToolUse: 호출 직전 — 입력 검증, 위험 명령 차단(git push --force), TDD 강제
PostToolUse: 호출 직후 — 린트·포맷·테스트 자동 실행
Notification: 작업 후 알림 — 긴 작업 끝나고 다시 붙을 때 유용
Stop: 모든 에이전트 완료 시점 — 최종 정리, 린트·빌드·테스트는 주로 여기서

CLAUDE.md는 "이렇게 해줘"라고 권장하는 거고, 훅은 "무조건 이렇게 된다"고 강제하는 차이

3. 서브에이전트 & 에이전트팀

서브에이전트끼리는 직접 소통 불가 — 팀 전체가 하나의 유기체처럼 움직이는 구조
서브에이전트는 sonnet으로 만드는 걸 권장
클로드 터미널 여러 개 띄워서 같은 파일 병렬 작업하면 충돌남 — worktree 파서 작업 (자연어로 부탁하거나 claude --worktree로 켤 때 설정)

worktree vs same-dir

same-dir: 같은 프로젝트 이어받아 작업 — 터미널1에서 A기능, 터미널2에서 B기능 동시에 하면 파일 충돌 위험
worktree: 새 깃 브랜치로 분리해서 작업 — PC에서 A기능 돌리는 중에 밖에서 폰으로 B기능 만지고 싶을 때
한 IDE는 터미널이 여러 개여도 결국 한 프로젝트 구조만 띄우니까, 브랜치만 새로 판다고 해결 안 됨 → 그래서 worktree

4. 스킬 & 플러그인

플러그인 = skill / hooks / agents를 만들어 묶은 공구박스 (조합은 자유)
/plugin 마켓플레이스에서 남이 만든 거 다운 가능 — 팀에 공유하고 싶으면 플러그인으로 배포
플러그인은 결국 깃에 올라간 걸 받아오는 구조 — .claude-plugin 폴더에 marketplace.json 세팅 필요
- /plugin marketplace add 깃유저명/레포 → /plugin discover 탭에서 검색해서 등록
skill-creator로 "유닛테스트 짜주는 스킬" 같은 거 생성 — 보통 스킬 + 전용 서브에이전트를 같이 만듦
스킬도 유지보수 대상 — 프로젝트 코드 구조나 컨벤션 바뀌면 같이 손봐야 함
스킬용 유닛테스트 = eval, skill-creator로 만들 때 자동 생성됨
만들고 나서 /skills에서 on 상태인지 확인
에이전틱 기능 하나 만들 때마다 플러그인에 쌓아서 팀이 받아쓰는 식

5. 컨텍스트 엔지니어링

에이전트의 first brain은 모델, second brain은 컨텍스트

Probabilistic Confusion — 모델은 다음 토큰 고를 때 컨텍스트 어디에 주의를 둘지 정함. 그릇 커졌다고 다 때려넣는 게 아니라 필요한 정보만

Hierarchical Markdown Tree — PRD, ARD 같은 코드베이스 밖 도메인 지식도 md로 같이 첨부. 코드베이스에 없는 도메인 지식은 에이전트한테 존재하지 않는 거나 마찬가지

Hierarchical Knowledge Graph — 트리 구조로 참조. CLAUDE.md / AGENTS.md → 파일 안에서 @docs/…로 분기 → 각 문서가 다시 세부 결정으로 분기

3 Layer 구조 — 레이어를 3개로 쪼개면 각 레이어에 연관된 정보끼리 뭉쳐두기. 이렇게 구조화하면 에이전트 컨텍스트가 현재 작업 범위로 좁혀짐

6. 에이전틱 4대 베이스

Agentic Validation

에이전트가 스스로 검증하는 루프 — 기술스택 달라도 패턴은 동일. 외부 결정론적 시스템에서 시그널 받아 컨텍스트로 줘서 자가 수정하게 만들기

1차: unit/integration test, 스크립트 크래시 — 가장 약한 검증
2차: 내부 system state(DB 무결성, 외부 시스템, 비정상 패턴)가 의도한 결과랑 맞는지

Agentic Tooling

인간 시간 뺏는 friction(인간 개입 강제)을 어떻게 없앨까가 핵심. 에이전트가 못 하는 걸 내가 대신 처리하지 말고 도구를 쥐어주기. 신규 시스템 도입하면 일단 CLI 먼저 — 자율 실행할 수 있는 1차 다리

friction 4분류해서 대응 도구 만들기

(로컬) 에이전트가 쓸 새 CLI 도구 — 직접 파일 수정·포맷·설정하게
(외부 시스템) github, aws 같은 거 api/cli/스크립트 쥐어줘서 알아서 돌리게
(사람 입력 대기) 매뉴얼 룩업·승인을 skill이나 mcp로
(신규 시스템) 권한 없다 → CLI로 감싸서 실행 허용. 단발 CLI도 스킬로 감싸면 팀 자산이 됨

middle-tier orchestration: 같은 동작·결과 보장되는 영역은 사람이 신경 끄기
high-level architectural: 같은 결과 보장하려고 가드레일 거는 영역에 사람이 집중 — 멀리 보면 이 영역 줄어들수록 완전 자동화에 가까워짐

Agentic Codebases

Pattern Contamination 제거 — 브라운필드(레거시)는 에이전트 루프에 독을 줌. 같은 기능 하는 현재 코드/레거시 코드가 둘 다 있으면 뭐 써야 할지 몰라서 컨텍스트 오염

DRY 딜레마 — 사람은 한 곳에 정의하고 불러쓰는데, 에이전트는 그 한 곳을 쓰는 모든 코드를 탐색하느라 컨텍스트가 커짐. 요즘 DRY 지키는 게 맞나 고민되는 지점
Consistent File Structures — 디렉토리 계층 표준화해서 "어디 둘까요" 안 묻고 예측 가능한 자리에 정확히 두게
Agent-Specific Logging — 사람이 디버깅할 일 없으니 에이전트용 로깅 필요. 기존 console → JSON line 로그(LogQL)
Agent RAG — 에이전트용 규칙을 md로 만들고 일관된 코드베이스 유지 (결제 코드는 src/payment에만…)

"이제 다음 사람이 아니라 다음 에이전트가 쓸 코드를 짠다"는 마인드

Compound Engineering

팀이 공유하며 쌓아온 위 4개 베이스로 완전 자동화된 에이전트 하나가 완성됨. compound 지식이 쌓이면 코드가 사실상 스스로를 만들기 시작하는 단계 진입

7. 하네스 설계 흐름

구조 설계 — 폴더 구조 잘 짜둬야 AI가 고민 없이 정확한 자리에 생성

맥락 설계 — user / project / folder 3 레이어 CLAUDE.md. CLAUDE.md엔 핵심만 두고 두꺼운 건 rules/에 빼서 필요할 때 참조

검증 계획 — 그냥 "해줘"보다 인터뷰 형식으로 같이 만들어가는 과정

실행 — 서브에이전트 / 팀 / 랄프 루프

랄프 루프: 조건 충족 전까지 계속 반복 — "전체 테스트 통과 + 빌드 성공 + 커버리지 80%" 못 채우면 테스트 더 짜고 반복

검증 — 기준 없으면 검증 불가

완료조건 먼저 → 측정 가능하게 → 미달이면 다시 돌리기
만드는 AI랑 검수하는 AI는 독립적으로 분리

개선 (주차별 예시)

1주차: 배포 전 점검(테스트·빌드)을 매번 시키다가 스킬로
2주차: AI가 자꾸 프로덕션 DB 건드림 → rules/에 규칙 추가
3주차: /context로 안 쓰는 mcp 찾아 삭제
4주차: 모델이 똑똑해졌으면 불필요한 규칙 삭제

딱 내가 원하는 걸 만들어내는 가벼운 하네스가 좋은 하네스. 하네스로 하네스를 만드는 게 메타하네스

CLAUDE.md 관리 도구

카파시 정리본을 복사해서 user CLAUDE.md에 넣어 전역 세팅
claude-md-management 플러그인 — claude-md-improver 스킬이 현재 CLAUDE.md 등급 매기고 수정 제안, /revise-claude-md가 세션에서 추가된 영역을 반영
AI-Ready Codebase(에이전트가 길 안 잃는 코드베이스)도 점수 매기고 수정 제안하는 스킬 만들어 주기적으로 검사

8. TDD / SDD

TDD — 코드 짜기 전에 에이전트가 따라갈 객관적 기준부터 만들기

test-first: 구현 파일 짜기 전 테스트 있는지 확인, 없으면 테스트부터
자기수정 루프 잠금: N회 이상 실패하면 자동 stop (무한루프 방지)

SDD — 자연어 스펙 먼저 쓰고 코드 생성·검증을 그 스펙이 주도하는 방식

9. 코드리뷰 자동화

2024: 전부 사람 손
2026: AI가 1차 리뷰, 중요한 부분만 사람이 2차

흐름

PR 올리기 전 작성자가 셀프리뷰 로컬로 (/code-review, pre-commit 훅)
PR 생성/푸시되면 깃액션에서 다른 모델(openai gpt 등)이 돌면서 PR에 직접 코멘트 — 로컬 검증 후 PR에서 다른 모델로 한 번 더
리스크 스코어 매겨서 점수 높으면 사람 리뷰 권장 — 보안, 파일 수, 환경변수 추가, 테스트 코드, DB 마이그레이션 등

실무자가 가장 많이 박는 5패턴 차단

rm -rf류 차단
.env 민감 파일 read 차단
프로덕션 DB 접속 차단
API 키 노출 차단
git push --force 차단

Oncall agent — 프로덕션 시그널에 1차 대응만, 절대 직접 처리 안 함

트리거: Sentry / PagerDuty / 로그 같은 signal
24/7 대기, 입력은 웹훅·metric·로그라인, 출력은 진단 리포트 + 사람 호출 결정
결정은 딱 하나 "사람을 깨울까 말까"
이점: 정리된 리포트 덕에 문제 지점 파악 시간 단축, 같은 패턴 버그면 과거 티켓 끌어와 이전 해결법 공유

10. 보안 & 원격

세션에서 API 키 직접 주지 말기 — 터미널 해킹으로 빼갈 수 있어서 직접 붙여넣는 방식으로 구현
claude -p는 비대화형 모드, 파이프라인용
claude -p dangerously skip permission — 혼자 작업 다 하는 비대화형, 클로드 서버에서 돎. 매일 밤 12시 어제 코드 검사 같은 거 자동화 가능, 별도 API 과금
폰으로 퍼미션 응답: /remote-control → config → remote에서 Enable Remote를 true로 하면 모든 세션 폰으로 확인
원격 작업은 PC 세션이 계속 살아있어야 함 — 터미널에서 caffeinate 치면 화면 꺼져도 프로세스는 유지
디스코드 연결: claude --channels plugin:discord@claude-plugins-official

11. 세컨드 브레인 & Context Intelligence

RAG vs LLM WIKI — 사내에서 AI로 문서 찾아 정보 얻을 때

RAG: 읽기 전용
LLM WIKI: 읽기 + 쓰기 + 유지보수 → 지식이 계속 누적됨
옵시디언 받아서 거기서 클로드 돌려 LLM WIKI 구축

Context Intelligence — AI 에이전트를 위한 조직 전체 공유 지식 레이어

"왜 결제가 실패했나?"처럼 API·인증·DB·알림·대시보드 5~6개 팀이 엮인 문제
문제는 팀 A의 변경이 팀 B에 영향 주는데, 팀 A 에이전트는 팀 A 코드밖에 모름
skill의 config 폴더 yaml에 회사 전체 정보를 참조하도록 걸어두기
팀 공유는 결국 플러그인으로 (깃에 올린 걸 받아오는 구조)

12. 실전 — 도담 프로젝트로 굴려본 전체 플로우

React Native 일정관리 앱 도담을 MVP로 빠르게 출시해보는 흐름

기획

요즘은 플랜모드 잘 안 쓰고 스킬로 풀어가는 편 — 한 번의 플랜으로 기획이 안 끝나서. 플랜모드 쓸 거면 최소 4번은 다시 시도
grill-me-skill 추천 — 면접관이 기획 빈틈 캐묻듯 파고드는 스킬

플랜/문서 반복 검증 순서

user flow·user journey 중심으로 모든 시나리오·가설 파악해서 PRD.md 수정 + user flow를 머메이드 다이어그램으로
ARCHITECTURE.md 검증 — 테크스택·DB·아키텍처·인터페이스 디자인 제대로 됐는지
엣지 케이스·에러 핸들링·보안 측면 점검, 고칠 것만 짚기
MVP 목적에 맞게 오버엔지니어링·불필요한 복잡함 없는지 재검수
결과를 PLAN.md(또는 docs/PRD·ARCHITECTURE·ADR)로
코덱스에서 재검토 → 클로드에서 마지막 검수

디자인

클로드코드 디자인이 구독 토큰이랑 공유돼서 넉넉하게 사용 가능
테마 컨셉 주고 디자인 시스템 생성 프롬프트(DESIGN_BRIEF.md) 받아서 → 슬라이드덱 테마 골라 프로토타입 구현
디자인 시스템 export해서 프로젝트로 옮기기 — 폴더 안에 디자인 스킬 등록, 프로토타입 폴더엔 README.md
docs/UI_GUIDE.md를 디자인 시스템 + DESIGN_BRIEF 참고해서 작성
프로토타입은 html로 나오니까, 이걸 내 개발 언어 코드로 재구현하는 스킬도 따로 생성

코드 작성 (코덱스 전환)

execute.py에서 claude 부분을 전부 codex로 바꾸고 AGENTS.md도 생성
codex hook도 셋업 (클로드처럼 훅이 등록돼 있어야 트리거됨)
/harness 스킬로 RN 기본 세팅·라이브러리 설치·공통 디자인 컴포넌트 생성

커스텀 /harness 스킬 동작 구조

요청 기능을 phase로 나누고, 각 phase 안에서 step으로 쪼갬 (전체 맥락은 나눠뒀지만 실제로는 당장 구현할 phase·step만 프로젝트에 생성)
execute.py가 phase명으로 브랜치 생성·체크아웃 → 각 step 단계별로 진행하며 커밋 → 마지막 step 끝나면 PR 자동 생성
이 과정을 마지막 phase까지 반복해서 자동 구현
각 step은 읽을 파일 정보랑 작업을 동일하게 들고 있음 — codex exec로 새 step마다 새 섹션을 파기 때문
step 결과물은 step{n}-output.json으로 따로 저장, 다음 step은 이전 output들을 참조하는 방식
한 사이클 끝나면 완료된 작업 토대로 harness 개선 부분 찾아 보완 (완벽한 자동화를 향해)

JAMEe_

안녕하세요