AgentSkillsCN

multi-file-changes

针对跨越3个以上文件、引入第三方代码，或跨crate边界的复杂变更，制定科学的方法论。在进行任何多文件变更前，务必先行咨询。

SKILL.md
--- frontmatter
auto-generated: true
name: multi-file-changes
description: "Methodology for complex changes spanning 3+ files, vendored code, or cross-crate boundaries. Consult before any multi-file change."

Overview

Methodology for complex changes that span multiple files, crates, or submodule boundaries. These disciplines ensure clean, well-coordinated changes rather than iterative patch-and-fix cycles.

Disciplines

1. Read Before Write

Read every file and symbol you will touch AND every file that references what you will change. For cross-boundary work this may mean a dozen or more targeted reads (struct definitions, trait implementations, module exports, command handlers, frontend type bindings) before writing a single line.

Anti-pattern: Read 2–3 files, form a mental model, start writing, patch when things break.

2. Trace the Type/Ownership Chain

For vendored/patched/deep code, trace the full path from where you are to the API you need. Document the chain explicitly so every line in a handler is intentional, not a guess.

3. Enumerate Second-Order Effects

After designing a change, ask: "what else touches the thing I'm changing?"

  • •Changing a struct field → what code reads/writes that field?
  • •Gating a code path → does the variable assignment need gating too? (unused warnings)
  • •Modifying a public API → which downstream consumers break?

4. Respect Conditional Compilation Boundaries

#[cfg(...)] blocks are load-bearing. Platform-specific code stays platform-specific. Do not unify into one abstraction when platforms genuinely differ.

5. Match Existing Patterns Exactly

Before writing a new test, commit, or task entry, read 2–3 existing examples of the same kind. Match structure, naming, style.

6. Verify at Each Layer

For multi-crate or submodule work: cargo check in submodule → cargo check in parent → cargo fmt → only then commit. Do not batch-verify at the end.

When to Consult This

  • •Before any change touching 3+ files
  • •Before any change to vendored/patched code
  • •Before any change that crosses a crate/submodule boundary
  • •After a failed attempt at a complex change (re-read before retrying)

See Also