하네스 엔지니어링 — 팀을 위한 AI 개발 환경을 설계하는 방법

왜 같은 도구인데 결과가 다를까

같은 AI 도구를 쓰는데 어떤 팀은 "그냥 쓸 만하다"고 하고, 어떤 팀은 "첫 시도에 원하는 코드가 나온다"고 한다. 차이는 프롬프트 실력이 아니다. AI가 일하는 환경이 다른 것이다.

우아한형제들이 공개한 사례는 이 차이를 잘 보여준다. 팀은 Claude Code를 쓰면서 "React Query 훅 만들어줘"라고 요청하면 프로젝트 컨벤션을 무시한 코드가 나오는 문제를 겪었다. 해결책은 더 자세한 프롬프트가 아니었다. Rules와 Skills로 AI의 작업 환경을 설계하는 것이었다.

이를 **하네스 엔지니어링(Harness Engineering)**이라고 부른다. AI가 길을 잃지 않도록 외부 통제 환경을 구축하는 것이다. 비유하면 신입 개발자에게 "알아서 해"라고 하는 게 아니라, 코딩 가이드, 팀 컨벤션 문서, 코드 리뷰 체크리스트를 미리 쥐여주는 것과 같다.

Rules — AI에게 프로젝트 컨벤션 전달하기

Rules는 AI가 코드를 작성할 때 항상 참조하는 규칙 파일이다. 핵심은 "AI가 이미 아는 것"은 쓰지 않는 것이다.

일반적인 React 컴포넌트 패턴, TypeScript 기본 문법 — 이건 AI가 이미 안다. Rules에 쓰면 컨텍스트 낭비다. Rules에는 프로젝트 특화 규칙만 넣는다.

## React Query 훅 작성 규칙
 
- 모든 쿼리 키는 `src/lib/queryKeys.ts`에서 중앙 관리한다
- API 호출은 반드시 `UserAPI`, `OrderAPI` 등 API Class를 통해 한다
- `fetch` 직접 사용 금지
- 훅 파일명: `use{Entity}{Action}.ts` (예: `useUserProfile.ts`)

이 Rules가 활성화된 상태에서 "user 조회 React Query 훅 만들어줘"라고 하면, AI는 자동으로 queryKeys.ts를 참조하고 UserAPI 클래스를 쓴다. 추가 설명 없이도.

[💡 잠깐! 이 용어는?] 글로브(globs) 옵션: Rules를 특정 파일 경로에서만 활성화하는 설정. src/components/**/*.tsx 파일을 편집할 때만 특정 규칙을 적용하고, 다른 경로에서는 비활성화할 수 있다. 불필요한 컨텍스트 소비를 막는다.

Before / After

Rules 없을 때:

요청: "user 조회 React Query 훅 만들어줘"

결과:
const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetch(`/api/user/${userId}`).then(r => r.json())
})
// fetch 직접 사용, 쿼리 키 분산 관리 — 컨벤션 위반

Rules 적용 후:

import { useQuery } from '@tanstack/react-query'
import { UserAPI } from '@/lib/api/UserAPI'
import { queryKeys } from '@/lib/queryKeys'
 
export function useUserProfile(userId: string) {
  return useQuery({
    queryKey: queryKeys.user.profile(userId),
    queryFn: () => UserAPI.getProfile(userId),
  })
}
// queryKeys 중앙 관리, UserAPI 사용 — 컨벤션 준수

Skills — 반복 작업을 워크플로로 자동화하기

Rules가 "어떻게 쓸 것인가"라면, Skills는 "무엇을 할 것인가"다. 스크립트와 CLI 도구를 실행해서 반복 작업 흐름을 자동화한다.

Skills는 "명령어 실행 + 결과 해석 + 코드 작성"을 하나의 흐름으로 연결한다. 개발자가 매번 수동으로 하던 일을 한 번의 요청으로 처리한다.

컨텍스트 최적화 — 데이터를 95% 줄인 전처리

AI를 쓸 때 비용을 가장 잡아먹는 것 중 하나가 불필요한 컨텍스트다. 관련 파일을 찾느라 여러 번 도구를 호출하고, 불필요한 코드까지 전부 읽는다.

팀은 Node.js 전처리 스크립트를 만들어 AI에게 필요한 메타데이터만 전달했다.

const fs = require('fs')
const path = require('path')
 
// API 클래스에서 클래스명과 메서드 시그니처만 추출
function extractApiMeta(filePath) {
  const content = fs.readFileSync(filePath, 'utf-8')
  const classMatch = content.match(/export class (\w+)/)
  const methods = [...content.matchAll(/async (\w+)\(([^)]*)\): Promise<([^>]+)>/g)]
 
  return {
    className: classMatch?.[1],
    methods: methods.map(([, name, params, returnType]) => ({
      name,
      params,
      returnType,
    })),
  }
}

결과:

Tool Call 횟수도 4회에서 1회로 줄었다. AI가 파일을 직접 뒤지는 대신 이미 정제된 정보를 받아서 바로 코드를 작성한다.

Rules와 Skills 역할 분리

두 개념을 혼동하기 쉽다. 기준은 단순하다.

Rules는 배경 지식, Skills는 도구 사용법이다.

도입 효과

팀이 겪은 변화는 수치보다 개발자 경험 측면에서 더 크다.

• 인지적 피로도 감소: 매번 컨벤션을 설명하는 대신 Rules가 대신 전달한다
• 일관성: 개발자마다 다른 방식으로 요청해도 결과 코드가 동일한 패턴을 따른다
• PR 리뷰 변화: "이렇게 쓰세요" 식의 스타일 지적이 줄고, 로직 리뷰에 집중할 수 있게 됐다

마무리

하네스 엔지니어링은 AI를 "더 잘 쓰는 법"이 아니라 "팀이 AI와 함께 일하는 환경을 설계하는 법"에 관한 이야기다. 프롬프트 엔지니어링이 개인 스킬이라면, 하네스 엔지니어링은 팀 인프라다.

Rules에 들어갈 내용을 정의하려면 팀 컨벤션을 명문화해야 하고, Skills를 만들려면 반복 작업을 파악해야 한다. 그 과정 자체가 팀의 개발 방식을 정리하는 계기가 된다.

AI 도구를 팀에 도입했는데 효과가 기대에 못 미친다면, 도구가 아니라 환경을 먼저 들여다볼 만하다.

참고:

• https://techblog.woowahan.com/26177/