Claude Code excels at multi-file refactoring and git-aware development. This lesson teaches you to orchestrate changes across 10+ files, maintain git history, and leverage Claude's understanding of codebase architecture.

Multi-File Editing: Refactoring at Scale

Scenario: You have a Python project with 15 files. You need to rename a database table from users to accounts throughout the codebase. Without Claude Code, you'd manually search-and-replace in each file (error-prone). With Claude Code, you orchestrate the change.

Step 1: Understand Current State

claude run "List all files that reference the 'users' table. Show file names and exact lines."

Claude scans codebase, outputs:

- main.py (line 5, 12, 34): CREATE TABLE users, SELECT * FROM users, INSERT INTO users
- db/migrations/001_create_users.py (line 10): CREATE TABLE users
- models/user.py (line 2, 15): class User, db.table('users')
- tests/test_db.py (line 20, 50): Mock users table

Step 2: Plan Refactoring

claude run "Create a refactoring plan to rename 'users' table to 'accounts'. Consider:
1. Database migrations
2. ORM model files
3. API endpoints
4. Tests
Show files affected and order of changes (dependencies first)"

Claude outputs:

Refactoring Plan:
1. db/migrations/create_users_migration.py → rename table, add backward compat view
2. models/user.py → update class name to Account
3. db/queries.py → update all SELECT/INSERT/UPDATE statements
4. api/endpoints.py → update endpoint logic
5. tests/test_db.py → update mock data
6. requirements.txt → no change needed

Step 3: Execute Changes

claude code "Refactor codebase: Rename 'users' table to 'accounts' in all files.
Required files: main.py, db/migrations/001_create_users.py, models/user.py, tests/test_db.py
Rules: Maintain backward compatibility with migration. Update comments. Add logging."

Claude generates changes for all files. You review and apply. Result: Table renamed consistently across codebase in 15 minutes (vs. 2 hours manually).

Git Integration: Commit Messages & History

Claude Code understands git. Use this for intelligent commits.

Auto-commit with AI-generated messages:

claude commit "Refactor database layer: Rename users table to accounts"

Claude generates commit message and commits. Benefits:

• Message is descriptive and follows conventions
• Claude bundles related changes logically
• You maintain clean git history for future debugging

View git-aware recommendations:

claude run "Analyze git history. What were the 5 most common types of changes?
Show patterns that might indicate technical debt."

Claude analyzes commits, outputs:

Top Changes:
1. Bug fixes in payment processing (30% of commits)
2. Database schema adjustments (20% of commits)
3. Performance optimizations (15% of commits)
4. API endpoint additions (15% of commits)
5. Dependency updates (10% of commits)

Technical Debt Indicators:
- Payment module has 5 bug fixes in last 20 commits (fragile code)
- No tests for new endpoints (15% of endpoints untested)

Code Review: Multi-File Audits

Review entire project in one command:

claude review

Claude audits all files:

• Consistency (naming, style, patterns)
• Security (hardcoded secrets, unsafe operations)
• Performance (N+1 queries, inefficient loops)
• Architecture (tight coupling, missing abstraction)
• Tests (coverage, missing edge cases)

Output:

Code Review Summary:

CRITICAL:
- db/queries.py (line 45): Hardcoded password in connection string
- api/endpoints.py (line 12): SQL injection vulnerability in search endpoint

HIGH:
- models/user.py: Missing type hints (should be 95%+ covered)
- tests/test_db.py: Only 40% test coverage (target: 80%)

MEDIUM:
- main.py: Long function (150 lines), should split into 3 functions
- db/migrations/: Migration naming inconsistent

RECOMMENDATIONS:
1. Fix security issues immediately
2. Add type hints (improves IDE support and catches bugs)
3. Increase test coverage to 80%
4. Refactor long functions

Pakistan-Specific Multi-File Example

Pakistani developer Zainab is building a WhatsApp bot that:

• Connects to PostgreSQL (orders, customers)
• Integrates WATI API (WhatsApp messaging)
• Processes Stripe payments (diaspora) + JazzCash (local)
• Sends SMS notifications via Jazz

Structure:

whatsapp-bot/
├── main.py
├── db/
│   ├── models.py
│   └── queries.py
├── integrations/
│   ├── wati.py
│   ├── stripe.py
│   └── jazzcash.py
├── notifications/
│   └── sms.py
├── tests/
│   └── test_*.py
└── CLAUDE.md

Zainab's refactoring: Add support for Zong SMS (in addition to Jazz). Needs changes across:

• integrations/jazzcash.py (add Zong integration)
• notifications/sms.py (route SMS to Jazz or Zong based on price)
• db/models.py (add provider preference to customer model)
• tests/ (add Zong tests)

Command:

claude code "Add Zong SMS integration alongside Jazz SMS. Route to cheaper provider.
Files: integrations/jazzcash.py, notifications/sms.py, db/models.py, tests/test_notifications.py
Requirements: Maintain backwards compatibility with Jazz. Add configuration option."

Claude generates all changes. Zainab reviews, commits with AI-generated message: "feat: add Zong SMS provider for cheaper notifications in Pakistan". In 30 minutes, multi-file refactoring is complete and tested.

Codebase Understanding Depth

Claude Code builds understanding of your codebase:

claude memory show

After working on 10 files, memory includes:

• Architecture (main.py coordinates db → integrations → notifications)
• Key patterns (all integrations inherit from BaseIntegration)
• Business logic (route SMS to cheaper provider)
• Dependencies (db.models depends on nothing, integrations depend on config)

Next time you ask for changes, Claude understands context deeply. Result: Better suggestions, fewer bugs, coherent architecture.

Task 1: Multi-File Refactoring — Create a project with 5 files (can be simple). Use Claude Code to: (1) Understand file dependencies, (2) Rename a function across all files, (3) Review all files, (4) Commit changes with AI-generated message.

Task 2: Git-Aware Development — Clone an existing project (or create one with 10 commits). Use Claude to: (1) Analyze commit history patterns, (2) Identify technical debt from commits, (3) Recommend refactoring based on patterns.

Conclusion

Multi-file editing with Claude Code is a force multiplier. You can refactor large codebases in hours (vs. days). The git integration ensures clean history. Code reviews catch issues before they ship.

Master this skill, and you can architect large systems confidently, knowing Claude has your back for large-scale refactoring.