Why it's needed
The most common cause of "change A breaks B" is that the editor doesn't know who else depends on A. Type checking and tests can catch most regressions, but only if:
- You know to run the tests
- The tests cover that dependency path
Spending 5 seconds before actually making the change to confirm "who imports me" turns after-the-fact debugging into an up-front decision.
When it triggers
Automatically triggers in the following situations:
- You need to modify
src/lib/、src/services/、src/utils/、src/hooks/, shared components, etc.referenced from multiple placesfiles that are - You need to rename, delete, or move a file or exported symbol
- You need to modify an exported function's signature or return type
- The user says "refactor", "restructure", "change the API", "extract this out"
When it doesn't need to triggersituations:
- Purely adding files (nothing depends on them yet)
- Only changing private/local symbols, not touching exports
- Simple style adjustments, copy changes
- Test files themselves
Execution flow
Step 1: Run the script
Call ${CLAUDE_PLUGIN_ROOT}/skills/deps-check/scripts/deps-check.sh <file-path>。
Currently only TypeScript / JavaScript projects are supported (.ts .tsx .js .jsx .mts .cts). Non-TS/JS files are skipped directly and will not interrupt the flow.
The script will:
- Find the nearest
package.jsongoing upward as the project root - If the project has
madgeinstalled, prefermadge --reverseto list dependents - Otherwise fall back to
grep, searchingsrc/、app/、lib/、test/for import / require statements in common directories such as - Output the dependent file paths and the actual referenced symbols (grep mode will display that line directly)
Step 2: Interpret the output
Decide the strategy based on the number of dependents:
| Dependency count | Strategy |
|---|---|
| 0 | Safe change, proceed directly |
| 1-3 | Read each dependent and confirm the change won't break them |
| 4+ | Report the impact scope to the user, confirm whether to split into multiple steps, or add a deprecation shim |
Step 3: Report
Before making the change, first inform the user of the impact scope in one or two sentences, for example:
noteService.tsis imported by 12 files, of whichApp.tsx、NoteList.tsx、useNotes.tsuseslistNotes(). What I want to change islistNotes's return type, and these three files all need to be updated in sync. Continue?
Step 4: Make the change
Only start editing after confirmation. If new dependencies are discovered during editing (e.g., dynamic imports, re-exports), run the script again.
Step 5: Final verification
After the change, run a type check once to confirm no new cross-file errors were introduced:
# 整個專案
npx tsc --noEmit
# 或只驗 incremental(大型專案較快)
npx tsc --noEmit --incremental
If there are errors, go back and fix them; only when it's confirmed clean is the change considered complete. deps-check tells youwhich files to look at, and tsc verifies that youchanged it correctly—only after both steps are done is the loop closed.
Relationship with other mechanisms
- Type checking (tsc): after making changes, run
tsc --noEmitto verify. deps-check isbeforehandto tell you which files to look at, while tsc isafter the factto verify whether you changed things correctly. The two are complementary. - bug-fix-learning: if deps-check did not catch some implicit coupling (for example, through events or global state), then when a bug-fix-learning is triggered afterward, this implicit coupling should be written into memory or the cookbook, so that next time it can be flagged in advance.
- code-reviewer: the review stage will check cross-file impact again, but by then the changes are already done; deps-check is meant to let review focus on quality rather than regressions.
Hook mode (optional)
Users can also attach the script to a PreToolUse hook so it runs automatically before Edit or Write. Example .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/skills/deps-check/scripts/deps-check.sh \"$CLAUDE_TOOL_INPUT_file_path\"",
"timeout": 10
}
]
}
]
}
}
Hook mode is suitable for teams that want to "enforce running it every time"; skill mode is suitable for individual developers who want "the AI to decide the timing itself." Both use the same script.
Future extensions
Currently only TS/JS is supported. If other languages are needed (Python pydeps、Go go list etc.), you can add the corresponding branches in scripts/deps-check.sh .