| name | harness-view-build |
| description | AgentZero Dev 하네스 뷰어(Home/harness-view/) 의 부분 업데이트 빌드 스킬.
콘텐츠가 추가/수정되면 인덱스 매니페스트만 부분 재생성해 즉시 UI에 반영한다.
네 가지 모드:
1) BUILDER 모드 — 인덱스 매니페스트 재생성 (콘텐츠 변경 반영용)
2) CREATOR 모드 — 뷰어 코드 자체를 만들거나 개선 (HTML/CSS/JS)
3) DEV SERVER 모드 — 로컬 dev 서버(127.0.0.1:8765, 인증 없음) 구동
4) PDSA UPDATE 모드 — harness/logs 최신 5개를 분석해 대시보드 PDSA 섹션 데이터 갱신
사용자 발화에 따라 네 모드 중 하나로 분기한다.
BUILDER 모드 트리거 (운영 — 컨텐츠 갱신):
- "하네스 뷰어 최신으로 갱신", "하네스뷰어 갱신", "harness-view 갱신"
- "하네스 뷰어 빌드", "harness-view 빌드", "뷰어 인덱스 재생성"
- "하네스 뷰어 새로고침", "뷰어 매니페스트 다시"
- "하네스 뷰어에 OOO 안 보임", "방금 추가한 파일이 뷰어에 안 보임"
- harness/{docs,agents,knowledge,logs,engine}, Docs/, Docs/design,
Docs/harness/template 중 하나라도 추가/삭제/수정 후 "뷰어에 반영" 언급 시 트리거.
CREATOR 모드 트리거 (개발 — 뷰어 자체 손보기):
- "하네스뷰 OOO 개선해줘", "하네스뷰어 OOO 개선", "harness-view OOO 개선"
- "하네스뷰에 OOO 추가해줘", "하네스뷰어 OOO 메뉴 추가"
- "하네스뷰 OOO 화면 만들어줘", "하네스뷰어 새 뷰", "harness-view 새 메뉴"
- "하네스뷰 OOO 버그", "하네스뷰어 깨짐 수정", "harness-view 디자인 변경"
- "하네스뷰 펜슬렌더 개선", "하네스뷰 MD 뷰어 개선", "spec card 개선"
- Home/harness-view/ 하위 css/js/index.html 파일을 수정·생성해야 하는 모든 요청
DEV SERVER 모드 트리거 (검증 — 로컬 서버 기동):
- "하네스뷰 데브서버 구동해", "하네스뷰 데브서브 구동해", "하네스뷰 dev 서버 구동"
- "하네스뷰 로컬 서버 띄워", "하네스뷰 서버 기동", "harness-view 로컬 서버"
- "하네스뷰 로컬 테스트 준비", "하네스뷰 playwright 서버", "harness-view serve"
- harness-view 를 Playwright 로 검증하기 직전 로컬 서버가 필요하면 무조건 트리거
PDSA UPDATE 모드 트리거 (콘텐츠 — 최근 로그 분석→인사이트 갱신):
**operator 가 명시적으로 부를 때만** 발동 — publish / 일반 콘텐츠 갱신 시
자동으로 따라가지 않는다. 의미 있는 활동(미션 묶음 마감, 릴리즈 게이트
통과, 큰 인사이트 발생) 이 쌓였다고 operator 가 판단할 때만 트리거.
- "하네스뷰 PDSA 업데이트", "하네스뷰 PDSA 업데이트해", "하네스뷰 PDSA 갱신"
- "PDSA 학습 다시 뽑아", "PDSA 인사이트 새로 정리", "PDSA 다시 분석"
- "대시보드 PDSA 최신화", "harness-view PDSA refresh"
- harness/logs 에 새 로그가 쌓였고 대시보드의 PDSA 섹션을 최신화하고 싶을 때 트리거
|
| allowed-tools | Bash, Read, Write, Edit, Glob, Grep |
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)
| 화면 영역 | 소스 경로 | 비고 |
|---|
| Dashboard "Build Log" 섹션 | harness/docs/*.md | semver-desc 정렬 (vN.N.N 카드). UI 라벨 (EN 기본 / KO 토글) 은 dashboard.js 의 T dict 에 있음. |
| Dashboard "Recent Updates" | Home/harness-view/data/news.json | 정적 · 이중언어. headline / narrative / highlights[].label,text / prompts[].tag,text 는 { en, ko } 객체 (2026-05-05~). 수동 갱신 시 두 언어 모두 채울 것. |
| Dashboard "PDSA Learning" | Home/harness-view/data/pdsa-insight.json | 정적 · 이중언어. sources[].title / tried[] / solved[] / remaining[] / learned.lead / learned.body 는 { en, ko } 객체. PDSA UPDATE 모드로 operator 가 명시 호출할 때만 재생성. publish 시 자동 갱신 금지 — 의미 있는 활동(미션 묶음 마감 / 릴리즈 통과 / 큰 인사이트) 이 쌓였다고 operator 가 판단할 때만 트리거. |
| Dashboard "Contributors" | git log on harness/, Docs/, Home/harness-view/ (union, dedup by SHA) | 자동. 매 build 마다 재계산 — CI 가 doc-v* push 마다 build 를 다시 돌리므로 publish 시 항상 최신. 별도 손작업 불필요. 데이터 (이름/SHA) 는 언어 중립 — 주변 라벨만 dashboard.js 의 T dict 에서 EN/KO 전환. |
| Workflow | Home/harness-view/data/workflow-graph.json | 정적. mermaid 그래프 7개 (스킬 시스템 노드는 의도적 제외) |
| Roles | harness/agents/*.md | 동적. 상세 페이지에 spec card |
| Skills | Docs/harness/template/<skill>/SKILL.md | in-repo 스냅샷. SKILL.md 본문은 인덱스에 인라인 임베드. 사용자 수동 동기화 |
| Knowledge → Expert | harness/knowledge/**/*.md (재귀) | 동적 |
| Knowledge → Tech / Domain (TECH-DOC) | Docs/**/*.md | 동적 트리 |
| Activity Log | harness/logs/<subfolder>/*.md | 동적. subfolder 이름 = 카테고리 태그 (qa/ba/code/cto 같은 hardcoded 없음) |
| Product Design | Docs/design/*.pen | 동적. parsePen + renderFrame |
| Product Intro | Home/index.html | iframe 임베드 |
모드 판별
| 사용자 의도 | 모드 | reference |
|---|
| 새 .md 파일 추가 후 뷰어에 반영 | BUILDER | references/builder.md |
| 운영 사이트 갱신 / 매니페스트 재빌드 | BUILDER | references/builder.md |
| 새 메뉴 / 화면 만들기 | CREATOR | references/creator.md |
| 뷰어 컴포넌트 / 디자인 개선 | CREATOR | references/creator.md |
| 펜슬 렌더 / MD 뷰어 / spec-card 수정 | CREATOR | references/creator.md |
| 버그 수정 (코드 변경 필요) | CREATOR | references/creator.md |
| 로컬 dev 서버 기동 (Playwright 검증 준비) | DEV SERVER | 본 파일 아래 절차 |
| 대시보드 PDSA 섹션 최신화 (로그 5개 재분석) | PDSA UPDATE | 본 파일 아래 절차 |
| 컨텐츠와 코드 둘 다 변경 필요 | CREATOR → BUILDER 순차 | |
판별이 모호하면 사용자에게 한 줄 확인.
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 파일 읽지 말고 즉시 아래 절차 수행.
절차
-
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
-
Preflight 로그 해석 — serve.js 는 기동 전 메타데이터 staleness 를 자동 판단:
[preflight] rebuild — ... : 소스가 최신 → build-indexes.js 자동 실행 후 기동[preflight] up-to-date — ... : 이미 최신 → skip 하고 바로 기동[preflight] skipped — --no-build flag : 사용자가 명시 skip
-
기동 확인 — 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)
-
이미 떠 있으면 (EADDRINUSE) — 새로 띄우지 말고 URL 만 안내.
-
사용자에게 한 줄 보고: 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 을 재생성한다.
절차
-
대상 로그 선정 — Home/harness-view/indexes/harness-logs.json 의 items 에서:
date 가 오늘부터 14일 내- 최신순(이미 정렬됨) 상위 5건
- 카테고리는 혼합 허용 (subfolder 이름이 그대로 카테고리)
-
각 로그 파일 읽기 — Read harness/logs/<category>/<file>
-
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 })
-
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 는 항상 두 언어를 채울 것.
-
인덱스 재빌드 불필요 — data/*.json 은 매니페스트 대상 아님.
-
사용자 보고 — 분석된 로그 5건 + 핵심 학습 리드 + 로컬 URL.
수행 패턴
- 모드 결정 — 위 표에서 매칭.
- reference 로드 —
Read .claude/skills/harness-view-build/references/<mode>.md
- 그 안의 절차 그대로 수행.
- 변경분 보고 — 변경 파일 / URL / 빌드 상태.
- 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 로 본다.
게시 명령 (캐노니컬)
git tag doc-v1.0.0
git push origin doc-v1.0.0
태그 네이밍: 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/).
