tegwick
2e6f292e48
Some checks failed
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
Test Suite / security-scan (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled
Add Design Pattern Documentation: - Add CopyFirstMigration.md - Documents the copy-first migration principle used in the TestDrive-JSUI capability migration - Add DontRepeatYourself.md - Documents the DRY principle - Add DesignPrincipleSchema.json - JSON schema for design pattern documentation Update Submodule: - Update testdrive-jsui submodule pointer to include Phase 4 documentation (migration completion with legacy file cleanup) Context: These design pattern examples document the principles applied during the successful TestDrive-JSUI migration, which serves as a reference implementation of the copy-first migration pattern. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
159 lines
4.5 KiB
Markdown
159 lines
4.5 KiB
Markdown
# Design Principle: Copy First Migration
|
||
|
||
## Meta
|
||
- **Name:** Copy First Migration
|
||
- **ShortName:** CopyFirst
|
||
- **Version:** 0.1
|
||
- **Status:** Draft
|
||
- **Tags:** refactoring, migration, safety, testing, legacy
|
||
- **RelatedPrinciples:** Don’t Repeat Yourself, Safe Refactoring, Test Pyramid, Capability-Based Testing
|
||
|
||
---
|
||
|
||
## Intent
|
||
Enable safe refactoring and structural migration of codebases by preserving
|
||
existing, working functionality until the new implementation is fully verified.
|
||
|
||
This principle prioritizes **reversibility, confidence, and continuity** over
|
||
speed or elegance.
|
||
|
||
---
|
||
|
||
## CoreStatement
|
||
Never move code directly; always copy first and delete only after verified
|
||
behavioral equivalence is established.
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
### InScope
|
||
- Large-scale refactors or directory restructurings
|
||
- Technology or language migrations (e.g. JS → new JS layout, JS → Python integration)
|
||
- Legacy code stabilization
|
||
- Safety-critical or business-critical systems
|
||
- Situations with incomplete test coverage
|
||
|
||
### OutOfScope
|
||
- Greenfield development
|
||
- Trivial refactors with full and trusted test coverage
|
||
- One-off throwaway scripts
|
||
- Performance-driven rewrites where duplication is unacceptable
|
||
|
||
---
|
||
|
||
## InterpretationGuidelines
|
||
|
||
### What “Copy First” Means
|
||
- The original code remains untouched and functional
|
||
- The new version is treated as **experimental until proven**
|
||
- Deletion is a **final, explicit act**, not an implicit side effect
|
||
|
||
### Common Misinterpretations
|
||
- “This is inefficient because it duplicates code”
|
||
→ Duplication is intentional and temporary
|
||
- “Moving files is faster”
|
||
→ Speed is not the optimization target here
|
||
- “Tests alone are enough”
|
||
→ Tests are necessary but not sufficient without behavioral comparison
|
||
|
||
---
|
||
|
||
## DetectionHeuristics
|
||
|
||
### Structural Signals
|
||
- Files or modules being relocated across directories or packages
|
||
- Parallel implementations during migration
|
||
- Introduction of a new architectural boundary
|
||
|
||
### Semantic Signals
|
||
- Code paths that must remain behaviorally identical
|
||
- Business rules with high regression risk
|
||
- Legacy logic that is poorly documented but relied upon
|
||
|
||
### Change-Cost Signals
|
||
- Rollbacks are expensive or disruptive
|
||
- Failures would impact production or customers
|
||
- Migration spans multiple commits or teams
|
||
|
||
---
|
||
|
||
## DiagnosticQuestions
|
||
1. What breaks if this migration is wrong?
|
||
2. Do we have a known-good reference implementation?
|
||
3. Can both old and new code paths run in parallel?
|
||
4. How quickly can we revert if a defect is found?
|
||
5. What is the minimal proof of behavioral equivalence?
|
||
|
||
---
|
||
|
||
## RecommendedActions
|
||
|
||
### Low-Risk Actions
|
||
- Copy files to the new location instead of moving
|
||
- Preserve original imports and entry points
|
||
- Add logging or tracing for comparison
|
||
|
||
### Medium-Risk Actions
|
||
- Introduce dual-track execution (old + new)
|
||
- Add integration tests targeting both implementations
|
||
- Compare outputs, side effects, and error behavior
|
||
|
||
### High-Risk Actions
|
||
- Switch production usage to the new implementation
|
||
- Remove old code only after full verification
|
||
- Collapse duplicated paths once confidence is established
|
||
|
||
---
|
||
|
||
## AcceptanceCriteria
|
||
- Original code remains functional until final removal
|
||
- New code passes all existing tests
|
||
- New integration tests validate identical behavior
|
||
- Dual-track comparisons show no regressions
|
||
- Deletion of old code is deliberate and reversible up to the final step
|
||
|
||
---
|
||
|
||
## AntiPatterns
|
||
- Moving files directly without a fallback
|
||
- Refactoring and migration in a single irreversible step
|
||
- Deleting “unused” code before equivalence is proven
|
||
- Assuming test parity guarantees behavioral parity
|
||
- Big-bang migrations without rollback paths
|
||
|
||
---
|
||
|
||
## Tradeoffs
|
||
Applying Copy First Migration intentionally:
|
||
- Introduces temporary duplication
|
||
- Increases short-term codebase size
|
||
- Slows perceived progress
|
||
|
||
These costs are justified by dramatically reduced risk and higher confidence
|
||
during complex migrations.
|
||
|
||
---
|
||
|
||
## AgentUsage
|
||
|
||
### When to Apply This Lens
|
||
- During directory, module, or architecture migrations
|
||
- When refactoring legacy or poorly understood code
|
||
- When safety and uptime matter more than speed
|
||
- When rollback must remain possible at all times
|
||
|
||
### When to Suspend This Lens
|
||
- In greenfield projects
|
||
- When full test coverage and confidence already exist
|
||
- For trivial mechanical refactors
|
||
|
||
### Expected Agent Output
|
||
- Identification of migration boundaries
|
||
- Copy-first migration plan with explicit stages
|
||
- Test strategy (unit, integration, dual-track)
|
||
- Rollback points and deletion criteria
|
||
- Clear signal for when old code may be removed
|
||
|
||
xxx
|