Skip to main content
refactoring-assistant Guide refactoring decisions and large-scale code improvements.
Use when: refactoring code, legacy modernization, technical debt, rewrite decisions.
Keywords: refactor, rewrite, legacy, strangler, technical debt, 重構, 重寫, 技術債.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/ValorVie/custom-skills --skill refactoring-assistantThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... Related occupations SOC
Based on SOC occupation classification
More from this repository 為目標、範圍與授權已明確的非簡單 Agent 工作選擇互動模式、能力層級、風險、派工形狀、審查與有限備援。適用於需要在主 Agent 直接處理、單一工作代理與有限平行之間選擇，或需要依複雜度與風險決定能力層級及審查強度的工作；Codex 專案缺少已驗證的 Agent 設定時，也用本 Skill 引導使用者選擇建立、預覽或略過。簡單問答、唯讀確認與可直接驗證的小修改不要使用。
以統一格式撰寫計畫、報告、指南、教學、紀錄、規範等文件，並依專案慣例決定知識庫放置路徑、主題分類與索引更新。
Use when: 使用者要求撰寫或起草文件，或需要整理 docs 目錄、文件分類、主題索引與知識庫結構。包含但不限於：計畫書（新功能/重構/遷移）、報告（調查/階段/分析）、指南、教學、會議紀錄、事件紀錄、決策紀錄、規範文件。
觸發方式: /custom-skills-doc-writer [type] [variant]
Keywords: 撰寫文件, 文件模板, 文件分類, 文件目錄, 知識庫, 主題索引, 計畫書, 報告, 指南, 教學, 紀錄, 規範, document writer, plan, report, guide, tutorial, record, standard, 寫文件, 起草, draft
CRITICAL PROTOCOL: 本技能是所有任務或其他技能的底層依賴。嚴禁在未讀取auto-skill/skill.md的情況下啟動任何開發任務。這不是建議，而是必須執行的初始化程序。任何跳過此步驟的行為都將被視為任務失敗。任何任務都必須同時啟用 auto-skill（即使其他技能已觸發）。每次對話自動檢查知識庫並調用最佳實踐；同時建立跨技能經驗記憶層，讓下次使用同技能時能主動提醒。當用戶表達滿意時，必須詢問是否記錄經驗。適用於所有任務型對話。
name refactoring-assistant scope universal description Guide refactoring decisions and large-scale code improvements.
Use when: refactoring code, legacy modernization, technical debt, rewrite decisions.
Keywords: refactor, rewrite, legacy, strangler, technical debt, 重構, 重寫, 技術債.
Refactoring Assistant
Language : English | 繁體中文
Version : 2.0.0
Last Updated : 2026-01-21
Applicability : Claude Code Skills
Purpose
This skill provides decision frameworks for refactoring vs rewriting, large-scale refactoring patterns, and technical debt management. Strategies are organized into three tiers: Tactical (daily), Strategic (architectural), and Safety (legacy code).
Quick Reference (YAML Compressed)
decision_tree:
- q: "Code in production?"
n: "→ Consider rewrite (lower risk)"
y: next
- q: "Understand what code does?"
n: "→ Characterization tests first"
y: next
-
q:
"Test coverage >60%?"
n:
"→ Add tests first"
y:
next
-
q:
"Core architecture salvageable?"
n:
"→ Strangler Fig pattern"
y:
"→ Incremental Refactoring ✓"
comparison_matrix:
favor_refactor:
large_codebase
good_tests
business_critical
team_knows_code
sound_arch
tight_deadline
low_risk
favor_rewrite:
small_isolated
no_tests
can_tolerate_downtime
no_knowledge
flawed_arch
flexible_time
higher_risk
rewrite_antipatterns:
-
"Adding features not in original"
-
"Over-abstracting for future flexibility"
-
"Ignoring lessons from existing system"
quote:
"The second system is the most dangerous system a person ever designs. — Fred Brooks"
tactical:
preparatory_refactoring:
definition:
"Restructure code to make upcoming change easier"
quote:
"First make the change easy (this might be hard), then make the easy change. — Kent Beck"
when:
feature_blocked
reduce_friction
upcoming_changes
workflow:
1:
"Identify the change you want to make"
2:
"Identify what makes this change difficult"
3:
"Refactor to make the change easy"
4:
"Make the (now easy) change"
principles:
-
"Preparatory refactoring is separate commit from feature"
-
"Each step maintains passing tests"
-
"Don't combine refactoring with feature work"
boy_scout_rule:
definition:
"Leave code cleaner than you found it (opportunistic refactoring)"
quote:
"Leave the campground cleaner than you found it. — Robert C. Martin"
when:
any_maintenance
bug_fixes
feature_additions
fighting_entropy
guidelines:
-
"Only small improvements (minutes, not hours)"
-
"Don't change behavior"
-
"Don't break existing tests"
-
"Keep scope within current task"
examples:
-
"Rename confusingly-named variable"
-
"Extract lines into well-named method"
-
"Remove dead code"
-
"Add clarifying comment"
antipatterns:
-
"Turning bug fix into major refactoring"
-
"Refactoring unrelated code"
-
"Changes without test coverage"
-
"Scope creep beyond original task"
red_green_refactor:
definition:
"TDD refactoring phase"
duration:
"5-15 min per cycle"
scope:
"single method/class"
techniques:
extract_method
rename
inline_var
replace_magic_number
reference:
"→ See TDD Standards"
strategic:
strangler_fig:
definition:
"Gradually replace legacy by routing to new system"
origin:
"Named after strangler fig trees"
phases:
1_intercept:
"Request → Facade → Legacy(100%)"
2_migrate:
"Request → Facade → [New(Feature), Legacy(Rest)]"
3_complete:
"Request → New(100%) [Legacy decommissioned]"
checklist:
-
"Identify interception point"
-
"Create event capture layer"
-
"Implement first feature in new"
-
"Route traffic incrementally"
-
"Monitor and compare"
-
"Decommission legacy"
anti_corruption_layer:
definition:
"Translation layer preventing legacy model from polluting new system"
origin:
"Eric Evans, Domain-Driven Design (2003)"
when:
-
"New and legacy must coexist and interact"
-
"Legacy has chaotic domain model"
-
"Protecting new system's Bounded Context"
components:
facade:
"Simplifies complex legacy interfaces"
adapter:
"Converts legacy data to new domain model"
translator:
"Maps legacy terminology to ubiquitous language"
checklist:
-
"Define clear ACL interface"
-
"Map legacy entities to new model"
-
"Handle data format conversions"
-
"Implement error translation"
-
"Add logging for debugging"
-
"Test ACL isolation thoroughly"
vs_strangler:
strangler:
"Goal is to replace legacy"
acl:
"Goal is to coexist with legacy"
branch_by_abstraction:
steps:
1:
"Client → Abstraction(interface) → OldImpl"
2:
"Client → Abstraction → [OldImpl, NewImpl(toggled)]"
3:
"Client → NewImpl [OldImpl removed]"
principles:
all_changes_on_trunk
feature_toggles
coexist_during_transition
parallel_change:
aka:
"Expand-Migrate-Contract"
phases:
expand:
"Add new alongside old, new code uses new, old still works"
migrate:
"Update all clients to new, verify, data migration"
contract:
"Remove old, clean up, update docs"
safety:
legacy:
definition:
"Code without tests (regardless of age)"
dilemma:
"Need tests to change safely → Need to change to add tests"
solution:
"Safe techniques to add tests first"
characterization_tests:
purpose:
"Capture existing behavior (not verify correctness)"
process:
1:
"Call code to understand"
2:
"Write assertion expected to FAIL"
3:
"Run, see actual result"
4:
"Update assertion to match actual"
5:
"Repeat until behavior covered"
principle:
"Document what code DOES, not what it SHOULD do"
scratch_refactoring:
definition:
"Refactor to understand, discard all changes"
workflow:
1:
"Create scratch branch (or git stash)"
2:
"Aggressively refactor to understand"
3:
"Take notes on learnings"
4:
"Discard changes (git reset --hard)"
5:
"Apply learnings to write characterization tests"
when:
code_too_complex
no_docs
need_mental_model_fast
principle:
"Goal is understanding, not clean code"
seams:
definition:
"Place to alter behavior without editing code"
object:
"Override via polymorphism (inject test double)"
preprocessing:
"Compile-time substitution (macros)"
link:
"Replace at link time (DI, module replacement)"
sprout_wrap:
sprout_method:
"New logic → create new method, call from old"
sprout_class:
"New logic evolves independently → new class"
wrap_method:
"Add before/after → rename original, create wrapper"
wrap_class:
"Decorate existing → decorator pattern"
principle:
"New code uses TDD; legacy untouched until tested"
db_expand_contract:
expand:
"Add new column/table, app writes BOTH, safe to rollback"
migrate:
"Copy data, verify consistency, app reads from new"
contract:
"Confirm old unused, remove old, cleanup dual-write"
db_scenarios:
rename_column:
strategy:
"add→migrate→drop"
risk:
medium
split_table:
strategy:
"new+FK→migrate→adjust"
risk:
high
merge_tables:
strategy:
"new→merge→switch"
risk:
high
change_datatype:
strategy:
"new_col→convert→switch"
risk:
medium
add_not_null:
strategy:
"fill_defaults→add_constraint"
risk:
low
before:
define_success_criteria
"coverage>80%"
clean_working_dir
create_branch
communicate
during:
one_small_change
test_after_every_change
revert_if_fail
commit_frequently
no_new_functionality
after:
all_tests_pass
measurably_better
docs_updated
team_reviewed
no_new_functionality
code_quality:
cyclomatic_complexity:
"<10/function"
cognitive_complexity:
"lower=better"
coupling:
"reduce"
cohesion:
"increase"
duplication:
"<3%"
test_quality:
coverage:
"≥80%, don't decrease"
speed:
"faster after refactoring"
flaky_count:
"decrease"
quadrant:
prudent_deliberate:
"We know this is debt"
reckless_deliberate:
"No time for design"
prudent_inadvertent:
"Now we know how we should have done it"
reckless_inadvertent:
"What's layering?"
priority:
high:
criteria:
"blocks dev, frequent bugs"
action:
"address immediately"
medium:
criteria:
"slows dev, increases complexity"
action:
"plan next sprint"
low:
criteria:
"minor annoyance, isolated"
action:
"address opportunistically"
tracking:
fields:
description
impact
estimated_effort
risk_if_ignored
related_code
decision_matrix:
-
strategy:
"Preparatory Refactoring"
scale:
"Small"
risk:
"Low"
use:
"Reduce friction before feature work"
-
strategy:
"Boy Scout Rule"
scale:
"Very Small"
risk:
"Low"
use:
"Continuous debt repayment"
-
strategy:
"Red-Green-Refactor"
scale:
"Small"
risk:
"Low"
use:
"TDD development cycle"
-
strategy:
"Strangler Fig"
scale:
"Large"
risk:
"Medium"
use:
"System replacement"
-
strategy:
"Anti-Corruption Layer"
scale:
"Medium"
risk:
"Low"
use:
"New-legacy coexistence"
-
strategy:
"Branch by Abstraction"
scale:
"Large"
risk:
"Medium"
use:
"Trunk refactoring"
-
strategy:
"Parallel Change"
scale:
"Medium"
risk:
"Low"
use:
"Interface/schema migration"
-
strategy:
"Characterization Tests"
scale:
"—"
risk:
"—"
use:
"Prerequisite for legacy refactoring"
-
strategy:
"Scratch Refactoring"
scale:
"Small"
risk:
"Low"
use:
"Understanding black-box code"
selection_guide:
feature_blocked_by_messy_code:
"Preparatory Refactoring"
touching_code_during_bug_fix:
"Boy Scout Rule"
writing_new_code_with_tdd:
"Red-Green-Refactor"
replacing_entire_legacy_system:
"Strangler Fig"
integrating_without_pollution:
"Anti-Corruption Layer"
refactoring_shared_code_on_trunk:
"Branch by Abstraction"
changing_widely_used_interface:
"Parallel Change"
working_with_untested_legacy:
"Characterization Tests + Scratch Refactoring FIRST"
Configuration Detection
Detection Order
Check CONTRIBUTING.md for "Disabled Skills" section
Check CONTRIBUTING.md for "Refactoring Standards" section
If not found, default to standard refactoring practices
Detailed Guidelines For complete standards, see:
Related Standards
Version History Version Date Changes 2.0.0 2026-01-21 Added tactical strategies (Preparatory Refactoring, Boy Scout Rule), Anti-Corruption Layer, Decision Matrix Summary. Reorganized into Tactical/Strategic/Safety tiers. 1.0.0 2026-01-12 Initial release
License 