Why Deprecate Instead of Delete
Deleting a rule immediately: the AI's behavior changes without warning. Developers: encounter unexpected AI output. Code review: catches patterns that were correct yesterday but wrong today. Trust: eroded. Deprecation: a graceful transition. The rule is marked as deprecated, the replacement is provided, developers have time to adapt, and the rule is removed only after the transition period. The result: zero surprise, zero disruption.
When to deprecate: the rule references a deprecated technology (old library, old framework version), the rule has been superseded by a better approach (new error handling pattern, improved testing convention), the rule is no longer relevant (the problem it solved no longer exists — the codebase was refactored), or the rule is causing more harm than good (high override rate, developer frustration, AI generates worse code following it).
The deprecation lifecycle: active → deprecated (with replacement) → removed. Each stage: has a defined duration and communication requirement. Active: the rule is followed. Deprecated: the rule is marked as deprecated with a pointer to the replacement (developers and AI see both). Removed: the rule is deleted from the rule file. The lifecycle: prevents the 'rug pull' of immediate removal.
Step 1: Mark as Deprecated with Replacement
In the rule file: add a deprecation notice. Before: '- Use lodash for utility functions (import specific functions: import { debounce } from lodash).' After: '- ~~Use lodash for utility functions~~ **DEPRECATED (v2.5.0)**: Use native JavaScript alternatives instead. Array methods: Array.map, Array.filter, Array.reduce. Debounce: use the custom debounce in @/utils/debounce. This rule will be removed in v3.0.0.' The strikethrough: visually signals deprecation. The replacement: tells the AI what to use instead. The removal date: gives developers a timeline.
The AI reads both: during the deprecation period, the AI sees both the deprecated rule and the replacement. It should follow the replacement. If the AI tool does not interpret strikethrough markdown: use a clearer format. 'DEPRECATED: Use lodash for utility functions. REPLACEMENT: Use native JavaScript alternatives (Array.map, Array.filter, Array.reduce). Use @/utils/debounce instead of lodash debounce. REMOVAL: v3.0.0.' The explicit DEPRECATED/REPLACEMENT/REMOVAL labels: unambiguous for any AI tool.
Transition period: the time between deprecation and removal. For minor rules (naming convention change): 2 weeks. For significant rules (error handling pattern change): 1-2 months. For breaking changes (fundamental architecture shift): 3-6 months. The period: gives developers time to update existing code and adjust their workflow. AI rule: 'The transition period matches the impact. Bigger impact = longer transition. A naming change: 2 weeks. A fundamental pattern change: 3+ months.'
During the transition: the rule file has both 'DEPRECATED: use lodash' and 'REPLACEMENT: use native alternatives.' The AI: reads both and should follow the replacement. This dual presence: ensures the AI generates the new pattern while the deprecated rule provides context (why the old pattern exists in the codebase). After removal: only the replacement remains. The transition: is visible in the rules and gradual in the AI's behavior.
Step 2: Communicate the Deprecation
Announcement: when a rule is deprecated, communicate via: Slack (#ai-standards — 'Rule deprecated: lodash utility functions. Replacement: native JavaScript alternatives. Removal: v3.0.0, estimated April 2026.'), the changelog (entry documenting the deprecation with reasoning and replacement), and the sync PR (if rules are synced — the PR shows the deprecation markup). The announcement: reaches developers before they encounter the change.
In the quarterly review: deprecated rules are a standing agenda item. Review: are deprecated rules ready for removal (has the transition period elapsed? Have teams migrated?)? Are any deprecated rules still being used (check if the AI or developers reference the deprecated pattern)? Is the replacement working (is the replacement rule effective, or does it need refinement before the deprecated rule is removed)?
Migration guidance: for significant rule changes, provide migration steps. 'Migration from lodash to native alternatives: (1) Search for lodash imports in your code. (2) For each: replace with the native equivalent (see the mapping table in docs/lodash-migration.md). (3) Remove lodash from package.json when all imports are replaced.' The migration guide: reduces the effort of transitioning. Without it: developers must figure out the migration themselves (time-consuming and error-prone). AI rule: 'For significant deprecations: provide a migration guide. The guide reduces transition effort and prevents migration errors.'
Monday: the AI generates Result pattern for error handling. Tuesday: someone removes the error handling rule without deprecation. Wednesday: the AI generates try-catch (the rule is gone, the AI defaults to generic patterns). The developer: 'What happened? Did someone break the rules?' Trust: damaged. The developer: starts overriding all rules ('they change without warning'). Deprecation: prevents this entire cascade. The transition: gives developers time to understand and adapt.
Step 3: Remove After the Transition Period
Removal check: before removing the deprecated rule, verify: the transition period has elapsed, teams have had time to migrate, the replacement rule is working (no issues reported), and no code still references the deprecated pattern (search the codebase for the old pattern). If all checks pass: remove the deprecated rule from the rule file. If not: extend the deprecation period.
Clean removal: delete the deprecated rule entirely (do not leave a comment saying 'removed rule about lodash' — that clutters the rule file). Record the removal in the changelog: 'v3.0.0: Removed: lodash utility function rule (deprecated in v2.5.0, replaced by native alternatives rule).' The changelog: preserves the history. The rule file: stays clean.
Post-removal: monitor for one week. If developers encounter issues (the AI generates lodash imports because the removal changed the AI's behavior unexpectedly): address immediately. The removal: should be a non-event (the deprecated rule was already not being followed — the replacement was). If the removal causes disruption: the deprecation period was too short or the replacement was not fully adopted. AI rule: 'Post-removal monitoring: one week. If there are no issues after one week: the deprecation lifecycle succeeded. If issues appear: the transition was incomplete — restore the deprecated rule and extend.'
If the deprecation lifecycle worked: the deprecated rule was already not being followed (the replacement was). Removing the deprecated text: changes nothing in practice. The AI: was already using the replacement. Developers: were already writing the new pattern. The removal: is housekeeping, not a behavioral change. If removing a deprecated rule causes disruption: the transition was incomplete (developers or the AI were still following the deprecated pattern). Restore and extend the transition.
Rule Deprecation Summary
Summary of deprecating AI rules gracefully.
- Lifecycle: active → deprecated (with replacement) → removed. Never skip the deprecated stage
- Markup: DEPRECATED label + REPLACEMENT rule + REMOVAL version/date. Unambiguous for AI and humans
- Transition period: 2 weeks (minor), 1-2 months (significant), 3-6 months (breaking)
- Communication: Slack announcement, changelog entry, sync PR with deprecation markup
- Migration guide: for significant changes. Mapping table, step-by-step instructions
- Removal check: transition elapsed, teams migrated, replacement working, no old pattern references
- Clean removal: delete entirely from rule file. Record in changelog. No comment-tombstones
- Post-removal: monitor 1 week. Issues = restore and extend transition. No issues = success