Understanding Unfamiliar Code

You’re working in a codebase you didn’t write. Maybe you just joined the team, or you’re fixing a bug in a service you’ve never touched. You need to understand how things connect before you start changing them.

Unfault’s code graph helps with this.

Finding What Depends on a File

Before changing a file, see what else depends on it:

unfault graph impact src/api/auth.py

Output:

Impact analysis for src/api/auth.py:

Direct dependents (3):
  → api/routes/users.py (imports validate_token)
  → api/routes/admin.py (imports validate_token, get_permissions)
  → tests/test_auth.py (imports validate_token)

Transitive impact (7 files total)

This tells you the blast radius. If you change validate_token, those three files are directly affected. Seven files total might see different behavior.

Finding What Depends on a Function

For more precision, check a specific function:

unfault graph function-impact src/api/auth.py:validate_token

This shows only what depends on that function, not everything in the file.

Finding the Most Important Files

When you’re new to a codebase, start with the most connected files:

unfault graph critical

Output:

Most critical files (by dependents):

  1. src/core/models.py          (47 dependents)
  2. src/utils/helpers.py        (31 dependents)
  3. src/api/auth.py             (23 dependents)
  4. src/db/connection.py        (19 dependents)
  5. src/config/settings.py      (18 dependents)

These are the files where changes have the most impact. They’re also often the best starting point for understanding how the system fits together.

Finding What a File Depends On

To see what external libraries or internal modules a file uses:

unfault graph deps src/api/client.py

Output:

Dependencies for src/api/client.py:

External:
  · requests
  · tenacity
  · structlog

Internal:
  · src/config/settings.py
  · src/utils/retry.py

This tells you what you need to understand to work on this file.

Finding Files That Use a Library

To see everywhere a library is used:

unfault graph library requests

Output:

Files using 'requests':

  · src/api/client.py:12
  · src/integrations/billing.py:8
  · src/integrations/notifications.py:15
  · scripts/health_check.py:3

Useful when you’re updating a dependency or changing how it’s used across the codebase.

Asking Questions

For higher-level understanding, ask questions in natural language:

unfault ask "How do we handle authentication?"
unfault ask "What's the pattern for database transactions?"
unfault ask "Where do HTTP timeouts get configured?"

This searches past reviews and code patterns to surface relevant context.

Before Making Changes

A practical workflow for changing unfamiliar code:

Check impact first
Terminal window
```
unfault graph impact path/to/file.py
```
Understand what the file depends on
Terminal window
```
unfault graph deps path/to/file.py
```

Ask about existing patterns

unfault ask "How is error handling done in this part of the codebase?"

Make your changes
Review before committing
Terminal window
```
unfault review --uncommitted
```

With AI Agents

If you’re using an AI assistant to modify unfamiliar code, add to your AGENTS.md:

Before modifying code in unfamiliar areas:

1. Run: unfault graph impact <file>
2. If impact is large (>10 files), mention this before proceeding
3. Run: unfault ask "How does [this area] work?"
4. After changes, run: unfault review --uncommitted

This gives the agent context it wouldn’t otherwise have.

Next Steps

Code Graph Reference

All graph commands and options. Read more

Pre-commit Review

Review your changes before committing. Read more

Use with AI Agents

Integrate with AI coding assistants. Read more