AI Rules During Reorgs and Migrations

When Teams Change, Knowledge Walks Out the Door

Organizational restructures move developers between teams. Technology migrations change the tools and patterns developers use. Both disrupt the conventions that teams rely on: a developer moves from the payments team (TypeScript strict, Drizzle, Next.js) to the infrastructure team (Go, Terraform, Kubernetes). The conventions they knew are irrelevant. The conventions they need are unfamiliar. AI rules bridge this gap: the developer's AI reads the new team's rules and generates correct code from day one.

The reorg pattern: team ownership changes (the auth module moves from Team A to Team B), team composition changes (developers transfer between teams), and team scope changes (Team A now owns auth AND payments). Each change creates a knowledge gap: the new owners do not know the existing conventions, the transferred developers do not know the new team's patterns, and the expanded team does not have unified conventions for the combined scope.

AI rules as organizational memory: when developers leave or transfer, their knowledge of conventions goes with them. AI rules stay in the repository. The next developer to work on the code: reads the rules, gets AI-generated code that follows the conventions, and maintains consistency without needing the departed developer's knowledge.

AI Rules Playbook for Reorgs

Before the reorg: ensure AI rules are current and comprehensive in every repo that will change ownership. AI rule: 'Pre-reorg checklist: every repo has current AI rules, rules reflect actual conventions (not aspirational), README is current (setup, development commands, architecture overview). The goal: any developer can take over any repo with rules + README as their guide. Do this before the reorg announcement — after the announcement, people are distracted.'

During the reorg: when a developer transfers to a new team, their first task: read the new team's AI rules file. AI rule: 'Transferred developer onboarding: (1) read CLAUDE.md/AI rules for the new team's repos, (2) set up the development environment following the README, (3) make a small change with AI assistance to verify the rules produce correct code, (4) submit a PR for review by the existing team members. This process takes 1-2 days and produces a productive contributor.'

After the reorg: new team ownership may reveal rule gaps (the previous team had institutional knowledge that was not encoded in rules). AI rule: 'Post-reorg rule audit: within 30 days, the new team reviews the AI rules for their inherited repos. Questions: are the rules complete (do they cover the conventions the code follows)? Are the rules current (do they reference the actual libraries and patterns used)? Are there undocumented conventions (patterns the code follows but rules do not mention)? Update the rules based on the audit.'

💡 Update Rules Before the Reorg, Not After

After the reorg announcement: developers are distracted (worrying about new teams), knowledge transfer is rushed (outgoing team members are disengaging), and documentation is the last priority. Before the announcement: developers are still engaged, can thoughtfully document their conventions, and have time to fill rule gaps. The window for good rule documentation: closes the moment the reorg is announced. Use it.

AI Rules Playbook for Technology Migrations

Migration phases: AI rules change as the migration progresses. Pre-migration: rules encode the current technology (Express.js patterns, REST API conventions). Transition: rules encode both old and new patterns (Express.js for existing code, Fastify for new code, migration helpers). Post-migration: rules encode only the new technology (Fastify patterns, remove Express.js references). AI rule: 'Update AI rules at each migration phase. Stale rules that reference the old technology: generate old-pattern code during the migration, undermining the migration effort.'

Dual-pattern period: during migration, both old and new patterns exist in the codebase. AI rule: 'During migration: the rules clearly distinguish old-pattern (for existing code maintenance) and new-pattern (for new code). Example: existing Express.js routes: maintain with current patterns. New routes: use Fastify with the new pattern. The AI generates the correct pattern based on context: editing an existing Express route = Express patterns. Creating a new route = Fastify patterns.'

Migration completion: after the migration, remove references to the old technology from the rules. AI rule: 'Post-migration cleanup: remove rules for the deprecated technology. Add a prohibition: do not use Express.js for new routes — the project has migrated to Fastify. This prevents regression (developers accidentally using the old pattern) and keeps the rules file lean (no references to deprecated technologies).'

⚠️ Stale Rules Undermine Migrations

The migration from Express to Fastify is underway. But the AI rules still say: 'Use Express router for new endpoints.' The AI generates Express code. Developers accept it without thinking. Three months later: 40% of new code uses the old framework. The migration timeline doubles. Rules must be updated at the start of the migration — not months in. If the rules contradict the migration direction: they are actively working against you.

Preserving Knowledge Through Rules

Institutional knowledge capture: before a key developer leaves or transfers, capture their conventions in AI rules. AI rule: 'Exit interview for conventions: when a senior developer or tech lead leaves the team, spend 1 hour capturing their undocumented conventions. What patterns do they enforce in code review? What anti-patterns do they catch? What architectural decisions did they make and why? Add these to the AI rules file. One hour of capture saves weeks of rediscovery by the next person.'

Knowledge distribution: AI rules distribute knowledge to every developer and every AI on the team. Instead of one person knowing that the error handling pattern uses a specific wrapper: the rule file documents it, the AI generates it, and every developer sees it. AI rule: 'Every convention that exists only in one person's head: is a liability. If that person leaves (transfer, resignation, leave): the convention is lost. AI rules transform individual knowledge into organizational knowledge that persists regardless of personnel changes.'

Living documentation: AI rules are the most-maintained documentation in the repository because they have practical impact (AI reads them for every generated line of code). AI rule: 'AI rules are updated more frequently than READMEs or design documents because: developers see immediate feedback when rules are wrong (AI generates incorrect code). This feedback loop: keeps AI rules accurate. Leverage this feedback loop by encoding more institutional knowledge in the rules file.'

ℹ️ One Hour of Knowledge Capture Saves Weeks of Rediscovery

The tech lead who built the payment system is transferring to another team. In their head: 'The refund flow uses a specific retry pattern because the payment processor has a 5-second timeout on refund endpoints. Without the retry: refunds occasionally fail silently.' If this is not captured in the rules: the next developer modifying the refund flow may remove the retry (it looks unnecessary). Refunds start failing. Investigation takes a week. One hour of exit interview: captures the why behind the pattern.

Reorg and Migration AI Rules Summary

Summary of AI rules strategies for organizational restructures and technology migrations.

Pre-reorg: ensure AI rules are current and comprehensive in all repos. Do this before the announcement
Transferred developers: read rules → setup → small change → PR review. Productive in 1-2 days
Post-reorg audit: new team reviews inherited rules within 30 days. Fill knowledge gaps
Migration phases: update rules at each phase (pre/transition/post). Stale rules undermine migration
Dual-pattern: clearly distinguish old-pattern (maintenance) and new-pattern (new code) in rules
Post-migration: remove deprecated technology rules. Add prohibitions to prevent regression
Knowledge capture: exit interviews for conventions. One hour captures weeks of rediscovery
Living docs: AI rules stay current because developers get immediate feedback when rules are wrong