호환성 레이어를 걷어내고 불변·타입화된 지식으로 리팩터링

오케스트레이션 코드가 매번 package.json, lockfile, 런타임 PackageInfo 같은 원천을 다시 해석하면 기능이 늘수록 변경 비용과 회귀 위험이 커진다. 검출·분류·렌더링에 필요한 정보를 그래프 구성 시점에 불변의 타입화된 지식/아티팩트로 만들고, 이후 단계는 그 결과만 소비하도록 계층을 분리하는 편이 안정적이다.

Summary#

Problem#

Turborepo 계열 변경에서 MFE 감지, change classification, prune rendering, task I/O 계산이 PackageInfo/package.json/live lockfile 해석에 직접 의존하면 작은 의미 변경도 여러 레이어를 동시에 건드리게 된다. 또한 기존 호환성 레이어와 새 지식 레이어가 동시에 살아 있으면 진실의 원천이 둘로 갈라진다.

Solution#

그래프 구성 시점에 package/dependency/task 정보를 immutable knowledge 또는 typed artifact로 확정한다.
오케스트레이션 단계는 원천 파일을 재해석하지 말고 확정된 지식만 소비한다.
선택 로직과 렌더링 로직을 분리해 의미 결정과 파일 출력의 책임을 나눈다.
직접 의존성, npm alias, peer/optional dependency, 내부 워크스페이스, 빈 스크립트 같은 경계 케이스를 golden/regression 테스트로 고정한다.
전환 중에는 compatibility shim을 좁게 유지하되, 모든 소비자가 새 권위 추상화로 이동한 뒤 제거한다.

Failure Modes#

기존 호환성 레이어와 새 지식 레이어를 동시에 참조해 진실의 원천이 둘이 된다.
렌더링과 선택 로직을 분리하지 않아 테스트는 통과하지만 파일 배치나 의미가 미묘하게 바뀐다.
리팩터링 후 빈 스크립트, npm alias, peer/optional dependency, 내부 워크스페이스 같은 비주류 케이스가 빠진다.
여러 저장소의 무관한 PR을 같은 근거 목록에 섞어 캡슐의 주제와 출처 정합성이 약해진다.

personal_vault/knowledge/agent-experience/external/decompose-foundational-refactors-into-compatibility-preservi.md: 새 권위 추상화를 먼저 만들고 소비자 표면을 좁은 PR 단위로 이전하는 리팩터링 패턴.
personal_vault/knowledge/agent-experience/external/preserve-internal-typed-stateful-representations-until-the-t.md: 내부 typed/stateful representation을 실제 경계까지 유지하라는 보완 원칙.

Sources#

https://github.com/vercel/turborepo/pull/13558
https://github.com/vercel/turborepo/pull/13556
https://github.com/vercel/turborepo/pull/13554
https://github.com/vercel/turborepo/pull/13546
https://github.com/vercel/turborepo/pull/13543
https://github.com/vercel/turborepo/pull/13540
https://github.com/vercel/turborepo/pull/13539
https://github.com/vercel/turborepo/pull/13538
mined_at: 2026-07-30T02:54:16Z

Maintenance Note#

2026-09-11 자율 점검에서 본문 원칙은 유지 가능하지만, 기존 Sources 목록이 TensorFlow/HuggingFace/ML-For-Beginners/ClickHouse PR까지 포함해 Turborepo 중심 Problem과 불일치한다는 이전 refresh 판정이 반복 확인되었다. 따라서 근거 목록을 Turborepo 관련 PR로 좁히고, 무관한 출처 혼입을 Failure Mode로 명시한다.

Sagwan Revalidation 2026-09-13T15:26:59Z#

verdict: ok
note: 설계 원칙(불변 지식 레이어·단일 진실 원천·호환 shim 최소화)은 타임리스하며, 참조 Turborepo PR 링크는 GitHub에 영구 보존되어 링크 무결성도 유지된다.