Purpose: Mark stable, critical code with @protected annotations to prevent regressions.
Principle: "If it works and it's critical, protect it."
- Code stable for 2+ sprints/months
- Critical business logic (payments, auth, data integrity)
- Complex integrations tested in production
- Public APIs with external consumers
- Code that caused production incidents when changed
- New experimental features
- Code under active development
- Simple utility functions
- Easily testable pure functions
- Throwaway/temporary code
/**
* @protected
* Locked: YYYY-MM-DD (Sprint XX)
* Status: STABLE - Brief description
*
* DO NOT modify without testing:
* 1. [Test case 1]
* 2. [Test case 2]
* 3. [Test case 3]
*
* Last incident: [DATE] - [Description if applicable]
*/
export function criticalFunction() {
// ...
}"""
@protected
Locked: YYYY-MM-DD (Sprint XX)
Status: STABLE - Brief description
DO NOT modify without testing:
1. [Test case 1]
2. [Test case 2]
Last incident: [DATE] - [Description if applicable]
"""
def critical_function():
pass# After sprint completion
git log --since="2 months ago" --pretty=format:"%s" | grep -i "fix\|bug\|hotfix"
# Look for:
# - Files that haven't changed in 2+ months
# - Files that caused incidents when modified
# - Files with >80% test coverage# Use script (coming soon)
./eng-platform/scripts/protect-code.sh src/api/payments.ts
# Or manually add annotation (see format above)## ⚠️ PROTECTED CODE
### STABLE Components (@protected)
| Component | Status | Test Checklist |
|-----------|--------|----------------|
| [payments.ts](src/api/payments.ts) | ✅ STABLE | Charge succeeds, refund works, webhook fires |**Before modifying payments.ts:**
1. ✅ Test charges in staging?
2. ✅ Test refunds work?
3. ✅ Webhooks fire correctly?
4. ✅ No breaking API changes?@protectedannotation in comments- PRE-FLIGHT checklist in CLAUDE.md
- Manual code review catches violations
// ESLint plugin detects @protected
// Warns: "This file is protected. Run checklist first."# GitHub Actions
- name: Check protected files
run: ./scripts/check-protected.sh
# Requires --force flag to bypass- Read the
@protectedannotation - Complete the PRE-FLIGHT checklist
- Run all tests
- Add new tests if behavior changes
- Get extra code review
If the code needs significant refactoring:
- Remove
@protectedannotation - Add TODO: "Stabilize and re-protect after Sprint XX"
- Refactor
- Re-test extensively
- Re-protect after stabilization
Quarterly audit checklist:
- Review all
@protectedfiles - Remove protection from frequently-changing files
- Add protection to newly-stable files
- Update PRE-FLIGHT checklists
- Verify tests still cover protected code
Last audit: [DATE] Next audit: [DATE + 3 months]
Good:
- Protected files have <5 changes/year
- Zero production incidents from protected code
- PRE-FLIGHT checklists completed before changes
Bad:
- Protected files change weekly (shouldn't be protected)
- Production incidents from skipping checklists
- Annotations outdated (>1 year old)
/**
* @protected
* Locked: 2025-01-17 (Sprint 17)
* Status: STABLE - tRPC + ES federation working
*
* DO NOT modify without testing:
* 1. Actor list loads (dismissed: false filter)
* 2. Validation badges display correctly
* 3. Update/dismiss/delete mutations work
* 4. ES data merges with PG data
*/Why protected: Core data layer, stable for 2 sprints, feeds entire UI.