Long-Running AI Agents를 위한 효과적인 하네스 설계

Session 1 (Day 1)
  "프로젝트를 시작합니다..."
  [컨텍스트 가득 참] → 세션 종료
 
        ⬇️ 기억 단절 ⬇️
 
Session 2 (Day 2)
  "이 프로젝트가 뭐였죠...?"
  [처음부터 다시 파악]

초기화 에이전트가 하는 일:
 
1. init.sh 스크립트 생성 (환경 설정 자동화)
2. claude-progress.txt 생성 (진행 상황 추적)
3. 초기 git 커밋 생성 (버전 관리 시작점)
4. 기본 프로젝트 구조 설정

코딩 에이전트의 세션 프로토콜:
 
1. pwd 실행 (현재 위치 확인)
2. 진행 파일 읽기 (어디까지 했는지)
3. git log 확인 (최근 변경사항)
4. 기능 목록 검토 (다음 할 일)
5. 개발 서버 시작
6. 한 가지 기능만 구현
7. 테스트 및 검증
8. 커밋 및 진행 파일 업데이트

{
  "features": [
    {
      "id": "auth-001",
      "name": "이메일 로그인",
      "priority": "high",
      "status": "pending",
      "acceptance_criteria": [
        "이메일/비밀번호 입력 폼",
        "유효성 검사",
        "에러 메시지 표시",
        "성공 시 대시보드 리다이렉트"
      ]
    }
  ]
}

# Project: E-commerce Dashboard
# Last Updated: 2026-02-05
 
## Completed
- [x] 프로젝트 초기 설정
- [x] 인증 모듈 기본 구조
- [x] 로그인 페이지 UI
 
## In Progress
- [ ] 로그인 API 연동 (80% 완료)
 
## Next Up
- [ ] 회원가입 페이지
- [ ] 비밀번호 재설정
 
## Known Issues
- 로그인 폼 모바일 반응형 깨짐 (낮은 우선순위)
 
## Notes for Next Session
- API 엔드포인트: /api/auth/login
- 테스트 계정: test@example.com / password123

커밋 단위:
- 기능 단위로 커밋 (한 세션 = 한 기능 = 한 커밋)
- 의미 있는 커밋 메시지
 
브랜치 전략:
main
  └── feature/auth
        ├── "feat: 로그인 폼 UI 구현"
        ├── "feat: 로그인 API 연동"
        └── "test: 로그인 통합 테스트"

❌ 나쁜 예: "오늘 인증 시스템 전체를 완성하겠습니다"
 
✅ 좋은 예: "오늘은 로그인 폼 UI만 완성하겠습니다"

세션 종료 전 체크리스트:
 
1. 현재 작업 상태 진행 파일에 기록
2. git commit (의미 있는 단위라면)
3. 다음 세션을 위한 노트 작성
4. 알려진 이슈 문서화

# CLAUDE.md
 
## 세션 시작 시
1. docs/progress.md 읽기
2. git log --oneline -5 확인
3. docs/features.json에서 다음 작업 선택
 
## 작업 완료 시
1. docs/progress.md 업데이트
2. git commit -m "feat: [기능명]"
3. 다음 세션 노트 작성

프로젝트/
├── CLAUDE.md          # 기본 규칙
└── docs/
    └── progress.md    # 진행 상황

프로젝트/
├── CLAUDE.md
├── init.sh            # 환경 설정 스크립트
└── docs/
    ├── progress.md
    └── features.json  # 기능 목록

프로젝트/
├── CLAUDE.md
├── init.sh
├── .claude/
│   ├── hooks/         # 자동화 훅
│   └── skills/        # 재사용 워크플로우
└── docs/
    ├── progress.md
    ├── features.json
    └── session-logs/  # 세션별 로그

하네스 도입 체크리스트:
 
[ ] 프로젝트에 progress.md를 생성했는가?
    - 세션 간 상태를 전달할 진행 문서 작성
 
[ ] 기능을 20개 이상으로 세분화했는가?
    - 에이전트가 한 세션에 처리할 수 있는 크기로 분할
 
[ ] 세션 시작/종료 프로토콜을 CLAUDE.md에 정의했는가?
    - 인수인계 절차를 표준화하여 연속성 확보