Making Legacy Projects Safer for Vibe Coding
English · 中文
AI Handrail is a skill suite for legacy projects, designed to make Vibe Coding safer and more reliable in real-world codebases.
It does not try to rewrite a legacy project in one shot. Instead, it first reshapes the project into a system that AI can work with more safely:
- Let AI understand the project from real code and real dependencies
- Turn tribal knowledge into reusable documentation
- Add guardrails such as tests and contracts
- Only then move into a small-step, verifiable, rollback-safe modernization flow
Legacy projects are like old houses that have been lived in for years: only the long-time maintainers know which switch controls which light, which door needs to be lifted slightly to close, and which wire should never be touched. If AI jumps in without that context, it may remove things that “look unnecessary” or replace implementations that “look outdated” — and end up breaking critical paths.
| Legacy reality | What AI does without guardrails |
|---|---|
| The project is too large to read all at once | Hallucinates structure it never actually inspected |
| Business context lives only in senior engineers' heads | "Optimizes" business logic based on guesses |
| Dependencies are still pinned to versions from years ago | Writes code against the latest APIs and fails to compile |
| No tests, no docs | Breaks core flows without noticing |
| Knowledge exists only in chat history | Starts from zero in the next session |
| Big-bang refactors | Damages critical flows very easily |
# Add the marketplace (once)
/plugin marketplace add ForeverSc/ai-handrail
# Install the plugin
/plugin install ai-handrail@ai-handrailOr install directly from a local clone:
git clone https://github.com/ForeverSc/ai-handrail.git
cd ai-handrail
/plugin install .git clone https://github.com/ForeverSc/ai-handrail.git ~/.codex/ai-handrail
mkdir -p ~/.agents/skills
ln -s ~/.codex/ai-handrail/skills ~/.agents/skills/ai-handrailSee .codex/INSTALL.md for details.
git clone https://github.com/ForeverSc/ai-handrail.git ~/.cursor/ai-handrail.cursor-plugin/plugin.json will be detected automatically.
Copy the skills/ directory into your tool's skill discovery path.
Option A: Guided (recommended)
- Install AI Handrail using one of the methods above
- Open your legacy project
- Say "Help me modernize this project" or "make this project AI-ready"
- Follow the prompts. The orchestrator will automatically handle the later steps
Option B: Manual
- Install AI Handrail using one of the methods above
- Open your legacy project
- Run
legacy-discoveryon one business domain or critical path - Move through the workflow phase by phase
| Skill | Purpose |
|---|---|
legacy-kickstart |
Guided one-click modernization — scans the project, generates a modernization plan, and orchestrates phases 0-2 automatically |
legacy-discovery |
Understand the project without touching code |
legacy-doc-bootstrap |
Turn tribal knowledge into documentation AI can read |
legacy-safety-rails |
Add tests, lock contracts, and prepare rollback paths |
legacy-refactor-plan |
Break work into small tasks, verify each step, and roll out incrementally |
One-click entry (recommended) → legacy-kickstart Orchestrates the full flow below
Phase 0: Discovery → legacy-discovery Understand the project without touching code
Phase 1: Documentation → legacy-doc-bootstrap Turn tribal knowledge into documentation AI can read
Phase 2: Safety Rails → legacy-safety-rails Add tests, lock contracts, prepare rollback paths
Phase 3: Modernization → legacy-refactor-plan Break work into small tasks, verify each step, roll out incrementally
Once the plugin is installed, AI gets automatic reminders during coding:
AI starts a new session
└→ [session-start] Detects project docs → injects context: "read the docs before editing code"
AI is about to edit files
└→ [pre-edit-guard] Checks relevant docs and test guardrails → blocks edits if prerequisites are missing
AI finishes editing files
└→ [post-edit-verify] Detects the project's test tooling → reminds AI: "run the tests and make sure nothing broke"
Even in a brand-new session with zero chat history, these hooks enforce the safety protocol. Knowledge no longer depends on AI "remembering" things. It is welded into the workflow.
Each module gets labeled so AI can immediately tell whether it is safe to touch:
| Label | Meaning | What AI should do |
|---|---|---|
P0-CRITICAL |
Core revenue or safety path | Maximum caution; any change requires human approval |
HIGH-RISK |
Complex, fragile, or poorly tested | Add tests before touching it |
LEGACY-SEALED |
Sealed area | Do not modify without explicit authorization |
SAFE-TO-EXTRACT |
Low coupling and suitable for extraction | Safe area for incremental modernization |
DOC-MISSING |
Documentation is missing | Write docs before changing code |
TEST-MISSING |
Tests are missing | Add tests before changing code |
HUMAN-REVIEW |
Human confirmation is required | Stop and ask a person |
DEAD-CODE |
Dead code | Lower its priority during analysis; do not delete it |
CIRCULAR-DEP |
Circular dependency | Break the cycle before extraction |
HOTSPOT |
High churn plus high complexity | Most bug-prone area; add tests first |
- Progressive analysis only — never scan an entire large project in one pass
- 80/20 first — identify and protect P0 critical paths before anything else
- Lockfile is truth — use the project's real dependency versions, not whatever the latest docs say
- Project code is the primary reference — existing implementations beat external examples
- Guardrails before cutting — tests, observability, canary plans, and rollback plans must be in place before refactoring
- Human checkpoints are mandatory — if business rules are unclear, stop and ask
- Every change must be verifiable, reversible, and auditable
| Technique | Phase | Purpose |
|---|---|---|
| Seam Detection | Discovery | Find safe entry points for modernization without ripping the system apart |
| Knowledge Archaeology | Discovery | Mine git history for hotspots and decision context |
| Dead Code Detection | Discovery | Remove noise so AI is not misled by irrelevant code |
| Characterization Testing | Safety Rails | Snapshot the system's actual behavior, including downstream quirks and bugs |
| Contract-First Boundaries | Safety Rails | Lock interface boundaries with schemas so internals can change safely |
| Anti-Corruption Layer | Modernization | Isolate new code from legacy concepts |
| Strangler Fig Pattern | Modernization | Run new and old code in parallel and shift traffic incrementally |
See docs/methodology.md for more details.
The templates/ directory contains ready-to-use document templates. Each skill references the templates it produces.
MIT