Dependency-aware change propagation for multi-file projects

Problem Statement

In any project with interconnected files, editing one file often requires updating others. Claude does not track these dependencies. The user has to remember them, or Claude has to rediscover them each session.

Example: I update a config file. That config is referenced by a build script, an API docs page, and several integration tests. If the config schema changes, those dependents may need updates too. Claude does not know this unless I tell it every time -- and if I forget, the files drift apart silently.

This gets worse as projects grow. A 50-file system with cross-references between configs, docs, templates, and generated outputs has dozens of dependency chains. Manual tracking is error-prone. Relying on Claude context to implicitly "know" what depends on what works sometimes but fails silently when it does not.

Existing tools (SYKE, CodeGraph, Augment) solve this for code via static analysis -- import trees, call graphs, type references. But many Claude Code projects include non-code artifacts (markdown docs, configs, templates, plans, knowledge bases) where static analysis does not work. The dependencies are semantic, not syntactic.

Related: #29852 (Orchestrator ignores cascading document dependencies) describes a similar need from a different angle.

Proposed Solution

A dependency map -- a structured file that Claude consults after every file edit. If the modified file has dependents, Claude surfaces them.

Format (markdown table, zero infrastructure):

# Dependency Map -- Change Propagation Registry

> When a file changes, this map tells you what ELSE needs to change.

| Source (when this changes...) | Depends On This (...update these) | What to check |
|-------------------------------|-----------------------------------|---------------|
| `docs/style-guide.md` | All templates in `templates/*.md` | Tone, formatting rules -- changes silently affect every generated doc |
| `config/settings.json` | `docs/generated-index.md` | Regenerate index when config changes |
| `config/settings.json` | `scripts/build.py` | Build script reads config -- new fields may need handling |
| `schemas/api-v2.yaml` | `docs/api-reference.md` | API docs must match schema |
| `schemas/api-v2.yaml` | `tests/integration/*.py` | Integration tests validate against schema |

Key design properties:

1. Bidirectional: Not just "what depends on what" but "what to check" -- tells Claude HOW to propagate, not just WHERE
2. Non-code aware: Tracks dependencies between markdown docs, JSON configs, templates, plans -- anything with semantic relationships that static analysis cannot parse
3. Human-readable + machine-consultable: A markdown table that both the user and Claude can read. No database, no MCP server, no build step.
4. Enforced via CLAUDE.md rule: "After modifying ANY file, consult the dependency map. If the file appears as a Source, check and update every dependent before closing the session."

Proposed integration with Claude Code:

After any Edit or Write tool use, Claude checks whether the modified file appears in the dependency map. If it does:

This file has 3 dependents in the dependency map:
  - templates/*.md (check: formatting rules, heading conventions)
  - scripts/build.py (check: new config fields may need handling)
  - docs/api-reference.md (check: schema alignment)
Want me to check them?

How this works today vs. what I am proposing:

Today, I enforce this via a CLAUDE.md rule: "After modifying ANY file, consult the dependency map." This works but is brittle -- Claude sometimes skips the check under context pressure or in long sessions. A native integration would be more reliable. The simplest implementation: a PostToolUse hook that parses a dependency_map.md (or dependency_map.json) and prints affected files to stderr, which Claude sees as context.

A complementary drift-detection health check can be built on top (I have one running), but that is a separate concern -- the core ask here is the post-edit notification.

Priority

High -- Significant impact on productivity

Feature Category

Configuration and settings

Alternative Solutions

Code-only tools I evaluated:

• SYKE MCP Server: Static import analysis, code-only, answers "what might break?" not "what must change?"
• CodeGraph: Tree-sitter parsing, code-only, no propagation protocol
• Aider repo map: PageRank-based context selection, code-only, read-only (no enforcement)
• Cursor/Augment: Implicit dependency awareness in the model context, not explicit or auditable

Why markdown over a database or MCP server:

• Zero infrastructure (no SQLite, no Neo4j, no server process)
• Version-controllable (git tracks changes to the map itself)
• Human-auditable (I can read and correct it)
• Works across harnesses (Claude Code, Copilot, any LLM that reads markdown)
• The dependencies I am tracking are semantic, not syntactic -- they can only be declared by a human who understands the project, not derived by static analysis

Use Case Example

1. I have a project where docs/style-guide.md defines formatting conventions
2. A dozen templates in templates/*.md and the build script both reference this guide
3. I update docs/style-guide.md to change a heading convention
4. After the edit, Claude checks the dependency map and finds: "This file has 2 dependency chains -- templates and the build script"
5. Claude offers to scan each dependent for references to the changed convention
6. I accept; Claude updates the 3 templates that directly reference the old convention

Without this: I update the style guide, close the session, and discover weeks later that generated docs are inconsistent -- because the templates still follow the old convention.

Additional Context

I have tracked 100+ dependency relationships across 15+ projects using this pattern. The map is organized by project/feature section + a system-wide section. Combined with a CLAUDE.md rule that makes consultation mandatory, it has caught drift that would otherwise go undetected for weeks.

What this does NOT solve:

• Code import/export dependencies (static analysis tools like SYKE are better for this)
• Automatic dependency discovery (the map is manually maintained -- the user declares relationships)
• Real-time enforcement (this is a consultation protocol, not a build gate)

The value proposition is: for non-code artifacts in AI-managed projects, this is the only dependency tracking approach I have found. Static analysis cannot parse "changing this config requires updating that documentation page" -- only a human (or an LLM that has been told) can know that.

Related: #29852 requests similar cascading dependency support. This is a concrete implementation approach for the non-code case.

If the Anthropic team is already exploring dependency awareness natively, I would be happy to contribute to or test it.