Imported from psmon/AgentZeroLite (.claude/skills/harness-view-build/SKILL.md). Install upstream with npx skills add psmon/AgentZeroLite --skill harness-view-build. Copyright stays with the author.

harness-view-build — 부분 업데이트 빌드 스킬 (AgentZero Dev 변형)

이 스킬은 네 가지 책임을 가진다. 사용자 발화에서 모드를 판별한 뒤, BUILDER/CREATOR 는 해당 reference 파일을 즉시 Read 도구로 읽어 그 안의 절차를 따르고, DEV SERVER / PDSA UPDATE 는 본 파일 하단 인라인 절차를 바로 수행한다.

이 변형의 정체성 본 스킬은 다른 프로젝트의 하네스 뷰어 빌드 스킬을 베이스로 가져와 AgentZeroLite 에 맞게 적응된 버전이다. 핵심 차이:

• 위치: harness-view/ → Home/harness-view/ (Home 하위에 둠)
• 사이트 제목: AgentZero Dev (sidebar logo + page title)
• 언어: 산출물 모두 영문 전용 (UI 라벨, 빈 상태, PDSA 본문 등). 사용자 대화는 한국어.
• GitHub Pages 배포 = .github/workflows/pages.yml — doc-v* 태그 푸시로만 발동 (2026-04-28 이후 tag-gated). 일반 main push 는 Pages 를 건드리지 않으므로 harness/logs 가 잦게 늘어나도 CI 가 돌지 않는다. CI 는 node Home/harness-view/scripts/build-indexes.js 로 매니페스트만 갱신한 뒤 repo 전체 (path: .) 를 artifact 로 업로드. 뷰어는 harness/, Docs/ 의 upstream MD 를 ../../<rel> 로 직접 fetch — 단일 진실 원천이고 미러 없음 (2026-05-04 이전엔 Home/_resources/ 로 복제했으나 dual-management 이슈로 폐기). 운영 게시 명령은 본 파일 하단 "Publish — doc version tag bump" 섹션 참조.
• .nojekyll 필수 — repo root + Home/ 양쪽에 둔다 (Jekyll 이 underscore-prefix 디렉토리를 자동 제외하지 못하도록).
• 외부 절대경로 참조 안티패턴 금지 — 모든 데이터 소스는 in-repo.

데이터 소스 매핑 (canonical for this project)

모드 판별

판별이 모호하면 사용자에게 한 줄 확인.

Data contracts (다른 스킬이 봐야 할 파일)

뷰어 인덱서 (Home/harness-view/scripts/build-indexes.js) 가 어떤 파일명· frontmatter 모양만 받아들이는지의 단일 진실 원천:

references/data-contracts.md

이 스킬 외부의 워크플로우 (특히 harness-kakashi-creator 의 tamer mission dispatch) 가 harness/missions/ · harness/logs/mission-records/ 에 파일을 쓸 때, 이 contract 를 먼저 확인해야 한다. 가장 자주 어기는 규칙은 mission record 파일명이 ^M\d+\b 로 시작해야 한다는 것 — timestamp prefix 를 붙이면 인덱서가 매칭에 실패해서 Missions 카드의 recordFile 이 null 로 남는다.

harness/knowledge/tamer/missions-protocol.md 와 harness/agents/tamer.md 의 관련 단계가 이 파일을 backlink 한다.

DEV SERVER 모드 — 로컬 dev 서버 기동 (인라인 절차)

사용자가 "하네스뷰 데브서버 구동해" 등을 말하면, reference 파일 읽지 말고 즉시 아래 절차 수행.

절차

1. Bash 로 background 실행 (server 는 상주 프로세스라 run_in_background: true 필수)

   node Home/harness-view/scripts/serve.js
   

   • 포트 지정: node Home/harness-view/scripts/serve.js 9000
   • 메타 자동빌드 skip: node Home/harness-view/scripts/serve.js --no-build

2. Preflight 로그 해석 — serve.js 는 기동 전 메타데이터 staleness 를 자동 판단:

   • [preflight] rebuild — ... : 소스가 최신 → build-indexes.js 자동 실행 후 기동
   • [preflight] up-to-date — ... : 이미 최신 → skip 하고 바로 기동
   • [preflight] skipped — --no-build flag : 사용자가 명시 skip

3. 기동 확인 — Bash 출력에 다음이 보이면 OK

   AgentZero Dev Harness — local server (no auth)
   URL        : http://127.0.0.1:8765/Home/harness-view/
   Screenshots: tmp/playwright/ (gitignored)
   Build log  : Home/harness-view/.meta-build.log (gitignored)
   

4. 이미 떠 있으면 (EADDRINUSE) — 새로 띄우지 말고 URL 만 안내.

5. 사용자에게 한 줄 보고: URL + preflight 결과 (rebuild / up-to-date) + 종료법.

메타데이터 추적 체계

• Home/harness-view/indexes/_meta.json : 마지막 빌드 시각·duration·trigger·스캔 경로 스냅샷.
• Home/harness-view/.meta-build.log : 빌드 이벤트 append-only 로그 (gitignored).
• Staleness 판정 : _meta.json.builtAtMs vs 스캔 경로들 중 최대 mtime. 소스가 최신이면 재빌드.
• Trigger 값 : manual (CLI 직접) / serve (serve.js preflight) / BUILD_TRIGGER env.

Playwright 검증 연계

DEV SERVER 모드로 서버 기동 후, 사용자가 Playwright 검증 요청 시:

• mcp__playwright__browser_navigate → http://127.0.0.1:8765/Home/harness-view/#<menu>
• mcp__playwright__browser_take_screenshot filename="tmp/playwright/<name>.png" (gitignored 경로)
• 운영 URL (GitHub Pages) 은 이 스킬에서 직접 검증 안 함 — push 후 사용자가 확인.

왜 Node 서버인가

• py -m http.server 는 Python 환경 의존. Node 는 repo 내 다른 스크립트들도 이미 사용.
• serve.js 는 127.0.0.1 로만 바인딩 + 인증 없음 = 로컬 전용 안전.
• Cache-Control: no-store 로 개발 중 캐시 이슈 없음.

PDSA UPDATE 모드 — 최근 로그 분석→PDSA 섹션 갱신 (인라인 절차)

사용자가 "하네스뷰 PDSA 업데이트해" 등을 말하면, reference 파일 읽지 말고 즉시 아래 절차 수행. 대시보드의 PDSA 학습 섹션이 읽는 Home/harness-view/data/pdsa-insight.json 을 재생성한다.

절차

1. 대상 로그 선정 — Home/harness-view/indexes/harness-logs.json 의 items 에서:

   • date 가 오늘부터 14일 내
   • 최신순(이미 정렬됨) 상위 5건
   • 카테고리는 혼합 허용 (subfolder 이름이 그대로 카테고리)

2. 각 로그 파일 읽기 — Read harness/logs/<category>/<file>

   • 앞부분 40~80줄 정도면 충분.

3. PDSA 4관점으로 합성 — EN/KO 두 언어 동시 산출 (대시보드는 EN 기본 + KO 토글, 두 언어 다 비어 있으면 안 됨). 글로벌 audience 기준으로 EN 을 먼저 쓰고, 같은 의미의 KO 를 한 줄씩 짝지어 작성:

   • tried (Plan + Do) : 무엇을 시도했나. 3~5 항목, 각 항목 { en, ko }.
   • solved : 완료/확정된 것. 2~4 항목, 각 항목 { en, ko }.
   • remaining : 미해결/차단/다음 사이클. 2~4 항목, 각 항목 { en, ko }.
   • learned (Study + Act) : 가장 중요. 반복된 Fail · 우연한 발견 · 재사용 가능한 프리미티브.
     • lead : 한 문장 핵심 통찰 ({ en, ko })
     • body : 2~4문장 상세 근거 + 다음 액션 ({ en, ko })

4. Home/harness-view/data/pdsa-insight.json 덮어쓰기 (이중언어 스키마):

   {
     "analyzedAt": "YYYY-MM-DD",
     "windowDays": 14,
     "sources": [
       {
         "date": "...", "time": "...", "category": "<subfolder>",
         "file":  "harness/logs/<subfolder>/...md",
         "title": { "en": "...", "ko": "..." }
       }
     ],
     "tried":     [{ "en": "...", "ko": "..." }],
     "solved":    [{ "en": "...", "ko": "..." }],
     "remaining": [{ "en": "...", "ko": "..." }],
     "learned":   {
       "lead": { "en": "...", "ko": "..." },
       "body": { "en": "...", "ko": "..." }
     }
   }

   레거시 (string-only) 항목도 렌더 시 t() 가 그대로 폴백하므로 점진적 마이그레이션 가능 — 단, 새로 작성하는 PDSA 는 항상 두 언어를 채울 것.

5. 인덱스 재빌드 불필요 — data/*.json 은 매니페스트 대상 아님.

6. 사용자 보고 — 분석된 로그 5건 + 핵심 학습 리드 + 로컬 URL.

수행 패턴

1. 모드 결정 — 위 표에서 매칭.
2. reference 로드 — Read .claude/skills/harness-view-build/references/<mode>.md
3. 그 안의 절차 그대로 수행.
4. 변경분 보고 — 변경 파일 / URL / 빌드 상태.
5. git commit / push 는 사용자 명시 요청 시에만 — main 으로의 일반 push 는 더 이상 Pages 를 건드리지 않는다 (harness/logs 잦은 변경으로 인한 무의미한 재배포 방지). 운영 사이트에 반영하려면 doc-v* 태그를 푸시해야 한다. 자세한 명령은 본 파일 하단 "Publish — doc version tag bump" 섹션 참고.

Publish — doc version tag bump (운영 게시 게이트)

Pages 배포는 doc-v* 태그 푸시로만 발동한다 (2026-04-28 이후). 일반 push 는 Pages 를 건드리지 않으므로 harness/logs 가 늘어나도 CI 가 돌지 않는다. 필요할 때 사용자가 명시적으로 버전을 올려 게시한다.

Workflow 다이어그램 + auto/manual 위젯 매트릭스: harness/engine/harness-view-publish.md. 이 스킬은 그 엔진의 interface, 엔진은 workflow contract — 두 곳이 다르게 흐르면 엔진을 single source of truth 로 본다.

게시 명령 (캐노니컬)

# 1) 변경분이 main 에 모두 commit/push 된 상태에서
git tag doc-v1.0.0          # 새 doc 버전 (앱 버전 v* 와는 별개 namespace)
git push origin doc-v1.0.0  # 태그 push → pages.yml 발동 → 30~60초 후 Pages 갱신

태그 네이밍: doc-v<major>.<minor>.<patch> (예: doc-v1.0.0, doc-v1.1.0, doc-v2.0.0). 앱 릴리스 태그 v* (release.yml 가 처리) 와 충돌 없음.

트리거 흐름 (CI-time 미러 포함)

git tag doc-v1.0.0 && git push origin doc-v1.0.0
   → pages.yml 트리거 (tags: doc-v*)
   → CI checkout 이 태그가 가리키는 커밋 트리 확보
   → CI: node Home/harness-view/scripts/build-indexes.js
        (indexes/*.json + Home/_resources/{Docs,harness} 새로 생성)
   → CI: actions/upload-pages-artifact path=Home
   → Pages 재배포 (30~60초)

Claude 가 이 스킬에서 알아야 할 것

• 사용자가 harness/ · Docs/ 에 파일을 추가/수정한 뒤 "뷰어에 반영" 류로 트리거하면, 로컬에서 BUILDER 돌리지 않아도 됨. 다만 일반 push 만으로는 운영 사이트가 갱신되지 않는다. 사용자가 "Pages 에도 올려" / "운영 갱신" / "배포" 류를 함께 말한 경우에만 태그 bump 까지 안내한다.
• 로컬 dev 서버로 push 전에 미리 보고 싶을 때 BUILDER (또는 그냥 serve.js) 를 돌리는 가치는 그대로 — preview 의도. 운영 반영과는 무관.
• 매니페스트 (Home/harness-view/indexes/*.json) 는 아직 git tracked. CI 가 태그 트리에서 다시 빌드해 artifact 에 덮어쓰므로, git tree 의 인덱스가 stale 해도 Pages 는 항상 신선한 인덱스를 서빙 (functional issue 없음).
• Home/_resources/ 는 절대 git add 하지 말 것 — .gitignore:44 가 막지만, 실수로 unignore 추가하면 a55c781 의 19k 줄 중복이 다시 들어감.
• escape hatch: GitHub Actions UI 에서 pages.yml 의 Run workflow 버튼 (= workflow_dispatch) 으로 태그 없이도 강제 재배포 가능. 일회성 핫픽스용.

배포 안 하고 싶을 때

routine 작업 (PDSA 갱신 / 새 로그 추가 / 스킬 동기화 등) 은 그냥 commit + push 로 끝. Pages 는 그대로 두면 됨. 다음번 의미 있는 마일스톤에서 한 번에 묶어서 doc-v<next> 태그로 게시.

컨텍스트 — AgentZero Dev 하네스 뷰어란

Home/harness-view/ 는 AgentZeroLite 레포 안의 개발용 정적 사이트다.

• 설계 First: Pencil(.pen) 로 화면 설계 후 HTML 로 구현
• 디자인 원본: Docs/design/design.pen (앱디자인 단일 펜) — Product Design 메뉴에 노출
• 두 가지 데이터 모드: 리소스참고 (동적 매니페스트) / 사전구현 (정적 JSON)
• 산출물 언어: 영문 기본 + 한국어 토글. 글로벌 audience 가 1순위라 EN 이 default. KO 는 운영자/한국어 독자 공유용으로 동시 유지. 토글은 Home/harness-view/js/components/bilingual.js 가 단일 진실 원천 — 새 뷰가 bilingual 을 지원해야 하면 그 컴포넌트의 getLang / makeLangToggle / t 를 그대로 import.

자세한 디렉토리 구조·라우팅·컴포넌트 패턴은 references/creator.md, 빌드 명령은 references/builder.md 참조.

제약

• 산출물 텍스트는 EN 기본 + KO 동시. 사전구현 JSON 의 사람이 쓴 필드는 { en, ko } 객체로 두고, 뷰는 bilingual.js#t() 로 해석. 하드코딩 UI 라벨은 뷰 파일 상단의 T dict 에 모아 lbl(T.<key>, lang, ...args) 로 렌더 — 어느 언어가 빠지면 EN 폴백, EN 도 없으면 첫 값. (예: Home/harness-view/js/views/dashboard.js 의 T)
• 사용자와의 대화는 한국어.
• 빌드/번들 도구를 추가하지 않는다 — vanilla HTML + ES Modules + CDN 만 사용.
• GitHub Pages 배포 자동화는 이 스킬 범위 밖. 사용자가 직접 commit/push.
• 외부 절대경로 참조 금지 — 모든 데이터는 in-repo. 외부 시스템에서 가져오는 자원은 사용자가 in-repo 스냅샷으로 동기화한다 (예: Skills → Docs/harness/template/).