SHIFTONE
적용기10분 읽기SHIFTONE Team

코드 대신 기준서를 썼다 — 톺톺·떠올라 하네스 엔지니어링 개발기

톺톺과 떠올라를 만들면서 사람이 쓴 건 구현 코드가 아니라 기준서와 루틴이었어요. 에이전트가 일하는 환경을 설계하는 하네스 엔지니어링 — 실제로 만든 문서와 정기 루틴, 중복 실행 사고까지 정리했어요.

벽에 정돈되어 걸린 목공 공구들 — 도구를 배치하는 일로서의 하네스 엔지니어링

저희는 요즘 두 서비스를 만들고 있어요. 톺톺은 넷플릭스·티빙·유튜브 영상 속 셀럽 착장 아이템을 신뢰도 라벨과 함께 확인하는 서비스고, 떠올라는 무작위로 떠오르는 단어를 채집해 발상을 돕는 iOS 앱이에요. 떠올라는 1.0.1이 App Store에 올라가 있고, 톺톺은 출시를 준비하고 있어요.

두 서비스의 구현 코드는 사람이 거의 쓰지 않았어요. Claude Code가 썼거든요. 저희가 쓴 건 기준서와 루틴, 그러니까 하네스였어요.

하네스 엔지니어링이 뭔가요

매번 프롬프트에 요구사항을 길게 적어 주는 대신, 에이전트가 일하는 환경 자체를 설계하는 쪽이에요. 기준서 · 경계 · 검증 절차 · 반복 실행 스케줄을 만들어 두면 에이전트는 그 안에서 움직여요. 사람이 손대는 대상이 "이번 작업물"에서 "작업이 굴러가는 구조"로 바뀌는 거죠.

기준서가 단일 진실 원본 — 프롬프트에 규칙을 복사하지 않는다 리포의 기준서 RESEARCH-BRIEF 177줄 REVIEW-BRIEF 120줄 SCAN-PLAYBOOK 252줄 07시 · 일일 리서치신규 아이템 50건+ 14시 · 유사 아이템원본은 건드리지 않음 서브에이전트병렬 5개 내외생성과 검수를다른 에이전트가 이 구조가 지키는 것 규칙이 한 곳에만 있다 — 기준서를 고치면 모든 루틴이 같이 바뀐다 루틴끼리 겹치지 않는다 — 각자 못 하는 일을 문서에 못 박아 둔다 만든 에이전트가 자기 결과를 승인하지 않는다 목표량보다 규칙이 위다 — 규칙을 어기며 건수를 채우지 않는다

실제로 만든 것

톺톺 리포에는 RESEARCH-BRIEF.md(177줄), REVIEW-BRIEF.md(120줄), SCAN-PLAYBOOK.md(252줄)가 있어요. 각각 리서치 규칙, 검수 판정 기준, 영상에서 아이템이 보이는 회차·시각을 특정하는 방법이에요. 루틴 정의에는 이런 문장을 넣어 뒀어요.

리서치·검수 서브에이전트에게도 이 파일들을 읽으라고 지시하라. 프롬프트에 규칙을 복사하지 마라.

규칙을 프롬프트에 복사하는 순간 진실이 두 곳이 돼요. 기준서를 고쳐도 프롬프트는 옛날 규칙을 들고 있거든요. 이걸 막는 게 하네스의 첫 번째 일이에요.

떠올라는 성격이 좀 달라요. 343줄짜리 tteoolla-v1-sdd.md 하나에 개요 · 아키텍처 · 데이터 모델 · API 명세 · 화면 명세 · 비기능 요구사항 · 마일스톤 · 열린 결정 사항까지 적어 두고 시작했어요. 마지막 항목이 중요해요. 아직 안 정한 걸 안 정했다고 적어 두면, 에이전트가 임의로 정하고 넘어가지 않거든요.

루틴 — 사람이 없어도 도는 부분

톺톺은 콘텐츠가 계속 들어와야 해서 정기 루틴 두 개가 돌아요. 07시 루틴은 새 영상에서 아이템을 찾아 제품 특정 · 구매 링크 · 검수 · 승인까지 끝내고, 14시 루틴은 등록된 아이템과 겉보기가 비슷한 대체 상품을 붙여요.

둘의 경계는 문서에 못 박아 뒀어요. 14시 루틴은 원본 아이템을 수정하지 않아요. 문제가 보이면 고치지 말고 보고만 하게 했어요. 07시 루틴은 구매 링크를 못 찾으면 14시로 넘기지 않고 자기가 반려해요. 넘길 곳을 만들어 두면 어려운 판단이 전부 그리로 흘러가더라고요.

부작용과 고친 지점

중복 실행. 8월 28일에 같은 루틴이 두 번 돌아 같은 작품을 동시에 조사한 적이 있어요. 지금은 루틴 시작할 때 다른 세션이 같은 일을 하고 있는지 먼저 확인하고, 겹치면 대상 작품을 나눠요.

스키마 드리프트. 컬럼이 늘어난 걸 모르고 예전 형식으로 넣는 사고가 있었어요. 그래서 이제 루틴 0단계에서 실제 스키마를 조회해 대조해요.

건수 압박. 하루 50건이라는 목표를 주면 에이전트는 규칙을 느슨하게 풀어서라도 채우려고 해요. 그래서 기준서에 "규칙을 어겨 가며 건수를 채우지 마라 — 적게 내는 게 낫다"를 대놓고 적어 뒀어요.

에이전트끼리 붙이는 건 아직 하네스 안에서

여러 에이전트가 동시에 도니까 조율이 필요해요. 지금은 같은 하네스 안에서 세션끼리 서로를 확인하고 일을 나누는 수준이고, MCP·A2A 같은 표준 프로토콜로 조직 경계를 넘어 붙이는 단계는 아니에요. 내부 조율과 프로토콜 상호운용은 다른 문제라서, 필요해지는 시점에 넘어가려고 해요.

배운 것

코드를 안 쓴다고 일이 줄지는 않았어요. 일의 종류가 바뀌었을 뿐이에요. 예전엔 구현이 어려웠는데, 지금은 "무엇을 옳다고 할 것인가"를 문서로 정확히 적는 게 어려워요. 기준서가 애매하면 에이전트는 애매한 결과를 대량으로 만들어 내거든요.

그래서 저희는 이렇게 정리했어요. 사람은 판정 기준과 경계를 쓰고, 에이전트는 그 안에서 만든다. 고객사 AI Agent 프로젝트에서 쓰는 방식도 같습니다.

자주 묻는 질문

Q. 정말 사람이 코드를 한 줄도 안 썼나요? 구현 코드는 대부분 에이전트가 작성했어요. 사람은 기준서 · 스펙 · 루틴 정의를 쓰고, 결과를 판정하고, 방향이 틀어졌을 때 구조를 고쳐요.

Q. 결과물 품질은 어떻게 담보하나요? 만든 에이전트가 자기 결과를 승인하지 못하게 했어요. 별도 검수 기준서를 가진 다른 에이전트가 판정하고, 기준에 못 미치면 반려해요.

Q. 작은 팀에서도 이렇게 할 수 있나요? 규칙이 반복되는 일부터 시작하시길 권해요. 매번 같은 설명을 프롬프트에 적고 있다면, 그건 이미 기준서로 뽑아낼 때가 됐다는 신호예요.

Sources