Files
clean-architecture-frontend…/docs/improvement/04-code-structure.md
T
DongHyeonka 05f0083538 docs(improvement): 폴더·모듈 구조와 코드 구조의 개선 기준을 적는다
문제: 구조를 바꿀 때 같이 고칠 정본(layers.md, .dependency-cruiser.json,
INVENTORY)과, 게이트가 막지 못해 다섯 라운드 반복된 코드 결함(실패
분류, 결과 불명 재전송, 손 사본, 지운 코드가 지키던 검사)을 막는
기준이 문서로 묶여 있지 않다.

고른 방법: 03장에 정본 표, 이 repo의 고정 전제(확장 지점 유지,
갈라진 복사본 합치기, 배럴 경계, kernel 예외 셋), 바꿀 때 같이
고칠 것, 문서 위치, 제거 가능성을 적는다. 04장에 판정 규칙 한 곳,
실패 드러내기, 같은 사실 한 곳, 지우거나 바꿀 때, 설정·환경,
동시성, 확장 지점, 수정이 새로 가정하는 것을 적고 부록 패턴을
가리킨다. 새 파일 단위 kernel 예외는 제안하지 않는다.

위험·한계: "모든 대기에는 끝나는 조건이 있다"는 지난 완료 기준을
일반화한 [제안]이다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
2026-11-05 22:15:22 +09:00

10 KiB

04. 코드 구조 기준

핵심

결함을 고치거나 리팩터링할 때 지킬 코드 기준이다. 계층·import 규칙은 03장과 게이트가 지킨다. 이 장은 게이트가 지키지 못하고 다섯 라운드 동안 반복된 결함을 막는 기준을 적는다.

판정 규칙은 한 곳에           → 실패 분류·결과 불명·멱등 키 (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

지금 이해하면 되는 것

  • 판정 규칙은 한 곳, 표 밖은 안전한 쪽. 결과 불명 쓰기의 모든 재전송 입구를 함께 본다.
  • 같은 사실은 원본에서 뽑거나 대조 테스트로 묶는다. 짝 백엔드 사실은 코드까지 따라간다.
  • 수정은 새로 가정하는 것을 적고, 그 가정이 깨지는 구성에서 돌려 본다.