Framework Changes Break Rules
A framework migration (Next.js Pages Router → App Router, Express → Fastify, Vue 2 → Vue 3) changes: file structure, component patterns, data fetching approaches, routing conventions, and API surface. Rules written for the old framework: generate incorrect code for the new framework. If the rules are not updated: the AI generates Pages Router code in an App Router project, Express middleware in a Fastify project, or Options API code in a Composition API project. The migration: must include the rules, not just the code.
The migration timeline: rules change at three points. Before migration: rules describe the current (old) framework. During migration: rules describe both frameworks (old patterns for existing code, new patterns for new code). After migration: rules describe only the new framework (old patterns removed or deprecated). This three-phase approach: ensures the AI generates correct code at every point in the migration.
The rule migration: happens BEFORE the code migration. If rules are updated after the code migration starts: the AI generates old-framework code during the migration, requiring manual correction. If rules are updated before: the AI generates new-framework code for all new work, and old-framework code is refactored by the AI using the correct new patterns. AI rule: 'Update rules before starting the framework migration. The rules guide the AI to generate new-framework code from the first day of migration.'
Step 1: Dual-Pattern Rules During Migration
During the migration: the codebase has both old and new framework code. The rules: must guide the AI for both. Format: '## Data Fetching\nNew code (App Router): fetch data in Server Components using async functions. No useEffect for data fetching.\nExisting code (Pages Router): maintain existing getServerSideProps and getStaticProps patterns. Refactor to Server Components when modifying these files.\nMigration: when touching a Pages Router page, convert to App Router pattern.' The dual-pattern: tells the AI which pattern to use based on the file's current state.
Scope-based dual patterns: 'Files in app/ directory: use App Router conventions (Server Components, Server Actions, route.ts for API routes). Files in pages/ directory: use Pages Router conventions (getServerSideProps, _app.tsx, api/ routes). New files: always create in app/ directory using App Router conventions.' The directory: determines which pattern the AI follows. New files: always use the new framework. Existing files: maintain the current pattern unless being migrated.
The boy scout rule in rules: 'When modifying a Pages Router file: migrate it to App Router. Do not leave it as Pages Router after modification.' This rule: makes migration incremental. Every PR that touches old-framework code: migrates that code to the new framework. Over months: the codebase migrates organically. No big-bang migration. No dedicated migration sprint. The AI: handles the migration as part of regular feature work. AI rule: 'The boy scout rule for framework migration: every touched file gets migrated. The AI does the migration work alongside the feature work.'
'Files in app/: App Router conventions. Files in pages/: Pages Router conventions. New files: always in app/.' The directory: is the natural boundary between old and new framework code. The AI: reads the file location and applies the correct pattern. No ambiguity. No conditional logic. The directory structure: already separates old from new. The dual-pattern rule: leverages this natural separation.
Step 2: Old-to-New Pattern Mapping
Create a mapping table in the rules or in a linked reference document. Format: 'Old pattern → New pattern. getServerSideProps → Server Component with async data fetching. getStaticProps → generateStaticParams + Server Component. _app.tsx → app/layout.tsx. pages/api/*.ts → app/api/*/route.ts. useRouter (next/router) → useRouter (next/navigation) or usePathname/useSearchParams.' The mapping: tells the AI exactly how to translate between frameworks. For each old pattern: the exact new equivalent.
The mapping: is the AI's migration guide. When the AI encounters old-framework code and needs to migrate it: it references the mapping to produce the correct new-framework equivalent. Without the mapping: the AI guesses at the translation (and may guess wrong — for example, using the wrong useRouter import). With the mapping: the translation is explicit and correct. AI rule: 'The mapping table: the most important artifact of the rule migration. It tells the AI exactly how to translate each pattern. Create it before the migration starts.'
Testing the mapping: for each entry in the mapping table, run a test prompt that requires the migration. 'Migrate this getServerSideProps page to App Router Server Component.' Verify: the AI applies the correct mapping. If the AI translates incorrectly: the mapping entry is ambiguous. Clarify. AI rule: 'Test each mapping entry with a migration prompt. The mapping must be unambiguous enough for the AI to apply correctly every time.'
The code migration begins Monday. The rules: still describe the old framework. The AI: generates old-framework code for new files. Developers: manually convert each AI-generated file to the new framework. Wasted effort. Fix: update rules to include new-framework patterns BEFORE the migration starts. Monday morning: the AI generates new-framework code for new files. Zero manual conversion. The rule update: should be the first PR of the migration, not the last.
Step 3: Post-Migration Rule Cleanup
After the migration is complete (all code is on the new framework): remove the dual-pattern rules and the old-framework references. Before: '## Data Fetching\nNew code: Server Components with async functions.\nExisting code: maintain getServerSideProps patterns.' After: '## Data Fetching\nUse Server Components with async functions for all data fetching. No useEffect for server data — fetch in the component directly.' The post-migration rules: clean, focused on the new framework only.
Deprecate old-framework rules: use the deprecation lifecycle from the previous tutorial. Mark old-framework rules as deprecated. Provide the new-framework equivalent. Remove after the transition period (1-2 weeks after the last old-framework file is migrated). The deprecation: a final safety net in case any old-framework code was missed during migration.
Archive the migration rules: the dual-pattern rules and the mapping table: are valuable historical documents. Archive them (do not delete). If the organization migrates another project with the same framework change later: the archived migration rules provide a ready-made guide. AI rule: 'Archive the migration rules after the migration completes. They are the blueprint for the next project that does the same framework migration.'
getServerSideProps → Server Component with async data. pages/api/*.ts → app/api/*/route.ts. useRouter (next/router) → useRouter (next/navigation). Each mapping: tells the AI exactly how to translate one pattern to another. Without the mapping: 'Migrate this page to App Router' produces the AI's best guess (often wrong for framework-specific details). With the mapping: the AI applies the documented translation. The mapping: 30 minutes to write. The value: every AI-generated migration is correct.
Framework Migration Summary
Summary of migrating AI rules during a framework change.
- Timing: update rules BEFORE starting the code migration. Rules guide the AI from day 1
- Three phases: pre-migration (old rules), during (dual-pattern rules), post (new rules only)
- Dual patterns: directory-scoped (app/ = new, pages/ = old). New files always use new framework
- Boy scout rule: every touched file gets migrated. AI migrates alongside feature work
- Mapping table: old pattern → new pattern for every convention. The AI's migration guide
- Test each mapping: migration prompt per entry. Verify AI translates correctly
- Post-migration: remove dual patterns. Deprecate old references. Clean rules for new framework only
- Archive: save migration rules. Blueprint for the next project doing the same framework change