lab-builder

# Lab Builder ## 실습 설계 원칙 ### 학습 사이클 각 실습은 **체험 → 이해 → 적용** 3단계로 구성: 1. **체험(Experience)**: 하네스 없이 에이전트에게 작업 시키기 → 문제 체험 2. **이해(Understand)**: 왜 문제가 발생했는지 분석, 하네스 개념 연결 3. **적용(Apply)**: 하네스를 직접 구축하여 문제 해결 ### 실습 환경 전제조건 - Claude Code CLI 설치 완료 - Node.js 18+ 설치 - Git 설치 - 터미널 기본 사용 가능 ## 실습별 상세 설계 ### Lab1: CLAUDE.md로 에이전트 행동 제어 **시나리오**: 간단한 Express API 프로젝트에서 Claude Code로 기능 추가 **Step 1 (체험)**: - CLAUDE.md 없이 "사용자 인증 기능 추가해줘" 요청 - 결과: 일관성 없는 코드 스타일, 프로젝트 규칙 무시 **Step 2 (이해)**: - 결과물의 문제점 분석 (파일 구조, 네이밍, 에러 처리 등) **Step 3 (적용)**: - CLAUDE.md 작성 (코딩 규칙, 파일 구조, 금지 사항 등) - 동일 요청 재실행 → 품질 비교 ### Lab2: 권한 모드와 Hooks로 Guardrails 구축 **시나리오**: 프로덕션 DB 접근 가능한 프로젝트에서 안전장치 구축 **Step 1 (체험)**: - 위험한 명령 실행 가능성 확인 (rm -rf, DB drop 등) **Step 2 (이해)**: - settings.json 권한 체계 학습 - hooks 개념 학습 **Step 3 (적용)**: - .claude/settings.json 에 deny 규칙 설정 - pre-hook으로 위험 패턴 차단 스크립트 작성 ### Lab3: 테스트 주도 에이전트 작업 **시나리오**: 계산기 모듈에 기능 추가 — 테스트 먼저 작성 **Step 1 (체험)**: - 테스트 없이 기능 추가 요청 → 에이전트가 "완료"라 하지만 버그 존재 **Step 2 (이해)**: - 자기검증(Self-Verify) 루프의 필요성 - LangChain의 "AI는 좋아 보이네 하고 멈추는 경향" 인용 **Step 3 (적용)**: - CLAUDE.md에 "구현 후 반드시 테스트 실행" 규칙 추가 - 테스트 파일 먼저 작성 → 에이전트가 테스트 통과까지 반복 ### Lab4: 장기 에이전트의 상태 관리 **시나리오**: 5개 기능을 가진 작은 앱을 여러 세션에 걸쳐 완성 **Step 1 (체험)**: - 한 세션에서 모든 기능 요청 → 컨텍스트 초과, 품질 저하 **Step 2 (이해)**: - Anthropic의 "초기화 에이전트 + 코딩 에이전트 분리" 패턴 - progress.txt 패턴 **Step 3 (적용)**: - features.json (기능 목록) + progress.txt (진행 상황) 파일 설계 - 세션당 1기능씩 구현, 매 세션 시작 시 progress 읽기 ### Lab5: 종합 — 실제 프로젝트에 하네스 적용 **시나리오**: 제공된 미완성 프로젝트에 풀 하네스 구축 **체크리스트**: - [ ] CLAUDE.md 작성 (프로젝트 규칙) - [ ] .claude/settings.json (권한 설정) - [ ] hooks 설정 (안전장치) - [ ] 테스트 스위트 구성 (검증 루프) - [ ] progress 관리 체계 (상태 관리) - [ ] 코드 리뷰 규칙 정의 ## 스타터 프로젝트 템플릿 각 실습의 스타터 프로젝트는 `assets/templates/` 참조. 기본 구조: ``` starter/ ├── package.json ├── src/ │ └── index.ts (또는 .js) ├── tests/ │ └── (Lab3부터) └── .claude/ └── (실습자가 채울 빈 구조) ``` ## 평가 체크리스트 형식 ```markdown # Lab{N} 평가 체크리스트 ## 필수 완료 항목 - [ ] {항목 1} - [ ] {항목 2} ## 품질 기준 - [ ] 하네스 적용 전후 차이가 명확한가 - [ ] 설정이 실제 동작하는가 - [ ] 다른 프로젝트에 재사용 가능한 형태인가 ## 심화 (보너스) - [ ] {추가 도전 과제} ```