목차
팀의 코딩 규칙을 기본값으로 삼은 Cursor 하네스 (2026-04)
원문 정보
- 원문: 하네스 엔지니어링(harness engineering)으로 팀 맞춤형 AI 환경 구축하기
- 매체 · 게시일: 우아한형제들 기술블로그 · 2026-04-17
- 저자: 본문에 저자 미표기
- 원문 내용을 바탕으로 재구성한 요약입니다.
한 줄 요청의 기본값이 된 Rules
“user 조회 React Query 훅 만들어줘”라는 요청은 짧았지만, 원하는 코드를 받기까지는 길었습니다. AI가 프로젝트의 규칙을 모르다 보니, React Query를 쓰고 캐시 키는 queryKeys.ts에서 중앙 관리하며 API 호출에는 직접 fetch를 쓰지 않고 API Class를 사용한다는 설명을 매번 덧붙여야 했습니다. 설명 뒤에도 키 패턴이 어긋나거나 fetch를 직접 호출하는 코드가 나오면 다시 수정을 요청하는 흐름입니다.
우아한형제들의 한 팀은 이 설명을 AI의 작업 환경에 미리 두었습니다. Cursor IDE의 .cursor 아래에 rules와 skills를 두고, Rules에는 코드 작성 규칙을, Skills에는 자동화할 작업 흐름을 담았습니다. AI가 길을 잃지 않고 안정적으로 일하도록 외부 통제 환경을 만드는 하네스 엔지니어링입니다.
Rules에 팀 규칙을 정의하자 요청에서 배경 설명이 빠졌습니다. 같은 한 줄을 입력해도 AI가 queryKeys.user(id)로 캐시 키를 지정하고 UserAPI.getUser(id)로 API를 호출하는 훅을 한 번에 생성했습니다. 개발자마다 지시하는 방식이 달라도 프로젝트 컨벤션을 기본 전제로 삼은 결과입니다.
규칙의 범위는 프로젝트 안으로 좁혔습니다. React 컴포넌트 작성법이나 TypeScript 기본 문법처럼 LLM이 이미 아는 내용까지 넣으면 컨텍스트만 커집니다. 대신 폴더 구조와 핵심 비즈니스 로직의 패턴을 명시해, AI가 유사한 코드를 찾으려고 프로젝트 전체를 무작위로 훑는 일을 줄이고자 했습니다. 관련 없는 파일을 참고해 환각을 일으키거나, 컨텍스트 윈도우를 낭비해 답변이 중간에 끊기는 문제를 막기 위한 선택입니다. 작업 절차는 Skills에 두어 Rules와 내용이 겹치지 않게 했습니다.
규칙을 읽는 시점도 제한했습니다. Rules 예시의 globs 값은 src/queries/**/*.ts이며, 이 경로의 파일을 다룰 때만 해당 규칙이 활성화됩니다. 모든 질문에 규칙을 붙이지 않으므로 불필요한 토큰 소비를 막고 응답 속도와 정확도를 높일 수 있습니다.
팀에서 체감한 변화는 요청을 준비하는 피로가 줄었다는 점입니다. 첫 시도에 원하는 결과를 얻는 비율도 높아졌습니다. 누가 요청하든 팀 컨벤션에 맞는 코드가 나오면서 PR(MR) 리뷰에서 단순한 스타일을 지적하던 시간도 사라졌다고 합니다. 프로젝트에 명확한 컨벤션이 있거나 팀 단위로 AI 활용 기준을 세우려 할 때 적용하기 좋은 방식입니다.
API 연동의 초안을 만드는 Skills
규칙을 알아도 남는 작업이 있습니다. API 스펙 문서를 보며 타입을 옮겨 적고, API 클래스와 React Query 훅 파일을 만들어 연결하는 초기 세팅입니다. Skills는 Node.js나 bash 스크립트, CLI 도구를 실행해 데이터를 가져오고 가공하며 이런 작업 순서를 자동화합니다.
Swagger 기반 API 스킬이 그 예입니다. Swagger 데이터를 가져와 분석한 뒤 TypeScript 타입, API 클래스, React Query Hook, 테스트 코드를 차례로 생성합니다. 문서를 읽고 파일을 하나씩 만들던 과정이 명령어 한 줄로 줄어듭니다. AI가 만든 코드가 100% 완벽한 것은 아닙니다. 개발자는 초기 뼈대를 잡는 대신, 생성된 코드가 비즈니스 로직에 맞는지 리뷰하고 다듬는 데 집중합니다.
여러 파일을 함께 만든다는 점에서도 작업 순서를 나눌 이유가 있습니다. 한 번의 프롬프트로 모두 처리하려 하면 파일 사이의 의존성이 엉켜 완성도가 떨어질 수 있기 때문입니다. Skills로 작업을 쪼개면 AI가 한 번에 한 역할에 집중하도록 해 결과물의 신뢰도를 높일 수 있습니다. 프로젝트 테스트 패턴에 맞춘 테스트 생성, Git 변경사항을 분석한 PR(MR) 본문 작성, 컴포넌트 분리나 훅 추출 같은 리팩토링도 스킬로 구성할 작업의 예입니다.
훅 하나를 위해 추려 낸 JSON
작업 흐름을 정해도 탐색 비용은 남았습니다. 특정 도메인의 API 훅을 만들도록 요청하면 AI가 관련 파일을 찾아 읽는 동안, 훅 생성에 직접 필요하지 않은 import 문과 로깅, 에러 처리까지 컨텍스트에 들어옵니다. 반복적인 tool call은 응답을 늦추고, 잘못된 코드를 참고하면 환각을 일으킬 가능성도 커집니다.
팀은 탐색 앞에 전처리 스크립트를 두었습니다. 스크립트가 파일을 먼저 읽고 코드 생성에 필요한 메타데이터만 JSON으로 추려 AI에게 전달하는 방식입니다. userApi.ts의 내부 구현과 수백 줄에 이르는 queryKeys.ts 설정을 읽는 대신, 훅 생성에 쓸 정보만 받도록 바꿨습니다.
전달하는 정보는 엔드포인트 GET /users/:id, 쿼리 키 queryKeys.user(id), API 메서드 UserAPI.getUser, 매개변수 id와 그 타입 string입니다.
전처리는 주로 Node.js 스크립트로 구현했습니다. 로컬 파일 시스템을 탐색하고 정규식으로 클래스명과 메서드명 등을 추출하거나, openapi-typescript 같은 도구로 API 명세를 타입 정의 파일로 변환한 뒤 정제된 데이터를 전달했습니다. AI는 원본 코드 탐색을 생략하고 생성 작업에 집중합니다. 팀에서는 불필요한 코드를 읽다가 길을 잃는 문제를 예방하고 일관된 결과를 안정적으로 얻을 수 있게 됐다고 설명합니다.
5개 도메인에서 AI 자율 탐색 방식과 스크립트 요약 방식을 비교한 결과, AI가 처리해야 할 데이터량은 평균 96.5% 줄었습니다. 아래 표는 도메인 규모별 데이터량과 호출 횟수입니다.
전처리 전후의 데이터량과 호출 횟수
| 도메인 규모 | 자율 탐색 | 스크립트 요약 | 절감률 | 호출 횟수 |
|---|---|---|---|---|
| 대규모 (API 11개) | 41,944 bytes | 1,763 bytes | 95.8% | 4회에서 1회 |
| 중규모 (API 4개) | 29,386 bytes | 668 bytes | 97.7% | 4회에서 1회 |
| 소규모 (API 2개) | 9,749 bytes | 539 bytes | 94.5% | 4회에서 1회 |
토큰 절감량은 추정치입니다. 영어 텍스트 기준 1토큰 약 4바이트로 환산했을 때, 1회 작업당 평균 약 6,800 토큰을 줄일 것으로 예상했습니다. 실제 토큰 사용량은 한글과 영문 코드의 비율, 사용하는 LLM의 토크나이저에 따라 달라집니다. 데이터량을 줄이는 효과 역시 프로젝트 구조와 데이터 크기에 따라 달라질 수 있습니다.
역할별로 작업을 나누는 다중 에이전트 환경
여기서 더 나아간 확장 방향으로는 다중 에이전트 환경을 고려할 수 있습니다. 역할별로 특화된 하위 에이전트에 작업을 위임하거나, 작업을 fork해 파이프라인을 병렬로 처리하는 방식입니다. 이는 이번 적용 결과에 이어 제안한 확장 가능성입니다.
함께 소개한 참고 리소스는 Agents.md와 Agent Skills입니다. 각각 에이전트에 맥락을 제공하는 표준과 에이전트 기능을 확장하는 모듈 명세입니다.