Agentic Coding을 위한 Harness 구축기

AI 코딩 도구를 팀에 도입하면 구현 속도는 빨라집니다. 하지만 그 속도가 곧 팀 생산성으로 이어지지는 않았습니다.

이번 글에서는 그 간극을 줄이기 위해 프론트엔드 팀에서 Agentic Coding을 위한 Harness를 설계하고 적용한 과정을 정리합니다.

Harness Engineering이란?

Prompt, Context, Harness의 역할을 비교한 다이어그램

Harness Engineering은 AI 코딩 에이전트가 팀의 개발 프로세스를 안정적이고 일관되게 수행할 수 있도록 실행 환경과 작업 규칙을 설계하는 일입니다.

이 글에서는 에이전트가 팀의 맥락과 기준에 따라 작업할 수 있도록 컨텍스트 문서와 Rule을 정리하고, 반복 작업을 Skill로 분리한 과정을 소개합니다. 또한 계획부터 구현, 리뷰, PR 준비까지 이어지는 개발 워크플로우를 구성하고, 단계별 검증을 담당하는 Subagent를 함께 설계한 경험을 다룹니다.

문제 인식

실제 작업에서는 구현 속도보다 작업의 맥락을 얼마나 안정적으로 이어가느냐가 더 큰 병목이었습니다.

제품 개발은 코드 작성만으로 끝나지 않습니다. 요구사항과 변경 영향을 이해하고, 작업의 맥락을 이어가며, 리뷰와 QA를 통해 품질을 검증하는 과정까지 하나의 흐름으로 이어져야 합니다.

에이전트 코딩으로 결과물을 더 빠르게 만들 수 있었지만, 완성도는 활용 방식과 제공된 맥락에 따라 편차가 있었습니다. 특히 작업 범위가 넓고 여러 도메인이 얽힐수록 에이전트가 맥락을 놓치기 쉬웠고, 결과물의 완성도도 낮아졌습니다.

개인의 프롬프트 작성 방식과 활용 습관에 의존해서는 이러한 편차를 줄이기 어려웠습니다. 그래서 AI가 팀의 개발 기준에 따라 계획하고, 구현하고, 검증할 수 있도록 공통 워크플로우를 설계했습니다.

설계 방향

핵심 방향은 세 가지였습니다.

컨텍스트를 먼저 구조화한다
반복적이고 단순한 작업은 Skill로 위임한다
에이전트 작업을 실제 개발 흐름에 맞게 설계한다

1. 컨텍스트를 먼저 구조화한다

에이전트가 프로젝트 구조를 매번 추측하는 대신, 팀과 제품의 실제 맥락을 바탕으로 작업할 수 있어야 했습니다. 이를 위해 각 리포지토리의 개발 환경과 구조, 도메인 맥락, 리포지토리 간 관계를 정리한 컨텍스트 문서를 만들었습니다.

처음부터 모든 정보를 문서화하려 하지는 않았습니다. 우선 개발 환경과 프로젝트 구조, 주요 도메인처럼 작업에 자주 필요한 정보부터 정리했습니다. 이후 실제 작업 과정에서 에이전트가 놓치거나 개발자가 반복해서 설명해야 했던 내용을 문서에 조금씩 추가했습니다.

리포지토리와 도메인별로 쌓인 CLAUDE.md와 docs/는 에이전트뿐 아니라 개발자에게도 공통 참고 자료가 되었습니다. 프로젝트 구조와 도메인 지식을 다시 파악하기 쉬워졌고, 새로 합류한 개발자에게는 온보딩 자료로도 활용할 수 있었습니다.

2. 반복적이고 단순한 작업은 Skill로 위임한다

저희 팀은 Feature Flag를 활용해 기능을 점진적으로 배포했습니다. 기능을 개발할 때는 Flag 값을 읽는 훅과 on/off 분기를 추가하고, 정식 배포가 끝나면 이를 다시 제거했습니다.

구현 자체는 단순했지만 매번 관련 파일과 사용처를 찾아야 했습니다. Flag를 추가할 때는 훅과 분기 코드를 만들고, 제거할 때는 남은 사용처와 import를 정리해야 했습니다. 간단한 작업이지만 관련 파일이 많을수록 번거로워지는 일이었습니다.

이 과정을 /flag Custom Skill로 만들었습니다. 에이전트가 Flag 훅 생성과 사용처 탐색, 분기 코드의 추가·제거, 불필요한 import 정리까지 정해진 순서에 따라 수행하도록 했습니다.

이후 flag 생성과 제거 흐름을 팀에서 같은 방식으로 처리할 수 있었고, 확인과 수정에 걸리던 시간도 줄었습니다.

3. 에이전트 작업을 개발 흐름에 맞게 설계한다

에이전트가 코드 작성만 빠르게 수행해서는 팀의 개발 생산성을 높이기 어려웠습니다. 계획부터 구현, 검증, 리뷰, PR 준비까지 실제 개발 흐름에 따라 작업할 수 있어야 했습니다.

Addy Osmani의 agent-skills, Matt Pocock의 skills 공개 사례를 참고하되, 저희 팀의 개발 방식과 리뷰 절차에 맞게 단계를 다시 구성했습니다.

Plan, Code, Review, Ship으로 이어지는 Harness 워크플로우

전체 워크플로우는 Plan → Code → Review → Ship 네 단계로 나눴습니다.

Plan (/plan): Jira 이슈와 요구사항을 바탕으로 PRD, 시나리오, 작업 계획을 작성합니다.
Code (/step): 계획을 작업 단위로 나누어 구현하고, 검증 루프를 통해 결과를 스스로 검증합니다.
Review (/review): 코드 리뷰와 QA 관점에서 변경 사항을 병렬로 점검합니다.
Ship (/ship): PR 제목과 본문, 검증 항목을 정리하고 PR 생성을 준비합니다.

각 단계의 결과는 다음 단계의 입력으로 이어집니다. Plan에서 정리한 작업 범위와 기준은 Code의 구현 기준이 되고, 구현 내용과 검증 결과는 Review에서 다시 점검됩니다. Review에서 확인한 내용은 Ship 단계에서 PR을 정리하는 근거로 활용됩니다.

Plan: 작업에 필요한 맥락을 문서화한다

Plan은 작업을 시작하기 전에 요구사항과 코드 맥락을 정리하는 단계입니다. 작업 티켓에서 요구사항을 확인하고, 관련 코드를 탐색해 변경 범위와 영향을 파악합니다. 이를 바탕으로 다음 세 가지 문서를 생성했습니다.

prd.md: 작업 배경과 목표, 요구사항, 범위, 완료 기준
scenarios.md: QA 관점의 BDD 시나리오
progress.md: 기능 목록과 진행 상태, 세션별 작업 기록

문서를 하나로 합치지 않고 역할에 따라 나눈 이유는 긴 작업에서도 맥락을 안정적으로 이어가기 위해서였습니다. 요구사항과 검증 기준은 별도로 유지하고, 작업 중 발생한 결정과 진행 상황은 progress.md에 계속 기록했습니다.

덕분에 에이전트가 작업 도중 맥락을 잃더라도 기준 문서를 바탕으로 흐름을 다시 파악할 수 있었습니다. 개발자 역시 작업을 재개하거나 /resume 스킬로 중단된 세션을 이어갈 때, 이전 진행 과정과 다음 작업을 빠르게 확인할 수 있었습니다.

Code: 작업 단위로 구현한다

Code 단계의 핵심은 /step입니다. /step은 기능 목록에서 다음 작업 하나를 선택해 구현부터 검증, 커밋, 진행 기록까지 마치는 단계입니다.

핵심은 한 번에 하나의 작업만 처리하는 것입니다. 에이전트가 여러 변경을 동시에 만들면 영향 범위가 커지고, 리뷰와 실패 원인 파악도 어려워집니다. 그래서 작업을 기능 단위로 작게 나누고, 각 작업이 끝날 때마다 커밋과 진행 기록을 남기도록 했습니다.

GROUND, APPLY, REFLECT, VERIFY, ADAPT로 이어지는 GRAVA 검증 루프

구현 과정에는 검증 루프(GRAVA)를 적용했습니다.

GROUND: 관련 파일과 명세를 읽고 기존 코드의 구조와 패턴을 파악합니다.
APPLY: 확인한 패턴을 바탕으로 필요한 범위만 구현합니다.
REFLECT: 구현 위치와 기술적 선택, 명세 충족 여부를 점검합니다.
VERIFY: 시나리오와 코드 변경을 대조하고 테스트와 정적 검사를 수행합니다.
ADAPT: 검증에 실패하면 원인을 분석하고 GROUND 단계로 돌아가 다시 확인합니다.

코드 작성 자체를 완료 기준으로 삼지 않고, 구현 → 검증 → 수정이 반복되도록 만든 구조입니다. 이를 통해 에이전트가 변경 사항을 스스로 점검하고, 검증 결과를 반영한 뒤 작업을 마치도록 했습니다.

Review: 코드와 QA 관점을 나눠 점검한다

Review는 변경 사항을 원격에 올리기 전에 실행하는 로컬 1차 품질 게이트입니다. 하나의 리뷰어가 모든 항목을 확인하도록 하지 않고, 코드 품질과 사용자 시나리오를 별도의 Subagent로 나눠 점검했습니다.

code-reviewer: 정확성, 가독성, 구조, 보안, 성능 관점에서 코드 품질을 확인합니다.
qa-reviewer: scenarios.md를 기준으로 사용자 시나리오와 예외 상황, 구현 누락을 확인합니다.

두 리뷰어의 결과는 메인 에이전트가 통합하고, 위험도에 따라 우선순위를 나눴습니다.

치명적 이슈: 머지 전 반드시 수정
중요 이슈: 수정 권장
제안 사항: 필요에 따라 선택적으로 반영

역할을 분리한 이유는 코드 품질과 QA 관점을 각각 깊게 검토하기 위해서였습니다. 각 리뷰어가 정해진 기준에 집중하고, 메인 에이전트는 중복된 의견을 정리해 최종 우선순위를 결정했습니다.

실제로 /review를 통해 다음과 같은 문제를 PR 전에 확인할 수 있었습니다.

사용성: 고정 패널을 추가하는 과정에서 하단 푸터가 가려질 수 있는 화면 구성 문제
구조: 불필요한 추상화로 함수의 책임이 모호해진 부분
구현: API의 public 설정 누락처럼 배포 후 장애로 이어질 수 있는 설정 문제

이를 통해 코드 구조뿐 아니라 사용자 시나리오와 배포 후 발생할 수 있는 위험까지 PR 전에 함께 점검할 수 있었습니다.

Ship: 리뷰 가능한 형태로 PR을 준비한다

/ship은 PR 마무리를 표준화하는 단계입니다.

사전 점검 항목 확인
PR 제목과 유형 정리
작업 배경과 변경 내용 작성
리뷰 포인트와 셀프 테스트 결과 정리
Bitbucket CLI를 활용한 PR 생성 또는 업데이트

에이전트가 작성한 PR 설명은 앞 단계의 맥락을 과도하게 담아 장황해지거나, 핵심 리뷰 포인트가 흐려지는 경우가 있었습니다. 이를 보완하기 위해 첫 5줄 안에 변경 내용과 목적이 드러나는지, 설명이 적정 길이를 넘지 않는지 확인하는 기준을 PR 작성 가이드에 추가했습니다.

완성된 설명을 그대로 사용하기에는 여전히 보완이 필요했지만, 계획과 구현, 검증 기록을 바탕으로 초안을 만드는 용도로는 충분히 유용했습니다. 이후 개발자가 불필요한 내용을 덜어내고 핵심을 보완해 PR을 완성했습니다.

Resume: 중단된 작업의 맥락을 복원한다

우선순위가 바뀌어 다른 업무로 전환하면, 이전 작업의 맥락을 놓치거나 진행 상태를 다시 파악하는 데 시간이 들었습니다.

이를 보완하기 위해 중단된 작업을 새로운 세션에서 이어가는 Resume Skill을 만들었습니다. 현재 Git 브랜치와 연결된 progress.md를 찾아 전체 작업 목록과 완료 항목, 다음 작업을 확인합니다.

다만 문서 기록만으로 상태를 판단하지는 않았습니다. git status와 최근 커밋을 함께 확인해 기록된 진행 상황과 실제 코드 상태가 일치하는지 검증하도록 했습니다.

하네스의 구현과 배포

처음에는 특정 애플리케이션 리포지토리의 .claude/ 설정에서 하네스를 만들었습니다. 실제 기능 개발에 적용하며 필요한 Skill과 Rule을 추가하고, 반복되는 작업 흐름을 다듬었습니다.

이후 여러 프로젝트에서 같은 워크플로우를 사용하게 되면서, 하네스를 stunning-fe-harness 플러그인 마켓플레이스로 분리했습니다. 개별 리포지토리마다 설정을 관리할 경우 변경 사항을 반복해서 반영해야 했기 때문입니다.

구성은 세 영역으로 나눴습니다.

plugins/fe-harness/
├── skills/   # /plan, /step, /review, /ship, /resume, /flag
├── rules/    # 작업 승인, Feature Flag, 함수 작성 규칙 등
└── harness/  # 설계 배경과 운영 가이드

skills/에는 개발 흐름을 실행하는 명령을, rules/에는 작업 중 지켜야 할 공통 기준을 두었습니다. harness/에는 설계 배경과 운영 방법을 문서화했습니다.

플러그인으로 분리한 뒤에는 여러 프로젝트에서 동일한 워크플로우를 설치해 사용하고, 변경 사항도 한곳에서 관리할 수 있었습니다.

입력 품질 표준화: Jira 티켓 템플릿과 자동화

하네스를 실제 작업에 적용하면서, 같은 워크플로우를 사용하더라도 Jira 티켓의 품질에 따라 에이전트의 작업 효율이 달라진다는 점을 확인했습니다.

작업 범위와 배경이 정리된 티켓은 /plan 이후의 재질문과 코드 탐색이 적었습니다. 반면 정보가 부족한 티켓은 요구사항과 관련 맥락을 다시 확인하는 과정이 반복됐고, 작업 시간과 토큰 사용량도 늘어났습니다.

이에 티켓 작성 방식을 공통 템플릿으로 표준화하고, 다음과 같은 원칙을 정했습니다.

설명에는 확정된 요구사항만 남기고 논의 과정은 댓글로 분리합니다.
디자인 링크에는 확인해야 할 화면과 상태를 함께 적습니다.
링크만으로 파악하기 어려운 댓글과 주석은 티켓 본문에도 기록합니다.
작업 범위와 완료 기준을 구분해 작성합니다.

외부 문서와 디자인 도구의 맥락을 에이전트가 항상 안정적으로 읽을 수 있는 것은 아니기 때문에, 필요한 정보를 티켓 안에 명시하도록 한 것입니다.

티켓은 기본 운영 일감, 에픽, 버그, 개선, 개발 하위 일감으로 구분했습니다. 각 유형에 필요한 항목이 자동으로 입력되도록 Jira Automation을 적용해, 티켓 생성 단계에서 중요한 정보가 빠지는 것을 줄였습니다.

템플릿은 팀원들이 최근 작업을 새로운 형식으로 다시 작성해 본 뒤, 실제 사용 피드백을 반영해 조정했습니다. 누락된 항목은 추가하고 활용도가 낮은 항목은 제거하면서 실제 개발 흐름에 맞게 다듬었습니다.

작성 원칙과 티켓 유형별 기준, 적용 과정은 별도의 레퍼런스 문서로 정리했습니다. 이를 통해 Jira 티켓을 개발자와 에이전트가 함께 참고하는 공통 입력 문서로 활용할 수 있었습니다.

자세히 보기: 사람과 AI가 함께 읽는 Jira 티켓 — 템플릿과 자동화로 입력 품질 높이기

결과

개인별 프롬프트에 의존하던 AI 활용을 팀 공통 워크플로우 기반의 Harness Engineering으로 옮겼습니다.
레포 구조, 도메인 맥락, 작업 규칙을 컨텍스트 문서와 Rule로 분리해 에이전트가 추측보다 근거 기반으로 작업하도록 만들었습니다.
/plan, /step, /review, /ship, /resume, /flag 명령으로 계획, 구현, 검증, 리뷰, PR 준비, 맥락 복원 흐름을 표준화했습니다.
반복적인 Feature Flag 생성·제거 작업을 Custom Skill로 분리해 확인과 수정에 걸리던 평균 시간을 5분에서 30초로 단축했습니다.
Jira 티켓 작성 규약과 종류별 자동화를 함께 정비해, 에이전트 작업의 입력 품질 자체를 끌어올렸습니다.
하네스만의 효과라고 단정할 수는 없지만, 월별 지표를 2개월 단위로 비교했을 때 이전 기간 대비 PR 수는 약 26% 증가했습니다.

회고

하네스를 설계하면서 개발 단계를 하나씩 나눠보니, 저희 팀의 개발 흐름을 다시 살펴볼 수 있었습니다. 어떤 부분은 문서로 남기고, 어떤 반복 작업은 Skill로 분리해야 하는지도 더 분명해졌습니다.

처음부터 완성된 시스템을 설계하기는 어려웠습니다. 여러 사람이 함께 쓰는 워크플로우였기 때문에, 큰 구조를 한 번에 정하기보다 간단한 부분부터 빠르게 적용해보고 피드백을 받는 과정이 더 중요했습니다. 실제 작업에서 반복되는 불편을 확인하며 Skill과 Rule을 조금씩 고쳐가면서, 하네스를 팀에서 쓸 수 있는 도구로 다듬어갔습니다.

이 과정에서 /plan 단계의 효율은 Jira 티켓의 정보 품질에 크게 영향을 받는다는 점도 확인했습니다. 그래서 하네스 자체뿐 아니라 티켓 종류별 템플릿과 자동화, 디자인 링크와 외부 맥락을 문서화하는 방식까지 함께 정비하게 됐습니다.