DEV Community: Alex Rogov

How to Structure a TypeScript Project So AI Agents Can Navigate It

Alex Rogov — Sun, 05 Apr 2026 18:49:29 +0000

Your AI coding assistant is only as good as the codebase it navigates. I've watched Claude Code, Cursor, and Copilot struggle with the same project structures that trip up junior developers — and excel in codebases designed with clear boundaries.

After restructuring 8 TypeScript projects specifically to work better with AI agents, here's what actually moves the needle.

Why Project Structure Matters More Now

When you ask an AI agent to "add a new endpoint for user notifications," it needs to:

Find where endpoints live
Understand the existing patterns
Locate related code (models, services, types)
Follow the conventions already established

In a well-structured project, the agent finds all of this in seconds. In a messy one, it hallucinates paths, invents patterns that don't match your codebase, and produces code you'll spend 20 minutes fixing.

The difference isn't the AI model — it's the signal-to-noise ratio in your file tree.

The Structure That Works

Here's the folder structure I use across all my TypeScript projects (NestJS, Next.js, Express):

src/
├── domain/                    # Pure business logic, zero dependencies
│   ├── user/
│   │   ├── user.entity.ts
│   │   ├── user.value-objects.ts
│   │   └── user.errors.ts
│   └── order/
│       ├── order.entity.ts
│       └── order.errors.ts
├── application/               # Use cases + port interfaces
│   ├── user/
│   │   ├── use-cases/
│   │   │   ├── create-user.ts
│   │   │   └── update-user.ts
│   │   └── ports/
│   │       ├── user.repository.ts
│   │       └── email.port.ts
│   └── order/
│       ├── use-cases/
│       └── ports/
├── infrastructure/            # Framework + external implementations
│   ├── database/
│   │   ├── prisma-user.repository.ts
│   │   └── prisma-order.repository.ts
│   ├── http/
│   │   ├── controllers/
│   │   │   ├── user.controller.ts
│   │   │   └── order.controller.ts
│   │   ├── middleware/
│   │   └── dto/
│   │       ├── create-user.dto.ts
│   │       └── update-user.dto.ts
│   └── external/
│       ├── email.service.ts
│       └── payment.gateway.ts
├── shared/                    # Cross-cutting utilities
│   ├── types/
│   ├── utils/
│   └── constants/
└── CLAUDE.md                  # AI agent instructions

Why this works for AI agents: every folder name is a clear signal. When the agent sees application/user/use-cases/, it knows exactly what goes there — and more importantly, what doesn't.

Rule 1: One Concept Per File

This is the single biggest improvement you can make for AI navigation.

// ❌ BAD: user.types.ts — 200 lines of mixed concerns
export interface User { ... }
export interface UserProfile { ... }
export interface CreateUserDto { ... }
export interface UpdateUserDto { ... }
export type UserRole = 'admin' | 'editor' | 'viewer';
export type UserPermission = 'read' | 'write' | 'delete';
export interface UserFilters { ... }
export interface PaginatedUsers { ... }

// ✅ GOOD: split by concept
// domain/user/user.entity.ts
export interface User {
  id: string;
  email: string;
  role: UserRole;
  profile: UserProfile | null;
  createdAt: Date;
}

export type UserRole = 'admin' | 'editor' | 'viewer';

// domain/user/user-profile.entity.ts
export interface UserProfile {
  displayName: string;
  avatarUrl: string | null;
  bio: string;
}

// infrastructure/http/dto/create-user.dto.ts
export class CreateUserDto {
  @IsEmail()
  email: string;

  @MinLength(8)
  password: string;

  @IsOptional()
  displayName?: string;
}

When an AI agent searches for "User entity," it finds user.entity.ts — not a 200-line grab bag where it has to parse which interface is the domain entity vs. the DTO vs. the filter type.

Rule 2: Predictable Naming Conventions

AI agents learn patterns from your existing files. If your naming is consistent, the agent extrapolates correctly. If it's inconsistent, every new file is a coin flip.

✅ Consistent pattern:
  create-user.ts        → CreateUser class
  update-user.ts        → UpdateUser class
  delete-user.ts        → DeleteUser class
  create-order.ts       → CreateOrder class

❌ Inconsistent naming:
  createUser.ts         → CreateUserUseCase class
  update_user.ts        → UpdateUser class
  deleteUserHandler.ts  → UserDeleteHandler class
  newOrder.ts           → OrderCreation class

My naming rules (defined in CLAUDE.md):

Files: kebab-case, suffix indicates type — .entity.ts, .repository.ts, .controller.ts, .dto.ts, .port.ts
Classes: PascalCase, no suffix redundancy — CreateUser not CreateUserUseCase
Interfaces: PascalCase, prefix with purpose — UserRepository, EmailPort
Test files: same name + .spec.ts — create-user.spec.ts

Rule 3: Explicit Dependency Direction

This is where most projects fall apart for AI agents. When imports go in every direction, the agent can't predict where to add new code.

// ❌ Infrastructure importing from other infrastructure
// infrastructure/database/prisma-user.repository.ts
import { EmailService } from '../external/email.service';  // Wrong layer!
import { UserController } from '../http/controllers/user.controller';  // Circular!

// ✅ Clean dependency direction: domain ← application ← infrastructure
// infrastructure/database/prisma-user.repository.ts
import { User } from '../../domain/user/user.entity';
import { UserRepository } from '../../application/user/ports/user.repository';

The rule is simple: imports only point inward. Infrastructure → Application → Domain. Never the reverse.

I enforce this with a simple TypeScript path alias in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@domain/*": ["src/domain/*"],
      "@application/*": ["src/application/*"],
      "@infrastructure/*": ["src/infrastructure/*"],
      "@shared/*": ["src/shared/*"]
    }
  }
}

When the AI sees @domain/user/user.entity, it immediately knows the layer. No ambiguous relative paths like ../../../models/user.

Rule 4: CLAUDE.md at the Root

Every project gets a CLAUDE.md that tells the agent how to navigate:

## Project Structure
- `src/domain/` — pure entities, value objects, domain errors. ZERO external imports.
- `src/application/` — use cases and port interfaces. Only imports from domain.
- `src/infrastructure/` — framework code, DB, HTTP, external services.
- `src/shared/` — cross-cutting utilities used by all layers.

## Conventions
- One class/interface per file
- File names: kebab-case with type suffix (.entity.ts, .repository.ts)
- Use cases: one per file in `application/{module}/use-cases/`
- New endpoint = controller method + DTO + use case + port (if needed)

## Adding a New Feature
1. Define entity in `domain/{module}/`
2. Create use case in `application/{module}/use-cases/`
3. Define ports in `application/{module}/ports/`
4. Implement infrastructure in `infrastructure/`
5. Wire up in module file
6. Run `npm run typecheck && npm run test`

This isn't just documentation — it's a navigation map. The AI reads this first and knows exactly where to put new code, what patterns to follow, and what commands to run for verification.

Rule 5: Kill Barrel Exports

This one surprised me. Barrel exports (index.ts files that re-export everything) actually hurt AI agent performance:

// ❌ src/domain/user/index.ts
export * from './user.entity';
export * from './user-profile.entity';
export * from './user.errors';
export * from './user.value-objects';

The problem: when the AI encounters import { User } from '@domain/user', it doesn't know which file contains User. It has to open the barrel, scan all re-exports, then find the source file. With large barrels (20+ exports), the agent frequently picks the wrong source when it needs to modify the definition.

// ✅ Direct imports — AI knows exactly where to look
import { User } from '@domain/user/user.entity';
import { UserNotFoundError } from '@domain/user/user.errors';

Direct imports are longer, but they're unambiguous. The AI can jump straight to the right file. The trade-off is worth it.

Rule 6: Co-locate Tests

❌ Separate test directory:
src/
  application/user/use-cases/create-user.ts
tests/
  unit/
    application/
      user/
        use-cases/
          create-user.spec.ts    ← 5 directories deep, mirrors src

✅ Co-located tests:
src/
  application/user/use-cases/
    create-user.ts
    create-user.spec.ts          ← right next to the source

When the AI modifies create-user.ts, it naturally finds create-user.spec.ts in the same directory. No searching through a mirrored test tree. It updates both files in one pass.

The Proof: Before vs After

I restructured a 40K-line NestJS project using these rules. Here's what changed in my AI-assisted workflow:

Metric	Before (flat structure)	After (layered + conventions)
AI finds correct file on first try	~60%	~95%
Generated code follows project patterns	~40%	~85%
"Fix the imports" follow-up prompts	3-4 per feature	0-1 per feature
Time from prompt to working code	8-12 min	2-4 min

The biggest win wasn't any single rule — it was the combination. When naming is predictable AND dependencies flow one direction AND CLAUDE.md explains the patterns, the AI connects the dots.

What This Doesn't Solve

To be clear: structure alone doesn't make AI write correct business logic. It still:

Misses edge cases in your domain rules
Oversimplifies error handling (as I covered in my previous article)
Doesn't understand your specific performance requirements
Can't infer undocumented business constraints

Structure makes the AI a better navigator. Your job is still being the architect.

Key Takeaways

One concept per file — the single biggest improvement for AI navigation
Predictable naming — consistent conventions let AI extrapolate patterns correctly
Explicit dependency direction — imports only point inward (infrastructure → application → domain)
CLAUDE.md at the root — a navigation map the AI reads first before touching any code
Kill barrel exports — direct imports give AI unambiguous file locations
Co-locate tests — the AI updates source and tests in one pass

Your codebase is the AI's context window. Make it scannable, predictable, and unambiguous — and the AI goes from "occasionally useful" to "consistently reliable."

More practical guides on AI-augmented architecture on Twitter/X. Connect on LinkedIn for the discussion.

Originally published on my Hashnode blog.

AI Didn't Replace the Architecture Decisions — It Eliminated the Tax

Alex Rogov — Thu, 26 Mar 2026 07:18:49 +0000

Last month I refactored a legacy NestJS service layer — 47 files, 15,000 lines of code tangled with circular dependencies, god services, and business logic buried inside controllers.

The old me would have blocked out 3+ hours, put on headphones, and ground through it file by file. Instead, I finished in 20 minutes. Not because AI wrote the code for me — but because it eliminated the tax I used to pay just to execute decisions I'd already made.

Here's the workflow, the real before/after code, and where AI actually helps versus where it absolutely doesn't.

The Refactoring That Needed to Happen

The codebase was a 2-year-old NestJS monolith. Classic symptoms:

God services: UserService had 1,200 lines and handled everything from auth to email to reporting
Circular dependencies: OrderService imported UserService which imported NotificationService which imported OrderService
No layer separation: Controllers contained business logic, repositories leaked into route handlers, and Prisma models appeared everywhere
Zero interfaces: Everything was concrete. Swapping an implementation meant touching 30+ files

The architecture decision was straightforward — extract domain logic into proper layers following Clean Architecture. I'd made that decision in my head in 5 minutes. But executing it? That's where the hours disappeared.

Mapping dependencies. Finding every import chain. Extracting interfaces. Moving files. Updating imports. Running tests after each step. This is the tax — the mechanical, repetitive work that sits between the architectural decision and its implementation.

The 4-Step AI-Assisted Workflow

Step 1: Map the Blast Radius

Before touching any code, I need to understand what I'm dealing with. This is where AI saves the most time.

## CLAUDE.md context for this refactoring

### Current Task
Refactoring UserService (src/services/user.service.ts) — extract into:
- src/domain/user/ (entities, value objects)
- src/application/user/ (use cases, ports)
- src/infrastructure/user/ (repository implementations)

### Rules
- Do NOT change any public API signatures
- Do NOT modify controller routes
- Every extracted file must have an interface in application layer
- Run `npm run typecheck` after each file move

Then I ask Claude to analyze the dependency graph:

Show me every file that imports from UserService,
and every file that UserService imports from.
Group them by layer: controller, service, repository, utility.

What AI gives me in 30 seconds that would take 15-20 minutes manually:

UserService is imported by:
  Controllers (4): UserController, AuthController, AdminController, ReportController
  Services (3): OrderService, NotificationService, AnalyticsService
  Tests (2): user.service.spec.ts, auth.service.spec.ts

UserService imports from:
  Repositories (2): PrismaService, RedisService
  Services (2): EmailService, NotificationService (⚠️ circular!)
  Utils (3): hash.util, date.util, validation.util
  External (1): @nestjs/jwt

That circular dependency between UserService and NotificationService? I might have caught it eventually, but AI flagged it in the first pass. That alone saved me from a 30-minute debugging session later.

Step 2: Generate the Migration Plan

This is the critical step where AI shines — but only if you've defined the target architecture clearly.

Based on the dependency analysis, generate a step-by-step migration plan.
Rules:
1. Extract leaf dependencies first (no internal imports)
2. One file per step
3. After each step: npm run typecheck must pass
4. Never break the public API

AI produces something like:

Step 1: Extract User entity → src/domain/user/user.entity.ts
Step 2: Extract UserRepository interface → src/application/user/ports/user.repository.ts
Step 3: Extract CreateUser use case → src/application/user/use-cases/create-user.ts
Step 4: Extract UpdateUser use case → src/application/user/use-cases/update-user.ts
Step 5: Move Prisma implementation → src/infrastructure/user/prisma-user.repository.ts
Step 6: Break circular dep — extract NotificationPort interface
Step 7: Wire up dependency injection in user.module.ts
Step 8: Update controller imports
Step 9: Delete old UserService, update barrel exports

Key insight: I don't blindly follow this plan. I review each step, reorder when needed, and sometimes merge steps. The AI gives me a draft — I give it architectural judgment.

Step 3: Execute in Small Batches

This is where most people misuse AI. They ask it to "refactor the entire service" in one shot. That's a recipe for a broken codebase and a 200-line diff you can't review.

Instead, I execute one step at a time:

Execute Step 1: Extract User entity.
Move the User interface and related types from UserService to src/domain/user/user.entity.ts.
Update all imports. Run typecheck.

Before (buried inside user.service.ts):

// src/services/user.service.ts — 1,200 lines of everything

interface User {
  id: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer';
  profile: UserProfile | null;
  createdAt: Date;
}

interface UserProfile {
  displayName: string;
  avatarUrl: string | null;
}

@Injectable()
export class UserService {
  constructor(
    private prisma: PrismaService,
    private redis: RedisService,
    private email: EmailService,
    private notification: NotificationService,
    private jwt: JwtService,
  ) {}

  async findById(id: string): Promise<User | null> {
    const cached = await this.redis.get(`user:${id}`);
    if (cached) return JSON.parse(cached);

    const user = await this.prisma.user.findUnique({
      where: { id },
      include: { profile: true },
    });

    if (user) {
      await this.redis.set(`user:${id}`, JSON.stringify(user), 'EX', 3600);
    }

    return user;
  }

  async createUser(data: CreateUserDto): Promise<User> {
    const hashedPassword = await hash(data.password, 12);
    const user = await this.prisma.user.create({
      data: { ...data, password: hashedPassword },
    });

    await this.email.sendWelcome(user.email, user.profile?.displayName);
    await this.notification.notifyAdmins('new-user', { userId: user.id });

    return user;
  }

  // ... 1,100 more lines: updateUser, deleteUser, findByEmail,
  // generateToken, verifyToken, resetPassword, updateProfile,
  // getActivityLog, exportUserData, handleGDPRDeletion...
}

After (Step 1-6 completed — clean layers):

// src/domain/user/user.entity.ts — pure domain, zero dependencies
export interface User {
  id: string;
  email: string;
  role: UserRole;
  profile: UserProfile | null;
  createdAt: Date;
}

export type UserRole = 'admin' | 'editor' | 'viewer';

export interface UserProfile {
  displayName: string;
  avatarUrl: string | null;
}

// src/application/user/ports/user.repository.ts — interface only
export interface UserRepository {
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  create(data: CreateUserInput): Promise<User>;
  update(id: string, data: UpdateUserInput): Promise<User>;
  delete(id: string): Promise<void>;
}

// src/application/user/use-cases/create-user.ts — one use case, one file
import { User } from '../../domain/user/user.entity';
import { UserRepository } from '../ports/user.repository';
import { NotificationPort } from '../ports/notification.port';
import { EmailPort } from '../ports/email.port';
import { PasswordHasher } from '../ports/password-hasher.port';

export class CreateUser {
  constructor(
    private readonly users: UserRepository,
    private readonly email: EmailPort,
    private readonly notifications: NotificationPort,
    private readonly hasher: PasswordHasher,
  ) {}

  async execute(input: CreateUserInput): Promise<User> {
    const hashedPassword = await this.hasher.hash(input.password);

    const user = await this.users.create({
      ...input,
      password: hashedPassword,
    });

    await this.email.sendWelcome(user.email, user.profile?.displayName);
    await this.notifications.notifyAdmins('new-user', { userId: user.id });

    return user;
  }
}

// src/infrastructure/user/prisma-user.repository.ts — implementation
import { Injectable } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { RedisService } from '../redis/redis.service';
import { UserRepository } from '../../application/user/ports/user.repository';
import { User } from '../../domain/user/user.entity';

@Injectable()
export class PrismaUserRepository implements UserRepository {
  constructor(
    private readonly prisma: PrismaService,
    private readonly redis: RedisService,
  ) {}

  async findById(id: string): Promise<User | null> {
    const cached = await this.redis.get(`user:${id}`);
    if (cached) return JSON.parse(cached);

    const user = await this.prisma.user.findUnique({
      where: { id },
      include: { profile: true },
    });

    if (user) {
      await this.redis.set(`user:${id}`, JSON.stringify(user), 'EX', 3600);
    }

    return user;
  }

  // ... other methods
}

The god service is gone. Each piece has one job, one file, clear dependencies. And the circular dependency? Gone — replaced by a NotificationPort interface in the application layer.

Step 4: Catch What AI Misses

Here's where architectural experience matters. After AI executes the mechanical work, I review for things it consistently gets wrong:

1. Naming consistency. AI might call it UserRepo in one file and UserRepository in another. I enforce naming conventions from my CLAUDE.md.

2. Error handling patterns. AI defaults to throwing generic errors. I replace them with domain-specific error types:

// AI generated this:
if (!user) throw new Error('User not found');

// I change it to this:
if (!user) throw new UserNotFoundError(id);

3. Transaction boundaries. AI doesn't understand your specific transaction requirements. When createUser needs to be atomic (user creation + welcome email + admin notification), I verify the transaction scope is correct.

4. Test coverage gaps. AI updates existing tests but rarely writes new ones for extracted interfaces. I add integration tests for the new repository implementations.

The Numbers

For this specific refactoring (47 files, ~15,000 lines):

Step	Without AI	With AI	Time Saved
Dependency mapping	15-20 min	30 sec	~97%
Migration planning	20-30 min	2 min	~92%
Mechanical execution	90-120 min	12 min	~88%
Review & corrections	15 min	8 min	~47%
Total	~3 hours	~23 min	~87%

Notice the pattern: AI saves the most time on mechanical, repetitive tasks (mapping, executing). It saves the least on judgment-heavy tasks (review, corrections). This is not a coincidence — it's the fundamental nature of where AI helps.

Where AI Does NOT Help

Let me be clear about what AI cannot do in this workflow:

1. Make the architecture decision. Choosing Clean Architecture over hexagonal, or deciding to extract services versus merge them — that's your job. AI doesn't understand your team's context, your deployment constraints, or your product roadmap.

2. Understand production constraints. The refactoring can't break the API. Existing clients depend on specific response shapes. Migration must be zero-downtime. AI doesn't weigh these trade-offs — you do.

3. Evaluate long-term maintainability. AI optimizes for "compiles and passes tests." It doesn't ask: "Will a new developer understand this in 6 months?" That question requires experience and judgment.

4. Handle the politics. Half of architecture is convincing your team it's the right move. AI can't attend your design review or explain why the refactoring is worth the sprint allocation.

The Mental Model

Think of AI as a force multiplier for execution, not for decision-making.

Architecture Workflow:
  1. Analyze (AI helps: fast, thorough)
  2. Decide (YOU: experience, judgment, context)
  3. Plan (AI helps: generates options, you pick)
  4. Execute (AI helps: 10x faster mechanical work)
  5. Verify (BOTH: AI runs checks, you review intent)

The engineers who get the most from AI aren't the ones who delegate thinking to it. They're the ones who've done enough refactorings to know what good looks like — and use AI to get there faster.

AI didn't replace my architecture decisions. It eliminated the tax I paid to execute them.

Key Takeaways

AI eliminates the execution tax — the mechanical, repetitive work between making an architectural decision and implementing it
Map the blast radius first — dependency analysis is where AI saves the most time (~97%)
Execute in small batches — one step at a time, typecheck after each. Never ask AI to refactor everything at once
Review for what AI misses — naming consistency, error handling patterns, transaction boundaries, and test gaps
The decision is still yours — AI is a force multiplier for execution, not a replacement for architectural judgment

I share daily insights on AI-augmented architecture on Twitter/X. Connect on LinkedIn — this article started as a LinkedIn post and your comments shaped it.

Originally published on my Hashnode blog. Follow me for more AI + Architecture content.

5 Custom Hooks I Copy to Every React Project

Alex Rogov — Sat, 21 Mar 2026 09:16:10 +0000

Every time I start a new React project, I copy the same 5 hooks. Not from a library — from my own collection, battle-tested across 15+ production apps.

These aren't clever abstractions. They're boring, reliable utilities that eliminate the same bugs I've fixed dozens of times. Senior engineers don't write more code. They carry better defaults.

Here are the 5, with full TypeScript implementations you can copy today.

1. useDebounce — Stop Hammering Your API

The most common performance bug in React: firing an API call on every keystroke. Search inputs, autocomplete fields, filter forms — they all need debouncing.

import { useState, useEffect } from 'react';

function useDebounce<T>(value: T, delay: number = 300): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);

  useEffect(() => {
    const timer = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => {
      clearTimeout(timer);
    };
  }, [value, delay]);

  return debouncedValue;
}

Usage:

function SearchBar() {
  const [query, setQuery] = useState('');
  const debouncedQuery = useDebounce(query, 300);

  useEffect(() => {
    if (debouncedQuery) {
      searchAPI(debouncedQuery);
    }
  }, [debouncedQuery]);

  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

Why not use lodash.debounce? Because lodash.debounce returns a function, which means you need useCallback + useRef to use it correctly in React. This hook works with React's mental model — it debounces a value, not a function. The component re-renders only when the debounced value actually changes.

Production tip: I use 300ms for search inputs, 500ms for auto-save, and 150ms for filter dropdowns. These aren't magic numbers — they're the result of user testing across multiple products.

2. usePrevious — Know Where You Came From

React doesn't give you a built-in way to access the previous value of a prop or state. But you need it constantly — for animations, comparison logic, and tracking changes.

import { useRef, useEffect } from 'react';

function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T | undefined>(undefined);

  useEffect(() => {
    ref.current = value;
  }, [value]);

  return ref.current;
}

Usage:

function PriceDisplay({ price }: { price: number }) {
  const previousPrice = usePrevious(price);

  const direction = previousPrice !== undefined
    ? price > previousPrice ? 'up' : price < previousPrice ? 'down' : 'same'
    : 'same';

  return (
    <span className={`price price--${direction}`}>
      ${price.toFixed(2)}
      {direction === 'up' && ' ↑'}
      {direction === 'down' && ' ↓'}
    </span>
  );
}

Why a ref and not state? Setting state would cause a re-render, which would update the "previous" value, which would cause another re-render — infinite loop. useRef updates synchronously without triggering re-renders.

Real-world use cases: I use this for price change animations (stocks, crypto), step-by-step form navigation (tracking which step the user came from), and undo functionality (storing the last N values with a small wrapper).

3. useLocalStorage — State That Survives Refresh

useState resets on page refresh. For user preferences, form drafts, and dark mode — you need persistence. But raw localStorage in React is full of pitfalls: SSR crashes, serialization bugs, tab sync issues.

import { useState, useEffect, useCallback } from 'react';

function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((prev: T) => T)) => void, () => void] {
  const [storedValue, setStoredValue] = useState<T>(() => {
    if (typeof window === 'undefined') return initialValue;
    try {
      const item = window.localStorage.getItem(key);
      return item ? (JSON.parse(item) as T) : initialValue;
    } catch {
      return initialValue;
    }
  });

  useEffect(() => {
    if (typeof window === 'undefined') return;
    try {
      window.localStorage.setItem(key, JSON.stringify(storedValue));
    } catch {
      console.warn(`Failed to save "${key}" to localStorage`);
    }
  }, [key, storedValue]);

  const remove = useCallback(() => {
    setStoredValue(initialValue);
    if (typeof window !== 'undefined') {
      window.localStorage.removeItem(key);
    }
  }, [key, initialValue]);

  return [storedValue, setStoredValue, remove];
}

Usage:

function Settings() {
  const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('theme', 'light');
  const [fontSize, setFontSize, resetFontSize] = useLocalStorage('fontSize', 16);

  return (
    <div>
      <button onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}>
        {theme === 'light' ? '🌙' : '☀️'}
      </button>
      <input
        type="range"
        min={12}
        max={24}
        value={fontSize}
        onChange={(e) => setFontSize(Number(e.target.value))}
      />
      <button onClick={resetFontSize}>Reset</button>
    </div>
  );
}

Three things most implementations get wrong:

SSR crashes. localStorage doesn't exist on the server. The typeof window === 'undefined' check is mandatory for Next.js and any SSR framework.
No error handling. localStorage can throw — when storage is full, when the browser blocks it (private mode in some browsers), or when the value can't be serialized. Always wrap in try-catch.
No removal. The remove function resets to initialValue AND clears the key from storage. Without it, you end up with stale data that the user can't clear.

Important note for EU/GDPR: localStorage falls under the same regulations as cookies. In production, I always wrap this hook with a consent check — only read/write after the user accepts storage preferences.

4. useMediaQuery — Responsive Logic Without CSS

CSS handles responsive styles. But sometimes you need responsive logic: different components, different data fetching strategies, different interaction patterns based on screen size.

import { useState, useEffect } from 'react';

function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState<boolean>(() => {
    if (typeof window === 'undefined') return false;
    return window.matchMedia(query).matches;
  });

  useEffect(() => {
    if (typeof window === 'undefined') return;

    const mediaQuery = window.matchMedia(query);
    setMatches(mediaQuery.matches);

    const handler = (event: MediaQueryListEvent) => {
      setMatches(event.matches);
    };

    mediaQuery.addEventListener('change', handler);
    return () => mediaQuery.removeEventListener('change', handler);
  }, [query]);

  return matches;
}

Usage:

function Dashboard() {
  const isMobile = useMediaQuery('(max-width: 768px)');
  const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');

  return (
    <div>
      {isMobile ? <MobileNav /> : <DesktopSidebar />}
      <Chart animated={!prefersReducedMotion} />
    </div>
  );
}

Why not just use CSS? Three real scenarios where I need this hook:

Conditional rendering. Mobile shows a bottom sheet; desktop shows a sidebar. These are different components, not different styles.
Different data loading. On mobile, load 10 items per page. On desktop, load 25. This is logic, not layout.
Accessibility queries. prefers-reduced-motion and prefers-color-scheme affect behavior, not just styles. Should I autoplay this animation? Depends on the user's OS setting.

Pro tip: Create named breakpoints as constants instead of repeating magic strings:

const breakpoints = {
  mobile: '(max-width: 768px)',
  tablet: '(min-width: 769px) and (max-width: 1024px)',
  desktop: '(min-width: 1025px)',
  reducedMotion: '(prefers-reduced-motion: reduce)',
  darkMode: '(prefers-color-scheme: dark)',
} as const;

// Usage: const isMobile = useMediaQuery(breakpoints.mobile);

5. useAbortController — Cancel Requests on Unmount

The most underrated hook. Every fetch call inside a useEffect should be abortable. Without it, you get state updates on unmounted components, race conditions on fast navigation, and memory leaks.

import { useRef, useEffect, useCallback } from 'react';

function useAbortController() {
  const controllerRef = useRef<AbortController | null>(null);

  const getSignal = useCallback(() => {
    if (controllerRef.current) {
      controllerRef.current.abort();
    }
    controllerRef.current = new AbortController();
    return controllerRef.current.signal;
  }, []);

  useEffect(() => {
    return () => {
      controllerRef.current?.abort();
    };
  }, []);

  return { getSignal };
}

Usage:

function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);
  const { getSignal } = useAbortController();

  useEffect(() => {
    const signal = getSignal();

    fetch(`/api/users/${userId}`, { signal })
      .then(res => res.json())
      .then(data => setUser(data))
      .catch(err => {
        if (err.name !== 'AbortError') {
          console.error('Failed to fetch user:', err);
        }
      });
  }, [userId, getSignal]);

  return user ? <div>{user.name}</div> : <div>Loading...</div>;
}

What getSignal() does:

Aborts any in-flight request from the previous call
Creates a fresh AbortController
Returns the new signal

This handles both unmount (cleanup effect aborts) and dependency changes (new call aborts the previous one). No race conditions. No stale data.

Why not just create the controller inside useEffect? You can, but then every effect needs its own abort boilerplate. This hook centralizes the pattern and makes it one line: const signal = getSignal().

Real scenario this prevents: User clicks through a list fast — clicks user 1, user 2, user 3. Without abort, all three requests are in flight. If request 1 returns last (network timing), user 3's profile shows user 1's data. Classic race condition that's invisible in dev but breaks production.

Bonus: How I Organize These

I keep these hooks in a /hooks directory with barrel exports:

src/
└── hooks/
    ├── useDebounce.ts
    ├── usePrevious.ts
    ├── useLocalStorage.ts
    ├── useMediaQuery.ts
    ├── useAbortController.ts
    └── index.ts

Each hook has its own file. The index.ts re-exports everything. When I start a new project, I literally copy this folder.

No npm package. No dependencies. No versioning headaches. Just 5 files, ~150 lines total, zero external dependencies.

Key Takeaways

useDebounce — debounce values, not functions. Works naturally with React's render model.
usePrevious — use useRef to avoid infinite re-render loops. Essential for animations and change tracking.
useLocalStorage — handle SSR, errors, and removal. Don't forget GDPR compliance.
useMediaQuery — responsive logic for conditional rendering, data loading, and accessibility.
useAbortController — prevent race conditions and memory leaks. Every fetch needs an abort signal.

These aren't exciting. They're not clever. They're just the boring infrastructure that prevents the same 5 bugs in every project. Copy them, adapt them, and move on to the interesting problems.

I share daily tips on React, TypeScript, and AI-augmented development on Twitter/X. Let's connect on LinkedIn — this post started there and your comments made it better.

Originally published on my Hashnode blog. Follow me for more AI + Architecture content.

How We Migrated 200K Lines from JS to Strict TypeScript

Alex Rogov — Sat, 21 Mar 2026 09:15:51 +0000

We didn't mass-rename .js files to .ts and call it a day. We migrated 200,000 lines of production JavaScript to strict TypeScript — with zero downtime, over 4 months, while shipping features every sprint.

Here's the playbook that actually worked.

Why We Almost Didn't Do It

The codebase was 6 years old. A Node.js monolith serving 50K daily active users, built by 12+ developers over the years. Some files had JSDoc types. Most had // @ts-ignore comments from a half-hearted migration attempt in 2021.

The business case was clear: we were spending 30% of every sprint debugging type-related bugs that TypeScript would have caught at compile time. Null reference errors in production. API responses with unexpected shapes. Refactoring was terrifying because nobody knew what would break.

But a big-bang migration was off the table. We couldn't freeze features for 4 months. So we built a system.

The 5-Phase Strategy

Phase 1: Set Up the Dual Runtime (Week 1)

The first step wasn't touching any JavaScript file. It was making TypeScript and JavaScript coexist peacefully.

// tsconfig.json — the migration config
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "strict": false,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Key decisions:

allowJs: true — JS and TS files live together
strict: false — we'll tighten this incrementally
checkJs: false — don't type-check existing JS (yet)

We also added a CI step that ran tsc --noEmit on every PR. At this point it checked nothing, but the infrastructure was in place.

Phase 2: Define the Boundary Types (Weeks 2-3)

Before converting any file, we typed the boundaries: API responses, database models, and shared interfaces.

// src/types/api.ts — typed API contracts
interface User {
  id: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer';
  createdAt: Date;
  profile: UserProfile | null;
}

interface UserProfile {
  displayName: string;
  avatarUrl: string | null;
  bio: string;
}

interface ApiResponse<T> {
  data: T;
  meta: {
    total: number;
    page: number;
    perPage: number;
  };
}

// src/types/database.ts — Prisma-generated types were our source of truth
// But we created domain interfaces that didn't depend on Prisma
interface UserRepository {
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  create(data: CreateUserInput): Promise<User>;
  update(id: string, data: UpdateUserInput): Promise<User>;
}

Why this matters: Once the boundary types existed, every converted file had something to reference. The types flowed inward — from the edges of the system toward the core.

Phase 3: The Module-by-Module Conversion (Weeks 4-14)

This is where the real work happened. We established rules:

Rule 1: Convert leaf modules first.
Start with files that have no internal imports — utilities, helpers, validators. They're self-contained, so you can convert them without touching anything else.

// Before: src/utils/format-date.js
function formatDate(date, format) {
  // 47 lines of date formatting
  // 3 bug reports in the last year from null dates
}

// After: src/utils/format-date.ts
type DateFormat = 'short' | 'long' | 'iso' | 'relative';

function formatDate(date: Date | string | null, format: DateFormat = 'short'): string {
  if (!date) return '—';
  const parsed = typeof date === 'string' ? new Date(date) : date;
  if (isNaN(parsed.getTime())) return 'Invalid date';
  // Same 47 lines, but now with type safety
}

Rule 2: One module per PR. Never mix migration with feature work.

This was non-negotiable. Every migration PR was purely mechanical: rename .js → .ts, add types, fix errors. No refactoring. No improvements. Just types.

Why? Because migration PRs should be boring. The reviewer should be able to approve them in 5 minutes by confirming that behavior didn't change.

Rule 3: Track progress with a migration scorecard.

# migration-stats.sh — we ran this weekly
echo "=== Migration Progress ==="
JS_COUNT=$(find src -name "*.js" -not -path "*/node_modules/*" | wc -l)
TS_COUNT=$(find src -name "*.ts" -o -name "*.tsx" | wc -l)
TOTAL=$((JS_COUNT + TS_COUNT))
PCT=$((TS_COUNT * 100 / TOTAL))
echo "JS files: $JS_COUNT"
echo "TS files: $TS_COUNT"
echo "Progress: $PCT%"
echo ""
echo "=== Strict Mode Violations ==="
npx tsc --noEmit --strict 2>&1 | grep "error TS" | sed 's/(.*//' | sort | uniq -c | sort -rn | head -20

We posted the results in Slack every Friday. Seeing the percentage climb from 12% → 45% → 78% kept the team motivated.

Phase 4: Tighten the Compiler (Weeks 12-16)

Once we hit 80% TypeScript, we started enabling strict flags one by one:

// Week 12: Enable strictNullChecks
{ "strictNullChecks": true }
// → Found 847 errors. Fixed over 2 weeks.
// → Caught 3 actual null-reference bugs in production code.

// Week 14: Enable noImplicitAny
{ "noImplicitAny": true }
// → Found 312 errors. Most were function parameters.
// → Forced us to type every public API.

// Week 15: Enable strictFunctionTypes
{ "strictFunctionTypes": true }
// → Found 56 errors. Mostly event handler signatures.

// Week 16: Full strict mode
{ "strict": true }
// → 23 remaining errors, all edge cases.

The killer insight: strictNullChecks alone found 3 production bugs we didn't know about. One was a race condition where a user's profile could be null during the first 200ms after signup. We'd been silently swallowing the error for months.

Phase 5: Lock the Door (Week 16+)

Once everything was converted and strict mode was on, we added guardrails to prevent regression:

# .github/workflows/typescript-guard.yml
- name: No new JS files
  run: |
    NEW_JS=$(git diff --name-only origin/main | grep '\.js$' | grep -v '.config.js' | grep -v '.eslintrc.js')
    if [ -n "$NEW_JS" ]; then
      echo "❌ New .js files detected. All new code must be TypeScript."
      echo "$NEW_JS"
      exit 1
    fi

- name: Strict mode check
  run: npx tsc --noEmit --strict

We also added an ESLint rule that banned any:

{
  "@typescript-eslint/no-explicit-any": "error",
  "@typescript-eslint/no-unsafe-assignment": "error",
  "@typescript-eslint/no-unsafe-member-access": "error"
}

The Numbers

After 4 months:

Metric	Before	After	Change
Type-related bugs (per sprint)	4-6	0-1	-85%
Time to onboard new developer	3 weeks	1.5 weeks	-50%
Refactoring confidence (team survey)	3.2/10	8.1/10	+153%
CI pipeline catch rate	~40%	~95%	+137%
Build time	12s	18s	+50%

Yes, the build got slower. We accepted that trade-off without hesitation.

What I'd Do Differently

1. Start with strictNullChecks from day one. We waited until 80% conversion. In retrospect, enabling it early would have caught bugs sooner and forced better typing habits from the start.

2. Use codemods more aggressively. We manually converted most files. Tools like ts-migrate from Airbnb could have automated 60% of the mechanical work.

3. Type the tests. We left test files as .js until the very end. This meant we had type-safe source code tested by untyped tests — the tests themselves had type bugs.

4. Don't allow as casts without a comment. We ended up with 200+ type assertions that hid real issues. Every as should require a // SAFETY: reason comment explaining why the cast is correct.

The Migration Checklist

If you're planning your own migration, here's the condensed checklist:

[ ] Set up tsconfig.json with allowJs: true, strict: false
[ ] Add tsc --noEmit to CI (even if it catches nothing yet)
[ ] Type the boundaries first: API contracts, DB models, shared interfaces
[ ] Convert leaf modules (utils, helpers) first
[ ] One module per PR — never mix migration with features
[ ] Track progress weekly (file count, error count)
[ ] Enable strict flags incrementally: strictNullChecks → noImplicitAny → strict
[ ] Add CI guard against new .js files
[ ] Ban any with ESLint after strict mode is on
[ ] Convert test files last (but do convert them)

Key Takeaways

Incremental migration beats big-bang every time — we shipped features throughout the 4-month process
Type the boundaries first — API responses, DB models, and shared interfaces give every file something to reference
strictNullChecks is the highest-ROI flag — it found 3 production bugs we didn't know about
One module per PR — keep migration PRs boring and reviewable in 5 minutes
Track progress visually — a weekly scorecard keeps the team motivated when progress feels slow

I share daily insights on AI-augmented architecture and TypeScript patterns on Twitter/X. Connect with me on LinkedIn — let's talk about your migration.

Originally published on my Hashnode blog. Follow me for more AI + Architecture content.

5 Things I Put in Every CLAUDE.md That Make AI Actually Useful

Alex Rogov — Sat, 21 Mar 2026 09:15:38 +0000

Most developers treat CLAUDE.md like a prompt — a paragraph of instructions they paste once and forget. That's why most developers get mediocre results from AI coding assistants.

I've been using Claude Code with CLAUDE.md files across 10+ production projects over the past year. After hundreds of iterations, I've narrowed it down to 5 things that consistently make the difference between "AI that generates random code" and "AI that understands my project."

Here's what I put in every single CLAUDE.md — and why.

1. Project Identity: What This Is (and What It's Not)

The first thing Claude Code reads is your CLAUDE.md. If it doesn't immediately understand what it's working on, every subsequent output will be slightly off.

Bad:

# My Project
This is a web app.

Good:

# Fintrack — Personal Finance Dashboard

## What is this
SaaS application for tracking personal finances.
Built as a monorepo with a Next.js frontend and NestJS API.

## Stack
- Frontend: Next.js 15, React 19, TypeScript 5.7, Tailwind CSS
- Backend: NestJS 11, PostgreSQL 16, Prisma ORM
- Infrastructure: Docker, AWS ECS, GitHub Actions CI/CD

## What this is NOT
- Not a mobile app (we have a separate React Native repo)
- Not a library — this is a product with users

The "What this is NOT" section is surprisingly powerful. It prevents the AI from suggesting React Native patterns in your web app, or treating your product code like a library that needs to be published to npm.

Why it works: Claude uses this context for every decision — file naming, import paths, error handling patterns, even how it writes commit messages. The more specific you are, the more targeted every output becomes.

2. Architecture Rules: The Dependency Map

This is the single highest-ROI section. Without it, Claude will create files anywhere, import anything from anywhere, and violate your architecture in ways that compile but slowly destroy your codebase.

## Architecture

### Layer Structure (Clean Architecture)

src/
├── domain/ # Entities, value objects, domain errors
│ └── NO imports from infrastructure or application
├── application/ # Use cases, ports (interfaces)
│ └── Can import from domain only
├── infrastructure/ # Repositories, external APIs, DB
│ └── Can import from domain and application
└── presentation/ # Controllers, resolvers, DTOs
└── Can import from application only


### Rules
- NEVER import from infrastructure in domain or application layers
- Every use case must go through a port (interface), never call infrastructure directly
- DTOs live in presentation layer, entities live in domain
- Database models (Prisma) are infrastructure — never leak them into domain

I can't stress this enough: AI coding assistants will cheerfully violate your architecture if you don't tell them not to. They optimize for "works now," not "maintainable in 6 months."

The dependency rules act as guardrails. When Claude Code generates a new service, it knows exactly where to put it, what it can import, and what patterns to follow.

Real example: Before I added this section, Claude kept importing Prisma models directly into my use cases. After — it automatically creates proper repository interfaces in the application layer and implements them in infrastructure. Zero prompting needed.

3. Code Style Contracts: Be Specific or Be Sorry

"Follow best practices" means nothing to an AI. It will default to whatever pattern appeared most in its training data — which might be a 2019 Express.js tutorial.

Instead, I write explicit contracts:

## Code Style

### TypeScript
- Strict mode always (`strict: true` in tsconfig)
- No `any` — use `unknown` with type guards
- Prefer `interface` over `type` for object shapes
- Use discriminated unions for state management
- Exhaustive switch with `never` for union types

### Error Handling
- Domain errors are custom classes extending `DomainError`
- Never throw generic `Error` — always use typed errors
- Use `Result<T, E>` pattern for operations that can fail
- HTTP errors are mapped in presentation layer, never in use cases

### Naming
- Files: kebab-case (`user-repository.ts`)
- Classes: PascalCase (`UserRepository`)
- Functions/methods: camelCase (`findById`)
- Use cases: verb-noun (`CreateUser`, `GetTransactions`)
- No abbreviations in public APIs (`transaction`, not `tx`)

### Testing
- Test files: `*.spec.ts` next to source files
- Use `describe/it` blocks, not `test`
- Mock external dependencies only (DB, APIs)
- Don't mock what you own — test through public interfaces

The naming section alone saves me hours of refactoring. Without it, Claude alternates between userRepo, UserRepository, user_repository, and userDataAccess — sometimes within the same PR.

Pro tip: Add examples of what NOT to do. AI models learn boundaries faster from negative examples:

### Anti-patterns (NEVER do this)
- ❌ `const data: any = await fetch(...)`
- ✅ `const data: unknown = await response.json()`
- ❌ `try { ... } catch (e) { console.log(e) }`
- ✅ `try { ... } catch (e) { throw new InfrastructureError('Failed to fetch user', { cause: e }) }`

4. Verification Commands: Trust but Verify

This is the one most people skip — and it's the one that prevents broken PRs.

## Verification

Before completing any task, run:
1. `npm run typecheck` — must pass with zero errors
2. `npm run lint` — must pass (we use strict ESLint config)
3. `npm run test` — all tests must pass
4. `npm run build` — must compile successfully

### After creating new files
- Run `npm run typecheck` to verify imports are correct
- Ensure new files follow the naming convention
- Add exports to the nearest barrel file (index.ts)

### After modifying API endpoints
- Update the OpenAPI schema: `npm run generate:schema`
- Regenerate client types: `npm run generate:client`

When Claude Code reads this, it actually runs these commands before telling you "done." Without this section, you get code that looks right but fails on the first CI run.

I've measured the impact: adding verification commands reduced my "fix CI after AI changes" time by ~70%. The AI catches its own mistakes before I even review the code.

Why this beats "just run tests": Being specific about which commands to run and when gives the AI a decision tree. It doesn't have to guess whether this change needs a type check, a build, or a schema regeneration — you've already told it.

5. Current Context: The Living Section

This is the section that evolves. While the first four sections are relatively stable, this one changes weekly:

## Current Context

### Active Sprint
- Implementing multi-currency support for transactions
- Related files: `src/domain/transaction/`, `src/application/use-cases/transactions/`
- Key constraint: amounts stored in cents (integer), never floats

### Recent Decisions
- 2026-03-01: Switched from REST to GraphQL for mobile API (REST stays for webhooks)
- 2026-02-15: Adopted Result pattern instead of throwing in use cases
- 2026-02-01: Migrated from Jest to Vitest (faster, native ESM)

### Known Issues
- `UserService.findByEmail` has N+1 query — fix after current sprint
- Rate limiter on `/api/auth` is too aggressive (100 req/min → change to 300)

### Do Not Touch
- `src/infrastructure/legacy/` — migrating gradually, don't refactor
- `docker-compose.prod.yml` — managed by DevOps team

This section is gold for two reasons:

It prevents the AI from "fixing" things you know about. Without the "Known Issues" section, Claude will happily refactor that N+1 query when you asked it to add a simple field.
"Do Not Touch" saves you from disaster. I learned this the hard way when Claude "helpfully" refactored a legacy payment integration that was working fine but looked ugly. Three hours of rollback.

The CLAUDE.md Mental Model

Here's the key insight: CLAUDE.md is not a prompt. It's an architecture contract.

A prompt is something you write once to get a response. A contract is a living document that defines the rules of engagement between you and your AI collaborator.

Think of it like an onboarding document for a new senior developer joining your team. You wouldn't just say "write good code." You'd explain the project, the architecture, the conventions, the current sprint, and the things that are off-limits.

That's exactly what CLAUDE.md does — except the new team member reads it every single time and never forgets.

Getting Started

If you don't have a CLAUDE.md yet, start with this minimal template:

# [Project Name]

## What is this
[One paragraph describing the project, stack, and purpose]

## Architecture
[Folder structure + dependency rules]

## Code Style
[5-10 most important conventions]

## Verification
[Commands to run before completing any task]

## Current Context
[What you're working on right now]

You can always add more later. The point is to start with something specific and iterate. Every time the AI does something wrong, ask yourself: "Could I have prevented this with a CLAUDE.md rule?" If yes, add it.

After a month, you'll have a CLAUDE.md that makes your AI assistant genuinely useful — not just fast, but accurate, consistent, and aligned with how you actually build software.

Key Takeaways

Project Identity prevents the AI from guessing what your project is — be explicit about what it is AND what it isn't
Architecture Rules are the highest-ROI section — without them, the AI will violate your dependency boundaries
Code Style Contracts must be specific, not generic — include negative examples
Verification Commands reduce CI failures by ~70% — tell the AI what to check and when
Current Context is the living section — update it weekly to keep the AI aligned with your sprint

Building a production app with Claude Code? I share daily tips on AI-augmented architecture on Twitter/X. Let's connect on LinkedIn if you're working in the same space.

Originally published on my Hashnode blog. Follow me for more AI + Architecture content.