I saw a post on X where someone asked an AI coding assistant to fix a terminal issue.

Instead, it rewrote their entire [.zshrc](https://github.com/ohmyzsh/ohmyzsh) with two lines.

Years of shell tweaks. Gone.

The takeaway isn’t “don’t use AI.”

The takeaway is: **don’t keep your entire shell brain in one fragile file**.

This post shows a simple way to make your Zsh setup more resilient: split `.zshrc` into small modules, then load them safely.

![2 Step Defense in Depth for Dotfiles: Modularizing Your .zshrc](/content/uploads/2026/02/Cursor_and_-zsh.png)

## The fix: modular configs

Instead of one big `.zshrc`, create a folder of focused config files.

### 1) Create a config directory

```bash
mkdir -p ~/.zsh.d
```

### 2) Split your config into modules

Here’s an example module list (based on a real‑world setup):

```
~/.zsh.d/
  00-exports.zsh
  05-paths.zsh
  10-functions.zsh
  20-nvm.zsh
  30-aliases.zsh
  40-aliases-proj1.zsh
  41-aliases-proj2.zsh
  42-aliases-proj3.zsh
  43-aliases-proj4.zsh
  90-keys.zsh
  99-prompt.zsh
```

Each file has one job. Small file, small blast radius.

## Important detail: load order matters

When you load files via `~/.zsh.d/*.zsh`, Zsh loads them **alphabetically**.

That’s why the numeric prefixes (e.g., `00-`, `10-`, `99-`) are not cosmetic.

They enforce a predictable order:

- **Exports first** (env vars)  
- **Paths early** (`PATH`, `MANPATH`, etc.)  
- **Functions before aliases** (aliases can call functions)  
- **Toolchains before project aliases** (so commands exist)  
- **Prompt last** (so it can reference everything loaded above)  

If you don’t control order, you’ll get “works on some terminals, breaks on others” behavior.

## A practical starting template

If you already have something like this in your `.zshrc`:

```zsh
source ~/.zsh.d/exports.zsh
source ~/.zsh.d/paths.zsh
source ~/.zsh.d/functions.zsh
source ~/.zsh.d/nvm.zsh
source ~/.zsh.d/aliases.zsh
source ~/.zsh.d/aliases-proj1.zsh
source ~/.zsh.d/aliases-proj2.zsh
source ~/.zsh.d/aliases-proj3.zsh
source ~/.zsh.d/aliases-proj4.zsh
source ~/.zsh.d/keys.zsh
source ~/.zsh.d/prompt.zsh
```

You can replace that entire block with the safe loader loop, then rename files with numeric prefixes to keep the order stable.

## Final note

AI tools are powerful. That’s the point.

So treat your dotfiles like production config:

- small modules  
- clear order  
- predictable behavior  
- minimal blast radius  

Your future self will thank you the next time a “quick fix” tries to become a hard reset.

**END_OF_REPORT** 🌿✨