SuperAPI AI Directory

deps-check

Coding & development

View repository

Updated 10-15 19:47

About this skill

deps-check — dependency lookup before editing

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:

  1. You know to run the tests
  2. 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:

  1. Find the nearest package.json going upward as the project root
  2. If the project has madgeinstalled, prefer madge --reverse to list dependents
  3. Otherwise fall back to grep, searching src/、app/、lib/、test/ for import / require statements in common directories such as
  4. 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.ts is imported by 12 files, of which App.tsx、NoteList.tsx、useNotes.ts uses listNotes(). What I want to change is listNotes '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 --noEmit to 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 .