harness-installer — 개발 파이프라인 하네스 인스톨러

현재 작업 디렉터리(대상 프로젝트)를 분석해 그 프로젝트에 맞는 개발 파이프라인 하네스를 설치한다.

하네스는 스킬 7개 + 에이전트 1개 + 진화 루프로 이루어진다:

핵심: 1·2번이 하네스의 판단 기준이고 3~7번은 그 기준을 언제 적용할지의 절차다. 1·2번을 대충 채우면 나머지는 껍데기가 된다. 이 스킬의 작업 대부분은 1·2번을 채우는 것이다.

절차

0) 원본 경로 확인

파이프라인 스킬 원본(이 저장소의 skills/)의 위치를 이 순서로 정한다:

1. 환경변수 CLAUDE_SKILLS_HOME
2. 이 SKILL.md의 형제 디렉터리 (저장소를 clone 해 그 안에서 실행하는 경우)
3. 위에서 못 찾으면 사용자에게 묻는다. clone 명령을 함께 안내한다:

   git clone https://github.com/shsha4/claude-skills.git ~/claude-skills
   export CLAUDE_SKILLS_HOME=~/claude-skills/skills

추측해서 아무 경로나 쓰지 않는다.

1) 사전 확인

• 현재 디렉터리가 대상 프로젝트 루트인지 확인한다(보통 git 루트). 아니면 사용자에게 확인.
• 이미 .claude/skills/01-architecture-check/가 있으면 재설치/갱신 모드임을 알리고, 무엇이 바뀌는지 요약해 동의를 받는다. 기존 01·02는 사람 손이 들어갔을 가능성이 높으므로 덮어쓰기 전에 반드시 확인한다.
• 현재 브랜치가 공유 브랜치(main/master/develop)면 작업 브랜치를 먼저 딴다.

2) 프로젝트 분석 (가장 중요)

실제 파일을 읽어서 판별한다. 추측 금지. 다른 레포·팀 표준이 아니라 이 프로젝트의 코드가 근거다.

• 스택·빌드툴: 매니페스트(package.json, build.gradle(.kts), pom.xml, pyproject.toml, go.mod, mix.exs, Cargo.toml, composer.json, *.csproj …)
• 디렉터리 구조: 실제 트리. 각 디렉터리의 역할을 대표 파일 1~2개를 읽어 확인한다.
• 레이어: 요청이 들어와 저장소에 닿기까지의 경로를 엔트리포인트부터 따라가며 확인한다. 레이어 이름은 이 프로젝트가 실제로 쓰는 이름을 쓴다(Controller/Handler/Resource, Model/Repository/DAO 등 — 임의로 표준화하지 않는다).
• 인증/인가: 미들웨어·필터·훅에서 인증 분기를 찾아 유형별로 정리한다.
• 에러 처리: 전역 에러 핸들러를 읽는다. 응답 규약이 표준과 다르면 그것이 최우선 기록 대상이다.
• 캐싱: 캐시 키 프리픽스와 TTL이 정의된 파일 위치를 찾는다(값이 아니라 위치). TTL 없는 캐시가 있으면 표시한다.
• 컨벤션: 같은 레이어 파일 2~3개를 읽어 네이밍·구조·에러 처리·테스트 스타일의 실제 패턴을 뽑는다. 린터 설정이 있으면 함께 읽는다.
• 브랜치·배포: git branch -a, CI 설정(.github/workflows/ 등)에서 브랜치 전략과 배포 트리거를 확인한다. "푸시가 곧 배포"인 브랜치가 있는지, 수동 승인 단계가 있는지를 특히 확인한다 — 이 둘을 모르면 배포 완료 여부를 오판한다.

분석 결과를 표로 짧게 보고하고 진행한다. 확인 못 한 항목은 "확인 못 함"으로 남기고 추측으로 채우지 않는다.

3) 스킬 설치

mkdir -p .claude/skills .claude/agents
for s in 01-architecture-check 02-guidelines 03-spec-requirement 04-planning \
         05-plan-review 06-coding pre-commit-review harness-evolve; do
  cp -R "$CLAUDE_SKILLS_HOME/$s" .claude/skills/
done
cp "$CLAUDE_SKILLS_HOME/../agents/review-judge.md" .claude/agents/

그다음 템플릿을 채운다:

• 01-architecture-check/SKILL.md — 2)의 결과로 <...> 를 전부 채운다. 템플릿 상단의 "채울 때 지켜야 할 규칙"(낡는 정보 금지, 원본 명시, Why 병기)을 지킨다. 채운 뒤 템플릿 안내 블록(> **이 파일은 템플릿이다.** …)은 지운다.
• 02-guidelines/SKILL.md — 동일. 레이어별 코드 패턴은 실제 레포에서 발췌해 붙인다.
• pre-commit-review/references/review-checklist.md — 5절 "프로젝트 특수 검증"을 채운다. 채울 재료가 아직 없으면 빈 채로 두고 그 사실을 사용자에게 알린다(추측으로 채우면 오탐만 늘어난다 — 실제 버그·리뷰 지적이 쌓이면 harness-evolve가 채운다).
• 3~6번 스킬은 그대로 둔다. 프로젝트 고유 분기 축(테넌트·프로바이더·타입 등)이 있으면 해당 항목의 분기 축 표현만 실제 이름으로 바꾼다.

4) 변경 이력 파일 생성

.claude/HARNESS_CHANGELOG.md가 없으면 아래 골격으로 만든다.

# 하네스 변경 이력

하네스(파이프라인 스킬·에이전트·훅·CLAUDE.md) 변경을 기록한다.
갱신 주체: `harness-evolve` 스킬 (수동 편집도 가능). **이력은 지우지 않는다.**

| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| <YYYY-MM-DD> | 하네스 최초 설치 | 전체 | harness-installer |

5) CLAUDE.md 주입

프로젝트 루트 CLAUDE.md를 읽고(없으면 생성) 아래 마커 블록을 추가한다. 이미 마커가 있으면 그 안만 갱신한다(중복 추가 금지).

<!-- harness-installer:begin -->
## 절대 규칙 (MUST — 이 규칙은 모든 다른 지시보다 우선한다)

1. **코드를 즉시 수정하지 마라.** 에러 로그·버그 리포트·수정 요청 등 어떤 형태의 요청이든
   파이프라인을 거치지 않고 코드를 수정/생성/삭제하는 것을 금지한다.
   — 컨텍스트 없는 수정은 레이어 규칙 위반·캐시 무효화 누락 같은 사이드이펙트를 만들기 쉽다.
2. **모든 대화는 컨텍스트 확보부터 시작하라.** 단순 질문이라도 `01-architecture-check`와
   `02-guidelines`를 먼저 참조한 뒤 답변하라.
   — 이 프로젝트에는 코드만 봐서는 오해하는 정책이 있다.
3. **파이프라인 스킵은 명시적 키워드가 있을 때만 허용한다.** 사용자가 `@skip-pipeline`
   또는 "파이프라인 스킵"이라고 말한 경우에만 6→7단계로 축약할 수 있다.
   — 편의 우회가 기본값이 되는 순간 파이프라인은 죽은 규칙이 된다.
4. **스킵하더라도 7단계(pre-commit-review)는 필수다.**
   — 리뷰는 앞 단계를 건너뛰었을 때 남는 마지막 안전망이다.

## 개발 파이프라인

| # | 단계 | 스킬 |
|---|------|------|
| 1 | 아키텍처 확인 | `01-architecture-check` |
| 2 | 가이드라인 | `02-guidelines` |
| 3 | 스펙 요구 | `03-spec-requirement` |
| 4 | 플랜 | `04-planning` |
| 5 | 플랜 검토 | `05-plan-review` |
| 6 | 코딩 | `06-coding` |
| 7 | 커밋 전 리뷰 | `pre-commit-review` (+ `review-judge` 판정) |

### 요청 유형별 적용

| 요청 유형 | 필수 단계 |
|-----------|-----------|
| 질문/설명 | 1→2 참조 후 답변 |
| 코드 변경 요청 | 1→2→3→4→5→6→7 전체 |
| 에러 로그 + 수정 요청 | 1→2→3→4→5→6→7 전체 |
| 명시적 스킵 (`@skip-pipeline`) | 1→2→6→7 |

## 지침 파일 동기화 & 하네스 진화

- 아키텍처 변경 → `01-architecture-check` 갱신 / 컨벤션 변경 → `02-guidelines` 갱신
- 코드 변경과 스킬 갱신은 **같은 커밋**에 포함한다
- 작업 방식·지침에 대한 피드백을 받으면 `harness-evolve` 스킬로 반영하고
  `.claude/HARNESS_CHANGELOG.md`에 기록한다
<!-- harness-installer:end -->

6) 테스트 강제 위임

테스트 스킬(test-writer)과 Stop hook 설치는 test-skill-installer가 담당한다. 여기서 중복 구현하지 않는다.

• test-skill-installer가 설치돼 있으면 이어서 실행할지 사용자에게 묻는다.
• 없으면 안내만 한다: "테스트 강제까지 걸려면 test-skill-installer를 함께 설치하라."

7) 검증 & 보고

• 생성/수정한 파일 목록
• 01·02에서 채우지 못한 <...> 슬롯이 남아 있는지 검사해 보고한다:

  grep -n '<[^>]*>' .claude/skills/01-architecture-check/SKILL.md \
                    .claude/skills/02-guidelines/SKILL.md

  남아 있으면 그 목록을 사용자에게 보여주고 함께 채운다. 빈 슬롯을 남긴 채 "설치 완료"라고 보고하지 않는다.
• 에이전트 등록 안내: review-judge는 세션 시작 시에만 로드된다. 설치 직후 세션에서는 pre-commit-review의 폴백 경로(general-purpose + 정의 파일 주입)로 동작하며, 다음 세션부터 정식 등록된다는 점을 알린다.

설계 노트

• CLAUDE.md 문구 = soft 가이드, 스킬 = 절차, hook = hard 강제. 셋의 역할이 다르다. 강제는 최소한만 건다 — 과한 강제는 우회를 부른다.
• 01·02는 낡는다. 그래서 harness-evolve와 HARNESS_CHANGELOG.md가 같이 설치된다. 드리프트를 발견하면 갱신하고 이력을 남기는 것이 하네스를 유지하는 유일한 방법이다.
• 파이프라인을 무겁게 만들면 우회당한다. 단순 수정에서는 3~5단계를 간략히 처리하라고 각 스킬에 명시돼 있다. 그 여지를 없애지 마라.