# 00 · 하네스 (호스트 프로젝트 맞물림 설계)

> 이 스킬이 **이미 CLAUDE.md·.claude가 있는 임의의 소스 레포**에 들어가 기존 에이전트와
> 충돌 없이 맞물려 동작하기 위한 계약. SKILL.md가 가장 먼저 참조한다.

## 비침습 계약 (절대 규칙)
- **읽기만**: 호스트의 `CLAUDE.md`, `.claude/`, `RULES.md`, `src/`·소스코드는 입력으로만 읽는다.
- **쓰기 격리**: 모든 생성/수정은 `docs/[Ubisam산출물]/` 하위로 한정.
- **경로 인용 의무 — 수단마다 방법이 다르다.** 이 경로의 대괄호는 문자클래스로 해석된다.
  **틀리면 에러가 아니라 조용히 0건**이 나오므로 검증이 통째로 헛돈다. (실측 확인)

  | 수단 | 올바른 방법 |
  |---|---|
  | 셸(bash) | 따옴표로 감싼다 — `"docs/[Ubisam산출물]/…"` |
  | `Glob` 도구의 `pattern` | **백슬래시 이스케이프** — `docs/\[Ubisam산출물\]/**/*.xlsx` (따옴표는 무효) |
  | `Grep` 도구의 `glob` | 동일하게 이스케이프하거나, 아래처럼 `path`로 분리 |
  | `Grep`/`Glob`의 `path` | **리터럴로 취급되므로 그대로** 쓴다 — `path: "docs/[Ubisam산출물]"` + `pattern: "**/*"` |
  | Python `os.path` | 무관 (그대로) |
- **임시 파일**: `py`는 네이티브 Windows 바이너리다. Git Bash(MSYS)가 POSIX 절대경로를 Windows
  경로로 **자동 변환**하므로 대개 동작하지만(실측 확인), 변환이 암묵적이라 파일이 어디에 떨어졌는지
  추적하기 어렵다. 임시 파일은 **저장소 상대경로**(`docs/[Ubisam산출물]/_workspace/`)에 만들어
  위치를 확정한다.
- **우선순위**: 호스트 루트 `rules.md`/`CLAUDE.md` > 본 산출물 규칙. 충돌 시 호스트 우선.
- **멱등**: 폴더·`.gitkeep`·`_task.md`는 "없으면 생성, 있으면 유지".
  **산출물 파일(xlsx·pptx·md)은 재생산 스크립트가 덮어쓴다** — 스크립트가 진실원이므로 매번 같은 결과가 나온다.
  손으로 편집한 산출물은 다음 재생산에서 사라지므로, 내용 변경은 스크립트·매핑표 쪽을 고친다.

## 입력 (호스트에서 읽는 진실원)
| 입력 | 용도 |
|---|---|
| 루트 `CLAUDE.md` | 설비·플랫폼·디바이스·시퀀스 등 프로젝트 사실 |
| 소스코드(`src/`,`Machines/` 등) | PLC/모션/IO/Vision 구성, 메인 시퀀스 추출 |
| `README*`, 설계 문서 | 보조 컨텍스트 |
| git 원격/폴더명 | 프로젝트 코드·명 자동 추정 |

추출 사실 → 산출물 필드 매핑은 [07-fill-mapping.md](07-fill-mapping.md).

## 데이터 흐름 (호스트 에이전트와 맞물림)
```
[호스트 CLAUDE.md + 소스] ──읽기──▶ (분석) ──▶ 사실 추출
        │                                         │
        ▼                                         ▼
   docs/[Ubisam산출물]/ 트리 생성 ◀── 매핑(07) ── 산출물 필드 채움
        │
        ▼
   _task.md 진행률 갱신 + [작업일지] 기록
```
- 스킬은 **온디맨드** 호출(트리거 문구). 호스트 에이전트 루프를 가로채지 않는다.
- 분석/검색은 호스트 에이전트의 도구(Grep/Read)를 그대로 활용.

## 프로젝트 자동 인식
1. `project_code`: git 원격명·폴더명·`CLAUDE.md`에서 추정 → 실패 시 사용자에게 질문.
2. `project_name`: `CLAUDE.md` 제목/설비명에서 추정.
3. 추정값은 `_meta/project.yaml`에 기록하고 **`[추론]`** 표기 (`rules.md` #15·#16 — 구 `(추정)` 대체).
   확정 전까지 문서에 `(제안)` 유지. 두 표기는 축이 다르다 — `[추론]`=확인 전 서술, `(제안)`=진실원 부재.

## 트리거 문구
- 생성: "산출물 구조 만들어줘", "Ubisam 트리 스캐폴딩".
- 채움: "설계 산출물 채워줘", "IO 맵 정의서 생성", "프로젝트 분석해서 산출물 채움".
- 갱신: "2.설계 진행률 갱신", "양산 단계 산출물 추가".

## 안전장치
- 호스트 파일 수정 요청이 들어오면 거부하고 `docs/` 내 대안 제시.
- 양식 엑셀은 **ref 파일 없이 from-scratch로 생성**한다([05-form-schemas.md](05-form-schemas.md)·[06-procedure.md](06-procedure.md)).
  **스타일 상수**(색·폰트·테두리)는 `xlsxfill.py`에 내장돼 있다. (원본 템플릿 복제 방식은 폐기됨 — ref 파일에 의존하지 않기 위함)
  ⚠ **조건부서식은 `xlsxfill.py`에 없다**(관련 API 0건). 필요하면 `openpyxl.formatting`을 직접 쓰되
  색·폰트는 `xlsxfill` 상수를 쓰고, 재현 불가하면 지어내지 말고 **"조건부서식 미이관"** 을 로그에 명시한다
  (`ubisam-producer.md` §에러 핸들링과 같은 규칙).