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,20 @@
+# Refactoring Evidence Contract
+
+Every WorkItem retains enough evidence for another reviewer or later Tech Log reanalysis to answer:
+
+1. What source revision was analyzed?
+2. What exact problem was confirmed in current code?
+3. What changed?
+4. What commands/tests/measurements were run?
+5. What raw outputs support the result?
+6. What conditions or limitations apply?
+
+Store:
+
+- execution/measurement environment;
+- raw baseline and after output when the type requires comparison;
+- functional/architecture/integration verification output;
+- changed-file/diff summary;
+- explicit acceptance result and limitations.
+
+Evidence is append-only for a completed cycle where practical. Do not replace a failed raw run with only the successful run; retain material failed attempts when they explain the final result. Never store secrets.
@@ -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.
@@ -0,0 +1,28 @@
+# Refactor Queue Contract
+
+`<분석 대상 저장소>/refactor-queue.yaml` is the ordering SSOT for bounded refactoring work.
+
+## Responsibility split
+
+- Queue: order, active item, summary state.
+- `docs/<프로젝트>/refactor/<project>/<item>/work-item.json`: detailed problem, goal, type, scope, acceptance criteria, evidence references.
+
+## Selection
+
+1. Ignore items whose analysis snapshot is no longer `COMPLETE`, revision-current, and clean.
+2. Among actionable `READY` items, lower priority number wins: `P0` → `P1` → `P2` → `P3`.
+3. For equal priority, file order wins.
+4. At most one WorkItem is active. Do not start another while the active item is baselining, changing source, verifying, or waiting for approval.
+5. One scheduled execution works on at most one bounded item.
+
+## Summary entry shape
+
+```yaml
+- project: backend-clean-architecture
+  id: RF-001
+  priority: P1
+  status: READY
+  detail: docs/<프로젝트>/refactor/backend-clean-architecture/RF-001/work-item.json
+```
+
+The queue does not duplicate detailed analysis or evidence. If queue summary and `work-item.json` disagree, stop and reconcile instead of guessing.
@@ -0,0 +1,28 @@
+# Refactoring Type Strategies
+
+Type selects mandatory work and verification. Scope controls how broadly dependencies and regressions must be checked.
+
+| Type | Mandatory strategy / evidence |
+|---|---|
+| PERFORMANCE | Baseline first, same-contract after measurement, before/after comparison, functional regression checks |
+| BUILD | Baseline/after build measurement when speed/size improvement is claimed; build correctness and task/configuration evidence |
+| ARCHITECTURE | Boundary/dependency evidence, architecture rules, build and affected integration paths |
+| MODULE_STRUCTURE | Module/package dependency graph or rule evidence plus affected build/integration tests |
+| DEPENDENCY | Before/after dependency graph, conflict/API impact, build/test evidence |
+| DATA_ACCESS | Query/SQL/row/query-count/plan evidence as relevant plus real DB integration when vendor behavior matters |
+| TRANSACTION | Transaction boundary, commit/rollback/failure contract tests; real provider/DB where semantics depend on it |
+| CONCURRENCY | Deterministic concurrency/contention tests and failure evidence; do not infer safety from sequential tests |
+| RELIABILITY | Failure-path/recovery/retry/timeout evidence and regression tests |
+| SECURITY | Positive and negative-path security tests/config evidence; never retain credentials in evidence |
+| CODE_STRUCTURE | Behavior-preserving tests, reference scan, build; public contract impact explicitly checked |
+| CLEANUP | Reference/usage scan proving removal is safe plus build/tests |
+| TESTABILITY | Demonstrate the targeted behavior is now directly verifiable; preserve production behavior |
+| CONFIGURATION | Binding/default/conditional-loading tests and affected runtime startup/config evidence |
+| OPERABILITY | Logs/metrics/health/runtime behavior evidence appropriate to the operational claim |
+
+## Scope expansion
+
+- `LOCAL`: verify immediate callers/contract plus relevant tests.
+- `MODULE`: verify module API, internal dependency edges, module tests/build.
+- `CROSS_MODULE`: verify all touched module contracts/dependency direction and integration paths.
+- `PROJECT`: exceptional; requires project-wide impact inventory and broad verification. Prefer decomposition when possible.
@@ -0,0 +1,35 @@
+# Refactoring WorkItem Contract
+
+`<분석 대상 저장소>/refactor-queue.yaml` determines execution order. `docs/<프로젝트>/refactor/<project>/<item>/work-item.json` owns detail.
+
+## Required fields
+
+- `id`, `project`, `analysisRevision`
+- `priority`: P0, P1, P2, P3
+- `type`: one supported strategy type
+- `scope`: LOCAL, MODULE, CROSS_MODULE, PROJECT
+- `target`, `problem`, `goal`
+- `acceptanceCriteria`
+- `status`
+- evidence references
+
+Priority decides order. Type and scope decide how work is executed and verified.
+
+## Statuses
+
+Allowed statuses are `CANDIDATE`, `READY`, `BASELINING`, `IN_PROGRESS`, `VERIFYING`, `WAITING_APPROVAL`, `APPROVED`, `MERGED`, `REJECTED`, `BLOCKED`, and `COMPLETE`.
+
+`BASELINING` is used by performance work before source modification. Other types normally move from `READY` directly to `IN_PROGRESS`.
+
+## Eligibility
+
+Before changing code:
+
+- analysis queue status is `COMPLETE`;
+- `analysisRevision` equals the completed analysis source revision;
+- current repository HEAD equals that revision;
+- source checkout is clean;
+- the finding still exists in current code;
+- item is bounded enough to review independently.
+
+If any source revision differs, the refactor is not eligible; reanalysis is required first.