Legacy Safety Rails

Legacy Safety Rails

Build the protective infrastructure that makes legacy refactoring safe: tests, observability, feature flags, and rollback plans.

Goal

Create a multi-layer safety net so that any future code change can be verified, monitored, and reversed.

When to Use

• After documentation exists (via legacy-doc-bootstrap)
• Before any refactoring or modernization work begins
• When the user wants to "make this safe to change"
• When critical paths lack test coverage

The Five Guardrail Layers

Layer 1: Behavior Baseline

Capture current behavior as the source of truth.

• API responses: Record request/response pairs for key endpoints
• UI state: Screenshots or snapshots of critical pages/states
• Data contracts: Current schemas, field types, required fields
• Performance baseline: Response times, throughput for P0 paths
• Side effects: What external calls happen (emails, webhooks, analytics events)
• Runtime behavior: Actual call chains, feature flag states, real data shapes (see docs/methodology.md → Runtime Behavior Capture)

Layer 2: Test Guardrails

Priority order (NOT "write all unit tests first"):

1. Characterization tests — capture actual behavior as golden files/snapshots, including bug behavior that downstream may depend on. See docs/methodology.md → Characterization Testing.
2. P0 path integration tests — end-to-end for critical user journeys
3. Business rule module tests — isolated tests for core business logic
4. Contract tests — API schemas, database schemas, message formats (see Contract-First below)
5. Smoke tests — basic "does it start and respond" health checks

Characterization test rules:

• Capture reality, not intent. Do not "fix" tests to match expectations.
• Include edge cases: empty input, null values, boundary conditions, error responses.
• Tools: snapshot testing (Jest snapshots, approval tests), API recording (VCR/Nock/Polly.js).
• After refactoring, these tests catch unintended behavior changes — even "bug fixes" that break downstream.

Layer 3: Compatibility Guardrails

Protect interfaces and contracts using a contract-first approach (see docs/methodology.md → Contract-First Boundary Definition):

• API contracts: OpenAPI spec / JSON Schema for HTTP interfaces
• Data contracts: TypeScript interfaces or JSON Schema for data structures
• Event contracts: Schema for events/messages between modules
• Database contracts: Migration-versioned schema expectations
• Error codes and error message formats
• Default values and fallback behaviors

Key rule: Contracts must be tested (Layer 2 contract tests). Untested contracts are just documentation.

Layer 4: Release Guardrails

Mechanisms for safe deployment:

• Feature flags for new code paths
• Gradual rollout / canary deployment strategy
• Shadow mode (new code runs but old code serves)
• Rollback procedure (documented, tested)

Layer 5: Change Guardrails

Per-change safety checklist:

• Impact scope documented
• Verification method defined
• Rollback method defined
• Human approval obtained for flagged changes

Mandatory Workflow

Step 1: Assess Existing Safety Infrastructure

1. What test framework is in use? What version?
2. What tests exist? What do they cover?
3. Is there CI/CD? What checks run on commit/deploy?
4. Are there feature flags, monitoring, or alerting?
5. What's the current deployment/rollback process?
6. Check project type from discovery outputs. Load the corresponding profile from skills/legacy-discovery/profiles/ to understand stack-specific testing tools and guardrail priorities.

Step 2: Prioritize by Risk

Using discovery risk labels:

| Label | Safety Action | |-------|--------------| | P0-CRITICAL | Layer 1 (baseline) + Layer 2 (integration test) + Layer 4 (rollback) | | HIGH-RISK | Layer 2 (module tests) + Layer 3 (contracts) | | TEST-MISSING | Layer 2 (appropriate test type) | | LEGACY-SEALED | Layer 1 (baseline only — don't touch) | | SAFE-TO-EXTRACT | Layer 2 (module tests before extraction) |

Step 3: Build Guardrails Incrementally

For each domain/module in scope:

1. Capture baseline — record current behavior
2. Write highest-priority tests — based on risk assessment
3. Document contracts — lock down interfaces
4. Define rollback procedure — before any refactor begins
5. Set up feature flags — if the project's tech stack supports them

Step 4: Verify Guardrails Work

• Run all new tests. They must pass against current code.
• Intentionally break something small — verify tests catch it.
• Document what each guardrail protects.

Step 5: Update Documentation

Add test baseline info to docs/legacy-modernization/domains//test-baseline.md. Record module-to-test mapping for every guarded source file and make the edit gate explicit (ALLOW / BLOCKED-TEST-MISSING / BLOCKED-DOC-MISSING).

Required Outputs

| Output | Description | |--------|-------------| | Test inventory | What tests were added, what they cover, what's still missing | | Contract registry | Documented API/schema/event contracts | | Baseline snapshots | Captured behavior baselines with storage location | | Rollback plan | Step-by-step rollback procedure for each area | | Coverage gap report | What's still unprotected, prioritized by risk | | Feature flag plan | What flags are needed for upcoming changes |

Hard Rules

1. Match the existing stack. Write tests using the project's existing test framework and version. Don't introduce new test frameworks without discussion.
2. Lockfile versions apply. If the project uses Jest 27, write Jest 27-compatible tests. Don't use Jest 29 APIs.
3. Tests must pass today. Every test you write must pass against the current codebase. Failing tests are not guardrails.
4. Don't test implementation details. Test behavior and contracts, not internal structure.
5. Baseline before changing. Never skip behavior capture for a P0-CRITICAL module.
6. Rollback must be documented. Every guardrailed area needs a written rollback procedure.
7. Don't boil the ocean. You don't need 100% coverage. You need coverage on the paths that matter.
8. Create module-to-test mapping. The guardrail is incomplete until each protected module points to concrete tests.
9. Block source edits when tests are missing. If a module is still TEST-MISSING, document that the edit gate remains closed.

Profile-Specific Guardrail Guidance

The project type (detected during discovery) determines which guardrails matter most. Consult the profile for stack-specific tools and approaches.

Frontend Projects (profiles/frontend.md)

| Layer | Focus | |-------|-------| | Behavior baseline | Screenshot snapshots of key pages/states, Core Web Vitals baseline (LCP, INP, CLS) | | Test guardrails | Component tests (Testing Library), E2E tests (Playwright/Cypress), visual regression (Chromatic/Percy) | | Compatibility guardrails | Component prop interfaces, API request/response types, CSS scope boundaries | | Release guardrails | Feature flags (LaunchDarkly/Unleash/custom), A/B testing hooks, bundle size gate in CI | | Change guardrails | Bundle size diff check, lighthouse CI, accessibility audit (axe-core) |

Backend-Node Projects (profiles/backend-node.md)

| Layer | Focus | |-------|-------| | Behavior baseline | API response recording (Nock/Polly.js), database state snapshots | | Test guardrails | API integration tests (Supertest), middleware isolation tests, queue/worker tests | | Compatibility guardrails | OpenAPI schema validation, database migration versioning, event schema contracts | | Release guardrails | Feature flags, canary deployment, graceful shutdown verification | | Change guardrails | npm audit in CI, health check endpoint verification |

Backend-Java Projects (profiles/backend-java.md)

| Layer | Focus | |-------|-------| | Behavior baseline | API response recording, database state with Testcontainers | | Test guardrails | @SpringBootTest integration tests, MockMvc/RestAssured API tests, ArchUnit architecture tests | | Compatibility guardrails | OpenAPI schema, Flyway/Liquibase migration versioning, message contract tests | | Release guardrails | Spring Profiles for feature toggling, Actuator health checks, JVM metrics baseline | | Change guardrails | OWASP dependency-check in CI, JaCoCo coverage gate |

Backend-Python Projects (profiles/backend-python.md)

| Layer | Focus | |-------|-------| | Behavior baseline | API response recording (VCR.py/responses), database state fixtures | | Test guardrails | pytest integration tests, DRF APIClient/FastAPI TestClient, factory_boy fixtures | | Compatibility guardrails | Schema validation (Pydantic/Marshmallow), Django migration lint, event contracts | | Release guardrails | Feature flags (django-waffle/Unleash), health check endpoints | | Change guardrails | pip-audit/safety in CI, coverage gate (pytest-cov) |

Backend-Go Projects (profiles/backend-go.md)

| Layer | Focus | |-------|-------| | Behavior baseline | API response recording, database state with testcontainers-go | | Test guardrails | httptest API tests, table-driven tests, -race flag in CI, integration tests with build tags | | Compatibility guardrails | protobuf/OpenAPI schema validation, migration versioning (golang-migrate/goose) | | Release guardrails | Feature flags, graceful shutdown (signal.NotifyContext), health/ready endpoints | | Change guardrails | govulncheck in CI, golangci-lint, benchmark regression tests |

Fullstack Projects (profiles/fullstack.md)

Apply both frontend and backend layers, plus:

| Layer | Focus | |-------|-------| | Behavior baseline | Full user journey recording spanning frontend and backend | | Compatibility guardrails | Frontend-backend API contract tests (shared types or schema validation) | | Release guardrails | Coordinated deploy strategy, deploy-order safety | | Change guardrails | Contract drift detection between frontend types and backend responses |

Anti-Patterns

| Don't | Do instead | |-------|------------| | Write 200 unit tests for utility functions | Write 5 integration tests for P0 user journeys | | Introduce a new test framework | Use the existing one at its actual version | | Write tests that depend on internal state | Test observable behavior and public interfaces | | Assume CI will catch everything | Verify tests actually run in CI | | Skip rollback planning | Document rollback for every guardrailed area | | Add guardrails to sealed modules | Capture baseline only — don't modify sealed code |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ForeverSc
• Source: ForeverSc/ai-handrail
• License: MIT

Install and usage instructions live in the source repository linked above.