feat(harness): 프론트에 Claude Code 하네스와 작업 매뉴얼 docs/work/를 둔다 #13

Merged
donghyeon.kang merged 20 commits from claude/fe-c-harness-0ae061 into main 2026-11-11 11:25:18 +00:00
Owner

무엇을, 왜

소유자가 2026-11-07에 Claude Code 작업 환경(하네스)을 자료(Claude Code 제작 책임자가 권하는 방식)대로 백엔드·프론트에 똑같이 적용하라고 정했다(design-docs harness/01-harness-design.md 13절). 백엔드는 끝났고 프론트가 남았다. 지금 프론트 세션은 리뷰 기준만 담은 CLAUDE.md(26줄)를 읽고 시작한다. 꼭 지킬 경계 규칙·지도·검증 진입점·맡은 일 라우터가 없고, 작업 매뉴얼도 main에 없다(초안은 PR #6에만 있다).

이 PR은 백엔드 main과 같은 모양으로 다음을 둔다.

파일 하는 일
AGENTS.md(35줄) 정본: 무엇인가 · 꼭 지킬 것 5 · 지도 · 맡은 일 라우터 · 검증 · 일하는 방식
CLAUDE.md(10줄) @AGENTS.md + Claude 전용: settings·훅, 하네스 플러그인과 비대화형 설치 두 명령(--scope project), 규칙·스킬·서브에이전트 위치, 리뷰 기준이 옮겨 간 곳
src/<계층>/AGENTS.md 9개 + 옆 CLAUDE.md(@AGENTS.md) 계층 폴더마다 지역 규칙: 하는 일, 그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 뽑은 규칙 이름), 검사 게이트, 테스트 위치. 다른 에이전트도 읽는다. .claude/rules/adapters·features는 이것을 가리킨다. check:adapter-inventory가 요구해 docs/reviews/adapters/INVENTORY.md에 두 행을 더했다
docs/vision.md, docs/problem-statement.md 소유자가 채우는 빈 양식(claude-harness template/docs/에서). 루트 AGENTS.md가 가리킨다
.claude/settings.json 플러그인 harness@claude-harness 켜기(마켓 git URL), 실제 .env·.env.local·.env.*.local·.env.<mode> 읽기·쓰기 deny, repo 훅
.claude/rules/ 5개 tests, docs, adapters, gates-and-budgets, features. paths로 그 파일을 열 때만 읽힌다
.claude/skills/ 2개 desktop-gates(desktop에서 게이트), new-feature(create:feature부터). 모델이 부르고 설명에 발동 조건
.claude/agents/ 3개 arch-reviewer, verify-app, code-simplifier. 결과만 돌려주고 쓰기 도구가 없다
scripts/hooks/hooks.py, README.md 편집 직후 N3 경계(.dependency-cruiser.json 규칙을 그대로 읽어 대 봄)·N6 게이트 기준(skip·only 증가, 예산·기준선 편집)·N2 문서 검사 알림, 턴 끝 N5 desktop 검증 알림. 모두 넛지
scripts/verify.sh 검증 진입점. stage(merge 등)·gate <ID>·parts <ID>·script <이름> -- <인자>·exec -- <명령>·docs·hooks. desktop으로 패치를 옮겨 새 worktree·깨끗한 HEAD·오프라인 설치·잠금·CI env로 돌리고 로그를 남긴다. 원격에서 바뀐 파일은 --apply-back으로 돌려받는다
scripts/check-work-docs.py 작업 매뉴얼 검사(분량 상한, 9절 뼈대, 진입 문서와 src/**/AGENTS.md의 이력 ID 0, 폴더 규칙의 CLAUDE.md 짝, 상대 링크). 백엔드 검사기를 옮겼다
scripts/tests/ 훅·검사기·설정·장부·verify.sh 시험 63건(python3 unittest)
docs/work/ README, playbook 6(new-feature, improve, research-design, docs-writing, operate, delegate), reference 7, evidence.md
docs/ledger/ 예측·실측 장부(merge=union), 이 작업의 예측·실측 줄
README.md, docs/README.md AGENTS.md·docs/work/ 포인터, 지워도 되는 표에서 CLAUDE.md 빼고 장부 넣기, 1절 링크
테스트 영향 셋 tests/unit/template-contract-documents.test.ts(새), deletable-history-documents.test.ts(CLAUDE.md 패턴 뺌), 제거 드릴 문서 사본에 AGENTS.md(removal-fixture.ts, template-feature-removal-documents.test.ts)

PR #6(브랜치 docs/improvement-manual의 docs/improvement 11개)의 내용은 모두 docs/work/로 옮겼다. 장마다 옮긴 곳은 docs/work/evidence.md 1.1절이다: 01→improve.md, 02→reference/review-criteria.md, 03·04→reference/structure.md, 05→reference/testing.md, 06→reference/performance.md, 07→reference/gates.md·operate.md, 08→reference/decisions.md, 09→delegate.md·improve.md 4.5절, 부록→reference/defect-patterns.md, README의 결정 M-1~M-10→reference/decisions.md와 evidence. PR #6은 닫아도 된다.

고른 방법과 버린 대안

  • 편집 훅은 노트북 정적 검사만(brief): 설계 13절 Q6은 편집 훅에서 한 파일 포맷·린트를 골랐지만, 프론트 eslint는 pnpm·node_modules가 필요해 "pnpm은 desktop에서만"(소유자 결정 2026-11-05)과 부딪친다. 포맷·린트·타입은 desktop scripts/verify.sh에서 돈다. 이 차이는 docs/work/reference/decisions.md O-20에 적었다.
  • N3는 규칙 파일을 그대로 읽는다: 손으로 규칙을 옮기면 갈라진 복사본이 된다. src/ 377개 파일(import 1,161개)에서 알림 0(거짓 양성 0), 넣어 본 위반은 모두 잡았다. 버린 대안: dependency-cruiser CLI(TypeScript 7을 못 읽는다), node 스크립트(노트북에서 node를 돌리게 된다).
  • 차단 훅 없음: repo 안 편집에 되돌릴 수 없는 것이 없다. 위험 명령 차단은 전역 훅과 플러그인 몫이다.
  • verify.sh는 새 worktree에서: 지금 손 절차(공유 checkout의 브랜치를 잠금 안에서 바꾸고 되돌리기)는 다른 세션의 checkout을 건드리고, 끝나지 않으면 바뀐 채 남는다. 패치 + 트리 해시 대조 + commit-tree로 push 없이 같은 트리를 깨끗한 HEAD로 돈다.
  • 지도 40줄: brief 상한 80보다 좁게, 13절 Q2(자료 20~40줄)와 백엔드 검사기 값에 맞췄다.
  • 결함 패턴 번호를 다시 매김: 초안의 P-NN이 결정 번호 꼴([MODP]-NN)과 겹쳐 진입 문서에서 인용할 수 없었다. 영역 글자+번호(G·T·C·S·W·B)로 바꾸고 옛 번호 대응을 evidence.md 4절에 뒀다.
  • 계층 규칙은 폴더 AGENTS.md가 정본(총괄 대조, 하네스 자료 3단계): .claude/rules/는 Claude만 읽는다. 백엔드처럼 옆에 @AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은 책을 읽는다. 규칙 이름은 규칙 파일에서 기계로 뽑았고, 바뀌면 손으로 고친다(정본은 규칙 파일).
  • CHANGELOG는 새 미출시 절: 다른 정리 세션이 같은 절에 줄을 더하므로 충돌을 줄이려고 따로 둔다.
  • 설계로 답이 안 난 선택(brief 8절): 훅 언어(백엔드와 같은 Python 표준 라이브러리), 장부를 README 지워도 되는 표에 "줄을 비운다"로 넣기, docs/README.md 1절이 work/reference/까지 링크하기(검사 범위를 넓히는 쪽). 모두 권하는 쪽을 골랐다.

위험과 영향

  • 문서 검사 범위가 넓어진다: AGENTS.md와 docs/work/·docs/work/reference/의 백틱 경로·package script·FE-GATE ID가 틀리면 FE-GATE-017과 FE-GATE-005·020 안의 같은 검사가 실패한다. 다른 세션이 경로·script를 옮기면 이 문서들도 같이 고쳐야 한다(CI 정리 세션이 schemas/·tsconfig·fixture script를 옮기는 중이다. 이 PR의 문서는 그 경로를 쓰지 않게 썼다).
  • 제거 드릴 사본에 AGENTS.md가 들어간다: CI 정리 세션도 scripts/lib/removal-fixture.ts(복사 목록)를 고친다. 이 PR은 문서 목록 쪽만 고쳐 줄은 겹치지 않는다.
  • README 번역과 겹침: 문서 체계 세션이 README를 옮기면 지워도 되는 표 제목이 바뀐다. 새 시험은 제목이 아니라 행으로 표를 찾는다. verify-documentation-readiness.ts의 지운 이력 목록은 영어 제목을 읽으니 그 세션이 같이 고친다.
  • 새 세션이 처음 읽는 지침이 늘었다(아래 검증 표, 2,677 B → 4,491 B). 꼭 지킬 것·지도·검증·라우터가 새로 들어가서다. 전에는 리뷰 기준만 읽혔다. 줄이라는 brief의 기대와 다르다.
  • 문서 체계 세션과 경로가 겹친다: 그 세션은 docs/architecture/decisions/ 같은 경로를 옮긴다. docs/work/가 그 경로를 백틱으로 가리키므로, 두 PR 중 나중에 병합되는 쪽에서 verify:documentation이 그 줄을 정확히 잡는다. 그 PR에서 같이 고친다.
  • 훅은 이 세션에서 돌지 않았다: 훅은 세션 시작에 읽힌다. 병합 뒤 첫 새 세션이 실제로 알림을 받는지 보면 좋다. 시험은 hooks.py를 직접 부른다.
  • scripts/tests/는 아직 CI workflow가 부르지 않는다: workflow 생성기·config/ci는 CI 정리 세션 몫이라 고치지 않았다. 지금은 scripts/verify.sh hooks로 돈다.
  • cold-read 시험은 서브에이전트 한 번이다: 이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능 만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가 나와 고쳤다(18ea5e93, c50da347). 고친 뒤 다시 시험하지는 않았다. 사람이나 새 세션이 실제 일을 해 본 시험은 아니다.
  • FE-GATE-013은 desktop 호스트 조건(user namespace)으로 rc=1이다. 어떻게 셀지는 결정 대기이고, 부분 실행 결과를 아래에 적는다.

검증

desktop(ssh desktop, scripts/verify.sh가 새 worktree에서, flock /tmp/claude-gates/heavy.lock, CI env). 로그는 desktop /tmp/claude-gates/<이름>/. 실제 Gitea 러너가 아니라 desktop에 CI env를 준 실행이다(실제 CI 미검증).

트리 실행 결과 로그
ac91704b(= 5fab0e46, 뒤 커밋 f98f39a3은 장부 한 줄) FE-GATE-005·010·017·020 모두 rc=0(005 149s, 010 64s, 017 2s, 020 911s). 게이트 뒤 status-after.txt·changes.patch 비어 있음 fe-c-final3-gates/
같음 scripts/verify.sh parts FE-GATE-013 test:system만 rc=1(호스트 사전 점검), verify:reproducible-build·build:release-candidate·verify:local-evidence·check:supply-chain:fixtures·check:supply-chain:provider-fixtures·check:security:fixtures·check:browser-security rc=0 fe-c-final3-013/
같음 scripts/verify.sh hooks --on desktop 63건 통과 rc=0 fe-c-final3-hooks/
67484ed3(= 8faec86d) scripts/verify.sh merge FE-GATE-001012·020 rc=0, FE-GATE-013 rc=1(아래). 그 뒤 바뀐 것은 Markdown(src/**/AGENTS.md, 문서), INVENTORY, scripts/verify.sh, Python 시험뿐이라 001004·006~009·011·012가 읽는 입력은 같다. 읽는 게이트(005·010·017·020·013)는 위에서 다시 돌렸다 fe-c-final-merge/
  • FE-GATE-013 판정 문구: merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약 실패(사전 점검이 "this host does not allow unprivileged user and network namespaces"로 멈춤, bwrap loopback: Failed RTM_NEWADDR). 뒤 명령 7개는 통과. merge 가능 여부는 FE-GATE-013을 어떻게 셀지의 결정 대기에 따라 소유자가 정한다.
  • 고치는 동안 desktop이 잡은 결함 셋: 새 시험이 지워도 되는 폴더 이름을 코드에 씀(4a21bc79), INVENTORY 합계 줄(141/141)을 고치지 않음, verify.sh parts에 SOURCE_DATE_EPOCH가 없음(둘 다 5fab0e46).
  • 앞선 merge 실행(트리 ada4015c)을 desktop에서 멈추려던 명령은 권한 분류기에 막혀 끝까지 돌게 두었다.

노트북(정적 검사):

  • scripts/verify.sh docs rc=0: AGENTS.md 35/40, CLAUDE.md 10/15, README 75/80, playbook 최대 150/150(improve), 진입 경로 최대 270/350, src/**/AGENTS.md 9개 최대 20/200, 이력 ID 0, 상대 링크 120개.
  • scripts/verify.sh hooks 63건 통과. 훅 조건 변이 10개 모두 시험이 잡음.
  • RED: tests/unit/template-contract-documents.test.ts는 README·docs/README.md를 고치기 전 트리에서 2건 모두 실패(desktop test:unit, 로그 /tmp/claude-gates/fe-c-harness-red/).

새 세션이 처음 읽는 지침(이 repo 몫):

전(main 8327e221) 후
읽히는 파일 CLAUDE.md만(추적되지 않는 AGENTS.md 사본은 CLAUDE.md가 있으면 읽히지 않는다) CLAUDE.md + 가져온 AGENTS.md
줄 26 45
바이트 2,677 4,491
글자 1,607 2,863

토큰은 직접 세지 못했다(토큰 세기 API를 쓰지 않았다). 같은 한국어 문서라 글자 수에 비례한다고 보면 약 1.8배다 [추정].

리뷰어가 볼 곳

  • scripts/verify.sh run_remote: 패치·트리 해시·commit-tree·설치·잠금·정리.
  • scripts/hooks/hooks.py broken_rules(규칙의 $1·pathNot 해석)와 ran_on_desktop(N5가 desktop 실행으로 치는 명령).
  • AGENTS.md 꼭 지킬 것 5와 docs/work/improve.md 4.5절(멈춤 기준), 5절(SPEC.md에서 옮긴 공통 완료 기준).
  • docs/work/evidence.md 1.1절(PR #6 장별 이동 표).

관련

  • 설계: design-docs harness/01-harness-design.md(13절 소유자 결정, 4.4절 테스트 영향 표)
  • 본보기: 백엔드 main AGENTS.md·.claude/·scripts/hooks/·docs/work/, 공개 repo claude-harness main 72078ca
  • 흡수한 것: PR #6(닫아도 된다)
  • 장부: docs/ledger/estimates.jsonl task fe-c-harness(예측 p50 115분, 실측 작업 중 192분으로 p80 170분을 넘음. 이유는 그 줄의 why)
## 무엇을, 왜 소유자가 2026-11-07에 Claude Code 작업 환경(하네스)을 자료(Claude Code 제작 책임자가 권하는 방식)대로 백엔드·프론트에 똑같이 적용하라고 정했다(design-docs `harness/01-harness-design.md` 13절). 백엔드는 끝났고 프론트가 남았다. 지금 프론트 세션은 리뷰 기준만 담은 `CLAUDE.md`(26줄)를 읽고 시작한다. 꼭 지킬 경계 규칙·지도·검증 진입점·맡은 일 라우터가 없고, 작업 매뉴얼도 main에 없다(초안은 PR #6에만 있다). 이 PR은 백엔드 main과 같은 모양으로 다음을 둔다. | 파일 | 하는 일 | | --- | --- | | `AGENTS.md`(35줄) | 정본: 무엇인가 · 꼭 지킬 것 5 · 지도 · 맡은 일 라우터 · 검증 · 일하는 방식 | | `CLAUDE.md`(10줄) | `@AGENTS.md` + Claude 전용: settings·훅, 하네스 플러그인과 비대화형 설치 두 명령(`--scope project`), 규칙·스킬·서브에이전트 위치, 리뷰 기준이 옮겨 간 곳 | | `src/<계층>/AGENTS.md` 9개 + 옆 `CLAUDE.md`(`@AGENTS.md`) | 계층 폴더마다 지역 규칙: 하는 일, 그 폴더에만 걸리는 import 금지(`.dependency-cruiser.json`에서 뽑은 규칙 이름), 검사 게이트, 테스트 위치. 다른 에이전트도 읽는다. `.claude/rules/adapters·features`는 이것을 가리킨다. `check:adapter-inventory`가 요구해 `docs/reviews/adapters/INVENTORY.md`에 두 행을 더했다 | | `docs/vision.md`, `docs/problem-statement.md` | 소유자가 채우는 빈 양식(claude-harness `template/docs/`에서). 루트 `AGENTS.md`가 가리킨다 | | `.claude/settings.json` | 플러그인 `harness@claude-harness` 켜기(마켓 git URL), 실제 `.env`·`.env.local`·`.env.*.local`·`.env.<mode>` 읽기·쓰기 deny, repo 훅 | | `.claude/rules/` 5개 | tests, docs, adapters, gates-and-budgets, features. `paths`로 그 파일을 열 때만 읽힌다 | | `.claude/skills/` 2개 | `desktop-gates`(desktop에서 게이트), `new-feature`(`create:feature`부터). 모델이 부르고 설명에 발동 조건 | | `.claude/agents/` 3개 | `arch-reviewer`, `verify-app`, `code-simplifier`. 결과만 돌려주고 쓰기 도구가 없다 | | `scripts/hooks/hooks.py`, `README.md` | 편집 직후 N3 경계(`.dependency-cruiser.json` 규칙을 그대로 읽어 대 봄)·N6 게이트 기준(skip·only 증가, 예산·기준선 편집)·N2 문서 검사 알림, 턴 끝 N5 desktop 검증 알림. 모두 넛지 | | `scripts/verify.sh` | 검증 진입점. stage(`merge` 등)·`gate <ID>`·`parts <ID>`·`script <이름> -- <인자>`·`exec -- <명령>`·`docs`·`hooks`. desktop으로 패치를 옮겨 새 worktree·깨끗한 HEAD·오프라인 설치·잠금·CI env로 돌리고 로그를 남긴다. 원격에서 바뀐 파일은 `--apply-back`으로 돌려받는다 | | `scripts/check-work-docs.py` | 작업 매뉴얼 검사(분량 상한, 9절 뼈대, 진입 문서와 `src/**/AGENTS.md`의 이력 ID 0, 폴더 규칙의 `CLAUDE.md` 짝, 상대 링크). 백엔드 검사기를 옮겼다 | | `scripts/tests/` | 훅·검사기·설정·장부·`verify.sh` 시험 63건(python3 unittest) | | `docs/work/` | README, playbook 6(new-feature, improve, research-design, docs-writing, operate, delegate), reference 7, `evidence.md` | | `docs/ledger/` | 예측·실측 장부(`merge=union`), 이 작업의 예측·실측 줄 | | `README.md`, `docs/README.md` | `AGENTS.md`·`docs/work/` 포인터, 지워도 되는 표에서 `CLAUDE.md` 빼고 장부 넣기, 1절 링크 | | 테스트 영향 셋 | `tests/unit/template-contract-documents.test.ts`(새), `deletable-history-documents.test.ts`(CLAUDE.md 패턴 뺌), 제거 드릴 문서 사본에 `AGENTS.md`(`removal-fixture.ts`, `template-feature-removal-documents.test.ts`) | PR #6(브랜치 `docs/improvement-manual`의 docs/improvement 11개)의 내용은 모두 `docs/work/`로 옮겼다. 장마다 옮긴 곳은 `docs/work/evidence.md` 1.1절이다: 01→`improve.md`, 02→`reference/review-criteria.md`, 03·04→`reference/structure.md`, 05→`reference/testing.md`, 06→`reference/performance.md`, 07→`reference/gates.md`·`operate.md`, 08→`reference/decisions.md`, 09→`delegate.md`·`improve.md` 4.5절, 부록→`reference/defect-patterns.md`, README의 결정 M-1~M-10→`reference/decisions.md`와 evidence. PR #6은 닫아도 된다. ## 고른 방법과 버린 대안 - **편집 훅은 노트북 정적 검사만**(brief): 설계 13절 Q6은 편집 훅에서 한 파일 포맷·린트를 골랐지만, 프론트 eslint는 pnpm·`node_modules`가 필요해 "pnpm은 desktop에서만"(소유자 결정 2026-11-05)과 부딪친다. 포맷·린트·타입은 desktop `scripts/verify.sh`에서 돈다. 이 차이는 `docs/work/reference/decisions.md` O-20에 적었다. - **N3는 규칙 파일을 그대로 읽는다**: 손으로 규칙을 옮기면 갈라진 복사본이 된다. `src/` 377개 파일(import 1,161개)에서 알림 0(거짓 양성 0), 넣어 본 위반은 모두 잡았다. 버린 대안: dependency-cruiser CLI(TypeScript 7을 못 읽는다), node 스크립트(노트북에서 node를 돌리게 된다). - **차단 훅 없음**: repo 안 편집에 되돌릴 수 없는 것이 없다. 위험 명령 차단은 전역 훅과 플러그인 몫이다. - **`verify.sh`는 새 worktree에서**: 지금 손 절차(공유 checkout의 브랜치를 잠금 안에서 바꾸고 되돌리기)는 다른 세션의 checkout을 건드리고, 끝나지 않으면 바뀐 채 남는다. 패치 + 트리 해시 대조 + `commit-tree`로 push 없이 같은 트리를 깨끗한 HEAD로 돈다. - **지도 40줄**: brief 상한 80보다 좁게, 13절 Q2(자료 20~40줄)와 백엔드 검사기 값에 맞췄다. - **결함 패턴 번호를 다시 매김**: 초안의 `P-NN`이 결정 번호 꼴(`[MODP]-NN`)과 겹쳐 진입 문서에서 인용할 수 없었다. 영역 글자+번호(G·T·C·S·W·B)로 바꾸고 옛 번호 대응을 evidence.md 4절에 뒀다. - **계층 규칙은 폴더 `AGENTS.md`가 정본**(총괄 대조, 하네스 자료 3단계): `.claude/rules/`는 Claude만 읽는다. 백엔드처럼 옆에 `@AGENTS.md` 한 줄 `CLAUDE.md`를 둬 Claude Code가 그 폴더 파일을 열 때 같은 책을 읽는다. 규칙 이름은 규칙 파일에서 기계로 뽑았고, 바뀌면 손으로 고친다(정본은 규칙 파일). - **CHANGELOG는 새 미출시 절**: 다른 정리 세션이 같은 절에 줄을 더하므로 충돌을 줄이려고 따로 둔다. - **설계로 답이 안 난 선택(brief 8절)**: 훅 언어(백엔드와 같은 Python 표준 라이브러리), 장부를 README 지워도 되는 표에 "줄을 비운다"로 넣기, `docs/README.md` 1절이 `work/reference/`까지 링크하기(검사 범위를 넓히는 쪽). 모두 권하는 쪽을 골랐다. ## 위험과 영향 - **문서 검사 범위가 넓어진다**: `AGENTS.md`와 `docs/work/`·`docs/work/reference/`의 백틱 경로·package script·FE-GATE ID가 틀리면 FE-GATE-017과 FE-GATE-005·020 안의 같은 검사가 실패한다. 다른 세션이 경로·script를 옮기면 이 문서들도 같이 고쳐야 한다(CI 정리 세션이 `schemas/`·tsconfig·fixture script를 옮기는 중이다. 이 PR의 문서는 그 경로를 쓰지 않게 썼다). - **제거 드릴 사본에 `AGENTS.md`가 들어간다**: CI 정리 세션도 `scripts/lib/removal-fixture.ts`(복사 목록)를 고친다. 이 PR은 문서 목록 쪽만 고쳐 줄은 겹치지 않는다. - **README 번역과 겹침**: 문서 체계 세션이 README를 옮기면 지워도 되는 표 제목이 바뀐다. 새 시험은 제목이 아니라 행으로 표를 찾는다. `verify-documentation-readiness.ts`의 지운 이력 목록은 영어 제목을 읽으니 그 세션이 같이 고친다. - **새 세션이 처음 읽는 지침이 늘었다**(아래 검증 표, 2,677 B → 4,491 B). 꼭 지킬 것·지도·검증·라우터가 새로 들어가서다. 전에는 리뷰 기준만 읽혔다. 줄이라는 brief의 기대와 다르다. - **문서 체계 세션과 경로가 겹친다**: 그 세션은 `docs/architecture/decisions/` 같은 경로를 옮긴다. `docs/work/`가 그 경로를 백틱으로 가리키므로, 두 PR 중 나중에 병합되는 쪽에서 `verify:documentation`이 그 줄을 정확히 잡는다. 그 PR에서 같이 고친다. - **훅은 이 세션에서 돌지 않았다**: 훅은 세션 시작에 읽힌다. 병합 뒤 첫 새 세션이 실제로 알림을 받는지 보면 좋다. 시험은 hooks.py를 직접 부른다. - **`scripts/tests/`는 아직 CI workflow가 부르지 않는다**: workflow 생성기·`config/ci`는 CI 정리 세션 몫이라 고치지 않았다. 지금은 `scripts/verify.sh hooks`로 돈다. - **cold-read 시험은 서브에이전트 한 번**이다: 이 대화를 모르는 서브에이전트에게 `AGENTS.md`부터 읽혀 두 일(새 기능 만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가 나와 고쳤다(`18ea5e93`, `c50da347`). 고친 뒤 다시 시험하지는 않았다. 사람이나 새 세션이 실제 일을 해 본 시험은 아니다. - **FE-GATE-013**은 desktop 호스트 조건(user namespace)으로 rc=1이다. 어떻게 셀지는 결정 대기이고, 부분 실행 결과를 아래에 적는다. ## 검증 desktop(`ssh desktop`, `scripts/verify.sh`가 새 worktree에서, `flock /tmp/claude-gates/heavy.lock`, CI env). 로그는 desktop `/tmp/claude-gates/<이름>/`. 실제 Gitea 러너가 아니라 desktop에 CI env를 준 실행이다(실제 CI 미검증). | 트리 | 실행 | 결과 | 로그 | | --- | --- | --- | --- | | `ac91704b`(= `5fab0e46`, 뒤 커밋 `f98f39a3`은 장부 한 줄) | FE-GATE-005·010·017·020 | 모두 rc=0(005 149s, 010 64s, 017 2s, 020 911s). 게이트 뒤 `status-after.txt`·`changes.patch` 비어 있음 | `fe-c-final3-gates/` | | 같음 | `scripts/verify.sh parts FE-GATE-013` | `test:system`만 rc=1(호스트 사전 점검), `verify:reproducible-build`·`build:release-candidate`·`verify:local-evidence`·`check:supply-chain:fixtures`·`check:supply-chain:provider-fixtures`·`check:security:fixtures`·`check:browser-security` rc=0 | `fe-c-final3-013/` | | 같음 | `scripts/verify.sh hooks --on desktop` | 63건 통과 rc=0 | `fe-c-final3-hooks/` | | `67484ed3`(= `8faec86d`) | `scripts/verify.sh merge` | FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(아래). 그 뒤 바뀐 것은 Markdown(`src/**/AGENTS.md`, 문서), INVENTORY, `scripts/verify.sh`, Python 시험뿐이라 001~004·006~009·011·012가 읽는 입력은 같다. 읽는 게이트(005·010·017·020·013)는 위에서 다시 돌렸다 | `fe-c-final-merge/` | - **FE-GATE-013 판정 문구**: merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약 실패(사전 점검이 "this host does not allow unprivileged user and network namespaces"로 멈춤, bwrap `loopback: Failed RTM_NEWADDR`). 뒤 명령 7개는 통과. merge 가능 여부는 FE-GATE-013을 어떻게 셀지의 결정 대기에 따라 소유자가 정한다. - 고치는 동안 desktop이 잡은 결함 셋: 새 시험이 지워도 되는 폴더 이름을 코드에 씀(`4a21bc79`), INVENTORY 합계 줄(141/141)을 고치지 않음, `verify.sh parts`에 `SOURCE_DATE_EPOCH`가 없음(둘 다 `5fab0e46`). - 앞선 merge 실행(트리 `ada4015c`)을 desktop에서 멈추려던 명령은 권한 분류기에 막혀 끝까지 돌게 두었다. 노트북(정적 검사): - `scripts/verify.sh docs` rc=0: AGENTS.md 35/40, CLAUDE.md 10/15, README 75/80, playbook 최대 150/150(improve), 진입 경로 최대 270/350, `src/**/AGENTS.md` 9개 최대 20/200, 이력 ID 0, 상대 링크 120개. - `scripts/verify.sh hooks` 63건 통과. 훅 조건 변이 10개 모두 시험이 잡음. - RED: `tests/unit/template-contract-documents.test.ts`는 README·`docs/README.md`를 고치기 전 트리에서 2건 모두 실패(desktop `test:unit`, 로그 `/tmp/claude-gates/fe-c-harness-red/`). 새 세션이 처음 읽는 지침(이 repo 몫): | | 전(main `8327e221`) | 후 | | --- | --- | --- | | 읽히는 파일 | `CLAUDE.md`만(추적되지 않는 `AGENTS.md` 사본은 `CLAUDE.md`가 있으면 읽히지 않는다) | `CLAUDE.md` + 가져온 `AGENTS.md` | | 줄 | 26 | 45 | | 바이트 | 2,677 | 4,491 | | 글자 | 1,607 | 2,863 | 토큰은 직접 세지 못했다(토큰 세기 API를 쓰지 않았다). 같은 한국어 문서라 글자 수에 비례한다고 보면 약 1.8배다 **[추정]**. ## 리뷰어가 볼 곳 - `scripts/verify.sh` `run_remote`: 패치·트리 해시·`commit-tree`·설치·잠금·정리. - `scripts/hooks/hooks.py` `broken_rules`(규칙의 `$1`·`pathNot` 해석)와 `ran_on_desktop`(N5가 desktop 실행으로 치는 명령). - `AGENTS.md` 꼭 지킬 것 5와 `docs/work/improve.md` 4.5절(멈춤 기준), 5절(SPEC.md에서 옮긴 공통 완료 기준). - `docs/work/evidence.md` 1.1절(PR #6 장별 이동 표). ## 관련 - 설계: design-docs `harness/01-harness-design.md`(13절 소유자 결정, 4.4절 테스트 영향 표) - 본보기: 백엔드 main `AGENTS.md`·`.claude/`·`scripts/hooks/`·`docs/work/`, 공개 repo `claude-harness` main `72078ca` - 흡수한 것: PR #6(닫아도 된다) - 장부: `docs/ledger/estimates.jsonl` task `fe-c-harness`(예측 p50 115분, 실측 작업 중 192분으로 p80 170분을 넘음. 이유는 그 줄의 `why`)
donghyeon.kang added 13 commits 2026-11-08 13:39:46 +00:00
프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 CLAUDE.md의
리뷰 기준만 읽고 시작했고, 개선 작업 기준은 main에 들어가지 않은 초안
(브랜치 docs/improvement-manual의 docs/improvement 11개)에만 있었다.

백엔드 docs/work/와 같은 모양으로 README(크기·공통 단계·커밋·보고),
playbook 여섯(new-feature, improve, research-design, docs-writing,
operate, delegate, 모두 같은 9절 뼈대), reference 일곱(gates,
review-criteria, structure, testing, performance, defect-patterns,
decisions)과 evidence.md를 둔다. 초안의 장을 나눠 옮긴 표는
evidence.md 1.1절이다. SPEC.md의 공통 완료 기준 9개는 improve.md 5절로
옮겨, 문서 체계 정리가 SPEC.md를 이력으로 옮길 수 있게 한다.

진입 문서에는 지난 리뷰 ID를 쓰지 않고 내용과 날짜로 쓴다. ID는
evidence.md와 결정·결함 패턴 색인에만 둔다. 결함 패턴 번호 P-NN은
결정 번호 꼴과 겹쳐 영역 글자+번호(G·T·C·S·W·B)로 다시 매기고 옛
번호 대응을 evidence.md 4절에 남겼다. 열린 결정 대기는 2026-11-06
리뷰 기준으로 갱신했다.

버린 대안: 초안처럼 docs/improvement/ 장 번호 체계를 유지하기. 백엔드와
진입 경로·검사기가 갈라진다.

위험·한계: 이 커밋만으로는 문서 검사 범위 밖이다. docs/README.md가 이
폴더를 링크하는 커밋부터 verify:documentation이 경로를 본다. cold-read
시험은 하지 않았다.

검증: python3 scripts/check-work-docs.py rc=0(뒤 커밋에서 더함).

Refs: design-docs harness/01-harness-design.md 13절, PR #6
루트에는 리뷰 기준만 담은 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
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
경계 위반, 늘어난 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절
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절
작업마다 착수할 때의 예측과 끝날 때의 실측을 남길 곳이 프론트에 없었다.
소유자 결정(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
README의 지워도 되는 파일 표가 루트 CLAUDE.md를 "템플릿 repo 자신의
리뷰 지시, 자기 것으로 바꿔라"로 분류했다. 소유자 결정(2026-11-07 Q4)은
루트 지침을 템플릿 계약으로 정했다. 그리고 AGENTS.md와 docs/work/는
verify:documentation 범위 밖이라 그 안의 경로·script·게이트 ID가 틀려도
아무 검사도 알리지 않는다.

- README: 문서 절에 AGENTS.md와 docs/work/ 포인터를 더하고, 지워도 되는
  표에서 CLAUDE.md 행을 빼고 docs/ledger/estimates.jsonl("줄을 비운다")을
  넣는다.
- docs/README.md 1절: ../AGENTS.md, work/, work/reference/를 링크한다.
- tests/unit/template-contract-documents.test.ts: 지워도 되는 표에
  AGENTS.md·CLAUDE.md·.claude·docs/work가 없고, 1절이 셋을 링크하는지
  본다. 표는 제목이 아니라 docs/superpowers/ 행으로 찾아 제목을 옮겨도
  돈다. 문서를 읽으니 REMOVAL_FIXTURE_DOCUMENT_TESTS에 올렸다.
- deletable-history-documents.test.ts: CLAUDE.md 패턴을 뺀다(이제 지워도
  되는 문서가 아니다).
- 제거 드릴의 문서 사본(REMOVAL_FIXTURE_DOCUMENT_TARGETS)과
  template-feature-removal-documents.test.ts의 사본에 AGENTS.md를 더한다.
  사본 안에서 검사기를 돌리므로, 1절이 링크한 AGENTS.md가 없으면
  FE-GATE-020과 그 단위 시험이 실패한다.

버린 대안: AGENTS.md를 링크하지 않고 백틱으로만 적기. 검사가 빠진다.

위험·한계: 문서 체계 세션이 README를 한국어로 옮기면 표 제목이 바뀐다.
새 시험은 행으로 찾지만, verify-documentation-readiness.ts의 지운 이력
목록은 영어 제목을 읽으니 그 세션이 같이 고친다.

검증: 새 시험은 README·docs/README.md를 고치기 전 트리에서 둘 다
실패했고(desktop test:unit), 고친 뒤 통과한다. verify:documentation과
merge 단계는 PR 전 합친 트리에서 돌린다.

Refs: design-docs harness/01-harness-design.md 4.4절·13절 Q4
복사한 프로젝트가 이 묶음을 받을 때 할 일(루트 CLAUDE.md를 걸러 내지
않기, .claude/ 무시 규칙, 장부 비우기)과 문서 검사 범위가 넓어진 계약
변경을 적는다. 다른 정리 단계 절과 줄이 겹치지 않게 절을 따로 둔다.

검증: 커밋 칸의 해시는 origin/main 8327e221 위로 rebase한 뒤의 값이다.
reference/review-criteria.md가 docs/reviews/TEMPLATE-MATURITY-REVIEW-
GUIDE.md를 정본의 사본이라 했지만, 그 파일은 2026-11-06부터 design-docs
정본 위치만 적은 포인터다. 드릴 시간 "20분 안팎"은 desktop 실측
822~1,245초(2026-11-06·08)로 바꾼다.

검증: scripts/verify.sh docs rc=0.
template-contract-documents.test.ts가 README 표를 찾으려고
docs/superpowers 경로를 문자열로 적었다. deletable-history-documents.
test.ts는 코드·테스트가 지워도 되는 문서를 가리키면 실패하므로,
desktop merge 단계의 FE-GATE-005에서 이 두 줄로 실패했다.

경로를 조각으로 이어 만든다(그 시험 자신과 같은 방법). 시험이 보는
것은 그대로다.

검증: desktop FE-GATE-005(트리 ada4015c)의 실패 줄이 이 파일 15·35줄
이었다. 고친 뒤 결과는 PR 전 merge 단계에서 본다.
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는 빈 파일).
이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능
만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가
나왔다. 고친 것:

- new-feature: 생성·기준선 다시 쓰기를 desktop에서 하고 --apply-back으로
  받는다. FE-GATE-020은 제품 기능을 지우지 않으므로 그 기능의 제거
  드릴을 따로 돌린다(사실과 달랐다). 생성 명령이 만드는 첫 context는
  중간이다. 새 기능은 FE-GATE-026도 돌린다. 매뉴얼 예시 이름이 오면
  묻는다. 초기 JS 기록의 파일을 적는다.
- gates·improve·AGENTS: FE-GATE-013 결정 대기 동안의 merge 판정 문구,
  PR·diff 리뷰도 merge 단계 전부를 돌린다, diff 리뷰의 base·head 규칙과
  ID 체계와 둘 곳, 라운드 세는 법, "빠른 게이트 8개"를 "검사 8개
  (package script)"로.
- review-criteria: 발견 한 개의 칸(가이드 36.3절 줄임)과 통제 M0~M4·
  증거 E0~E4의 뜻을 옮긴다. 가이드 없이 판정할 수 있다는 문장을 맞춘다.
- README·CLAUDE·decisions·rules/docs·skills: 최근 리뷰 README의 실제 절
  이름, 사고 순서 흔적의 여섯 칸과 design-docs 위치, 보고 칸과 말투의
  정본, `docs/work/README.md`를 가리키게, 리뷰 README 조치 절 예외,
  스킬의 새 명령 모양.

고치지 않은 것: 세션에 주입된 옛 CLAUDE.md(시험 세션이 이 브랜치 전에
시작했다).

검증: scripts/verify.sh docs rc=0, scripts/verify.sh hooks 통과.
donghyeon.kang added 1 commit 2026-11-08 13:40:37 +00:00
donghyeon.kang added 3 commits 2026-11-08 13:57:05 +00:00
하네스 자료는 레이어 규칙·훅·스킬과 함께 비전(세 문장)과 문제 정의(고객의
말 그대로, 하지 않는 것, SMART 성공 기준)를 빈 양식으로 템플릿에 두라고
한다. 프론트에는 둘 다 없었다.

claude-harness template/docs/의 두 파일을 옮긴다. 프로젝트 이름 자리표시자는
빼고, 결정 기록 위치는 이 repo의 docs/architecture/decisions/로 바꿨다.
루트 AGENTS.md가 한 줄로 가리킨다(다음 커밋).

위험·한계: 채울 것 자리는 소유자 몫이라 비워 둔다. 문서 검사 범위
(docs/README.md 1절) 밖이다.

검증: python3 -m unittest scripts/tests/test_claude_setup.py 통과.
계층별 규칙이 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건 통과.
donghyeon.kang added 1 commit 2026-11-08 14:18:53 +00:00
커밋 전 검사 8개, 통합 때 5개, 옛 게이트 11개처럼 config/ci/gates.json과 표가
정하는 개수를 문장에 옮겨 적었다. 표가 바뀌면 문장이 낡는다(문서 체계
검사의 숫자 복사 규칙). 개수를 빼고 표를 가리킨다.

검증: scripts/verify.sh docs rc=0.
donghyeon.kang added 1 commit 2026-11-08 14:40:33 +00:00
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
5fab0e462a
desktop(트리 04bb0e0e)에서 두 가지가 실패했다.
- FE-GATE-010·020: check:adapter-inventory가 "total does not equal 143
  tracked files"로 멈췄다. src/adapters의 AGENTS.md·CLAUDE.md 두 행은
  더했지만 INVENTORY.md 끝의 합계 줄(141/141)을 고치지 않았다.
- scripts/verify.sh parts FE-GATE-013: verify:reproducible-build,
  build:release-candidate, verify:local-evidence가 "missing required CI build
  environment: SOURCE_DATE_EPOCH"로 실패했다. ci:gate는 HEAD에서 이 값을
  만들지만 parts·script는 명령을 직접 부른다.

합계를 143/143으로 고치고, ci_env가 HEAD 커밋 시각으로 SOURCE_DATE_EPOCH를
준다(ci:gate와 같은 값).

검증: python3 -m unittest discover -s scripts/tests 통과(ci_env가 HEAD
SHA·커밋 시각·digest 꼴 이미지를 주는 시험 추가). desktop 재실행은 이
커밋 트리에서.
donghyeon.kang added 1 commit 2026-11-08 15:49:48 +00:00
chore(ledger): 범위가 늘어난 뒤의 하네스 작업 실측으로 고친다
frontend-quality-gates / FE-GATE-003 / typecheck (pull_request) Successful in 1m9s
frontend-quality-gates / FE-GATE-006 / component (pull_request) Successful in 44s
frontend-quality-gates / FE-GATE-007 / integration (pull_request) Successful in 50s
frontend-quality-gates / FE-GATE-011 / build (pull_request) Successful in 40s
frontend-quality-gates / FE-GATE-012 / bundle (pull_request) Successful in 31s
frontend-quality-gates / FE-GATE-013 / security (pull_request) Failing after 31s
frontend-quality-gates / FE-GATE-020 / removability (pull_request) Failing after 10m40s
frontend-quality-gates / FE-GATE-009 / accessibility (pull_request) Successful in 4m40s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-001 / manifest-lockfile (pull_request) Successful in 1m9s
frontend-quality-gates / FE-GATE-002 / lint (pull_request) Successful in 1m5s
frontend-quality-gates / FE-GATE-004 / runtime-schema (pull_request) Successful in 29s
frontend-quality-gates / FE-GATE-005 / unit (pull_request) Failing after 1m41s
frontend-quality-gates / FE-GATE-010 / architecture (pull_request) Successful in 1m42s
frontend-quality-gates / FE-GATE-008 / e2e (pull_request) Failing after 5m59s
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
f98f39a3db
donghyeon.kang merged commit d1b9c08732 into main 2026-11-11 11:25:18 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-frontend-template#13