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

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

이것은 harness-starter-kit 시리즈의 5번째 글입니다.

이 시리즈를 처음 읽으시는 분들은 이전 글들을 먼저 읽으시면 흐름을 이해하기 쉬울 것입니다.

• Cursor에게 매번 같은 지시를 반복하는 것이 힘들어져서, 규칙을 리포지토리(repository)에 남기는 OSS 키트를 만들었다
  https://blog.csdn.net/2604_96221454/article/details/161573772
• harness-starter-kit를 실제 프로젝트에 넣어 테스트해 보았다
  https://blog.csdn.net/2604_96221454/article/details/161632236
• harness-starter-kit는 마법이 아니다. 에러를 빠르게 드러내기 위한 것이다
  https://blog.csdn.net/2604_96221454/article/details/161657136
• 아직 harness가 agent를 강력하게 만들었다고는 말할 수 없다. 하지만 PR에서 agent work의 경계, 검증 결과, 재사용 가능한 증거를 기록하기 시작했다

이전 글들에서는 주로 다음과 같은 내용을 써왔습니다.

• 왜 harness-starter-kit를 만들었는가 - 왜 coding agent에게 매번 같은 프로젝트 규칙을 설명하고 싶지 않은가
• 왜 repo에 AGENTS.md, 검사 스크립트, decision memory, failure memory를 남겨야 하는가 - 왜 감각만으로는 agent가 좋아졌다고 판단할 수 없는가
• 왜 PR이 agent work의 measurement unit이 될 수 있는가

이번에는 한 걸음 더 나아간 이야기입니다.

지난번에 저는 이렇게 썼습니다.

기록이 없다면 비교는 할 수 없다.

하지만 ERP dogfood를 해보면서, 한 문장을 더 추가해야 한다는 것을 깨달았습니다.

기록이 있는 것만으로는 부족하다.

기록 그 자체도 검증되어야 한다.

이전에는 Next.js의 today-bus라는 프로젝트에서 dogfood를 하고 있었습니다.

이번에는 보다 사내 업무 시스템에 가까운 작은 프로젝트로 바꿨습니다.

harness-erp

거대한 시스템은 아닙니다.

그럼에도 이전 사례보다는 전통적인 업무 애플리케이션에 가깝습니다.

기술 스택(tech stack)은 대략 다음과 같습니다.

• Java 21
• Spring Boot
• Maven wrapper
• H2 database
• vanilla HTML / CSS / JavaScript frontend

업무 내용도 비교적 흔한 것들입니다.

• employee management
• purchase request
• approval workflow
• role-based access policy
• approval history
• frontend API coverage

ERP를 선택한 것은 완전한 ERP 제품을 만들고 싶어서가 아닙니다.

더 중요했던 것은 다음을 관찰하고 싶었기 때문입니다.

coding agent가 backend, frontend, 업무 규칙, 권한 규칙, 테스트, 문서를 가진 프로젝트를 상대할 때, harness가 불필요한 변경, 검증 누락, 이미 알고 있는 실수의 재발을 줄이는 데 도움이 되는가.

단순히 기능만 본다면, 에이전트가 API를 만들고, 화면을 작성하고, 테스트를 통과하면 끝인 것처럼 보입니다.

하지만 harness dogfood에서는 그렇게 보지 않습니다.

각 태스크(task)에 task outcome record를 남기도록 했습니다.

거기에는 다음과 같은 내용을 기록합니다.

• 이번 태스크의 목적
• expected boundary
• 에이전트가 실제로 변경한 파일
• wrong-file edit이 있었는가
• repeated known mistake가 있었는가
• first-pass verification을 통과했는가
• 마지막으로 실행한 검증 커맨드(command)
• 이 태스크를 effectiveness report에 넣을 수 있는가

조금 번거로워 보일지도 모릅니다.

하지만 저에게 있어 이러한 기록들은 매우 중요합니다.

에이전트의 작업이 채팅 로그에만 남아 있으면 금방 사라져 버리기 때문입니다.

며칠 후면, 저는 아마 이렇게밖에 기억하지 못할 것입니다.

이번에는 꽤 매끄러웠던 것 같아.

하지만 다음과 같은 사항까지는 기억하지 못할 수도 있습니다.

• 어떤 태스크 (task)에서 첫 번째 테스트가 실패했는지
• 어떤 태스크가 범위를 벗어난 파일 (out-of-bounds files)을 수정했는지
• 어떤 태스크가 setup 단계였으며, product-task metrics에 포함되지 말았어야 했는지
• 어떤 검증 (verification) 명령어가 실제로 실행되었는지
• 어떤 것이 검증처럼 보이기만 했을 뿐인지

그래서 이제는 이렇게 생각하게 되었습니다.

코드 차이 (code diff)만이 전부가 아니다.

에이전트 작업 (agent work)의 경계, 검증, 실패 또한 리포지토리 (repo) 내의 아티팩트 (artifact)가 되어야 한다.

이번 ERP dogfood는 단일 태스크가 아니었습니다.

몇 개의 태스크 그룹 (task group)으로 나누었습니다.

첫 번째 그룹은 backend initial benchmark입니다.

ERP-001
: employee search -
ERP-002
: purchase request amount validation -
ERP-003
: approval comment -
ERP-004
: employee department field -
ERP-005
: role-based access policy

그 후, backend follow-up도 있었습니다.

ERP-006
: enforce service-layer role policy -
ERP-007
: purchase request filtering -
ERP-008
: approval history -
ERP-009
: employee update

나아가 frontend follow-up도 있습니다.

FE-001
: vanilla frontend shell -
FE-002
: employee management frontend -
FE-003
: purchase request frontend -
FE-004
: approval workflow frontend -
FE-005
: full frontend API verification

총 14개의 product-task outcome을 기록했습니다.

결과만 보면 나쁘지 않습니다.

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

• backend initial group에 5개의 product task
• backend follow-up group에 4개의 product task
• frontend follow-up group에 5개의 product task
• 많은 태스크에서 wrong-file edit이 발생하지 않음
• 알려진 실수의 명확한 재발이 보이지 않음
• 모든 태스크에 task outcome record가 남음

그럼에도 저는 아직 이렇게 말할 수 없습니다.

harness가 에이전트 (agent)를 더 유효하게 만들었다고 증명할 수는 없습니다.

이유는 지난번과 같습니다.

pre-harness baseline이 없습니다.

human rework minutes도 제대로 측정하지 않았습니다.

프로젝트 규모도 아직 충분하지 않습니다.

더 정확하게는, 다음과 같이 말해야 한다고 생각합니다.

이번 ERP dogfood는 더 많은 harnessed-only evidence를 제공해 주었다.

harness가 에이전트 작업 (agent work)의 경계, 검증, 실패를 기록하는 데 도움이 된다는 것을 보여준다.

다만, harness adoption이 에이전트 유효성 (agent effectiveness)을 높였다는 것은 아직 증명하지 못했다.

이 결론은 광고 문구로서는 약합니다.

하지만 이것이 더 정직한 태도라고 생각합니다.

ERP dogfood 이후, 더 세밀한 문제들을 깨달았습니다.

이전의 저는 이렇게 보았습니다.

task outcome record가 있는가.

하지만 지금은 이렇게 보게 되었습니다.

task outcome record에 기록된 verification command는 정말로 신뢰할 수 있는가.

예를 들어 기록에 다음과 같이 적혀 있다고 가정해 봅시다.

./mvnw verify

그렇다면, 해당 리포지토리에는 정말로 mvnw가 있을까요?

기록에 다음과 같이 적혀 있는 경우는 어떨까요?

mvn test

리포지토리(repository)의 루트(root)에 정말로 pom.xml이 있을까요?

이렇게 적혀 있는 경우도 있습니다.

./gradlew check

해당 repo에 정말로 gradlew가 있을까요?

혹은, 다음과 같이 적혀 있는 경우입니다.

go test ./...

repo root에 정말로 go.mod가 있을까요?

하나하나가 작은 문제처럼 보일 수 있습니다.

하지만 매우 중요합니다.

확인하지 않으면, 에이전트(agent)는 "마치 검증을 수행한 것처럼 보이는 기록"을 남길 수 있기 때문입니다.

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

Verification:

mvn test

하지만 대상 repo는 Maven 프로젝트가 아닙니다.

혹은, 다음과 같은 기록입니다.

Detection check:

go test ./...

하지만 repo에 go.mod가 없습니다.

이러한 기록은 겉보기에는 깔끔합니다.

하지만 실제로는 아무것도 증명하지 못합니다.

그저 evidence(증거)가 갖춰져 있는 것처럼 보일 뿐입니다.

이는 harness에게 위험합니다.

harness의 목적은 깔끔한 문서를 만드는 것이 아닙니다.

repo를 더 신뢰할 수 있는 상태로 만들고, 에이전트의 실수를 빠르게 드러내는 것입니다.

그래서 이번에 harness-starter-kit에도 한 단계 더 나아간 체크를 추가했습니다.

현재 starter-kit 브랜치에서 수행하고 있는 작업은 상당히 구체적입니다.

failure memory, adoption report, task outcome 중에서 Maven, Gradle, Go 검증 명령어를 참조하고 있는 경우, 해당 명령어가 repo root의 project marker와 일치하는지 확인합니다.

대략적인 규칙은 다음과 같습니다.

mvn test에는 root pom.xml이 필요

./mvnw verify에는 root pom.xml과 root mvnw가 필요

gradle test에는 Gradle build/settings file이 필요

./gradlew check에는 Gradle build/settings file과 root gradlew가 필요

go test ./...에는 root go.mod가 필요

이것으로 명령어가 올바른 비즈니스 로직(business logic)을 모두 커버하고 있다는 것을 증명할 수 있는 것은 아닙니다.

예를 들어 mvn test가 존재하더라도, approval comment를 정말로 테스트하고 있다고 단정할 수 없습니다.

go test ./...가 존재하더라도, 특정 bug path를 커버하고 있다고 할 수 없습니다.

그럼에도 불구하고, 더 기본적인 문제는 방지할 수 있습니다.

문서에 검증 같은 명령어가 적혀 있지만,

그 명령어가 현재 repo와 애초에 일치하지 않는 상황 말입니다.

즉, 이것은 완전한 correctness proof(정확성 증명)는 아닙니다.

더 이른 단계의 sanity check(정상성 확인)입니다.

하지만 이 sanity check는 상당히 유용합니다.

에이전트는 "그럴듯한 문장"을 쉽게 써낼 수 있기 때문입니다.

harness는 그 일부를 검사 가능한 것으로 바꾸어야 한다고 생각합니다.

처음 harness-starter-kit을 만들었을 때, 생각은 더 단순했습니다.

저는 그저, coding agent에게 매번 똑같은 것을 설명하는 데 지쳐 있었습니다.

• 이 프로젝트에서는 어떤 명령어를 사용하는지
• 어떤 파일을 변경해서는 안 되는지
• 테스트는 어떻게 실행하는지
• 이전에 어떤 에러가 발생했는지
• 어떤 아키텍처상의 결정을 반복해서 논의하지 말아야 하는지

그래서 이러한 규칙들을 repo에 넣기로 생각했습니다.

그 후, 규칙이 있는 것만으로는 부족하다는 것을 알게 되었습니다.

그래서 failure memory를 추가했습니다.

나아가, failure를 기록하는 것만으로는 부족하다는 것을 알게 되었습니다.

failure memory는 regression check(회귀 테스트 확인)로 이어질 필요가 있었습니다.

그리고 이제, task outcome record가 있는 것만으로는 부족하다는 것을 알게 되었습니다.

task outcome에 기록된 verification command (검증 명령) 또한 검사될 필요가 있습니다.

이 과정을 통해, 저의 harness에 대한 이해는 바뀌었습니다.

이것은 "에이전트를 자동으로 똑똑하게 만드는 마법의 도구"가 아닙니다.

오히려 repo (저장소) 안에 있는 feedback loop (피드백 루프)입니다.

• 에이전트가 실수를 한다
• repo가 그 실수를 기록한다
• repo가 규칙, 테스트, 체크를 추가한다
• 다음에 에이전트가 비슷한 실수를 했을 때, 더 빨리 드러난다
• 체크 그 자체에 허점이 있다면, 그 체크도 보강한다

이것이 제가 지금 harness-starter-kit을 전파하고 싶은 이유입니다.

모든 문제를 해결했기 때문이 아닙니다.

실용적인 방향성을 제시해주기 때문입니다.

prompt (프롬프트)만을 최적화하지 않습니다.

repo 그 자체도 엔지니어링합니다.

Cursor, Claude Code, Codex, 기타 coding agent (코딩 에이전트)를 사용하는 분이라면, 비슷한 상황을 마주해 본 적이 있을지도 모릅니다.

• 새로운 세션마다 프로젝트 규칙을 다시 설명해야 함
• 에이전트가 테스트 실행을 잊어버림
• 에이전트가 수정해서는 안 되는 파일을 건드림
• 에이전트가 겉보기에는 깔끔하지만 아무도 유지보수하지 않는 docs (문서)를 생성함
• 에이전트가 "검증 완료"라고 말하지만, 무엇을 검증했는지 알 수 없음
• 동일한 버그나 동일한 종류의 실수가 며칠 뒤에 다시 나타남

이것들은 긴 prompt만으로는 해결하기 어려운 문제들입니다.

chat prompt (채팅 프롬프트)는 사라지기 쉽기 때문입니다.

반면, repo 내의 파일은 그렇게 쉽게 사라지지 않습니다.

그래서 저의 제안은 작게 시작하는 것입니다.

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

• 짧은 AGENTS.md를 작성한다
• 반복해서 발생한 failure (실패)를 하나 기록한다
• 그 failure를 test (테스트)나 check (체크)에 연결한다
• 프로젝트의 실제 검증 명령을 작성한다
• PR (Pull Request)에 task outcome (작업 결과)을 기록한다
• setup task (설정 작업)와 product task (제품 작업)를 나누어 집계한다

처음부터 복잡하게 만들 필요는 없습니다.

저 자신의 dogfood (자사 제품 사용)도 조금씩 진행하고 있습니다.

첫 번째 단계는 규칙을 repo에 두는 것이었습니다.

두 번째 단계는 실패를 기록하는 것이었습니다.

세 번째 단계는 task outcome을 기록하는 것이었습니다.

네 번째 단계는 harness health (harness 상태)와 agent effectiveness (에이전트 유효성)를 구분하는 것이었습니다.

그리고 지금의 다섯 번째 단계는 다음입니다.

evidence (증거) 그 자체도 검사 대상으로 삼는 것입니다.

현재의 harness-starter-kit에는 저 자신이 dogfood 해온 것들이 몇 가지 포함되어 있습니다.

• prompt-first adoption workflow (프롬프트 우선 채택 워크플로우)
• AGENTS.md guidance (가이드) - decision memory (의사결정 메모리)
• failure memory (실패 메모리)
• drift checks (드리프트 체크)
• Harness Doctor
• task outcome template (작업 결과 템플릿)
• effectiveness report template (유효성 보고서 템플릿)
  /harness doctor
/harness update
/harness refresh
/harness review
• TodayBus와 Harness ERP의 dogfood reports (dogfood 보고서)
• common checks (공통 체크)의 command-reference validation (명령어 참조 검증)
• Maven / Gradle / Go project-marker validation (프로젝트 마커 검증)

이것은 자동 설치기가 아닙니다.

당신의 프로젝트에 대해 당신의 프로젝트 이상으로 이해하는 척하지도 않습니다.

설계 방향은 다음과 같습니다.

먼저 agent에게 repo를 읽게 합니다.

그 후에 최소한으로 유용한 harness pieces (harness 구성 요소)만을 추가합니다.

이 점은 저에게 매우 중요합니다.

템플릿을 여기저기 복사해서 마지막에 repo를 복잡하게 만드는 도구로 만들고 싶지 않습니다.

제가 만들고 싶은 것은 starter kit (스타터 키트)입니다.

에이전트에게 다음과 같은 작업 방법을 부여하는 것입니다.

• 우선 대상 프로젝트를 조사한다
• 기존 아키텍처 (Architecture)를 존중한다
• 프로젝트 고유의 패키지 매니저 (Package manager), CI, 테스트, 문서화 관습을 유지한다
• 정말로 도움이 되는 규칙, 체크, 메모리 (Memory)만을 추가한다
• 중요한 실패를 나중에 검토하고 탐지할 수 있는 기록으로 바꾼다

이번 ERP dogfooding (도그푸딩)을 정리하자면, 지금의 저는 이렇게 말하겠습니다.

Harness ERP dogfooding에서는 14개의 harnessed-only product-task outcomes (제품-태스크 결과물)를 기록했습니다.

Spring/Maven 백엔드 (Backend), vanilla 프론트엔드 (Frontend), 역할 정책 (Role policy), 승인 워크플로우 (Approval workflow), 프론트엔드 API 커버리지 (Frontend API coverage), 브라우저 스모크 검증 (Browser smoke verification)을 포함합니다.

이러한 증거 (Evidence)들은 에이전트 작업 (Agent work)의 경계와 검증 결과를 재검토하는 데 도움이 됩니다.

다만, pre-harness baseline (사전 harness 기준점)이 없고, human rework minutes (인간 재작업 시간)도 측정하지 않았기 때문에, harness 도입이 agent effectiveness (에이전트 유효성)를 높였다고는 아직 증명할 수 없습니다.

여기에 덧붙이자면,

이번 dogfooding을 통해 task outcome record (태스크 결과 기록)에 작성된 검증 명령어도 검사해야 한다는 것을 알게 되었습니다.

따라서 starter kit (스타터 키트)는 Maven, Gradle, Go의 커맨드 레퍼런스 (Command reference)가 repo root (레포지토리 루트)의 project marker (프로젝트 마커)와 일치하는지 검증하기 시작했습니다.

긴 문장입니다.

하지만 "이 도구로 에이전트가 강해집니다"라고 말하는 것보다 더 정확합니다.

최근에는 너무 과한 홍보 문구를 쓰고 싶지 않다는 생각이 들었습니다.

오히려 이렇게 쓰고 싶습니다.

이 kit (키트)는 에이전트가 실수하지 않는다는 것을 보장하지 않습니다.

하지만 에러, 규칙, 검증, 증거를 repo (레포지토리)에 두어, 다음 실수를 더 빨리 드러내도록 도와줍니다.

harness-starter-kit은

여기에 있습니다.

실제 프로젝트에서 coding agent (코딩 에이전트)를 사용하면서,

"매번 같은 규칙을 다시 설명해야 한다", "에이전트가 프로젝트 컨텍스트 (Context)를 잊어버린다", "검증 기록을 신뢰하기 어렵다"와 같은 문제에 직면해 있다면 이 kit를 살펴보세요.

처음부터 완벽한 체계를 도입할 필요는 없습니다.

작은 발걸음부터 시작할 수 있습니다.

에이전트에게 가장 자주 반복하는 규칙을 단 한 문장이라도 repo에 적으세요.

최근에 다시는 겪고 싶지 않은 실패를 failure memory (실패 메모리)로 남기세요.

다음 PR (Pull Request)의 에이전트 작업을 task outcome (태스크 결과물)으로 기록하세요.

이것만으로도 채팅 로그에만 의존하는 것보다 훨씬 신뢰할 수 있습니다.

앞으로도 dogfooding을 계속할 것입니다.

특히 다음과 같은 영역을 시도해보고 싶습니다.

• 더 많은 Spring/Maven 시나리오
• monorepo (모노레포) 커맨드 검증 (Command validation)
• Rust / .NET / Python 모듈 커맨드 체크 (Module command checks)
• human rework minutes (인간 재작업 시간) 트래킹
• 더 안정적인 prompt reference (프롬프트 레퍼런스)
• 더 많은 실제 PR에 기반한 effectiveness report (유효성 보고서)

이 방향성이 도움이 될 것 같다고 생각하신다면, GitHub repo에 star를 눌러주시면 감사하겠습니다.

저에게 이것은 단순한 OSS (오픈 소스 소프트웨어) 프로젝트가 아닙니다.

주니어 개발자로서 코딩 에이전트와 더 진지하게 협업하는 방법을 배우기 위한 시도이기도 합니다.

에이전트가 항상 옳다고 믿는 것이 아닙니다.

repo에 다음 사항들을 기억하게 하는 것입니다.

• 에이전트가 지켜야 할 규칙
• 에이전트가 이전에 저지른 실수
• 실제로 실행된 검증
• 나중에 검토할 수 있는 evidence (증거)
• 아직 과도하게 홍보해서는 안 될 결론

이것이 지금 제가 이해하고 있는 harness engineering (하네스 엔지니어링)입니다.