4. harness가 agent를 강하게 만들었다고는 말할 수 없다. 하지만 PR을 통해 agent work의 경계, 검증 결과, 재사용

안녕하세요. 한국 출신 주니어 개발자입니다.

일본어는 도구의 도움을 받으며 다듬고 있습니다. 조금 부자연스러운 표현이 있더라도 양해 부탁드립니다.

지금까지의 3편의 기사에 이어, 이번에는 4번째입니다.

이전 기사들에서는 주로 두 가지 내용을 다루었습니다.

첫 번째는 다음 내용입니다.

harness-starter-kit

을 실제 프로젝트에 도입하여, 에이전트(agent)가 템플릿을 무분별하게 복사하지 않는지, 구조를 망가뜨리지 않는지, 아무도 유지보수하지 않는 docs를 늘리기만 하는 것은 아닌지 살펴보았습니다.

두 번째는 다음 내용입니다.

harness는 반드시 에이전트를 즉시 똑똑하게 만드는 것은 아니다.

보다 현실적인 가치는 에러를 빠르게 드러내고, 리포지토리(repository)에 그 실패를 학습시키는 데 있다.

이번에는 그 다음 단계로 나아가 보겠습니다.

만약 harness가 도움이 된다고 한다면, 어떻게 판단해야 할까요?

감각만으로는 판단할 수 없습니다.

Harness Doctor

의 점수만으로도 불충분합니다.

어떤 PR(Pull Request)이 잘 진행된 것처럼 보인다고 해서, 즉시 다음과 같이 말할 수도 없습니다.

agent effectiveness(에이전트 효과성)가 올라갔다.

그래서 이번에는 실제 dogfood PR을 하나 사용하여, 작은 effectiveness tracking(효과성 추적)을 시도해 보았습니다.

먼저 결론부터 말씀드리면 다음과 같습니다.

이 PR만으로는 harness가 에이전트를 강하게 만들었다고 증명할 수 없습니다.

다만, 향후 비교를 위한 initial benchmark(초기 벤치마크)는 되었습니다.

이번에 살펴본 것은 today-bus의 dogfood PR입니다.

프로젝트 이름은 다음과 같습니다.

today-bus

이는 Next.js 프로젝트이며, 목적은 다음과 같습니다.

구미역 열차 시간에 맞추기 위해 언제 출발해야 하는지, 어느 버스 정류장까지 걸어가야 하는지, 어떤 버스를 타야 하는지를 계산한다.

이번에 평가한 PR은 다음과 같습니다.

baskduf/today-bus#2

merge commit은 다음과 같습니다.

85312c181b294c3419dd0813820c10977dd5005b

평가 윈도우(evaluation window)는 다음과 같습니다.

2026-06-04 dogfood PR

이것은 정식 실험이 아닙니다.

더 정확하게는 다음과 같은 위치를 차지합니다.

harnessed-only initial benchmark

즉, pre-harness baseline(harness 도입 전 기준점)은 없습니다.

따라서 "이전보다 얼마나 좋아졌는가"라고는 말할 수 없습니다.

말할 수 있는 것은 다음뿐입니다.

이미 harness를 채택하고 있는 이 PR에서는 에이전트의 태스크 경계, 검증 결과, 알려진 실패의 재발 상황을 나중에 다시 검토할 수 있는 evidence(증거)로서 기록할 수 있었다.

이번에 저에게 중요했던 점이 하나 있습니다.

모든 agent run(에이전트 실행)을 effectiveness measurement(효과성 측정)에 포함시켜서는 안 된다는 점입니다.

TodayBus에는 setup outcome record가 있었습니다.

dogfood-effectiveness-20260604-160333.yaml

하지만 이것은 product-task metrics(제품 태스크 지표)에서 제외했습니다.

이유는 그것이 구체적인 제품 태스크가 아니었기 때문입니다.

그보다는 setup / tracking을 위한 준비 작업에 가까웠습니다.

다음 조건들이 부족했습니다.

• concrete product task (구체적인 제품 태스크)
• expected boundary (예상된 경계)
• known failure mode (알려진 실패 모드)
• required verification commands (필요한 검증 명령)

이러한 setup run까지 포함하면 수치는 좋아 보일 수 있습니다.

하지만 그 수치의 의미는 약해집니다.

그래서 이번에는 실제 product-task outcome(제품 태스크 결과)만을 집계했습니다.

이 구분은 매우 유용했습니다.

이전 같았으면 저는 이렇게 말했을지도 모릅니다.

"이 PR에는 agent task가 몇 개 있으니까 전부 넣어두자."

지금은 조금 더 신중합니다.

비교 가능한 제품 태스크만을 effectiveness report(효과성 보고서)에 넣습니다.

setup, adoption, placeholder prompt는 기록해도 좋지만, 효과의 증거로서 함부로 다루지 않습니다.

이 PR에서는 최종적으로 3개의 task outcome을 집계했습니다.

첫 번째는 홈페이지 문구 조정입니다.

목적은 UI를 다시 만드는 것도, 제품의 동작을 바꾸는 것도 아닙니다.

페이지 상의 copy를 조금 더 이해하기 쉽게 만드는 것이었습니다.

기대되는 경계 (boundary)는 대략 다음과 같은 범위입니다.

• app page
• layout metadata
• search form copy
• task outcome record

흔히 발생하는 실패 모드 (failure mode)는 다음과 같습니다.

• 에이전트가 덤으로 UI를 다시 만든다
• 시각적 구조를 변경한다
• 제품의 동작을 변경한다
• task outcome 기록을 잊어버린다

최종 변경 사항은 주로 다음 파일에 집중되었습니다.

src/app/layout.tsx
src/app/page.tsx
src/components/today-bus/search-form.tsx
...

이 태스크는 검증을 통과했습니다.

두 번째는 planner의 empty-result fallback에 deterministic test를 추가하는 태스크입니다.

이는 TodayBus에 있어 중요한 태스크였습니다.

이 프로젝트는 외부 API에 의존하고 있지만, normal gate는 live API에 의존해서는 안 되기 때문입니다.

이 태스크의 경계는 다음과 같습니다.

• planner test
• task outcome record

흔히 발생하는 실패 모드는 다음과 같습니다.

• 테스트를 위해 제품 동작을 변경한다
• deterministic test 안에서 live API를 호출한다
• 덤으로 UI를 변경한다
• external provider의 문제를 local test에 섞는다

최종 변경 사항은 주로 다음 파일이었습니다.

tests/planner-branches.test.mjs
docs/effectiveness/task-outcomes/todaybus-002-empty-result-tests.yaml

이 태스크도 검증을 통과했습니다.

세 번째는 domain docs 내의 planner 용어를 정리하는 태스크입니다.

이는 docs-only task입니다.

기대되는 경계는 다음과 같습니다.

• domain docs
• task outcome record

흔히 발생하는 실패 모드는 다음과 같습니다.

• docs-only임에도 app code를 변경한다
• ADR의 내용을 중복시킨다
• 용어가 drift(표류)한다
• 덤으로 test나 implementation을 변경한다

최종 변경 사항은 다음 파일에 집중되었습니다.

docs/domain/glossary.md
docs/domain/tago-api.md
docs/domain/gumi-bis.md
...

이 태스크도 검증을 통과했습니다.

이번 report의 결과는 대략 다음과 같았습니다.

Metric	Result
Product-task outcomes counted	3
...

표만 보면 이렇게 말하고 싶어질지도 모릅니다.

"harness는 상당히 유효하다."

하지만 저는 그렇게 말하기에는 이르다고 생각합니다.

이유는 몇 가지 있습니다.

• pre-harness baseline이 없다
• PR이 하나뿐이다
• product task가 3개뿐이다
• reviewer가 비교적 명확한 경계와 failure mode를 제공했다
• human rework minutes를 기록하지 않았다
• prompt text / prompt hash를 안정적인 artifact로 저장하지 않았다

더 정확하게는 다음과 같이 말해야 합니다.

"이 PR은 initial benchmark를 만들었다."

경계 준수, first-pass verification, outcome record completeness를 기록했다.

다만, harness adoption이 agent effectiveness를 높였다는 것은 아직 증명하지 못했다.

이 결론은 화려하지 않습니다.

하지만 이 편이 더 정직하다고 생각합니다.

이전에 저는 PR을 볼 때 주로 다음 사항들을 보고 있었습니다.

• 코드가 올바른가
• 테스트 (tests)가 통과하는가
• 명백한 버그가 없는가
• 리뷰 코멘트 (review comment)에 대응할 필요가 있는가

하지만 이번 dogfood 이후, PR을 다른 각도에서도 바라보게 되었습니다.

PR은 agent work의 측정 단위 (measurement unit)가 될 수도 있습니다.

즉, PR에는 코드 차분 (diff)뿐만 아니라 다음과 같은 정보도 남길 수 있습니다.

• 이 태스크 (task)의 기대 경계 (expected boundary)는 무엇이었는가
• 에이전트가 실제로 변경한 파일은 무엇인가
• 잘못된 파일 수정 (wrong-file edit)이 있었는가
• 이미 알려진 실수 (known mistake)를 반복했는가
• 1차 검증 (first-pass verification)을 통과했는가
• 되돌려진 파일 (reverted files)이 있었는가
• 인간의 재작업 (human rework)은 0인가, 알 수 없음 (unknown)인가, 아니면 구체적으로 몇 분인가
• 이 결과 (outcome)를 효과성 보고서 (effectiveness report)에 포함해야 하는가

이러한 정보들이 채팅 로그에만 남아 있다면 금방 사라져 버립니다.

하지만 태스크 결과 기록 (task outcome records)으로서 리포지토리 (repository)에 두면, 나중에 비교할 수 있습니다.

예를 들어, 다음에 TodayBus에서 3개에서 5개 정도의 유사한 태스크를 실시했을 때, 다음과 같이 물을 수 있습니다.

• 잘못된 파일 수정 (wrong-file edits)은 여전히 0인가
• 1차 검증 (first-pass verification)을 유지하고 있는가
• 이미 기록한 TAGO / TMAP / 생성된 파일 (generated file)의 문제가 재발하지 않았는가
• 인간의 재작업 (human rework)이 줄어들고 있는가
• 어떤 harness rule이 정말로 도움이 되고, 어떤 것이 단순한 문서인지

이는 "이번 에이전트는 잘한 것 같다"라는 느낌보다 더 신뢰할 수 있습니다.

이번 작업에서 한 가지 더 확신한 것이 있습니다.

Harness Doctor

는 편리하지만, 에이전트 효과성 점수 (agent effectiveness score)는 아닙니다.

Doctor가 알려주는 것은, 리포지토리 (repo)에 다음과 같은 지속 가능한 증거 (durable evidence)가 있는지 여부입니다.

AGENTS.md

• 로컬 체크 (local checks)
• CI 힌트 (CI hints)
• 결정 기록 (decision records)
• 실패 기록 (failure records)
• 채택 보고서 (adoption report)
• 소스 추적 (source tracking)
• 효과성 계획 (effectiveness plan)

이것은 harness 건강 신호 (harness health signal)입니다.

하지만 Doctor는 다음 사항들을 알려주지 않습니다.

• 에이전트가 잘못된 파일을 변경하기 어려워졌는가
• 리뷰어의 재작업 (reviewer rework)이 줄었는가
• 알려진 실패 (known failure)의 재발이 줄었는가
• 1차 검증 (first-pass verification)이 통과하기 쉬워졌는가

이것들은 태스크 결과 (task outcome)와 효과성 보고서 (effectiveness report)를 통해 기록해야 합니다.

그래서 지금은 다음의 두 계층을 나누고 있습니다.

Harness health:
repo에 지속 가능한 규칙 / 체크 / 메모리 (durable rules / checks / memory)가 있는가
Agent effectiveness:
...

이번 보고서에서 계속 강조한 것도 바로 이 점입니다.

initial benchmark, not proof.

효과 향상을 증명할 수는 없습니다.

그럼에도 불구하고, 이 PR에는 몇 가지 좋은 신호가 있었습니다.

첫째, 에이전트가 태스크 경계 (task boundary)를 넘지 않았습니다.

3개의 태스크는 모두 대체로 기대 범위 내의 파일들만 변경했습니다.

둘째, 결정론적 테스트 (deterministic test)와 라이브 API (live API)의 경계를 유지할 수 있었습니다.

빈 결과 폴백 테스트 (empty-result fallback test)는 라이브 프로바이더 (live provider)에 의존하지 않았습니다.

셋째, 문서 전용 태스크 (docs-only task)가 구현 태스크 (implementation task)로 변하지 않았습니다.

domain terminology alignment는 부수적으로 앱 코드 (app code)를 변경하지 않았습니다.

넷째, 각 제품 태스크 (product task)가 태스크 결과 기록 (task outcome record)을 남겼습니다.

이를 통해 나중에 리뷰나 비교를 수행할 수 있는 재료가 마련되었습니다.

저에게 이것들은 최종 결론은 아닙니다.

다만, 앞으로 계속 추적할 수 있는 신호들입니다.

이번 tracking (추적)에서는 measurement (측정) 측면의 과제도 보였습니다.

첫 번째는, human rework (사람의 재작업)를 기록하지 않았다는 점입니다.

report (보고서)에는 다음과 같이 적었습니다.

Human rework minutes: Unknown

이는 0이라고 적는 것보다 정직한 표현입니다.

측정하지 않았으면서 비용이 들지 않은 척할 수는 없기 때문입니다.

다음으로 진지하게 비교하려면, reviewer (검토자)가 얼마나 많은 시간을 사용했는지도 기록해야 합니다.

두 번째는, prompt reference (프롬프트 참조)가 안정적이지 않았다는 점입니다.

report에는 prompt refs (프롬프트 참조)가 있습니다.

하지만 prompt text (프롬프트 텍스트)와 prompt hash (프롬프트 해시)를 안정적인 artifact (결과물)로서 저장하지 않았습니다.

이러면 두 개의 run (실행)이 정말로 비교 가능한지 판단하기 어려워집니다.

세 번째는, sample size (샘플 크기)가 작다는 점입니다.

하나의 PR, 세 개의 task (태스크)는 어디까지나 initial benchmark (초기 벤치마크)일 뿐입니다.

큰 결론을 내리기에는 부족합니다.

따라서 다음에 해야 할 일은 결과를 서둘러 홍보하는 것이 아니라, 더 많은 PR을 계속해서 기록하는 것입니다.

이전 같았으면 저는 이렇게 썼을지도 모릅니다.

harness-starter-kit는 agent effectiveness (에이전트 효과성)를 높인다.

지금은 그렇게 쓰지 않습니다.

오히려 다음과 같이 씁니다.

TodayBus PR #2에서는 harness를 통해 3개의 product-task outcomes (제품-태스크 결과)를 기록할 수 있었다.

3개의 태스크에서 wrong-file edits (잘못된 파일 수정)와 repeated known mistakes (알려진 실수 반복)는 관찰되지 않았으며, first-pass verification (초기 검증)은 3/3이었다.

다만, baseline (기준점)이 없고 샘플도 적으며, human rework (사람의 재작업)도 측정하지 않았기 때문에 이는 initial benchmark (초기 벤치마크)이며, effectiveness improvement (효과성 개선)의 증거는 아니다.

길고, 홍보 문구로서는 약합니다.

하지만 현시점에서 책임지고 말할 수 있는 것은 이 정도입니다.

저는 주니어 개발자라서 "자동화처럼 보이는 것"에 끌리기 쉽습니다.

하지만 dogfood (자사 제품 사용)를 계속하면서 점점 이렇게 생각하게 되었습니다.

정말로 중요한 것은 숫자를 예쁘게 보여주는 것이 아니다.

어떤 evidence (증거)가 어떤 결론을 뒷받침할 수 있는지를 스스로 알 수 있게 만드는 것이다.

Harness Doctor

의 점수가 높다는 것은 repo (저장소)의 harness evidence (harness 증거)가 비교적 잘 갖춰져 있음을 나타냅니다.

하지만 에이전트가 정말로 실수를 줄였다고는 말할 수 없습니다.

하나의 PR이 순조로웠다고 해서 그것만으로 harness가 유효하다고 할 수는 없습니다.

다만, 매번 PR에 task outcome (태스크 결과)을 남기면 조금씩 경향이 보이기 시작합니다.

여기에 제가 harness-starter-kit의 가치를 느끼는 이유가 있습니다.

이것은 마법이 아닙니다.

설치하면 끝나는 도구도 아닙니다.

오히려 다음과 같은 질문을 계속해서 던지게 만듭니다.

• 이번 agent task (에이전트 태스크)의 경계는 무엇인가
• 실제 변경 사항이 그 경계를 넘었는가
• 알려진 failure (실패)가 재발했는가
• 어떤 check (체크)를 실행했는가
• 어떤 check (체크)를 실행하지 않았는가
• 이번 결과는 나중에 비교할 수 있는가

이러한 질문 그 자체가 agent workflow (에이전트 워크플로우)를 더 유지보수하기 쉽게 만듭니다.

다음에는 몇 가지 사항을 계속해 나가고 싶습니다.

첫째, TodayBus에서 다음 3~5개의 product task (제품 태스크)를 계속해서 기록하겠습니다. 특히 외부 API, planner logic (플래너 로직), UI copy, domain docs (도메인 문서)와 같은 태스크들입니다.

둘째, human rework minutes (사람의 재작업 시간)를 기록하기 시작하겠습니다. 대략적인 값이라도 unknown (알 수 없음)보다는 도움이 됩니다.

셋째, 더 안정적인 prompt reference (프롬프트 참조)를 저장하겠습니다. 예를 들어 prompt text (프롬프트 텍스트), prompt hash (프롬프트 해시), 적어도 명확한 prompt summary (프롬프트 요약)입니다.

넷째, effectiveness report (효과성 보고서)와 task outcome template (태스크 결과 템플릿)을 더욱 개선하겠습니다. setup run (설정 실행), adoption run (채택 실행), product task (제품 태스크)가 서로 섞이지 않도록 하기 위해서입니다.

다섯째로, 다음의 두 가지를 계속해서 구분해야 합니다.

harness health != agent effectiveness

전자는 Doctor나 drift checks (드리프트 체크)를 통해 확인할 수 있습니다.

후자는 실제 task outcome (태스크 결과)를 통해 관찰해야 합니다.

GitHub:

Cursor / Claude Code / Codex와 같은 coding agent (코딩 에이전트)를 사용하면서,

"리포지토리 내의 규칙이나 체크가 정말로 에이전트의 작업에 도움이 되고 있는가"를 알고 싶은 분들은, 작게 시작하는 것이 좋다고 생각합니다.

처음부터 효과를 증명하려고 하지 마세요.

먼저, 다음 PR을 통해 에이전트가 실제로 무엇을 했는지 기록하십시오.

기록이 없다면, 비교할 수 없습니다.

비교가 없다면, 마지막에 남는 것은 감각뿐입니다.