--- title: "A Refactoring Strategy for Legacy Systems in the AI Era" description: "How to refactor legacy systems strategically in the AI era — from requirement consolidation, separating old and new systems via API Gateway, building AI-readable architecture guides, to fault-tolerance tiers and fast rollback." canonical_url: "https://blog.markkulab.net/en/post/ai-refactoring-strategy" author: "Mark Ku" author_url: "https://blog.markkulab.net/en/author/mark-ku" site: "Mark Ku's Tech Notes" date_published: "2026-01-09 01:01:35 +0800" category: ".NET Core" tags: ["ai", "refactoring", "architecture", "dotnet", "api-gateway", "devops"] language: "en" license: "CC BY 4.0" license_url: "https://creativecommons.org/licenses/by/4.0/" attribution: "when reusing or quoting, credit the author and link back to the original" --- # A Refactoring Strategy for Legacy Systems in the AI Era ## Preface A question I've been getting a lot lately: in the AI era, how should we actually refactor legacy systems? Let me consolidate my recent thinking and approach into one article. ## 1. AI accelerates development — and amplifies risk Vibe Coding / AI Pair Programming really can multiply software productivity. But it can equally multiply bugs, technical debt, and system complexity (extra code, over-engineering). When a major system error happens, engineers still have to step in — and because much of the code wasn't typed line by line, when something breaks, it's not always obvious where. So talking about refactoring in the AI era, what we really need is to **make the system more understandable**, not just chase "produce more code." ## 2. Before you rewrite: make sure you have "headroom" From my past experience rewriting a system, the people before and after were the same team. The old system's core features kept hitting issues while new requirements kept coming in, and dev resources were constantly pulled both ways. The result: nearly a year and a half just stabilizing the old system's requirements, drawing clear boundaries, before the team had real headroom to talk about a rewrite. P.S. The practices below are what I've gathered — adjust based on your actual resources and task priorities. ## 3. Requirement consolidation: clarify before you act Against this backdrop, requirement consolidation itself becomes a critical engineering task — not just "write some specs": 1. **Comprehensive inventory** Includes unused features, known issues and potential leaks, the long-standing wishlist from the business side, the actual usage scenarios, resource quotas, and the responsibilities and role boundaries of each department. 2. **Redesign, don't rubber-stamp** For each item in the inventory, rethink: what's worth keeping, what needs adjusting, what shouldn't have existed in the first place, or what's so big it must be deferred. 3. **Surface uncertainty** Take *known unknowns* and proactively put them on the table — convert them into known, manageable risks and decision criteria. For example: draw flow diagrams. 4. **Redefine processes when needed** Some problems aren't rooted in the system but in the workflow itself. Have the courage to redefine the workflow, not just paper over it with technical brute force. > P.S. Thanks to Big Bro Lei N from 104 for the perspectives and reminders shared here. ## 4. Use API Gateway to separate old and new systems From a technical angle, if the old system already has APIs, you can first **set up a unified entry point (API Gateway)**: All requests no longer hit the old system's IP directly — they go through the API Gateway: ```text /api/v1/orders -> Old System /api/v2/orders -> New Microservice ``` Versioning hides both old and new behind the Gateway, so you can **migrate one API at a time** instead of rewriting everything at once. Old APIs get phased out gradually, and any future old/new version management is much easier. ## 5. Lay out an AI-readable architecture guide The point isn't how thick the docs are — it's the **consistency of logic and structure**: * System architecture * Database schema * Code style and conventions * File naming and folder placement rules * Relationships between modules * Data flow diagrams (Mermaid is great for AI to consume) * How unit tests should be written These aren't only for humans — they help AI build "context." During the build phase, you can pair them with tools that enforce constraints: * Frontend: ESLint to keep code style unified. * .NET: Roslyn Analyzer + `.editorconfig` to enforce conventions in the build pipeline. This way AI doesn't "produce a different style every time," and it can better grasp the architecture you actually want. Also, critical business logic should have tests. The pattern: a human first writes out the scenarios and input/output, then asks AI to help generate or fill in the tests — ensuring "the same input always produces the expected output." That keeps risk relatively lowest. ## 6. Inventory features for refactoring; decide AI's involvement First list out the features that need refactoring, then use **fault tolerance** to decide how far AI can go: * **High tolerance**: AI can generate automatically, with human spot-checks or rough validation. * **Low tolerance**: must have human review, AI is only an assistant. Even after launch, humans should observe for a few days, or set up monitoring alerts. Not every spot is suited for full automation — some places require an engineer to read line by line, or test by hand. ## 7. Use AI as a Code Reviewer You can have AI do code review — let it scan for issues, evaluate risk, and suggest fixes — but the final decisions and trade-offs still belong to humans. For example, GitHub + Copilot can automatically trigger AI Review in your PR flow, scanning for potential risks first. P.S. Cursor has a similar mechanism. ## 8. When things really break, you need to see it fast When most of the code is AI-produced, the team's familiarity with system details is usually low. You'll need **error status codes** and **well-placed logs** as anchors to quickly narrow down the problem. - Active monitoring (periodic requests / website service monitoring): `uptime-kuma` - Passive monitoring (someone using it notices it's broken or slow): `Prometheus + Grafana`, or `Jaeger` for custom-metric monitoring At minimum, you want a few real-time observability signals: * API error rate * Latency * Some custom business-process metrics for critical flows ![Custom tracking metrics via Jaeger](https://blog.markkulab.net/content/markku/posts/ai-refactoring-strategy/images/tracking.png) ## 9. If you can't diagnose quickly, you need a safe rollback You will make mistakes during refactoring, so the escape route must be planned and prepared in advance. The mistakes you'll make, others are likely to make too. When something does break, treat it as an opportunity to improve the existing refactor and deploy flow — let the whole system iterate forward, step by step, and mature over time. Common rollback approaches: * Direct Git revert, rebuild container or app container * Switch back to old system at the API Gateway * k8s rollback ## 10. From WinForm to Web: migrating the UX The biggest challenge in moving from WinForm to Web isn't tech — it's the **users' existing operational habits**. People used to fly through WinForm with combo boxes and hotkeys, fast and intuitive. Going to Web means rethinking interaction design so it feels just as smooth — or even faster. - **Quick selection**: use autocomplete with full keyboard support (hotkeys) and focus management. - **Low-latency feedback**: avoid full-page reloads — modern frontend frameworks make "no reload" UX trivial. - **Batch and shortcuts**: keep common hotkeys and batch-operation capabilities to shorten action paths. - **Consistent semantics**: reuse the old system's terminology and flow mapping to lower the learning curve. ## 11. Responsive design: Mobile-first and Tailwind CSS Most people now browse on phones, so design typically starts mobile-first. I recommend Tailwind — it's mobile-first by design, with mature responsive variants and utility classes for various device sizes, and it's easy to extend. - **Public-facing site**: start from mobile, then enhance for desktop. - **Admin system**: admin features are usually numerous; making everything fully RWD is expensive. Unless a feature is essential, do RWD only on the parts that need it. - **Desktop system**: focus on the efficiency of dense operations, close to users' daily habits. ## Reflections Refactoring at its core is **reducing system uncertainty**. If the structure is complex and lacks consistency, then a system that was already messy will, with AI's amplification, become "many times messier." Don't expect AI to rewrite everything for you — use AI to help with the parts that are clearly defined and logically explicit. When the system becomes "understandable" — for engineers and for AI alike — that's when refactoring and rewriting actually pay off. --- ## About this article and its author Originally published on [Mark Ku's Tech Notes](https://blog.markkulab.net/en/post/ai-refactoring-strategy) License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — when reusing or quoting, credit the author and link back to the original ### About the author **[Mark Ku](https://blog.markkulab.net/en/author/mark-ku)** — Software Solution Provider - 10+ years senior software engineer, now an AI Builder - Focused on large-platform architecture — North-American e-commerce, AI SaaS subscription billing - Combining AI Agents and automation to build evolvable product foundations ### Free tools built by the author All of these are free to use: - [Free PDF Sign Tool](https://blog.markkulab.net/en/tools/pdf-sign): Online PDF sign tool — draw, type, or upload a signature, then drag, resize, and download. Everything runs in your browser; nothing is uploaded. - [VS Code Refactory](https://blog.markkulab.net/en/tools/refactory): Refactory is a VS Code refactoring extension: 34 actions plus a 37-rule code-smell inspection layer with a Code Health dashboard, across 18 languages, backed by 534 tests. It learns your repo's conventions: where interfaces live, where DI is registered, whether 'use client' belongs. It ranks files by git churn × complexity so you know what to fix first, and hands any smell to the Claude Code already on your machine. Free to use, and your source never leaves your computer. - [DB-Kit Database Manager](https://blog.markkulab.net/en/tools/db-kit): DB-Kit is a lightweight, cross-platform database manager built with Tauri + Rust + React. Manage MySQL, MariaDB, PostgreSQL, SQL Server, Oracle, SQLite, MongoDB, Redis, Kafka, Elasticsearch and RabbitMQ from one consistent interface: passwords encrypted in the OS keychain, SSH tunnels, full CRUD, a visual query builder, stacked multi-statement result sets, cross-connection data transfer and compare/sync, Excel / CSV import & export, visualized execution plans, ER diagrams, scheduled backups, SQL stress testing with p50–p99 latency percentiles, a 15-rule SQL review engine, Kafka message browsing with monitoring & alerts, a bilingual UI (Traditional Chinese / English), a built-in AI assistant (natural-language SQL, AI review and tuning advice) and the dbk CLI. Free and open source (MIT), with installers for Windows, macOS and Linux. - [VS Code Super Mermaid](https://blog.markkulab.net/en/tools/super-mermaid): Super Mermaid is a VS Code extension for beautiful Mermaid diagrams out of the box: auto-colored live preview, mouse pan & zoom, high-res PNG / SVG export, 21 templates and multiple themes. Free and open source (MIT). - [React Super Mermaid](https://blog.markkulab.net/en/tools/react-super-mermaid): react-super-mermaid is an open-source React component library: render beautiful Mermaid diagrams with a single , with built-in colorful / sketch themes, pan & zoom, in-diagram search, and high-res SVG / PNG export. Lightweight, SSR-safe, fully typed. Free and open source (MIT). - [Jira / Confluence Super Mermaid](https://blog.markkulab.net/en/tools/jira-super-mermaid): An Atlassian Forge app: write Mermaid syntax directly inside a Jira issue or a Confluence page and get flowcharts, sequence diagrams, state machines and Gantt charts. 11 diagram types, SVG / PNG export, light and dark themes, full CJK support. Runs on Atlassian: your diagrams live in your own site and the app calls no third-party service. Free, coming soon to the Atlassian Marketplace. - [Mermaid Live Preview](https://blog.markkulab.net/en/tools/mermaid-preview): Write Mermaid in your browser, see it render instantly, and share the whole diagram as a single link. No sign-up, nothing uploaded to a server, and mermaid.live share links work as-is. - [React Intl Phone Number](https://blog.markkulab.net/en/tools/react-intl-phone-number): react-intl-phone-number is an open-source React component: framework-agnostic and antd-free, with E.164 in/out, a searchable flag / country-code dropdown, configurable validation levels (strict / mobile-strict / loose), themeable CSS, and i18n — phone logic powered by google-libphonenumber. Lightweight and fully typed. Free and open source (MIT). - [Uptime Kuma Cluster](https://blog.markkulab.net/en/tools/uptime-kuma-cluster): Turn single-node Uptime Kuma into a highly available cluster: OpenResty + Lua smart load balancing, shared MariaDB state, health checks and automatic failover, plus cluster-management REST APIs. One Docker Compose command to start. Free and open source (MIT). - [Special Education](https://blog.markkulab.net/en/education): Learning materials crafted for special education students ### Daily podcasts - [Mark's Tech Insights — Daily AI News](https://blog.markkulab.net/en/category/tech-news): Daily curated AI and tech trends. Catch the latest developments via audio summaries — covering AI applications, software architecture, DevOps, and engineering practice. — RSS: https://blog.markkulab.net/feed.xml - [AI股市蝦聊](https://blog.markkulab.net/en/category/ai-stock-chat): Every trading day, an AI-analyzed take on the Taiwan stock market, delivered as a two-host conversation covering the session and the next-day outlook. — RSS: https://blog.markkulab.net/ai-stock-chat/feed.xml - [開源好物週報](https://blog.markkulab.net/en/category/open-source-weekly): A weekly two-host pick of free open-source tools surfaced from real Hacker News, GitHub, and Reddit buzz — what pain they solve and the fastest way to get started. — RSS: https://blog.markkulab.net/open-source-weekly/feed.xml ### Newsletter [Subscribe to the newsletter](https://blog.markkulab.net/en/subscribe) — Be the first to know about new posts. No spam, unsubscribe anytime.