08de54c4958a4c9040eb2c5af74cde19ee55e54e
10
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
1b3eee41e3 |
test(claude): 스킬이 인용하는 절 이름을 문서 제목과 대조한다
문제: 스킬은 정본 문서의 절을 「이름」이나 「N절」로 가리킨다. 문서 검사 (verify:documentation)는 경로만 보므로, 문서를 번역하거나 절을 바꾸면 인용한 절이 사라져도 통과한다. 지금 9곳이 그렇다. - fe-structure: 「Decision rule」(지금 「판단 규칙」), 「The adapter kernel」(지금 「adapter kernel」) - fe-a11y: 「What the automated run scans」, 「Included primitives」 - fe-design-system: 「Arbitrary-value policy」 - fe-performance: 「Service Worker steps」 - fe-ux: 「routing 6.4절」이 앞 인용(typescript 설계서)의 6.4절로 읽힌다. 그 설계서에는 6.4절이 없다. - desktop-gates: 경로 없이 `gates.md`·`operate.md`라고만 쓴다. 고른 방법: scripts/tests/test_claude_setup.py의 SkillTest에 시험을 더한다. - 모든 repo 스킬에서 읽는 인용 꼴: `경로.md` 「이름」, `경로.md` N절 (3·4절, 6.1·11절), `경로.md` N절 「이름」, 같은 문서 N절, `fe-x` 「이름」(다른 스킬의 절). - 인용마다 대상 파일에 그 제목이 있는지 본다. 제목은 앞 번호와 끝 괄호를 뗀 꼴도 받는다. 「이름:」만 있는 소제목 줄도 받는다. 코드 블록 안 제목은 보지 않는다. - 파서와 제목 읽기를 따로 고정하는 시험 둘을 함께 둔다. - 9곳은 지금 제목으로 고치고, 짧게 쓴 경로는 전체 경로로 쓴다. 버린 대안: 문서 검사(scripts/lib/docs-system.ts)에 넣는 방법. 스킬 구성의 다른 규칙이 이미 이 시험 파일에 있고, `scripts/verify.sh hooks`로 노트북에서 바로 돈다. 위험: 「 」 안의 말이 절 이름이 아닌데 경로 바로 뒤에 붙으면 거짓 실패가 난다. 경로 뒤의 —, 괄호, 문장 끝에서 읽기를 멈춰 지금 196개 인용에는 그런 경우가 없다. 「N절」이 다른 문서를 줄여 부르면(「routing 6.4절」) 앞 경로로 읽으니 전체 경로로 쓴다. 이 시험은 게이트가 아니라 hooks 단계에서 돈다. 검증: python3 -m unittest scripts.tests.test_claude_setup. - 고치기 전: 새 시험이 9곳(과 처음 판에서 거짓 실패 2곳)을 냈다(RED). - 고친 뒤: 24개 모두 통과했다. 인용 196개를 확인했다. |
||
|
|
b5e7f54bd1 |
feat(claude): 분야 전문가를 지식 스킬 아홉 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다
frontend-quality-gates / merge / static checks (pull_request) Successful in 3m3s
frontend-quality-gates / merge / tests (pull_request) Failing after 13m34s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 9m26s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
문제: 하네스에 분야 지식이 없다. QA·디자인/UX·디자인 시스템·React·폴더 구조·시험 환경·접근성·성능·보안의 이 repo 규칙(배럴 경계, 토큰 밖 색 금지, axe 태그 범위, 예산, FE-GATE 실행법 등)은 문서와 검사기에 흩어져 있고, 여러 분야에 걸친 일을 누가 보고 어떻게 합치는지 정한 곳이 없다. 고른 방법(소유자 결정 2026-11-11 「W3 설계대로」, 백엔드와 같은 모양): - 지식 스킬 fe-* 9개(.claude/skills/). paths를 걸어 그 분야 파일을 만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 → 검증 → 이 repo에서 정한 것 순서. 초안은 이 repo 문서만 본 서브에이전트가 썼고 glob 75개가 모두 파일에 걸리는 것을 확인했다. - 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는 fe-structure를, verify-app은 fe-qa를 미리 싣는다(QA 탐색 차터). - .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의 「함정」·「검증」을 보게 하는 두 줄. - docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도(백엔드 repo로 가는 API 계약 차이는 총괄을 거침)·충돌·비용. 루트 AGENTS.md·CLAUDE.md 한 줄씩, README 3절 4단계와 delegate.md 4.3절에 가리키는 말. - 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 미리 싣는 스킬, 지식 스킬의 paths·설명 300자·금지어·절 순서·150줄·glob이 파일에 걸림, 명단이 모든 전문가를 담음, 규칙 목록에 expert-skills. - 문서 PR #15와 겹치지 않게 docs/는 docs/work/만 건드렸다. 버린 대안: 분야마다 서브에이전트(QA·디자인·접근성 …). Anthropic 2026-10-22·2026-01-23·2026-04-07 글이 반대하고, 설명이 모든 세션에 든다. 위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이 병합돼야 받는다. fe-ux·fe-a11y의 paths는 템플릿에 기능 화면이 없어 src/presentation/**까지만 건다(기능이 생기면 넓힌다). 검증: scripts/verify.sh docs → rc=0, scripts/verify.sh hooks → 68건 통과. 새 시험은 조건을 깰 때마다 실패했다. desktop merge 단계는 이 커밋 뒤에 돈다. |
||
|
|
5fab0e462a |
fix(scripts): adapter 목록 합계를 맞추고 verify.sh parts에 SOURCE_DATE_EPOCH를 준다
frontend-quality-gates / FE-GATE-001 / manifest-lockfile (pull_request) Failing after 24s
frontend-quality-gates / FE-GATE-002 / lint (pull_request) Failing after 27s
frontend-quality-gates / FE-GATE-003 / typecheck (pull_request) Failing after 27s
frontend-quality-gates / FE-GATE-004 / runtime-schema (pull_request) Failing after 36s
frontend-quality-gates / FE-GATE-005 / unit (pull_request) Failing after 25s
frontend-quality-gates / FE-GATE-007 / integration (pull_request) Failing after 26s
frontend-quality-gates / FE-GATE-011 / build (pull_request) Failing after 26s
frontend-quality-gates / FE-GATE-012 / bundle (pull_request) Failing after 28s
frontend-quality-gates / FE-GATE-013 / security (pull_request) Failing after 25s
frontend-quality-gates / FE-GATE-020 / removability (pull_request) Failing after 32s
frontend-quality-gates / FE-GATE-008 / e2e (pull_request) Failing after 2m56s
frontend-quality-gates / FE-GATE-009 / accessibility (pull_request) Successful in 3m45s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / FE-GATE-006 / component (pull_request) Failing after 36s
frontend-quality-gates / FE-GATE-010 / architecture (pull_request) Failing after 1m28s
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
desktop(트리
|
||
|
|
f117a5af41 |
docs(src): 계층 폴더마다 지역 규칙 AGENTS.md를 두고 CLAUDE.md가 가져온다
계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는 보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다. src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일, 그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그 폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든 폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에 @AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은 책을 읽는다(백엔드와 같은 짝). - .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다. - scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를 본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다. - docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters 아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다. - 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의 양식을 가리킨다. 버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md 없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만 읽어 백엔드와 갈린다). 위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면 이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture). 검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200), python3 -m unittest discover -s scripts/tests 62건 통과. |
||
|
|
c50da34712 |
feat(scripts): verify.sh가 인자를 넘기고 원격에서 바뀐 파일을 돌려받는다
cold-read 시험에서 두 곳이 막혔다. script 단계가 인자를 넘기지 못해 test:sample-removal -- --feature=<id>를 돌릴 수 없었고, desktop에서 만든 파일(create:feature, 초기 JS 기록 다시 쓰기)을 노트북으로 가져올 길이 없었다. dry-run은 공백 든 인자를 실제와 다르게 보였다. - script <이름> -- <인자…>: 인자는 script가 하나일 때만 넘긴다. - exec -- <명령…>: 한 테스트 파일이나 package script가 아닌 node 스크립트. - 원격에서 바뀐 파일은 로그 폴더의 changes.patch에 남고, --apply-back이면 노트북 작업 트리에 얹는다. - VERIFY_SNAPSHOT=1이면 artifacts·dist·test-results를 snapshot/에 복사한다 (리뷰어가 함께 읽는 사본). VERIFY_INSTALL=0은 설치를 건너뛴다(시험용). - dry-run이 인자를 %q로 보인다. - 원격 호출은 단계 다음에 --on here를 둔다. 뒤에 두면 `--` 뒤 명령 인자가 되어 원격이 자기를 다시 원격으로 보냈다(시험에서 잠금 교착으로 드러났다). - 원격 준비가 일찍 실패해도 /tmp의 패치 파일을 지운다. 위험·한계: --apply-back은 노트북 작업 트리가 원격 기준과 다르면 패치가 얹히지 않는다. 그때는 rc=4와 원격 패치 경로를 알린다. 검증: python3 -m unittest scripts/tests/test_verify.py 통과(인자 전달, exec, 잘못된 인자 10가지가 원격 호출 0, 가짜 ssh로 원격에서 만든 파일 둘을 돌려받음, 바뀐 것 없는 단계의 changes.patch는 빈 파일). |
||
|
|
9d65a41d82 |
chore(ledger): 예측·실측 장부를 두고 이 작업의 착수 예측을 남긴다
작업마다 착수할 때의 예측과 끝날 때의 실측을 남길 곳이 프론트에 없었다. 소유자 결정(2026-11-07 Q11)은 repo마다 docs/ledger/estimates.jsonl이다. docs/ledger/README.md(백엔드와 같은 형식)와 estimates.jsonl을 두고, 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes가 merge=union을 준다. 첫 줄은 이 작업(fe-c-harness)의 착수 예측이다. 위험·한계: 복사한 프로젝트는 템플릿의 줄을 받는다. README 지워도 되는 표에 "줄을 비운다"로 적는다(뒤 커밋). 검증: python3 -m unittest scripts/tests/test_ledger.py 통과. Refs: design-docs harness/01-harness-design.md 10절·13절 Q11 |
||
|
|
c6e4252802 |
feat(scripts): 검증 진입점 scripts/verify.sh가 단계를 desktop으로 옮겨 돈다
desktop에서 게이트를 돌리는 법이 문서와 세션마다 다른 손 절차였다 (checkout 바꾸기·되돌리기, CI env 넣기, runner 스크립트 복사). 같은 빈틈이 되풀이됐고, 공유 checkout의 브랜치를 바꾼 채 두는 위험이 있었다. scripts/verify.sh <단계>는 claude-harness template/scripts/verify.sh의 운반부를 쓰고 단계를 채운다. - 단계: config/ci/gates.json의 stage id(merge·release·production·field· documentation)는 그 gateIds 전부를 ci:gate로, gate <ID>…, parts <ID>(그 게이트의 명령을 하나씩 끝까지, FE-GATE-013 진단용), script <이름>…, docs·hooks(노트북). stage는 실패가 있어도 끝까지 돌고 게이트마다 rc와 초를 남긴다. - desktop: 지금 트리를 기준 커밋에 대한 패치로 보내 공유 checkout에서 새 worktree를 만들고, 트리 해시를 맞춘 뒤 commit-tree로 깨끗한 HEAD를 만든다. CI=true pnpm install --frozen-lockfile --offline 뒤 flock 잠금 아래 CI env(CI, VITE_COMMIT_SHA, VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE)로 돌리고, /tmp/claude-gates/<이름>/에 summary·로그·게이트 산출물· status-after를 남긴 뒤 worktree를 지운다. push하지 않는다. - 잘못된 단계·게이트는 desktop에 보내기 전에 노트북에서 거절한다. 버린 대안: 공유 checkout의 브랜치를 잠금 안에서 바꾸고 되돌리기(지금 손 절차). 다른 세션의 checkout을 건드리고, 끝나지 않으면 바뀐 채 남는다. 위험·한계: 새 worktree의 오프라인 설치는 desktop pnpm store에 의존한다. 없으면 온라인 설치로 넘어간다. CI workflow가 아직 이 스크립트를 부르지 않는다(CI 재편 몫). 검증: python3 -m unittest scripts/tests/test_verify.py 통과(stage마다 계약의 gateIds, parts의 명령, 잘못된 인자는 원격 호출 0, 가짜 ssh로 패치 → 같은 트리 해시 → 로그 → worktree 정리, 없는 원격 repo는 rc=4). desktop에서 실제 운반을 한 번 돌려 트리 해시 일치와 worktree 정리를 봤다. Refs: design-docs harness/01-harness-design.md 6절 |
||
|
|
9961ecb106 |
feat(hooks): 편집 직후 경계·게이트 기준·문서 알림과 턴 끝 desktop 알림을 건다
경계 위반, 늘어난 skip·only, 작업 매뉴얼 규칙 위반은 desktop 게이트에서야 드러났고, desktop 검증 없이 턴을 끝내도 아무것도 알리지 않았다. scripts/hooks/hooks.py(백엔드 hooks.py와 같은 모양, 표준 라이브러리와 git만)를 .claude/settings.json에 단다. - N3: src TypeScript를 고치면 import를 .dependency-cruiser.json의 forbidden 규칙(path·pathNot·$1)에 그대로 대 본다. 규칙 파일을 읽으므로 규칙이 바뀌면 따라간다. - N6: 테스트에 .skip·.only·.fixme·.todo가 마지막 커밋보다 늘거나, 예산· 기준선·ungated 목록·스냅숏을 고치면 알린다. - N2: .md를 고치면 scripts/check-work-docs.py의 실패 줄을 알린다. - N5: desktop만 확인할 수 있는 파일을 고친 뒤 desktop 실행이 없으면 턴 끝을 한 번 막고 이유를 준다. 모두 넛지다. repo 안 편집에 되돌릴 수 없는 것이 없어 차단 훅은 없다. 고른 방법: 노트북에서는 정적 검사만 하고 포맷·린트·타입은 desktop scripts/verify.sh에 둔다(brief, 2026-11-08). 설계 13절 Q6은 편집 훅에서 한 파일 eslint를 골랐지만, 프론트 eslint는 pnpm·node_modules가 필요해 "pnpm은 desktop에서만" 규칙과 부딪친다. 위험·한계: N3는 정규식으로 import를 뽑아 주석 속 따옴표 같은 드문 모양을 놓칠 수 있다. 정본은 check:architecture다. 훅 시험은 아직 CI workflow가 부르지 않는다. 훅은 세션 시작에 읽혀 이 세션에서는 돌지 않았다. 검증: python3 -m unittest scripts/tests/test_hooks.py 26건 통과. 실제 규칙과 src 377개 파일에서 N3 알림 0(거짓 양성 시험). 조건 하나씩 끈 변이 10개를 모두 시험이 잡았다. Refs: design-docs harness/01-harness-design.md 5.2·5.3절 |
||
|
|
9f8596280c |
feat(claude): 경로별 규칙·스킬·결과만 돌려주는 서브에이전트를 둔다
Claude Code 세션이 테스트·문서·adapter·게이트 기준·기능 폴더를 고칠 때 읽을 규칙이 루트 한 파일에 섞여 있었고, desktop 실행과 새 기능 절차를 부르는 스킬, 결과만 받는 리뷰어 정의가 없었다. - .claude/rules/: tests, docs, adapters, gates-and-budgets, features. paths로 그 파일을 열 때만 읽힌다. - .claude/skills/: desktop-gates(scripts/verify.sh로 desktop에서 돌리기), new-feature(create:feature부터). 소유자 결정대로 모델이 부르고, 설명에 발동 조건을 문단으로 쓴다. 본문은 정본 playbook을 가리킨다. - .claude/agents/: arch-reviewer(경계 규칙), verify-app(desktop에서 빌드·브라우저 확인), code-simplifier. 쓰기 도구가 없다. - .claude/settings.json: 하네스 플러그인 harness@claude-harness를 켜고 실제 .env 읽기·쓰기를 막는다. Agent deny는 두지 않는다. - .gitignore: .claude/는 이 넷만 추적하고 worktree·훅 상태· settings.local.json은 무시한다. 버린 대안: Agent deny 유지(소유자 결정 2026-11-07 Q5가 풀었다), 스킬을 사용자 호출 전용으로(Q9가 모델 호출을 골랐다). 위험·한계: 규칙 paths는 지금 있는 파일로 시험하지만 Claude Code가 실제로 읽는지는 이 세션에서 보지 않았다(설정은 세션 시작에 읽힌다). 검증: python3 -m unittest scripts/tests/test_claude_setup.py 통과 (서브에이전트 쓰기 도구 없음, 스킬 설명 길이와 발동 조건, 규칙 paths가 가리키는 파일 있음). Refs: design-docs harness/01-harness-design.md 13절 Q3·Q5·Q9 |
||
|
|
6e8cc963ec |
docs(agents): 루트 AGENTS.md를 정본으로 두고 CLAUDE.md가 가져온다
루트에는 리뷰 기준만 담은 CLAUDE.md(26줄)가 있었다. 꼭 지킬 경계 규칙, 지도, 검증 진입점, 맡은 일 라우터가 없었고, "서브에이전트를 병렬로"는 소유자 결정(2026-11-07)과 맞지 않았다. AGENTS.md(35줄)에 무엇인가 · 꼭 지킬 것 5 · 지도 · 맡은 일 · 검증 · 일하는 방식을 둔다. CLAUDE.md는 @AGENTS.md와 Claude 전용 줄(10줄)이다: settings·훅, 하네스 플러그인과 비대화형 설치 두 명령, 규칙·스킬· 서브에이전트 위치, 리뷰 기준이 옮겨 간 곳, 소유자 환경. 리뷰 기준과 전체 리뷰 절차는 docs/work/reference/review-criteria.md와 docs/work/improve.md 4.1절로 옮겼다. scripts/check-work-docs.py는 백엔드 검사기를 옮긴 것이다: 지도 40줄, CLAUDE.md 15줄, README 80줄, playbook 150줄, 진입 경로 350줄, 9절 뼈대, 진입 문서의 이력 ID 0, 상대 링크. 이력 패턴에 이 repo의 꼴(1105 README, P-43·O-12·D-14)을 더했다. 표준 라이브러리만 써서 노트북에서 돈다. 버린 대안: CLAUDE.md만 두기(다른 에이전트가 못 읽는다), 심볼릭 링크 (Claude 전용 줄을 둘 수 없다). 위험·한계: 지도 40줄은 자료와 백엔드에 맞춘 값이다. brief 상한 80보다 좁다. 검증: python3 scripts/check-work-docs.py rc=0, python3 -m unittest scripts/tests/test_check_work_docs.py 통과. Refs: design-docs harness/01-harness-design.md 4.3절·13절 Q1·Q2 |