diff --git a/docs/improvement/03-folder-module-structure.md b/docs/improvement/03-folder-module-structure.md new file mode 100644 index 00000000..13caa63a --- /dev/null +++ b/docs/improvement/03-folder-module-structure.md @@ -0,0 +1,99 @@ +# 03. 폴더·모듈 구조 기준 + +## 핵심 + +폴더 구조의 규칙은 이미 코드와 게이트에 있다. 이 장은 **구조를 바꿀 때 어느 정본을 같이 고쳐야 하는지**와 +**리뷰에서 구조 결함으로 볼 것과 보지 않을 것**만 적는다. + +```text +src/ 최상위 9개 폴더 ── 역할: docs/architecture/layers.md 표 + │ 규칙: .dependency-cruiser.json (check:architecture, FE-GATE-010) + ├─ adapters/<그룹>/index.ts ── 공개 경계(배럴) + │ └─ platform/** 등 kernel 3곳만 그룹을 넘어 import 가능 + ├─ features// ── 지울 수 있는 기능 하나 (제거 드릴, FE-GATE-020) + └─ contexts/, apps/ ── 기능 묶음과 배포 단위 +``` + +## 1. 정본 + +| 무엇 | 정본 | 검사 | +| --- | --- | --- | +| 최상위 `src/` 폴더 9개와 각 역할 | `docs/architecture/layers.md` 7~21줄 표 | `verify:documentation`이 폴더 목록·설명 일치를 본다(`scripts/verify-documentation-readiness.ts` 101~152줄) | +| import 규칙 31개 | `.dependency-cruiser.json` `forbidden`, 설명은 `docs/architecture/layers.md` 33~75줄 | `check:architecture` | +| adapter kernel | `docs/architecture/layers.md` 77~97줄, `.dependency-cruiser.json` 253~261줄 | `check:architecture` | +| 규칙 예외의 이유·담당·재검토 조건 | 그 규칙의 `comment`(`docs/architecture/layers.md` 104~117줄) | 사람이 본다 | +| adapter 그룹의 공개 경계 | `docs/architecture/layers.md` 119줄부터, 규칙 `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/README.md` | `verify:documentation` | + +## 2. 이 repo의 고정 전제 + +`CLAUDE.md` 「이 repo의 리뷰 전제」(19~22줄)를 구조 기준으로 읽으면 다음과 같다. + +1. **확장 지점은 남긴다.** repo 안에 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이다. 죽은 코드로 + 보고 지우지 않는다. 2026-09-16 사용자 결정 1(08장 표 O-1)이 출처다. +2. **갈라진 중복 복사본은 하나로.** 같은 일을 하는 코드가 두 벌이고 서로 달라지기 시작했으면 결함이다(부록 P-14). + 합칠 곳은 kernel(`src/adapters/platform/`)이나 `src/contracts/`다(`SPEC.md` 34줄). +3. **배럴이 공개 경계다.** 그룹 바깥(`src/bootstrap`, `src/features`, `src/presentation`)은 그룹의 `index.ts`만 import한다. + 배럴 폐지는 2026-09-16에 기각됐다(08장 표 O-2). +4. **kernel 예외는 셋뿐이다.** `src/adapters/platform/` 폴더 전체, `src/adapters/browser-file-storage/result.ts`, + `src/adapters/cross-context-invalidation/index.ts`. 새 파일 단위 예외를 제안하지 않는다(`CLAUDE.md` 21줄). 새 공유 + 프리미티브는 `src/adapters/platform/`에 넣는다. 폴더 전체가 예외라 규칙을 바꿀 필요가 없다. +5. **실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다.** 서버 메모리 상태·다중 인스턴스 경쟁 기준은 적용하지 + 않는다. 탭 사이 경쟁은 적용한다(1105 README 0절). + +## 3. 바꿀 때 같이 고칠 것 + +| 바꾸는 것 | 같은 커밋에서 고칠 것 | +| --- | --- | +| 최상위 `src/` 폴더 추가·삭제 | `docs/architecture/layers.md` 표 한 행. 같은 설명 문장을 루트 `README.md`, `docs/architecture/overview.md`, `docs/architecture/frontend-application-foundation.md`에 그대로 | +| import 규칙 추가·이름 변경 | `.dependency-cruiser.json`, `docs/architecture/layers.md` 규칙 표의 행(규칙 이름이 빠지면 `verify:documentation`이 실패) | +| 규칙 예외 | 그 규칙의 `pathNot`과 `comment`(이유·담당·재검토 조건). 파일 단위 kernel 예외는 만들지 않는다 | +| adapter 파일 추가·이동·삭제 | `docs/reviews/adapters/INVENTORY.md`(`SPEC.md` 33줄) | +| adapter 그룹 공개 표면 | 그 그룹의 `index.ts`. 2단계 `index.ts`는 공개 배럴이 아니다(예외: `storage/indexeddb`, `storage/opfs` 서브배럴) | +| 기능·context 경계 | `src/features//`와 `tests/features//`. 기능끼리, context끼리 import하지 않는다(규칙 `features-do-not-import-other-features`, `contexts-do-not-import-other-contexts`) | +| 지울 수 있는 단위(참조 기능, recipe, 선택 runtime) | 그 단위의 제거 드릴이 함께 지울 목록. 예: `scripts/test-sample-removal.ts`의 머리말 주석과 `SAMPLE_EXTRAS`(루트 `README.md` 「Files you can delete after copying」 아래 문단) | + +## 4. 문서 위치 + +| 문서 | 둘 곳 | +| --- | --- | +| 지금 코드가 지키는 규칙 | `docs/README.md` §1 묶음. 링크하면 `verify:documentation` 범위에 든다 | +| 앞으로의 설계·결정 | §2 묶음. ADR은 `docs/architecture/decisions/` | +| 리뷰·계획·작업 추적 | §3 묶음(`docs/reviews/`, `docs/superpowers/`). 복사한 프로젝트가 지울 수 있다 | +| 새 기능 절차 | `docs/manual/` | +| 개선 작업 기준 | `docs/improvement/`(이 매뉴얼) | +| 여러 repo에 걸친 설계·공통 원칙 | repo 밖 `design-docs`. 템플릿 `docs/`에 두지 않는다(`docs/manual/README.md` 「이 폴더에 두지 않는 것」) | + +- 코드·테스트·스크립트·설정은 지워도 되는 문서(`docs/reviews/`, `docs/superpowers/`, `SPEC.md`, `CLAUDE.md`, `tasks/`)를 + 읽지 않는다. 예외는 `docs/reviews/adapters/INVENTORY.md` 하나다. `tests/unit/deletable-history-documents.test.ts`가 + 검사한다. 테스트가 리뷰 문서를 열어 제거 드릴 셋을 깨뜨린 적이 있다(같은 파일 머리말). +- 현재 계약 문서는 작업 이력 문서에 기대지 않는다(`docs/manual/README.md` 68줄). + +## 5. 리뷰에서 구조 결함으로 보는 것 + +| 결함으로 본다 | 결함으로 보지 않는다 | +| --- | --- | +| 갈라진 중복 복사본(부록 P-14) | 소비자 없는 확장 지점, 빈 레지스트리 | +| 같은 사실을 여러 곳에 손으로 다시 적는다(부록 P-03) | 인터페이스가 많다는 사실만으로(가이드 35.2절) | +| 문서가 없는 폴더·규칙을 말한다 | kernel 폴더가 크다는 사실만으로 | +| 템플릿 파일을 고쳐야 기능을 더하거나 지울 수 있다(1103 README 5절 원인 2) | 다운스트림이 쓰지 않는 선택 runtime | +| 지울 수 있다고 한 단위를 지우면 게이트가 실패한다(1105/14-01) | | + +## 6. 제거 가능성 + +지울 수 있는 단위는 merge 게이트 FE-GATE-020의 드릴이 지켜 준다. 드릴 목록은 `config/ci/gates.json`의 FE-GATE-020 +`commandIds` 다섯 개다(`test:sample-removal`, `test:feature-scaffold`, `test:optional-recipe-removal`, +`test:browser-file-storage-removal`, `test:realtime-removal`). + +- 구조를 바꾸면 드릴을 돌린다. 드릴 fixture가 복사하는 파일 목록이 바뀐 구조를 아는지 본다. fixture 복사 목록에 + `README.md`·`CHANGELOG.md`가 없어 드릴 넷 중 셋이 항상 실패한 적이 있다(1103/02-06). +- 드릴은 오래 걸린다. FE-GATE-020은 1,150초 안팎이다(1105 README 11.1절). desktop에서 잠금 아래 돌린다(07장 7절). + +## 지금 이해하면 되는 것 + +- 폴더 역할은 `layers.md`, import 규칙은 `.dependency-cruiser.json`, adapter 목록은 `INVENTORY.md`가 정본이다. +- 확장 지점은 남기고, 갈라진 복사본은 합친다. 새 공유 코드는 `src/adapters/platform/`이나 `src/contracts/`로. +- 구조를 바꾸면 규칙·문서·INVENTORY를 같은 커밋에서 고치고 제거 드릴을 돌린다. diff --git a/docs/improvement/04-code-structure.md b/docs/improvement/04-code-structure.md new file mode 100644 index 00000000..441701f6 --- /dev/null +++ b/docs/improvement/04-code-structure.md @@ -0,0 +1,127 @@ +# 04. 코드 구조 기준 + +## 핵심 + +결함을 고치거나 리팩터링할 때 지킬 코드 기준이다. 계층·import 규칙은 03장과 게이트가 지킨다. 이 장은 **게이트가 +지키지 못하고 다섯 라운드 동안 반복된 결함**을 막는 기준을 적는다. + +```text +판정 규칙은 한 곳에 → 실패 분류·결과 불명·멱등 키 (2절) +실패는 드러나게 → 원인을 싣고, 멈추지 않고, 사실대로 보고 (3절) +같은 사실은 한 곳에 → repo 안 손 사본, 두 템플릿 사이 손 사본 (4절) +지우거나 바꿀 때 → 그 코드가 지키던 것을 찾는다 (5절) +설정·환경은 한 출처에서 → 빌드 설정, base path, 테스트 env (6절) +고칠 때 → 수정이 새로 가정하는 것을 적는다 (8절) +``` + +각 기준 끝의 `P-NN`은 부록 결함 패턴 카탈로그의 행이다. 그 행에 지난 발견 ID가 있다. + +## 1. 정본 + +| 무엇 | 정본 | +| --- | --- | +| 계층과 import 방향 | `docs/architecture/layers.md`, `.dependency-cruiser.json`(03장) | +| 재시도 의미, 결과 불명, 인증, 업로드의 판단 기준 | `docs/manual/02-decision-tables.md` 3·4·5·7절 | +| 오류 모델, 재시도 모델, 실패 경계, trace | `scale-architecture.md §13`, `§17`, `§29`, `§30` (`docs/architecture/scale-architecture.md`) | +| 짝 백엔드 응답의 판정 표 | `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`, 근거 문서 `docs/architecture/backend-api-and-server-state-contract.md` 6.1절 | +| 위험을 코드에 드러내는 방법 | 가이드 29절 | +| 설계 의도와 단순화의 보존 조건 | 가이드 39절 | + +## 2. 판정 규칙은 한 곳에 + +- **실패 분류는 status 하나로 하지 않는다.** status와 code를 함께 본다. 표 밖의 값은 안전한 쪽(결과 불명)으로 둔다. + 업무 거절이 결과 불명으로, 일시 오류가 무결성 실패로, rate-limit 503이 결과 불명으로 분류되는 결함이 두 라운드 + 다섯 영역에서 났다. P-28 +- **짝 백엔드 쓰기 응답의 판정 표는 `REFUSED_BEFORE_WRITE` 하나다.** 실행 경로가 둘이어도 같은 표를 읽는다. 표를 + 경로마다 따로 두면 두 번째 표가 다시 갈라진다(1101 README 14.6절의 버린 대안). operation 단위 예외는 descriptor의 + `commandEffect.refusedBeforeWrite` code 목록으로만 선언한다(1103 결정 D2). +- **결과 불명 쓰기를 다시 보내는 모든 입구를 함께 본다.** 재전송 버튼, hook 재제출, 실행기 재시도, poll 재시도, 업로드 + 재시도. 하나를 막으면 다른 입구에서 다시 나왔다. 키 없는 쓰기(`NEVER`)는 결과 불명 뒤 재전송하지 않는다. 키 있는 + 쓰기는 같은 키로만 다시 보낸다. P-29 +- **판정 규칙의 경계를 테스트로 고정한다.** 경계 하나를 바꾸는 변이가 게이트에서 실패해야 한다(05장 3.2절). P-13 + +## 3. 실패는 드러나게 + +- **원인과 추적값을 싣는다.** 실패 객체·진단에 effect, reason, `traceId`, 어느 참여자인지를 싣는다. 서로 다른 실패를 + 같은 reason으로 남기지 않는다. 진단 reason은 이 repo가 소유한 닫힌 목록이고 서버 code를 그대로 넣지 않는다. + 서버 code는 실패의 `AppFailure.code`에 남는다(커밋 `93782b0` 결정, 1101 README 14.6절). 한 모듈에서 고친 누락이 새 모듈에서 다시 생겼다. 새 adapter는 같은 + 기준으로 리뷰한다. P-33 +- **오지 않을 신호를 기다리지 않는다.** 모든 대기에는 끝나는 조건(예산 소진, 마감, 취소)이 있다 **[제안]** — 지난 + 완료 기준(0925/04-01 "예산을 실제로 소진했을 때만 terminal")을 일반 규칙으로 올린 것이다. P-30 +- **손상 한 건이 전체를 멈추지 않게 한다.** 손상 행은 건너뛰고 수를 보고한다(1101 README 14.1절 0929/05-01 행). + P-31 +- **결과를 사실대로 보고한다.** 다 하지 못했으면 `COMPLETED`·`verified`·`active`를 보고하지 않는다. 상태를 읽은 + 시점과 보고하는 시점 사이에 다른 작업(다른 탭의 put, release)이 끼어들 수 있으면, 같은 잠금 아래에서 다시 대조하거나 + 끝난 뒤 한 번 더 센다(1105 README 9절 1103/05-01 행). 테스트는 객체 셋 이상으로 한다. P-32 +- **실패·복구 전이 뒤 화면이 다음 행동을 남긴다.** 실패 표시에서 고친 포커스·안내 장치를 복구 성공, 확인, 진행 중 + 전이에도 쓴다. 페이지마다 복사하지 않고 공용 폼 hook 안에서 한다. P-38 +- **확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다.** 코드에 상수 `true` 판정을 두지 않는다(`SPEC.md` D-14). + +## 4. 같은 사실은 한 곳에 + +- **repo 안:** 스키마 메타, 레지스트리 행, 허용 키 목록, 빌드 입력 목록, 저장 키를 원본(zod 스키마, descriptor, + registry)에서 뽑는다. 손으로 다시 적어야 하면 원본과 대조하는 테스트를 같이 둔다. 두 검사기가 같은 산출물을 다른 + 키 목록으로 읽어 merge 게이트가 항상 실패한 적이 있다(1103/12-09). P-03 +- **이미 갈라진 복사본은 하나로 합친다.** 합칠 곳은 `src/adapters/platform/`(adapter 공용 메커니즘)이나 + `src/contracts/`(공유 어휘)다. 갈라진 recipe port는 지우고 `src` port를 다시 내보낸다(1101 README 14.1절 0929/05-03 + 행). P-14 +- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 프론트에 옮길 때는 백엔드 문서만 보지 + 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 적이 + 있다(1103 README 10.5절 03-01 행). 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 + 테스트로 묶는다(1103 결정 D6). pin과 drift 검사는 아직 계약 문서 글자만 비교한다. 답 표 JSON과 생성기 사실은 대조 + 밖이다(1105/07-01, 1105/16-02). P-04 +- 짝 백엔드 repo는 읽기만 한다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다(09장 1절). + +## 5. 지우거나 바꿀 때 + +- **그 코드가 지키던 것을 찾는다.** 실행 동작만 옮기면 지운 행·테스트·분기가 지키던 규칙이 조용히 사라진다. V2 + 삭제 때 실행 동작 셋만 찾고, 지운 검사·테스트가 지키던 것을 놓쳤다(1103/07-01, 1103/10-04). 지우기 전에 그 코드를 + 읽는 테스트와 검사를 `git grep`으로 찾고, 각각이 지키던 규칙이 새 경로에도 있는지 적는다. P-23 +- **이름을 바꿀 때는** 새 이름을 내고 옛 이름은 한 릴리스 동안 `@deprecated` 별칭으로 남긴다(1101 README 14.1절 + 16-03 행). 이름 하나가 여러 뜻을 가지거나 한 뜻이 여러 이름을 가지면 결함이다. P-37 +- **확장 지점은 지우지 않는다.** 소비자 없는 코드와 빈 레지스트리는 다운스트림용이다(03장 2절). +- **공개 포트는 추가만 한다.** 깨야 하면 결정 표에 적고 BREAKING으로 커밋한다(`SPEC.md` 35줄, 08장 6절). + +## 6. 설정·환경은 한 출처에서 + +- **같은 설정을 경로마다 다르게 읽지 않는다.** 번들, 빌드 스크립트, Service Worker 빌드가 같은 출처에서 읽는다. P-35 +- **URL은 router base path를 따른다.** `/`부터 직접 조립하지 않는다. 기본 게이트가 루트 경로만 돌아 드러나지 않는다. + 하위 경로 빌드 테스트로 확인한다. P-34 +- **테스트가 띄우는 빌드·서버의 env는 테스트가 정한다.** workflow가 job 전체에 주는 `CI=true`와 빌드 식별값이 + vitest·dev server·테스트 안 빌드로 새면 실제 CI에서만 실패한다. 테스트용 로컬 빌드 식별값은 + `scripts/lib/build-environment.ts`가 한 곳에서 준다. 테스트마다 env에서 기대값을 읽는 방식은 버렸다(다음 테스트가 + 같은 실수를 한다). P-05 +- **환경 가정은 적고, 확인하고, 없으면 이유를 말하며 실패한다.** 글꼴, user namespace, 옆 checkout(07장 5·6절). P-08 + +## 7. 동시성 + +- 여러 탭이 같은 저장소·구독·잠금을 건드리는 경로는 Web Locks로 직렬화하거나, 잠금 없이도 안전한 이유를 적는다 + (`SPEC.md` D-3·D-4). 잠금을 기다리는 작업에는 abort와 상한이 있다. P-36 +- 실행 형태가 브라우저 SPA라 서버 다중 인스턴스 경쟁은 보지 않는다. 탭 사이 경쟁은 본다(02장 1절). + +## 8. 확장 지점과 경계 + +- **제품마다 다른 것은 제품 소유 파일에 둔다.** 제품이 템플릿 소유 파일을 고쳐야 하면 결함이다. 동기화마다 같은 파일이 + 충돌한다. 제품 소유 자리의 예: `src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`, + `config/ci/product-gates.json`. 효과는 다음 동기화 충돌 수로 잰다(1101 README 5절). P-39 +- **경계 예외는 실제 쓰임만큼만 연다.** 예외의 이유·담당·재검토 조건을 규칙의 `comment`에 적는다. kernel 폴더에는 공유 + 메커니즘만 둔다(03장 2절). P-40 +- **두 모듈이 이어지는 곳을 지나는 테스트를 둔다.** 모듈마다 단위 테스트가 있어도, 한쪽이 보내는 결과를 다른 쪽이 다른 + 뜻으로 받는 결함은 연결 지점에서만 보인다. P-41 + +## 9. 고칠 때 — 수정이 새로 가정하는 것 + +4라운드 새 발견 48건 중 22건의 원인이 지난 수정이었다(1105 README 4절 끝). 수정 커밋마다 다음을 본문 「위험·한계」에 +적는다. + +1. 이 변경이 새로 가정하는 상태(빈 제품 파일, CI env 없음, 객체 하나, 기능 0개 등). +2. 그 가정이 깨지는 지원 구성에서 한 번 돌렸는가(01장 2절 5단계). +3. 이 변경이 다른 검사를 약하게 했는가. 예: 경로를 백틱 밖으로 옮겨 문서 검사를 피한 수정이 그 경로를 검사 밖으로 + 냈다(1105/14-03). 위험을 커밋 본문에 적고도 테스트하지 않아 다운스트림 게이트가 항상 실패한 수정도 있다 + (1105/09-01, 수정 커밋 `235143c`). P-26 + +## 지금 이해하면 되는 것 + +- 판정 규칙은 한 곳, 표 밖은 안전한 쪽. 결과 불명 쓰기의 모든 재전송 입구를 함께 본다. +- 같은 사실은 원본에서 뽑거나 대조 테스트로 묶는다. 짝 백엔드 사실은 코드까지 따라간다. +- 수정은 새로 가정하는 것을 적고, 그 가정이 깨지는 구성에서 돌려 본다.