Harness Engineering은 선택이 아니라 필수일지도 모른다.

회사에서 개발 티켓 지표를 위한 몇 가지 속성이 추가되었고, 올해 생성된 개발 티켓을 대상으로 속성을 수정해야 했다.
벌써 올해 상반기가 지나가고 있었기 때문에 변경할 대상 티켓이 많았지만 나에게는 Cursor와 Atlassian MCP가 있어서 걱정이 없었다.

요청은 단순했다.

올해 개발 티켓 중 담당자가 내 아이디인 티켓 속성을 추가해줘.
특정 조건에는 A 라벨을, 다른 조건에는 B 라벨을 추가해줘.

지금까지도 MCP를 티켓이나 문서 작업에 사용해 왔기 때문에 별다른 의심 없이 일을 시켜두고 다른 작업을 하고 있었다.
그런데 동기한테 DM이 왔다.

너 왜 내 티켓 바꾸냐 ㅋㅋㅋㅋㅋ

뭔가 잘못된거 같다…

순간 Cursor에 일을 시켜 놓은 게 떠올랐다.
터미널을 보니 아직까지 수정 작업이 진행 중이었다.

급하게 작업을 중지함과 동시에 다른 팀원분께도 DM이 왔다.

라벨 잘못 다신거 같아요! 제 티켓에 다셨어요..!

확인해보니 내 담당 티켓뿐만 아니라 다른 개발자분들의 티켓 라벨도 수정되고 있었다.
결과적으로 약 33개의 티켓 라벨이 변경되었고, 대상자도 여러 명이라 tech 소통 채널에 공지를 올려야 했다.

이번 포스팅에서는 이 실수를 계기로 업무 시스템에서 AI Agent를 사용할 때 왜 하네스가 필요하다고 생각했는지 정리해본다.

문제 상황

Cursor Auto 모델과 Atlassian MCP를 사용하면 자연어로 Jira 티켓을 조회하고 수정할 수 있다.

예를 들어 다음과 같은 작업을 요청할 수 있다.

• 특정 조건에 맞는 티켓 조회
• 조회된 티켓의 라벨 수정
• 개발 티켓 생성
• 배포 티켓 생성
• 문서 페이지 생성

이 기능 자체는 매우 편리하다.
반복적인 티켓 작업을 줄일 수 있고, 사람이 놓칠 수 있는 값도 같이 확인할 수 있다.

하지만 실제 업무 시스템을 수정하는 작업에서는 편리함보다 중요한 것이 있다.
수정 대상의 범위를 정확하게 제한하는 것이다.

이번 작업에서는 분명히 담당자가 내 아이디인 티켓만 수정해달라고 요청했다.
하지만 결과적으로 다른 개발자분들의 티켓까지 수정되었다.

다행히 이번에는 라벨만 변경하는 작업이었다.
라벨은 다시 수정할 수 있고, 문서상 큰 이슈가 생기는 값은 아니었다.

하지만 같은 방식으로 더 중요한 값이 수정되었다면 문제가 더 커질 수 있었다.
예를 들어 티켓 상태, 일정, 담당자, 작업량, 배포 관련 값처럼 지표나 업무 흐름에 영향을 주는 값이었다면 단순한 해프닝으로 끝나지 않았을 것이다.

이번 실수는 라벨 변경이었지만, 업무 시스템에서 AI Agent가 잘못된 범위를 수정할 수 있다는 것을 직접 경험한 사건이었다.

왜 이런 일이 생겼을까

이번 문제를 겪고 나서 자연어 프롬프트만으로는 충분하지 않다는 생각을 했다.

나는 분명히 담당자가 내 아이디인 티켓이라고 요청했다.
하지만 에이전트가 실제로 어떤 검색 조건을 사용했는지, 조회된 티켓의 담당자가 누구였는지, 수정 전에 대상 목록을 확인했는지는 명확하지 않았다.

사람이 직접 티켓을 수정할 때는 여러 가지를 암묵적으로 확인한다.

예를 들어 내 담당 티켓인지 확인하고, 현재 값이 무엇인지 확인하고, 수정해도 되는 값인지 한 번 더 확인한다.
여러 티켓을 수정해야 한다면 대상 목록을 먼저 살펴본다.

하지만 AI Agent에게는 이런 암묵지가 자동으로 전달되지 않는다.

자연어로 “내 담당 티켓만”이라고 말해도 실제 작업에서는 다음과 같은 기준이 필요했다.

• 어떤 계정을 내 계정으로 볼 것인지
• 어떤 조건으로 대상을 조회해야 하는지
• 조회 결과를 바로 수정해도 되는지
• 여러 건을 수정하기 전에 확인 절차가 필요한지
• 기존 값을 덮어써도 되는지
• 수정하면 안 되는 값은 무엇인지
• 작업 후 결과를 어떻게 확인할 것인지

즉, 프롬프트에는 의도가 있었지만 작업 절차는 충분히 고정되어 있지 않았다.

그래서 업무 시스템을 수정하는 Agent에게는 하네스가 필요하다고 생각했다.

하네스란 무엇인가

하네스는 원래 어떤 대상이 안전하게 동작하도록 잡아주고 제한하는 장치이다.
테스트 자동화에서는 테스트 하네스라는 표현을 사용한다. 테스트 대상이 정해진 조건 안에서 실행되도록 준비하고, 입력과 출력을 검증할 수 있게 만드는 구조를 의미한다.

AI Agent에게도 비슷한 개념이 필요하다고 생각했다.

여기서 말하는 하네스는 Agent가 작업을 수행하기 전에 반드시 따라야 하는 작업 규칙과 안전장치의 묶음이다.
단순히 프롬프트를 길게 쓰는 것이 아니라, 반복되는 작업 기준을 문서화해서 Agent가 항상 같은 방식으로 확인하고 실행하도록 만드는 것이다.

하네스는 Agent에게 다음과 같은 역할을 한다.

• 작업 전에 기준을 먼저 확인하게 한다.
• 수정 대상의 범위를 명확하게 제한한다.
• 여러 건을 수정하기 전에 대상 목록을 확인하게 한다.
• 기존 값을 함부로 덮어쓰지 않게 한다.
• 위험한 작업과 단순 작업을 구분하게 한다.
• 작업 후 결과를 보고하게 한다.

즉, 하네스는 Agent가 더 똑똑해지도록 만드는 장치라기보다, Agent가 위험하게 행동하지 않도록 작업 범위를 고정하는 장치에 가깝다.

프롬프트가 “무엇을 해줘”에 가깝다면, 하네스는 “어떤 절차 안에서 해줘”에 가깝다.

어떤 하네스를 구성했나

이번 일을 계기로 Atlassian MCP를 사용할 때 Agent가 먼저 따라야 하는 하네스를 cursor를 이용해서 구성했다.

하네스의 목적은 단순히 티켓 양식을 맞추는 것이 아니었다.
Jira나 Confluence처럼 실제 업무 데이터가 쌓이는 시스템을 수정할 때, Agent가 작업 범위를 잘못 해석하지 않도록 기준을 고정하는 것이 목적이었다.

구성은 크게 두 부분으로 나누었다.

첫 번째는 Cursor가 자동으로 읽는 규칙 파일이다.
두 번째는 Agent와 사람이 함께 참고할 수 있는 문서 하네스이다.

전체 구조는 다음과 같이 구성했다.

.cursor/
└── rules/
    └── atlassian.mdc

harness/
├── AGENTS.md
├── README.md
└── atlassian/
    ├── README.md
    ├── account.md
    ├── account.local.md.example
    ├── ticket-harness.md
    ├── jira-formats.md
    ├── confluence-formats.md
    ├── fields-reference.md
    └── ticket-policy.md

.cursor/rules/atlassian.mdc는 Cursor가 Atlassian 작업을 할 때 자동으로 적용하는 규칙이다.
여기에는 Jira나 Confluence 작업 요청이 들어오면 어떤 문서를 먼저 읽어야 하는지, 대량 수정 전에 무엇을 확인해야 하는지, 기존 값을 어떻게 다뤄야 하는지 같은 핵심 규칙을 넣었다.

이 파일은 Agent가 하네스로 진입하는 입구 역할을 한다.
사용자가 매번 “하네스 문서를 먼저 읽어줘”라고 말하지 않아도, Atlassian 작업이라면 기본 규칙이 먼저 적용되도록 하기 위한 장치이다.

AGENTS.md는 Agent가 실제 작업을 시작할 때 읽는 체크리스트이다.
계정 정보를 확인하고, 티켓 작업인지 문서 작업인지 구분하고, 필요한 포맷 문서를 읽은 뒤 MCP 도구를 호출하도록 순서를 정리했다.

README.md는 사람을 위한 진입 문서이다.
하네스를 처음 사용하는 사람이 어떤 목적의 문서인지 이해하고, 개인 설정이나 MCP 연결, 하네스 갱신 방법을 빠르게 확인할 수 있도록 구성했다.

atlassian/README.md는 실무 작업 흐름을 정리한 문서이다.
티켓을 만들거나 수정할 때 어떤 체크리스트를 따라야 하는지, 어떤 기준으로 조회해야 하는지, 자주 사용하는 작업 방식은 무엇인지 정리했다.

account.md는 기본 계정과 환경 정보를 담고 있다.
담당자 기준으로 티켓을 조회하거나 문서를 생성할 때 어떤 계정을 기본으로 사용할지 정리했다.
개인별로 달라지는 값은 account.local.md로 분리할 수 있게 했다.

ticket-harness.md는 하네스의 중심 문서이다.
잘 작성된 기존 티켓을 reference로 두고, 제목 형식, 설명 구조, 자주 사용하는 값, 생성 시 주의할 점을 정리했다.
새 티켓을 만들거나 기존 티켓을 수정할 때 팀의 작성 관습을 참고할 수 있게 하기 위한 문서이다.

jira-formats.md는 Jira 티켓을 만들거나 수정할 때 사용하는 형식을 정리한 문서이다.
제목은 어떤 식으로 작성하는지, 설명에는 어떤 순서로 내용을 넣는지, 배포나 운영과 관련된 티켓에는 어떤 정보가 필요한지 정리했다.

confluence-formats.md는 문서 생성 기준을 정리한 문서이다.
티켓과 연결된 문서를 어디에 생성해야 하는지, 기존 문서와 중복되지 않으려면 무엇을 먼저 확인해야 하는지 정리했다.

fields-reference.md는 Jira API에서 사용하는 필드 정보를 모아둔 참조 문서이다.
화면에 보이는 이름과 API에서 사용하는 필드 값이 다를 수 있기 때문에, Agent가 잘못된 필드를 수정하지 않도록 분리했다.

onpd-ticket-policy.md는 개발 티켓 관리 정책을 정리한 문서이다.
샘플 티켓에서 학습한 작성 관습과 실제 지표 관리 정책이 충돌할 수 있기 때문에, 정책에 해당하는 내용은 별도 문서로 분리했다.
하네스에서는 샘플보다 정책을 우선하도록 했다.

이렇게 파일을 나눈 이유는 Agent가 작업의 성격에 따라 필요한 기준을 찾기 쉽게 하기 위해서이다.

기존 티켓을 수정하는 작업이라면 계정 기준, 조회 범위, 기존 값 보존 규칙이 중요하다.
새 티켓을 생성하는 작업이라면 제목과 설명 형식, 필요한 정보가 중요하다.
문서를 생성하는 작업이라면 생성 위치와 중복 여부 확인이 중요하다.

하네스는 이 기준을 한 번에 모두 외우게 하는 것이 아니라, 작업 전에 필요한 문서를 읽고 같은 절차로 실행하도록 만드는 구조이다.

하네스가 동작하는 흐름

하네스는 다음과 같은 흐름으로 동작하도록 구성했다.

사용자가 Atlassian 작업 요청 → Cursor 규칙 파일 적용 → Agent 작업 체크리스트 확인 → 계정과 작업 범위 확인 → 작업 유형에 맞는 하네스 문서 확인 → 필요한 경우 기존 티켓이나 문서 조회 → 수정 대상 목록 확인 → 사용자 확인 후 생성 또는 수정 → 작업 결과 보고

중요한 점은 Agent가 바로 수정하지 않도록 만든 것이다.

이전에는 사용자가 “내 티켓에 라벨을 추가해줘”라고 하면 Agent가 바로 조회하고 수정할 수 있었다.
하지만 하네스를 구성한 뒤에는 먼저 기준을 확인하고, 대상 목록을 보여준 뒤, 사용자가 확인하면 수정하는 흐름을 따르게 했다.

특히 여러 건을 수정하는 작업은 반드시 중간 확인 단계를 거치도록 했다.
이번 실수처럼 조회 범위가 잘못되면 여러 사람의 티켓이 한 번에 바뀔 수 있기 때문이다.

작업 유형별 기준 나누기

흐름을 정하고 나니 작업 유형도 나누어야 했다. Jira나 Confluence에서 Agent가 하는 일은 겉으로 보면 조회하고, 만들고, 수정하는 정도로 비슷해 보인다. 하지만 막상 기준을 만들려고 보니 작업마다 망가지는 지점이 달랐다.

기존 티켓을 수정할 때는 무엇보다 수정 대상이 문제였다. 이번 실수도 결국 조회 범위가 잘못 잡히면서 시작되었다. 한 번 잘못 조회된 뒤에는 라벨을 어떻게 붙일지, 기존 값을 보존할지 같은 기준이 잘 지켜져도 의미가 없어진다. 그래서 기존 항목을 수정하는 작업에서는 먼저 대상 목록을 보고, 담당자와 현재 값을 같이 확인하도록 했다. 기존 값은 기본적으로 유지하고 필요한 값만 추가하는 기준도 여기에 넣었다.

새 티켓을 만드는 작업은 조금 달랐다. 수정 대상이 틀릴 일은 없지만, 정보가 부족한 상태로 티켓이 만들어질 수 있다. 제목만 그럴듯하게 만들어도 티켓은 생성되지만 담당자, 일정, 배포 여부, 참고 문서 같은 정보가 빠지면 결국 사람이 다시 정리해야 한다. 생성 작업에서는 바로 만들기보다 필요한 정보가 충분한지 먼저 확인하게 한 이유가 여기에 있다.

문서 작업은 또 다른 문제가 있었다. Confluence 문서는 위치가 잘못되거나 이미 비슷한 문서가 있는데 새로 만들어지면 나중에 찾기도 어렵고 관리도 어려워진다. 티켓처럼 상태 값 하나를 바꾸는 문제가 아니라, 잘못된 위치에 애매한 문서가 하나 더 생기는 문제가 된다. 그래서 문서를 만들 때는 생성 위치와 중복 여부를 먼저 확인하도록 했다.

결국 하네스에서 나누고 싶었던 것은 명령의 종류라기보다 실패하는 방식이었다. 수정 작업은 잘못된 대상을 건드릴 수 있고, 생성 작업은 필요한 정보가 빠질 수 있고, 문서 작업은 위치와 중복이 문제가 될 수 있다. 작업마다 실수하는 모양이 다르다면 확인해야 하는 기준도 달라져야 한다고 생각했다.

샘플을 기준으로 맞추기

작업 기준을 나누는 것만으로는 조금 부족했다. 업무 시스템에는 필수 값 말고도 팀에서 자연스럽게 맞춰 온 작성 방식이 있다.

예를 들어 티켓 제목을 어떤 단위로 쓰는지, 설명에는 배경과 작업 내용을 어떤 순서로 넣는지, 배포가 필요한 작업에서는 어떤 정보를 남기는지 같은 것들이다. 이런 내용은 문서로 정확히 정리되어 있지 않은 경우가 많지만, 사람이 보면 어색한 티켓과 자연스러운 티켓은 구분된다.

Agent가 만든 티켓도 마찬가지였다. 필수 필드만 채운다고 해서 실제로 이어서 작업하기 좋은 티켓이 되는 것은 아니었다. 그래서 하네스에는 잘 작성된 기존 티켓과 문서를 참고하는 흐름을 넣었다. 단순히 값을 채우는 것보다, 팀에서 평소에 읽고 쓰던 형태에 가깝게 맞추는 편이 이후 작업에도 낫다고 봤다.

물론 샘플을 그대로 복사하게 두지는 않았다. 일반 개발 작업, 설정 변경 작업, 배포 작업, 문서 정리 작업은 필요한 정보와 설명 방식이 다르다. 샘플은 어디까지나 형식을 맞추기 위한 참고 자료이고, 실제 작성 기준은 작업 유형과 정책을 우선하도록 했다.

이 부분은 안전장치라기보다는 품질을 맞추기 위한 장치에 가까웠다. Agent가 만든 결과물도 결국 사람이 다시 읽고 이어서 작업해야 한다. 그렇다면 시스템에 저장만 되는 결과물이 아니라, 팀에서 원래 일하던 흐름과 크게 어긋나지 않는 결과물을 만드는 쪽이 더 낫다고 봤다.

작업 방식의 변화

하네스를 만들기 전에는 Agent에게 다음과 같이 요청했다.

내 담당 티켓 중에서 조건에 맞는 티켓을 찾아서 라벨을 수정해줘.
기존 라벨은 유지하고 필요한 라벨만 추가해줘.
다른 사람 티켓은 수정하지 마.

요청 안에 중요한 조건이 모두 들어있기는 하다. 문제는 매번 이 조건을 빠뜨리지 않고 말해야 한다는 점이었다. 더 큰 문제는 조건을 다 말하더라도 Agent가 실제로 어떤 조회 조건을 사용했는지 확인하기 어렵다는 점이었다.

하네스를 만든 뒤에는 요청 방식이 조금 바뀌었다.

하네스 기준으로 내 담당 티켓 중 라벨 수정 후보를 조회해줘.
수정 전에 대상 목록 먼저 보여줘.

작업을 AI에게 맡기는 것은 그대로다. 달라진 점은 바로 수정하지 않는다는 것이다. 먼저 하네스 기준으로 후보를 조회하고, 대상 목록을 확인한 뒤, 그 다음에 수정한다. 요청 자체도 짧아졌지만 더 중요한 변화는 실행 시점이 뒤로 밀렸다는 점이다.

예전 요청은 Agent가 바로 행동할 수 있는 문장이었다. 하네스를 적용한 뒤의 요청은 먼저 후보를 찾고, 기준에 맞는지 보고, 사용자가 확인한 뒤에 실행하는 문장에 가깝다. 이 차이가 생각보다 컸다.

프롬프트는 요청에 가깝고, 하네스는 작업 계약에 가깝다고 느꼈다. 요청은 매번 달라질 수 있지만, 작업 계약은 반복적으로 적용된다.

AI Agent가 업무 시스템을 수정할 때는 “무엇을 해줘”뿐만 아니라 “어떤 절차로 해줘”까지 같이 정해야 한다. 하네스는 이 절차를 매번 다시 설명하지 않아도 되도록 고정하는 역할을 한다.

정리

이번 글에서는 Cursor Auto 모델과 Atlassian MCP를 사용하다가 다른 개발자분들의 티켓 라벨을 수정하게 된 경험과, 이를 계기로 하네스를 구성한 과정을 정리해보았다.

AI Agent를 업무 시스템에 연결하면 반복 작업을 빠르게 처리할 수 있다. 하지만 Jira나 Confluence처럼 실제 업무 데이터가 쌓이는 시스템에서는 속도보다 정확한 범위를 지키는 일이 먼저였다.

이번 실수는 라벨 변경이라 큰 문제로 이어지지는 않았다. 하지만 같은 실수가 더 중요한 값에서 발생했다면 영향이 컸을 것이다.

그래서 업무 시스템을 수정하는 Agent에게는 자연어 프롬프트만으로는 부족하고, 먼저 읽고 따라야 하는 하네스가 있어야 한다고 생각했다. 작업 전에 기준을 확인하고, 담당자와 조회 범위를 명확하게 하고, 여러 건을 수정하기 전에는 대상 목록을 보여주는 식의 절차가 필요했다. 기존 값은 함부로 덮어쓰지 않고, 작업 종류에 따라 확인해야 하는 기준도 달라져야 했다.

AI 자동화는 단순히 사람의 일을 대신하는 것보다, 사람이 정한 작업 방식을 안정적으로 반복하도록 만드는 데 더 큰 의미가 있다고 생각한다. 편리함은 중요하지만, 실제 업무 데이터와 연결되는 순간에는 편리함보다 안전한 실행 흐름이 먼저여야 한다.

이번 경험을 통해 업무 자동화에서는 모델 성능만큼이나 작업 범위와 안전장치를 설계하는 일이 중요하다는 것을 느꼈다.
Harness Engineering은 선택이 아니라 필수일지도 모른다.