strategy-legacy-safe-edits
Skill4 starsChanged 4 months agoMITView on GitHub
Edit legacy code such as old CMS or framework code safely — isolate the change, do not modernize in place, avoid touching unrelated legacy, and keep the patch reversible. Use when the agent is about to edit legacy procedural PHP or an older CMS codebase (e.g. Bitrix `CIBlockElement`, `$APPLICATION`, global includes); the user wants a bug fixed in old, legacy code and explicitly does not want it rewritten (for example, "поправь баг в старом коде, не переписывай"); the change must be isolated to the legacy module and easy to revert as a single patch if it misbehaves. Keywords: strategy, legacy, safe, edits, isolate, reversible, patch, modernize, старый, переписывай.
In this repository119 other files it gives its agents.
- strategy-bitrix-d7-incrementalSkill
- strategy-explicit-over-magicSkill
- strategy-framework-conventionsSkill
- strategy-minimal-diffSkill
- strategy-no-untested-refactorSkill
- strategy-preserve-public-apiSkill
- strategy-readonly-immutabilitySkill
- strategy-security-firstSkill
- strategy-test-drivenSkill
- openapiSkill
- paginationSkill
- rest-designSkill
- versioningSkill
- cqrsSkill
- dependency-inversionSkill
- hexagonalSkill
- repository-patternSkill
- service-layerSkill
- bitrixSkill
- findings-reportSkill
- laravelSkill
- performanceSkill
- phpSkill
- project-analysisSkill
- refactoringSkill
- roi-prioritizationSkill
- securitySkill
- stack-detectionSkill
- cache-layersSkill
- component-engineSkill
- d7-eventsSkill
- d7-loaderSkill
- d7-orm-queriesSkill
- iblock-elementsSkill
- kernel-main-moduleSkill
- localizationSkill
- controllersSkill
- ormSkill
- validationSkill
- controllersSkill
- query-builderSkill
- routingSkill
- autoload-psr4Skill
- dependency-managementSkill
- scriptsSkill
- connection-poolingSkill
- mysql-indexingSkill
- redisSkill
- transactionsSkill
- ci-github-actionsSkill
- deployment-strategiesSkill
- docker-phpSkill
- env-configSkill
- associationsSkill
- entities-mappingSkill
- orm-basicsSkill
- entity-apiSkill
- module-developmentSkill
- routing-controllersSkill
- formsSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 68
Do not apply legacy-safe restraint when the user has explicitly commissioned a modernization or migration of the legacy component with its …
- Distinctive: line 70
Do not apply this strategy when the work is new code in a modern, well-tested codebase with no legacy constraints.
- Very specific: line 88
Never replace a working legacy API call (e.g.
- Distinctive: line 93
Prefer the smallest change that satisfies the task, kept local to the file being touched, and easy to revert with a single diff.
- Distinctive: line 98
Avoid touching, reformatting, or modernizing unrelated legacy code near your change.
- Distinctive: line 143
Not applicable — no I/O, auth, or untrusted input.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- generated: do not edit — source: knowledge/atoms/ai-rules/strategy-legacy-safe-edits/ --><!-- schema: atomVersion=3 skillVersion=2 graphVersion=1 --><!-- compile: @php-skills/compiler v1.0.0 (deterministic build) -->Strategy — Legacy-Safe Edits
When to use
- The agent is about to edit legacy procedural PHP or an older CMS codebase
(e.g. Bitrix
CIBlockElement,$APPLICATION, global includes). - The user wants a bug fixed in old, legacy code and explicitly does not want it rewritten (for example, "поправь баг в старом коде, не переписывай").
- The change must be isolated to the legacy module and easy to revert as a single patch if it misbehaves.
When NOT to use
- Do not apply legacy-safe restraint when the user has explicitly commissioned a modernization or migration of the legacy component with its own plan and tests.
- Do not apply this strategy when the work is new code in a modern, well-tested codebase with no legacy constraints.
Core guidance
- Isolate the change to the legacy component — Confine the edit to the single legacy file or function that needs it; do not let the change ripple into other legacy modules.
- Match the legacy code's existing conventions — Follow the legacy file's existing conventions and APIs even if they are dated; do not introduce a different style just for your lines.
- Do not modernize legacy code in place — Do not swap legacy idioms for modern ones (new syntax, new framework APIs, new type hints) while making an unrelated fix in legacy code.
- Keep the patch reversible — Structure the edit so it can be reverted as a single, self-contained patch without unwinding other changes.
- Verify the edit runs on the legacy runtime — Confirm any construct you add is valid on the legacy runtime (for example, no PHP 8 syntax in a PHP 7.4 codebase) before proposing the patch.
Never
- Never replace a working legacy API call (e.g.
CIBlockElement::GetList) with a modern equivalent as a side effect of an unrelated task.
Prefer
- Prefer the smallest change that satisfies the task, kept local to the file being touched, and easy to revert with a single diff.
Avoid
- Avoid touching, reformatting, or modernizing unrelated legacy code near your change; leave surrounding old code exactly as it is.
Escalate to user when
- Escalate to the user before starting a broad migration from legacy API to a modern one (e.g. old CMS API to a D7-style ORM), since it is a separate effort.
Quick recipe
- Identify the single legacy file and lines to change and confirm the runtime version so you use only constructs it supports. (verify: The change is scoped to one legacy component and uses only syntax valid on that runtime.)
- Make the smallest edit in the legacy style, leaving surrounding legacy untouched, so the change is a single reversible patch. (verify: The diff touches only the required lines and can be reverted as one patch.)
Anti-patterns
| Anti-pattern | Why it fails | Do instead |
| Modernizing legacy code during an unrelated fix | It couples a risky modernization with a small fix, expanding the blast radius on<br>untested code. | Make the minimal fix in the legacy style; propose modernization as a separate,<br>planned effort. |
| Reformatting a whole legacy file | The reformatting buries the real change, destroys blame, and can shift behavior<br>in whitespace-sensitive legacy code. | Match the file's existing formatting and touch only the lines the task needs. |
| Replacing a working legacy API call | Legacy APIs often carry subtle behavior the modern call does not reproduce,<br>causing hard-to-trace regressions. | Keep the existing legacy API call and change only what the task requires. |
See references/anti-patterns.md.
Common mistakes
- A patch that cannot be cleanly reverted — Interleaving the fix with unrelated edits makes the patch impossible to revert without losing other work. Fix: Keep the fix self-contained so it maps to a single revertible patch.
- Modern syntax breaks the legacy runtime — Adding PHP 8-only syntax such as enums or constructor promotion to a PHP 7.4 legacy file causes a fatal parse error at runtime. Fix: Use only constructs valid on the legacy runtime; confirm the minimum PHP version before editing.
- Editing unrelated legacy while nearby — "Cleaning up" adjacent legacy code while fixing the target widens the change into fragile, untested territory you were not asked to touch. Fix: Restrict the edit to the exact lines the task requires and leave the rest of the legacy file alone.
Version notes
- Legacy-safe editing spans runtime versions (PHP >=7.4) — This strategy targets legacy code that commonly runs on PHP 7.4 or earlier; the restraint it prescribes applies from PHP 7.4 upward and adapts to whatever the legacy runtime allows.
Security
- Not applicable — no I/O, auth, or untrusted input.
Testing
- Activation and decision behavior are verified in
eval/scenarios/ai-rules/strategy-legacy-safe-edits.yaml.
Additional resources
- references/anti-patterns.md
- references/examples.md
- references/pitfalls.md
- references/recipes.md
- references/version-differences.md
Knowledge graph
Related: ai-rules/strategy-bitrix-d7-incremental, ai-rules/strategy-minimal-diff, ai-rules/strategy-preserve-public-api
<!-- graph-fragment: graph/fragments/ai-rules/strategy-legacy-safe-edits.yaml -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.