[iflov]

ARCHITECTURE.md의 「이 템플릿이 아직 문서를 따라가지 못하는 곳」표 다섯 줄을 전부 닫는다.
문서는 d3aeff6에서 inbound/outbound port로 바뀌었는데 코드가 따라가지 않았다. 이 저장소는
파생 프로젝트가 보고 시작하는 유일한 참조 구현이라, 어긋난 채 두면 다음 프로젝트가 이미
폐기된 형태로 시작한다.

⚠ base가 로컬 main이라 아직 push되지 않았던 d3aeff6(문서 + ESLint 규칙 4번)이 함께 올라간다.

표의 다섯 줄

자리	어떻게 닫았나
src/health/	QueryBus + GetHealthQuery 대신 application/ports/in/health.port.ts로 진입한다
health.controller.ts	execute<A, B>(...) 함정이 버스와 함께 사라졌다
application/ports/	in/out으로 나눴다
src/architecture-rule-fixture/	git이 추적하지 않던 빈 디렉토리 셋. 체크아웃에서 지웠고 새 clone에는 원래 없다 — 이 PR에 파일 변경은 없다
ESLint	규칙 4번은 d3aeff6에 이미 들어와 있었다. 표의 그 줄만 stale이었다

무엇이 사라졌나

GetHealthQuery와 GetHealthQueryHandler는 coordinator.check()를 그대로 전달했고 보내는 곳이
health.controller.ts 하나였다. ARCHITECTURE.md가 정한 버스 사용 조건 — 같은 메시지를 여러
inbound가 보내거나 dispatch 자체가 값을 하는 경우 — 을 만족하지 못한다.

함께 사라지는 것이 함정이다. execute<GetHealthQuery, SystemHealth>(...)처럼 타입 인자를 둘
명시하면 @nestjs/cqrs의 두 번째 오버로드가 잡혀 결과 타입을 거짓말해도 tsc가 통과시켰다
(파생 프로젝트 실측). 메서드 시그니처에는 그 문제가 없다 — 결과 타입이 port에 한 번 적히고
호출부는 추론만 받는다. @nestjs/cqrs 의존성과 CqrsModule.forRoot()도 사용처가 0이 되어 뺐다.

무엇이 생겼나

• application/ports/in/health.port.ts — HealthPort + HEALTH Symbol. check()와
  inspectIndicators() 둘 다 담는다. entry point가 HTTP와 Prometheus scrape 둘이고 둘 다 이
  계약을 지난다.
• application/ports/out/health-indicator.port.ts — 기존 파일을 옮긴 것. 방향이 곧 공개 여부다.
• domain/system-health.ts — HealthStatus·HealthIndicatorSnapshot·SystemHealth. 두 방향의
  port가 모두 쓰는 타입이라 domain에 둔다. 비공개인 ports/out/에 두면 소비자가 결과 타입을
  이름 부르려고 비공개 파일을 열어야 한다.
• health.controller.spec.ts — 소비자 test가 inbound port fake를 주입하는 표본. 대역이 check
  라는 메서드 이름을 갖는 것이 값이다(버스 시절에는 execute() 하나였다).

module은 exports: [HEALTH, HealthMetricsService]로 토큰만 내보낸다. HealthCoordinator는
{ provide: HEALTH, useClass: HealthCoordinator }로만 등록되고 소비자의 런타임 import 그래프에
들어가지 않는다.

ESLint 규칙은 실제로 무는가

위반 파일을 직접 만들어 돌렸다. 네 규칙이 모두 물었고, flat config 교체 함정에도 불구하고
기존 규칙이 살아 있다.

위반	결과
src/lint-probe/probe.ts → ../health/adapters/out/...	no-restricted-imports (규칙 4번)
test/lint-probe.ts → ../src/health/adapters/out/...	no-restricted-imports (규칙 4번)
scripts/lint-probe/probe.ts → ../../src/health/adapters/out/...	no-restricted-imports (규칙 4번)
ports/in/probe.ts의 @nestjs/common	@typescript-eslint/no-restricted-imports (규칙 3번)
ports/in/probe.ts → ../../../adapters/out/...	규칙 2번 + 4번 둘 다
객체 spread { ...base, b: 2 }	no-restricted-syntax (constitution A-5)

no-restricted-syntax 블록에는 A-5 객체 spread 규칙만 있고 execute() 타입 인자 규칙은 없었다.
뺄 것이 없어 블록은 그대로 두었다. probe 파일은 확인 후 전부 지웠다.

문서

README.md·AGENTS.md·CLAUDE.md 세 문서가 여전히 "CQRS-lite — create/update/delete는
CommandHandler, read는 QueryHandler"를 기본 규칙으로 규정하고 있었다. 에이전트와 파생
프로젝트가 읽는 것이 이 셋이라, 코드만 바꾸면 다음 프로젝트가 여전히 폐기된 형태를 지시받는다.
port 경계 서술로 바꿨다. docs/의 과거 조사 기록은 그 시점의 관측이므로 그대로 둔다.

검증

lint · typecheck · test(35 files / 318) · check:scaffold · check:observability ·
build · test:e2e(2 files / 20, Docker postgres) 전부 통과.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BpFLpds7xSWRhwheHcyZYf

[iflov]

Codex 리뷰 반영 (afa7161)

같은 워크트리에 리뷰 레인을 열어 여섯 건을 받았다. 다섯 건을 고치고 한 건은 근거를 적어
ARCHITECTURE.md의 표에 남겼다.

P1 — cross-capability 규칙이 깊은 경로에서 우회됐다 (실제 버그)

../를 1~4번 쓴 여섯 패턴만 열거해서, 여섯 단계 깊이의 위반이 exit 0으로 통과했다.
열거를 늘리면 경계만 옮겨지므로 glob이 실제로 어떻게 동작하는지 재보고 다시 썼다.

측정	결과
**/*/adapters/** (하나로 끝내기)	깊이 1도 통과 — **는 .. segment를 건너지 못한다
../**/*/adapters/**	깊이 1·6 모두 차단 — 리터럴 ../ 뒤의 **는 남은 ..를 건넌다
./**/*/adapters/**	src/app.module.ts의 ./health/adapters/** 차단
자기 capability ./adapters/**·../adapters/**	통과(의도대로)

이 rule의 glob은 import 문자열을 그대로 본다 — 경로를 resolve하지 않으므로 ..가 리터럴
segment이고, 위 두 성질이 거기서 따라온다. 근거를 eslint.config.mjs 주석에 적었다.

오검출 하나는 남긴다: *가 ..에도 매치되므로 ../../adapters/**도 걸린다. 그 자리는
application/·domain/뿐이고 역방향 차단이 이미 막는다.

P2 — Prometheus의 1/0이 public inbound port로 샜다

HealthPort.inspectIndicators(): Promise<Record<string, number>>를 지웠다. 이전 커밋에서 내가
넣은 것이고, gauge encoding을 capability의 공개 계약으로 만들면 metrics backend를 바꿀 때
health의 외부 API가 따라 바뀐다. port는 check(): Promise<SystemHealth> 하나만 주고 up/down →
1/0 변환은 그것을 요구하는 health-metrics.service.ts가 소유한다. 대역이 실제 HealthPort를
구조적으로 만족하게 되면서 spec의 as never도 필요 없어졌다.

P2 — module이 concrete service를 다시 공개했다

exports: [HEALTH, HealthMetricsService] → exports: [HEALTH]. 소비자가 없었고,
HealthMetricsService는 gauge를 등록하는 이 capability의 inbound infrastructure adapter다.
e2e의 app_health_check_status 검증이 그대로 통과한다.

P3 둘

• pnpm-workspace.yaml의 @nestjs/cqrs@12.0.0 minimumReleaseAgeExclude 제거.
• README 다이어그램이 CLI를 Controller에 묶었다 → HTTP / CLI / message → inbound adapter (Controller, CLI command, consumer).

고치지 않은 것 — 표에 한 줄로 남겼다

health-metrics.service.ts가 optional한 MetricsService를 ModuleRef.get(..., { strict: false })
로 찾는다. optional dependency와 실패 모드가 module wiring이 아니라 DI lookup에 숨는 것이 맞다.
고치려면 metrics 유무에 따른 provider 구성을 바꿔야 하고 그것은 health 밖의 결정이라
ARCHITECTURE.md의 「이 템플릿이 아직 문서를 따라가지 못하는 곳」표에 남겼다. 그 절이 비어
있지 않게 된 것이 오히려 정상이다.

검증

lint · typecheck · test(35 files / 318) · check:scaffold · check:observability ·
build · test:e2e(2 files / 20, Docker postgres) 전부 통과. lint 규칙은 위반 파일을 실제로
만들어 확인했고 probe는 전부 지웠다.

🤖 Generated with Claude Code