refactor: 분리되어 관리하고 있던 문서 시스템을 하나로 통일
This commit is contained in:
DongHyeonka
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user