문제: 프론트 docs/는 지금 동작을 설명하는 문서와 쓴 때의 기록이 한 폴더에 섞여 있다. docs/architecture/에는 현재 계약 10개와 목표 설계 14개, 결정 기록 VD 23개가 같이 있고, 설계서·계획서는 플러그인 이름 폴더(docs/superpowers/)에 있다. 문서 체계 규칙(design-docs conventions/docs-system.md v1, 2026-11-07 소유자 결정)은 수명으로 나누고 폴더 이름을 백엔드와 같게 하라고 정한다. 고른 방법: 내용 변경 없이 git mv만 담는다. git이 이름 바뀜을 알아보고 리뷰어가 이동과 내용 변경을 따로 볼 수 있게 하려는 것이다. 참조 수정과 머리 블록은 다음 커밋들이 한다. - docs/superpowers/specs → docs/design/, plans → docs/history/plans/ - docs/architecture/ 목표 설계 13개와 styling·testing의 목표 설계 2개 → docs/design/<작성일>-<이름>-design.md (2026-07-30 결정 정본은 이름 그대로) - docs/architecture/decisions/VD-* → docs/adr/ (번호 유지) 위험: 이 커밋만으로는 옮긴 문서를 가리키는 링크와 경로가 깨진다. 다음 커밋이 고친다. 게이트가 읽는 파일(review-ledger.json, review-evidence.md, adapter-remediation-ledger.md, INVENTORY.md)은 옮기지 않았다. docs/history/는 복사한 프로젝트가 지워도 된다는 약속 (tests/unit/deletable-history-documents.test.ts)이 있어서 코드가 읽는 파일을 둘 수 없다. SPEC.md는 공통 완료 기준을 매뉴얼로 옮긴 뒤 따로 옮긴다. 검증: git status가 이름 바뀜(R) 66개만 보인다.
3.6 KiB
VD-01: TypeScript 7과 ESLint 10의 점진적 전환 도구
- 상태: Accepted
- 결정일: 2026-07-26
- 적용 브랜치:
feature-frontend-typescript-tooling-foundation
배경
저장소는 TypeScript 7.0.2와 ESLint 10.8.0을 고정하고 있다. 첫 전환
브랜치는 compiler를 변경하거나 production source를 일괄 변환하지 않고
JS/JSX/TS/TSX가 같은 품질 게이트를 통과하게 해야 한다.
결정 시점의 package peer contract는 다음과 같다.
typescript-eslint@8.65.0과 canary는 TypeScript<6.1.0을 요구한다.eslint-plugin-jsx-a11y@6.10.2는 ESLint<=9를 요구한다.eslint-plugin-react-hooks@7.1.1은 ESLint 10을 지원한다.- Babel 8 ESLint parser는 ESLint 10을 지원하고 Node
>=24.11.0을 요구한다.
호환되지 않는 peer dependency를 강제 설치하면 lockfile 검증은 통과하더라도 지원되지 않는 parser와 rule 조합을 플랫폼 계약으로 만들게 된다.
결정
- TypeScript
7.0.2와 ESLint10.8.0을 유지한다. - TypeScript/TSX의 ESLint syntax parsing에는
@babel/eslint-parser와 TypeScript/JSX syntax plugin을 사용한다. - TypeScript의 이름 해석, unused 진단과 type semantics는
tsc가 소유한다. Babel parser가 TypeScript scope manager를 제공하지 않으므로 TS 파일의 coreno-undef와no-unused-vars는 끄고 분리된 app/node/test TypeScript project를 필수 게이트로 실행한다. - React Hook 규칙은 호환되는
eslint-plugin-react-hooks로 즉시 적용한다. - JSX 접근성은 현재의 semantic component contract, Testing Library,
axe 기반 cross-browser gate와 수동 검토 계약이 계속 담당한다. 호환되지 않는
eslint-plugin-jsx-a11y는 설치하지 않는다. - Babel 8의 지원 범위에 맞춰 Node engine 하한을
24.11.0으로 명시한다. - production source의 대량 rename은 이 결정에 포함하지 않는다.
적용 후 상태 (2026-07-27)
후속 migration에서 production source, 비-fixture tests, Node scripts와 지원되는
tool config를 모두 TS/TSX로 전환했다. allowJs는 껐고 runtime/source 영역의
JavaScript 재유입은 architecture gate가 거절한다. Node scripts는 pinned Node
24에서 .ts로 직접 실행되며 NodeNext, verbatimModuleSyntax와
erasableSyntaxOnly로 별도 typecheck한다. tests/fixtures/**도 TS/TSX
architecture/security/type negative input으로 전환했다. 이는 7번 결정의 범위를
변경한 것이 아니라 그 기반 위에서 완료한 별도 후속 작업이다.
검증
check:types는 app, Node scripts/config, tests project를 모두 검사한다.- TS invalid-call, invalid port, discriminated-union fixture는 실패해야 한다.
- ESLint와
check:architecture의 import 그래프(scripts/check-architecture.ts)가 TS/TSX architecture fixture를 검사한다. dependency-cruiser 18은 TypeScript 7을 해석하지 못해 0개 모듈을 검사하고 통과했으므로 실행하지 않는다(리뷰 12-05)..dependency-cruiser.json은 이름만 남은 규칙 파일이고 그래프가 읽는다. - registry scanner는 TS registry의 required field, uniqueness와 reference를 검증한다.
- browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.
후속 검토와 제거
typescript-eslint가 TypeScript 7을, JSX 접근성 plugin이 ESLint 10을 공식
지원하면 별도 dependency 브랜치에서 peer metadata와 전체 negative fixture를
재검증한다. 교체할 때는 Babel parser package와 TS 전용 ESLint override를
함께 제거한다. compiler downgrade나 --force 설치는 이 ADR의 rollback
방법이 아니다.