AI 코딩 에이전트를 위한 Harness Engineering이란?

안녕하세요. 일본을 좋아하는 한국인 주니어 개발자입니다.

일본어는 아직 공부 중이라 부자연스러운 표현이 있더라도 양해 부탁드립니다.

최근 Cursor / Claude Code / Codex와 같은 AI 코딩 에이전트(AI coding agent)를 자주 사용하고 있습니다.

편리하지만, 매번 같은 문제가 있었습니다.

새로운 세션을 열 때마다 다시 똑같은 내용을 설명해야 한다는 점입니다.

예를 들어,

이 프로젝트에서는 npm을 사용함
생성된 파일은 편집하지 말 것
변경 후에는 이 체크를 실행할 것
...

이런 규칙들을 매번 프롬프트(prompt)로 설명하곤 했습니다.

하지만 이것은 조금 이상하다고 생각했습니다.

프로젝트의 규칙인데, 왜 채팅창 안에만 존재하는가?

제가 이해하는 Harness Engineering은 다음과 같은 사고방식입니다.

AI 에이전트(AI agent)가 작업하기 쉽도록,

프로젝트 측에 규칙·제약·체크·기억을 준비해 두는 것.

즉, 에이전트를 매번 프롬프트만으로 제어하는 것이 아니라, 리포지토리(repository) 자체를 에이전트가 작업하기 쉬운 환경으로 만드는 것이라는 생각입니다.

저는 다음과 같이 정리하고 있습니다.

Harness = Instructions + Constraints + Feedback + Memory + Evaluation

각각을 간단히 말하자면,

Instructions: 에이전트가 읽는 규칙
Constraints: 지켜야 할 제약
Feedback: 테스트나 체크
...

AI 에이전트는 세션을 넘어가면 이전 대화를 잊어버리는 경우가 있습니다.

물론 긴 프롬프트를 작성하면 어느 정도는 대응할 수 있습니다.

하지만 프롬프트에만 의존하면 문제가 발생합니다.

• 새로운 세션에서 매번 설명이 필요함
• 사람이 설명을 잊어버림
• 에이전트가 같은 실수를 반복함
• 과거의 판단이 채팅 속에 파묻힘
• 체크해야 할 사항이 모호해짐

특히 제가 곤란했던 점은 "실패가 남지 않는다"는 것이었습니다.

한 번 버그를 고쳤더라도 그 이유가 리포지토리(repository)에 남아 있지 않다면, 다음 에이전트는 또다시 같은 길을 돌아갈지도 모릅니다.

이 사고방식을 시험해 보기 위해, harness-starter-kit라는 작은 스타터 키트(starter kit)를 만들었습니다.

GitHub:

이것은 자동 인스톨러라기보다는, 타겟 리포지토리(target repository)에 맞춰 최소한의 harness를 추가하기 위한 레퍼런스 키트(reference kit)입니다.

중요한 것은 타겟 리포지토리가 진실의 원천(source of truth)이어야 한다는 점입니다.

즉, 스타터 키트의 템플릿을 그대로 복사하는 것이 아니라,

기존 구조
기존 패키지 매니저 (package manager)
기존 문서 (docs)
...

를 우선시합니다.

그 위에 필요한 것들만 추가합니다.

예를 들어, 다음과 같은 것들입니다.

AGENTS.md
docs/decisions/
docs/failures/
...

AGENTS.md는 에이전트가 가장 먼저 읽는 프로젝트 규칙입니다.

예를 들어,

어떤 명령어를 실행할 것인가
어떤 파일을 편집해서는 안 되는가
어떤 디렉토리에 무엇을 둘 것인가
...

를 작성합니다.

docs/decisions/에는 구조적인 판단을 남깁니다.

예를 들어,

왜 이 프레임워크 (framework)를 사용하는가
왜 이 API 경계 (boundary)로 설정했는가
왜 mock fallback을 남겨두는가

와 같은 판단들입니다.

docs/failures/에는 반복하고 싶지 않은 실패를 남깁니다.

다만, 실패를 적는 것만으로는 부족하다고 생각합니다.

실패에는 가능한 한 탐지(detection) / 방지(prevention)를 연결합니다.

즉,

어떤 테스트(test)로 탐지할 수 있는가
어떤 픽스처(fixture)로 재현할 수 있는가
어떤 스모크 체크(smoke check)를 실행할 것인가
...

까지 작성하도록 합니다.

이 키트를 제 실제 프로젝트에서 테스트하고 있습니다.

하나는 Django의 작은 프로젝트입니다.

여기서는,

scripts/check_harness.py
.github/workflows/harness-check.yml
docs/decisions/
...

를 사용하여 local check (로컬 체크)와 CI check (CI 체크) 흐름을 만들었습니다.

또 다른 하나는 Next.js 프로젝트입니다.

이것은 외부 API를 다루는 project (프로젝트)로, TAGO / Gumi BIS / TMAP / OpenRouteService 등을 사용하고 있습니다.

이 project (프로젝트)에서는 특히 failure memory (실패 메모리)가 유용했습니다.

예를 들어, 어떤 API endpoint (엔드포인트)에서는 parameter (파라미터) 명의 casing (케이스)이 중요했습니다.

nodeid

를 사용해야 하는 곳에서,

nodeId

를 사용하면, provider (프로바이더)가 stop filter (스톱 필터)를 무시하게 되어 결과적으로 rate limit (요청 제한)에 가까운 문제가 발생했습니다.

이 실패는 단순한 메모가 아니라 docs/failures/에 기록하고, 관련된 test (테스트)로도 연결했습니다.

흥미로웠던 점은 npm run check:harness가 실패했을 때입니다.

처음에는 나쁜 일처럼 보였습니다.

하지만 실제로는 harness (하네스)가 문제를 일찍 찾아준 사례였습니다.

원인은 app source (앱 소스)가 아니라, Next.js의 generated type artifact (생성된 타입 아티팩트)였습니다.

.next/ 이하의 생성 파일을 직접 편집하는 대신, typecheck (타입 체크) 전에 next typegen을 실행하도록 했습니다.

그리고 그 판단을 docs/decisions/에, 실패를 docs/failures/에 남겼습니다.

이전 같았으면 이것은 채팅 속에서 끝났을지도 모릅니다.

다음부터는 next typegen을 먼저 실행하자

하지만 지금은 repository (레포지토리)에 남아 있습니다.

솔직히 말하면, 이 kit (키트)가 agent (에이전트)를 정말로 좋게 만들었다고 증명할 수 있는 것은 아닙니다.

Harness Doctor와 같은 진단은 repository (레포지토리)에 durable evidence (지속적인 증거)가 있는지 확인할 수는 있습니다.

예를 들어,

AGENTS.md가 있는가
check script (체크 스크립트)가 있는가
decision / failure docs (결정/실패 문서)가 있는가
...

등입니다.

하지만 그것이 agent effectiveness (에이전트 효과성) 그 자체는 아닙니다.

정말로 알고 싶은 것은,

agent (에이전트)가 잘못된 파일을 편집하지 않게 되었는가
같은 실패를 반복하지 않게 되었는가
reviewer (리뷰어)의 재작업이 줄었는가
...

입니다.

이것은 task outcome (태스크 결과)을 더 수집해야 알 수 있습니다.

그래서 지금 저의 결론은 이것입니다.

harness (하네스)는 agent (에이전트)를 마법처럼 똑똑하게 만드는 것이 아닙니다.

하지만 실패를 빨리 찾아내고, repository (레포지토리)에 기억으로서 남기는 데 도움을 줍니다.

AI coding agent (AI 코딩 에이전트)를 사용할 때, prompt (프롬프트)는 중요합니다.

하지만 프로젝트의 규칙을 매번 프롬프트에만 두는 것은 약하다고 생각했습니다.

그래서 저는 repository (레포지토리) 측에 harness (하네스)를 만드는 방향을 시도하고 있습니다.

규칙을 AGENTS.md에 남긴다
판단을 docs/decisions에 남긴다
실패를 docs/failures에 남긴다
...

이렇게 함으로써, 새로운 agent session (에이전트 세션)에서도 적어도 project context (프로젝트 컨텍스트)를 다시 읽을 수 있는 장소가 생깁니다.

아직 실험 중이지만, Django와 Next.js 프로젝트에서 dogfood (도그푸딩)하며 개선하고 있습니다.

GitHub:

Cursor / Claude Code / Codex 등을 사용하고 계신 분들의 입장에서, 이 방향성이 유용할지 피드백을 주시면 감사하겠습니다.

저는 아직 주니어 개발자이기 때문에, 경험이 있는 분들의 의견을 들어보고 싶습니다.