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,34 @@
+---
+name: refactoring-from-analysis
+description: Use when a completed codebase analysis should be turned into one bounded, evidence-backed refactoring WorkItem and implemented in isolation.
+---
+
+# Refactoring From Analysis
+
+## Goal
+
+Use `docs/<프로젝트>` as high-value context for a bounded refactor while treating the current `<분석 대상 저장소>` as source truth. One execution handles at most one WorkItem.
+
+## Required sequence
+
+1. Read `<분석 대상 저장소>/refactor-queue.yaml` and the selected `docs/<프로젝트>/refactor/<project>/<item>/work-item.json`.
+2. Read the project's completed `document-detail` analysis and source anchors cited by the WorkItem.
+3. Confirm the analysis queue entry is `COMPLETE`, its completed source revision equals current repository HEAD, and the source working tree is clean. Otherwise do not refactor.
+4. Re-check the finding against current code. If it no longer exists, mark the item `REJECTED` with evidence; do not force a change.
+5. Read `references/refactor-queue-contract.md`, `references/work-item-contract.md`, `references/type-strategies.md`, and `references/evidence-contract.md`. For `PERFORMANCE`, also read `references/performance-evidence-contract.md`.
+6. Create/use an isolated Git worktree/branch for the WorkItem. Never implement directly in the analysis source checkout.
+7. Follow the strategy selected by `type` and `scope`.
+8. Preserve raw verification evidence under `docs/<프로젝트>/refactor/<project>/<item>/`.
+9. Run `scripts/verify-refactor-work-item.py <item-dir>` before moving to `WAITING_APPROVAL`.
+
+## Performance ordering rule
+
+For `PERFORMANCE`, the state/operation sequence is mandatory:
+
+`READY → BASELINING → baseline capture at analysisRevision → IN_PROGRESS → source change → VERIFYING → after capture under the same measurement contract → comparison → functional regression checks → WAITING_APPROVAL`.
+
+`IN_PROGRESS` means source-changing work is now allowed, so a performance item may not enter it until baseline raw evidence and baseline metadata exist. No source-changing refactor begins before that baseline exists. If comparable measurement conditions cannot be maintained, mark the item `BLOCKED` or the comparison `INCOMPARABLE`; never claim improvement.
+
+## Bounded change rule
+
+If a WorkItem expands beyond its declared scope or uncovers an independent problem, stop expanding the diff. Create another candidate WorkItem instead. A large project or module is not permission for a large refactor item.