Circular dependencies in code: how to find and fix them to reduce tech debt
By Daniel Brooks Published 9 min read
On this page (8 sections)
- The short version
- Circular dependencies form a closed import path
- Claude Code skills can miss circular dependencies
- Named tools can verify cycles in each ecosystem
- Cycles can cross features and workspace packages
- Design changes break the loop more safely than import tricks
- A disagreement needs a coverage record
- Questions people still ask
In short: A Claude Code skill can miss a circular dependency because it reads selected files, not a complete resolved dependency graph. It may grep imports, open files one at a time, and stop before reaching another module. Verify file coverage, resolve aliases, and confirm the loop with a real checker.
Part of our guide on quick fixes for update issues
| Smallest cycle in one file | A module importing itself |
|---|---|
| Smallest cycle between files | Two modules |
| Best evidence | A complete resolved import path |
| TypeScript check | dependency-cruiser or Madge with Node and config |
| Webpack check | circular-dependency-plugin during compilation |
| Refactor safety net | Tests plus a repeatable checker |
The short version
- Check which files the skill opened before trusting its result
- Resolve aliases, generated files, barrels, dynamic imports, and workspace boundaries
- Use a named checker with the project's resolver and entry points
- Break the design loop instead of hiding it inside a function
- Prioritise cycles by change frequency, build cost, and refactor risk
Circular dependencies form a closed import path
Say a screen imports a formatter, while the formatter imports the screen's title. Each file makes sense alone, yet the two arrows close a loop.
A module importing itself is already a cycle. Between two different files, the smallest cycle has two modules.
A cycle can span many files, including a barrel that re-exports another module. The practical damage depends on runtime order, build behaviour, and change frequency.
The program may still run. Teams then work around the loop, and each workaround makes the next change harder. The other half of this decision is difference between oem and retail license.
- Self-cycle: one module imports itself through a direct or resolved path
- Direct cycle: file A imports file B, and file B imports file A
- Indirect cycle: A imports B, B imports C, and C imports A
- Barrel edge: an index file re-exports a module that points back to its importer
Claude Code skills can miss circular dependencies
A Claude Code skill is a written instruction file with a declared set of allowed tools. It tells Claude Code which commands to run, files to inspect, and checks to perform.
A skill misses cycles when its instructions never ask for a resolved graph. If it only says grep the tree and open files, the limitation sits in the instructions, not in Claude Code.
Open the skill definition before trusting its result. Look for a step that resolves imports into a graph, names configuration files, and includes generated or workspace paths. We cover troubleshooting passkey sync between iphone and windows pc in its own article.
A shell search can find import-looking text, but it cannot reliably apply aliases, extensions, package exports, or loader rules. Context limits can also leave distant modules unopened.
Ask the skill to report its scope. Request opened files, skipped files, unresolved paths, entry points, and commands it ran.
Import syntax and path rules create blind spots
A grep pattern may match static import lines yet miss require(), export … from, or import(). Variable-based dynamic imports need runtime or build information. People in this spot often ask about how to improve email deliverability for campaigns as well.
Non-JavaScript files can add edges too. Python imports, Java package references, generated clients, templates, and native bindings need checks suited to their toolchain.
TypeScript may map @/services/user through tsconfig paths. Webpack, Vite, and package exports can apply different aliases, extensions, and conditions.
Read the resolver configuration and list generated directories before judging a negative result. A missing edge can mean an uncovered file, a wrong resolver, or an actual clean graph. We go through checking NAS IP and shares step by step elsewhere on the site.
Named tools can verify cycles in each ecosystem
Use a checker that understands your project's resolver. For TypeScript or JavaScript, dependency-cruiser and Madge can report cycles after configuration points to the right source files.
For example, a TypeScript project might run npx madge --circular --extensions ts src/. Output commonly lists a path such as src/a.ts > src/b.ts > src/a.ts, though exact formatting varies by version.
Dependency-cruiser needs Node and a configuration file such as .dependency-cruiser.js. Its command and rule names depend on the installed version, so read its local documentation before copying a command. Before you commit to anything, it is worth looking at choose an eSIM for your trip.
Webpack projects can use circular-dependency-plugin during compilation. ESLint projects can use import/no-cycle from eslint-plugin-import when its resolver matches the project.
Python teams can inspect imports with pydeps or pylint's cyclic-import warning. Java teams can use JDepend or ArchUnit rules, while .NET teams can use NDepend or NetArchTest.
A skill can run these tools only when its instructions allow shell commands and the environment has the needed package, Node version, or configuration.
- Count source files and record resolver configuration
- Inspect the skill definition for a graph-resolution step
- Run the named checker with configured aliases and generated paths
- Walk one reported path and verify every import edge
- Keep the command, report, and configuration with the finding
| Method | What it proves | Limit | Requirement |
|---|---|---|---|
| dependency-cruiser or Madge | Configured JavaScript or TypeScript graph contains a reported cycle | Wrong resolver settings can omit edges | Node, package, source path, and often a config file |
| Webpack circular-dependency-plugin | Webpack compilation saw a cycle | Covers Webpack's graph and entry points | Webpack project and plugin configuration |
| import/no-cycle | ESLint found a cycle under its resolver | Lint settings and scope control coverage | ESLint, eslint-plugin-import, and resolver settings |
| Claude Code skill | Text evidence suggests a possible path | It may skip files or resolve aliases incorrectly | A written skill, allowed tools, and accessible files |
- Named tools expose resolver settings
- A manual walk checks the reported edges
- Claude Code can speed up file triage
- Poor configuration can create false negatives
- Dynamic imports may need manual review
- Different tools may inspect different entry points
Cycles can cross features and workspace packages
A validation helper might import a screen, while the screen imports a service and the service imports the helper. Each edge looks reasonable until the path closes.
Barrel files widen the graph. An index file re-exports several modules, so one short import can load code from another feature.
Monorepos add a boundary question. A cycle inside one package differs from a cycle crossing workspace packages, because package exports, build order, and ownership affect the fix.
Run checks per package and from the workspace entry points. Include generated package output when consumers import it, then decide whether the boundary should permit that edge.
Record tracing time across recent changes if you need to size the debt. Count files opened, minutes spent, and tests or builds affected.
- Helper imports screen: pass screen data into the helper
- Logger imports model: pass an owner identifier instead
- Barrel re-export hides an edge: inspect the barrel and its targets
Design changes break the loop more safely than import tricks
Pass data across the boundary when a lower-level helper needs information from a higher layer. The helper then depends on a value, not the screen or controller that called it.
Split a large module when one file serves unrelated roles. Remove a barrel export when it hides ownership, or create a shared data module with no back-edge.
Keep dependencies pointing toward stable, lower-level code. A module should not import a module that imports it.
Moving an import into a function body can alter loading time without removing the graph edge. Use that pattern only when the runtime behaviour is deliberate and documented.
- Write the complete loop and mark each resolved import edge
- Choose data or behaviour both sides can use without importing either endpoint
- Move the shared part into a module with no back-edge
- Delete old imports and update direct callers
- Run the checker, tests, and relevant build entry points
- Value passing removes unwanted ownership edges
- Smaller modules are easier to test
- Clear direction makes later changes cheaper
- Several callers may need updates
- Generated files may need regeneration
- Tests must cover changed entry points
A disagreement needs a coverage record
Start with scope, not the verdict. Count files under the package, list entry points, and record resolver files such as tsconfig.json or webpack.config.js.
Compare the skill's opened files with the checker's scanned files and mark unresolved paths. A missing file explains disagreement better than a confidence score.
Reproduce one reported path manually. Open each file, copy the import line, resolve aliases, and mark dynamic or generated edges.
If the skill finds a cycle and the checker does not, run the checker against the same entry point and configuration. If the checker finds one first, give Claude Code the missing files and ask it to explain each edge.
A true negative has matching scope, resolver settings, and entry points. A false negative usually has an unopened file, an unresolved alias, or an excluded generated path.
| Evidence | Strong finding | Weak finding |
|---|---|---|
| Import path | A to B to C back to A | A folder looks tangled |
| File coverage | All path files were inspected | Some files were skipped |
| Resolver | Aliases and extensions are configured | Relative paths were assumed |
| Tool agreement | A checker reports the same edge | Only a text scan agrees |
| Cost | Minutes and affected changes are recorded | The debt is described vaguely |
- Coverage records explain tool disagreements
- Resolved paths make claims checkable
- Cost notes support sensible prioritisation
- Configuration takes time
- Dynamic imports still need judgement
- Records become stale after large refactors
Use Claude Code for triage, then prove coverage and confirm cycles with a resolver-aware checker before refactoring.
Questions people still ask
Does a circular dependency always crash the program?
No. A runtime can load a partial module or avoid the edge on a particular path. The cycle can still cause order-dependent behaviour and harder changes.
Can I fix a cycle by moving an import into a function?
That changes loading timing rather than the graph. Separate shared behaviour or pass the needed value across the boundary.
Should I fix every cycle?
Prioritise cycles in frequently changed code, slow builds, flaky tests, or shared packages. Leave a stable low-cost cycle alone only after recording why.
Why did my checker report no cycle when Claude Code found one?
Compare entry points, resolver settings, generated files, and scanned files. One tool may inspect a different graph, or the skill may have inferred an unresolved edge.
How do I estimate circular-dependency tech debt?
Track tracing minutes across several changes, count files opened, and record build or test delays. Rank cycles by change frequency, tracing cost, and refactor risk.