refactor: 분리되어 관리하고 있던 문서 시스템을 하나로 통일

2026-09-04 18:56:01 +09:00
parent 4b9e7148b5
commit 43bccd08a8
121 changed files with 2861 additions and 534 deletions
@@ -0,0 +1,37 @@
+# Performance Evidence Contract
+
+A performance refactor is not complete because code looks faster. It needs a comparable before/after experiment.
+
+## Lifecycle
+
+A performance item uses `READY → BASELINING → IN_PROGRESS → VERIFYING → WAITING_APPROVAL`. `BASELINING` is measurement-only. Source changes are forbidden until the baseline at `analysisRevision` has been retained and the item moves to `IN_PROGRESS`.
+
+## Before code changes
+
+Freeze the measurement contract in `work-item.json`:
+
+- exact command or reproducible procedure;
+- cwd;
+- environment record;
+- dataset/fixture/load profile;
+- warmup and iteration policy when relevant;
+- metrics and units;
+- acceptance criteria.
+
+Capture baseline raw output under `evidence/baseline/raw/` and fill `evidence/baseline/metadata.json` with source revision, command, cwd, exit code, dataset, metrics, and raw file references.
+
+## After code changes
+
+Use the same measurement contract. Capture raw output under `evidence/after/raw/` and the matching metadata file.
+
+## Comparison
+
+`evidence/comparison.md` must state whether conditions are materially equivalent and list baseline, after, delta, acceptance result, functional regression checks, conclusion, and limitations.
+
+Allowed conclusions: `IMPROVED`, `NEUTRAL`, `REGRESSED`, `INCOMPARABLE`.
+
+If command/procedure, metric definition, dataset/load profile, or material environment differs enough to invalidate comparison, use `INCOMPARABLE`. Do not convert incomparable measurements into an improvement claim.
+
+## Evidence quality
+
+Retain raw output. A hand-written summary alone is insufficient. Do not fabricate missing runs. Avoid secrets at command construction time rather than relying on later redaction.