Specification for file management in Claude Code

file-management-spec.md

File Management & Version Control Specification

Problem Statement

When working with Claude Code on web applications, a common issue occurs where Claude creates new files with updated logic but leaves old files with outdated logic intact. This leads to:

• Mixed old and new logic in the codebase
• Inconsistent application behavior
• Overcomplicated file structure
• Claude using outdated files as reference in subsequent changes

File Management Protocol

1. File Inventory Requirement

Before making any changes, Claude must:

1. List all existing files in the project structure
2. Identify files that will be affected by the requested changes
3. Explicitly state which files will be:
   • Modified (updated in place)
   • Replaced (completely rewritten)
   • Deleted (no longer needed)
   • Created (new files)

2. Change Documentation

For every modification request, create a change log entry:

## Change Log Entry: [Date] - [Feature/Fix Description]

### Files Affected:
- **Modified:** `src/components/UserProfile.js`
- **Replaced:** `src/utils/auth.js` → `src/services/authService.js`
- **Deleted:** `src/legacy/oldAuth.js`, `src/helpers/deprecatedUtils.js`
- **Created:** `src/hooks/useAuthentication.js`

### Logic Changes:
- Moved authentication logic from utils to services
- Updated component to use new auth service
- Removed deprecated helper functions

### Dependencies Updated:
- Updated imports in: `src/App.js`, `src/components/Login.js`

3. Explicit File Operations

Always explicitly state:

DELETING: src/old-file.js (reason: logic moved to new-service.js)
UPDATING: src/main-component.js (reason: integrate new authentication)
CREATING: src/services/auth-service.js (reason: centralize auth logic)

4. Reference File Maintenance

Create and maintain a docs/file-references.md:

# Current File Reference Map

## Authentication
- **Primary:** `src/services/authService.js`
- **Components using:** `src/components/Login.js`, `src/components/UserProfile.js`
- **Hooks:** `src/hooks/useAuthentication.js`
- **Deprecated:** ~~`src/utils/auth.js`~~ (replaced 2024-01-15)

## Data Management
- **Primary:** `src/services/dataService.js`
- **Types:** `src/types/apiTypes.ts`
- **Components using:** `src/components/DataTable.js`, `src/pages/Dashboard.js`

Last Updated: [Date]

Implementation Workflow

Phase 1: Pre-Change Analysis

1. Run find . -name "*.js" -o -name "*.jsx" -o -name "*.ts" -o -name "*.tsx" (or equivalent)
2. Identify all files related to the change request
3. Create change plan with explicit file operations

Phase 2: Execution

1. Delete obsolete files FIRST
2. Create new files
3. Update existing files
4. Update reference documentation

Phase 3: Verification

1. Update docs/file-references.md
2. Verify no imports reference deleted files
3. Test that application still functions

Commands for Claude Code

File Analysis Commands

# List all source files
find src -type f -name "*.js" -o -name "*.jsx" -o -name "*.ts" -o -name "*.tsx" | sort

# Find references to a specific function/import
grep -r "oldFunctionName" src/
grep -r "from './old-file'" src/

Cleanup Commands

# Remove unused imports (if using tools like ESLint)
npx eslint src/ --fix

# Find unused files (manual inspection required)
grep -r "import.*from.*fileName" src/

Integration with CLAUDE.md

Add this section to your project's CLAUDE.md:

## File Management Protocol

**CRITICAL:** Before making changes, read and follow `docs/file-management-spec.md`

### Quick Reference:
1. **Always list affected files** before making changes
2. **Explicitly delete outdated files** - don't leave them hanging
3. **Update `docs/file-references.md`** after every significant change
4. **State file operations clearly:** "DELETING X", "CREATING Y", "UPDATING Z"

### Current File Structure:
[Link to or embed current file-references.md content]

Memory Integration with Selena MCP

If Selena MCP is available, create these memory entries:

{
  "project_rule": "Always check and update file-references.md before making changes",
  "file_operations": "Explicitly state DELETE/CREATE/UPDATE for every change",
  "cleanup_protocol": "Remove old files when creating new implementations",
  "reference_doc": "docs/file-references.md contains current file mapping"
}

Workflow Checklist

Before every change request:

• List all files that will be affected
• Identify files to DELETE (old implementations)
• Identify files to CREATE (new implementations)
• Identify files to UPDATE (modified implementations)
• Update docs/file-references.md after changes
• Verify no broken imports remain

Example Implementation

When asked to "refactor authentication to use modern hooks":

1. Analysis:

   Current auth files:
   - src/utils/auth.js (OLD - will delete)
   - src/components/Login.js (UPDATE - change imports)
   - src/components/UserProfile.js (UPDATE - change imports)
   
   New structure:
   - src/hooks/useAuth.js (CREATE - modern hook)
   - src/services/authService.js (CREATE - API calls)
   

2. Execution:

   • DELETE src/utils/auth.js
   • CREATE src/hooks/useAuth.js
   • CREATE src/services/authService.js
   • UPDATE src/components/Login.js
   • UPDATE src/components/UserProfile.js

3. Documentation:

   • Update docs/file-references.md
   • Add change log entry

This protocol ensures no outdated files remain to confuse future development cycles.