CatalogueArchitecture & Code Health
Architecture Drift & Dependency Map
Compares the architecture you believe you have with the dependencies the code actually has.
What it examines
- Modules that depend on modules they should not reach
- Boundaries drawn in a diagram and crossed in the code
- Hidden coupling through shared data or shared types
- A map of those edges a team can review
What you get back
A findings file. Each item has the evidence, how serious it is, and a fix.
Dependencies
- An AI coding agent that reads SKILL.md files, such as Claude Code, Codex or Gemini CLI
- Read access to the repository
- Git history. A snapshot of the files without history is not enough.
- Node.js, to run the analysis tool that ships in the package’s tool folder
- Python 3 with the jsonschema package, to check findings.json before fixing anything
How it works
The audit is read-only. It builds two maps of your code: which files import which, and which files keep changing together in git history.
The findings sit where the two disagree, such as files that always change together with no import between them. It also finds import cycles and infrastructure modules whose change reaches every root that uses them.
Every finding carries the exact command used, so you can re-run it. This package maps coupling and does not fix it, so the remediate skill produces a plan.
Setup
- Unzip the download and keep the whole folder. Copy its audit and remediate folders into your agent's skills folder (for Claude Code, .claude/skills/) in the repository you want to check.
- Confirm Node.js is installed: node --version. Make sure the repository is a full clone with history.
- Open the repository in your agent and ask it to run the d1-architecture-drift-dependency-map-audit skill.
- Check the result with the validator: pip install jsonschema, then python3 path/to/the-unzipped-folder/schema/validate.py findings.json.
- Ask your agent to run the d1-architecture-drift-dependency-map-remediate skill using findings.json. Fix some findings and leave the rest open if you like.
Run it with your agent
Copy the prompt, fill in the parts in square brackets, and paste it into your agent.
Run the d1-architecture-drift-dependency-map-audit skill on this repository. Run the bundled tool with Node.js against this repository, and use the full git history. Mode: audit only. Do not change any code. Write findings.json and findings.md in the repository root.
Run the d1-architecture-drift-dependency-map-remediate skill using findings.json. Work through the findings I choose, and leave the rest open.