harness-starter-kit을 실제 프로젝트에 적용해 본 후기

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

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

지난 기사에서는 제가 왜 harness-starter-kit을 만들었는지에 대해 썼습니다.

이유는 간단합니다.

Cursor 나 Claude Code 의 새로운 세션(session)을 열 때마다, 동일한 프로젝트 규칙을 에이전트(agent)에게 매번 다시 설명하고 싶지 않았기 때문입니다.

이 기사는 깔끔하게 정리된 튜토리얼이 아닙니다.

실제 프로젝트에 이 스타터 키트(starter kit)를 넣어보았을 때 어떤 일이 일어났는지를 기록한 것입니다.

처음에 불안했던 점은 다음과 같았습니다.

• 에이전트가 템플릿을 대량으로 복사해버리지 않을까
• 기존 프로젝트의 구조를 망가뜨리지 않을까
• 아무도 유지보수하지 않아 docs/ 디렉터리만 늘어나는 것이 아닐까

그래서 프롬프트(prompt)에서는 다음과 같은 사항을 여러 번 강조했습니다.

• 먼저 현재 프로젝트를 조사할 것
• 템플릿을 맹목적으로 복사하지 말 것
• 필요한 최소한의 것만 추가할 것
• 기존 파일을 마음대로 덮어쓰지 말 것

대략 다음과 같은 프롬프트를 전달했습니다.

Use this kit to apply harness engineering to this repository:

Clone the kit into ./harness-starter-kit, read it as read-only reference,
...

실제로 실행해 보니 주로 다음과 같은 것들이 추가되었습니다.

AGENTS.md

• 몇 가지 작은 검사 스크립트(script)
  docs/decisions/

docs/failures/

• 도입 보고서(adoption report)

저에게 중요했던 점은 프로젝트를 특정 '표준 구조'로 억지로 바꾸지 않았다는 것입니다.

원래 채팅에서 여러 번 설명했던 규칙을 리포지터리(repository) 안으로 옮겼을 뿐이었습니다.

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

- 변경 후에는 기존 테스트를 실행한다
- 자동 생성 파일은 변경하지 않는다
- 기존 디렉터리 구성을 따른다
...

Before:

• 규칙이 채팅 로그(chat log) 안에만 있었다
• 새로운 세션에서는 컨텍스트(context)를 잊어버리기 쉬웠다
• 에이전트의 실수는 인간이 찾아낼 수밖에 없었다
• 실패로부터 얻은 지식이 남기 어려웠다

After:

• 규칙이 리포지터리에 들어갔다
• 에이전트가 매번 AGENTS.md를 읽을 수 있게 되었다
• 일부 실수는 스크립트로 조기에 검출할 수 있게 되었다
• 과거의 실패를 docs/failures/에 남길 수 있게 되었다

솔직히 말해서, 이것으로 에이전트가 정말 좋아졌다고는 아직 증명할 수 없습니다.

말할 수 있는 것은, 몇몇 규칙이 채팅 로그 안에만 갇혀 있지 않게 되었다는 점입니다.

다음 세션을 열었을 때, 에이전트가 적어도 그 규칙을 읽을 기회를 가질 수 있게 되었습니다.

다만, 이것이 정말로 에러(error)를 줄여줄지는 아직 별개의 문제입니다.

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

• 잘못된 파일을 변경하는 횟수가 줄어드는가
• 테스트 실행을 잊어버리지 않게 되는가
• 같은 버그를 반복하지 않게 되는가
• 리뷰어(reviewer)의 재작업(rework)이 줄어드는가

이를 말하기 위해서는 더 많은 실제 프로젝트에서의 데이터가 필요합니다.

그래서 저는 Doctor의 점수가 올라갔다고 해서 에이전트의 품질이 올라갔다고 말하지는 않습니다.

정말로 중요한 것은 실제 태스크 결과(task outcome)입니다.

앞으로는 더 많은 실제 프로젝트에서의 이용 상황을 수집하고 싶습니다.

만약 Cursor 나 Claude Code 를 자주 사용하면서 비슷한 문제로 고민하고 계신 분이 있다면, 꼭 이 프로젝트를 확인해 보세요.

GitHub:

현재 기여하기 쉬운 이슈(issue)도 몇 가지 있습니다.

• Go / Rust / iOS / Rails / Laravel 프로필(profile) 추가
• 모노레포(monorepo) 도입 예시(adoption example) 작성
• GitLab CI 도입 노트(adoption note) 보충
• Harness Doctor의 메시지 개선
• 실제 도입 보고서(adoption report) / 효과 증거(effectiveness evidence) 추가

이러한 사고방식에 문제가 있다고 생각하신다면, 언제든 솔직하게 지적해 주세요.

저는 아직 주니어 개발자이기 때문에, 경험이 풍부한 개발자분들의 피드백을 특히 듣고 싶습니다.