팀 하네스 설계 체크리스트

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

아래 질문에 답할 수 없다면 그 부분이 다음 설계 과제입니다.

빠른 진단 점수표

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

1. 리포지터리와 문서

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

2. 역할과 경계

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

3. 평가와 완료 기준

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

4. 도구 접근성

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

5. HITL과 승인

• 어떤 작업은 자동으로 진행하고 어떤 작업은 사람 승인이 필요한가
• 파괴적 명령, 배포, 보안 민감 변경의 승인이 분리되어 있는가
• 승인 기준이 사람마다 다르지 않은가
• 승인 이후에 무엇을 다시 검증해야 하는가

6. 워크플로우 배포

• 팀의 좋은 작업 방식을 slash command, skill, template, hook으로 배포하고 있는가
• 특정 고수만 아는 루틴이 여전히 구전으로만 전파되는가
• 신규 팀원이 같은 요청으로 비슷한 기본 품질을 낼 수 있는가

7. 운영과 정리

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

점수화 시트

점수에 따른 다음 행동

바로 적용할 최소 버전

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

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

하네스 MVP 패키지

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

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

1. read AGENTS/docs -> implement -> verify -> update log
2. UI가 있으면 browser QA를 완료 조건에 포함
3. 고위험 변경이면 human gate를 분리

과설계 방지 체크

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

아래 중 2개 이상이 예면 과설계를 의심할 가치가 큽니다.

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

팀 상황별 우선순위

30일 도입 예시

체크리스트의 목적

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