SHIFTONE
적용기10분 읽기SHIFTONE Team

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

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

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

SHIFTONE은 최근 두 서비스를 만들고 있습니다. 톺톺은 넷플릭스·티빙·유튜브 영상 속 셀럽 착장 아이템을 신뢰도 라벨과 함께 확인하는 서비스이고, 떠올라는 무작위로 떠오르는 단어를 채집해 발상을 돕는 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 같은 표준 프로토콜로 조직 경계를 넘어 붙이는 단계는 아닙니다. 내부 조율과 프로토콜 상호운용은 다른 문제라, 필요해지는 시점에 넘어갈 계획입니다.

배운 것

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

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

자주 묻는 질문

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

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

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

Sources