문제: runner PR 1회(merge job 셋, capacity 1이라 차례로)가 28.5분이다 (run 151). tests job의 FE-GATE-020이 13분 13초로 가장 크고, 그 안의 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)이 약 7분이다. worker를 늘리지 않는 대책을 다 넣어도 25분 목표에 닿지 않는다. 고른 방법(소유자 결정 p, 2026-11-12): 그 드릴 셋을 새 게이트 FE-GATE-030 `optional-removability`로 떼어 main 단계(`main_gate`, FE-GATE-029 다음)에서 돌린다. 샘플 제거와 scaffold 드릴은 merge의 FE-GATE-020에 남는다. 짝 백엔드가 무거운 lane을 nightly로 옮긴 것과 같은 모양이다. - 계약: 정규 게이트 ID를 001..030으로, MAIN_READY를 029·030으로, main_gate job의 게이트를 029·030으로 바꾼다. 계약 보고서의 gateCount는 29(016은 은퇴). - scaffold 드릴의 제외 목록에서 셋을 뺀다. 이제 merge 명령이 아니라서, 계약 검사가 「merge 밖 명령을 제외하면 숨긴다」고 거절했다. - main job 이름을 `main / self-tests and removal drills`로 바꾼다. - 시험: 020은 merge·merge_test에서 sample·scaffold만, 030은 main·main_gate에서 셋을 돈다고 단언한다. 승격 공식 시험에 030을 더한다. - 문서: 결정 색인(decisions.md 2.2), 구조·시험·리뷰 기준·CI 문서, fe-structure 스킬의 드릴 명령. 위험·한계: 선택 runtime을 바꾼 PR의 제거 회귀는 병합 뒤 main run에서 본다. main이 빨강이면 다음 PR이 고친다. 그런 PR은 `scripts/verify.sh gate FE-GATE-030`을 직접 돌려야 한다(structure.md 12절에 적음). 파생 프로젝트가 main job 이름을 필수 검사로 걸었으면 이름이 바뀐다. 검증(desktop): generate:ci-workflow, 생성 시험 스냅샷 갱신, ci-workflow-generation·promotion-readiness·feature-scaffold-drill· removal-drill-test-paths·example-feature-rules 등 483개 통과, check:ci(29 gates) rc=0, check:ci:gating rc=0, verify:documentation PASS_SCOPED, check:types·eslint rc=0. 로그 /tmp/claude-gates/w2fe2-o1b~g/.
14 KiB
14 KiB
구조 기준 — 폴더·모듈·코드
폴더 구조와 import의 규칙은 이미 코드와 게이트에 있다. 이 문서는 구조를 바꿀 때 어느 정본을 같이 고쳐야 하는지, 리뷰에서 구조 결함으로 볼 것과 보지 않을 것, 그리고 게이트가 지키지 못해 반복된 코드 결함을 막는 기준을 적는다. 괄호 안 결함 패턴 X0은 defect-patterns.md의 행이다.
src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
│ 규칙: .dependency-cruiser.json (check:architecture, FE-GATE-010)
├─ adapters/<그룹>/index.ts ── 공개 경계(배럴)
│ └─ platform/** 등 kernel 3곳만 그룹을 넘어 import 가능
├─ features/<id>/ ── 지울 수 있는 기능 하나 (제거 드릴, FE-GATE-020)
└─ contexts/, apps/ ── 기능 묶음과 배포 단위
1. 정본
| 무엇 | 정본 | 검사 |
|---|---|---|
최상위 src/ 폴더와 각 역할 |
docs/architecture/layers.md 표 |
verify:documentation이 폴더 목록·설명 일치를 본다 |
| import 규칙 | .dependency-cruiser.json forbidden, 설명은 docs/architecture/layers.md |
check:architecture |
| adapter kernel | docs/architecture/layers.md, 규칙 adapters-do-not-know-other-concrete-adapters |
check:architecture |
| 규칙 예외의 이유·담당·재검토 조건 | 그 규칙의 comment |
사람이 본다 |
| adapter 그룹의 공개 경계 | 규칙 adapter-groups-are-reached-through-their-barrel |
check:architecture, 고정 fixture tests/fixtures/architecture/dependency-graph/barrel |
| adapter 파일 목록 | docs/reviews/adapters/INVENTORY.md |
check:adapter-inventory(FE-GATE-010) |
| 공유 타입·프리미티브를 어디에 둘지 | docs/architecture/contract-ownership.md 「Decision rule」 |
사람이 본다 |
| 기능 폴더의 모양 | docs/manual/01-add-a-feature.md, create:feature가 만드는 파일 |
FE-GATE-020의 test:feature-scaffold |
| 재시도 의미, 결과 불명, 인증, 업로드의 판단 기준 | docs/manual/02-decision-tables.md |
사람이 본다 |
| 오류·재시도·실패 경계·trace 모델 | docs/architecture/scale-architecture.md(코드 주석의 scale-architecture.md §N) |
사람이 본다 |
| 짝 백엔드 쓰기 응답의 판정 표 | src/adapters/http/backend-envelope.ts의 REFUSED_BEFORE_WRITE, 근거 docs/architecture/backend-api-and-server-state-contract.md 6.1절 |
짝 계약 대조 테스트 |
2. 이 repo의 고정 전제
- 확장 지점은 남긴다. 소비자 없는 코드와 빈 레지스트리는 다운스트림용이다. 죽은 코드로 보고 지우지 않는다(소유자 결정 2026-09-16).
- 갈라진 중복 복사본은 하나로. 같은 일을 하는 코드가 두 벌이고 서로 달라지기 시작했으면 결함이다(결함 패턴 S3). 합칠 곳은 kernel(
src/adapters/platform/)이나src/contracts/다. - 배럴이 공개 경계다. 그룹 바깥(
src/bootstrap,src/features,src/presentation)은 그룹의index.ts만 import한다. 배럴 폐지안은 2026-09-16에 기각됐다. 2단계index.ts는 공개 배럴이 아니다(예외:storage/indexeddb,storage/opfs서브배럴). - kernel 예외는 셋뿐이다.
src/adapters/platform/폴더 전체,src/adapters/browser-file-storage/result.ts,src/adapters/cross-context-invalidation/index.ts. 새 파일 단위 예외를 제안하지 않는다. 새 공유 프리미티브는src/adapters/platform/에 넣는다. 폴더 전체가 예외라 규칙을 바꿀 필요가 없다. - 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. 서버 메모리 상태·다중 인스턴스 경쟁 기준은 적용하지 않는다. 탭 사이 경쟁은 적용한다.
3. 바꿀 때 같이 고칠 것
| 바꾸는 것 | 같은 커밋에서 고칠 것 |
|---|---|
최상위 src/ 폴더 추가·삭제 |
docs/architecture/layers.md 표 한 행. 같은 설명 문장을 루트 README.md, docs/architecture/overview.md, docs/architecture/frontend-application-foundation.md에 그대로(verify:documentation이 대조한다) |
| import 규칙 추가·이름 변경 | .dependency-cruiser.json, docs/architecture/layers.md 규칙 표의 행 |
| 규칙 예외 | 그 규칙의 pathNot과 comment(이유·담당·재검토 조건). 파일 단위 kernel 예외는 만들지 않는다 |
| adapter 파일 추가·이동·삭제 | docs/reviews/adapters/INVENTORY.md |
| adapter 그룹 공개 표면 | 그 그룹의 index.ts |
| 기능·context 경계 | src/features/<id>/와 tests/features/<id>/. 기능끼리, context끼리 import하지 않는다 |
| 지울 수 있는 단위(기능, recipe, 선택 runtime) | 그 단위의 제거 드릴이 함께 지울 목록(scripts/test-sample-removal.ts 머리말) |
4. 문서 위치와 지워도 되는 문서
- 지금 코드가 지키는 규칙은 제자리의 살아 있는 문서(
docs/README.md1절 지도), 설계서는docs/design/, 결정 기록은docs/adr/, 계획·증거는docs/history/, 리뷰는docs/reviews/(앞 둘은 복사한 프로젝트가 지울 수 있다), 새 기능 절차는docs/manual/, 작업 절차는docs/work/, 여러 repo에 걸친 설계는 repo 밖 design-docs다. - 코드·테스트·스크립트·설정은 지워도 되는 문서(루트
README.md의 지워도 되는 파일 표)를 읽지 않는다. 예외는docs/reviews/adapters/INVENTORY.md하나다.tests/unit/deletable-history-documents.test.ts가 검사한다. 테스트가 리뷰 문서를 열어 제거 드릴 셋을 깨뜨린 일이 있다. - 루트
AGENTS.md·CLAUDE.md,.claude/,docs/work/는 지워도 되는 문서가 아니다. 복사한 프로젝트가 받는 템플릿 계약이다(소유자 결정 2026-11-07). - 현재 계약 문서는 작업 이력 문서에 기대지 않는다.
5. 리뷰에서 구조 결함으로 보는 것
| 결함으로 본다 | 결함으로 보지 않는다 |
|---|---|
| 갈라진 중복 복사본(결함 패턴 S3) | 소비자 없는 확장 지점, 빈 레지스트리 |
| 같은 사실을 여러 곳에 손으로 다시 적는다(결함 패턴 S1) | 인터페이스가 많다는 사실만으로 |
| 문서가 없는 폴더·규칙을 말한다 | kernel 폴더가 크다는 사실만으로 |
| 템플릿 파일을 고쳐야 기능을 더하거나 지울 수 있다(결함 패턴 S4) | 다운스트림이 쓰지 않는 선택 runtime |
| 지울 수 있다고 한 단위를 지우면 게이트가 실패한다 |
6. 코드 기준 — 판정 규칙은 한 곳에
- 실패 분류는 status 하나로 하지 않는다. status와 code를 함께 본다. 표 밖의 값은 안전한 쪽(결과 불명)으로 둔다. 업무 거절이 결과 불명으로, 일시 오류가 무결성 실패로 분류되는 결함이 여러 영역에서 났다(결함 패턴 C1).
- 짝 백엔드 쓰기 응답의 판정 표는
REFUSED_BEFORE_WRITE하나다. 실행 경로가 둘이어도 같은 표를 읽는다. operation 단위 예외는 descriptor의commandEffect.refusedBeforeWritecode 목록으로만 선언한다. - 결과 불명 쓰기를 다시 보내는 모든 입구를 함께 본다. 재전송 버튼, hook 재제출, 실행기 재시도, poll 재시도, 업로드 재시도. 하나를 막으면 다른 입구에서 다시 나왔다. 키 없는 쓰기(
NEVER)는 결과 불명 뒤 재전송하지 않는다. 키 있는 쓰기는 같은 키로만 다시 보낸다(결함 패턴 C2). - 판정 규칙의 경계를 테스트로 고정한다. 경계 하나를 바꾸는 변이가 게이트에서 실패해야 한다(testing.md 3절).
7. 코드 기준 — 실패는 드러나게
- 원인과 추적값을 싣는다. 실패 객체·진단에 effect, reason,
traceId, 어느 참여자인지를 싣는다. 서로 다른 실패를 같은 reason으로 남기지 않는다. 진단 reason은 이 repo가 소유한 닫힌 목록이고 서버 code를 그대로 넣지 않는다. 서버 code는 실패의AppFailure.code에 남는다. 새 adapter도 같은 기준으로 리뷰한다(결함 패턴 C6). - 오지 않을 신호를 기다리지 않는다. 모든 대기에는 끝나는 조건(예산 소진, 마감, 취소)이 있다 [제안](결함 패턴 C3).
- 손상 한 건이 전체를 멈추지 않게 한다. 손상 행은 건너뛰고 수를 보고한다(결함 패턴 C4).
- 결과를 사실대로 보고한다. 다 하지 못했으면
COMPLETED·verified·active를 보고하지 않는다. 읽은 시점과 보고 시점 사이에 다른 작업(다른 탭의 put, release)이 끼어들 수 있으면, 같은 잠금 아래에서 다시 대조하거나 끝난 뒤 한 번 더 센다. 테스트는 객체 셋 이상으로 한다(결함 패턴 C5). - 실패·복구 전이 뒤 화면이 다음 행동을 남긴다. 실패 표시에서 고친 포커스·안내를 복구 성공, 확인, 진행 중 전이에도 쓴다. 페이지마다 복사하지 않고 공용 폼 hook 안에서 한다(결함 패턴 C11).
- 확인하지 못한 판정은
PASS가 아니라UNVERIFIED다. 코드에 상수true판정을 두지 않는다.
8. 코드 기준 — 같은 사실은 한 곳에
- repo 안: 스키마 메타, 레지스트리 행, 허용 키 목록, 빌드 입력 목록, 저장 키를 원본(zod 스키마, descriptor, registry)에서 뽑는다. 손으로 다시 적어야 하면 원본과 대조하는 테스트를 같이 둔다. 두 검사기가 같은 산출물을 다른 키 목록으로 읽어 merge 게이트가 항상 실패한 일이 있다(결함 패턴 S1).
- 이미 갈라진 복사본은 하나로 합친다. 갈라진 recipe port는 지우고
srcport를 다시 내보낸다. - 두 템플릿 사이: 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 옮길 때는 백엔드 문서만 보지 않고 코드까지 따라간다(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 일이 있다. 옮긴 사실은 기준 커밋(
config/contracts/backend-contract-pin.json)과 대조 테스트로 묶는다. pin과 drift 검사는 아직 계약 문서 글자만 비교하고, 답 표 JSON과 생성기 사실은 대조 밖이다(결함 패턴 S2). - 짝 백엔드 repo는 읽기만 한다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다.
9. 코드 기준 — 지우거나 바꿀 때
- 그 코드가 지키던 것을 찾는다. 실행 동작만 옮기면 지운 행·테스트·분기가 지키던 규칙이 조용히 사라진다. 지우기 전에 그 코드를 읽는 테스트와 검사를
git grep으로 찾고, 각각이 지키던 규칙이 새 경로에도 있는지 적는다(결함 패턴 T10). - 이름을 바꿀 때는 새 이름을 내고 옛 이름은 한 릴리스 동안
@deprecated별칭으로 남긴다. 이름 하나가 여러 뜻을 가지거나 한 뜻이 여러 이름을 가지면 결함이다(결함 패턴 C10). - 공개 포트는 추가만 한다. 깨야 하면 결정 표에 적고 BREAKING으로 커밋한다.
10. 코드 기준 — 설정·환경, 동시성, 확장 지점
- 같은 설정을 경로마다 다르게 읽지 않는다. 번들, 빌드 스크립트, Service Worker 빌드가 같은 출처에서 읽는다(결함 패턴 C8).
- URL은 router base path를 따른다.
/부터 직접 조립하지 않는다. 기본 게이트가 루트 경로만 돌아 드러나지 않는다. 하위 경로 빌드 테스트로 확인한다(결함 패턴 C7). - 테스트가 띄우는 빌드·서버의 env는 테스트가 정한다(gates.md 4절).
- 환경 가정은 적고, 확인하고, 없으면 이유를 말하며 실패한다. 글꼴, user namespace, 옆 checkout(결함 패턴 G6).
- 여러 탭이 같은 저장소·구독·잠금을 건드리는 경로는 Web Locks로 직렬화하거나 잠금 없이도 안전한 이유를 적는다. 잠금을 기다리는 작업에는 abort와 상한이 있다(결함 패턴 C9).
- 제품마다 다른 것은 제품 소유 파일에 둔다. 제품이 템플릿 소유 파일을 고쳐야 하면 결함이다. 동기화마다 같은 파일이 충돌한다. 제품 소유 자리의 예:
src/bootstrap/product-composition.ts,src/contracts/product-contracts.ts,config/ci/product-gates.json. 효과는 다음 동기화 충돌 수로 잰다(결함 패턴 S4). - 경계 예외는 실제 쓰임만큼만 연다. kernel 폴더에는 공유 메커니즘만 둔다(결함 패턴 S5).
- 두 모듈이 이어지는 곳을 지나는 테스트를 둔다. 한쪽이 보내는 결과를 다른 쪽이 다른 뜻으로 받는 결함은 연결 지점에서만 보인다(결함 패턴 S6).
11. 고칠 때 — 수정이 새로 가정하는 것
2026-11-05 리뷰의 새 발견 48건 중 22건은 원인이 지난 수정이었다. 수정 커밋마다 본문 「위험·한계」에 적는다(결함 패턴 G13).
- 이 변경이 새로 가정하는 상태(빈 제품 파일, CI env 없음, 객체 하나, 기능 0개 등).
- 그 가정이 깨지는 지원 구성에서 한 번 돌렸는가(../improve.md 4.2절 6단계).
- 이 변경이 다른 검사를 약하게 했는가. 경로를 백틱 밖으로 옮겨 문서 검사를 피한 수정이 그 경로를 검사 밖으로 냈다. 위험을 커밋 본문에 적고도 테스트하지 않아 다운스트림 게이트가 항상 실패한 수정도 있다.
12. 제거 가능성
지울 수 있는 단위는 드릴이 지킨다. 기능 드릴(샘플 제거, 생성 기능의 scaffold·제거)은 merge 게이트 FE-GATE-020, 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)은 main 단계 FE-GATE-030이다(소유자 결정 2026-11-12). 드릴 목록은 config/ci/gates.json의 두 게이트 commandIds다. 선택 runtime을 바꾼 PR은 merge에서 FE-GATE-030이 돌지 않으니 scripts/verify.sh gate FE-GATE-030을 직접 돌린다.
- 구조를 바꾸면 드릴을 돌린다. 드릴 fixture가 복사하는 목록(
scripts/lib/removal-fixture.ts, 이 목록 하나만 쓴다)이 바뀐 구조를 아는지 본다. 그 목록에README.md·CHANGELOG.md가 없어 드릴 넷 중 셋이 항상 실패한 일이 있다(결함 패턴 G11). - 드릴은 오래 걸린다(desktop 2026-11-13 실측: FE-GATE-020과 FE-GATE-030 합쳐 약 10분 30초). desktop에서 잠금 아래 돌린다.