Ai handrail

Making Legacy Projects Safer for Vibe Coding. AI适老化改造，让老项目更适合 Vibe Coding。

Install

npx -y skills add ForeverSc/ai-handrail

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when working with legacy projects, old codebases, or inherited systems that need modernization. Triggers when user mentions legacy code, old project, inherited codebase, technical debt, legacy refactoring, safe modernization, understanding an unfamiliar large codebase before making changes, AI化改造, AI-friendly modernization, make this project AI-ready, or modernize this project.

SKILL.md

5.6 KB, as published. Nobody here has run it

AI Handrail — Legacy Project Modernization Suite

A skill suite for incrementally making legacy projects AI-friendly. Core principle: add handrails first, then refactor.

When to Use

Inheriting or onboarding to a large existing codebase
Planning modernization of legacy systems
Needing to understand old code before making changes
Adding AI-assisted development to projects without docs/tests
Reducing risk of breaking changes in critical business systems

When NOT to Use

Greenfield projects
Small scripts or utilities with obvious structure
Projects already well-documented with comprehensive test suites

Project Type Profiles

Discovery (Phase 0) automatically detects the project type and loads a corresponding profile from skills/legacy-discovery/profiles/. Profiles provide stack-specific reconnaissance checklists, critical path patterns, risk labels, and structural analysis tools.

Profile	File	Triggers
Frontend	`profiles/frontend.md`	React, Vue, Angular, Svelte, etc.
Backend-Node	`profiles/backend-node.md`	Express, Fastify, NestJS, Koa, etc.
Backend-Java	`profiles/backend-java.md`	Spring Boot, Quarkus, Jakarta EE, etc.
Backend-Python	`profiles/backend-python.md`	Django, Flask, FastAPI, etc.
Backend-Go	`profiles/backend-go.md`	Go with gin, echo, chi, net/http, etc.
Fullstack	`profiles/fullstack.md`	Both frontend + backend signals detected

Profiles extend the base workflow — they add stack-specific checks without replacing core steps. Subsequent skills (doc-bootstrap, safety-rails, refactor-plan) use the detected project type to apply profile-aware guidance.

Sub-Skills

This suite contains 4 skills used in sequence, plus an orchestrator for guided end-to-end experience:

Orchestrator → `legacy-kickstart` (Recommended Starting Point)

One-click guided modernization. Read skills/legacy-kickstart/SKILL.md. Use when: You want a full guided experience — project scan, modernization plan, then automated phased execution. Best for first-time users or when starting fresh on a large legacy project.

Phase 0 → `legacy-discovery`

Understand the project. Read skills/legacy-discovery/SKILL.md. Use when: Starting work on an unfamiliar legacy project.

Phase 1 → `legacy-doc-bootstrap`

Create AI-consumable documentation. Read skills/legacy-doc-bootstrap/SKILL.md. Use when: Discovery is complete and knowledge needs to be persisted.

Phase 2 → `legacy-safety-rails`

Build guardrails. Read skills/legacy-safety-rails/SKILL.md. Use when: Documentation exists but no safety nets protect refactoring.

Phase 3 → `legacy-refactor-plan`

Plan safe, incremental changes. Read skills/legacy-refactor-plan/SKILL.md. Use when: Guardrails are in place and actual code changes are needed.

Hard Rules (apply to ALL sub-skills)

No full-project scans. Analyze one domain / critical path / subsystem per round.
Lockfile is truth. Read package-lock.json, yarn.lock, Gemfile.lock, poetry.lock, go.sum, etc. Never assume latest versions.
Project code is primary reference. Existing implementations beat external documentation.
High-impact old dependencies require source-backed verification. If an outdated dependency has a large blast radius, you must review the lockfile, project code, and package source code for the pinned version instead of trusting generic examples.
80/20 rule. Identify P0 critical paths first. Don't chase completeness in round one.
Complex logic needs a flowchart. State-heavy and branch-heavy legacy behavior must be documented visually.
Non-standard behavior must be tagged. Hidden traps and counter-intuitive side effects should be recorded explicitly, not left implicit.
No hidden assumptions. If something is unknown, mark it UNKNOWN — never guess silently.
Human checkpoints are non-negotiable. Business rules, schema changes, deletions, and behavioral changes require explicit human approval.
Guardrails before depth. Tests → observability → feature flags → rollback plan → then refactor.
No source edits before tests exist. TEST-MISSING or missing module-to-test mapping means add tests first, then change code.

Risk Labels

Tag every module/area analyzed. Full label definitions in docs/naming.md.

P0-CRITICAL — core revenue/safety path
HIGH-RISK — complex, fragile, or undertested
LEGACY-SEALED — do not touch without explicit approval
SAFE-TO-EXTRACT — low coupling, safe to isolate
DOC-MISSING / TEST-MISSING — prerequisite work needed before changes
HUMAN-REVIEW — requires human sign-off
DEAD-CODE — unused code, mark as AI-ignorable
CIRCULAR-DEP — circular dependency, high coupling risk
HOTSPOT — frequently modified file, high bug probability

Profile-specific labels (e.g., GLOBAL-CSS, GOROUTINE-LEAK, CONTRACT-DRIFT) are defined in each profile and in docs/naming.md.

Per-Round Completion Criteria

Every analysis round must answer exactly 4 questions:

What specific area was analyzed this round?
What has been confirmed?
What remains unknown?
What should be analyzed next and why?