Build legacy guardrails

Build Legacy Guardrails

Build the smallest credible safety net before modifying a legacy project.

The goal is not coverage percentage or fixing every old test. The goal is: environment can be reproduced, critical paths are known, P0 guardrail tests are green, CI blocks regressions on those guardrails, and remaining risks are explicit.

Hard Rules

• Do not assume Maven, Java, Spring, Nacos, or any specific stack. Detect the project.
• Prefer existing project commands, scripts, Compose files, fixtures, and test style.
• Make the environment phase self-contained; do not require another skill to know how to run it.
• Use docs/source assets when present; if missing, generate the minimum map needed or record the gap.
• Characterization Tests assert actual current behavior, not ideal behavior.
• Do not fix business behavior during guardrail setup unless required to make tests runnable; record suspected bugs in summary.md.
• P0 guardrail tests must pass. Full existing test suites must be run and recorded, but only become blocking when already green or explicitly requested.
• Keep P0 batches to 1-3 tests, preferably 1. Simple CRUD does not enter the plan.
• Try at most 3 fixes for the same error, then stop and record the blocker.
• Never delete volumes, databases, caches, or object storage data.
• Never copy real secrets into docs, tests, CI, or examples.

Read references/guardrail-policy.md before writing tests, CI, or summary.md.

Workflow

1. Preflight

Inspect the project shape before acting:

• guidance files: AGENTS.md, CLAUDE.md, .claude/skills/*, .agents/skills/*
• existing docs: docs/api-list.md, docs/data-model.md, diagrams, dependency docs
• build/test manifests: pom.xml, build.gradle*, package.json, pyproject.toml, requirements*.txt, go.mod, *.sln
• runtime: Docker Compose, Dockerfiles, env examples, README
• existing CI and test directories

If architecture/data/API assets are absent, create only the minimum needed to identify critical paths, or call the local project-infra/docs skill if available.

2. Environment Baseline

Run the environment path directly:

• create/update docs/env-checklist.md
• create/update docs/install-log.md
• create/update docs/startup-log.md
• create/update docs/smoke-test-result.md
• create/update docs/setup-guide.md
• create scripts/install-deps.sh only when host-level dependency installation is actually needed
• create deps-start.sh, deps-stop.sh, and deps-status.sh only when the project has no equivalent existing commands
• create docker-compose.dev.yml only when no sufficient Compose file exists

Inspect dependency diagrams, configs, env examples, Docker files, build manifests, and README. For each dependency record name, major version, default port, connection info, initialization needs, and evidence.

Prefer Docker/Compose for middleware. Reuse existing Compose before creating overlays. Validate Compose before startup. Start the app with the project-standard command, run the detected build command, then smoke test 3-5 safe endpoints or ports. Do not call destructive, payment, messaging, or external-write endpoints.

3. Critical Paths And Test Inventory

Create/update:

• docs/critical-paths.md: at most 8 risky business paths.
• docs/test-status.md: existing unit/integration/E2E inventory, controller/service coverage, critical-path coverage, real test run result.
• docs/test-gaps.md: P0 max 10 and P1 max 10, only for critical paths.
• docs/test-plan.md: P0 batches, ordered as Characterization > integration > complex unit.

Do not include every endpoint or every service. Include only paths likely to break during refactor or migration.

4. Fill P0 Guardrails

Implement P0 batches one at a time:

1. Run or probe the existing behavior first.
2. Convert observed behavior into assertions.
3. Run the smallest relevant test command.
4. Move to the next batch only after the current batch passes.
5. Record what was observed and what was skipped.

For integration tests, start the real application context and required real middleware/test database. Mock only external paid/network providers and nondeterministic AI calls.

5. CI

Generate or update the project CI:

• push to any branch and pull/merge request triggers
• project runtime version from manifests
• required middleware from the environment checklist
• dependency cache for the detected package manager
• P0 guardrail command as the blocking check
• full-suite command as blocking only if the suite is already green or explicitly requested
• test reports/logs uploaded as artifacts

Use the repository's platform if discoverable. Otherwise default to GitHub Actions.

6. Summary

Write root summary.md with:

• produced files and one-line purpose for each
• environment status
• critical paths chosen
• P0 tests added and whether each is Characterization or integration
• actual test commands and results
• CI status
• suspected bugs and human-confirmation items
• assumptions made because the project lacked evidence

Completion Check

Before reporting done, verify:

• expected docs exist
• environment smoke is passed or blockers are documented
• docs/critical-paths.md, docs/test-status.md, docs/test-gaps.md, and docs/test-plan.md agree with each other
• P0 guardrail tests pass
• full-suite result is recorded even if red
• CI file uses test placeholders, not real secrets
• summary.md tells the next engineer what is safe to refactor and what still needs attention