docs(manual): 기능마다 바뀌는 추적 파일 둘과 충돌 처리 명령을 적는다

문제: 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다.
create:feature가 public/release-manifest.json(dev server manifest)의
setDigest·packages를 다시 쓰고, 참조 기능이 있는 동안은 초기 JS 기록
(config/scale/feature-shape-ceilings.json initialJavascript)을 명령으로 다시
써야 한다. 03 문서 A절은 "생성 명령이 쓰는 폴더 밖 파일은 둘"(context 선언,
a11y 기록)이라고만 적고, 정본 표(starter-experience.md "Adding a feature")에도
두 파일이 없다. 기능 브랜치 둘은 같은 setDigest 줄을 다른 값으로 바꿔
충돌하는데, 어떻게 푸는지는 test:unit 실패 문구에만 있다.

고른 방법(리뷰 대안 (a)): 문서와 생성 출력에 두 파일, 쓰는 주체, 다시 쓰는
명령, 충돌 처리("아무 쪽이나 고르고 명령을 다시 돌린다")를 적는다.
- scripts/create-feature.ts에 FEATURE_TRACKED_FILE_REWRITES(경로·명령)를
  두고 생성 출력이 충돌 처리 줄에 쓴다.
- 03 A절에 표와 충돌 단락, "기능을 지울 때"에 초기 JS 기록 재작성, 정본 표에
  두 행, 01 1단계 흐름에 manifest 재작성 줄을 더했다.
- 새 단위 테스트가 그 상수의 파일·명령이 03 A절과 정본 표에 있는지 본다.
초기 JS 기록과 그 측정 스크립트 경로는 참조 기능과 함께 지워지므로 문서에서
백틱 없이 적었다(performance-evidence.md와 같은 규칙, 제거 드릴의
verify:documentation).
버린 대안(이번에 하지 않음, 결정 대기):
- (b) dev manifest를 생성 파일로 두고(.gitignore) dev·Playwright 시작 전에
  만들기: 커밋 줄이 사라지지만 dev 스크립트와 Playwright webServer 명령을
  바꿔야 한다. Playwright 설정은 다른 작업(12-04)이 고치는 중이다.
- (d) 초기 JS 기록이 템플릿 자신의 값만 담게 측정에서 설치된 제품 기능을
  빼기: 측정 스크립트가 어떤 기능이 템플릿 것인지 알아야 한다.

위험·한계: 충돌 자체는 남는다. 두 기능 브랜치를 합칠 때 사람이 명령을 다시
돌려야 한다. 완료 기준의 둘째 길("03 A절·정본 표가 두 파일과 충돌 처리
명령을 적는다")만 채운다. 실제 두 브랜치 git merge로 재현하지 않았다.
테스트는 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴에서는 돌지
않는다(`scripts/lib/removal-fixture.ts`의 문서 테스트 목록).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-tracked-files.test.ts
corepack pnpm verify:documentation
corepack pnpm test:realtime-removal

Refs: 1105/16-01
This commit is contained in:
DongHyeonka
2026-11-06 02:12:06 +09:00
parent f600e6b132
commit 6d084cf6a2
6 changed files with 103 additions and 2 deletions
+23
View File
@@ -1691,6 +1691,27 @@ async function readInstalledFacts(root: string): Promise<InstalledFacts> {
});
}
/**
* 1105/16-01. Tracked template files that change with every added feature,
* and the command that writes each. A feature branch commits them with the
* feature; two feature branches change the same lines, and the merge takes
* the command again instead of a hand-merged value. docs/manual/03 (A) and
* the "Adding a feature" table in docs/architecture/starter-experience.md
* list them (tests/unit/feature-tracked-files.test.ts).
*/
export const FEATURE_TRACKED_FILE_REWRITES = Object.freeze([
Object.freeze({
path: "public/release-manifest.json",
command: "node scripts/write-dev-release-manifest.ts",
when: "create:feature runs it: the dev server's manifest names the installed contract packages",
}),
Object.freeze({
path: "config/scale/feature-shape-ceilings.json",
command: "node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write",
when: "by hand while the sample is installed (the file goes with it): test:unit compares it with a build",
}),
]);
const USAGE =
"Usage: pnpm create:feature <id> [--context <context id>] [--with-create [--keyed]] " +
"[--package @scope/name@x.y.z --digest sha256:<64 hex> --revision <hex>]";
@@ -1752,6 +1773,8 @@ function report(plan: FeaturePlan): string {
" A failing gate's log is artifacts/quality/gates/FE-GATE-<NNN>.txt. Locally FE-GATE-013 needs VITE_COMMIT_SHA=$(git rev-parse HEAD); to run them as CI does, set CI=true and the CI build identity (README).",
" 3. The initial JavaScript changes. While config/scale/feature-shape-ceilings.json exists (the sample is installed), rewrite it with node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write and commit it with the feature; test:unit compares it with a build. corepack pnpm check:bundle checks the budget.",
" public/release-manifest.json (the dev server's manifest) now names the feature's contract package; commit it with the feature.",
" Two feature branches change the same lines of these files. On a merge conflict, take either side and run the command again:",
...FEATURE_TRACKED_FILE_REWRITES.map((file) => ` ${file.path}: ${file.command}`),
" The registry baseline does not change: new routes, operations, schemas and invalidation topics are additive.",
];
return `${lines.join("\n")}\n`;
+2
View File
@@ -70,6 +70,8 @@ export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = Object.freeze([
export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([
"tests/unit/changelog-review-ids.test.ts",
"tests/unit/documentation-readiness.test.ts",
// 1105/16-01. Reads the 03 manual and docs/architecture/starter-experience.md.
"tests/unit/feature-tracked-files.test.ts",
] as const);
/** The tests a fixture copied from `copyTargets` cannot run. */