Code Alignment

Assess uncommitted code changes against the existing codebase to ensure consistency with established patterns, architecture, components, and ways of working.

When to use

• •Before committing new code
• •When adding new features or components
• •After refactoring to verify consistency
• •When onboarding and unsure if code follows project conventions

Instructions

Step 1: Gather uncommitted changes

First, identify what has changed:

git status
git diff --stat
git diff
git diff --cached  # for staged changes

Focus on:

• •New files being added
• •Modified files
• •The nature of changes (new component, utility, service, etc.)

Step 2: Understand the existing codebase

Before assessing, build context on existing patterns by exploring:

1. •Project structure: How are files and folders organized?
2. •Naming conventions: How are files, functions, variables, components named?
3. •Import patterns: How are dependencies imported and organized?
4. •Code organization: How is code structured within files?
5. •Existing utilities: What helpers, hooks, services already exist?
6. •Component patterns: How are similar components built?
7. •Error handling: How are errors handled throughout?
8. •Testing patterns: How are tests structured?

Use targeted exploration:

• •Look at sibling files in the same directory
• •Find similar existing implementations
• •Check for shared utilities that could be reused

Step 3: Assess alignment

Evaluate the uncommitted changes against these dimensions:

A. Code Style & Conventions

• •Naming conventions (files, functions, variables, classes)
• •Code formatting and structure
• •Comment style and documentation patterns
• •Import organization and grouping

B. Architectural Patterns

• •File placement (is it in the right directory?)
• •Module boundaries and responsibilities
• •Dependency direction (does it respect existing layers?)
• •Service/component granularity

C. Reuse Opportunities

• •Existing utilities that could replace custom code
• •Shared components that could be leveraged
• •Common patterns that should be followed
• •DRY violations (reimplementing existing functionality)

D. Consistency

• •Error handling approach
• •Logging patterns
• •State management conventions
• •API/data fetching patterns
• •Testing approach

Step 4: Generate report

Produce a structured report with these sections:

## Code Alignment Report

### Summary
[One paragraph overview: is the code well-aligned, partially aligned, or introducing foreign patterns?]

### Findings

#### Aligned Well
- [Things that match existing patterns]

#### Concerns
- [Pattern deviations with severity: minor/moderate/significant]
- [Include file:line references where relevant]

#### Reuse Opportunities
- [Existing utilities/components that could be leveraged]
- [Include paths to existing code]

#### Quick Wins
- [Simple changes that would improve alignment]
- [Mark with estimated effort: trivial/small/medium]

### Recommendations
[Prioritized list of suggested changes]

Step 5: Handle user commands

Default: Display report in chat

"Write to file": Write the report to a markdown file

# Suggest path like: .claude/reports/code-alignment-YYYY-MM-DD.md
# Or project-appropriate location

"Execute quick wins": Implement the trivial/small effort fixes automatically

• •Only execute changes marked as "trivial" or "small" effort
• •Show each change before making it
• •Skip anything that requires user judgment

Assessment criteria by category

File & Folder Patterns

• •Does the file live where similar files live?
• •Does the filename follow the same convention as peers?
• •Is the folder structure consistent with the project?

Naming Patterns

• •Variables: camelCase, snake_case, PascalCase - match the project
• •Functions: verb-first, descriptive, consistent with similar functions
• •Components: match existing component naming
• •Files: match adjacent file naming patterns

Code Structure Patterns

• •Function length and complexity (match existing norms)
• •Class vs functional approaches (match project preference)
• •Export patterns (default vs named, barrel files)
• •Code organization within files

Import Patterns

• •Grouping (stdlib, external, internal, relative)
• •Aliasing conventions
• •Barrel imports vs direct imports

Error Handling

• •Try/catch patterns
• •Error types and messages
• •Logging on errors
• •User-facing error handling

Testing Patterns

• •Test file location and naming
• •Test structure (describe/it, test functions)
• •Mocking approaches
• •Assertion styles

Example report

## Code Alignment Report

### Summary
The new `UserCard` component is mostly well-aligned but introduces a custom date formatting utility when the project already has `lib/utils/formatDate.ts`. Minor naming inconsistency in props interface.

### Findings

#### Aligned Well
- File location in `components/users/` follows existing pattern
- Component structure matches other card components
- Uses existing `Card` base component
- Error handling follows established pattern

#### Concerns
- **Moderate**: Custom `formatUserDate()` function duplicates `lib/utils/formatDate.ts`
- **Minor**: Props interface named `Props` instead of `UserCardProps` (project convention is `{Component}Props`)
- **Minor**: Import groups not separated by blank lines (see `components/users/UserList.tsx` for reference)

#### Reuse Opportunities
- `lib/utils/formatDate.ts` - use instead of custom date formatting
- `hooks/useUserData.ts` - could replace manual fetch logic
- `components/common/Avatar.tsx` - exists but not used

#### Quick Wins
- [trivial] Rename `Props` to `UserCardProps`
- [trivial] Add blank lines between import groups
- [small] Replace custom date formatting with `formatDate()`

### Recommendations
1. Replace custom `formatUserDate()` with existing `formatDate()` utility
2. Consider using `useUserData` hook for data fetching consistency
3. Rename props interface to follow `{Component}Props` convention

Best practices

1. •Be specific: Reference actual file paths and line numbers
2. •Prioritize: Not all inconsistencies are equal - highlight what matters
3. •Show examples: Point to existing code as reference
4. •Stay objective: Report facts, not opinions on code quality
5. •Consider context: New patterns might be intentional improvements
6. •Quick wins first: Identify easy alignment fixes separately from larger refactors

Limitations

• •Cannot assess runtime behavior or performance implications
• •May miss project-specific conventions not evident in code
• •Best used alongside human judgment, not as final arbiter
• •Large changesets may require focusing on most impactful files