harness-factory: Skill for Claude Code

개발 규칙 (Development)

코드를 작성·수정·검증할 때 따른다. IMPORTANT: 시스템/사용자 메시지가 이 스킬보다 우선한다. 프로젝트 명령어는 AGENT.md의 표를, 절대 수정 금지 경로는 .env, secrets/, .venv/, node_modules/를 따른다.

0. 코드 짜기 전에 생각하기 (가장 싼 수정은 틀린 코드를 안 쓰는 것)

• 가정을 말로 꺼낸다. 사용자가 의도를 다 안 적었을 때, 무엇을 가정했는지 한 줄로 명시한다.
• 모호하면 묵묵히 고르지 말고 드러낸다. 두 해석이 다 맞는다면 둘 다 적고 묻는다. 잘못된 무언의 선택 한 번이 묻는 질문 한 번보다 비싸다.
• 더 단순한 길이 있으면 push back 한다. 시키는 대로만 하지 말고, 같은 문제를 더 작게 푸는 방법이 있으면 제안한다.
• 막히면 멈춘다. 무엇이 헷갈리는지 이름 붙여 묻는다. 혼란을 추측 코드로 덮지 않는다.

나쁨:  "유저 데이터 export 기능 추가해줘" → 곧장 csv/json/xml exporter 작성
좋음:  "API 엔드포인트, 페이지네이션 JSON, PII 제외 필드만이라 가정. 맞나? 'export'는 다른 세 가지 의미도 가능 — 함께 보여드릴까요?"

작업 흐름 (Read → Think → Plan → Edit → Verify)

1. Read — 고치기 전에 인접 코드·패턴을 읽고 이 레포의 관례를 파악한다. 라이브러리는 매니페스트(import/패키지 파일)로 존재를 확인한다.
2. Think — §0을 적용. 모호하면 코드 짜기 전에 먼저 묻는다.
3. Plan — 3단계 이상이거나 모호하면 PLAN.md에 단계를 적되 단계마다 verify 줄을 함께 적는다(§목표 주도 실행 참고).
4. Edit — 아래 규칙대로 최소 변경.
5. Verify — .scripts/verify.sh를 통과시킨다. 통과 전 "완료" 보고 금지.

브랜치 전략 (작업 공간)

작업 공간 전략: git worktree로 작업

• 작업마다 별도 워크트리를 만들어 메인 체크아웃을 건드리지 않는다: git worktree add ../<프로젝트>-<작업명> -b <브랜치명>.
• 해당 워크트리 디렉터리에서 작업·커밋하고, 끝나면 PR로 병합한 뒤 git worktree remove로 정리한다.
• main 체크아웃에서 직접 커밋하지 않는다. (여러 작업을 병렬로 격리할 때 유용하다.)

범위 규율 (가장 흔한 실패 모드)

• 요청한 것만 한다. 버그 수정에 주변 정리를 끼워넣지 않는다.
• 비슷한 세 줄이 섣부른 추상화보다 낫다. 가상의 미래 요구를 위해 설계하지 않는다.
• 기존 파일 수정 > 새 파일 생성. 반쪽 구현을 남기지 않는다.
• 발견한 표류/죽은 코드는 고치지 말고 .docs/plans/tech-debt.md에 적고 넘어간다(범위 밖 청소는 별도 PR).

목표 주도 실행 (명령형을 검증 가능한 목표로 변환)

LLM은 검증 가능한 목표를 향해선 안정적으로 루프를 돈다. 모호한 명령형엔 표류한다. 모든 작업을 "X 한다 → Y 로 검증한다" 로 다시 적는다.

명령형 요청	검증 가능한 목표
"검증 로직 추가"	잘못된 입력에 대한 테스트를 먼저 작성 → 통과시키기
"버그 수정"	버그를 재현하는 테스트 작성 → 통과시키기
"X 리팩터링"	변경 전·후 기존 테스트가 모두 통과하는지 보장
"더 빠르게"	목표치 있는 벤치마크 작성 → 달성

여러 단계라면 PLAN.md에 단계마다 verify 줄을 함께 적는다:

1. 멱등키 검사 추가         → verify: 신규 단위 테스트 통과, 기존 결제 테스트도 그린
2. 웹훅 핸들러에 연결       → verify: 중복 웹훅 통합 테스트 통과
3. 24h 만료 처리            → verify: 타임트래블 테스트 통과, verify.sh 그린