LGES-OC5-PtoP-Welder/.claude/skills/ubisam-deliverables/references/00-harness.md

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.

데이터 흐름 (호스트 에이전트와 맞물림)

[호스트 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·06-procedure.md). 스타일 상수(색·폰트·테두리)는 xlsxfill.py에 내장돼 있다. (원본 템플릿 복제 방식은 폐기됨 — ref 파일에 의존하지 않기 위함) ⚠ 조건부서식은 xlsxfill.py에 없다(관련 API 0건). 필요하면 openpyxl.formatting을 직접 쓰되 색·폰트는 xlsxfill 상수를 쓰고, 재현 불가하면 지어내지 말고 "조건부서식 미이관" 을 로그에 명시한다 (ubisam-producer.md §에러 핸들링과 같은 규칙).