💡 Harness Engineering은 AI agent를 직접 통제하는 거대한 시스템을 새로 만드는 일이 아니라, 이미 있는 도구와 규칙을 조합해 안전한 작업 흐름을 만드는 일에 가깝습니다.

AI coding agent를 쓰다 보면 어느 순간 비슷한 생각을 하게 됩니다.

"작업 전에 계획을 세우게 해야겠다."
"테스트를 돌리고 실패하면 고치게 해야겠다."
"리뷰어 역할을 따로 둬야겠다."
"반복되는 실수는 다음 작업에 재사용할 수 있게 기록해야겠다."

이 생각 자체는 맞습니다. 하지만 여기서 곧바로 자체 agent pipeline을 만들기 시작하면 금방 복잡해집니다.

브레인스토밍, 구현 계획, TDD, 코드 리뷰, 보안 리뷰, 검증, 메모리 기록, phase 관리, 실패 시 중단 기준까지 직접 만들려고 하면 정작 제품 개발보다 agent 운영 프레임워크를 만드는 데 시간을 더 쓰게 됩니다.

그래서 저는 하네스 엔지니어링을 이렇게 보는 편이 현실적이라고 생각합니다.

바퀴를 재발명하지 말고, 이미 있는 하네스를 비교해서 조합하자.

Harness Engineering이란 무엇인가

Harness Engineering은 AI agent가 자율적으로 일하되, 프로젝트가 정한 규칙과 경계 안에서 움직이도록 만드는 작업 방식입니다.

프롬프트 엔지니어링이 "AI에게 어떻게 말할 것인가"에 가깝다면, 하네스 엔지니어링은 "AI가 어떤 절차와 제약 안에서 일하게 할 것인가"에 가깝습니다.

예를 들어 프롬프트는 이렇게 말할 수 있습니다.

기존 auth hook 패턴을 따라 로그인 기능을 추가해줘.
로딩, 실패, 비활성 상태를 처리하고 기존 API wrapper를 사용해줘.

하지만 하네스는 여기서 한 단계 더 나아갑니다.

1. 관련 파일과 프로젝트 규칙을 먼저 읽는다.
2. 작업 범위를 정리한다.
3. 필요한 경우 구현 계획을 만든다.
4. 코드를 수정한다.
5. lint, test, build 중 필요한 검증을 실행한다.
6. 실패하면 로그를 읽고 수정한다.
7. diff를 리뷰한다.
8. 반복 방지 가치가 있는 실수는 lessons에 남긴다.

프롬프트는 요청이고, 하네스는 작업 시스템입니다.

다만 이 시스템을 모두 직접 만들 필요는 없습니다. Codex나 Claude Code 같은 agentic coding system에는 기본 실행 하네스가 있고, Cursor 같은 AI IDE에는 에디터 중심의 보조/agent 경험이 있습니다. 여기에 Superpowers나 G-Stack 같은 별도 workflow set을 얹을 수도 있습니다. 팀은 이 중 필요한 것을 골라 쓰면 됩니다.

도구마다 맡는 층위가 다르다

AI 개발 도구들은 겉으로 보면 모두 비슷해 보입니다. 코드베이스를 읽고, 파일을 수정하고, 터미널 명령을 실행하고, 테스트 결과를 보고 다시 고치는 것처럼 보입니다.

하지만 실제로는 도구의 성격이 다릅니다.

그래서 "정답 도구"를 하나 고르기보다, 어떤 층위를 보강하려는지 먼저 보는 편이 낫습니다.

Codex나 Claude Code처럼 agent에게 작업을 통째로 맡기는 흐름이 맞는 사람도 있고, Cursor처럼 IDE 안에서 계속 맥락을 보며 함께 수정하는 흐름이 더 편한 사람도 있습니다. 이 둘은 경쟁 도구이기도 하지만, 사용 경험만 보면 조금 다른 범주의 도구입니다.

모델과 도구에 따라 제공되는 하네스, skill set, rule 체계도 달라집니다. 어떤 환경에서는 Superpowers 같은 skill 묶음이 자연스럽고, 어떤 환경에서는 Claude Code의 CLAUDE.md와 slash command 중심 흐름이 더 편할 수 있습니다. 또 어떤 팀은 Cursor rules나 GitHub Copilot coding agent처럼 IDE/협업 도구에 붙은 방식을 더 자연스럽게 받아들일 수도 있습니다.

핵심은 하나입니다.

특정 도구를 정답으로 외우기보다, 내가 맡기려는 작업에 어떤 하네스가 필요한지 먼저 보는 것.

직접 만들 필요가 없는 것들

AI agent workflow를 직접 만들고 싶어지는 이유는 이해됩니다. 팀마다 코드베이스가 다르고, 검증 명령도 다르고, 리뷰 기준도 다르기 때문입니다.

하지만 아래 같은 것들은 대개 직접 처음부터 만들 필요가 없습니다.

• 작업 전 계획 루프
• 구현 후 검증 루프
• 실패 로그를 읽고 다시 수정하는 루프
• 코드 리뷰 체크
• 보안/권한 관점 리뷰
• 반복 실수 기록
• phase 단위 작업 분해
• 작업 상태 추적

이미 많은 도구가 이 문제를 각자의 방식으로 풀고 있습니다.

예를 들어:

• Codex, Claude Code는 agent에게 작업을 맡기고 코드 수정과 검증 실행까지 이어가는 환경을 제공합니다.
• Cursor 같은 AI IDE는 에디터 중심의 탐색, 수정, 리뷰 경험을 제공합니다.
• Superpowers 같은 skill set은 planning, debugging, verification 같은 개발 루프를 제공합니다.
• G-Stack류의 접근은 여러 역할 관점으로 계획이나 결과물을 검토하게 도와줍니다.
• Compound Engineering류의 접근은 반복 실수를 lessons로 남겨 다음 작업에 재사용하게 합니다.
• Paperclip이나 issue board는 복잡한 작업 상태를 채팅창 밖에서 관리하게 해줍니다.

이 도구들을 모두 써야 한다는 뜻은 아닙니다. 오히려 반대입니다. 이미 있는 선택지가 많으니, 필요한 부분만 골라 쓰면 됩니다.

도구를 볼 때의 기준

도구를 비교할 때 "어떤 모델이 더 똑똑한가"만 보면 부족합니다.

실제 작업에서는 아래 기준이 더 중요할 때가 많습니다.

마지막 항목도 중요합니다.

아무리 좋은 도구라도 손에 안 맞으면 오래 못 씁니다. 반대로 완벽하지 않아도 내 작업 리듬에 잘 맞으면 생산성이 크게 올라갑니다.

결국 도구 선택은 어느 정도 기호의 영역입니다. Codex와 Claude Code 같은 agentic coding tool을 비교해보고, Cursor 같은 AI IDE도 함께 써보면서 본인이 피로하지 않게 계속 쓸 수 있는 흐름을 찾는 것이 좋습니다.

하네스 도구는 레이어로 보면 편하다

도구 이름을 하나씩 외우기보다, 역할별 레이어로 보면 이해하기 쉽습니다.

1. 실행 레이어
   - 코드 읽기
   - 파일 수정
   - 터미널 실행
   - diff 확인

2. workflow 레이어
   - 계획
   - 구현
   - 디버깅
   - 검증
   - 리뷰

3. 프로젝트 규칙 레이어
   - AGENTS.md
   - CLAUDE.md
   - docs/ai/*
   - Cursor rules
   - Copilot instructions

4. 자동 검증 레이어
   - lint
   - typecheck
   - test
   - build
   - CI

5. 학습/상태 레이어
   - lessons
   - memory
   - issue board
   - phase file
   - 작업판

Codex나 Claude Code는 주로 실행 레이어와 기본 workflow 레이어를 제공합니다. Cursor는 IDE 안에서 실행 레이어 일부와 프로젝트 규칙 레이어를 에디터 경험에 녹여냅니다. Superpowers, G-Stack, Compound 같은 것들은 workflow, 리뷰, 학습 레이어를 보강합니다. AGENTS.md, CLAUDE.md, Cursor rules는 프로젝트 규칙 레이어에 가깝습니다. lint, test, CI는 자동 검증 레이어입니다.

이렇게 나눠보면 특정 도구 하나에 모든 것을 기대하지 않게 됩니다.

내가 필요한 것이 실행 환경인지, 계획 루프인지, 리뷰 관점인지, 반복 실수 기록인지 먼저 보고 그에 맞는 도구를 붙이면 됩니다.

프로젝트별로 직접 해야 하는 일

기존 하네스를 쓴다고 해서 할 일이 없어지는 것은 아닙니다.

외부 도구가 대신 알 수 없는 것들이 있습니다.

• 이 repo에서 따라야 할 API 호출 패턴
• generated 파일 처리 방식
• module boundary
• 금지된 라이브러리나 명령
• 검증 명령
• PR 제목과 본문 규칙
• 보안과 민감 정보 기준
• 작은 작업과 큰 작업을 나누는 기준

이런 정보는 프로젝트 안에 있어야 합니다.

예를 들어 "GraphQL generated 파일은 직접 수정하지 말고 .gql operation을 수정한 뒤 codegen을 실행한다" 같은 규칙은 도구가 자동으로 알 수 없습니다. 팀이 문서로 남기고, 가능하면 lint나 CI로 검증해야 합니다.

그래서 이상적인 구조는 다음에 가깝습니다.

범용 하네스는 도구에서 빌려 쓴다.
프로젝트 규칙은 직접 문서화한다.
중요한 규칙은 자동 검증으로 만든다.
반복 실수는 lessons로 남긴다.

바퀴를 다시 만들 필요는 없지만, 우리 프로젝트의 도로 상태는 우리가 알려줘야 합니다.

작게 시작하는 방법

처음부터 복잡한 agent platform을 만들 필요는 없습니다.

개인이나 작은 팀이라면 아래 정도로 시작해도 충분합니다.

1. Codex, Claude Code 같은 agentic coding tool을 1~2개 직접 써본다.
2. Cursor 같은 AI IDE도 함께 써보고 작업 위치와 사용감 차이를 비교한다.
3. 각 도구의 instruction file, rules, skill set이 어떻게 다른지 비교한다.
4. 프로젝트 규칙은 AGENTS.md, CLAUDE.md, docs/ai/* 중 팀에 맞는 위치에 둔다.
5. 자주 쓰는 검증 명령을 명확히 적는다.
6. 큰 작업에만 planning/review workflow를 강하게 적용한다.
7. 반복되는 실수는 lessons나 checklist로 남긴다.

중요한 것은 모든 도구를 한 번에 도입하는 것이 아닙니다.

먼저 내 작업에서 자주 실패하는 지점을 봐야 합니다.

• 계획 없이 바로 구현해서 문제가 생기는가?
• 검증을 자주 빼먹는가?
• 리뷰에서 같은 지적이 반복되는가?
• UI 상태나 edge case가 자주 빠지는가?
• 큰 작업의 상태를 채팅창에서 잃어버리는가?

문제가 계획이라면 planning workflow를 보강하고, 검증이라면 verification loop를 보강하고, 반복 실수라면 lessons를 보강하면 됩니다.

하네스는 도구 수집이 아니라 문제 해결입니다.

하네스를 과하게 쓰지 않기

하네스가 중요하다고 해서 모든 작업에 무거운 절차를 적용하면 안 됩니다.

작은 작업에는 작은 하네스면 충분합니다.

예를 들어:

• 문구 수정
• 단일 파일 문서 수정
• import 정리
• 좁은 UI 스타일 수정
• 기존 패턴을 그대로 따르는 작은 버그 수정

이런 작업에 PRD, architecture review, multi-agent review, phase file까지 적용하면 배보다 배꼽이 커집니다.

반대로 아래 작업은 더 강한 하네스가 필요합니다.

• 결제, 권한, 인증
• DB schema 변경
• 대규모 UI flow 변경
• 외부 API 연동
• 보안과 개인정보가 걸린 작업
• 여러 agent가 나눠서 해야 하는 작업

하네스는 무조건 무겁게 만드는 장치가 아닙니다. 작업 위험도에 맞게 절차의 무게를 조절하는 장치입니다.

정리

Harness Engineering을 처음 들으면 거대한 agent framework를 직접 만들어야 할 것처럼 느껴질 수 있습니다. 하지만 실무적으로는 반대에 가깝습니다.

이미 쓸 수 있는 하네스는 많습니다.

Codex와 Claude Code 같은 agentic coding tool은 작업을 위임하고 실행하는 환경을 제공합니다. Cursor 같은 AI IDE는 에디터 안에서 개발자가 맥락을 보며 AI와 함께 수정하는 경험을 제공합니다. Superpowers 같은 skill set은 개발 작업 루프를 보강합니다. G-Stack류 접근은 역할 기반 리뷰를 도와줍니다. Compound Engineering류 접근은 반복 실수를 다음 작업의 자산으로 바꿉니다. Paperclip이나 issue board는 복잡한 작업 상태를 관리하게 해줍니다.

다만 이 중 하나가 정답은 아닙니다. 모델별, 도구별, 팀별로 맞는 하네스는 달라질 수 있습니다.

그래서 중요한 것은 특정 도구를 외우는 것이 아니라, 이런 질문을 던지는 것입니다.

이 작업에는 어떤 실행 환경이 필요한가?
계획이 필요한가, 바로 수정해도 되는가?
검증은 무엇으로 할 수 있는가?
리뷰 관점이 더 필요한가?
반복 실수로 남길 가치가 있는가?
작업 상태를 채팅 밖에 남겨야 하는가?

좋은 하네스는 결국 이런 구조에 가깝습니다.

범용 하네스는 빌려 쓴다.
프로젝트 규칙은 직접 쓴다.
검증은 자동화한다.
도구 선택은 작업 성격과 본인의 기호에 맞춘다.

AI agent 시대에 중요한 것은 더 긴 프롬프트를 쓰는 능력만이 아닙니다. 이미 있는 도구를 적절히 비교하고, 필요한 만큼만 조합하고, 우리 프로젝트에 맞는 최소한의 울타리를 설계하는 능력입니다.

참고 자료

• AGENTS.md format
• Claude Code memory and CLAUDE.md
• Cursor Rules
• GitHub Copilot repository custom instructions
• Gemini CLI documentation