개요 최근 팀에서 AI 코딩 도구를 활용하는 빈도가 늘어나면서, AI가 프로젝트의 고유한 맥락(context)과 컨벤션을 인지하지 못해 같은 설명을 매번 반복해야 하는 비효율을 자주 겪었습니다. 예를 들어 “user 조회 React Query 훅 만들어줘”라고 요청하면, 규칙을 모르는 AI는 공식 문서에 나올 법한 기초적인 형태로 코드를 짜줍니다. 결국 원하는 코드를 얻기 위해 매번 이런 설명을 덧붙여야 했습니다. 이 […]
The post 하네스 엔지니어링(harness engineering)으로 팀 맞춤형 AI 환경 구축하기 first appeared on 우아한형제들 기술블로그. || 개요
최근 팀에서 AI 코딩 도구를 활용하는 빈도가 늘어나면서, AI가 프로젝트의 고유한 맥락(context)과 컨벤션을 인지하지 못해 같은 설명을 매번 반복해야 하는 비효율을 자주 겪었습니다.
예를 들어 “user 조회 React Query 훅 만들어줘”라고 요청하면, 규칙을 모르는 AI는 공식 문서에 나올 법한 기초적인 형태로 코드를 짜줍니다. 결국 원하는 코드를 얻기 위해 매번 이런 설명을 덧붙여야 했습니다.
이 프로젝트는 React Query를 사용하고
캐시 키는 특정 파일에서 중앙 관리하며
API 호출은 직접 fetch를 쓰지 않고 API Class를 사용합니다
원하는 코드 하나를 얻기 위해 ‘규칙 설명, 오류 지적, 재요청’이라는 피곤한 과정을 매번 반복해야 했습니다.
출처: 생성형 AI 이미지, Gemini
그래서 이런 생각이 들었습니다. ‘AI가 프로젝트 규칙을 처음부터 알고 있게 만들 수는 없을까?’
이러한 요구는 이미 개발 업계에서 ‘하네스 엔지니어링(harness engineering)’이라는 개념으로 구체화되어 있습니다. 이는 AI가 길을 잃지 않고 안정적으로 일할 수 있도록 외부 통제 환경을 구축하는 것을 의미합니다.이 글에서는 최근 많이 활용하는 Cursor IDE 환경을 기준으로, Rules와 Skills를 이용해 우리 팀만의 하네스를 구성하고, 더 나아가 응답 속도와 토큰 비용까지 최적화해 본 실전 사례를 공유합니다.
Rules / Skills
Cursor 환경에서 AI의 동작을 제어하고 자동화하기 위해 다음과 같은 디렉토리 구조를 구성할 수 있습니다.
.cursor
├ rules
└ skills
각 역할은 다음과 같습니다.
구성
역할
Rules
코드 작성 규칙 전달
Skills
작업 자동화
Rules
Rules는 AI에게 프로젝트의 코딩 컨벤션을 전달하는 역할을 합니다. 앞서 개요에서 언급했던 ‘우리 팀의 핵심 규칙(React Query, 캐시 키 중앙 관리, API Layer 분리)’을 Rules로 정의하면 다음과 같이 작성할 수 있습니다.
---
description: React Query 훅 작성 규칙
globs: "src/queries/**/*.ts"
---
# Data Fetching
상태 관리는 React Query(useQuery, useMutation)를 활용한 커스텀 훅으로 작성
API 호출 시 직접 fetch하지 않고, 지정된 API Class(예: UserAPI)를 import하여 사용
Query Key는 하드코딩을 금지하며, queryKeys.ts의 중앙 관리 객체를 참조
Tip: 여기서 주목할 점은 globs 옵션입니다. 모든 질문에 정의된 Rules를 무조건 포함하는 것이 아니라, globs에 지정한 경로의 파일들을 작업할 때만 해당 규칙이 활성화됩니다. 이를 통해 불필요한 토큰 낭비를 막고 AI의 응답 속도와 정확도를 높일 수 있습니다.
이렇게 규칙을 정의해 두면 AI가 코드를 생성할 때 별도의 추가 설명 없이도 우리가 만든 커스텀 axios 인스턴스를 알아서 import 해오고, 중앙 관리되는 캐시 키 객체를 찾아 사용하는 등 ‘실무에 바로 투입 가능한 형태’로 첫 코드를 뽑아줍니