하네스 엔지니어링(harness engineering)으로 팀 맞춤형 AI 환경 구축하기

Rules와 Skills의 명확한 분리

블로그에서 제시한 .cursor/rules와 .cursor/skills 구조가 인상 깊었다. 나는 그동안 skills를 정의를 하고 사용하더라도 코드 작성 rule에 대해서는 AI에게 지시할 때마다 마크다운 파일에 규칙을 정리해두고 첨부(@ 사용)를 통해 인지하도록 했는데, IDE 레벨에서 프로젝트 구조에 따라 자동으로 컨텍스트를 주입한다는 게 확실히 체계적이다. 특히 globs 옵션으로 특정 경로에서만 규칙을 활성화하는 부분에서 새롭게 한가지 깨달았다. src/queries/**/*.ts 파일을 건드릴 때만 React Query 규칙을 주입하면, 불필요하게 전체 컨텍스트를 차지하지 않으니 토큰 비용도 아끼고 응답도 빨라지겠구나!!!

생각해보니 LLM이 이미 아는 내용(React 기본 문법 같은 것)을 Rules에 넣지 말라는 조언도 공감되었다. AI를 사용하던 초창기에 "다 적어놓으면 더 잘 알지 않을까?" 하고 중복해서 넣었던 경험이 있는데, 오히려 노이즈가 되어 AI를 헷갈리게 만들었던 것이다. 프로젝트 특화 규칙만 담되, 그것은 명확하게 담는 것이 핵심이지 않을까?

데이터 정제가 핵심!

가장 집중해서 읽었던 부분은 전처리 스크립트를 활용한 컨텍스트 최적화 부분이었다. AI가 프로젝트를 [탐색]하게 두는 대신, Node.js 스크립트로 메타데이터만 추출해서 JSON으로 던져주는 방식. 토큰 사용량이 96%나 줄었다는 수치가 정말 놀라울 따름이다.

나도 AI에게 기존 코드베이스를 참고하라고 할 때, 가끔 import 문이나 로깅 코드, 에러 핸들링 같은 부분까지 쓸데없이 읽어서 맥락을 낭비하는 걸 봐왔다. "UserAPI.getUser"만 필요한데 파일 전체를 다 긁어다 context window에 담아버리니까! 이런 것을 미리 스크립트로 {"className": "UserAPI", "methods": ["getUser"]} 이런 식으로 정제해서 주면, AI는 탐색 시간도 없이 바로 생성에만 집중하겠지?

이건 마치 백엔드에서 데이터베이스 쿼리할 때 SELECT * 말고 필요한 컬럼만 SELECT 하는 것과 비슷한 느낌이든다. AI도 결국 context window가 무한하지 않기 때문에, [쿼리 튜닝]이 필요한 셈이다. 이 부분은 바로 내 프로젝트에 적용해야겠다. 특히 레거시 코드베이스가 큰 프로젝트에서 AI가 파일을 뒤지다가 엉뚱한 코드를 참고해서 hallucination 일으키는 걸 막을 수 있을 것 같은 느낌이 든다.

Skills의 자동화 파이프라인

Swagger URL을 넣으면 타입과 Mock 데이터, API 클래스, React Query 훅, 테스트 코드까지 한 번에 생성하는 파이프라인이 있다는게 부러웠다. 보일러플레이트 코드 작성은 정말 영혼 없는 작업인데, 이걸 skills로 만들어두면 개발자는 비즈니스 로직만 검토하면 되니 생산성이 확실히 오르지 않을까?

다만 한 가지 걱정되는 점은 이런 스킬을 만드는 것 자체가 꽤나 시간이 드는 작업이라는 것이다. 작은 스타트업이나 개인 프로젝트에서는 "스킬 만드는 시간에 그냥 내가 코딩하지 뭣하러 만들고 있어?"라는 생각이 들 수도 있다. 하네스 엔지니어링의 진입장벽이 꽤 높지 않을까 하는 우려다. 팀 규모가 어느 정도 되고 프로젝트가 장기적으로 운영될 때만 ROI가 나오는 구조일 수도 있다.

팀 컨벤션과 AI의 표준화

[누가 질문하든 팀 컨벤션을 준수하는 일관된 코드 산출]이라는 부분도 꽤나 공감됐다. 우리 팀도 AI 쓰면서 "A는 이렇게 시키고 B는 저렇게 시켜서" 코드 스타일이 달라지는 경우가 굉장히 많이 있었다. PR 리뷰할 때 "AI가 이렇게 짜던데요?"라고 하면서 스타일이 엉망인 코드가 올라오는 게 굉장히 불편했다. Rules로 표준을 강제하면 코드 리뷰에서 스타일 논쟁은 줄어든다는 장점이 명확하다.

참고

• 하네스 엔지니어링(harness engineering)으로 팀 맞춤형 AI 환경 구축하기 - 우아한형제들 기술블로그