AI 에이전트 하네스 치트시트: 구성 요소, 파일, 문제 해결과 시작 체크리스트

AI 에이전트 하네스의 다섯 구성 요소

처음부터 구축하는 순서: 피드백 → 지침 → 상태 → 환경 → 도구.

하네스 파일

AGENTS.md 골격

# 프로젝트: 결제 백엔드 (FastAPI, PostgreSQL)

## 실행
docker compose up -d && ./scripts/init.sh

## 검사
make check   # lint, 타입, unit, arch-check
make e2e     # 엔드투엔드 시나리오

## Definition of Done
- make check와 make e2e — 코드 0
- 기능이 scripts/verify.sh로 passing 처리됨
- PROGRESS.md 갱신됨

## MUST
- 데이터베이스 요청은 repository를 통해서만
- 비밀 정보는 환경 변수에서만

## 문서
- docs/payments.md — 결제와 환불 관련 작업일 때
- docs/migrations.md — 데이터베이스 스키마를 바꿀 때

기능의 상태

검증 단계

"완료"라고 말할 권한은 가장 상위 단계를 통과한 뒤에만 있습니다. 초록색 unit 테스트는 완료가 아닙니다.

규칙의 기계화

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: 서비스는 데이터베이스와 직접 통신하지 않는다"
  echo "FIX: app/repositories/의 repository를 사용하세요"
  fail=1
fi
exit $fail

자주 생기는 문제와 해결책

긴 작업의 역할

자율 작업의 예산

• 목표는 한 문장으로 (예: 모든 기능을 passing으로 만들기).
• WIP=1, 기능당 시간과 시도 횟수 제한.
• 지표는 단조 증가해야 하며, 회귀는 즉시 롤백.
• Migration, 인프라, 돈: 사람에게 에스컬레이션.
• 여러 번 리뷰에 실패하면 기능을 깨끗한 context에서 다시 시작.

에이전트 시작 체크리스트

1. AGENTS.md가 있다: 스택, 실행 방법, 검사 명령, DoD.
2. make check가 깨끗한 클론에서 통과한다.
3. 환경이 재현 가능하다: 잠금 파일, Docker 또는 devcontainer.
4. 에이전트에게 필요한 명령이 열려 있고, 위험한 명령은 막혀 있거나 sandbox 안에 있다.
5. 최소한 주요 시나리오에 대한 E2E가 있다.
6. PROGRESS.md가 있고, 세션 시작 시 읽으라는 규칙이 있다.
7. 기능이 상태와 함께 목록에 있고, 활성은 하나뿐이다.
8. passing 표시는 스크립트가 찍는다.
9. 검사 메시지에 WHY와 FIX가 있다.
10. 작업이 인수 기준과 범위 경계와 함께 적혀 있다.
11. 사람의 결정이 필요한 것이 무엇인지 정해져 있다.
12. 변경 전에 verification gap을 측정해 비교 기준을 만들었다.

하네스 지표

요약

하네스는 파일이 아니라 순환입니다: 지침, 도구, 환경, 상태, 피드백. 검사에서 시작하고, AGENTS.md는 짧게 유지하고, 완료 표시는 스크립트에 맡기고, 하네스를 정기적으로 점검하세요. 이 모든 것은 실제 프로젝트에서 하나의 하네스로 묶어 실습 과정에서 가르칩니다.