문제: 구조를 바꿀 때 같이 고칠 정본(layers.md, .dependency-cruiser.json, INVENTORY)과, 게이트가 막지 못해 다섯 라운드 반복된 코드 결함(실패 분류, 결과 불명 재전송, 손 사본, 지운 코드가 지키던 검사)을 막는 기준이 문서로 묶여 있지 않다. 고른 방법: 03장에 정본 표, 이 repo의 고정 전제(확장 지점 유지, 갈라진 복사본 합치기, 배럴 경계, kernel 예외 셋), 바꿀 때 같이 고칠 것, 문서 위치, 제거 가능성을 적는다. 04장에 판정 규칙 한 곳, 실패 드러내기, 같은 사실 한 곳, 지우거나 바꿀 때, 설정·환경, 동시성, 확장 지점, 수정이 새로 가정하는 것을 적고 부록 패턴을 가리킨다. 새 파일 단위 kernel 예외는 제안하지 않는다. 위험·한계: "모든 대기에는 끝나는 조건이 있다"는 지난 완료 기준을 일반화한 [제안]이다. 검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
100 lines
7.9 KiB
Markdown
100 lines
7.9 KiB
Markdown
# 03. 폴더·모듈 구조 기준
|
|
|
|
## 핵심
|
|
|
|
폴더 구조의 규칙은 이미 코드와 게이트에 있다. 이 장은 **구조를 바꿀 때 어느 정본을 같이 고쳐야 하는지**와
|
|
**리뷰에서 구조 결함으로 볼 것과 보지 않을 것**만 적는다.
|
|
|
|
```text
|
|
src/ 최상위 9개 폴더 ── 역할: 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/` 폴더 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/<id>/`와 `tests/features/<id>/`. 기능끼리, 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를 같은 커밋에서 고치고 제거 드릴을 돌린다.
|