From 9f8596280c0d5f8d99dafad89fb5a85e8eb8b7c1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 17:25:03 +0900 Subject: [PATCH] =?UTF-8?q?feat(claude):=20=EA=B2=BD=EB=A1=9C=EB=B3=84=20?= =?UTF-8?q?=EA=B7=9C=EC=B9=99=C2=B7=EC=8A=A4=ED=82=AC=C2=B7=EA=B2=B0?= =?UTF-8?q?=EA=B3=BC=EB=A7=8C=20=EB=8F=8C=EB=A0=A4=EC=A3=BC=EB=8A=94=20?= =?UTF-8?q?=EC=84=9C=EB=B8=8C=EC=97=90=EC=9D=B4=EC=A0=84=ED=8A=B8=EB=A5=BC?= =?UTF-8?q?=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .claude/agents/arch-reviewer.md | 29 ++++++ .claude/agents/code-simplifier.md | 27 +++++ .claude/agents/verify-app.md | 31 ++++++ .claude/rules/adapters.md | 18 ++++ .claude/rules/docs.md | 15 +++ .claude/rules/features.md | 17 ++++ .claude/rules/gates-and-budgets.md | 23 +++++ .claude/rules/tests.md | 25 +++++ .claude/settings.json | 29 ++++++ .claude/skills/desktop-gates/SKILL.md | 22 ++++ .claude/skills/new-feature/SKILL.md | 19 ++++ .gitignore | 10 ++ scripts/tests/test_claude_setup.py | 139 ++++++++++++++++++++++++++ 13 files changed, 404 insertions(+) create mode 100644 .claude/agents/arch-reviewer.md create mode 100644 .claude/agents/code-simplifier.md create mode 100644 .claude/agents/verify-app.md create mode 100644 .claude/rules/adapters.md create mode 100644 .claude/rules/docs.md create mode 100644 .claude/rules/features.md create mode 100644 .claude/rules/gates-and-budgets.md create mode 100644 .claude/rules/tests.md create mode 100644 .claude/settings.json create mode 100644 .claude/skills/desktop-gates/SKILL.md create mode 100644 .claude/skills/new-feature/SKILL.md create mode 100644 scripts/tests/test_claude_setup.py diff --git a/.claude/agents/arch-reviewer.md b/.claude/agents/arch-reviewer.md new file mode 100644 index 00000000..85bf8637 --- /dev/null +++ b/.claude/agents/arch-reviewer.md @@ -0,0 +1,29 @@ +--- +name: arch-reviewer +description: 바뀐 TypeScript·규칙 파일이 이 프론트 repo의 경계 규칙(AGENTS.md 꼭 지킬 것 1~3, .dependency-cruiser.json, adapter 배럴·kernel 예외, 기능·context 경계)을 지키는지 읽기만 하고 판정을 돌려준다. 구현이나 수정 묶음을 끝내고 커밋이나 PR 전에, 또는 사용자가 "구조 리뷰", "경계 확인", "레이어 위반 없나", "import 규칙 확인"이라고 할 때 쓴다. 파일을 고치지 않는다. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# arch-reviewer — 경계 규칙 리뷰(읽기 전용) + +맡긴 쪽이 준 범위(기준 커밋, diff, 경로)만 본다. 결과만 돌려주고 파일을 쓰거나 고치지 않는다. Bash는 `git diff`, `git log`, `git grep`, `python3 scripts/check-work-docs.py` 같은 읽기 명령에만 쓴다. pnpm·node·게이트는 돌리지 않는다(판정의 정본인 `check:architecture`는 맡긴 쪽이 desktop에서 돌린다). + +## 순서 + +1. 루트 `AGENTS.md`의 꼭 지킬 것과 지도, `docs/work/reference/structure.md` 2·3절을 읽는다. +2. 바뀐 파일마다 `.dependency-cruiser.json`의 `forbidden` 규칙 중 `from.path`가 그 파일에 맞는 것을 고른다. +3. 그 파일의 import(정적·type-only·re-export·리터럴 dynamic import)를 해석한 경로로 보고, 고른 규칙의 `to.path`·`pathNot`(`$1`은 `from`의 첫 그룹)에 걸리는지 본다. 특히 배럴 밖 import, kernel 셋 밖 adapter 간 import, 기능·context 간 import, presentation의 adapter 직접 import. +4. 새 파일 단위 예외(`pathNot`에 파일 하나를 더함)나 넓어진 예외가 있으면 위반으로 적는다. 예외에는 `comment`(이유·담당·재검토 조건)가 있어야 한다. +5. adapter 파일을 더하거나 옮겼으면 `docs/reviews/adapters/INVENTORY.md`가 같은 diff에서 바뀌었는지 본다. 최상위 `src/` 폴더가 바뀌었으면 `docs/architecture/layers.md` 표와 세 문서의 같은 문장이 바뀌었는지 본다. +6. 판정 규칙이 갈라진 사본으로 생기지 않았는지 본다(같은 판정 표를 두 곳에 두기, kernel이 아닌 곳의 공용 로직). + +## 돌려줄 것 + +```text +판정: 통과 / 위반 있음 / 판단 못 함 +발견: (위반마다) 꼭 지킬 것 번호 또는 규칙 이름 · 파일:줄 · 무엇이 무엇을 import하나 · 근거(문서 경로) +확인 못 한 것: (읽지 못한 파일, 게이트로만 판정할 것 — 예: 사이클, check:architecture) +``` + +발견이 없으면 "발견 0"과 본 파일 수를 적는다. 추측은 발견에 넣지 않고 「확인 못 한 것」에 넣는다. diff --git a/.claude/agents/code-simplifier.md b/.claude/agents/code-simplifier.md new file mode 100644 index 00000000..72156e2b --- /dev/null +++ b/.claude/agents/code-simplifier.md @@ -0,0 +1,27 @@ +--- +name: code-simplifier +description: 지정한 파일·diff에서 동작을 바꾸지 않고 줄일 수 있는 곳(중복, 죽은 분기, 불필요한 래퍼·상태, 더 단순한 표준 API·React 패턴)을 찾아 제안만 돌려준다. 구현을 마친 뒤 "단순하게", "정리할 곳", "중복 없나"라고 할 때나 리뷰 전에 쓴다. 파일을 고치지 않는다. 고치는 일은 맡긴 세션이 한다. +tools: Read, Grep, Glob +model: inherit +--- + +# code-simplifier — 단순화 제안(읽기 전용) + +맡긴 범위만 본다. 제안만 돌려주고 파일을 쓰지 않는다. + +## 지킬 것 + +- 동작을 바꾸는 제안을 하지 않는다. 공개 계약(adapter 배럴 표면, 공개 포트·hook 시그니처, 런타임 설정 키, 오류 code, 짝 백엔드 wire 모양)을 바꾸는 제안은 하지 않는다. +- 경계 규칙(루트 `AGENTS.md` 꼭 지킬 것 1~3)을 어기게 만드는 제안을 하지 않는다. 예: 배럴을 건너뛰어 내부 파일을 바로 import하기, kernel 예외에 파일 하나 더하기. +- 소비자 없는 확장 지점과 빈 레지스트리는 죽은 코드가 아니다. 지우자고 제안하지 않는다. 갈라진 복사본을 하나로 합치는 제안은 한다(합칠 곳은 `src/adapters/platform/`이나 `src/contracts/`). +- 테스트를 줄이는 제안은 단언이 약해지지 않을 때만 한다(`.claude/rules/tests.md`). 예산·기준선·skip을 건드리는 제안은 하지 않는다. +- 요청 범위 밖의 큰 리팩터링은 제안하지 않고 「범위 밖에서 본 것」에 한 줄로 적는다. + +## 돌려줄 것 + +```text +제안: (하나마다) 파일:줄 · 지금 모양 · 바꿀 모양(짧은 코드) · 왜 동작이 같은가 · 그것을 보일 테스트 +범위 밖에서 본 것: (있으면) +``` + +제안이 없으면 "제안 0"과 본 파일 수를 적는다. diff --git a/.claude/agents/verify-app.md b/.claude/agents/verify-app.md new file mode 100644 index 00000000..a25cdc8d --- /dev/null +++ b/.claude/agents/verify-app.md @@ -0,0 +1,31 @@ +--- +name: verify-app +description: 지정한 브랜치·커밋 또는 지금 작업 트리의 앱을 desktop에서 실제로 빌드해 preview로 띄우고, 지정한 라우트를 브라우저(Playwright)로 열어 화면·콘솔 오류·HTTP 응답만 돌려준다. 화면이나 라우트 동작을 바꾼 변경을 끝내고 "직접 돌려 봐", "화면 떠?", "앱 확인", "라우트 열어 봐"라고 할 때나 PR 전 확인으로 쓴다. 노트북에서 pnpm·브라우저를 돌리지 않고, 노트북 checkout의 파일을 고치지 않는다. +tools: Bash, Read, Grep, Glob +model: inherit +--- + +# verify-app — desktop에서 앱을 띄워 확인 + +pnpm·브라우저는 desktop에서만 돈다. 실행 위치의 정본은 `docs/work/operate.md` 4.1절이고, 이 문서는 그 안에서 앱을 띄우는 순서만 적는다. 노트북 checkout은 읽기만 한다. + +## 받을 것 + +- 확인할 트리(push된 브랜치, 또는 지금 작업 트리)와 작업 이름. +- 열 라우트 목록과 기대(보여야 할 제목·텍스트, 없어야 할 콘솔 오류). 없으면 `/`만 본다. + +## 순서 + +1. 앱이 뜨는지는 desktop의 build 게이트로 먼저 본다: `scripts/verify.sh gate FE-GATE-011 --log <작업 이름>-app`. rc와 로그 경로를 적는다. +2. 화면 확인은 같은 트리의 브라우저 게이트로 한다: `scripts/verify.sh gate FE-GATE-008 --log <작업 이름>-app`(e2e, 세 엔진). 특정 라우트만 보려면 desktop에서 `scripts/verify.sh`가 남긴 방식대로 새 worktree를 만들고 그 안에서 `flock /tmp/claude-gates/heavy.lock` 아래 `corepack pnpm build`와 `corepack pnpm exec playwright test `을 돌린다. 기존 checkout `~/workspace/clean-architecture-frontend-template`의 브랜치와 `stash@{0}`는 건드리지 않는다. +3. 받은 라우트마다 화면 텍스트와 콘솔 오류를 확인한다. 브라우저 테스트를 한 checkout에서 둘 이상 돌리면 실행마다 다른 `TEST_RUN_ID`를 준다(`ci:gate`에는 주지 않는다). +4. 끝나면 만든 worktree를 지우고 desktop checkout의 `git status`가 비었는지 본다. + +## 돌려줄 것 + +```text +결과: 떴다 / 안 떴다(멈춘 단계) +라우트: (라우트마다) 경로 · 보인 제목 · 기대와 같은가 · 콘솔 오류 수와 첫 줄 +증거: desktop 로그 경로, summary.txt 첫 줄(트리 해시) +남은 것: 지우지 못한 worktree, 확인 못 한 라우트·엔진 +``` diff --git a/.claude/rules/adapters.md b/.claude/rules/adapters.md new file mode 100644 index 00000000..06f4ef0b --- /dev/null +++ b/.claude/rules/adapters.md @@ -0,0 +1,18 @@ +--- +paths: + - "src/adapters/**" + - ".dependency-cruiser.json" + - "docs/reviews/adapters/INVENTORY.md" +--- + +# adapter와 import 규칙을 고칠 때 + +정본은 `.dependency-cruiser.json`(규칙), `docs/architecture/layers.md`(설명), `docs/work/reference/structure.md`(바꿀 때 같이 고칠 것)다. 판정은 `check:architecture`(FE-GATE-010)다. + +- 그룹 밖에서는 그 그룹의 `index.ts`(배럴)로만 들어간다. 배럴 밖으로 공개 표면을 늘리지 않는다. 2단계 `index.ts`는 공개 배럴이 아니다(예외: `storage/indexeddb`, `storage/opfs`). +- adapter끼리 import하는 예외는 kernel 셋뿐이다: `src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`. 새 공유 프리미티브는 `src/adapters/platform/`에 넣는다. 새 파일 단위 예외를 만들거나 제안하지 않는다. +- adapter는 presentation·bootstrap을 import하지 않는다. 관측 vendor SDK는 adapter 뒤에만 둔다. +- adapter 파일을 더하거나 옮기거나 지우면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다(`check:adapter-inventory`). +- 규칙을 더하거나 이름을 바꾸면 `docs/architecture/layers.md` 규칙 표도 고친다. 예외는 `pathNot`과 `comment`(이유·담당·재검토 조건)를 함께 쓴다. 규칙·예외 변경은 크기가 큼이다(`docs/work/README.md` 2절). +- 편집 훅(N3)은 편집한 파일의 import를 이 규칙 파일에 대 보고 의심 줄을 알린다. 그래프 전체(사이클)는 게이트만 본다. +- 실패 분류는 status와 code를 함께 보고, 짝 백엔드 쓰기 응답 판정은 `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE` 하나만 쓴다. 결과 불명 쓰기의 모든 재전송 입구를 함께 본다. diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md new file mode 100644 index 00000000..651e0844 --- /dev/null +++ b/.claude/rules/docs.md @@ -0,0 +1,15 @@ +--- +paths: + - "**/*.md" +--- + +# 문서를 고칠 때 + +- 문서 위치·묶음·언어 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다. +- 기록 문서(`docs/reviews/`, `docs/history/`, `docs/superpowers/`, 결정 기록)는 머리 블록만 고친다. 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. +- 진입 문서(루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다. 편집 훅이 `scripts/check-work-docs.py`의 실패 줄을 먼저 알려 준다. +- `docs/README.md` 1절이 링크한 문서(루트 `AGENTS.md`, `docs/work/` 포함)는 `verify:documentation`이 백틱 경로·명령 경로·마크다운 링크·package script·FE-GATE ID를 본다. 있는 것만 쓴다. 검사를 피하려고 백틱을 빼지 않는다. 기능 제거 드릴의 문서 사본은 `scripts/lib/removal-fixture.ts`의 목록만 복사하니, 그 목록 밖 루트 파일을 마크다운 링크로 가리키지 않는다. +- repo 밖 문서(design-docs 등)는 링크가 아니라 코드 표기로 쓴다. +- 숫자(예산, 기준선, 테스트 수)를 옮겨 적지 않는다. 정본을 가리킨다. +- 그 문서를 읽는 테스트를 `git grep -n '<파일 이름>' -- tests scripts`로 찾는다. 있으면 desktop에서 돌린다. +- 고친 뒤: 작업 매뉴얼이면 `scripts/verify.sh docs`(노트북), 1절 묶음이면 desktop `scripts/verify.sh script verify:documentation`. diff --git a/.claude/rules/features.md b/.claude/rules/features.md new file mode 100644 index 00000000..4430437e --- /dev/null +++ b/.claude/rules/features.md @@ -0,0 +1,17 @@ +--- +paths: + - "src/features/**" + - "src/contexts/**" + - "tests/features/**" +--- + +# 기능 폴더를 고칠 때 + +정본은 `docs/manual/`(만드는 순서와 판단 기준)과 `docs/work/new-feature.md`(크기·완료 기준)다. 새 기능은 스킬 `new-feature`로 시작한다. + +- 뼈대는 `corepack pnpm create:feature `로 만든다. 다른 기능 폴더를 복사해 이름을 바꾸지 않는다. +- 기능끼리, context끼리 import하지 않는다. 기능의 계층(domain → application → adapters·presentation)은 `.dependency-cruiser.json`의 `feature-*` 규칙을 따른다. 기능 밖 adapter는 기능의 `adapters/`나 `src/features/feature-adapter-contribution.ts`로만 닿는다. +- 기능 폴더 밖 파일을 생성 명령 밖에서 고쳐야 하면 거기서 멈춘다(`docs/manual/03-outside-feature-folder.md`). 크기가 큼이다. +- 기능 테스트는 `tests/features//`에 둔다. 기능과 함께 지워진다. +- 기능을 더하거나 지우면 초기 JS 기록과 기능 모양 기록이 바뀐다. 생성 명령 출력 `Next:`의 명령으로 다시 쓴다. 예산을 넘으면 올리기 전에 멈추고 묻는다. +- 결과 불명 쓰기와 재전송은 `docs/manual/02-decision-tables.md` 3·4절 기준이다. diff --git a/.claude/rules/gates-and-budgets.md b/.claude/rules/gates-and-budgets.md new file mode 100644 index 00000000..0e2d6018 --- /dev/null +++ b/.claude/rules/gates-and-budgets.md @@ -0,0 +1,23 @@ +--- +paths: + - "config/ci/**" + - "config/performance/**" + - "config/scale/**" + - "config/testing/**" + - ".gitea/**" + - "scripts/run-ci-gate.ts" + - "scripts/contracts/**" + - "scripts/check-*.ts" +--- + +# 게이트·예산·기준선을 고칠 때 + +정본은 `config/ci/gates.json`(게이트 ID·단계·명령), `config/performance/budgets.json`(예산), `docs/work/reference/gates.md`(언제 무엇을, 거짓 통과 막기)다. + +- 게이트 기준(문턱, 예산, 기준선, skip·only, ungated 목록)을 낮춰 통과시키지 않는다(꼭 지킬 것 4). 올리거나 넓혀야 하면 결정이다: 이유·대안·재검토 조건을 적고 소유자 결정을 받는다(`docs/work/reference/decisions.md` 3절). +- `config/ci/ungated-scripts.json`·`config/ci/ungated-tests.json`에 줄을 더하는 것은 그 script·테스트를 어느 게이트도 돌리지 않게 하는 일이다. 이유 없이 더하지 않는다. +- 기준선 기록(초기 JS, 기능 모양)은 손으로 고치지 않는다. 측정 스크립트를 `--initial-baseline --write`로 돌린 결과를 같은 변경에 넣는다. +- workflow는 생성기로 만든다. `.gitea/workflows/`만 손으로 고치지 않는다(`check:ci`가 대조한다). +- 새 검사에는 통과 fixture와 거절 fixture를 함께 둔다. 실패 메시지는 넘은 항목·잰 값·고칠 파일을 말한다. 사전 점검은 본 단계와 같은 방법으로 한 번 실행해 본다. +- 바꾼 뒤 desktop에서 `scripts/verify.sh merge`. stage·게이트 목록이 바뀌어도 `scripts/verify.sh`는 계약 파일에서 읽어 따라간다. +- 편집 훅(N6)이 이 파일들의 편집을 알린다. 알림은 막지 않는다. 의도한 변경이면 커밋 본문에 이유와 결정 출처를 적는다. diff --git a/.claude/rules/tests.md b/.claude/rules/tests.md new file mode 100644 index 00000000..70cea1e7 --- /dev/null +++ b/.claude/rules/tests.md @@ -0,0 +1,25 @@ +--- +paths: + - "tests/**" + - "**/*.spec.ts" + - "vitest.config.ts" + - "playwright*.config.ts" +--- + +# 테스트를 쓰거나 고칠 때 + +정본은 `docs/testing/taxonomy.md`(층·명령·실행 환경)와 `docs/work/reference/testing.md`(결함을 막는지 확인하는 법)다. + +1. 층은 프레임워크가 아니라 필요한 실행 환경으로 정한다: Node만 `tests/unit`, React·hook `tests/component`, HTTP/MSW·IndexedDB·조립된 경계 `tests/integration`, 실제 브라우저 `tests/e2e` 등, 한 기능의 테스트 `tests/features//`. +2. 동작을 바꾸면 재현 테스트가 먼저 실패하고(RED) 고친 뒤 통과한다(GREEN). 검출력이 문제였으면 보호 규칙을 지우는 변이를 넣어 새 테스트가 실패하는지 본다. +3. 템플릿 원래 상태 밖에서도 돈다: 기능을 더한 상태, 확장 지점을 채운 상태, 입력·객체가 셋 이상. +4. 단언이 대상에 닿는지 본다: fixture가 비어 첫 줄에서 return하지 않는가, 로딩·오류 화면이나 fixture 자신을 검사하지 않는가. +5. `.only`를 두지 않는다. `.skip`·`fixme`는 Playwright spec에만, owner·defect·route·만료일이 있는 quarantine으로만 둔다(`scripts/check-test-evidence.ts`). 빠른 계층에는 quarantine이 없다. 편집 훅이 마지막 커밋보다 늘어난 skip·only·fixme·todo를 알린다. +6. 가끔 떨어지는 테스트를 재시도·timeout 늘리기·worker 줄이기·`force` 클릭으로 덮지 않는다. 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로 원인을 찾는다. +7. 환경에 기대지 않는다: gitignore된 생성물, 작성자 PC의 글꼴·CPU, 바깥 env(`CI=true`, 빌드 식별값). 테스트가 띄우는 빌드·서버의 env는 테스트가 정한다. +8. 플랫폼 테스트를 기능·스타터 화면에 묶지 않는다(테스트 전용 라우트, `tests/mocks/`). 테스트가 지워도 되는 문서(`docs/reviews/` 등)를 읽지 않는다. +9. 자식 프로세스를 띄우는 suite는 자기 timeout을 선언한다. 전역 timeout을 올리지 않는다. + +## 돌리는 법 + +- 노트북에서는 돌리지 않는다. 한 파일도 desktop에서: `scripts/verify.sh script test:unit`, 또는 `ssh desktop`으로 `node scripts/run-vitest.ts run `(이 runner가 생성물을 먼저 만든다. `pnpm exec vitest run `은 import 오류로 실패한다). diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..5dfb8657 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,29 @@ +{ + "permissions": { + "deny": [ + "Read(**/.env)", + "Read(**/.env.local)", + "Read(**/.env.*.local)", + "Read(**/.env.development)", + "Read(**/.env.staging)", + "Read(**/.env.production)", + "Edit(**/.env)", + "Edit(**/.env.local)", + "Edit(**/.env.*.local)", + "Edit(**/.env.development)", + "Edit(**/.env.staging)", + "Edit(**/.env.production)" + ] + }, + "extraKnownMarketplaces": { + "claude-harness": { + "source": { + "source": "git", + "url": "https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git" + } + } + }, + "enabledPlugins": { + "harness@claude-harness": true + } +} diff --git a/.claude/skills/desktop-gates/SKILL.md b/.claude/skills/desktop-gates/SKILL.md new file mode 100644 index 00000000..1d658877 --- /dev/null +++ b/.claude/skills/desktop-gates/SKILL.md @@ -0,0 +1,22 @@ +--- +name: desktop-gates +description: 이 프론트 repo에서 pnpm·게이트·테스트·빌드·브라우저(Playwright)·성능 측정을 돌려야 할 때 쓴다. 노트북에서는 돌리지 않고 scripts/verify.sh로 desktop에 옮겨 공유 잠금 아래 돌린다. 사용자가 "테스트 돌려", "게이트", "검증해", "merge 게이트", "ci:gate", "FE-GATE", "lint 돌려", "타입 검사"라고 하거나, 편집 훅이 턴 끝에 desktop 검증이 없다고 알렸을 때, merge 가능을 말하기 전에 부른다. 지금 트리를 패치로 보내 같은 트리에서 돌리는 법, CI env, FE-GATE-013 기록법, 로그·rc 남기기를 준다. +--- + +# desktop에서 게이트 돌리기 + +정본은 `docs/work/operate.md` 4.1절(실행 위치)·4.2절(기록)과 `docs/work/reference/gates.md`(무엇을 돌릴지)다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. + +1. 무엇을 돌릴지 고른다(`gates.md` 2절). merge 가능을 말하려면 `merge` 단계 전부다. 고른 스크립트 목록으로 merge 가능을 말하지 않는다. +2. `ssh desktop uptime`으로 부하를 적는다. +3. 돌린다. 오래 걸리면 background로 띄우고 끝나기를 한 번 기다린다. + - 단계: `scripts/verify.sh merge --log <작업 이름>` + - 게이트 하나: `scripts/verify.sh gate FE-GATE-005 --log <작업 이름>` + - 게이트의 명령을 끝까지: `scripts/verify.sh parts FE-GATE-013 --log <작업 이름>` + - package script: `scripts/verify.sh script verify:documentation test:unit --log <작업 이름>` + - 먼저 무엇을 돌릴지만 보려면 `--dry-run`. +4. 스크립트가 하는 일: 지금 트리를 패치로 보내고, desktop 공유 checkout에서 새 worktree를 만들어 같은 트리인지 해시로 보고, 깨끗한 커밋 하나로 만들어 오프라인 설치 뒤 `flock /tmp/claude-gates/heavy.lock` 아래 CI env(`CI=true` 등)로 돌린다. 공유 checkout의 브랜치와 stash는 건드리지 않는다. push하지 않는다. +5. 결과를 읽는다: desktop `/tmp/claude-gates/<작업 이름>/summary.txt`(첫 줄이 트리 해시), 게이트별 로그, `gate-artifacts/`, `status-after.txt`(비어 있어야 한다). +6. FE-GATE-013은 desktop에서 호스트 제약(user namespace)으로 실패한다. "호스트 제약 실패"로 적고 `parts`로 뒤 명령 결과를 함께 적는다. +7. 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다. 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. +8. 보고에는 단계·게이트, rc, 시간, 핵심 숫자, 직전 부하, 트리 해시, 로그 경로를 적는다(`operate.md` 8절 표). diff --git a/.claude/skills/new-feature/SKILL.md b/.claude/skills/new-feature/SKILL.md new file mode 100644 index 00000000..d7a2e313 --- /dev/null +++ b/.claude/skills/new-feature/SKILL.md @@ -0,0 +1,19 @@ +--- +name: new-feature +description: 이 프론트 템플릿(또는 복사한 프로젝트)에 새 기능(화면과 그 화면이 쓰는 API 호출, src/features//)을 더할 때 쓴다. 사용자가 "기능 추가", "새 화면", "새 페이지", "create:feature", "/new-feature ", "백엔드 API에 화면 붙이기"라고 하거나, brief의 작업 종류가 docs/work/new-feature.md일 때 부른다. corepack pnpm create:feature로 뼈대를 만들고 docs/manual 0~11단계로 채운 뒤 desktop에서 merge 단계를 돌리는 순서를 준다. 있는 기능을 고치는 일은 이 스킬이 아니라 docs/work/improve.md다. +--- + +# 새 기능 만들기 + +정본은 `docs/work/new-feature.md`(크기·받을 것·완료 기준)와 `docs/manual/`(만드는 순서와 판단 기준)이다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. + +1. `docs/work/README.md`, `docs/work/new-feature.md`, `docs/manual/README.md`를 읽고 크기를 정한다. 새 context, 기능 폴더 밖 파일 수정, 짝 백엔드와 새 계약, 예산 상향은 큼이다. 큼이면 만들기 전에 `docs/work/research-design.md`대로 소유자 검토를 받는다. +2. 받을 것을 확인한다: 기능 ID(케밥, 40자 이하), context, 짝 백엔드 경로와 작성 API 유무(`--with-create`), 재전송될 수 있는 쓰기인지(`--keyed`), 계약 패키지 신원. 백엔드 쪽 사실이 brief에 없으면 묻는다. +3. 뼈대: `corepack pnpm create:feature [--context ] [--with-create [--keyed]]`. node가 필요하니 desktop이나 노트북의 깨끗한 복제본에서 만든다. 출력의 `Next:` 목록을 보고에 옮긴다. +4. `docs/manual/01-add-a-feature.md` 2~10단계로 채운다. 막히면 02 결정표, 폴더 밖 파일은 03, 짝 백엔드 인증은 04, 오류 메시지는 `docs/manual/reference/errors.md`. +5. 동작은 테스트를 먼저 쓴다(`tests/features//`, 규칙은 `.claude/rules/tests.md`). 결과 불명 쓰기와 재전송 입구는 02 결정표 3·4절. +6. 편집 훅의 경계 알림(N3)이 나오면 그 자리에서 고친다. 기능끼리 import하지 않는다. +7. 초기 JS 기록은 `Next:`의 명령으로 다시 쓰고 같은 커밋에 넣는다. 예산을 넘으면 올리지 말고 멈추고 묻는다. +8. desktop에서 `scripts/verify.sh merge --log <기능 id>`(스킬 `desktop-gates`). 라우트 로딩을 바꿨으면 `scripts/verify.sh gate FE-GATE-026`도. +9. 결과를 보고 싶으면 서브에이전트 `arch-reviewer`(경계 리뷰)와 `verify-app`(desktop에서 앱을 띄워 그 라우트를 연다)에 맡긴다. +10. `docs/work/new-feature.md` 8절 형식으로 보고한다. diff --git a/.gitignore b/.gitignore index 34cdbac7..7347b810 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,13 @@ artifacts/tests/a11y-manual/* # graphify knowledge-graph output (local analysis, not part of the product). graphify-out/ + +# Claude Code: the project settings, path rules, skills and subagents are the +# template's (AGENTS.md, scripts/hooks/README.md). Session worktrees, the hook +# state and a developer's settings.local.json stay out. +.claude/* +!.claude/settings.json +!.claude/rules/ +!.claude/agents/ +!.claude/skills/ +__pycache__/ diff --git a/scripts/tests/test_claude_setup.py b/scripts/tests/test_claude_setup.py new file mode 100644 index 00000000..c0eb889c --- /dev/null +++ b/scripts/tests/test_claude_setup.py @@ -0,0 +1,139 @@ +"""루트 지침과 `.claude/`의 규칙·스킬·서브에이전트가 소유자 결정(2026-11-07)대로인지 본다. + +결과만 받는 일은 서브에이전트, 파일을 바꾸는 위임은 하위 세션이다(docs/work/delegate.md 4.3절). +새 스킬은 모두 모델이 부를 수 있고, 설명에 발동 조건을 문단으로 적는다. + + python3 -m unittest discover -s scripts/tests +""" + +from __future__ import annotations + +import json +import re +import unittest +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent.parent +CLAUDE = REPO / ".claude" +# Claude Code cuts a skill description at this many characters in the listing. +DESCRIPTION_LIMIT = 1536 +WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"} + + +def front_matter(path: Path) -> tuple[dict[str, str], list[str]]: + """The scalar fields and the list items of a document's YAML front matter.""" + match = re.match(r"^---\n(.*?)\n---\n", path.read_text(encoding="utf-8"), re.S) + if not match: + return {}, [] + fields, items = {}, [] + for line in match.group(1).splitlines(): + if line.lstrip().startswith("- "): + items.append(line.strip()[2:].strip('"')) + continue + key, _, value = line.partition(":") + fields[key.strip()] = value.strip() + return fields, items + + +class RootInstructionsTest(unittest.TestCase): + def test_claude_md_imports_the_map_and_says_how_to_install_the_plugin_non_interactively(self) -> None: + text = (REPO / "CLAUDE.md").read_text(encoding="utf-8") + self.assertEqual(text.splitlines()[0], "@AGENTS.md") + for command in ("claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git" + " --scope project", "claude plugin install harness@claude-harness --scope project"): + self.assertIn(command, text) + + def test_the_map_holds_the_five_rules_the_router_and_the_entry_point(self) -> None: + text = (REPO / "AGENTS.md").read_text(encoding="utf-8") + self.assertEqual(len(re.findall(r"^[1-5]\. ", text.split("## 지도")[0], re.M)), 5) + for fragment in ("docs/work/README.md", "scripts/verify.sh", "config/ci/gates.json", ".dependency-cruiser.json", + "하위 세션", "서브에이전트"): + self.assertIn(fragment, text) + + def test_the_review_criteria_left_the_session_instructions(self) -> None: + for path in ("AGENTS.md", "CLAUDE.md"): + text = (REPO / path).read_text(encoding="utf-8") + self.assertNotIn("28개 관점", text, path) + self.assertNotIn("서브에이전트를 병렬로", text, path) + + +class SubagentTest(unittest.TestCase): + AGENTS = CLAUDE / "agents" + + def test_the_agent_tool_is_not_denied(self) -> None: + settings = json.loads((CLAUDE / "settings.json").read_text(encoding="utf-8")) + deny = settings.get("permissions", {}).get("deny", []) + self.assertFalse([rule for rule in deny if rule == "Agent" or rule.startswith("Agent(")]) + + def test_each_definition_names_itself_and_says_when_to_use_it(self) -> None: + definitions = sorted(self.AGENTS.glob("*.md")) + self.assertEqual([path.stem for path in definitions], ["arch-reviewer", "code-simplifier", "verify-app"]) + for path in definitions: + fields, _ = front_matter(path) + self.assertEqual(fields.get("name"), path.stem, path) + self.assertIn("쓴다", fields.get("description", ""), path) + self.assertTrue(fields.get("tools"), f"{path} must list its tools; an empty list inherits every tool") + + def test_no_subagent_can_edit_files(self) -> None: + for path in self.AGENTS.glob("*.md"): + tools = {tool.strip() for tool in front_matter(path)[0].get("tools", "").split(",")} + self.assertFalse(tools & WRITE_TOOLS, f"{path} returns results only; it must not hold {tools & WRITE_TOOLS}") + + def test_the_reviewers_run_nothing_heavy(self) -> None: + self.assertNotIn("Bash", front_matter(self.AGENTS / "code-simplifier.md")[0]["tools"]) + reviewer = (self.AGENTS / "arch-reviewer.md").read_text(encoding="utf-8") + self.assertIn("파일을 쓰거나 고치지 않는다", reviewer) + self.assertIn("pnpm·node·게이트는 돌리지 않는다", reviewer) + + def test_verify_app_runs_on_the_desktop_under_the_shared_lock(self) -> None: + text = (self.AGENTS / "verify-app.md").read_text(encoding="utf-8") + for fragment in ("docs/work/operate.md", "scripts/verify.sh", "flock /tmp/claude-gates/heavy.lock", + "stash@{0}", "TEST_RUN_ID"): + self.assertIn(fragment, text) + + +class SkillTest(unittest.TestCase): + CANON = {"new-feature": "docs/work/new-feature.md", "desktop-gates": "docs/work/operate.md"} + + def test_the_repository_skills_are_the_two_the_manual_names(self) -> None: + self.assertEqual(sorted(path.parent.name for path in (CLAUDE / "skills").glob("*/SKILL.md")), sorted(self.CANON)) + + def test_each_skill_is_model_invoked_and_says_when_in_its_description(self) -> None: + for name in self.CANON: + fields, _ = front_matter(CLAUDE / "skills" / name / "SKILL.md") + self.assertEqual(fields.get("name"), name) + self.assertNotIn("disable-model-invocation", fields) + description = fields.get("description", "") + self.assertLessEqual(len(description), DESCRIPTION_LIMIT, name) + self.assertIn("쓴다", description, f"{name}: say when to use it") + self.assertIn("부른다", description, f"{name}: say what the user says that calls it") + + def test_each_skill_points_at_its_canonical_playbook_instead_of_copying_it(self) -> None: + for name, canon in self.CANON.items(): + body = (CLAUDE / "skills" / name / "SKILL.md").read_text(encoding="utf-8") + self.assertIn(f"정본은 `{canon}`", body) + self.assertIn("정본이 맞다", body) + + +class PathRuleTest(unittest.TestCase): + def test_every_rule_is_scoped_by_paths_that_exist(self) -> None: + rules = sorted((CLAUDE / "rules").glob("*.md")) + self.assertEqual([path.stem for path in rules], ["adapters", "docs", "features", "gates-and-budgets", "tests"]) + for path in rules: + fields, patterns = front_matter(path) + self.assertIn("paths", fields, path) + self.assertTrue(patterns, path) + for pattern in patterns: + # A pattern that matches nothing is a rule nobody reads. + self.assertTrue(next(REPO.glob(pattern), None), f"{path}: '{pattern}' matches no file") + + +class GitignoreTest(unittest.TestCase): + def test_the_shared_claude_files_are_tracked_and_session_state_is_not(self) -> None: + lines = (REPO / ".gitignore").read_text(encoding="utf-8").splitlines() + for line in (".claude/*", "!.claude/settings.json", "!.claude/rules/", "!.claude/agents/", "!.claude/skills/"): + self.assertIn(line, lines) + + +if __name__ == "__main__": + unittest.main()