팀 하네스 설계 체크리스트

핵심 요약

• 리포·문서, 역할·경계, 평가·완료 기준, 도구 접근, HITL·승인, 샌드박스·통합, workflow 배포, 운영·정리 8개 영역을 각 0~2점으로 진단합니다.
• 16점 만점 총점으로 단계를 나눠, 05점은 진입 문서·검증 명령부터, 611점은 release gate·sandbox boundary, 12~16점은 telemetry·garbage collection을 다음 행동으로 잡습니다.
• 최소 버전 7가지(진입 문서, 도메인 규칙, 검증 명령, review 루프, 실행 검증, sandbox/MCP/hooks/approval boundary, updates·cleanup)만 갖춰도 품질이 크게 좋아집니다.
• 과설계 체크: 안 읽히는 규칙 파일 증가, 새 실패를 못 잡는 reviewer, 작은 작업의 full loop 강제 같은 신호가 2개 이상이면 요소를 줄여야 합니다.
• 30일 도입은 1주차 진입 문서, 2주차 검증·승인 명문화, 3주차 review/QA 분리, 4주차 updates·cleanup 순으로 진행합니다.

하네스 설계는 멋진 철학을 세우는 일이라기보다 에이전트가 실제로 부딪히는 병목을 없애는 일에 가깝습니다.

아래 질문에 답하지 못한다면 그 부분이 다음 설계 과제입니다.

빠른 진단 점수표

각 항목을 0, 1, 2점으로 거칠게 채점해 보면 어디를 먼저 손대야 할지 금세 드러납니다.

1. 리포지터리와 문서

• 에이전트가 읽어야 할 첫 문서는 무엇인가
• AGENTS.md 또는 동등한 진입 문서가 짧고 최신 상태인가
• 아키텍처, 도메인 규칙, 릴리즈 기준이 리포 안에 있는가
• Slack/Notion/회의록에만 있는 규칙이 많은가
• 문서 간 링크와 소유자가 분명한가

2. 역할과 경계

• planner, builder, reviewer, QA 중 어떤 역할이 실제로 필요한가
• 모든 작업을 한 에이전트가 다 하는 것이 아니라 분리해야 할 병목이 있는가
• 각 역할의 입력과 출력이 명확한가
• reviewer가 단순 칭찬이 아니라 구체적 실패 모드를 찾도록 설계되어 있는가

3. 평가와 완료 기준

• "완료"를 무엇으로 판정하는가
• lint, typecheck, build, 테스트 외에 브라우저 검증이 필요한가
• 도메인 특화 게이트가 있는가 예: 결제 정합성, 권한 누락, 데이터 마이그레이션 안전성
• 평가 기준이 프롬프트 속 문장에만 있고 자동화되어 있지 않은가

4. 도구 접근성

• 에이전트가 필요한 로그, 메트릭, 트레이스, 브라우저에 접근 가능한가
• 실제 문제를 고치려면 외부 시스템을 꼭 봐야 하는데 리포 정보만으로는 부족하지 않은가
• 브라우저 QA가 필요한 제품인데 텍스트만 보고 수정하게 두고 있지 않은가

5. HITL과 승인

• 어떤 작업은 자동으로 진행하고 어떤 작업은 사람 승인이 필요한가
• 파괴적 명령, 배포, 보안 민감 변경의 승인이 분리되어 있는가
• 승인 기준이 사람마다 다르지 않은가
• 승인 이후에 무엇을 다시 검증해야 하는가
• 자동 승인 모드를 쓴다면 trust boundary, block rule, allow exception이 문서/설정으로 남아 있는가
• classifier가 차단한 작업을 우회하지 않고 더 안전한 경로를 찾도록 설계되어 있는가
• 고위험 인프라, 결제, 보안 변경은 자동 분류기가 아니라 hard human gate로 남아 있는가

6. 샌드박스와 통합 경계

• shell, filesystem, apply_patch, browser, MCP 중 어떤 도구를 기본으로 열 것인가
• 민감 데이터나 production credential이 모델 생성 코드가 실행되는 환경과 분리되어 있는가
• private/on-prem MCP를 public internet에 직접 노출하지 않는 연결 경로가 있는가
• hooks로 prompt 검사, validation, logging, memory 생성 같은 lifecycle 작업을 자동화하고 있는가
• remote approval이 필요한 장시간 작업에서 사람이 제때 개입할 수 있는가
• session log, harness, sandbox가 같은 장애 경계에 묶여 있지 않은가
• subagent가 외부 도구를 쓰거나 결과를 반환할 때 별도 handoff 검사가 필요한가

7. 워크플로우 배포

• 팀의 좋은 작업 방식을 slash command, skill, template, hook으로 배포하고 있는가
• 특정 고수만 아는 루틴이 여전히 구전으로만 전파되는가
• 신규 팀원이 같은 요청으로 비슷한 기본 품질을 낼 수 있는가
• provider setup, API key 연결, troubleshooting처럼 반복되는 플랫폼 작업을 plugin으로 배포할 수 있는가
• 도메인별 template이 skills, connectors, subagents, approval flow를 함께 포함하는가

8. 운영과 정리

• stale 문서를 찾는 루틴이 있는가
• 더 이상 쓰지 않는 명령과 스킬을 정리하는 주기가 있는가
• 모델이 바뀌었을 때 불필요해진 scaffolding을 줄이고 있는가
• 업데이트 로그가 남아 있어 "왜 바뀌었는지" 추적 가능한가

점수화 시트

점수에 따른 다음 행동

바로 적용할 최소 버전

아래 7가지만 있어도 하네스 품질은 크게 좋아집니다.

1. 짧은 진입 문서 하나
2. 아키텍처/도메인 규칙 문서
3. 필수 검증 명령 세트
4. 최소 한 개의 review 루프
5. 최소 한 개의 브라우저 또는 실제 실행 검증
6. sandbox/MCP/hooks/approval boundary
7. 업데이트 로그와 stale cleanup 루틴

하네스 MVP 패키지

가장 먼저 만들 최소 패키지는 이 정도면 충분합니다.

이 패키지에 반드시 연결될 실행 루프:

1. read AGENTS/docs -> implement -> verify -> update log
2. UI가 있으면 browser QA를 완료 조건에 포함
3. 고위험 변경이면 human gate를 분리
4. 외부 도구가 필요하면 MCP allowlist와 sandbox 권한을 먼저 고정
5. 자동 승인 모드를 쓸 때는 trust boundary와 deny rule을 설정으로 남김

과설계 방지 체크

좋은 하네스는 많이 붙이는 것보다 필요한 것만 남기는 것에 가깝습니다.

아래 중 2개 이상이 예라면 과설계를 의심해 볼 만합니다.

• 아무도 읽지 않는 규칙 파일이 계속 늘어난다
• reviewer 단계가 있어도 실제로 새 실패를 거의 못 잡는다
• 작은 작업도 항상 full loop를 강제해서 속도가 급격히 떨어진다
• command 이름은 많지만 팀이 뭘 써야 하는지 더 헷갈린다
• 사람 승인 단계가 형식만 있고 실제 판단 기준이 비어 있다

팀 상황별 우선순위

30일 도입 예시

체크리스트의 목적

이 체크리스트는 "완벽한 하네스"를 만들기 위한 것이 아닙니다. 지금 우리 팀의 병목이 문서인지, 역할인지, 평가인지, 운영인지 빨리 식별하기 위한 도구입니다.